RVC module

POST api/v2/jobs/rvc

Starts a SC//Reliant™ Virtual Controller (RVC) job for the RVC module. This provides a way to retrieve information about the SC//Reliant Virtual Controller (RVC) server running on a target. The API 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 and the payload details.

Required permissions

In order to perform these actions, the following conditions must be met:

Must have the Remote Job Execution feature turned on for your SC//Reliant Platform Manager tenant.
The user making the API request must have the following SC//Reliant Platform Manager capabilities:
- Create and Update a RVC job
- Call RVC read-only methods

Methods

The following are the available methods in the RVC module.

Method	Description
`rvc.api`	Retrieves the API information for all modules available.
`rvc.busy`	Retrieves a list of the long running tasks that RVC modules are performing.
`rvc.diagnostics`	Checks the environment for RVC runtime dependencies for each of its modules. To check a single module, pass `{"module":"<module>"}` in `params`. The default is `all`.
`rvc.external_connectivity_check`	Checks if RVC can connect to an external HTTP server. Pass the URL to check in `params` as `{"uri":"<url>"}`. This parameter is required. The result contains a `message` and the `roundtrip_time_ms`.
`rvc.external_processes`	Retrieves a list of the external processes that the RVC server is running. The list is empty when no external processes are running.
`rvc.instance`	Retrieves process information about the running instance of the RVC server.
`rvc.publish`	Publishes a message to a topic. Subscribers to the topic receive the message at their notification URI. Pass `topic` and `message` in `params`. Optionally pass `severity` (default `info`), `exit_code`, and `module` (default `rvc`).
`rvc.state`	Retrieves the state data for the running instance of the RVC server.
`rvc.subscribe`	Subscribes a notification URI to a topic on a module, so that the URI receives the progress messages that RVC publishes to the topic. Pass `module`, `topic`, and `subscriber_uri` in `params`. For example, subscribe to the `kvm` module and the name of a virtual machine to receive the progress messages for operations on that virtual machine.
`rvc.subscriptions`	Retrieves the current subscriptions, grouped by module and topic, with the notification URIs subscribed to each topic.
`rvc.unsubscribe`	Removes a subscription. Pass the same `module`, `topic`, and `subscriber_uri` in `params` that were used to subscribe.
`rvc.version`	Returns the version of the currently running RVC server. To include the build and package versions, pass `{"build":true,"package":true}` in `params`.

Common request parameters

The RVC module methods accept the following common request parameters as data in JSON format. These request parameters specify the RVC module and method to use as well as details about the target.

Parameter	Type	Description	Required
`method`	String	The RVC action to start. This value is specified as a combination of the RVC module and method. For example, to retrieve the version of the running RVC server you would specify the `rvc` module and the `version` method combined as `rvc.version`.	Yes
`params`	Object	The parameters for the method. Only the `rvc.diagnostics`, `rvc.external_connectivity_check`, `rvc.publish`, `rvc.subscribe`, `rvc.unsubscribe`, and `rvc.version` methods take parameters. For the parameters each method accepts, see Methods.	Dependent. Only for methods that take parameters.
`hostnames`	String array	The list of node hostnames 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.

Response syntax

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

{
    "id": integer,
    "type": "RVC3",
    "status": "string",
    "message": "string",
    "trigged_by": "string",
    "parameters": {
        "method": "rvc.<method>",
        "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": "RVC3",
    "status": "string",
    "message": "string",
    "trigged_by": "string",
    "parameters": {
        "method": "rvc.<method>",
        "node_group_name": "string",
        "node_group_id": integer,
        "saved_filter_name": "string",
        "saved_filter_id": integer
    },
    "time_started": "timestamp"
}

Common 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 RVC job. For RVC jobs, it is `RVC3`.
`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.

Examples

To see API examples for the RVC module, see RVC module examples