Getting started with the RMS gRPC API
This guide shows you how to connect to RMS, call your first RPC, and follow three common flows: control power, update firmware, and operate on nodes that RMS doesn’t store.
Prerequisites
- A running RMS instance. To start one for development, refer to Running RMS.
- The address of the RMS gRPC listener. The default port is
8801. - For a production deployment, a client certificate, client key, and CA certificate. RMS requires mutual TLS (mTLS) over TLS 1.3 unless an operator explicitly enables plaintext for development. For the settings, refer to Configuring RMS.
grpcurlto call RPCs from a shell.- The protobuf files for the services. RMS doesn’t enable gRPC server reflection, so
grpcurlneeds the files on disk.
Get the protobuf files
Clone the RMS repository and check out the tag of your
RMS release. The files are in the crates/librms/proto directory:
rack_manager.protodefines theRackManagerservice.rack_manager_v2.protodefines theRackManagerV2service and importsrack_manager.proto.
Releases that pin librms by Git revision in Cargo.toml don’t have crates/librms. For those,
use the proto directory of nv-rms-client at
the pinned revision, and pass that directory to -import-path.
Call an RPC with grpcurl
Set the address and the common grpcurl flags once. The examples in this reference use these two
variables. They assume a Bash shell.
For a development instance that serves plaintext, replace the three certificate flags with
-plaintext.
Check connectivity with GetVersion:
The response carries the server version:
If you prefer a purpose-built client, the rack_manager_client binary in the RMS repository
wraps many of the RPCs. Each RPC page lists the equivalent command where one exists.
Control power on a registered node
Registered RPCs act on nodes that you store in RMS inventory.
-
Register the node with
CreateNodes. Settypeto aNodeTypevalue that matches the hardware. The node needs a BMC endpoint with credentials. -
Read the power state with
GetPowerState: -
Change it with
SetPowerState. Both calls are synchronous, so the response carries the result.
Update firmware and poll the job
Firmware updates are asynchronous. The RPC starts the work and returns a job ID.
-
Start the update with
UpdateFirmware. Thefilenameis relative to the RMS firmware directory, or an absolute path.The response includes
job_id. -
Poll
GetFirmwareJobStatuswith that ID untiljob_stateisFIRMWARE_JOB_STATE_COMPLETEDorFIRMWARE_JOB_STATE_FAILED:If the job fails,
error_codeanderror_messageexplain why. On completion,result_jsonholds the detailed result.
For the job model, including parent and child jobs for batch RPCs, refer to Async jobs.
Operate on nodes that RMS doesn’t store
Batch RPCs act on caller-supplied nodes. The request carries each node’s endpoints and credentials,
and RMS doesn’t store them. For example, read power state for a set of nodes with
BatchGetPowerState:
The response reports a result for each node in response.node_results and the power states of the
nodes that RMS queried in node_power_states. A batch can partly succeed, so check each node’s
result. For details, refer to Conventions.
Next steps
- Browse the RPC catalog to find the RPC for your task.
- Read Conventions to understand node identity and error handling.
- Read Async jobs before you build a client that starts long-running work.