docker/swarmkit

syntax = "proto3";

package docker.swarmkit.v1;

import "github.com/docker/swarmkit/api/types.proto";
import "gogoproto/gogo.proto";
import "google/protobuf/duration.proto";
import "google/protobuf/any.proto";
import "google/protobuf/wrappers.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;
        ReplicatedJob replicated_job = 10;
        GlobalJob global_job = 11;
    }

    // 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.
}

// ReplicatedJob is a certain type of one-off job which executes many Tasks in
// parallel until the specified number of Tasks have succeeded.
message ReplicatedJob {
    // MaxConcurrent indicates the maximum number of Tasks that should be
    // executing simultaneously at any given time.
    uint64 max_concurrent = 1;

    // TotalCompletions sets the total number of Tasks desired to run to
    // completion. This is also the absolute maximum number of Tasks that will
    // be executed in parallel. That is, if this number is smaller than
    // MaxConcurrent, only this many replicas will run.
    uint64 total_completions = 2;
}

// GlobalJob is a type of one-off job which executes one Task on every node
// matching the service's placement constraints.
message GlobalJob {
    // 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;

    // ResourceReferences provides a generic way to specify resources that
    // are used by this task, and should be sent down to agents along with
    // the task. Inside the runtime field there may be more specific
    // information about how to use the resource, but ResourceReferences
    // establishes the relationship at the store level, and instructs the
    // dispatcher to send the related objects.
    //
    // ResourceReferences is a list of ResourceReferences used by the task.
    repeated ResourceReference resource_references = 11 [(gogoproto.nullable) = false];
}

message ResourceReference {
    string resource_id = 1;
    ResourceType resource_type = 2;
}

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;

    // Init declares that a custom init will be running inside the container, if null, use the daemon's configured settings
    google.protobuf.BoolValue init = 23;

    // 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;

    enum Isolation {
        option (gogoproto.goproto_enum_prefix) = false;

        // ISOLATION_DEFAULT uses whatever default value from the container runtime
        ISOLATION_DEFAULT = 0 [(gogoproto.enumvalue_customname) = "ContainerIsolationDefault"];

        // ISOLATION_PROCESS forces windows container isolation
        ISOLATION_PROCESS = 1 [(gogoproto.enumvalue_customname) = "ContainerIsolationProcess"];

        // ISOLATION_HYPERV forces Hyper-V isolation
        ISOLATION_HYPERV = 2 [(gogoproto.enumvalue_customname) = "ContainerIsolationHyperV"];
    }

    // Isolation defines the isolation level for windows containers (default, process, hyperv).
    // Runtimes that don't support it ignore that field
    Isolation isolation = 24;

    // PidsLimit prevents from OS resource damage by applications inside the container
    // using fork bomb attack.
    int64 pidsLimit = 25;

    // Sysctls sets namespaced kernel parameters (sysctls) in the container. This
    // option is equivalent to passing --sysctl to docker run.
    //
    // Note that while options are subject to the same restrictions as arguments
    // passed to the --sysctl flag on docker run, those options are not further
    // validated to ensure that they are safe or sensible in a clustered
    // environment.
    //
    // Additionally, sysctls are not validated for support in the underlying
    // daemon. For information about supported options, refer to the
    // documentation at:
    //
    // https://docs.docker.com/engine/reference/commandline/run/#configure-namespaced-kernel-parameters-sysctls-at-runtime
    map<string, string> sysctls = 26;

    // CapabilityAdd sets the list of capabilities to add to the default capability list
    repeated string capability_add = 27;
    // CapabilityDrop sets the list of capabilities to drop from the default capability list
    repeated string capability_drop = 28;

    message Ulimit {
        string name = 1;
        int64 soft = 2;
        int64 hard = 3;
    }

    // Ulimits defines the list of ulimits to set in the container. This option
    // is equivalent to passing --ulimit to docker run.
    repeated Ulimit ulimits = 29;
}

// 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;

    // Templating controls whether and how to evaluate the secret payload as
    // a template. If it is not set, no templating is used.
    //
    // The currently recognized values are:
    // - golang: Go templating
    Driver templating = 3;

    // Driver is the the secret driver that is used to store the specified secret
    Driver driver = 4;
}

// 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;

    // Templating controls whether and how to evaluate the secret payload as
    // a template. If it is not set, no templating is used.
    //
    // The currently recognized values are:
    // - golang: Go templating
    Driver templating = 3;
}

message VolumeSpec {
    // Annotations includes the name and labels of a volume. The name used in the
    // spec's Annotations will be passed to the Plugin as the "Name" in the
    // CreateVolume request.
    Annotations annotations = 1 [(gogoproto.nullable) = false];

    // Group defines the volume group this particular volume belongs to. When
    // requesting volumes for a workload, the group name can be used instead of
    // the volume's name, which tells swarmkit to pick one from the many volumes
    // belonging to that group.
    string group = 2;

    // Driver represents the CSI Plugin object and its configuration parameters.
    // The "options" field of the Driver object is passed in the CSI
    // CreateVolumeRequest as the "parameters" field. The Driver must be
    // specified; there is no default CSI Plugin.
    Driver driver = 3;

    // AccessMode is similar to, and used to determine, the volume access mode as
    // defined in the CSI spec, as well as the volume type (block vs mount). In
    // this way, it is more similar to the VolumeCapability message in the CSI
    // spec.
    VolumeAccessMode access_mode = 4;

    // Secrets represents a set of key/value pairs to pass to the CSI plugin. The
    // keys of the secrets can be anything, but the values refer to swarmkit
    // Secret objects. See the "Secrets Requirements" section of the CSI Plugin
    // Spec for more information.
    repeated VolumeSecret secrets = 5;

    // AccessibilityRequirements specifies where a volume must be accessible
    // from.
    //
    // This field must be empty if the plugin does not support
    // VOLUME_ACCESSIBILITY_CONSTRAINTS capabilities. If it is present but the
    // plugin does not support it, volume will not be created.
    //
    // If AccessibilityRequirements is empty, but the plugin does support
    // VOLUME_ACCESSIBILITY_CONSTRAINTS, then Swarmkit will assume the entire
    // cluster is a valid target for the volume.
    TopologyRequirement AccessibilityRequirements = 6;

    // CapacityRange is the capacity this volume should be created with. If nil,
    // the plugin will decide the capacity.
    CapacityRange capacity_range = 7;

    enum VolumeAvailability {
        option (gogoproto.goproto_enum_prefix) = false;

        // Active allows a volume to be used and scheduled to. This is the
        // default state.
        ACTIVE = 0 [(gogoproto.enumvalue_customname) = "VolumeAvailabilityActive"];

        // Pause prevents volumes from having new workloads scheduled to use
        // them, even if they're already published on a Node.
        PAUSE = 1 [(gogoproto.enumvalue_customname) = "VolumeAvailabilityPause"];

        // Drain causes existing workloads using this volume to be rescheduled,
        // causing the volume to be unpublished and removed from nodes.
        DRAIN = 2 [(gogoproto.enumvalue_customname) = "VolumeAvailabilityDrain"];
    }

    // Availability is the Volume's desired availability. Analogous to Node
    // Availability, this allows the user to take volumes offline in order to
    // update or delete them.
    VolumeAvailability availability = 8;
}