├── README.md └── proto └── v1alpha1 ├── meta.proto ├── resource.proto └── state.proto /README.md: -------------------------------------------------------------------------------- 1 | # specification 2 | Common Operating System Interface Specification 3 | -------------------------------------------------------------------------------- /proto/v1alpha1/meta.proto: -------------------------------------------------------------------------------- 1 | syntax = "proto3"; 2 | 3 | // Meta package defines protobuf serialization of standard COSI resources from the 'meta' namespace. 4 | package cosi.resource.meta; 5 | 6 | option go_package = "github.com/cosi-project/runtime/api/v1alpha1"; 7 | 8 | // NamespaceSpec is the protobuf serialization of the Namespace resource. 9 | message NamespaceSpec { 10 | // Description of the namespace. 11 | string description = 1; 12 | } 13 | 14 | // ResourceDefinitionSpec is the protobuf serialization of the ResourceDefinition resource. 15 | message ResourceDefinitionSpec { 16 | // Canonical type name. 17 | string resource_type = 1; 18 | // Displayed human-readable type name. 19 | string display_type = 2; 20 | 21 | // Default namespace to look for the resource if no namespace is given. 22 | string default_namespace = 3; 23 | 24 | // Human-readable aliases. 25 | repeated string aliases = 4; 26 | // All aliases for automatic matching. 27 | repeated string all_aliases = 5; 28 | 29 | message PrintColumn { 30 | string name = 1; 31 | string json_path = 2; 32 | } 33 | 34 | // Additional columns to print in table output. 35 | repeated PrintColumn print_columns = 6; 36 | 37 | enum Sensitivity { 38 | NON_SENSITIVE = 0; 39 | SENSITIVE = 1; 40 | } 41 | 42 | // Sensitivity indicates how secret resource of this type is. 43 | // The empty value represents a non-sensitive resource. 44 | Sensitivity sensitivity = 7; 45 | } 46 | -------------------------------------------------------------------------------- /proto/v1alpha1/resource.proto: -------------------------------------------------------------------------------- 1 | syntax = "proto3"; 2 | 3 | // Resource package defines protobuf serialization of COSI resources. 4 | package cosi.resource; 5 | 6 | option go_package = "github.com/cosi-project/runtime/api/v1alpha1"; 7 | 8 | import "google/protobuf/timestamp.proto"; 9 | 10 | // Metadata represents resource metadata. 11 | // 12 | // (namespace, type, id) is a resource pointer. 13 | // (version) is a current resource version. 14 | // (owner) is filled in for controller-managed resources with controller name. 15 | // (phase) indicates whether resource is going through tear down phase. 16 | // (finalizers) are attached controllers blocking teardown of the resource. 17 | // (labels) and (annotations) are free-form key-value pairs; labels allow queries. 18 | message Metadata { 19 | string namespace = 1; 20 | string type = 2; 21 | string id = 3; 22 | string version = 4; 23 | string owner = 5; 24 | string phase = 6; 25 | google.protobuf.Timestamp created = 7; 26 | google.protobuf.Timestamp updated = 8; 27 | repeated string finalizers = 9; 28 | map annotations = 11; 29 | map labels = 10; 30 | } 31 | 32 | // Spec defines content of the resource. 33 | message Spec { 34 | // Protobuf-serialized representation of the resource. 35 | bytes proto_spec = 1; 36 | // YAML representation of the spec (optional). 37 | string yaml_spec = 2; 38 | } 39 | 40 | // Resource is a combination of metadata and spec. 41 | message Resource { 42 | Metadata metadata = 1; 43 | Spec spec = 2; 44 | } 45 | 46 | // LabelTerm is an expression on a label. 47 | message LabelTerm { 48 | enum Operation { 49 | // Label exists. 50 | EXISTS = 0; 51 | // Label value is equal. 52 | EQUAL = 1; 53 | // Label doesn't exist. 54 | NOT_EXISTS = 2 [deprecated=true]; 55 | // Label value is in the set. 56 | IN = 3; 57 | // Label value is less. 58 | LT = 4; 59 | // Label value is less or equal. 60 | LTE = 5; 61 | // Label value is less than number. 62 | LT_NUMERIC = 6; 63 | // Label value is less or equal numeric. 64 | LTE_NUMERIC = 7; 65 | } 66 | 67 | string key = 1; 68 | Operation op = 2; 69 | repeated string value = 3; 70 | // Inverts the condition. 71 | bool invert = 5; 72 | } 73 | 74 | // LabelQuery is a query on resource metadata labels. 75 | // 76 | // Terms are combined with AND. 77 | message LabelQuery { 78 | repeated LabelTerm terms = 1; 79 | } 80 | 81 | // IDQuery is a query on resource metadata ID. 82 | message IDQuery { 83 | string regexp = 1; 84 | } 85 | -------------------------------------------------------------------------------- /proto/v1alpha1/state.proto: -------------------------------------------------------------------------------- 1 | syntax = "proto3"; 2 | 3 | package cosi.resource; 4 | 5 | option go_package = "github.com/cosi-project/runtime/api/v1alpha1"; 6 | 7 | import "v1alpha1/resource.proto"; 8 | 9 | enum EventType { 10 | CREATED = 0; 11 | UPDATED = 1; 12 | DESTROYED = 2; 13 | BOOTSTRAPPED = 3; 14 | ERRORED = 4; 15 | NOOP = 5; 16 | } 17 | 18 | // Event is emitted when resource changes. 19 | message Event { 20 | Resource resource = 1; 21 | Resource old = 3; 22 | optional string error = 4; 23 | EventType event_type = 2; 24 | optional bytes bookmark = 5; 25 | } 26 | 27 | service State { 28 | // Get a resource by type and ID. 29 | // 30 | // If a resource is not found, error is returned. 31 | rpc Get(GetRequest) returns (GetResponse); 32 | 33 | // List resources by type. 34 | rpc List(ListRequest) returns (stream ListResponse); 35 | 36 | // Create a resource. 37 | // 38 | // If a resource already exists, Create returns an error. 39 | rpc Create(CreateRequest) returns (CreateResponse); 40 | 41 | // Update a resource. 42 | // 43 | // If a resource doesn't exist, error is returned. 44 | // On update current version of resource `new` in the state should match 45 | // curVersion, otherwise conflict error is returned. 46 | rpc Update(UpdateRequest) returns (UpdateResponse); 47 | 48 | // Destroy a resource. 49 | // 50 | // If a resource doesn't exist, error is returned. 51 | // If a resource has pending finalizers, error is returned. 52 | rpc Destroy(DestroyRequest) returns (DestroyResponse); 53 | 54 | // Watch state of a resource by (namespace, type) or a specific resource by (namespace, type, id). 55 | // 56 | // It's fine to watch for a resource which doesn't exist yet. 57 | // Watch is canceled when context gets canceled. 58 | // Watch sends initial resource state as the very first event on the channel, 59 | // and then sends any updates to the resource as events. 60 | rpc Watch(WatchRequest) returns (stream WatchResponse); 61 | } 62 | 63 | // Get RPC 64 | 65 | message GetRequest { 66 | string namespace = 1; 67 | string type = 2; 68 | string id = 3; 69 | 70 | GetOptions options = 4; 71 | } 72 | 73 | message GetOptions { 74 | } 75 | 76 | message GetResponse { 77 | resource.Resource resource = 1; 78 | } 79 | 80 | // List RPC 81 | 82 | message ListRequest { 83 | string namespace = 1; 84 | string type = 2; 85 | 86 | ListOptions options = 3; 87 | } 88 | 89 | message ListOptions { 90 | repeated resource.LabelQuery label_query = 1; 91 | resource.IDQuery id_query = 2; 92 | } 93 | 94 | message ListResponse { 95 | resource.Resource resource = 1; 96 | } 97 | 98 | // Create RPC 99 | 100 | message CreateRequest { 101 | resource.Resource resource = 1; 102 | 103 | CreateOptions options = 2; 104 | } 105 | 106 | message CreateOptions { 107 | string owner = 1; 108 | } 109 | 110 | message CreateResponse { 111 | resource.Resource resource = 1; 112 | } 113 | 114 | // Update RPC 115 | 116 | message UpdateRequest { 117 | reserved 1; 118 | reserved "current_version"; 119 | 120 | resource.Resource new_resource = 2; 121 | 122 | UpdateOptions options = 3; 123 | } 124 | 125 | message UpdateOptions { 126 | string owner = 1; 127 | optional string expected_phase = 2; 128 | } 129 | 130 | message UpdateResponse { 131 | resource.Resource resource = 1; 132 | } 133 | 134 | // Destroy RPC 135 | 136 | message DestroyRequest { 137 | string namespace = 1; 138 | string type = 2; 139 | string id = 3; 140 | 141 | DestroyOptions options = 4; 142 | } 143 | 144 | message DestroyOptions { 145 | string owner = 1; 146 | } 147 | 148 | message DestroyResponse { 149 | } 150 | 151 | // Watch RPC 152 | 153 | message WatchRequest { 154 | string namespace = 1; 155 | string type = 2; 156 | optional string id = 3; 157 | 158 | WatchOptions options = 4; 159 | 160 | // Supported API versions: 161 | // 0 (not set): event types Created,Updated,Deleted 162 | // 1: additional event types Bootstrapped,Errored 163 | int32 api_version = 5; 164 | } 165 | 166 | message WatchOptions { 167 | bool bootstrap_contents = 1; 168 | int32 tail_events = 2; 169 | repeated resource.LabelQuery label_query = 3; 170 | resource.IDQuery id_query = 4; 171 | bool aggregated = 5; 172 | optional bytes start_from_bookmark = 6; 173 | bool bootstrap_bookmark = 7; 174 | } 175 | 176 | message WatchResponse { 177 | repeated Event event = 1; 178 | } 179 | --------------------------------------------------------------------------------