RVC module examples

The following are examples demonstrating the use of the SC//Reliant™ Virtual Controller (RVC) API job for the RVC module. 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 RVC methods in the RVC module. You can substitute these in any of the provided examples.

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.
`rvc.external_connectivity_check`	Checks if RVC can connect to an external HTTP server.
`rvc.instance`	Retrieves process information about the running instance of the RVC server.
`rvc.state`	Retrieves the state data for the running instance of the RVC server.
`rvc.version`	Returns the version of the currently running RVC server.

Examples

Example 1: Retrieve the RVC server version for a list of node hostnames.

This example starts a RVC job requesting the RVC server version for a node with hostname sit0001red0.

ruby api.rb <customer_code> post api/v2/jobs/rvc '{"method":"rvc.version","hostnames":["sit0001red0"]}'

Response

{
  "id": 1599018,
  "type": "RVC3",
  "status": "pending",
  "message": null,
  "trigged_by": "test.user",
  "parameters": {
    "method": "rvc.version",
    "hostnames": [
      "sit0001red0"
    ]
  },
  "time_started": "2025-04-11T17:44:26Z"
}

Use the following API call to retrieve the job details, which includes the payload with the RVC version details. Ensure that you're using the job ID from the output of the previous API call when requesting the job details.

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

Response

{
  "id": 1599018,
  "type": "RVC3",
  "status": "finished",
  "message": null,
  "payload": {
    "sit0001red0": [
      {
        "result": "3.13.0",
        "timestamp": 1775490559
      }
    ]
  },
  "trigged_by": "test.user",
  "success_nodes_count": 1,
  "failed_nodes_count": 0,
  "total_nodes_count": 1,
  "parameters": {
    "method": "rvc.version",
    "params": {
    },
    "hostnames": [
      "sit0001red0"
    ],
    "update_rpm": true
  },
  "time_started": "2026-04-06T15:49:17Z",
  "time_finished": "2026-04-06T15:49:18Z"
}

Example 2: Retrieve the RVC server instance details for a list of node hostnames.

This example starts a RVC job requesting the RVC server instance details for a node with hostname sit0001red0.

ruby api.rb <customer_code> post api/v2/jobs/rvc '{"method":"rvc.instance","hostnames":["sit0001red0"]}'

Response

{
  "id": 1600018,
  "type": "RVC3",
  "status": "pending",
  "message": null,
  "trigged_by": "test.user",
  "parameters": {
    "method": "rvc.instance",
    "hostnames": [
      "sit0001red0"
    ]
  },
  "time_started": "2025-04-11T17:50:12Z"
}

Use the following API call to retrieve the job details, which includes the payload with the RVC instance details. Ensure that you're using the job ID from the output of the previous API call when requesting the job details.

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

Response

{
  "id": 1600018,
  "type": "RVC3",
  "status": "finished",
  "message": null,
  "payload": {
    "sit0001red0": [
      {
        "result": {
          "pid": 2409,
          "user": "root",
          "uptime": "22:45:07.083934408",
          "cluster": true,
          "command": "/usr/local/bin/rvcd --config=/etc/rvc/rvc.yaml",
          "child_processes": [
          ]
        },
        "timestamp": 1775490659
      }
    ]
  },
  "trigged_by": "test.user",
  "success_nodes_count": 1,
  "failed_nodes_count": 0,
  "total_nodes_count": 1,
  "parameters": {
    "method": "rvc.instance",
    "params": {
    },
    "hostnames": [
      "sit0001red0"
    ],
    "update_rpm": true
  },
  "time_started": "2026-04-06T15:50:58Z",
  "time_finished": "2026-04-06T15:50:59Z"
}

Example 3: List the long-running tasks on a list of node hostnames

This example uses rvc.busy to check whether RVC is performing any long-running operations on the nodes with hostnames sit0001red0 and sit0001red1. Use it before you start an operation on a virtual machine, and to confirm that an operation you started, such as a backup or a restore, has finished.

ruby api.rb <customer_code> post api/v2/jobs/rvc '{"method":"rvc.busy","hostnames":["sit0001red0","sit0001red1"]}'

Use the job ID from the response to retrieve the job details.

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

Response

{
  "id": 1785920,
  "type": "RVC3",
  "status": "finished",
  "message": null,
  "payload": {
    "sit0001red0": [
      {
        "result": [
          {
            "module": "kvm",
            "tasks": [
              "VM kvm1 is performing full backup"
            ]
          }
        ],
        "timestamp": 1792204154
      }
    ],
    "sit0001red1": [
      {
        "result": [],
        "timestamp": 1792204154
      }
    ]
  },
  "trigged_by": "test.user",
  "success_nodes_count": 2,
  "failed_nodes_count": 0,
  "total_nodes_count": 2,
  "parameters": {
    "method": "rvc.busy",
    "hostnames": [
      "sit0001red0",
      "sit0001red1"
    ]
  }
}

The result for each node is a list with one entry for each RVC module that is busy. Modules with nothing running are left out, so a node with no long-running operations returns an empty list, as sit0001red1 does here. Each entry has the following fields.

Field	Type	Description
`module`	String	The RVC module performing the operations, for example `kvm`.
`tasks`	Array of strings	A short description of each operation in progress.

The following modules report long-running operations. Other modules always return no tasks.

Module	Task description	Operations
`kvm`	`VM <name> is performing <operation>`	`start`, `full backup`, `restore backup`, `create snapshot`, `restore snapshot`, and `redefine snapshots`.
`shell`	`process <pid> running since <time>`	Commands started through the shell module that haven't finished.

A virtual machine can run only one of these operations at a time. A second operation on a busy virtual machine is refused with error -32085, Virtual Machine <name> is busy running the <operation> operation. Wait until the virtual machine no longer appears in the rvc.busy result, and then try again.

While a long-running operation is starting, a node can be too busy to answer within the job's reply window, and its result is Node <hostname> not discovered by RJE broker. This doesn't mean the operation has finished. Wait and run rvc.busy again. For more information, see Troubleshooting RVC jobs.