api/services/leases/v1/leases.proto

/*
	Copyright The containerd Authors.

	Licensed under the Apache License, Version 2.0 (the "License");
	you may not use this file except in compliance with the License.
	You may obtain a copy of the License at

		http://www.apache.org/licenses/LICENSE-2.0

	Unless required by applicable law or agreed to in writing, software
	distributed under the License is distributed on an "AS IS" BASIS,
	WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	See the License for the specific language governing permissions and
	limitations under the License.
*/
syntax = "proto3";

package containerd.services.leases.v1;

import "google/protobuf/empty.proto";
import "google/protobuf/timestamp.proto";

option go_package = "github.com/containerd/containerd/api/services/leases/v1;leases";

// Leases service manages resources leases within the metadata store.
service Leases {
	// Create creates a new lease for managing changes to metadata. A lease
	// can be used to protect objects from being removed.
	rpc Create(CreateRequest) returns (CreateResponse);

	// Delete deletes the lease and makes any unreferenced objects created
	// during the lease eligible for garbage collection if not referenced
	// or retained by other resources during the lease.
	rpc Delete(DeleteRequest) returns (google.protobuf.Empty);

	// List lists all active leases, returning the full list of
	// leases and optionally including the referenced resources.
	rpc List(ListRequest) returns (ListResponse);

	// AddResource references the resource by the provided lease.
	rpc AddResource(AddResourceRequest) returns (google.protobuf.Empty);

	// DeleteResource dereferences the resource by the provided lease.
	rpc DeleteResource(DeleteResourceRequest) returns (google.protobuf.Empty);

	// ListResources lists all the resources referenced by the lease.
	rpc ListResources(ListResourcesRequest) returns (ListResourcesResponse);
}

// Lease is an object which retains resources while it exists.
message Lease {
	string id = 1;

	google.protobuf.Timestamp created_at = 2;

	map<string, string> labels = 3;
}

message CreateRequest {
	// ID is used to identity the lease, when the id is not set the service
	// generates a random identifier for the lease.
	string id = 1;

	map<string, string> labels = 3;
}

message CreateResponse {
	Lease lease = 1;
}

message DeleteRequest {
	string id = 1;

	// Sync indicates that the delete and cleanup should be done
	// synchronously before returning to the caller
	//
	// Default is false
	bool sync = 2;
}

message ListRequest {
	repeated string filters = 1;
}

message ListResponse {
	repeated Lease leases = 1;
}

message Resource {
	string id = 1;

	// For snapshotter resource, there are many snapshotter types here, like
	// overlayfs, devmapper etc. The type will be formatted with type,
	// like "snapshotter/overlayfs".
	string type = 2;
}

message AddResourceRequest {
	string id = 1;

	Resource resource = 2;
}

message DeleteResourceRequest {
	string id = 1;

	Resource resource = 2;
}

message ListResourcesRequest {
	string id = 1;
}

message ListResourcesResponse {
	repeated Resource resources = 1	;
}