Jobs¶

While the rest of the LCM API simply defines what the cluster should be, jobs are what actually make it so. Jobs can generally be run at either the cluster, datacenter, or node level.

Job Type	URL
Install	`POST /api/v1/lcm/actions/install`
Configure	`POST /api/v1/lcm/actions/configure`
Restart	`POST /api/v1/lcm/actions/restart`
Terminate	`POST /api/v1/lcm/actions/terminate`

To get a listing of job types and what options they support, you can go to the following API route:

GET /api/v1/lcm/actions/¶

All job creation is asynchronous and should return a response immediately with the created Job object. This only means that the job has been queued. The job may or may not start immediately depending on whether LCM is already running a job.

Job¶

{
    "node-id": null,
    "description": null,
    "datacenter-name": null,
    "datacenter-id": null,
    "cluster-name": "c1",
    "job-data": {
        "change-default-cassandra-password": "blarg",
        "continue-on-error": false,
        "job-type": "install",
        "auto-bootstrap": null
    },
    "job-type": "install",
    "node-name": null,
    "id": "dad24ef7-fa09-49d8-9070-0406c7a6c585",
    "cluster-id": "7064583a-0656-4914-819e-937863793ab5",
    "status": "PENDING",
    "dry-run": false
}

Property	Description of Values
id	A UUID for the Job.
job-type	The job type (`install`, `configure`, etc.)
status	The current Job Status.
cluster-id	A reference to the cluster for this job.
cluster-name	The name of the cluster (at the time the job was created).
datacenter-id	The datacenter of the job (only set if the job was run at the datacenter or node level).
datacenter-name	The name of the datacenter (at the time the job was created).
node-id	The node for the job (only set if the job was run for a specific node).
node-name	The name of the node (at the time the job was created).
description	A verbal description of the job. Optional.
dry-run	Not currently used.

GET /api/v1/lcm/jobs/{id}¶

Gets a Job by job ID.

Path arguments:	id – A Job ID.

Returns a Job object.

Example:

curl http://localhost:8888/api/v1/lcm/jobs/27138a41-59b6-487b-892a-3a211201fb51

Output:

{
    "node-id": null,
    "created-on": "2016-06-21T17:21:30.357Z",
    "description": null,
    "datacenter-name": null,
    "type": "job",
    "datacenter-id": null,
    "cluster-name": "c1",
    "job-data": {
        "change-default-cassandra-password": "sfdgs",
        "job-type": "install",
        "auto-bootstrap": null
    },
    "related-resources": {
        "job-events": "http://localhost:8888/api/v1/lcm/jobs/27138a41-59b6-487b-892a-3a211201fb51/job_events/",
        "cluster": "http://localhost:8888/api/v1/lcm/clusters/7064583a-0656-4914-819e-937863793ab5",
        "job-nodes": "http://localhost:8888/api/v1/lcm/jobs/27138a41-59b6-487b-892a-3a211201fb51/job_nodes/"
    },
    "modified-by": "system",
    "job-type": "install",
    "node-name": null,
    "modified-on": "2016-06-21T17:21:32.596Z",
    "id": "27138a41-59b6-487b-892a-3a211201fb51",
    "href": "http://localhost:8888/api/v1/lcm/jobs/27138a41-59b6-487b-892a-3a211201fb51",
    "created-by": "system",
    "cluster-id": "7064583a-0656-4914-819e-937863793ab5",
    "status": "FAILED",
    "dry-run": false
}

GET /api/v1/lcm/jobs/¶

Gets a paginated list of all Job records. See Paginated Results for an overview of the query string parameters that can be used.

Example:

curl http://localhost:8888/api/v1/lcm/jobs/

Output:

{
    "next": null,
    "previous": null,
    "last": 1,
    "count": 1,
    "per-page": 50,
    "current": 1,
    "results": [
        {
            "node-id": null,
            "created-on": "2016-06-21T20:24:21.432Z",
            "description": null,
            "datacenter-name": null,
            "type": "job",
            "datacenter-id": null,
            "cluster-name": "cluster01",
            "related-resources": {
                "job-events": "http://localhost:8888/api/v1/lcm/jobs/53db1340-8037-47fe-817a-951b9324b04a/job_events/",
                "cluster": "http://localhost:8888/api/v1/lcm/clusters/39efe91a-86bf-44a9-a5b8-fed6d37b8e21",
                "job-nodes": "http://localhost:8888/api/v1/lcm/jobs/53db1340-8037-47fe-817a-951b9324b04a/job_nodes/"
            },
            "job-type": "install",
            "node-name": null,
            "modified-on": "2016-06-21T20:25:08.787Z",
            "id": "53db1340-8037-47fe-817a-951b9324b04a",
            "href": "http://localhost:8888/api/v1/lcm/jobs/53db1340-8037-47fe-817a-951b9324b04a",
            "cluster-id": "39efe91a-86bf-44a9-a5b8-fed6d37b8e21",
            "status": "FAILED",
            "dry-run": false
        }
    ]
}

Job Node¶

Job Node objects represent the status of the job on a specific node.

{
    "job-id": "53db1340-8037-47fe-817a-951b9324b04a",
    "node-id": "3bfa4fdf-a861-4ac2-aff1-4730f90af28c",
    "datacenter-name": "datacenter01",
    "node-name": "10.0.3.132",
    "id": "8a7f8efc-fe35-4541-a570-4d235fcf1438",
    "status": "FAILED"
}
Property Description of Values

id A UUID for the Job Node object.

job-id The UUID of the job.

node-id The UUID of the node.

node-name The name of the node (at the time of job creation).

datacenter-name The name of datacenter (at the time of job creation).

status The job status for this node.

GET /api/v1/lcm/job_nodes/{id}¶

Gets a specific job node record by ID.

arg id:	A Job Node ID.

Returns a Job Node object.

Example:

curl http://localhost:8888/api/v1/lcm/job_nodes/8a7f8efc-fe35-4541-a570-4d235fcf1438

Output:

{
    "job-id": "53db1340-8037-47fe-817a-951b9324b04a",
    "node-id": "3bfa4fdf-a861-4ac2-aff1-4730f90af28c",
    "created-on": "2016-06-21T20:24:26.419Z",
    "datacenter-name": "datacenter01",
    "type": "job-node",
    "related-resources": {
        "job-events": "http://localhost:8888/api/v1/lcm/job_nodes/8a7f8efc-fe35-4541-a570-4d235fcf1438/job_events/",
        "node": "http://localhost:8888/api/v1/lcm/nodes/3bfa4fdf-a861-4ac2-aff1-4730f90af28c",
        "job": "http://localhost:8888/api/v1/lcm/jobs/53db1340-8037-47fe-817a-951b9324b04a"
    },
    "modified-by": "system",
    "node-name": "10.0.3.132",
    "modified-on": "2016-06-21T20:25:08.738Z",
    "id": "8a7f8efc-fe35-4541-a570-4d235fcf1438",
    "href": "http://localhost:8888/api/v1/lcm/job_nodes/8a7f8efc-fe35-4541-a570-4d235fcf1438",
    "created-by": "system",
    "status": "FAILED"
}

GET /api/v1/lcm/job_nodes/¶

Gets a paginated list of all Job Node records. See Paginated Results for an overview of the query string parameters that can be used.

Example:

curl http://localhost:8888/api/v1/lcm/job_nodes/

Output:

{
    "next": null,
    "previous": null,
    "last": 1,
    "count": 1,
    "per-page": 50,
    "current": 1,
    "results": [
        {
            "job-id": "53db1340-8037-47fe-817a-951b9324b04a",
            "node-id": "3bfa4fdf-a861-4ac2-aff1-4730f90af28c",
            "created-on": "2016-06-21T20:24:26.419Z",
            "datacenter-name": "datacenter01",
            "type": "job-node",
            "related-resources": {
                "job-events": "http://localhost:8888/api/v1/lcm/job_nodes/8a7f8efc-fe35-4541-a570-4d235fcf1438/job_events/",
                "node": "http://localhost:8888/api/v1/lcm/nodes/3bfa4fdf-a861-4ac2-aff1-4730f90af28c",
                "job": "http://localhost:8888/api/v1/lcm/jobs/53db1340-8037-47fe-817a-951b9324b04a"
            },
            "node-name": "10.0.3.132",
            "modified-on": "2016-06-21T20:25:08.738Z",
            "id": "8a7f8efc-fe35-4541-a570-4d235fcf1438",
            "href": "http://localhost:8888/api/v1/lcm/job_nodes/8a7f8efc-fe35-4541-a570-4d235fcf1438",
            "status": "FAILED"
        }
    ]
}

Job Status¶

The status field of Job objects can be one of the following values:

Status Description

PENDING The job has been queued for execution, but is not yet running.

RUNNING The job is currently running.

FAILED The job has failed.

WILL_FAIL The job is still running, but we know that it will ultimately fail.

COMPLETE The job finished successfully.

IDLE The job is running, but hasn’t reported any activity within a configurable timeout. The job may be hung or may simply be running slowly. In the latter case, it will eventually flip back to RUNNING.

TERMINATED The job was terminated by request.

ORPHANED If the OpsCenter server is restarted while a job is RUNNING, the job will be given this status on startup.

Job Event¶

Each node will report status and other useful information to LCM as the job executes on the remote host. All the non-status information is captured in a Job Event object. These are used to track changes, milestones, and errors on the node. They are very useful for troubleshooting.

{
    "id": <value>,
    "job-id": <value>,
    "node-id": <value>,
    "event-type": <value>,
    "event-subtype": <value>,
    "before": {"<key>": <value>},
    "changes": <value>,
    "message": <value>,
    "event-resource": <value>,
    "after": {"key": <value>},
    "traceback": <value>
}
Property Description of Values

id A UUID for the Job Event.

job-id The UUID of the Job.

node-id The UUID of the Node.

event-type The main type of the event (ie, “milestone”, “error”, etc.)

event-subtype The subtype of the event (“MeldError”, “file-contents”, etc.)

event-resource The resource related to the event. Often this is a file path, but could be other things and is sometimes null.

message A description of the event.

changes A boolean indicating whether a change was made on the remote machine. This is often used to indicate whether a config file was overwritten.

before An object sometimes used to indicate some node state before the event happened.

after An object sometimes used to indicate some node state after the event happened.

traceback Contains a program stacktrace, if there is one. This is only present when event-type is “error”.

GET /api/v1/lcm/job_events/{id}¶

Gets a specific job event record by ID.

Path arguments:	id – A Job Event ID.

Returns a Job Event object.

Example:

curl http://localhost:8888/api/v1/lcm/job_events/65c12a12-1e71-40db-aad6-2d1bedeb0f98

Output:

{
    "job-id": "53db1340-8037-47fe-817a-951b9324b04a",
    "node-id": "3bfa4fdf-a861-4ac2-aff1-4730f90af28c",
    "event-subtype": "file-contents",
    "before": { },
    "created-on": "2016-06-21T20:24:28.552Z",
    "event-type": "check",
    "changes": false,
    "type": "job-event",
    "message": "Checking if the contents of /etc/apt/sources.list.d/opsc.list need to be updated",
    "related-resources": {
        "job-node": "http://localhost:8888/api/v1/lcm/job_nodes/8a7f8efc-fe35-4541-a570-4d235fcf1438",
        "node": "http://localhost:8888/api/v1/lcm/nodes/3bfa4fdf-a861-4ac2-aff1-4730f90af28c",
        "job": "http://localhost:8888/api/v1/lcm/jobs/53db1340-8037-47fe-817a-951b9324b04a"
    },
    "event-resource": "/etc/apt/sources.list.d/opsc.list",
    "href": "http://localhost:8888/api/v1/lcm/job_events/65c12a12-1e71-40db-aad6-2d1bedeb0f98",
    "after": { },
    "id": "65c12a12-1e71-40db-aad6-2d1bedeb0f98",
    "traceback": null,
    "created-by": "system"
}

GET /api/v1/lcm/job_events/¶

Gets a paginated list of all Job Event records. See Paginated Results for an overview of the query string parameters that can be used.

Example:

curl http://localhost:8888/api/v1/lcm/job_events/

Output:

{
    "next": null,
    "previous": null,
    "last": 1,
    "count": 29,
    "per-page": 50,
    "current": 1,
    "results": [
        {
            "job-id": "dad24ef7-fa09-49d8-9070-0406c7a6c585",
            "node-id": null,
            "event-subtype": "start",
            "created-on": "2016-06-21T16:20:01.848Z",
            "event-type": "milestone",
            "type": "job-event",
            "message": "job started...",
            "related-resources": {
                "job": "http://localhost:8888/api/v1/lcm/jobs/dad24ef7-fa09-49d8-9070-0406c7a6c585"
            },
            "href": "http://localhost:8888/api/v1/lcm/job_events/15890710-a1bb-42c6-8d49-738ee9c3f844",
            "id": "15890710-a1bb-42c6-8d49-738ee9c3f844"
        }
    ]
}

Install¶

Installs and configures DSE on a set of nodes. Initially this only makes sense at the cluster level, but can be used on an existing cluster to add nodes (re-balancing will be necessary afterward). It is safe to re-run install on a node.

POST /api/v1/lcm/actions/install¶

This request will return immediately while the install job runs asynchronously. For more information on all the parameters available and a description of each, make a GET request to /api/v1/lcm/actions/install

Example:

Input:

{
    "job-type":"install",
    "job-scope":"cluster",
    "resource-id":"7064583a-0656-4914-819e-937863793ab5",
    "auto-bootstrap":null,
    "continue-on-error":false,
    "change-default-cassandra-password":"blarg"
}

curl -X POST -d '<example input>' http://localhost:8888/api/v1/lcm/actions/install

Output:

{
    "node-id": null,
    "created-on": "2016-06-21T16:20:00.955Z",
    "description": null,
    "datacenter-name": null,
    "type": "job", "datacenter-id": null,
    "cluster-name": "c1",
    "job-data": {
        "change-default-cassandra-password": "blarg",
        "continue-on-error": false,
        "job-type": "install",
        "auto-bootstrap": null
    },
    "modified-by": "system",
    "job-type": "install",
    "node-name": null,
    "modified-on": "2016-06-21T16:20:00.955Z",
    "id": "dad24ef7-fa09-49d8-9070-0406c7a6c585",
    "created-by": "system",
    "cluster-id": "7064583a-0656-4914-819e-937863793ab5",
    "status": "PENDING",
    "dry-run": false
}

Configure¶

The only difference between install and configure is that configure jobs do not attempt to install packages, set the CQL password in DataStax Enterprise, or register the cluster with OpsCenter. It pushes the current configs to the managed nodes and restarts them.

For more information on all the parameters available and a description of each, make a GET request to /api/v1/lcm/actions/configure

POST /api/v1/lcm/actions/configure¶

Example:

Input:

{
    "job-type":"configure",
    "job-scope":"cluster",
    "resource-id":"7064583a-0656-4914-819e-937863793ab5",
    "change-default-cassandra-password":"foobie"
}

curl -X POST -d '<example input>' http://localhost:8888/api/v1/lcm/actions/configure

The output is similar to POST /api/v1/lcm/actions/install.

Restart¶

Does a rolling restart of the nodes specified.

For more information on all the parameters available and a description of each, make a GET request to /api/v1/lcm/actions/restart

POST /api/v1/lcm/actions/restart¶

Example:

Input:

{
    "job-type":"restart",
    "job-scope":"cluster",
    "resource-id":"7064583a-0656-4914-819e-937863793ab5"
}

curl -X POST -d '<example input>' http://localhost:8888/api/v1/lcm/actions/restart

The output is similar to POST /api/v1/lcm/actions/install.

Terminate¶

Technically not a job, this action is for killing jobs that are pending or running.

For more information on all the parameters available and a description of each, make a GET request to /api/v1/lcm/actions/terminate

POST /api/v1/lcm/actions/terminate¶

Example:

curl -X POST -d '{"job-id":"27138a41-59b6-487b-892a-3a211201fb51"}' http://localhost:8888/api/v1/lcm/actions/terminate

Output:

"Termination in progress"

Table Of Contents

Previous topic

Next topic

This Page

Jobs¶

Job Status¶

Install¶

Configure¶

Restart¶

Terminate¶

Property	Description of Values
id	A UUID for the Job Node object.
job-id	The UUID of the job.
node-id	The UUID of the node.
node-name	The name of the node (at the time of job creation).
datacenter-name	The name of datacenter (at the time of job creation).
status	The job status for this node.

Status	Description
PENDING	The job has been queued for execution, but is not yet running.
RUNNING	The job is currently running.
FAILED	The job has failed.
WILL_FAIL	The job is still running, but we know that it will ultimately fail.
COMPLETE	The job finished successfully.
IDLE	The job is running, but hasn’t reported any activity within a configurable timeout. The job may be hung or may simply be running slowly. In the latter case, it will eventually flip back to RUNNING.
TERMINATED	The job was terminated by request.
ORPHANED	If the OpsCenter server is restarted while a job is RUNNING, the job will be given this status on startup.

Property	Description of Values
id	A UUID for the Job Event.
job-id	The UUID of the Job.
node-id	The UUID of the Node.
event-type	The main type of the event (ie, “milestone”, “error”, etc.)
event-subtype	The subtype of the event (“MeldError”, “file-contents”, etc.)
event-resource	The resource related to the event. Often this is a file path, but could be other things and is sometimes null.
message	A description of the event.
changes	A boolean indicating whether a change was made on the remote machine. This is often used to indicate whether a config file was overwritten.
before	An object sometimes used to indicate some node state before the event happened.
after	An object sometimes used to indicate some node state after the event happened.
traceback	Contains a program stacktrace, if there is one. This is only present when event-type is “error”.