RMS gRPC API conventions
This page describes the conventions that apply across the RMS gRPC API: how you connect, how you identify nodes, how requests and responses are shaped, and how RMS reports failures.
Transport and authentication
RMS serves gRPC over TLS 1.3 and requires mutual TLS (mTLS) by default. The default port is 8801.
An operator can enable plaintext for development only, and that mode needs two independent opt-ins.
For the settings, refer to Configuring RMS.
RMS doesn’t apply per-RPC authorization. Any client that completes the TLS handshake can call every RPC, so restrict access to trusted services and operators on a controlled management network.
Registered and caller-supplied targets
Each RPC acts on nodes in one of three ways. The RPC catalog shows the mode of each RPC in its Target column.
Batch RPCs usually take caller-supplied nodes, so a client that owns the list of nodes can operate on them without registering them first. For the reasoning behind this model, refer to Overview.
Node identity
A node is described by NodeInfo, and a list of nodes by
NodeSet.
node_ididentifies the node, andrack_ididentifies the rack that contains it.bmc_endpointandhost_endpointare each anEndpoint: a network interface, a port, andCredentials. Credentials are either a username and password or a session token. Which endpoints a node needs depends on its type and on the RPC, so each RPC page and the Operations guides state what is required.typeis aNodeTypethat selects the hardware-specific implementation. Iftypeis unset orNODE_TYPE_UNSPECIFIED, RMS usesnode_descriptor. A concretetypetakes precedence over the descriptor.node_descriptorcarries identity attributes as string pairs. RMS dispatch currently accepts therole,vendor, andproduct_familyattributes.
Request and response shapes
- Fields in messages use the protobuf field names shown in this reference.
grpcurlaccepts these names and the lower camel case JSON names. - Proto3 has no required fields. A field that an RPC needs says so in its description, and a missing value takes the protobuf default for its type.
- A field marked
optionalhas explicit presence, so RMS can tell an unset field from a default value. A field markedrepeatedis a list, and amapfield is a set of key-value pairs. - A
oneofallows at most one of its member fields.Credentialsis an example. - Enum fields use the value names shown in the reference. The zero value is
*_UNSPECIFIEDand means the caller left the field unset. Don’t send it where an RPC needs a value.
Error handling
RMS reports an outcome in two places: the gRPC status of the call, and a status inside the response. Check both.
Status in the response
Most RPCs return a ReturnCode in a status field,
either directly or inside an
OperationResponse or
NodeBatchResponse.
RMS returns validation and business failures this way, inside a successful gRPC response. A gRPC
OK status therefore doesn’t mean the operation succeeded.
Batch responses
RPCs that act on several nodes return a NodeBatchResponse with these fields:
A batch can partly succeed. For an asynchronous batch, a FAILURE status together with successful
entries in node_results means RMS refused some nodes and started the rest. A batch fails outright
only when RMS admitted no node. Refer to Async jobs for why RMS
refuses a node.
gRPC errors
RMS rejects some requests with a gRPC error instead of a response status. For example, it returns
INVALID_ARGUMENT for an invalid enum value or an empty required identifier, and NOT_FOUND when
you poll a job that it doesn’t track. Each RPC page lists the gRPC errors that were verified for
that RPC. Treat any non-OK gRPC status as a failed call.
Concurrency
Operations on different nodes run in parallel, and operations on the same node run one at a time. Registered power changes also hold a per-rack guard, so RMS refuses a second power change on a rack while one is in progress. For details, refer to Operations overview.
Compatibility
The RackManager service is a guaranteed public interface. Within a major version, existing clients
continue to work, and RMS adds new optional fields and RPCs in a backward-compatible way. Ignore
fields that you don’t recognize. For the full policy, refer to
Release and QA process.