| syntax = "proto3"; |
| package cloud.bmaas.server.api; |
| option go_package = "source.monogon.dev/cloud/bmaas/server/api"; |
| |
| import "metropolis/proto/api/configuration.proto"; |
| import "cloud/agent/api/hwreport.proto"; |
| |
| // AgentCallback runs on the BMDB Server and exposes a gRPC interface to agents |
| // running on machines. These APIs are served over TLS using component-style |
| // server certificates, but clients are authenticated using ephemeral |
| // certificates proving ownership of an agent keypair. |
| service AgentCallback { |
| // Heartbeat is called by agents repeatedly to upload a hardware report, signal |
| // liveness and retrieve actions to be prformed on a host. |
| // |
| // This isn't a streaming RPC as the current server implementation actually |
| // isn't reactive, so it would have to do its own inner polling to create |
| // a stream of updates. To keep things simple, we instead let the agent decide |
| // on the cadence of updates it wants to keep up with. |
| rpc Heartbeat(AgentHeartbeatRequest) returns (AgentHeartbeatResponse); |
| } |
| |
| message AgentHardwareReport { |
| cloud.agent.api.Node report = 1; |
| // List of human-readable warnings which occurred during hardware report |
| // generation. |
| repeated string warning = 2; |
| } |
| |
| // OSInstallationReport is submitted from the agent to the BMDB server after |
| // successful OS installation. |
| message OSInstallationReport { |
| // generation must be set to the same value as 'generation' in the |
| // OSInstallation request which triggered the OS installation |
| int64 generation = 1; |
| |
| // Success is set by the agent when the installation request has been |
| // successfully fulfilled. It is currently empty but is specified as a |
| // message to allow it to be expanded in the future. |
| message Success {} |
| // Error is set by the agent when the installation request could not be |
| // fulfilled due to an error. |
| message Error { |
| // A human-readable message of what went wrong. |
| string error = 1; |
| } |
| oneof result { |
| Success success = 2; |
| Error error = 3; |
| } |
| } |
| |
| message AgentHeartbeatRequest { |
| // MachineID that this agent represents. Technically not necessary since |
| // keypairs between agents should be unique, but this provides an extra layer |
| // of protection against programming bugs. |
| string machine_id = 1; |
| // Optional hardware report to be upserted for this machine. An agent should |
| // submit one at least once after it's started, as early as it can. |
| AgentHardwareReport hardware_report = 2; |
| // Optional installation report sent to be upserted to this machine. An agent |
| // should submit one after it successfully installed an operating system for |
| // a given OSInstallationRequest. |
| OSInstallationReport installation_report = 3; |
| } |
| |
| message MetropolisInstallationRequest { |
| // An HTTPS URL to a Metropolis bundle containing the OS to install. |
| string bundle_url = 1; |
| // Node parameters to be supplied to the new node. Note that network_config |
| // is automatically filled out if coming from the takeover. |
| metropolis.proto.api.NodeParameters node_parameters = 2; |
| // Name of the block device to be used as the root device for the install. |
| // A list of block devices can be taken from the node hardware report. |
| string root_device = 3; |
| } |
| |
| // OSInstallationRequest is provided to the agent by the BMDB server, from |
| // a responding BMDB tag, when an OS installation request is pending. |
| message OSInstallationRequest { |
| // generation is the 'version' of the OS installation request, and will always |
| // be incremented within the BMDB when a new OS installation request is |
| // submitted. The agent must pipe this through to the OSInstallationReport to |
| // let the rest of the system know which OS installation request it actually |
| // fulfilled. |
| int64 generation = 1; |
| // Selects which operating system installation flow is used. |
| oneof type { |
| MetropolisInstallationRequest metropolis = 2; |
| } |
| } |
| |
| message AgentHeartbeatResponse { |
| // If set, the control plane is requesting the installation of an operating |
| // system. |
| OSInstallationRequest installation_request = 1; |
| } |