types.proto

syntax = "proto3";

package docker.swarmkit.v1;

import "google/protobuf/timestamp.proto";
import "google/protobuf/duration.proto";
import "google/protobuf/wrappers.proto";
import "gogoproto/gogo.proto";

// This file contains types that are common to objects and spec or that are not
// considered first-class within the cluster object-model.

// Version tracks the last time an object in the store was updated.
message Version {
	uint64 index = 1;
}

message IndexEntry {
	string key = 1;
	string val = 2;
}

// Annotations provide useful information to identify API objects. They are
// common to all API specs.
message Annotations {
	string name = 1;
	map<string, string> labels = 2;

	// Indices provides keys and values for indexing this object.
	// A single key may have multiple values.
	repeated IndexEntry indices = 4 [(gogoproto.nullable) = false];
}

// NamedGenericResource represents a "user defined" resource which is defined
// as a string.
// "Kind" is used to describe the Kind of a resource (e.g: "GPU", "FPGA", "SSD", ...)
// Value is used to identify the resource (GPU="UUID-1", FPGA="/dev/sdb5", ...)
message NamedGenericResource {
	string kind = 1;
	string value = 2;
}

// DiscreteGenericResource represents a "user defined" resource which is defined
// as an integer
// "Kind" is used to describe the Kind of a resource (e.g: "GPU", "FPGA", "SSD", ...)
// Value is used to count the resource (SSD=5, HDD=3, ...)
message DiscreteGenericResource {
	string kind = 1;
	int64 value = 2;
}

// GenericResource represents a "user defined" resource which can
// be either an integer (e.g: SSD=3) or a string (e.g: SSD=sda1)
message GenericResource {
	oneof resource {
		NamedGenericResource named_resource_spec = 1;
		DiscreteGenericResource discrete_resource_spec = 2;
	}
}

enum ResourceType {
	TASK = 0;
	SECRET = 1;
	CONFIG = 2;
	VOLUME = 3;
}

message Resources {
	// Amount of CPUs (e.g. 2000000000 = 2 CPU cores)
	int64 nano_cpus = 1 [(gogoproto.customname) = "NanoCPUs"];

	// Amount of memory in bytes.
	int64 memory_bytes = 2;

	// User specified resource (e.g: bananas=2;apple={red,yellow,green})
	repeated GenericResource generic = 3;
}

message ResourceRequirements {
	Resources limits = 1;
	Resources reservations = 2;

	// Amount of swap in bytes - can only be used together with a memory limit
	// -1 means unlimited
	// a null pointer indicates that the default behaviour of granting twice
	// the memory is maintained
	google.protobuf.Int64Value swap_bytes = 3;

	// Tune container memory swappiness (0 to 100) - if not specified, defaults
	// to the container OS's default - generally 60, or the value predefined in
	// the image; set to -1 to unset a previously set value
	google.protobuf.Int64Value memory_swappiness = 4;
}

message Platform {
	// Architecture (e.g. x86_64)
	string architecture = 1;

	// Operating System (e.g. linux)
	string os = 2 [(gogoproto.customname) = "OS"];
}

// PluginDescription describes an engine plugin.
message PluginDescription {
	// Type of plugin. Canonical values for existing types are
	// Volume, Network, and Authorization. More types could be
	// supported in the future.
	string type = 1;

	// Name of the plugin
	string name = 2;
}

message EngineDescription {
	// Docker daemon version running on the node.
	string engine_version = 1;

	// Labels attached to the engine.
	map<string, string> labels = 2;

	// Volume, Network, and Auth plugins
	repeated PluginDescription plugins = 3 [(gogoproto.nullable) = false];
}

message NodeDescription {
	// Hostname of the node as reported by the agent.
	// This is different from spec.meta.name which is user-defined.
	string hostname = 1;

	// Platform of the node.
	Platform platform = 2;

	// Total resources on the node.
	Resources resources = 3;

	// Information about the Docker Engine on the node.
	EngineDescription engine = 4;

	// Information on the node's TLS setup
	NodeTLSInfo tls_info = 5 [(gogoproto.customname) = "TLSInfo"];

	// FIPS indicates whether the node has FIPS-enabled
	bool fips = 6 [(gogoproto.customname) = "FIPS"];

	repeated NodeCSIInfo csi_info = 7 [(gogoproto.customname) = "CSIInfo"];
}

message NodeTLSInfo {
	// Information about which root certs the node trusts
	bytes trust_root = 1;

	// Information about the node's current TLS certificate
	bytes cert_issuer_subject = 2;
	bytes cert_issuer_public_key = 3;
}

// NodeCSIInfo represents information about a Node returned by calling the
// NodeGetInfo RPC on the CSI plugin present on the node. There is a separate
// NodeCSIInfo object for each CSI plugin present.
message NodeCSIInfo {

	// PluginName is the name of the CSI plugin.
	string plugin_name = 1;

	// NodeID is the ID of the node as reported by the CSI plugin. This will be
	// different from the swarmkit node ID.
	string node_id = 2;

	// MaxVolumesPerNode is the maximum number of volumes that may be published
	// to this node.
	int64 max_volumes_per_node = 3;

	// AccessibleTopology indicates the location of this node in the CSI plugin's
	// topology
	Topology accessible_topology = 4;
}

message RaftMemberStatus {
	bool leader = 1;

	enum Reachability {
		// Unknown indicates that the manager state cannot be resolved
		UNKNOWN = 0;

		// Unreachable indicates that the node cannot be contacted by other
		// raft cluster members.
		UNREACHABLE = 1;

		// Reachable indicates that the node is healthy and reachable
		// by other members.
		REACHABLE = 2;
	}

	Reachability reachability = 2;
	string message = 3;
}

message NodeStatus {
	// TODO(aluzzardi) These should be using `gogoproto.enumvalue_customname`.
	enum State {
		// Unknown indicates the node state cannot be resolved.
		UNKNOWN = 0;

		// Down indicates the node is down.
		DOWN = 1;

		// Ready indicates the node is ready to accept tasks.
		READY = 2;

		// Disconnected indicates the node is currently trying to find new manager.
		DISCONNECTED = 3;
	}

	State state = 1;
	string message = 2;
	// Addr is the node's IP address as observed by the manager
	string addr = 3;
}

message Image {
	// reference is a docker image reference. This can include a rpository, tag
	// or be fully qualified witha digest. The format is specified in the
	// distribution/reference package.
	string reference = 1;
}

// Mount describes volume mounts for a container.
//
// The Mount type follows the structure of the mount syscall, including a type,
// source, target. Top-level flags, such as writable, are common to all kinds
// of mounts, where we also provide options that are specific to a type of
// mount. This corresponds to flags and data, respectively, in the syscall.
message Mount {
	enum Type {
		option (gogoproto.goproto_enum_prefix) = false;
		option (gogoproto.enum_customname) = "MountType";

		BIND = 0 [(gogoproto.enumvalue_customname) = "MountTypeBind"]; // Bind mount host dir
		VOLUME = 1 [(gogoproto.enumvalue_customname) = "MountTypeVolume"];  // Remote storage volumes
		TMPFS = 2 [(gogoproto.enumvalue_customname) = "MountTypeTmpfs"]; // Mount a tmpfs
		NPIPE = 3 [(gogoproto.enumvalue_customname) = "MountTypeNamedPipe"]; // Windows named pipes
		CLUSTER = 4 [(gogoproto.enumvalue_customname) = "MountTypeCluster"]; // CSI volume
	}

	// Type defines the nature of the mount.
	Type type = 1;

	// Source specifies the name of the mount. Depending on mount type, this
	// may be a volume name or a host path, or even ignored.
	//
	// For CSI type mounts, the source is either the name of the volume or the
	// name of the volume group. To specify a volume group, the source should be
	// prefixed with "group:", as in "group:groupname"
	string source = 2;

	// Target path in container
	string target = 3;

	// ReadOnly should be set to true if the mount should not be writable.
	bool readonly = 4 [(gogoproto.customname) = "ReadOnly"];

	// Consistency indicates the tolerable level of file system consistency
	enum Consistency {
		option (gogoproto.goproto_enum_prefix) = false;
		option (gogoproto.enum_customname) = "MountConsistency";

		DEFAULT = 0 [(gogoproto.enumvalue_customname) = "MountConsistencyDefault"];
		CONSISTENT = 1 [(gogoproto.enumvalue_customname) = "MountConsistencyFull"];
		CACHED = 2 [(gogoproto.enumvalue_customname) = "MountConsistencyCached"];
		DELEGATED = 3 [(gogoproto.enumvalue_customname) = "MountConsistencyDelegated"];
	}
	Consistency consistency = 8;

	// BindOptions specifies options that are specific to a bind mount.
	message BindOptions {
		enum Propagation {
			option (gogoproto.goproto_enum_prefix) = false;
			option (gogoproto.enum_customname) = "MountPropagation";

			RPRIVATE = 0 [(gogoproto.enumvalue_customname) = "MountPropagationRPrivate"];
			PRIVATE = 1 [(gogoproto.enumvalue_customname) = "MountPropagationPrivate"];
			RSHARED = 2 [(gogoproto.enumvalue_customname) = "MountPropagationRShared"];
			SHARED = 3 [(gogoproto.enumvalue_customname) = "MountPropagationShared"];
			RSLAVE = 4 [(gogoproto.enumvalue_customname) = "MountPropagationRSlave"];
			SLAVE = 5 [(gogoproto.enumvalue_customname) = "MountPropagationSlave"];
		}

		// Propagation mode of mount.
		Propagation propagation = 1;
		// allows non-recursive bind-mount, i.e. mount(2) with "bind" rather than "rbind".
		bool nonrecursive = 2 [(gogoproto.customname) = "NonRecursive"];
		// Create the mount point
		bool createmountpoint = 3 [(gogoproto.customname) = "CreateMountpoint"];
		// ReadOnlyNonRecursive makes the mount non-recursively read-only, but still leaves the mount recursive
		// (unless NonRecursive is set to true in conjunction).
		bool readonlynonrecursive = 4 [(gogoproto.customname) = "ReadOnlyNonRecursive"];
		// ReadOnlyForceRecursive raises an error if the mount cannot be made recursively read-only.
		bool readonlyforcerecursive = 5 [(gogoproto.customname) = "ReadOnlyForceRecursive"];
	}

	// VolumeOptions contains parameters for mounting the volume.
	message VolumeOptions {
		// nocopy prevents automatic copying of data to the volume with data from target
		bool nocopy = 1 [(gogoproto.customname) = "NoCopy"];

		// labels to apply to the volume if creating
		map<string, string> labels = 2;

		// DriverConfig specifies the options that may be passed to the driver
		// if the volume is created.
		//
		// If this is empty, no volume will be created if the volume is missing.
		Driver driver_config = 3;

		// subpath inside the volume to mount.
		string subpath = 4 [(gogoproto.customname) = "Subpath"];
	}

	message TmpfsOptions {
		// Size sets the size of the tmpfs, in bytes.
		//
		// This will be converted to an operating system specific value
		// depending on the host. For example, on linux, it will be convered to
		// use a 'k', 'm' or 'g' syntax. BSD, though not widely supported with
		// docker, uses a straight byte value.
		//
		// Percentages are not supported.
		int64 size_bytes = 1;

		// Mode of the tmpfs upon creation
		uint32 mode = 2 [(gogoproto.customtype) = "os.FileMode", (gogoproto.nullable) = false];

		// Options passed to tmpfs mount
		string options = 3;
		// TODO(stevvooe): There are several more tmpfs flags, specified in the
		// daemon, that are accepted. Only the most basic are added for now.
		//
		// From docker/docker/pkg/mount/flags.go:
		//
		// var validFlags = map[string]bool{
		// 	"":          true,
		// 	"size":      true, X
		// 	"mode":      true, X
		// 	"uid":       true,
		// 	"gid":       true,
		// 	"nr_inodes": true,
		// 	"nr_blocks": true,
		// 	"mpol":      true,
		// }
		//
		// Some of these may be straightforward to add, but others, such as
		// uid/gid have implications in a clustered system.
	}

	// Depending on type, one of bind_options or volumes_options will be set.

	// BindOptions configures properties of a bind mount type.
	//
	// For mounts of type bind, the source must be an absolute host path.
	BindOptions bind_options = 5;

	// VolumeOptions configures the properties specific to a volume mount type.
	//
	// For mounts of type volume, the source will be used as the volume name.
	VolumeOptions volume_options = 6;

	// TmpfsOptions allows one to set options for mounting a temporary
	// filesystem.
	//
	// The source field will be ignored when using mounts of type tmpfs.
	TmpfsOptions tmpfs_options = 7;

	// TODO(stevvooe): It be better to use a oneof field above, although the
	// type is enough to make the decision, while being primary to the
	// datastructure.
}

message RestartPolicy {
	enum RestartCondition {
		option (gogoproto.goproto_enum_prefix) = false;
		option (gogoproto.enum_customname) = "RestartCondition";
		NONE = 0 [(gogoproto.enumvalue_customname) = "RestartOnNone"];
		ON_FAILURE = 1 [(gogoproto.enumvalue_customname) = "RestartOnFailure"];
		ANY = 2 [(gogoproto.enumvalue_customname) = "RestartOnAny"];
	}

	RestartCondition condition = 1;

	// Delay between restart attempts
	// Note: can't use stdduration because this field needs to be nullable.
	google.protobuf.Duration delay = 2;

	// MaxAttempts is the maximum number of restarts to attempt on an
	// instance before giving up. Ignored if 0.
	uint64 max_attempts = 3;

	// Window is the time window used to evaluate the restart policy.
	// The time window is unbounded if this is 0.
	// Note: can't use stdduration because this field needs to be nullable.
	google.protobuf.Duration window = 4;
}

// UpdateConfig specifies the rate and policy of updates.
// TODO(aluzzardi): Consider making this a oneof with RollingStrategy and LockstepStrategy.
message UpdateConfig {
	// Maximum number of tasks to be updated in one iteration.
	// 0 means unlimited parallelism.
	uint64 parallelism = 1;

	// Amount of time between updates.
	google.protobuf.Duration delay = 2 [(gogoproto.stdduration) = true, (gogoproto.nullable) = false];

	enum FailureAction {
		PAUSE = 0;
		CONTINUE = 1;
		ROLLBACK = 2;
	}

	// FailureAction is the action to take when an update failures.
	FailureAction failure_action = 3;

	// Monitor indicates how long to monitor a task for failure after it is
	// created. If the task fails by ending up in one of the states
	// REJECTED, COMPLETED, or FAILED, within Monitor from its creation,
	// this counts as a failure. If it fails after Monitor, it does not
	// count as a failure. If Monitor is unspecified, a default value will
	// be used.
	// Note: can't use stdduration because this field needs to be nullable.
	google.protobuf.Duration monitor = 4;

	// MaxFailureRatio is the fraction of tasks that may fail during
	// an update before the failure action is invoked. Any task created by
	// the current update which ends up in one of the states REJECTED,
	// COMPLETED or FAILED within Monitor from its creation counts as a
	// failure. The number of failures is divided by the number of tasks
	// being updated, and if this fraction is greater than
	// MaxFailureRatio, the failure action is invoked.
	//
	// If the failure action is CONTINUE, there is no effect.
	// If the failure action is PAUSE, no more tasks will be updated until
	// another update is started.
	// If the failure action is ROLLBACK, the orchestrator will attempt to
	// roll back to the previous service spec. If the MaxFailureRatio
	// threshold is hit during the rollback, the rollback will pause.
	float max_failure_ratio = 5;

	// UpdateOrder controls the order of operations when rolling out an
	// updated task. Either the old task is shut down before the new task
	// is started, or the new task is started before the old task is shut
	// down.
	enum UpdateOrder {
		STOP_FIRST = 0;
		START_FIRST = 1;
	}

	UpdateOrder order = 6;
}

// UpdateStatus is the status of an update in progress.
message UpdateStatus {
	enum UpdateState {
		UNKNOWN = 0;
		UPDATING = 1;
		PAUSED = 2;
		COMPLETED = 3;
		ROLLBACK_STARTED = 4;
		ROLLBACK_PAUSED = 5; // if a rollback fails
		ROLLBACK_COMPLETED = 6;
	}

	// State is the state of this update. It indicates whether the
	// update is in progress, completed, paused, rolling back, or
	// finished rolling back.
	UpdateState state = 1;

	// StartedAt is the time at which the update was started.
	// Note: can't use stdtime because this field is nullable.
	google.protobuf.Timestamp started_at = 2;

	// CompletedAt is the time at which the update completed successfully,
	// paused, or finished rolling back.
	// Note: can't use stdtime because this field is nullable.
	google.protobuf.Timestamp completed_at = 3;

	// TODO(aaronl): Consider adding a timestamp showing when the most
	// recent task update took place. Currently, this is nontrivial
	// because each service update kicks off a replacement update, so
	// updating the service object with a timestamp at every step along
	// the rolling update would cause the rolling update to be constantly
	// restarted.

	// Message explains how the update got into its current state. For
	// example, if the update is paused, it will explain what is preventing
	// the update from proceeding (typically the failure of a task to start up
	// when OnFailure is PAUSE).
	string message = 4;
}

// TaskState enumerates the states that a task progresses through within an
// agent. States are designed to be monotonically increasing, such that if two
// states are seen by a task, the greater of the new represents the true state.

// Only the manager create a NEW task, and move the task to PENDING and ASSIGNED.
// Afterward, the manager must rely on the agent to update the task status
// (pre-run: preparing, ready, starting;
//  running;
//  end-state: complete, shutdown, failed, rejected)
enum TaskState {
	// TODO(aluzzardi): Move it back into `TaskStatus` because of the naming
	// collisions of enums.

	option (gogoproto.goproto_enum_prefix) = false;
	option (gogoproto.enum_customname) = "TaskState";
	NEW = 0 [(gogoproto.enumvalue_customname)="TaskStateNew"];
	PENDING = 64 [(gogoproto.enumvalue_customname)="TaskStatePending"]; // waiting for scheduling decision
	ASSIGNED = 192 [(gogoproto.enumvalue_customname)="TaskStateAssigned"];
	ACCEPTED = 256 [(gogoproto.enumvalue_customname)="TaskStateAccepted"]; // task has been accepted by an agent.
	PREPARING = 320 [(gogoproto.enumvalue_customname)="TaskStatePreparing"];
	READY = 384 [(gogoproto.enumvalue_customname)="TaskStateReady"];
	STARTING = 448 [(gogoproto.enumvalue_customname)="TaskStateStarting"];
	RUNNING = 512 [(gogoproto.enumvalue_customname)="TaskStateRunning"];
	COMPLETE = 576 [(gogoproto.enumvalue_customname)="TaskStateCompleted"]; // successful completion of task (not error code, just ran)
	SHUTDOWN = 640 [(gogoproto.enumvalue_customname)="TaskStateShutdown"]; // orchestrator requested shutdown
	FAILED = 704 [(gogoproto.enumvalue_customname)="TaskStateFailed"]; // task execution failed with error
	// TaskStateRejected means a task never ran, for instance if something about
	// the environment failed (e.g. setting up a port on that node failed).
	REJECTED = 768 [(gogoproto.enumvalue_customname)="TaskStateRejected"]; // task could not be executed here.
	// TaskStateRemove is used to correctly handle service deletions and scale
	// downs. This allows us to keep track of tasks that have been marked for
	// deletion, but can't yet be removed because the agent is in the process of
	// shutting them down. Once the agent has shut down tasks with desired state
	// REMOVE, the task reaper is responsible for removing them.
	REMOVE = 800 [(gogoproto.enumvalue_customname)="TaskStateRemove"];
	// TaskStateOrphaned is used to free up resources associated with service
	// tasks on unresponsive nodes without having to delete those tasks. This
	// state is directly assigned to the task by the orchestrator.
	ORPHANED = 832 [(gogoproto.enumvalue_customname)="TaskStateOrphaned"];

	// NOTE(stevvooe): The state of a task is actually a lamport clock, in that
	// given two observations, the greater of the two can be considered
	// correct. To enforce this, we only allow tasks to proceed to a greater
	// state.
	//
	// A byproduct of this design decision is that we must also maintain this
	// invariant in the protobuf enum values, such that when comparing two
	// values, the one with the greater value is also the greater state.
	//
	// Because we may want to add intervening states a later date, we've left
	// 64 spaces between each one. This should allow us to make 5 or 6
	// insertions between each state if we find that we made a mistake and need
	// another state.
	//
	// Remove this message when the states are deemed perfect.
}

// Container specific status.
message ContainerStatus {
	string container_id = 1;

	int32 pid = 2 [(gogoproto.customname) = "PID"];
	int32 exit_code = 3;
}

// PortStatus specifies the actual allocated runtime state of a list
// of port configs.
message PortStatus {
	repeated PortConfig ports = 1;
}

message TaskStatus {
	// Note: can't use stdtime because this field is nullable.
	google.protobuf.Timestamp timestamp = 1;

	// State expresses the current state of the task.
	TaskState state = 2;

	// Message reports a message for the task status. This should provide a
	// human readable message that can point to how the task actually arrived
	// at a current state.
	//
	// As a convention, we place the a small message here that led to the
	// current state. For example, if the task is in ready, because it was
	// prepared, we'd place "prepared" in this field. If we skipped preparation
	// because the task is prepared, we would put "already prepared" in this
	// field.
	string message = 3;

	// Err is set if the task is in an error state, or is unable to
	// progress from an earlier state because a precondition is
	// unsatisfied.
	//
	// The following states should report a companion error:
	//
	//	FAILED, REJECTED
	//
	// In general, messages that should be surfaced to users belong in the
	// Err field, and notes on routine state transitions belong in Message.
	//
	// TODO(stevvooe) Integrate this field with the error interface.
	string err = 4;

	// Container status contains container specific status information.
	oneof runtime_status {
		ContainerStatus container = 5;
	}

	// HostPorts provides a list of ports allocated at the host
	// level.
	PortStatus port_status = 6;

	// AppliedBy gives the node ID of the manager that applied this task
	// status update to the Task object.
	string applied_by = 7;

	// AppliedAt gives a timestamp of when this status update was applied to
	// the Task object.
	// Note: can't use stdtime because this field is nullable.
	google.protobuf.Timestamp applied_at = 8;
}

// NetworkAttachmentConfig specifies how a service should be attached to a particular network.
//
// For now, this is a simple struct, but this can include future information
// instructing Swarm on how this service should work on the particular
// network.
message NetworkAttachmentConfig {
	// Target specifies the target network for attachment. This value must be a
	// network ID.
	string target = 1;
	// Aliases specifies a list of discoverable alternate names for the service on this Target.
	repeated string aliases = 2;
	// Addresses specifies a list of ipv4 and ipv6 addresses
	// preferred. If these addresses are not available then the
	// attachment might fail.
	repeated string addresses = 3;
	// DriverAttachmentOpts is a map of driver attachment options for the network target
	map<string, string> driver_attachment_opts = 4;
}

// IPAMConfig specifies parameters for IP Address Management.
message IPAMConfig {
	// TODO(stevvooe): It may make more sense to manage IPAM and network
	// definitions separately. This will allow multiple networks to share IPAM
	// instances. For now, we will follow the conventions of libnetwork and
	// specify this as part of the network specification.

	// AddressFamily specifies the network address family that
	// this IPAMConfig belongs to.
	enum AddressFamily {
		UNKNOWN = 0; // satisfy proto3
		IPV4 = 4;
		IPV6 = 6;
	}

	AddressFamily family = 1;

	// Subnet defines a network as a CIDR address (ie network and mask
	// 192.168.0.1/24).
	string subnet = 2;

	// Range defines the portion of the subnet to allocate to tasks. This is
	// defined as a subnet within the primary subnet.
	string range = 3;

	// Gateway address within the subnet.
	string gateway = 4;

	// Reserved is a list of address from the master pool that should *not* be
	// allocated. These addresses may have already been allocated or may be
	// reserved for another allocation manager.
	map<string, string> reserved = 5;
}

// PortConfig specifies an exposed port which can be
// addressed using the given name. This can be later queried
// using a service discovery api or a DNS SRV query. The node
// port specifies a port that can be used to address this
// service external to the cluster by sending a connection
// request to this port to any node on the cluster.
message PortConfig {
	enum Protocol {
		option (gogoproto.goproto_enum_prefix) = false;

		TCP = 0 [(gogoproto.enumvalue_customname) = "ProtocolTCP"];
		UDP = 1 [(gogoproto.enumvalue_customname) = "ProtocolUDP"];
		SCTP = 2 [(gogoproto.enumvalue_customname) = "ProtocolSCTP"];
	}

	// PublishMode controls how ports are published on the swarm.
	enum PublishMode {
		option (gogoproto.enum_customname) = "PublishMode";
		option (gogoproto.goproto_enum_prefix) = false;

		// PublishModeIngress exposes the port across the cluster on all nodes.
		INGRESS = 0 [(gogoproto.enumvalue_customname) = "PublishModeIngress"];

		// PublishModeHost exposes the port on just the target host.  If the
		// published port is undefined, an ephemeral port will be allocated. If
		// the published port is defined, the node will attempt to allocate it,
		// erroring the task if it fails.
		HOST = 1 [(gogoproto.enumvalue_customname) = "PublishModeHost"];
	}

	// Name for the port. If provided the port information can
	// be queried using the name as in a DNS SRV query.
	string name = 1;

	// Protocol for the port which is exposed.
	Protocol protocol = 2;

	// The port which the application is exposing and is bound to.
	uint32 target_port = 3;

	// PublishedPort specifies the port on which the service is exposed. If
	// specified, the port must be within the available range. If not specified
	// (value is zero), an available port is automatically assigned.
	uint32 published_port = 4;

	// PublishMode controls how the port is published.
	PublishMode publish_mode = 5;
}

// Driver is a generic driver type to be used throughout the API. For now, a
// driver is simply a name and set of options. The field contents depend on the
// target use case and driver application. For example, a network driver may
// have different rules than a volume driver.
message Driver {
	string name = 1;
	map <string, string> options = 2;
}

message IPAMOptions {
	Driver driver = 1;
	repeated IPAMConfig configs = 3;
}

// Peer should be used anywhere where we are describing a remote peer.
message Peer {
	string node_id = 1;
	string addr = 2;
}

// WeightedPeer should be used anywhere where we are describing a remote peer
// with a weight.
message WeightedPeer {
	Peer peer = 1;
	int64 weight = 2;
}


message IssuanceStatus {
	enum State {
		option (gogoproto.goproto_enum_prefix) = false;

		UNKNOWN = 0 [(gogoproto.enumvalue_customname) = "IssuanceStateUnknown"];
		// A new certificate should be issued
		RENEW = 1 [(gogoproto.enumvalue_customname)="IssuanceStateRenew"];
		// Certificate is pending acceptance
		PENDING = 2 [(gogoproto.enumvalue_customname)="IssuanceStatePending"];
		// successful completion certificate issuance
		ISSUED = 3 [(gogoproto.enumvalue_customname)="IssuanceStateIssued"];
		// Certificate issuance failed
		FAILED = 4 [(gogoproto.enumvalue_customname)="IssuanceStateFailed"];
		// Signals workers to renew their certificate. From the CA's perspective
		// this is equivalent to IssuanceStateIssued: a noop.
		ROTATE = 5 [(gogoproto.enumvalue_customname)="IssuanceStateRotate"];
	}
	State state = 1;

	// Err is set if the Certificate Issuance is in an error state.
	// The following states should report a companion error:
	//	FAILED
	string err = 2;
}

message AcceptancePolicy {
	message RoleAdmissionPolicy {
		message Secret {
			// The actual content (possibly hashed)
			bytes data = 1;
			// The type of hash we are using, or "plaintext"
			string alg = 2;
		}

		NodeRole role = 1;
		// Autoaccept controls which roles' certificates are automatically
		// issued without administrator intervention.
		bool autoaccept = 2;
		// Secret represents a user-provided string that is necessary for new
		// nodes to join the cluster
		Secret secret = 3;
	}

	repeated RoleAdmissionPolicy policies = 1;
}

message ExternalCA {
	enum CAProtocol {
		CFSSL = 0 [(gogoproto.enumvalue_customname) = "CAProtocolCFSSL"];
	}

	// Protocol is the protocol used by this external CA.
	CAProtocol protocol = 1;

	// URL is the URL where the external CA can be reached.
	string url = 2 [(gogoproto.customname) = "URL"];

	// Options is a set of additional key/value pairs whose interpretation
	// depends on the specified CA type.
	map<string, string> options = 3;

	// CACert specifies which root CA is used by this external CA
	bytes ca_cert = 4 [(gogoproto.customname) = "CACert"];
}

message CAConfig {
	// NodeCertExpiry is the duration certificates should be issued for
	// Note: can't use stdduration because this field needs to be nullable.
	google.protobuf.Duration node_cert_expiry = 1;

	// ExternalCAs is a list of CAs to which a manager node will make
	// certificate signing requests for node certificates.
	repeated ExternalCA external_cas = 2 [(gogoproto.customname) = "ExternalCAs"];

	// SigningCACert is the desired CA certificate to be used as the root and
	// signing CA for the swarm.  If not provided, indicates that we are either happy
	// with the current configuration, or (together with a bump in the ForceRotate value)
	// that we want a certificate and key generated for us.
	bytes signing_ca_cert = 3 [(gogoproto.customname) = "SigningCACert"];

	// SigningCAKey is the desired private key, matching the signing CA cert, to be used
	// to sign certificates for the swarm
	bytes signing_ca_key = 4 [(gogoproto.customname) = "SigningCAKey"];

	// ForceRotate is a counter that triggers a root CA rotation even if no relevant
	// parameters have been in the spec. This will force the manager to generate a new
	// certificate and key, if none have been provided.
	uint64 force_rotate = 5;
}

// OrchestrationConfig defines cluster-level orchestration settings.
message OrchestrationConfig {
	// TaskHistoryRetentionLimit is the number of historic tasks to keep per instance or
	// node. If negative, never remove completed or failed tasks.
	int64 task_history_retention_limit = 1;

}

// TaskDefaults specifies default values for task creation.
message TaskDefaults {
	// LogDriver specifies the log driver to use for the cluster if not
	// specified for each task.
	//
	// If this is changed, only new tasks will pick up the new log driver.
	// Existing tasks will continue to use the previous default until rescheduled.
	Driver log_driver = 1;
}

// DispatcherConfig defines cluster-level dispatcher settings.
message DispatcherConfig {
	// HeartbeatPeriod defines how often agent should send heartbeats to
	// dispatcher.
	// Note: can't use stdduration because this field needs to be nullable.
	google.protobuf.Duration heartbeat_period = 1;
}

// RaftConfig defines raft settings for the cluster.
message RaftConfig {
	// SnapshotInterval is the number of log entries between snapshots.
	uint64 snapshot_interval = 1;
	// KeepOldSnapshots is the number of snapshots to keep beyond the
	// current snapshot.
	uint64 keep_old_snapshots = 2;
	// LogEntriesForSlowFollowers is the number of log entries to keep
	// around to sync up slow followers after a snapshot is created.
	uint64 log_entries_for_slow_followers = 3;
	// HeartbeatTick defines the amount of ticks (in seconds) between
	// each heartbeat message sent to other members for health-check.
	uint32 heartbeat_tick = 4;
	// ElectionTick defines the amount of ticks (in seconds) needed
	// without a leader to trigger a new election.
	uint32 election_tick = 5;
}

message EncryptionConfig {
	// AutoLockManagers specifies whether or not managers TLS keys and raft data
	// should be encrypted at rest in such a way that they must be unlocked
	// before the manager node starts up again.
	bool auto_lock_managers = 1;
}

message SpreadOver {
	string spread_descriptor = 1; // label descriptor, such as engine.labels.az
	// TODO: support node information beyond engine and node labels

	// TODO: in the future, add a map that provides weights for weighted
	// spreading.
}

message PlacementPreference {
	oneof Preference {
		SpreadOver spread = 1;
	}
}

// Placement specifies task distribution constraints.
message Placement {
	// Constraints specifies a set of requirements a node should meet for a task.
	repeated string constraints = 1;

	// Preferences provide a way to make the scheduler aware of factors
	// such as topology. They are provided in order from highest to lowest
	// precedence.
	repeated PlacementPreference preferences = 2;

	// Platforms stores all the platforms that the image can run on.
	// This field is used in the platform filter for scheduling. If empty,
	// then the platform filter is off, meaning there are no scheduling restrictions.
	repeated Platform platforms = 3;

	// MaxReplicas specifies the limit for maximum number of replicas running on one node.
	uint64 max_replicas = 4;
}

// JoinToken contains the join tokens for workers and managers.
message JoinTokens {
	// Worker is the join token workers may use to join the swarm.
	string worker = 1;

	// Manager is the join token workers may use to join the swarm.
	string manager = 2;
}

message RootCA {
	// CAKey is the root CA private key.
	bytes ca_key = 1 [(gogoproto.customname) = "CAKey"];

	// CACert is the root CA certificate.
	bytes ca_cert = 2 [(gogoproto.customname) = "CACert"];

	// CACertHash is the digest of the CA Certificate.
	string ca_cert_hash = 3 [(gogoproto.customname) = "CACertHash"];

	// JoinTokens contains the join tokens for workers and managers.
	JoinTokens join_tokens = 4 [(gogoproto.nullable) = false];

	// RootRotation contains the new root cert and key we want to rotate to - if this is nil, we are not in the
	// middle of a root rotation
	RootRotation root_rotation = 5;

	// LastForcedRotation matches the Cluster Spec's CAConfig's ForceRotation counter.
	// It indicates when the current CA cert and key were generated (or updated).
	uint64 last_forced_rotation = 6;
}


enum NodeRole {
	option (gogoproto.enum_customname) = "NodeRole";
	option (gogoproto.goproto_enum_prefix) = false;

	WORKER = 0 [(gogoproto.enumvalue_customname) = "NodeRoleWorker"];
	MANAGER = 1 [(gogoproto.enumvalue_customname) = "NodeRoleManager"];
}

message Certificate {
	NodeRole role = 1;

	bytes csr = 2 [(gogoproto.customname) = "CSR"];

	IssuanceStatus status = 3 [(gogoproto.nullable) = false];

	bytes certificate = 4;

	// CN represents the node ID.
	string cn = 5 [(gogoproto.customname) = "CN"];
}


// Symmetric keys to encrypt inter-agent communication.
message EncryptionKey {
	// Agent subsystem the key is intended for. Example:
	// networking:gossip
	string subsystem = 1;

	// Encryption algorithm that can implemented using this key
	enum Algorithm {
		option (gogoproto.goproto_enum_prefix) = false;

		AES_128_GCM = 0;
	}

	Algorithm algorithm = 2;

	bytes key = 3;

	// Time stamp from the lamport clock of the key allocator to
	// identify the relative age of the key.
	uint64 lamport_time = 4;
}

// ManagerStatus provides informations about the state of a manager in the cluster.
message ManagerStatus {
	// RaftID specifies the internal ID used by the manager in a raft context, it can never be modified
	// and is used only for information purposes
	uint64 raft_id = 1;

	// Addr is the address advertised to raft.
	string addr = 2;

	// Leader is set to true if this node is the raft leader.
	bool leader = 3;

	// Reachability specifies whether this node is reachable.
	RaftMemberStatus.Reachability reachability = 4;
}

// FileTarget represents a specific target that is backed by a file
message FileTarget {
	// Name represents the final filename in the filesystem
	string name = 1;

	// UID represents the file UID
	string uid = 2 [(gogoproto.customname) = "UID"];

	// GID represents the file GID
	string gid = 3 [(gogoproto.customname) = "GID"];

	// Mode represents the FileMode of the file
	uint32 mode = 4 [(gogoproto.customtype) = "os.FileMode", (gogoproto.nullable) = false];
}

// RuntimeTarget represents that this secret is _not_ mounted into the
// container, but is used for some other purpose by the container runtime.
//
// Currently, RuntimeTarget has no fields; it's just a placeholder.
message RuntimeTarget {}

// SecretReference is the linkage between a service and a secret that it uses.
message SecretReference {
	// SecretID represents the ID of the specific Secret that we're
	// referencing. This identifier exists so that SecretReferences don't leak
	// any information about the secret contents.
	string secret_id = 1;

	// SecretName is the name of the secret that this references, but this is just provided for
	// lookup/display purposes.  The secret in the reference will be identified by its ID.
	string secret_name = 2;

	// Target specifies how this secret should be exposed to the task.
	oneof target {
		FileTarget file = 3;
	}
}

// ConfigReference is the linkage between a service and a config that it uses.
message ConfigReference {
	// ConfigID represents the ID of the specific Config that we're
	// referencing.
	string config_id = 1;

	// ConfigName is the name of the config that this references, but this is just provided for
	// lookup/display purposes. The config in the reference will be identified by its ID.
	string config_name = 2;

	// Target specifies how this config should be exposed to the task.
	oneof target {
		FileTarget file = 3;
		RuntimeTarget runtime = 4;
	}
}

// BlacklistedCertificate is a record for a blacklisted certificate. It does not
// contain the certificate's CN, because these records are indexed by CN.
message BlacklistedCertificate {
	// Expiry is the latest known expiration time of a certificate that
	// was issued for the given CN.
	// Note: can't use stdtime because this field is nullable.
	google.protobuf.Timestamp expiry = 1;
}

// HealthConfig holds configuration settings for the HEALTHCHECK feature.
message HealthConfig {
	// Test is the test to perform to check that the container is healthy.
	// An empty slice means to inherit the default.
	// The options are:
	// {} : inherit healthcheck
	// {"NONE"} : disable healthcheck
	// {"CMD", args...} : exec arguments directly
	// {"CMD-SHELL", command} : run command with system's default shell
	repeated string test = 1;

	// Interval is the time to wait between checks. Zero means inherit.
	// Note: can't use stdduration because this field needs to be nullable.
	google.protobuf.Duration interval = 2;

	// Timeout is the time to wait before considering the check to have hung.
	// Zero means inherit.
	// Note: can't use stdduration because this field needs to be nullable.
	google.protobuf.Duration timeout = 3;

	// Retries is the number of consecutive failures needed to consider a
	// container as unhealthy. Zero means inherit.
	int32 retries = 4;

	// Start period is the period for container initialization during
	// which health check failures will note count towards the maximum
	// number of retries.
	google.protobuf.Duration start_period = 5;

	// StartInterval is the time to wait between checks during the start period.
	// Zero means inherit.
	// Note: can't use stdduration because this field needs to be nullable.
	google.protobuf.Duration start_interval = 6;

}

message MaybeEncryptedRecord {
	enum Algorithm {
		NONE = 0 [(gogoproto.enumvalue_customname) = "NotEncrypted"];
		SECRETBOX_SALSA20_POLY1305 = 1 [(gogoproto.enumvalue_customname) = "NACLSecretboxSalsa20Poly1305"];
		FERNET_AES_128_CBC = 2 [(gogoproto.enumvalue_customname) = "FernetAES128CBC"];
	}

	Algorithm algorithm = 1;
	bytes data = 2;
	bytes nonce = 3;
}


message RootRotation {
	bytes ca_cert = 1 [(gogoproto.customname) = "CACert"];
	bytes ca_key = 2 [(gogoproto.customname) = "CAKey"];
	// cross-signed CA cert is the CACert that has been cross-signed by the previous root
	bytes cross_signed_ca_cert = 3 [(gogoproto.customname) = "CrossSignedCACert"];
}

// Privileges specifies security configuration/permissions.
message Privileges {
	// CredentialSpec for managed service account (Windows only).
	message CredentialSpec {
		oneof source {
			string file = 1;
			string registry = 2;

			// Config represents a Config ID from which to get the CredentialSpec.
			// The Config MUST be included in the SecretReferences with a RuntimeTarget
			string config = 3;
		}
	}
	CredentialSpec credential_spec = 1;

	// SELinuxContext contains the SELinux labels for the container.
	message SELinuxContext {
		bool disable = 1;

		string user = 2;
		string role = 3;
		string type = 4;
		string level = 5;
	}
	SELinuxContext selinux_context = 2 [(gogoproto.customname) = "SELinuxContext"];

	// SeccompOpts contains options for configuring seccomp profiles on the
	// container. See https://docs.docker.com/engine/security/seccomp/ for more
	// information.
	message SeccompOpts {
		enum SeccompMode {
			DEFAULT = 0;
			UNCONFINED = 1;
			CUSTOM =  2;
		}
		SeccompMode mode = 1;
		// Profile contains the json definition of the seccomp profile to use,
		// if Mode is set to custom.
		bytes profile = 2;
	}
	SeccompOpts seccomp = 3;

	// AppArmorOpts contains options for configuring AppArmor profiles on the
	// container. Currently, custom profiles are not supported. See
	// https://docs.docker.com/engine/security/apparmor/ for more information.
	message AppArmorOpts {
		enum AppArmorMode {
			DEFAULT = 0;
			DISABLED = 1;
		}
		AppArmorMode mode = 1;
	}
	AppArmorOpts apparmor = 4;

	// NoNewPrivileges, if set to true, disables the container from gaining new
	// privileges. See https://docs.kernel.org/userspace-api/no_new_privs.html
	// for details.
	bool no_new_privileges = 5;
}

// JobStatus indicates the status of a Service that is in one of the Job modes.
message JobStatus {
	// JobIteration is the count of how many times the Job has been excecuted,
	// successfully or otherwise. "Executed" refers to the job as a whole being
	// started, not to the individual Tasks being launched. This is used to
	// disambiguate which Tasks belong to which iteration of a Job.
	Version job_iteration = 1 [(gogoproto.nullable) = false];

	// LastExecution is the time that the job was last executed. This is set by
	// the orchestrator in the same transaction that JobIteration is incremented.
	// While time is a fungible concept in distributed systems like Swarmkit,
	// this value gives us a best-effort attempt to prevent weird behavior like
	// newly added nodes executing long-forgotten jobs.
	google.protobuf.Timestamp last_execution = 2;
}

// VolumeAccessMode is the access mode of the volume, and is used to determine
// the CSI AccessMode value, as well as the volume access type (block vs
// mount). In this way, it is more similar to the CSI VolumeCapability message.
//
// This defines how and where a volume can be accessed by more than
// one Task, but does not imply anything about the accessible topology of the
// volume.
//
// For analogy, a flash drive can be used on many computers, but only one of
// them at a time, and so would have a scope of "Single". But, it can be used
// by any number of programs simultaneously, so would have a sharing of "All".
message VolumeAccessMode {
	// Scope enumerates the possible volume access scopes.
	enum Scope {
		option (gogoproto.goproto_enum_prefix) = false;
		// VolumeScopeSingleNode indicates that only one node at a time may have
		// access to the volume.
		SINGLE_NODE = 0 [(gogoproto.enumvalue_customname) = "VolumeScopeSingleNode"];
		// VolumeScopeMultiNode indicates that multiple nodes may access the volume
		// at the same time.
		MULTI_NODE = 1 [(gogoproto.enumvalue_customname) = "VolumeScopeMultiNode"];
	}

	// Sharing enumerates the possible volume sharing modes.
	enum Sharing {
		option (gogoproto.goproto_enum_prefix) = false;
		// VolumeSharingNone indicates that the volume may only be used by a single
		// Task at any given time.
		NONE = 0 [(gogoproto.enumvalue_customname) = "VolumeSharingNone"];
		// VolumeSharingReadOnly indicates that the volume may be accessed by
		// multiple Tasks, but all Tasks only have have read access.
		READ_ONLY = 1 [(gogoproto.enumvalue_customname) = "VolumeSharingReadOnly"];
		// VolumeSharingOneWriter indicates that the Volume may be accessed by
		// multiple Tasks, but only the one Task may have write permission for the
		// Volume.
		ONE_WRITER = 2 [(gogoproto.enumvalue_customname) = "VolumeSharingOneWriter"];
		// VolumeSharingAll indicates that any number of Tasks may have read and
		// write access to the volume.
		ALL = 3 [(gogoproto.enumvalue_customname) = "VolumeSharingAll"];
	}

	// BlockVolume indicates the volume will be accessed with the block device
	// API.
	message BlockVolume {
		// intentionally empty
	}

	// MountVolume indicates the volume will be access with the filesystem API.
	message MountVolume {
		// FsType is the filesystem type. This field is optional, and an empty
		// string is equal to an unspecified value.
		string fs_type = 1;

		// MountFlags indicates mount options to be used for the volume. This
		// field is optional, and may contain sensitive data.
		repeated string mount_flags = 2;
	}

	// Scope defines on how many nodes this volume can be accessed
	// simultaneously. If unset, will default to the zero-value of SINGLE_NODE.
	Scope scope = 1;

	// Sharing defines how many tasks can use this volume at the same time, and
	// in what way. If unset, will default to the zero-value of NONE.
	Sharing sharing = 2;

	// AccessType defines the access type of the volume. Unlike Sharing and
	// Scope, Swarmkit itself doesn't define either of these as a default, but
	// but the upstream is free to do so. However, one of these MUST be set.
	oneof access_type {
		BlockVolume block = 3;
		MountVolume mount = 4;
	}
}

// VolumeSecret indicates a secret value that must be passed to CSI plugin
// operations.
message VolumeSecret {
	// Key represents the key that will be passed as a controller secret to the
	// CSI plugin.
	string key = 1;

	// Secret represents the swarmkit Secret object from which to read data to
	// use as the value to pass to the CSI plugin. This can be either a secret
	// name or ID.
	//
	// TODO(dperny): should this be a SecretReference instead?
	string secret = 2;
}

// VolumePublishStatus contains information about the volume's publishing to a
// specific node.
//
// Publishing or unpublishing a volume to a node is a two-step process.
//
// When a Volume is needed on a Node, a VolumePublishStatus with state
// PendingPublish is added. This indicates that the volume should be published,
// but the RPCs have not been executed.
//
// Then, afterward, ControllerPublishVolume is called for the Volume, and the
// State is changed to Published, indicating that the call was a success.
//
// When a Volume is no longer needed, the process is similar, with the State
// being changed to PendingUnpublish. When ControllerUnpublishVolume succeeds,
// the PublishStatus for that Node is simply removed.
//
// Without this two-step process, the following could happen:
//
//   1. ControllerPublishVolume is called and the Volume is successfully
//      published.
//   2. A crash or leadership change disrupts the cluster before
//      the Volume with the updated VolumePublishStatus can be added to the
//      store.
//   3. The Task that required the Volume to be published is deleted.
//
// In this case, the Volume would be published to the Node, but Swarm would be
// unaware of this, and would additionally be unaware that the Volume _should_
// be published to the Node.
//
// By first committing our intention to publish a Volume, we guarantee that the
// Volume itself is sufficient to know which Nodes it may have been published
// to.
message VolumePublishStatus {
	// State is the state of the volume in the publish/unpublish
	// lifecycle, on a particular node.
	enum State {
		// PendingPublish indicates that the volume should be published on this
		// node, but the call to ControllerPublishVolume has not been
		// successfully completed yet and the result recorded by swarmkit.
		PENDING_PUBLISH = 0;

		// Published means the volume is published successfully to the node.
		PUBLISHED = 1;

		// PendingNodeUnpublish indicates that the Volume should be unpublished
		// on the Node, and we're waiting for confirmation that it has done so.
		// After the Node has confirmed that the Volume has been unpublished,
		// the state will move to PendingUnpublish.
		PENDING_NODE_UNPUBLISH = 2;

		// PendingUnpublish means the volume is published to the node, and
		// needs to not be, but the call to ControllerUnpublishVolume has not
		// verifiably succeeded yet. There is no Unpublished state, because
		// after the volume has been verifiably unpublished, the
		// VolumePublishStatus for the node is removed.
		PENDING_UNPUBLISH = 3;
	}

	// NodeID is the swarm (not CSI plugin) node ID that this volume is
	// published to.
	string node_id = 1;

	// State is the publish state of the volume.
	State state = 2;

	// PublishContext is the same PublishContext returned by a call to
	// ControllerPublishVolume.
	map<string, string> publish_context = 3;

	// Message is a human-readable message explaining the state of the volume.
	// It exists to convey the current situation with the volume to the user,
	// allowing, for example, the user to see error messages why a volume might
	// not be published yet.
	string message = 5;
}

// VolumeInfo contains information about the volume originating from the CSI
// plugin.
message VolumeInfo {
	// CapacityBytes is the capacity of this volume in bytes. A value of 0
	// indicates that the capcity is unknown.
	int64 capacity_bytes = 1;

	// VolumeContext includes fields that are opaque to Swarmkit.
	map<string, string> volume_context = 2;

	// VolumeID is the ID of the volume as reported by the CSI plugin.
	// Information about the volume is not cached in swarmkit's object store;
	// instead, it is retrieved on-demand as needed. If the VolumeID field is an
	// empty string, and the plugin advertises CREATE_DELETE_VOLUME capability,
	// then Swarmkit has not yet called CreateVolume.
	string volume_id = 3;

	// AccessibleTopology is the topology this volume is actually accessible
	// from.
	repeated Topology accessible_topology = 4;
}

// CapacityRange describes the minimum and maximum capacity a volume should be
// created with.
message CapacityRange {
	// RequiredBytes specifies that a volume must be at least this big. The value
	// of 0 indicates an unspecified minimum. Must not be negative.
	int64 required_bytes = 1;

	// LimitBytes specifies that a volume must not be bigger than this. The value
	// of 0 indicates an unspecified maximum. Must not be negative.
	int64 limit_bytes = 2;
}

// VolumeAssignment contains the information needed by a Node to use a CSI
// volume. This includes the information need to Stage and Publish the volume
// on the node, but never the full Volume object.
message VolumeAssignment {
	// ID is the swarmkit ID for the volume. This is used by swarmkit components
	// to identify the volume.
	string id = 1;

	// VolumeID is the CSI volume ID as returned from CreateVolume. This is used
	// by the CSI driver to identify the volume.
	string volume_id = 2;

	// Driver is the CSI Driver that this volume is managed by.
	Driver driver = 3;

	// VolumeContext is a map returned from the CSI Controller service when a
	// Volume is created. It is optional for the driver to provide, but if it is
	// provided, it must be passed to subsequent calls.
	map<string,string> volume_context = 4;

	// PublishContext is a map returned from the Controller service when
	// ControllerPublishVolume is called. Again, it is optional, but if provided,
	// must be passed.
	map<string,string> publish_context = 5;

	// AccessMode specifies the access mode of the volume.
	VolumeAccessMode access_mode = 6;

	// Secrets is the set of secrets required by the CSI plugin. These refer to
	// swarmkit Secrets that will be distributed separately to the node.
	repeated VolumeSecret secrets = 7;
}

// VolumeAttachment is the information associating a Volume with a Task.
message VolumeAttachment {
	// ID is the swarmkit ID of the volume assigned to this task, not the CSI
	// volume ID.
	string id = 1;

	// Source indicates the Mount source that this volume is assigned for.
	string source = 2;

	// Target indicates the Mount target that this volume is assigned for.
	string target = 3;
}


// These types are copied from the CSI spec. They are copied because there is
// difficulty in compatibility between the CSI protos and the swarmkit protos,
// and straight importing them is difficult.

// TopologyRequirement expresses the user's requirements for a volume's
// accessible topology.
message TopologyRequirement {
	// Specifies the list of topologies the provisioned volume MUST be
	// accessible from.
	// This field is OPTIONAL. If TopologyRequirement is specified either
	// requisite or preferred or both MUST be specified.
	//
	// If requisite is specified, the provisioned volume MUST be
	// accessible from at least one of the requisite topologies.
	//
	// Given
	//   x = number of topologies provisioned volume is accessible from
	//   n = number of requisite topologies
	// The CO MUST ensure n >= 1. The SP MUST ensure x >= 1
	// If x==n, then the SP MUST make the provisioned volume available to
	// all topologies from the list of requisite topologies. If it is
	// unable to do so, the SP MUST fail the CreateVolume call.
	// For example, if a volume should be accessible from a single zone,
	// and requisite =
	//   {"region": "R1", "zone": "Z2"}
	// then the provisioned volume MUST be accessible from the "region"
	// "R1" and the "zone" "Z2".
	// Similarly, if a volume should be accessible from two zones, and
	// requisite =
	//   {"region": "R1", "zone": "Z2"},
	//   {"region": "R1", "zone": "Z3"}
	// then the provisioned volume MUST be accessible from the "region"
	// "R1" and both "zone" "Z2" and "zone" "Z3".
	//
	// If x<n, then the SP SHALL choose x unique topologies from the list
	// of requisite topologies. If it is unable to do so, the SP MUST fail
	// the CreateVolume call.
	// For example, if a volume should be accessible from a single zone,
	// and requisite =
	//   {"region": "R1", "zone": "Z2"},
	//   {"region": "R1", "zone": "Z3"}
	// then the SP may choose to make the provisioned volume available in
	// either the "zone" "Z2" or the "zone" "Z3" in the "region" "R1".
	// Similarly, if a volume should be accessible from two zones, and
	// requisite =
	//   {"region": "R1", "zone": "Z2"},
	//   {"region": "R1", "zone": "Z3"},
	//   {"region": "R1", "zone": "Z4"}
	// then the provisioned volume MUST be accessible from any combination
	// of two unique topologies: e.g. "R1/Z2" and "R1/Z3", or "R1/Z2" and
	//  "R1/Z4", or "R1/Z3" and "R1/Z4".
	//
	// If x>n, then the SP MUST make the provisioned volume available from
	// all topologies from the list of requisite topologies and MAY choose
	// the remaining x-n unique topologies from the list of all possible
	// topologies. If it is unable to do so, the SP MUST fail the
	// CreateVolume call.
	// For example, if a volume should be accessible from two zones, and
	// requisite =
	//   {"region": "R1", "zone": "Z2"}
	// then the provisioned volume MUST be accessible from the "region"
	// "R1" and the "zone" "Z2" and the SP may select the second zone
	// independently, e.g. "R1/Z4".
	repeated Topology requisite = 1;

	// Specifies the list of topologies the CO would prefer the volume to
	// be provisioned in.
	//
	// This field is OPTIONAL. If TopologyRequirement is specified either
	// requisite or preferred or both MUST be specified.
	//
	// An SP MUST attempt to make the provisioned volume available using
	// the preferred topologies in order from first to last.
	//
	// If requisite is specified, all topologies in preferred list MUST
	// also be present in the list of requisite topologies.
	//
	// If the SP is unable to to make the provisioned volume available
	// from any of the preferred topologies, the SP MAY choose a topology
	// from the list of requisite topologies.
	// If the list of requisite topologies is not specified, then the SP
	// MAY choose from the list of all possible topologies.
	// If the list of requisite topologies is specified and the SP is
	// unable to to make the provisioned volume available from any of the
	// requisite topologies it MUST fail the CreateVolume call.
	//
	// Example 1:
	// Given a volume should be accessible from a single zone, and
	// requisite =
	//   {"region": "R1", "zone": "Z2"},
	//   {"region": "R1", "zone": "Z3"}
	// preferred =
	//   {"region": "R1", "zone": "Z3"}
	// then the the SP SHOULD first attempt to make the provisioned volume
	// available from "zone" "Z3" in the "region" "R1" and fall back to
	// "zone" "Z2" in the "region" "R1" if that is not possible.
	//
	// Example 2:
	// Given a volume should be accessible from a single zone, and
	// requisite =
	//   {"region": "R1", "zone": "Z2"},
	//   {"region": "R1", "zone": "Z3"},
	//   {"region": "R1", "zone": "Z4"},
	//   {"region": "R1", "zone": "Z5"}
	// preferred =
	//   {"region": "R1", "zone": "Z4"},
	//   {"region": "R1", "zone": "Z2"}
	// then the the SP SHOULD first attempt to make the provisioned volume
	// accessible from "zone" "Z4" in the "region" "R1" and fall back to
	// "zone" "Z2" in the "region" "R1" if that is not possible. If that
	// is not possible, the SP may choose between either the "zone"
	// "Z3" or "Z5" in the "region" "R1".
	//
	// Example 3:
	// Given a volume should be accessible from TWO zones (because an
	// opaque parameter in CreateVolumeRequest, for example, specifies
	// the volume is accessible from two zones, aka synchronously
	// replicated), and
	// requisite =
	//   {"region": "R1", "zone": "Z2"},
	//   {"region": "R1", "zone": "Z3"},
	//   {"region": "R1", "zone": "Z4"},
	//   {"region": "R1", "zone": "Z5"}
	// preferred =
	//   {"region": "R1", "zone": "Z5"},
	//   {"region": "R1", "zone": "Z3"}
	// then the the SP SHOULD first attempt to make the provisioned volume
	// accessible from the combination of the two "zones" "Z5" and "Z3" in
	// the "region" "R1". If that's not possible, it should fall back to
	// a combination of "Z5" and other possibilities from the list of
	// requisite. If that's not possible, it should fall back  to a
	// combination of "Z3" and other possibilities from the list of
	// requisite. If that's not possible, it should fall back  to a
	// combination of other possibilities from the list of requisite.
	repeated Topology preferred = 2;
}

// Topology is a map of topological domains to topological segments.
// A topological domain is a sub-division of a cluster, like "region",
// "zone", "rack", etc.
// A topological segment is a specific instance of a topological domain,
// like "zone3", "rack3", etc.
// For example {"com.company/zone": "Z1", "com.company/rack": "R3"}
// Valid keys have two segments: an OPTIONAL prefix and name, separated
// by a slash (/), for example: "com.company.example/zone".
// The key name segment is REQUIRED. The prefix is OPTIONAL.
// The key name MUST be 63 characters or less, begin and end with an
// alphanumeric character ([a-z0-9A-Z]), and contain only dashes (-),
// underscores (_), dots (.), or alphanumerics in between, for example
// "zone".
// The key prefix MUST be 63 characters or less, begin and end with a
// lower-case alphanumeric character ([a-z0-9]), contain only
// dashes (-), dots (.), or lower-case alphanumerics in between, and
// follow domain name notation format
// (https://tools.ietf.org/html/rfc1035#section-2.3.1).
// The key prefix SHOULD include the plugin's host company name and/or
// the plugin name, to minimize the possibility of collisions with keys
// from other plugins.
// If a key prefix is specified, it MUST be identical across all
// topology keys returned by the SP (across all RPCs).
// Keys MUST be case-insensitive. Meaning the keys "Zone" and "zone"
// MUST not both exist.
// Each value (topological segment) MUST contain 1 or more strings.
// Each string MUST be 63 characters or less and begin and end with an
// alphanumeric character with '-', '_', '.', or alphanumerics in
// between.
message Topology {
	map<string, string> segments = 1;
}

// VolumeCapability specifies a capability of a volume.
message VolumeCapability {
	// Indicate that the volume will be accessed via the block device API.
	message BlockVolume {
		// Intentionally empty, for now.
	}

	// Indicate that the volume will be accessed via the filesystem API.
	message MountVolume {
		// The filesystem type. This field is OPTIONAL.
		// An empty string is equal to an unspecified field value.
		string fs_type = 1;

		// The mount options that can be used for the volume. This field is
		// OPTIONAL. `mount_flags` MAY contain sensitive information.
		// Therefore, the CO and the Plugin MUST NOT leak this information
		// to untrusted entities. The total size of this repeated field
		// SHALL NOT exceed 4 KiB.
		repeated string mount_flags = 2;
	}

	// Specify how a volume can be accessed.
	message AccessMode {
		enum Mode {
			UNKNOWN = 0;

			// Can only be published once as read/write on a single node, at
			// any given time.
			SINGLE_NODE_WRITER = 1;

			// Can only be published once as readonly on a single node, at
			// any given time.
			SINGLE_NODE_READER_ONLY = 2;

			// Can be published as readonly at multiple nodes simultaneously.
			MULTI_NODE_READER_ONLY = 3;

			// Can be published at multiple nodes simultaneously. Only one of
			// the node can be used as read/write. The rest will be readonly.
			MULTI_NODE_SINGLE_WRITER = 4;

			// Can be published as read/write at multiple nodes
			// simultaneously.
			MULTI_NODE_MULTI_WRITER = 5;
		}

		// This field is REQUIRED.
		Mode mode = 1;
	}

	// Specifies what API the volume will be accessed using. One of the
	// following fields MUST be specified.
	oneof access_type {
		BlockVolume block = 1;
		MountVolume mount = 2;
	}

	// This is a REQUIRED field.
	AccessMode access_mode = 3;
}