nomad/contributing/checklist-rpc-endpoint.md

New/Updated RPC Endpoint Checklist

Prefer adding a new message to changing any existing RPC messages.

Code

• Request struct and *RequestType constant in nomad/structs/structs.go. Append the constant, old constant values must remain unchanged. Just add the request type to this file, all other resource definitions must be on their own separate file.

• In nomad/fsm.go, add a dispatch case to the switch statement in (n *nomadFSM) Apply

  • *nomadFSM method to decode the request and call the state method

• State method for modifying objects in a Txn in the state package, located in nomad/state/. Every new resource should have its own file and test file, named using the convention nomad/state/state_store_[resource].go and nomad/state/state_store_[resource]_test.go

• Handler for the request in nomad/foo_endpoint.go

  • RPCs are resolved by matching the method name for bound structs net/rpc
  • Register any new RPC structs in nomad/server.go
  • Authentication:
    • For RPCs that support HTTP APIs, call Authenticate before forwarding. Return any error after frowarding, and call ResolveACL to get an ACL to check.
    • For RPCs that support client-to-server RPCs only, use AuthenticateClientOnly before forwarding. Check the AllowClientOp ACL after forwarding.
    • For RPCs that support server-to-server RPCs only, use AuthenticateServerOnly before forwarding. Check the AllowServerOp ACL before forwarding.
  • Authorization:
    • Use ResolveACL to turn the authenticated request into an ACL to check.
    • For Update/Get/Delete RPCs, check ACLs before hitting the state store.
    • For List RPCs, use ACLs as a filter on the query.
    • Never check that the ACL object is nil to bypass authorization. The authorization methods in acl/acl.go should already handle nil ACL objects correctly (by rejecting them).

• Wrapper for the HTTP request in command/agent/foo_endpoint.go

  • Backwards compatibility requires a new endpoint, an upgraded client or server may be forwarding this request to an old server, without support for the new RPC
  • RPCs triggered by an internal process may not need support
  • Check ACLs as an optimization

• Endpoint added/updated in the nomad-openapi repository.

  • New endpoints will need to be configured in that repository's generator package.
  • Updated endpoints may require the generator configuration to change, especially if parameters or headers change.
  • If the accepted or returned struct schema changes, the Nomad version references in generator/go.mod will need to be updated. Once the version is updated, regenerate the spec and all all clients so that the new schema is reflected in the spec and thus the generated models.
  • If QueryOptions, QueryMeta, WriteOptions, or WriteMeta change, the v1 framework will need to updated to support the change.

• nomad/core_sched.go sends many RPCs

  • ServersMeetMinimumVersion asserts that the server cluster is upgraded, so use this to guard sending the new RPC, else send the old RPC
  • Version must match the actual release version!

• If implementing a Client RPC...

  • Use QueryOptions instead of WriteRequest in the Request struct as WriteRequest is only for Raft writes.
  • Set QueryOptions.AllowStale = true in the Server RPC forwarder to avoid an infinite loop between leaders and followers when a Client RPC is forwarded through a follower. See https://github.com/hashicorp/nomad/issues/16517

Docs

• Changelog
• Metrics
• API docs for RPCs with an HTTP endpoint, include ACLs, params, and example response body.