specs.proto 14 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399
  1. syntax = "proto3";
  2. package docker.swarmkit.v1;
  3. import "types.proto";
  4. import "gogoproto/gogo.proto";
  5. import "google/protobuf/duration.proto";
  6. import "google/protobuf/any.proto";
  7. // Specs are container objects for user provided input. All creations and
  8. // updates are done through spec types. As a convention, user input from a spec
  9. // is never touched in created objects. This allows one to verify that the
  10. // users intent has not been modified.
  11. //
  12. // Put differently, spec types can be said to represent the desired state of
  13. // the system. In situations where modifications need to be made to a
  14. // particular component, API objects will either contain a copy of the spec
  15. // component or a different representation to reflect allocation or resolution.
  16. message NodeSpec {
  17. Annotations annotations = 1 [(gogoproto.nullable) = false];
  18. enum Membership {
  19. option (gogoproto.goproto_enum_prefix) = false;
  20. PENDING = 0 [(gogoproto.enumvalue_customname) = "NodeMembershipPending"];
  21. ACCEPTED = 1 [(gogoproto.enumvalue_customname) = "NodeMembershipAccepted"];
  22. }
  23. enum Availability {
  24. option (gogoproto.goproto_enum_prefix) = false;
  25. // Active nodes.
  26. ACTIVE = 0 [(gogoproto.enumvalue_customname) = "NodeAvailabilityActive"];
  27. // Paused nodes won't be considered by the scheduler, preventing any
  28. // further task to run on them.
  29. PAUSE = 1 [(gogoproto.enumvalue_customname) = "NodeAvailabilityPause"];
  30. // Drained nodes are paused and any task already running on them will
  31. // be evicted.
  32. DRAIN = 2 [(gogoproto.enumvalue_customname) = "NodeAvailabilityDrain"];
  33. }
  34. // DesiredRole defines the role the node should have.
  35. NodeRole desired_role = 2;
  36. // Membership controls the admission of the node into the cluster.
  37. Membership membership = 3;
  38. // Availability allows a user to control the current scheduling status of a
  39. // node.
  40. Availability availability = 4;
  41. }
  42. // ServiceSpec defines the properties of a service.
  43. //
  44. // A service instructs the cluster in orchestrating repeated instances of a
  45. // template, implemented as tasks. Based on the number of instances, scheduling
  46. // strategy and restart policy, a number of application-level behaviors can be
  47. // defined.
  48. message ServiceSpec {
  49. Annotations annotations = 1 [(gogoproto.nullable) = false];
  50. // Task defines the task template this service will spawn.
  51. TaskSpec task = 2 [(gogoproto.nullable) = false];
  52. oneof mode {
  53. ReplicatedService replicated = 3;
  54. GlobalService global = 4;
  55. }
  56. // Update contains settings which affect updates.
  57. UpdateConfig update = 6;
  58. // Rollback contains settings which affect rollbacks of updates.
  59. UpdateConfig rollback = 9;
  60. // ServiceSpec.Networks has been deprecated and is replaced by
  61. // Networks field in Task (TaskSpec.Networks).
  62. // This field (ServiceSpec.Networks) is kept for compatibility.
  63. // In case TaskSpec.Networks does not exist, ServiceSpec.Networks
  64. // is still honored if it exists.
  65. repeated NetworkAttachmentConfig networks = 7 [deprecated=true];
  66. // Service endpoint specifies the user provided configuration
  67. // to properly discover and load balance a service.
  68. EndpointSpec endpoint = 8;
  69. }
  70. // ReplicatedService sets the reconciliation target to certain number of replicas.
  71. message ReplicatedService {
  72. uint64 replicas = 1;
  73. }
  74. // GlobalService represents global service.
  75. message GlobalService {
  76. // Empty message for now.
  77. }
  78. message TaskSpec {
  79. oneof runtime {
  80. NetworkAttachmentSpec attachment = 8;
  81. ContainerSpec container = 1;
  82. GenericRuntimeSpec generic = 10;
  83. }
  84. // Resource requirements for the container.
  85. ResourceRequirements resources = 2;
  86. // RestartPolicy specifies what to do when a task fails or finishes.
  87. RestartPolicy restart = 4;
  88. // Placement specifies node selection constraints
  89. Placement placement = 5;
  90. // LogDriver specifies the log driver to use for the task. Any runtime will
  91. // direct logs into the specified driver for the duration of the task.
  92. Driver log_driver = 6;
  93. // Networks specifies the list of network attachment
  94. // configurations (which specify the network and per-network
  95. // aliases) that this task spec is bound to.
  96. repeated NetworkAttachmentConfig networks = 7;
  97. // ForceUpdate is a counter that triggers an update even if no relevant
  98. // parameters have been changed. We do this to allow forced restarts
  99. // using the same reconciliation-based mechanism that performs rolling
  100. // updates.
  101. uint64 force_update = 9;
  102. }
  103. message GenericRuntimeSpec {
  104. string kind = 1;
  105. google.protobuf.Any payload = 2;
  106. }
  107. // NetworkAttachmentSpec specifies runtime parameters required to attach
  108. // a container to a network.
  109. message NetworkAttachmentSpec {
  110. // ContainerID specifies a unique ID of the container for which
  111. // this attachment is for.
  112. string container_id = 1;
  113. }
  114. // Container specifies runtime parameters for a container.
  115. message ContainerSpec {
  116. // image defines the image reference, as specified in the
  117. // distribution/reference package. This may include a registry host, name,
  118. // tag or digest.
  119. //
  120. // The field will be directly passed to the engine pulling. Well-behaved
  121. // service definitions will used immutable references, either through tags
  122. // that don't change or verifiable digests.
  123. string image = 1;
  124. // Labels defines labels to be added to the container at creation time. If
  125. // collisions with system labels occur, these labels will be overridden.
  126. //
  127. // This field *must* remain compatible with the Labels field of
  128. // Annotations.
  129. map<string, string> labels = 2;
  130. // Command to run the the container. The first element is a path to the
  131. // executable and the following elements are treated as arguments.
  132. //
  133. // If command is empty, execution will fall back to the image's entrypoint.
  134. //
  135. // Command should only be used when overriding entrypoint.
  136. repeated string command = 3;
  137. // Args specifies arguments provided to the image's entrypoint.
  138. //
  139. // If Command and Args are provided, Args will be appended to Command.
  140. repeated string args = 4;
  141. // Hostname specifies the hostname that will be set on containers created by docker swarm.
  142. // All containers for a given service will have the same hostname
  143. string hostname = 14;
  144. // Env specifies the environment variables for the container in NAME=VALUE
  145. // format. These must be compliant with [IEEE Std
  146. // 1003.1-2001](http://pubs.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap08.html).
  147. repeated string env = 5;
  148. // Dir defines the working directory to set for the container process.
  149. string dir = 6;
  150. // User specifies the user that should be employed to run the container.
  151. //
  152. // Note that the primary group may be specified by appending the group name
  153. // or id to the user name, separated by a `:`. This syntax is
  154. // `<user>:<group>`.
  155. string user = 7;
  156. // Groups specifies supplementary groups available to the user.
  157. repeated string groups = 11;
  158. // Privileges specifies security configuration/permissions.
  159. Privileges privileges = 22;
  160. // TTY declares that a TTY should be attached to the standard streams,
  161. // including stdin if it is still open.
  162. bool tty = 13 [(gogoproto.customname) = "TTY"];
  163. // OpenStdin declares that the standard input (stdin) should be open.
  164. bool open_stdin = 18;
  165. // ReadOnly declares that the container root filesystem is read-only.
  166. // This only impacts the root filesystem, not additional mounts (including
  167. // tmpfs). For additional mounts that are not part of the initial rootfs,
  168. // they will be decided by the modes passed in the mount definition.
  169. bool read_only = 19;
  170. // StopSignal defines the signal to stop the container.
  171. string stop_signal = 20;
  172. repeated Mount mounts = 8 [(gogoproto.nullable) = false];
  173. // StopGracePeriod the grace period for stopping the container before
  174. // forcefully killing the container.
  175. // Note: Can't use stdduration here because this needs to be nullable.
  176. google.protobuf.Duration stop_grace_period = 9;
  177. // PullOptions allows one to parameterize an image pull.
  178. message PullOptions {
  179. // RegistryAuth is the registry auth token obtained from the client, required
  180. // to pull private images. This is the unmodified JSON used as part of
  181. // the `X-Registry-Auth` header.
  182. // TODO(nishanttotla): This field will later be deprecated
  183. string registry_auth = 64;
  184. }
  185. // PullOptions parameterize the behavior of image pulls.
  186. PullOptions pull_options = 10;
  187. // SecretReference contains references to zero or more secrets that
  188. // will be exposed to the container.
  189. repeated SecretReference secrets = 12;
  190. // ConfigReference contains references to zero or more configs that
  191. // will be exposed to the container.
  192. repeated ConfigReference configs = 21;
  193. // Hosts allow additional entries to be specified in /etc/hosts
  194. // that associates IP addresses with hostnames.
  195. // Detailed documentation is available in:
  196. // http://man7.org/linux/man-pages/man5/hosts.5.html
  197. // IP_address canonical_hostname [aliases...]
  198. //
  199. // The format of the Hosts in swarmkit follows the same as
  200. // above.
  201. // This is different from `docker run --add-host <hostname>:<ip>`
  202. // where format is `<hostname>:<ip>`
  203. repeated string hosts = 17;
  204. // DNSConfig specifies DNS related configurations in resolver configuration file (resolv.conf)
  205. // Detailed documentation is available in:
  206. // http://man7.org/linux/man-pages/man5/resolv.conf.5.html
  207. // TODO: domain is not supported yet
  208. message DNSConfig {
  209. // Nameservers specifies the IP addresses of the name servers
  210. repeated string nameservers = 1;
  211. // Search specifies the search list for host-name lookup
  212. repeated string search = 2;
  213. // Options allows certain internal resolver variables to be modified
  214. repeated string options = 3;
  215. }
  216. // DNSConfig allows one to specify DNS related configuration in resolv.conf
  217. DNSConfig dns_config = 15 [(gogoproto.customname) = "DNSConfig"];
  218. // Healthcheck describes how to check the container is healthy. If the
  219. // container is considered unhealthy, it will be destroyed, its creating
  220. // task will exit and a new task will be rescheduled elsewhere. A container
  221. // is considered unhealthy after `Retries` number of consecutive failures.
  222. HealthConfig healthcheck = 16;
  223. }
  224. // EndpointSpec defines the properties that can be configured to
  225. // access and loadbalance the service.
  226. message EndpointSpec {
  227. // ResolutionMode specifies the mode of resolution to use for
  228. // internal loadbalancing between tasks which are all within
  229. // the cluster. This is sometimes calls east-west data path.
  230. enum ResolutionMode {
  231. option (gogoproto.goproto_enum_prefix) = false;
  232. // VIP resolution mode specifies that the
  233. // service resolves to a logical IP and the requests
  234. // are sent to that logical IP. Packets hitting that
  235. // logical IP are load balanced to a chosen backend.
  236. VIP = 0 [(gogoproto.enumvalue_customname) = "ResolutionModeVirtualIP"];
  237. // DNSRR resolution mode specifies that the
  238. // service directly gets resolved to one of the
  239. // backend IP and the client directly initiates a
  240. // request towards the actual backend. This requires
  241. // that the client does not cache the DNS responses
  242. // when the DNS response TTL is 0.
  243. DNSRR = 1 [(gogoproto.enumvalue_customname) = "ResolutionModeDNSRoundRobin"];
  244. }
  245. ResolutionMode mode = 1;
  246. // List of exposed ports that this service is accessible from
  247. // external to the cluster.
  248. repeated PortConfig ports = 2;
  249. }
  250. // NetworkSpec specifies user defined network parameters.
  251. message NetworkSpec {
  252. Annotations annotations = 1 [(gogoproto.nullable) = false];
  253. // DriverConfig specific configuration consumed by the network driver.
  254. Driver driver_config = 2;
  255. // IPv6Enabled enables support for IPv6 on the network.
  256. bool ipv6_enabled = 3;
  257. // internal restricts external access to the network. This may be
  258. // accomplished by disabling the default gateway or through other means.
  259. bool internal = 4;
  260. IPAMOptions ipam = 5 [(gogoproto.customname) = "IPAM"];
  261. // Attachable allows external(to swarm) entities to manually
  262. // attach to this network. With this flag enabled, external
  263. // entities such as containers running in an worker node in
  264. // the cluster can manually attach to this network and access
  265. // the services attached to this network. If this flag is not
  266. // enabled(default case) no manual attachment to this network
  267. // can happen.
  268. bool attachable = 6;
  269. // Ingress indicates this network will provide the routing-mesh.
  270. // In older versions, the network providing the routing mesh was
  271. // swarm internally created only and it was identified by the name
  272. // "ingress" and the label "com.docker.swarm.internal": "true".
  273. bool ingress = 7;
  274. // ConfigFrom is the source of the configuration for this network.
  275. oneof config_from {
  276. // Network is the name of a network that provides the network
  277. // specific configuration for this network, locally on the node
  278. // where this network is being plumbed.
  279. string network = 8;
  280. }
  281. }
  282. // ClusterSpec specifies global cluster settings.
  283. message ClusterSpec {
  284. Annotations annotations = 1 [(gogoproto.nullable) = false];
  285. // DEPRECATED: AcceptancePolicy defines the certificate issuance policy.
  286. // Acceptance policy is no longer customizable, and secrets have been
  287. // replaced with join tokens.
  288. AcceptancePolicy acceptance_policy = 2 [deprecated=true, (gogoproto.nullable) = false];
  289. // Orchestration defines cluster-level orchestration settings.
  290. OrchestrationConfig orchestration = 3 [(gogoproto.nullable) = false];
  291. // Raft defines the cluster's raft settings.
  292. RaftConfig raft = 4 [(gogoproto.nullable) = false];
  293. // Dispatcher defines cluster-level dispatcher settings.
  294. DispatcherConfig dispatcher = 5 [(gogoproto.nullable) = false];
  295. // CAConfig defines cluster-level certificate authority settings.
  296. CAConfig ca_config = 6 [(gogoproto.nullable) = false, (gogoproto.customname) = "CAConfig"];
  297. // TaskDefaults specifies the default values to use for task creation.
  298. TaskDefaults task_defaults = 7 [(gogoproto.nullable) = false];
  299. // EncryptionConfig defines the cluster's encryption settings.
  300. EncryptionConfig encryption_config = 8 [(gogoproto.nullable) = false];
  301. }
  302. // SecretSpec specifies a user-provided secret.
  303. message SecretSpec {
  304. Annotations annotations = 1 [(gogoproto.nullable) = false];
  305. // Data is the secret payload - the maximum size is 500KB (that is, 500*1024 bytes)
  306. bytes data = 2;
  307. }
  308. // ConfigSpec specifies user-provided configuration files.
  309. message ConfigSpec {
  310. Annotations annotations = 1 [(gogoproto.nullable) = false];
  311. // Data is the config payload - the maximum size is 500KB (that is, 500*1024 bytes)
  312. // TODO(aaronl): Do we want to revise this to include multiple payloads in a single
  313. // ConfigSpec? Define this to be a tar? etc...
  314. bytes data = 2;
  315. }