Adding GRPC Definitions (kubernetes#18)

keps/sig-storage/20191125-bucket-provisioning.md

@@ -484,3 +484,355 @@ cosi.io/provisioner-secret-namespace:
   cosi.io/provisioner-secret-name: "${bucket.name}"
   cosi.io/provisioner-secret-namespace: "${bucket.namespace}"
   ```
+
+# GRPC Definitions
+```protobuf
+ syntax = "proto3";
+
+ package cosi.v1;
+
+ import "google/protobuf/descriptor.proto";
+
+ option go_package = "github.com/container-object-store-interface/go-cosi";
+
+ extend google.protobuf.MessageOptions {
+
+     // cosi_secret should be used to designate messages containing sensitive data
+     //             to provide protection against that data being logged or otherwise leaked.
+     bool cosi_secret = 1000;
+ }
+
+ message DriverInfoRequest {
+     // INTENTIONALLY BLANK
+ }
+
+ // DataProtocol defines a set of constants used in Create and Grant requests.
+ enum DataProtocol {
+     PROTOCOL_UNSPECIFIED = 0;
+     AZURE_BLOB = 1;
+     GCS = 2;
+     S3 = 3;
+ }
+
+ // AccessMode defines a common set of permissions among object stores
+ enum AccessMode {
+     MODE_UNSPECIFIED = 0;
+     RO = 1;
+     WO = 2;
+     RW = 3;
+ }
+
+ // S3SignatureVersion defines the 2 supported versions of S3's authentication
+ enum S3SignatureVersion {
+     VERSION_UNSPECIFIED = 0;
+     V2 = 1;
+     V4 = 2;
+ }
+
+ message DriverInfoResponse {
+     // DriverName
+     string DriverName = 1;
+
+     // SupportedProtocols
+     repeated DataProtocol SupportedProtocols = 2;
+
+     // NextId = 3;
+ }
+ 
+ message S3Context {
+     // returns the location where bucket will be created
+     string location = 1
+ }
+
+message GCSContext {
+   // returns the location where bucket is created
+   string location = 1
+   // returns the project the bucket belongs to
+   string project = 2
+}
+
+message AzureContext {
+}
+
+message GenericContext {
+     // generic output content
+     map<string, string> bucket_data
+}
+
+message ProviderContext {
+     oneof {
+          S3Context
+          GCSContext
+          AzureContext
+          GenericContext
+     }
+}
+
+message Bucket {
+  // Name is the name of the bucket
+  string name = 1
+  // provisioner used to create and other bucket operations
+  // ProjectName this bucket created under
+  ProviderContext provider_context = 2 //- { azure_context, gcs_context, s3_context, generic_context}
+  string provisioner = 3
+  // access mode
+  AccessMode access_mode = 4;
+    
+}
+
+
+ message CreateBucketRequest {
+     // bucket_name, This field is REQUIRED.
+     // Maintain Idempotency. 
+     //    In the case of error, the CO MUST handle the gRPC error codes
+     //    per the recovery behavior defined in the "CreateBucket Errors"
+     //    section below.
+     // BucketRequest:name 
+     string bucket_name = 1;
+
+     // RequestProtocol, one of the predefined values
+     // Driver must check the protocol used to match 
+     // BucketClass:supportedProtocols - {"azureblob", "gcs", "s3", ... } [3]
+     // BucketRequest:protocol - use this as request protocol but check 
+     // if the protocol is in the BucketClass' suppportedProtocols
+     DataProtocol request_protocol = 2;
+
+     // DriverParameters, these are parameters that are extracted from 
+     // BuckerRequest and BucketClass so that the call has context.
+     // For example GCS require projectName for CreateBucket to succeed.
+     // BucketClass:provisioner - identify the  
+     // projectID if GCS
+     ProviderContext provider_context = 3 //- { azure_context, gcs_context, s3_context, generic_context}
+     map<string, string> driver_parameters = 4;  
+
+     // AccessMode is requested as RO, RW, WO and depends on driver.
+     // If driver supports access mode if not ignores it
+     // BucketClass:accessMode - {"ro", "wo", "rw"} [4]
+     AccessMode access_mode = 5;
+
+     // Information required to make createBucket call. This field is REQUIRED
+     // A series of tokens, user name, etc based on protocol choice
+     // BucketRequest:secretName will provide necessary security token to
+     // connect to the provider API.  
+     // Azure:
+     //    message AuthenticationData {
+     //        option (cosi_secret) = true;
+     //        string StorageAccountName = 1;
+     //        string AccountKey = 2;
+     //        string SasToken = 3;
+     //    }
+     // GCS:
+     //    message AuthenticationData {
+     //        option (cosi_secret) = true;
+     //        string StorageAccountName = 1;
+     //        string PrivateKeyName = 2;
+     //        string PrivateKey = 3;
+     //    }
+     // S3:
+     //    message AuthenticationData {
+     //        option (cosi_secret) = true;
+     //        string AccessKeyId = 1;
+     //        string SecretKey = 2;
+     //        string StsToken = 3;
+     //        string UserName = 4;
+     //    }
+     map<string, string> secrets = 6;
+ }
+
+
+CREATE_INVALID_ARGUMENT    : validation of the input argument fails 
+CREATE_INVALID_PROTOCOL    : driver does not support the protocol
+CREATE_ALREADY_EXISTS      : resource already exists 
+CREATE_INVALID_CREDENTIALS : resource creation failed due to invalid credentials 
+CREATE_INTERNAL_ERROR      : Failed to execute the requested call
+
+ message CreateBucketResponse {
+     // Bucket returned
+     Bucket bucket
+ }
+ 
+ message DeleteBucketRequest {
+     // The name of the bucket to be deleted.
+     // This field is REQUIRED.
+     string bucket_name = 1;
+    
+     // RequestProtocol, one of the predefined values
+     // Driver must check the protocol used to match 
+     // BucketClass:supportedProtocols - {"azureblob", "gcs", "s3", ... } [3]
+     // BucketRequest:protocol - use this as request protocol but check 
+     // if the protocol is in the BucketClass' suppportedProtocols
+     DataProtocol request_protocol = 2;
+
+     // DriverParameters, these are parameters that are extracted from 
+     // BuckerRequest and BucketClass so that the call has context.
+     // For example GCS require projectName for CreateBucket to succeed.
+     // BucketClass:provisioner - identify the  
+     // projectID if GCS
+     ProviderContext provider_context = 3 - { azure_context, gcs_context, s3_context, generic_context}
+     map<string, string> driver_parameters = 4; //provider_context
+  
+     // Secrets required by driver to complete bucket deletion request.
+     // This field is OPTIONAL. Refer to the `Secrets Requirements`
+     // section on how to use this field.
+     // Azure:
+     //    message AuthenticationData {
+     //        option (cosi_secret) = true;
+     //        string StorageAccountName = 1;
+     //        string AccountKey = 2;
+     //        string SasToken = 3;
+     //    }
+     // GCS:
+     //    message AuthenticationData {
+     //        option (cosi_secret) = true;
+     //        string StorageAccountName = 1;
+     //        string PrivateKeyName = 2;
+     //        string PrivateKey = 3;
+     //    }
+     // S3:
+     //    message AuthenticationData {
+     //        option (cosi_secret) = true;
+     //        string AccessKeyId = 1;
+     //        string SecretKey = 2;
+     //        string StsToken = 3;
+     //        string UserName = 4;
+     //    }
+     map<string, string> secrets = 5
+}
+
+
+
+ message DeleteBucketResponse {
+     // INTENTIONALLY BLANK
+ }
+
+DELETE_BUCKET_DOESNOT_EXIST : Bucket specified does not exist 
+DELETE_DELETE_INPROGRESS    : Delete bucket is in progress
+DELETE_INVALID_CREDENTIALS  : resource deletion failed due to invalid credentials
+DELETE_INTERNAL_ERROR       : Failed to execute the requested call
+DELETE_INVALID_ARGUMENT     : validation of the input argument fails 
+
+
+
+service CosiController {
+  rpc CreateBucket (CreateBucketRequest)
+    returns (CreateBucketResponse) {}
+
+  rpc DeleteBucket (DeleteBucketRequest)
+    returns (DeleteBucketResponse) {}
+}
+
+
+ message S3Credentials {
+      string id = 1 // one of id, emailid, uri
+      string permission = 1
+      string owner
+ }
+
+message GCSCredentials {
+     string entity = 1 //one ot userid, emailid, groupid, etc or 'allusers/allAuthenticatedUsers
+     string role = 2
+     string domain = 3
+     string project = 4
+}
+
+message AzureCredentials {
+     string id
+     string permission
+}
+
+message GenericCredentials {
+     // generic output content
+     map<string, string> credentials
+}
+
+message ProviderCredentials {
+     oneof {
+          S3Credentials
+          GCSCredentials
+          AzureCredentials
+          GenericCredentials
+     }
+}
+
+
+ message GrantBucketAccessRequest {
+     // The name of the bucket to be granted access.
+     // This field is REQUIRED.
+     string bucket_name = 1;
+
+     // RequestProtocol, one of the predefined values
+     // Driver must check the protocol used to match 
+     // BucketClass:supportedProtocols - {"azureblob", "gcs", "s3", ... } [3]
+     // BucketRequest:protocol - use this as request protocol but check 
+     // if the protocol is in the BucketClass' suppportedProtocols
+     DataProtocol request_protocol = 2;
+
+     // permission granted
+     map<string,string> permissions = 3 
+
+     // provisioner used to create and other bucket operations
+     // ProjectName this bucket created under
+     ProviderContext provider_context = 4 - { azure_context, gcs_context, s3_context, generic_context}
+
+     map<string,string> secrets
+ }
+
+ message GrantBucketAccessResponse {
+     // No data returned by this call other than error or success code
+     repeated ProviderCredentials creds
+ }
+
+
+GRANT_BUCKET_DOESNOT_EXIST : Bucket specified does not exist 
+GRANT_INVALID_CREDENTIALS  : resource deletion failed due to invalid credentials
+GRANT_INTERNAL_ERROR       : Failed to execute the requested call
+GRANT_INVALID_ARGUMENT     : validation of the input argument fails
+GRANT_INVALID_PRINCIPAL    : Failed to grant, principal provided is invalid 
+
+
+
+ message RevokeBucketAccessRequest {
+     // The name of the bucket to be granted access.
+     // This field is REQUIRED.
+     string bucket_name = 1;
+
+     // RequestProtocol, one of the predefined values
+     // Driver must check the protocol used to match 
+     // BucketClass:supportedProtocols - {"azureblob", "gcs", "s3", ... } [3]
+     // BucketRequest:protocol - use this as request protocol but check 
+     // if the protocol is in the BucketClass' suppportedProtocols
+     DataProtocol request_protocol = 2;
+
+     // the service_account from which permissions are revoked
+     ProviderCredentials service_account
+
+     // permission revoked
+     map<string,string> permissions = 3 
+
+     // provisioner used to create and other bucket operations
+     // ProjectName this bucket created under
+     ProviderContext provider_context = 4 - { azure_context, gcs_context, s3_context, generic_context}
+
+     map<string,string> secrets
+
+ }
+
+ message RevokeBucketAccessResponse {
+     // No data returned by this call other than error or success code
+     repeated ProviderCredentials creds    
+ }
+
+REVOKE_BUCKET_DOESNOT_EXIST : Bucket specified does not exist 
+REVOKE_INVALID_CREDENTIALS  : resource deletion failed due to invalid credentials
+REVOKE_INTERNAL_ERROR       : Failed to execute the requested call
+REVOKE_INVALID_ARGUMENT     : validation of the input argument fails
+REVOKE_INVALID_PRINCIPAL    : Failed to grant, principal provided is invalid 
+
+
+
+ service CosiController {
+     rpc GrantBucketAccess (GrantBucketAccessRequest) returns (GrantBucketAccessResponse);
+     rpc RevokeBucketAccess (RevokeBucketAccessRequest) returns (RevokeBucketAccessResponse);
+}
+
+