Create a Reliant Virtual Controller (RVC) job

POST api/jobs/rvc

Starts a SC//Reliant™ Virtual Controller (RVC) job. The response will indicate that the RVC job is created and is scheduled to run. You can use the job ID from the response to retrieve the job status.

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

Must have the Remote Job Execution feature turned on at the site level.
The user must have the following capabilities:
- Create and Update a RVC job
- Create a node

Request syntax

post api/jobs/rvc '{target_details}'

Request parameters

The request accepts the following data in JSON format.

Parameter	Type	Description	Required
`hostnames`	String array	The list of nodes on which to run the RVC job.	Dependent. Only if no node group or saved filter is provided.
`node_group_name`	String	The name of the node group on which to run the RVC job. The RVC job will run on all nodes that are members of the node group.	Dependent. Only if no hostnames or saved filter is provided.
`node_group_id`	Integer	The ID of the node group on which to run the RVC job. The RVC job will run on all nodes that are members of the node group.	Dependent. Only if no hostnames or saved filter is provided.
`saved_filter_name`	String	The name of the saved filter on which to run the RVC job. The RVC job will run on all nodes that match the saved filter.	Dependent. Only if no hostnames or node group is provided.
`saved_filter_id`	Integer	The ID of the saved filter on which to run the RVC job. The RVC job will run on all nodes that match the saved filter.	Dependent. Only if no hostnames or node group is provided.
`action`	String	The RVC action to start. Available options are: `status`, `enable-maintenance-mode`, and `disable-maintenance-mode`.	Yes
`target_type`	String	The target type. Available options are: `cluster`.	Yes

Response syntax

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

{
    "id": integer,
    "type": "RVC",
    "status": "string",
    "message": "string",
    "trigged_by": "string",
    "parameters": {
        "action": "string",
        "target_type":"cluster",
        "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": "RVC",
    "status": "string",
    "message": "string",
    "trigged_by": "string",
    "parameters": {
        "action": "string",
        "target_type":"cluster",
        "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.

Field	Type	Description
`id`	Integer	The ID of the RVC job.
`type`	String	The type of job. For service checks, it is `Service Check`.
`status`	String	The status of the job.
`message`	String	This field is reserved for internal use.
`trigged_by`	String	The username of the person who initiated the job.
`parameters`	String	The request parameters indicating the hostnames, node groups, or saved filters the RVC job ran on.
`time_started`	Timestamp	The timestamp indicating when the job started. The timestamp is given in ISO 8601 UTC datetime format.

Errors

For a list of potential errors, refer to the common errors, as this action does not have any unique error responses. For more information, see Common errors.

Examples

Example 1: Start an RVC job using a list of hostnames.

This example starts an RVC job requesting status for nodes with hostnames sit0016red0 and sit0016red1.

ruby api.rb <customer_code> post api/jobs/rvc '{"action":"status","target_type":"cluster","hostnames":["sit0016red0", "sit0016red1"]}'

Response

{
    "id": 1541739,
    "type": "RVC",
    "status": "pending",
    "message": null,
    "trigged_by": "test.user",
    "parameters": {
        "action": "status",
        "target_type": "cluster",
        "hostnames": [
            "sit0016red0",
            "sit0016red1"
        ]
    },
    "time_started": "2024-09-04T23:51:09Z"
}

Example 2: Start an RVC job using a node group name.

This example starts an RVC job enabling maintenance mode for the nodes in node group Test Node Group.

ruby api.rb <customer_code> post api/jobs/rvc '{"target_type":"cluster","action":"enable-maintenance-mode","node_group_name":"Test Node Group"}'

Response

{
    "id": 1541251,
    "type": "RVC",
    "status": "pending",
    "message": null,
    "trigged_by": "test.user",
    "parameters": {
        "action": "enable-maintenance-mode",
        "target_type":"cluster",
        "node_group_name": "Test Node Group"
    },
    "payload": null,
    "time_started": "2024-09-03T19:16:04Z"
}

Example 3: Retrieving the payload from an RVC job.

This example retrieves the payload from RVC job ID 000.

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

Response

{
    "id": 1541739,
    "type": "RVC",
    "status": "finished",
    "message": null,
    "payload": {
        "success_nodes": {
            "sit0016red0": {
                "response": {
                    "standby": false,
                    "unclean": false,
                    "hostname": "sit0016red0",
                    "ha_cluster": true,
                    "active_node": false,
                    "maintenance": false,
                    "last_checked": "Wed Sep 04  7:51:11 PM 2024 EDT"
                },
                "exit_code": 0
            },
            "sit0016red1": {
                "response": {
                    "standby": false,
                    "unclean": false,
                    "hostname": "sit0016red1",
                    "ha_cluster": true,
                    "active_node": true,
                    "maintenance": false,
                    "last_checked": "Wed Sep 04  7:51:12 PM 2024 EDT"
                },
                "exit_code": 0
            }
        }
    },
    "trigged_by": "test.user",
    "success_nodes_count": 2,
    "failed_nodes_count": 0,
    "total_nodes_count": 2,
    "parameters": {
        "action": "status",
        "hostnames": [
            "sit0016red0",
            "sit0016red1"
        ],
        "target_type": "cluster"
    },
    "time_started": "2024-09-04T23:51:09Z",
    "time_finished": "2024-09-04T23:51:12Z"
}