-
Notifications
You must be signed in to change notification settings - Fork 20
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
This patch adds specification for EncryptionKeyRotation operation of CSI addons. Signed-off-by: black-dragon74 <[email protected]>
- Loading branch information
1 parent
fd8ce6b
commit 4c51293
Showing
6 changed files
with
530 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,20 @@ | ||
| # Copyright 2024 The csi-addons Authors. All rights reserved. | ||
| # | ||
| # 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. | ||
|
|
||
| PROTO := encryptionkeyrotation.proto | ||
| PROTO_SOURCE := README.md | ||
|
|
||
| all: install-deps $(PROTO) build | ||
|
|
||
| include ../release-tools/build.make |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,95 @@ | ||
| # CSI Addons Operation: EncryptionKeyRotation | ||
|
|
||
| ## Terminology | ||
|
|
||
| | Term | Definition | | ||
| | -------- | ------------------------------------------------------------------------------------- | | ||
| | VolumeID | The identifier of the volume generated by the plugin. | | ||
| | CO | Container Orchestration system that communicates with plugins using CSI service RPCs. | | ||
| | SP | Storage Provider, the vendor of a CSI plugin implementation. | | ||
| | RPC | [Remote Procedure Call](https://en.wikipedia.org/wiki/Remote_procedure_call). | | ||
|
|
||
| ## Objective | ||
|
|
||
| Define an extension to the CSI specification that will enable storage vendors | ||
| (SP) to develop controllers/plugins that can rotate the Encryption Keys (KEK) | ||
| of existing volumes that are encrypted. | ||
|
|
||
| ### Goals in MVP | ||
|
|
||
| The new extension will define a procedure that | ||
|
|
||
| - can be called for existing encrypted volumes | ||
| - functions for Block mode volumes | ||
| - interacts with the Node-Plugin | ||
| - makes it possible for the SP to rotate encrpytion keys on volumes | ||
|
|
||
| ### Non-Goals in MVP | ||
|
|
||
| - Rotating encrpytion keys for inactive volumes | ||
|
|
||
| ## Solution Overview | ||
|
|
||
| This specification defines an interface along with the minimum operational and | ||
| packaging recommendations for a storage provider (SP) to implement a key rotate operation for volumes. The interface declares the RPCs that a plugin | ||
| MUST expose. | ||
|
|
||
| ## RPC Interface | ||
|
|
||
| - **Node Service**: The Node plugin MAY implement this RPC. | ||
|
|
||
| ```protobuf | ||
| syntax = "proto3"; | ||
| package encryptionkeyrotation; | ||
| import "github.com/container-storage-interface/spec/lib/go/csi/csi.proto"; | ||
| import "google/protobuf/descriptor.proto"; | ||
| option go_package = "github.com/csi-addons/spec/lib/go/encryptionkeyrotation"; | ||
| // EncryptionKeyRotationController holds the RPC method for running | ||
| // key rotation operation on the volume. | ||
| service EncryptionKeyRotationController { | ||
| // EncryptionKeyRotate is a procedure that is called on the CSI Nodeplugin | ||
| rpc EncryptionKeyRotate(EncryptionKeyRotateRequest) | ||
| returns (EncryptionKeyRotateResponse){} | ||
| } | ||
| ``` | ||
|
|
||
| ### EncryptionKeyRotateRequest | ||
|
|
||
| ```protobuf | ||
| // EncryptionKeyRotateRequest contains the information needed to identify | ||
| // the volume by the SP and access any backend services so that the key can be | ||
| // rotated. | ||
| message EncryptionKeyRotateRequest { | ||
| // The ID of the volume for which the key is to be rotated. This field is REQUIRED. | ||
| string volume_id = 1; | ||
| // Plugin specific parameters passed in as opaque key-value pairs. | ||
| map<string, string> parameters = 2; | ||
| // Secrets required by the plugin to complete the request. | ||
| map<string, string> secrets = 3 [(csi.v1.csi_secret) = true]; | ||
| } | ||
| ``` | ||
|
|
||
| ### EncryptionKeyRotateResponse | ||
|
|
||
| ```protobuf | ||
| // EncryptionKeyRotateResponse holds the information about the result of the | ||
| // EncryptionKeyRotateRequest call. | ||
| message EncryptionKeyRotateResponse { | ||
| } | ||
| ``` | ||
|
|
||
| ### Error Schemes | ||
|
|
||
| | Condition | gRPC Code | Description | Recovery Behavior | | ||
| | ---------------------------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ||
| | Missing required field | 3 INVALID_ARGUMENT | Indicates that a required field is missing from the request. | Caller MUST fix the request by adding the missing required field before retrying. | | ||
| | Volume does not exist | 5 NOT_FOUND | Indicates that a volume corresponding to the specified `volume_id` does not exist. | Caller MUST verify that the `volume_id` is correct and that the volume is accessible and has not been deleted before retrying with exponential back off. | | ||
| | Operation pending for volume | 10 ABORTED | Indicates that there is already an operation pending for the specified `volume_id`. In general the CSI-Addons CO plugin is responsible for ensuring that there is no more than one call "in-flight" per `volume_id` at a given time. However, in some circumstances, the CSI-Addons CO plugin MAY lose state (for example when the it crashes and restarts), and MAY issue multiple calls simultaneously for the same `volume_id`. The CSI-driver, SHOULD handle this as gracefully as possible, and MAY return this error code to reject secondary calls. | Caller SHOULD ensure that there are no other calls pending for the specified `volume_id`, and then retry with exponential back off. | | ||
| | Not authenticated | 16 UNAUTHENTICATED | The invoked RPC does not carry secrets that are valid for authentication. | Caller SHALL either fix the secrets provided in the RPC, or otherwise regalvanize said secrets such that they will pass authentication by the Plugin for the attempted RPC, after which point the caller MAY retry the attempted RPC. | | ||
| | Error is Unknown | 2 UNKNOWN | Indicates that a unknown error is generated | Caller MUST study the logs before retrying | |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,34 @@ | ||
| // Code generated by make; DO NOT EDIT. | ||
| syntax = "proto3"; | ||
| package encryptionkeyrotation; | ||
|
|
||
| import "github.com/container-storage-interface/spec/lib/go/csi/csi.proto"; | ||
| import "google/protobuf/descriptor.proto"; | ||
|
|
||
| option go_package = "github.com/csi-addons/spec/lib/go/encryptionkeyrotation"; | ||
|
|
||
| // EncryptionKeyRotationController holds the RPC method for running | ||
| // key rotation operation on the volume. | ||
| service EncryptionKeyRotationController { | ||
| // EncryptionKeyRotate is a procedure that is called on the CSI Nodeplugin | ||
| rpc EncryptionKeyRotate(EncryptionKeyRotateRequest) | ||
| returns (EncryptionKeyRotateResponse){} | ||
| } | ||
| // EncryptionKeyRotateRequest contains the information needed to identify | ||
| // the volume by the SP and access any backend services so that the key can be | ||
| // rotated. | ||
| message EncryptionKeyRotateRequest { | ||
| // The ID of the volume for which the key is to be rotated. This field is REQUIRED. | ||
| string volume_id = 1; | ||
|
|
||
| // Plugin specific parameters passed in as opaque key-value pairs. | ||
| map<string, string> parameters = 2; | ||
|
|
||
| // Secrets required by the plugin to complete the request. | ||
| map<string, string> secrets = 3 [(csi.v1.csi_secret) = true]; | ||
| } | ||
| // EncryptionKeyRotateResponse holds the information about the result of the | ||
| // EncryptionKeyRotateRequest call. | ||
| message EncryptionKeyRotateResponse { | ||
|
|
||
| } |
Oops, something went wrong.