2021-12-09 14:25:44 +00:00
|
|
|
# New/Updated RPC Endpoint Checklist
|
2019-06-13 19:08:33 +00:00
|
|
|
|
|
|
|
|
Prefer adding a new message to changing any existing RPC messages.
|
|
|
|
|
|
|
|
|
|
## Code
|
|
|
|
|
|
2019-06-26 14:45:29 +00:00
|
|
|
* [ ] `Request` struct and `*RequestType` constant in
|
|
|
|
|
`nomad/structs/structs.go`. Append the constant, old constant
|
|
|
|
|
values must remain unchanged
|
2020-01-31 15:13:21 +00:00
|
|
|
|
2019-10-14 20:09:27 +00:00
|
|
|
* [ ] In `nomad/fsm.go`, add a dispatch case to the switch statement in `(n *nomadFSM) Apply`
|
2019-06-13 19:08:33 +00:00
|
|
|
* `*nomadFSM` method to decode the request and call the state method
|
2020-01-31 15:13:21 +00:00
|
|
|
|
2019-06-13 19:08:33 +00:00
|
|
|
* [ ] State method for modifying objects in a `Txn` in `nomad/state/state_store.go`
|
|
|
|
|
* `nomad/state/state_store_test.go`
|
2020-01-31 15:13:21 +00:00
|
|
|
|
2019-06-13 19:08:33 +00:00
|
|
|
* [ ] Handler for the request in `nomad/foo_endpoint.go`
|
|
|
|
|
* RPCs are resolved by matching the method name for bound structs
|
|
|
|
|
[net/rpc](https://golang.org/pkg/net/rpc/)
|
2020-02-14 15:41:18 +00:00
|
|
|
* Check ACLs for security, list endpoints filter by ACL
|
2020-01-28 15:28:34 +00:00
|
|
|
* Register new RPC struct in `nomad/server.go`
|
2020-01-31 15:13:21 +00:00
|
|
|
* Check ACLs to enforce security
|
|
|
|
|
|
2021-12-09 14:25:44 +00:00
|
|
|
* [ ] Wrapper for the HTTP request in `command/agent/foo_endpoint.go`
|
2019-06-13 19:08:33 +00:00
|
|
|
* 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
|
2020-01-31 15:13:21 +00:00
|
|
|
* Check ACLs as an optimization
|
|
|
|
|
|
2021-12-09 14:25:44 +00:00
|
|
|
* [ ] Endpoint added/updated in the [`nomad-openapi`](https://github.com/hashicorp/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.
|
|
|
|
|
|
2019-06-13 19:08:33 +00:00
|
|
|
* [ ] `nomad/core_sched.go` sends many RPCs
|
|
|
|
|
* `ServersMeetMinimumVersion` asserts that the server cluster is
|
2021-03-23 17:55:34 +00:00
|
|
|
upgraded, so use this to guard sending the new RPC, else send the old RPC
|
2019-06-13 19:08:33 +00:00
|
|
|
* Version must match the actual release version!
|
|
|
|
|
|
2023-03-20 23:32:32 +00:00
|
|
|
* [ ] 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
|
|
|
|
|
|
2019-06-13 19:08:33 +00:00
|
|
|
## Docs
|
|
|
|
|
|
|
|
|
|
* [ ] Changelog
|
2021-01-04 17:59:55 +00:00
|
|
|
* [ ] [Metrics](https://www.nomadproject.io/docs/operations/metrics#server-metrics)
|
|
|
|
|
* [ ] [API docs](https://www.nomadproject.io/api-docs) for RPCs with an HTTP endpoint, include ACLs, params, and example response body.
|
