Create a service check job

POST api/jobs/service_check

Starts a service check job. A service check job executes the following Docker requests to one or more nodes.

In order to perform this action, the following conditions must be met:

• Must have the Docker Service Check feature turned on at the site level.
• The user must have the following capabilities:
  • Create and Update a ServiceCheck job

Request syntax

The target for a service check job can be specified using a list of node hostnames, a node group name, a node group ID, a saved filter name, or a saved filter ID. Only one target parameter can be used per request.

Target nodes using a list of hostnames.

post api/jobs/service_check '{"hostnames":["<node_hostname>"]}'

Target nodes using a node group name.

post api/jobs/service_check '{"node_group_name":"<node_group_name>"}'

Target nodes using a node group ID.

post api/jobs/service_check '{"node_group_id":<node_group_id>}'

Target nodes using a saved filter name.

post api/jobs/service_check '{"saved_filter_name":"<saved_filter_name>"}'

Target nodes using a saved filter ID.

post api/jobs/service_check '{"saved_filter_id":<saved_filter_id>}'

Request parameters

The request accepts the following data in JSON format.

Response syntax

When the hostnames request parameter is used, the following response syntax is received.

{
    "id": integer,
    "type": "Service Check",
    "status": "string",
    "message": "string",
    "trigged_by": "string",
    "parameters": {
        "hostnames": [
            "string",
            "string"
        ]
    },
    "time_started": "timestamp"
}

When the node group or saved filter request parameters are used, the following response syntax is received.

{
    "id": integer,
    "type": "Service Check",
    "status": "string",
    "message": "string",
    "trigged_by": "string",
    "parameters": {
        "node_group_name": "string",
        "node_group_id": integer,
        "saved_filter_name": "string",
        "saved_filter_id": integer
    },
    "time_started": "timestamp"
}

Response parameters

If the action is successful, an HTTP 200 response is returned. The following data is returned in JSON format.

The following data is returned if you include the payload.

Errors

The following are common errors returned by this API. For a list of additional common errors, see Common errors.

Examples

Example 1: Start a service check job using a list of hostnames.

This example starts a service check job for nodes with hostnames sit0016red0 and sit0016red1.

ruby api.rb <customer_code> post api/jobs/service_check '{"hostnames":["sit0016red0","sit0016red1"]}'

Response

{
    "id": 1541246,
    "type": "Service Check",
    "status": "pending",
    "message": null,
    "trigged_by": "test.user",
    "parameters": {
        "hostnames": [
            "sit0016red0",
            "sit0016red1"
        ]
    },
    "time_started": "2024-09-03T18:47:57Z"
}

Example 2: Start a service check job using a node group name.

This example starts a service check job for all nodes in the node group Test Node Group.

ruby api.rb <customer_code> post api/jobs/service_check '{"node_group_name":"Test Node Group"}'

Response

{
    "id": 1541258,
    "type": "Service Check",
    "status": "pending",
    "message": null,
    "trigged_by": "test.user",
    "parameters": {
        "node_group_name": "Test Node Group"
    },
    "time_started": "2024-09-03T19:05:12Z"
}

Example 3: Start a service check job using a node group ID.

This example starts a service check job for all nodes in node group ID 42.

ruby api.rb <customer_code> post api/jobs/service_check '{"node_group_id":42}'

Response

{
    "id": 1541251,
    "type": "Service Check",
    "status": "pending",
    "message": null,
    "trigged_by": "test.user",
    "parameters": {
        "node_group_id": 42
    },
    "time_started": "2024-09-03T19:16:04Z"
}

Example 4: Start a service check job using a saved filter name.

This example starts a service check job for nodes included in the saved filter named Test nodes. The filter name is case sensitive.

ruby api.rb <customer_code> post api/jobs/service_check '{"saved_filter_name":"Test nodes"}'

Response

{
    "id": 1541275,
    "type": "Service Check",
    "status": "pending",
    "message": null,
    "trigged_by": "test.user",
    "parameters": {
        "saved_filter_name": "Test nodes"
    },
    "time_started": "2024-09-03T19:22:38Z"
}

Example 5: Start a service check job using a saved filter ID.

This example starts a service check job for all nodes that match saved filter ID 17.

ruby api.rb <customer_code> post api/jobs/service_check '{"saved_filter_id":17}'

Response

{
    "id": 1541285,
    "type": "Service Check",
    "status": "pending",
    "message": null,
    "trigged_by": "test.user",
    "parameters": {
        "saved_filter_id": 17
    },
    "time_started": "2024-09-03T19:28:15Z"
}

Retrieve the payload from a service check job.

This example retrieves the payload from service check job with ID 1541246.

ruby api.rb <customer_code> get api/jobs/1541246\?include_payload=true

Response

{
    "id": 1541246,
    "type": "Service Check",
    "status": "finished",
    "message": null,
    "payload": {
        "success_nodes": {
            "sit0016red0": [
                {
                    "error": "",
                    "output": [],
                    "exitcode": 0
                },
                {
                    "error": "",
                    "output": [
                        {
                            "ID": "e376bb7e6bde",
                            "Tag": "latest",
                            "Size": "148MB",
                            "Digest": "<none>",
                            "CreatedAt": "2024-07-17 19:31:14 -0400 EDT",
                            "Containers": "N/A",
                            "Repository": "httpd",
                            "SharedSize": "N/A",
                            "UniqueSize": "N/A",
                            "VirtualSize": "148.2MB",
                            "CreatedSince": "7 weeks ago"
                        }
                    ],
                    "exitcode": 0
                }
            ]
        }
    },
    "trigged_by": "test.user",
    "success_nodes_count": 1,
    "failed_nodes_count": 0,
    "total_nodes_count": 1,
    "parameters": {
        "hostnames": [
            "sit0016red0"
        ]
    },
    "time_started": "2024-09-05T02:37:13Z",
    "time_finished": "2024-09-05T02:37:15Z"
}