| syntax = "proto3"; |
| |
| package containerd.services.containers.v1; |
| |
| import "gogoproto/gogo.proto"; |
| import "google/protobuf/any.proto"; |
| import "google/protobuf/empty.proto"; |
| import "google/protobuf/field_mask.proto"; |
| import "google/protobuf/timestamp.proto"; |
| |
| option go_package = "github.com/containerd/containerd/api/services/containers/v1;containers"; |
| |
| // Containers provides metadata storage for containers used in the execution |
| // service. |
| // |
| // The objects here provide an state-independent view of containers for use in |
| // management and resource pinning. From that perspective, containers do not |
| // have a "state" but rather this is the set of resources that will be |
| // considered in use by the container. |
| // |
| // From the perspective of the execution service, these objects represent the |
| // base parameters for creating a container process. |
| // |
| // In general, when looking to add fields for this type, first ask yourself |
| // whether or not the function of the field has to do with runtime execution or |
| // is invariant of the runtime state of the container. If it has to do with |
| // runtime, or changes as the "container" is started and stops, it probably |
| // doesn't belong on this object. |
| service Containers { |
| rpc Get(GetContainerRequest) returns (GetContainerResponse); |
| rpc List(ListContainersRequest) returns (ListContainersResponse); |
| rpc Create(CreateContainerRequest) returns (CreateContainerResponse); |
| rpc Update(UpdateContainerRequest) returns (UpdateContainerResponse); |
| rpc Delete(DeleteContainerRequest) returns (google.protobuf.Empty); |
| } |
| |
| message Container { |
| // ID is the user-specified identifier. |
| // |
| // This field may not be updated. |
| string id = 1; |
| |
| // Labels provides an area to include arbitrary data on containers. |
| // |
| // The combined size of a key/value pair cannot exceed 4096 bytes. |
| // |
| // Note that to add a new value to this field, read the existing set and |
| // include the entire result in the update call. |
| map<string, string> labels = 2; |
| |
| // Image contains the reference of the image used to build the |
| // specification and snapshots for running this container. |
| // |
| // If this field is updated, the spec and rootfs needed to updated, as well. |
| string image = 3; |
| |
| message Runtime { |
| // Name is the name of the runtime. |
| string name = 1; |
| // Options specify additional runtime initialization options. |
| google.protobuf.Any options = 2; |
| } |
| // Runtime specifies which runtime to use for executing this container. |
| Runtime runtime = 4; |
| |
| // Spec to be used when creating the container. This is runtime specific. |
| google.protobuf.Any spec = 5; |
| |
| // Snapshotter specifies the snapshotter name used for rootfs |
| string snapshotter = 6; |
| |
| // SnapshotKey specifies the snapshot key to use for the container's root |
| // filesystem. When starting a task from this container, a caller should |
| // look up the mounts from the snapshot service and include those on the |
| // task create request. |
| // |
| // Snapshots referenced in this field will not be garbage collected. |
| // |
| // This field is set to empty when the rootfs is not a snapshot. |
| // |
| // This field may be updated. |
| string snapshot_key = 7; |
| |
| // CreatedAt is the time the container was first created. |
| google.protobuf.Timestamp created_at = 8 [(gogoproto.stdtime) = true, (gogoproto.nullable) = false]; |
| |
| // UpdatedAt is the last time the container was mutated. |
| google.protobuf.Timestamp updated_at = 9 [(gogoproto.stdtime) = true, (gogoproto.nullable) = false]; |
| |
| // Extensions allow clients to provide zero or more blobs that are directly |
| // associated with the container. One may provide protobuf, json, or other |
| // encoding formats. The primary use of this is to further decorate the |
| // container object with fields that may be specific to a client integration. |
| // |
| // The key portion of this map should identify a "name" for the extension |
| // that should be unique against other extensions. When updating extension |
| // data, one should only update the specified extension using field paths |
| // to select a specific map key. |
| map<string, google.protobuf.Any> extensions = 10 [(gogoproto.nullable) = false]; |
| } |
| |
| message GetContainerRequest { |
| string id = 1; |
| } |
| |
| message GetContainerResponse { |
| Container container = 1 [(gogoproto.nullable) = false]; |
| } |
| |
| message ListContainersRequest { |
| // Filters contains one or more filters using the syntax defined in the |
| // containerd filter package. |
| // |
| // The returned result will be those that match any of the provided |
| // filters. Expanded, containers that match the following will be |
| // returned: |
| // |
| // filters[0] or filters[1] or ... or filters[n-1] or filters[n] |
| // |
| // If filters is zero-length or nil, all items will be returned. |
| repeated string filters = 1; |
| } |
| |
| message ListContainersResponse { |
| repeated Container containers = 1 [(gogoproto.nullable) = false]; |
| } |
| |
| message CreateContainerRequest { |
| Container container = 1 [(gogoproto.nullable) = false]; |
| } |
| |
| message CreateContainerResponse { |
| Container container = 1 [(gogoproto.nullable) = false]; |
| } |
| |
| // UpdateContainerRequest updates the metadata on one or more container. |
| // |
| // The operation should follow semantics described in |
| // https://developers.google.com/protocol-buffers/docs/reference/csharp/class/google/protobuf/well-known-types/field-mask, |
| // unless otherwise qualified. |
| message UpdateContainerRequest { |
| // Container provides the target values, as declared by the mask, for the update. |
| // |
| // The ID field must be set. |
| Container container = 1 [(gogoproto.nullable) = false]; |
| |
| // UpdateMask specifies which fields to perform the update on. If empty, |
| // the operation applies to all fields. |
| google.protobuf.FieldMask update_mask = 2; |
| } |
| |
| message UpdateContainerResponse { |
| Container container = 1 [(gogoproto.nullable) = false]; |
| } |
| |
| message DeleteContainerRequest { |
| string id = 1; |
| } |