objects.proto 14 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450
  1. syntax = "proto3";
  2. package docker.swarmkit.v1;
  3. import "types.proto";
  4. import "specs.proto";
  5. import "google/protobuf/timestamp.proto";
  6. import "gogoproto/gogo.proto";
  7. import "google/protobuf/any.proto";
  8. import "plugin/plugin.proto";
  9. // This file contains definitions for all first-class objects in the cluster
  10. // API. Such types typically have a corresponding specification, with the
  11. // naming XXXSpec, but not all.
  12. // Meta contains metadata about objects. Every object contains a meta field.
  13. message Meta {
  14. // Version tracks the current version of the object.
  15. Version version = 1 [(gogoproto.nullable) = false];
  16. // Object timestamps.
  17. // Note: can't use stdtime because these fields are nullable.
  18. google.protobuf.Timestamp created_at = 2;
  19. google.protobuf.Timestamp updated_at = 3;
  20. }
  21. // Node provides the internal node state as seen by the cluster.
  22. message Node {
  23. option (docker.protobuf.plugin.store_object) = {
  24. watch_selectors: {
  25. id: true
  26. id_prefix: true
  27. name: true
  28. name_prefix: true
  29. custom: true
  30. custom_prefix: true
  31. role: true
  32. membership: true
  33. }
  34. };
  35. // ID specifies the identity of the node.
  36. string id = 1;
  37. Meta meta = 2 [(gogoproto.nullable) = false];
  38. // Spec defines the desired state of the node as specified by the user.
  39. // The system will honor this and will *never* modify it.
  40. NodeSpec spec = 3 [(gogoproto.nullable) = false];
  41. // Description encapsulated the properties of the Node as reported by the
  42. // agent.
  43. NodeDescription description = 4;
  44. // Status provides the current status of the node, as seen by the manager.
  45. NodeStatus status = 5 [(gogoproto.nullable) = false];
  46. // ManagerStatus provides the current status of the node's manager
  47. // component, if the node is a manager.
  48. ManagerStatus manager_status = 6;
  49. // The node attachment to the ingress network.
  50. NetworkAttachment attachment = 7;
  51. // Certificate is the TLS certificate issued for the node, if any.
  52. Certificate certificate = 8 [(gogoproto.nullable) = false];
  53. // Role is the *observed* role for this node. It differs from the
  54. // desired role set in Node.Spec.Role because the role here is only
  55. // updated after the Raft member list has been reconciled with the
  56. // desired role from the spec.
  57. //
  58. // This field represents the current reconciled state. If an action is
  59. // to be performed, first verify the role in the cert. This field only
  60. // shows the privilege level that the CA would currently grant when
  61. // issuing or renewing the node's certificate.
  62. NodeRole role = 9;
  63. }
  64. message Service {
  65. option (docker.protobuf.plugin.store_object) = {
  66. watch_selectors: {
  67. id: true
  68. id_prefix: true
  69. name: true
  70. name_prefix: true
  71. custom: true
  72. custom_prefix: true
  73. }
  74. };
  75. string id = 1;
  76. Meta meta = 2 [(gogoproto.nullable) = false];
  77. ServiceSpec spec = 3 [(gogoproto.nullable) = false];
  78. // SpecVersion versions Spec, to identify changes in the spec. Note that
  79. // this is not directly comparable to the service's Version.
  80. Version spec_version = 10;
  81. // PreviousSpec is the previous service spec that was in place before
  82. // "Spec".
  83. ServiceSpec previous_spec = 6;
  84. // PreviousSpecVersion versions PreviousSpec. Note that this is not
  85. // directly comparable to the service's Version.
  86. Version previous_spec_version = 11;
  87. // Runtime state of service endpoint. This may be different
  88. // from the spec version because the user may not have entered
  89. // the optional fields like node_port or virtual_ip and it
  90. // could be auto allocated by the system.
  91. Endpoint endpoint = 4;
  92. // UpdateStatus contains the status of an update, if one is in
  93. // progress.
  94. UpdateStatus update_status = 5;
  95. }
  96. // Endpoint specified all the network parameters required to
  97. // correctly discover and load balance a service
  98. message Endpoint {
  99. EndpointSpec spec = 1;
  100. // Runtime state of the exposed ports which may carry
  101. // auto-allocated swarm ports in addition to the user
  102. // configured information.
  103. repeated PortConfig ports = 2;
  104. // An endpoint attachment specifies the data that the process
  105. // of attaching an endpoint to a network creates.
  106. // VirtualIP specifies a set of networks this endpoint will be attached to
  107. // and the IP addresses the target service will be made available under.
  108. message VirtualIP {
  109. // NetworkID for which this endpoint attachment was created.
  110. string network_id = 1;
  111. // A virtual IP is used to address this service in IP
  112. // layer that the client can use to send requests to
  113. // this service. A DNS A/AAAA query on the service
  114. // name might return this IP to the client. This is
  115. // strictly a logical IP and there may not be any
  116. // interfaces assigned this IP address or any route
  117. // created for this address. More than one to
  118. // accommodate for both IPv4 and IPv6
  119. string addr = 2;
  120. }
  121. // VirtualIPs specifies the IP addresses under which this endpoint will be
  122. // made available.
  123. repeated VirtualIP virtual_ips = 3 [(gogoproto.customname) = "VirtualIPs"];
  124. }
  125. // Task specifies the parameters for implementing a Spec. A task is effectively
  126. // immutable and idempotent. Once it is dispatched to a node, it will not be
  127. // dispatched to another node.
  128. message Task {
  129. option (docker.protobuf.plugin.store_object) = {
  130. watch_selectors: {
  131. id: true
  132. id_prefix: true
  133. name: true
  134. name_prefix: true
  135. custom: true
  136. custom_prefix: true
  137. service_id: true
  138. node_id: true
  139. slot: true
  140. desired_state: true
  141. }
  142. };
  143. string id = 1;
  144. Meta meta = 2 [(gogoproto.nullable) = false];
  145. // Spec defines the desired state of the task as specified by the user.
  146. // The system will honor this and will *never* modify it.
  147. TaskSpec spec = 3 [(gogoproto.nullable) = false];
  148. // SpecVersion is copied from Service, to identify which version of the
  149. // spec this task has. Note that this is not directly comparable to the
  150. // service's Version.
  151. Version spec_version = 14;
  152. // ServiceID indicates the service under which this task is orchestrated. This
  153. // should almost always be set.
  154. string service_id = 4;
  155. // Slot is the service slot number for a task.
  156. // For example, if a replicated service has replicas = 2, there will be a
  157. // task with slot = 1, and another with slot = 2.
  158. uint64 slot = 5;
  159. // NodeID indicates the node to which the task is assigned. If this field
  160. // is empty or not set, the task is unassigned.
  161. string node_id = 6;
  162. // Annotations defines the names and labels for the runtime, as set by
  163. // the cluster manager.
  164. //
  165. // As backup, if this field has an empty name, the runtime will
  166. // allocate a unique name for the actual container.
  167. //
  168. // NOTE(stevvooe): The preserves the ability for us to making naming
  169. // decisions for tasks in orchestrator, albeit, this is left empty for now.
  170. Annotations annotations = 7 [(gogoproto.nullable) = false];
  171. // ServiceAnnotations is a direct copy of the service name and labels when
  172. // this task is created.
  173. //
  174. // Labels set here will *not* be propagated to the runtime target, such as a
  175. // container. Use labels on the runtime target for that purpose.
  176. Annotations service_annotations = 8 [(gogoproto.nullable) = false];
  177. TaskStatus status = 9 [(gogoproto.nullable) = false];
  178. // DesiredState is the target state for the task. It is set to
  179. // TaskStateRunning when a task is first created, and changed to
  180. // TaskStateShutdown if the manager wants to terminate the task. This field
  181. // is only written by the manager.
  182. TaskState desired_state = 10;
  183. // List of network attachments by the task.
  184. repeated NetworkAttachment networks = 11;
  185. // A copy of runtime state of service endpoint from Service
  186. // object to be distributed to agents as part of the task.
  187. Endpoint endpoint = 12;
  188. // LogDriver specifies the selected log driver to use for the task. Agent
  189. // processes should always favor the value in this field.
  190. //
  191. // If present in the TaskSpec, this will be a copy of that value. The
  192. // orchestrator may choose to insert a value here, which should be honored,
  193. // such a cluster default or policy-based value.
  194. //
  195. // If not present, the daemon's default will be used.
  196. Driver log_driver = 13;
  197. }
  198. // NetworkAttachment specifies the network parameters of attachment to
  199. // a single network by an object such as task or node.
  200. message NetworkAttachment {
  201. // Network state as a whole becomes part of the object so that
  202. // it always is available for use in agents so that agents
  203. // don't have any other dependency during execution.
  204. Network network = 1;
  205. // List of IPv4/IPv6 addresses that are assigned to the object
  206. // as part of getting attached to this network.
  207. repeated string addresses = 2;
  208. // List of aliases by which a task is resolved in a network
  209. repeated string aliases = 3;
  210. // Map of all the driver attachment options for this network
  211. map<string,string> driver_attachment_opts = 4;
  212. }
  213. message Network {
  214. option (docker.protobuf.plugin.store_object) = {
  215. watch_selectors: {
  216. id: true
  217. id_prefix: true
  218. name: true
  219. name_prefix: true
  220. custom: true
  221. custom_prefix: true
  222. }
  223. };
  224. string id = 1;
  225. Meta meta = 2 [(gogoproto.nullable) = false];
  226. NetworkSpec spec = 3 [(gogoproto.nullable) = false];
  227. // Driver specific operational state provided by the network driver.
  228. Driver driver_state = 4;
  229. // Runtime state of IPAM options. This may not reflect the
  230. // ipam options from NetworkSpec.
  231. IPAMOptions ipam = 5 [(gogoproto.customname) = "IPAM"];
  232. }
  233. // Cluster provides global cluster settings.
  234. message Cluster {
  235. option (docker.protobuf.plugin.store_object) = {
  236. watch_selectors: {
  237. id: true
  238. id_prefix: true
  239. name: true
  240. name_prefix: true
  241. custom: true
  242. custom_prefix: true
  243. }
  244. };
  245. string id = 1;
  246. Meta meta = 2 [(gogoproto.nullable) = false];
  247. ClusterSpec spec = 3 [(gogoproto.nullable) = false];
  248. // RootCA contains key material for the root CA.
  249. RootCA root_ca = 4 [(gogoproto.nullable)=false, (gogoproto.customname) = "RootCA"];
  250. // Symmetric encryption key distributed by the lead manager. Used by agents
  251. // for securing network bootstrapping and communication.
  252. repeated EncryptionKey network_bootstrap_keys = 5;
  253. // Logical clock used to timestamp every key. It allows other managers
  254. // and agents to unambiguously identify the older key to be deleted when
  255. // a new key is allocated on key rotation.
  256. uint64 encryption_key_lamport_clock = 6;
  257. // BlacklistedCertificates tracks certificates that should no longer
  258. // be honored. It's a mapping from CN -> BlacklistedCertificate.
  259. // swarm. Their certificates should effectively be blacklisted.
  260. map<string, BlacklistedCertificate> blacklisted_certificates = 8;
  261. // UnlockKeys defines the keys that lock node data at rest. For example,
  262. // this would contain the key encrypting key (KEK) that will encrypt the
  263. // manager TLS keys at rest and the raft encryption keys at rest.
  264. // If the key is empty, the node will be unlocked (will not require a key
  265. // to start up from a shut down state).
  266. repeated EncryptionKey unlock_keys = 9;
  267. }
  268. // Secret represents a secret that should be passed to a container or a node,
  269. // and is immutable.
  270. message Secret {
  271. option (docker.protobuf.plugin.store_object) = {
  272. watch_selectors: {
  273. id: true
  274. id_prefix: true
  275. name: true
  276. name_prefix: true
  277. custom: true
  278. custom_prefix: true
  279. }
  280. };
  281. string id = 1;
  282. Meta meta = 2 [(gogoproto.nullable) = false];
  283. // Spec contains the actual secret data, as well as any context around the
  284. // secret data that the user provides.
  285. SecretSpec spec = 3 [(gogoproto.nullable) = false];
  286. // Whether the secret is an internal secret (not set by a user) or not.
  287. bool internal = 4;
  288. }
  289. // Config represents a set of configuration files that should be passed to a
  290. // container.
  291. message Config {
  292. option (docker.protobuf.plugin.store_object) = {
  293. watch_selectors: {
  294. id: true
  295. id_prefix: true
  296. name: true
  297. name_prefix: true
  298. custom: true
  299. custom_prefix: true
  300. }
  301. };
  302. string id = 1;
  303. Meta meta = 2 [(gogoproto.nullable) = false];
  304. // Spec contains the actual config data, as well as any context around the
  305. // config data that the user provides.
  306. ConfigSpec spec = 3 [(gogoproto.nullable) = false];
  307. }
  308. // Resource is a top-level object with externally defined content and indexing.
  309. // SwarmKit can serve as a store for these objects without understanding their
  310. // meanings.
  311. message Resource {
  312. option (docker.protobuf.plugin.store_object) = {
  313. watch_selectors: {
  314. id: true
  315. id_prefix: true
  316. name: true
  317. name_prefix: true
  318. custom: true
  319. custom_prefix: true
  320. kind: true
  321. }
  322. };
  323. string id = 1 [(gogoproto.customname) = "ID"];
  324. Meta meta = 2 [(gogoproto.nullable) = false];
  325. Annotations annotations = 3 [(gogoproto.nullable) = false];
  326. // Kind identifies this class of object. It is essentially a namespace
  327. // to keep IDs or indices from colliding between unrelated Resource
  328. // objects. This must correspond to the name of an Extension.
  329. string kind = 4;
  330. // Payload bytes. This data is not interpreted in any way by SwarmKit.
  331. // By convention, it should be a marshalled protocol buffers message.
  332. google.protobuf.Any payload = 5;
  333. }
  334. // Extension declares a type of "resource" object. This message provides some
  335. // metadata about the objects.
  336. message Extension {
  337. option (docker.protobuf.plugin.store_object) = {
  338. watch_selectors: {
  339. id: true
  340. id_prefix: true
  341. name: true
  342. name_prefix: true
  343. custom: true
  344. custom_prefix: true
  345. }
  346. };
  347. string id = 1 [(gogoproto.customname) = "ID"];
  348. Meta meta = 2 [(gogoproto.nullable) = false];
  349. Annotations annotations = 3 [(gogoproto.nullable) = false];
  350. string description = 4;
  351. // TODO(aaronl): Add optional indexing capabilities. It would be
  352. // extremely useful be able to automatically introspect protobuf, json,
  353. // etc. objects and automatically index them based on a schema and field
  354. // paths defined here.
  355. //
  356. //oneof Schema {
  357. // google.protobuf.Descriptor protobuf = 1;
  358. // bytes json = 2;
  359. //}
  360. //
  361. //Schema schema = 5;
  362. //
  363. // // Indices, with values expressed as Go templates.
  364. //repeated IndexEntry index_templates = 6;
  365. }