123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399 |
- syntax = "proto3";
- package docker.swarmkit.v1;
- import "types.proto";
- import "gogoproto/gogo.proto";
- import "google/protobuf/duration.proto";
- import "google/protobuf/any.proto";
- // Specs are container objects for user provided input. All creations and
- // updates are done through spec types. As a convention, user input from a spec
- // is never touched in created objects. This allows one to verify that the
- // users intent has not been modified.
- //
- // Put differently, spec types can be said to represent the desired state of
- // the system. In situations where modifications need to be made to a
- // particular component, API objects will either contain a copy of the spec
- // component or a different representation to reflect allocation or resolution.
- message NodeSpec {
- Annotations annotations = 1 [(gogoproto.nullable) = false];
- enum Membership {
- option (gogoproto.goproto_enum_prefix) = false;
- PENDING = 0 [(gogoproto.enumvalue_customname) = "NodeMembershipPending"];
- ACCEPTED = 1 [(gogoproto.enumvalue_customname) = "NodeMembershipAccepted"];
- }
- enum Availability {
- option (gogoproto.goproto_enum_prefix) = false;
- // Active nodes.
- ACTIVE = 0 [(gogoproto.enumvalue_customname) = "NodeAvailabilityActive"];
- // Paused nodes won't be considered by the scheduler, preventing any
- // further task to run on them.
- PAUSE = 1 [(gogoproto.enumvalue_customname) = "NodeAvailabilityPause"];
- // Drained nodes are paused and any task already running on them will
- // be evicted.
- DRAIN = 2 [(gogoproto.enumvalue_customname) = "NodeAvailabilityDrain"];
- }
- // DesiredRole defines the role the node should have.
- NodeRole desired_role = 2;
- // Membership controls the admission of the node into the cluster.
- Membership membership = 3;
- // Availability allows a user to control the current scheduling status of a
- // node.
- Availability availability = 4;
- }
- // ServiceSpec defines the properties of a service.
- //
- // A service instructs the cluster in orchestrating repeated instances of a
- // template, implemented as tasks. Based on the number of instances, scheduling
- // strategy and restart policy, a number of application-level behaviors can be
- // defined.
- message ServiceSpec {
- Annotations annotations = 1 [(gogoproto.nullable) = false];
- // Task defines the task template this service will spawn.
- TaskSpec task = 2 [(gogoproto.nullable) = false];
- oneof mode {
- ReplicatedService replicated = 3;
- GlobalService global = 4;
- }
- // Update contains settings which affect updates.
- UpdateConfig update = 6;
- // Rollback contains settings which affect rollbacks of updates.
- UpdateConfig rollback = 9;
- // ServiceSpec.Networks has been deprecated and is replaced by
- // Networks field in Task (TaskSpec.Networks).
- // This field (ServiceSpec.Networks) is kept for compatibility.
- // In case TaskSpec.Networks does not exist, ServiceSpec.Networks
- // is still honored if it exists.
- repeated NetworkAttachmentConfig networks = 7 [deprecated=true];
- // Service endpoint specifies the user provided configuration
- // to properly discover and load balance a service.
- EndpointSpec endpoint = 8;
- }
- // ReplicatedService sets the reconciliation target to certain number of replicas.
- message ReplicatedService {
- uint64 replicas = 1;
- }
- // GlobalService represents global service.
- message GlobalService {
- // Empty message for now.
- }
- message TaskSpec {
- oneof runtime {
- NetworkAttachmentSpec attachment = 8;
- ContainerSpec container = 1;
- GenericRuntimeSpec generic = 10;
- }
- // Resource requirements for the container.
- ResourceRequirements resources = 2;
- // RestartPolicy specifies what to do when a task fails or finishes.
- RestartPolicy restart = 4;
- // Placement specifies node selection constraints
- Placement placement = 5;
- // LogDriver specifies the log driver to use for the task. Any runtime will
- // direct logs into the specified driver for the duration of the task.
- Driver log_driver = 6;
- // Networks specifies the list of network attachment
- // configurations (which specify the network and per-network
- // aliases) that this task spec is bound to.
- repeated NetworkAttachmentConfig networks = 7;
- // ForceUpdate is a counter that triggers an update even if no relevant
- // parameters have been changed. We do this to allow forced restarts
- // using the same reconciliation-based mechanism that performs rolling
- // updates.
- uint64 force_update = 9;
- }
- message GenericRuntimeSpec {
- string kind = 1;
- google.protobuf.Any payload = 2;
- }
- // NetworkAttachmentSpec specifies runtime parameters required to attach
- // a container to a network.
- message NetworkAttachmentSpec {
- // ContainerID specifies a unique ID of the container for which
- // this attachment is for.
- string container_id = 1;
- }
- // Container specifies runtime parameters for a container.
- message ContainerSpec {
- // image defines the image reference, as specified in the
- // distribution/reference package. This may include a registry host, name,
- // tag or digest.
- //
- // The field will be directly passed to the engine pulling. Well-behaved
- // service definitions will used immutable references, either through tags
- // that don't change or verifiable digests.
- string image = 1;
- // Labels defines labels to be added to the container at creation time. If
- // collisions with system labels occur, these labels will be overridden.
- //
- // This field *must* remain compatible with the Labels field of
- // Annotations.
- map<string, string> labels = 2;
- // Command to run the the container. The first element is a path to the
- // executable and the following elements are treated as arguments.
- //
- // If command is empty, execution will fall back to the image's entrypoint.
- //
- // Command should only be used when overriding entrypoint.
- repeated string command = 3;
- // Args specifies arguments provided to the image's entrypoint.
- //
- // If Command and Args are provided, Args will be appended to Command.
- repeated string args = 4;
- // Hostname specifies the hostname that will be set on containers created by docker swarm.
- // All containers for a given service will have the same hostname
- string hostname = 14;
- // Env specifies the environment variables for the container in NAME=VALUE
- // format. These must be compliant with [IEEE Std
- // 1003.1-2001](http://pubs.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap08.html).
- repeated string env = 5;
- // Dir defines the working directory to set for the container process.
- string dir = 6;
- // User specifies the user that should be employed to run the container.
- //
- // Note that the primary group may be specified by appending the group name
- // or id to the user name, separated by a `:`. This syntax is
- // `<user>:<group>`.
- string user = 7;
- // Groups specifies supplementary groups available to the user.
- repeated string groups = 11;
- // Privileges specifies security configuration/permissions.
- Privileges privileges = 22;
- // TTY declares that a TTY should be attached to the standard streams,
- // including stdin if it is still open.
- bool tty = 13 [(gogoproto.customname) = "TTY"];
- // OpenStdin declares that the standard input (stdin) should be open.
- bool open_stdin = 18;
- // ReadOnly declares that the container root filesystem is read-only.
- // This only impacts the root filesystem, not additional mounts (including
- // tmpfs). For additional mounts that are not part of the initial rootfs,
- // they will be decided by the modes passed in the mount definition.
- bool read_only = 19;
- // StopSignal defines the signal to stop the container.
- string stop_signal = 20;
- repeated Mount mounts = 8 [(gogoproto.nullable) = false];
- // StopGracePeriod the grace period for stopping the container before
- // forcefully killing the container.
- // Note: Can't use stdduration here because this needs to be nullable.
- google.protobuf.Duration stop_grace_period = 9;
- // PullOptions allows one to parameterize an image pull.
- message PullOptions {
- // RegistryAuth is the registry auth token obtained from the client, required
- // to pull private images. This is the unmodified JSON used as part of
- // the `X-Registry-Auth` header.
- // TODO(nishanttotla): This field will later be deprecated
- string registry_auth = 64;
- }
- // PullOptions parameterize the behavior of image pulls.
- PullOptions pull_options = 10;
- // SecretReference contains references to zero or more secrets that
- // will be exposed to the container.
- repeated SecretReference secrets = 12;
- // ConfigReference contains references to zero or more configs that
- // will be exposed to the container.
- repeated ConfigReference configs = 21;
- // Hosts allow additional entries to be specified in /etc/hosts
- // that associates IP addresses with hostnames.
- // Detailed documentation is available in:
- // http://man7.org/linux/man-pages/man5/hosts.5.html
- // IP_address canonical_hostname [aliases...]
- //
- // The format of the Hosts in swarmkit follows the same as
- // above.
- // This is different from `docker run --add-host <hostname>:<ip>`
- // where format is `<hostname>:<ip>`
- repeated string hosts = 17;
- // DNSConfig specifies DNS related configurations in resolver configuration file (resolv.conf)
- // Detailed documentation is available in:
- // http://man7.org/linux/man-pages/man5/resolv.conf.5.html
- // TODO: domain is not supported yet
- message DNSConfig {
- // Nameservers specifies the IP addresses of the name servers
- repeated string nameservers = 1;
- // Search specifies the search list for host-name lookup
- repeated string search = 2;
- // Options allows certain internal resolver variables to be modified
- repeated string options = 3;
- }
- // DNSConfig allows one to specify DNS related configuration in resolv.conf
- DNSConfig dns_config = 15 [(gogoproto.customname) = "DNSConfig"];
- // Healthcheck describes how to check the container is healthy. If the
- // container is considered unhealthy, it will be destroyed, its creating
- // task will exit and a new task will be rescheduled elsewhere. A container
- // is considered unhealthy after `Retries` number of consecutive failures.
- HealthConfig healthcheck = 16;
- }
- // EndpointSpec defines the properties that can be configured to
- // access and loadbalance the service.
- message EndpointSpec {
- // ResolutionMode specifies the mode of resolution to use for
- // internal loadbalancing between tasks which are all within
- // the cluster. This is sometimes calls east-west data path.
- enum ResolutionMode {
- option (gogoproto.goproto_enum_prefix) = false;
- // VIP resolution mode specifies that the
- // service resolves to a logical IP and the requests
- // are sent to that logical IP. Packets hitting that
- // logical IP are load balanced to a chosen backend.
- VIP = 0 [(gogoproto.enumvalue_customname) = "ResolutionModeVirtualIP"];
- // DNSRR resolution mode specifies that the
- // service directly gets resolved to one of the
- // backend IP and the client directly initiates a
- // request towards the actual backend. This requires
- // that the client does not cache the DNS responses
- // when the DNS response TTL is 0.
- DNSRR = 1 [(gogoproto.enumvalue_customname) = "ResolutionModeDNSRoundRobin"];
- }
- ResolutionMode mode = 1;
- // List of exposed ports that this service is accessible from
- // external to the cluster.
- repeated PortConfig ports = 2;
- }
- // NetworkSpec specifies user defined network parameters.
- message NetworkSpec {
- Annotations annotations = 1 [(gogoproto.nullable) = false];
- // DriverConfig specific configuration consumed by the network driver.
- Driver driver_config = 2;
- // IPv6Enabled enables support for IPv6 on the network.
- bool ipv6_enabled = 3;
- // internal restricts external access to the network. This may be
- // accomplished by disabling the default gateway or through other means.
- bool internal = 4;
- IPAMOptions ipam = 5 [(gogoproto.customname) = "IPAM"];
- // Attachable allows external(to swarm) entities to manually
- // attach to this network. With this flag enabled, external
- // entities such as containers running in an worker node in
- // the cluster can manually attach to this network and access
- // the services attached to this network. If this flag is not
- // enabled(default case) no manual attachment to this network
- // can happen.
- bool attachable = 6;
- // Ingress indicates this network will provide the routing-mesh.
- // In older versions, the network providing the routing mesh was
- // swarm internally created only and it was identified by the name
- // "ingress" and the label "com.docker.swarm.internal": "true".
- bool ingress = 7;
- // ConfigFrom is the source of the configuration for this network.
- oneof config_from {
- // Network is the name of a network that provides the network
- // specific configuration for this network, locally on the node
- // where this network is being plumbed.
- string network = 8;
- }
- }
- // ClusterSpec specifies global cluster settings.
- message ClusterSpec {
- Annotations annotations = 1 [(gogoproto.nullable) = false];
- // DEPRECATED: AcceptancePolicy defines the certificate issuance policy.
- // Acceptance policy is no longer customizable, and secrets have been
- // replaced with join tokens.
- AcceptancePolicy acceptance_policy = 2 [deprecated=true, (gogoproto.nullable) = false];
- // Orchestration defines cluster-level orchestration settings.
- OrchestrationConfig orchestration = 3 [(gogoproto.nullable) = false];
- // Raft defines the cluster's raft settings.
- RaftConfig raft = 4 [(gogoproto.nullable) = false];
- // Dispatcher defines cluster-level dispatcher settings.
- DispatcherConfig dispatcher = 5 [(gogoproto.nullable) = false];
- // CAConfig defines cluster-level certificate authority settings.
- CAConfig ca_config = 6 [(gogoproto.nullable) = false, (gogoproto.customname) = "CAConfig"];
- // TaskDefaults specifies the default values to use for task creation.
- TaskDefaults task_defaults = 7 [(gogoproto.nullable) = false];
- // EncryptionConfig defines the cluster's encryption settings.
- EncryptionConfig encryption_config = 8 [(gogoproto.nullable) = false];
- }
- // SecretSpec specifies a user-provided secret.
- message SecretSpec {
- Annotations annotations = 1 [(gogoproto.nullable) = false];
- // Data is the secret payload - the maximum size is 500KB (that is, 500*1024 bytes)
- bytes data = 2;
- }
- // ConfigSpec specifies user-provided configuration files.
- message ConfigSpec {
- Annotations annotations = 1 [(gogoproto.nullable) = false];
- // Data is the config payload - the maximum size is 500KB (that is, 500*1024 bytes)
- // TODO(aaronl): Do we want to revise this to include multiple payloads in a single
- // ConfigSpec? Define this to be a tar? etc...
- bytes data = 2;
- }
|