From b2087e45176a2dcda600bc34f453b3a68f6e031c Mon Sep 17 00:00:00 2001 From: Praveen M Date: Tue, 20 Feb 2024 19:51:07 +0530 Subject: [PATCH] doc: added docs for Azure KMS Signed-off-by: Praveen M --- PendingReleaseNotes.md | 2 + docs/deploy-rbd.md | 27 +++++++++ .../encryption-with-azure-keyvault.md | 58 +++++++++++++++++++ 3 files changed, 87 insertions(+) create mode 100644 docs/design/proposals/encryption-with-azure-keyvault.md diff --git a/PendingReleaseNotes.md b/PendingReleaseNotes.md index 7b9f1dd83..8f85d3bf5 100644 --- a/PendingReleaseNotes.md +++ b/PendingReleaseNotes.md @@ -4,4 +4,6 @@ ## Features +- kms: added Azure Key Vault as a supported KMS in [PR](https://github.com/ceph/ceph-csi/pull/4455) + ## NOTE diff --git a/docs/deploy-rbd.md b/docs/deploy-rbd.md index 7a8512a5f..e493113b9 100644 --- a/docs/deploy-rbd.md +++ b/docs/deploy-rbd.md @@ -448,6 +448,33 @@ the AWS KMS is expected to contain: This Secret is expected to be created by the tenant/user in each namespace where Ceph-CSI is used to create encrypted rbd volumes. +#### Configuring Azure key vault + +Ceph-CSI can be configured to use +[Azure key vault](https://azure.microsoft.com/en-in/products/key-vault), +for encrypting RBD volumes. + +There are a few settings that need to be included in the [KMS configuration +file](../examples/kms/vault/kms-config.yaml): + +1. `KMS_PROVIDER`: should be set to `azure-kv`. +1. `AZURE_CERT_SECRET_NAME`: name of the Kubernetes Secret (in the Namespace where + Ceph-CSI is deployed) which contains the credentials for communicating with + Azure. This defaults to `ceph-csi-azure-credentials`. +1. `AZURE_VAULT_URL`: URL to access the Azure Key Vault service. +1. `AZURE_CLIENT_ID`: Client ID of the Azure application object (service principal) + created in Azure Active Directory that serves as the username. +1. `AZURE_TENANT_ID`: Tenant ID of the service principal. + +The [Secret with credentials](../examples/kms/vault/azure-credentials.yaml) for +the Azure KMS is expected to contain: + +1. `CLIENT_CERT`: The client certificate used for authentication + with Azure Key Vault. + +This Secret is expected to be created by the user in the namespace where Ceph-CSI +is deployed. + #### Configuring KMIP KMS The Key Management Interoperability Protocol (KMIP) is an extensible diff --git a/docs/design/proposals/encryption-with-azure-keyvault.md b/docs/design/proposals/encryption-with-azure-keyvault.md new file mode 100644 index 000000000..b6794fe0b --- /dev/null +++ b/docs/design/proposals/encryption-with-azure-keyvault.md @@ -0,0 +1,58 @@ +# Encrypted volumes with Azure Key Vault + +Azure Key Vault is a cloud service for securely storing and accessing secrets. +A secret is anything that you want to tightly control access to, such as API +keys, passwords, certificates, or cryptographic keys. + +## Connection to Azure Key Vault + +Below values are used to establish the connection to the Key Vault +service from the CSI driver and to make use of the secrets +`GetSecret`/`SetSecret`/`DeleteSecret` operations: + +```text +* AZURE_VAULT_URL +The URL used to access the Azure Key Vault service. + +* AZURE_CLIENT_ID +The Client ID of the Azure application object (also known as the service principal). +This ID serves as the username. + +* AZURE_TENANT_ID +The Tenant ID associated with the service principal. + +* CLIENT_CERT +The client certificate (which includes the private key and is not password protected) +used for authentication with Azure Key Vault. +``` + +### Values provided in the connection secret + +Considering `AZURE_CLIENT_CERTIFICATE` is sensitive information, +it will be provided as a Kubernetes secret to the Ceph-CSI driver. The Ceph-CSI +KMS plugin interface for the Azure key vault will read the secret name from the +kms configMap and fetch the certificate. + +### Values provided in the config map + +`AZURE_VAULT_URL`, `AZURE_CLIENT_ID`, `AZURE_TENANT_ID` are part of the +KMS ConfigMap. + +### Storage class values or configuration + +The Storage class has to be enabled for encryption and `encryptionKMSID` has +to be provided which is the matching value in the kms config map. + +## Volume Encrypt or Decrypt Operation + +Ceph-CSI generate's unique passphrase for each volume to be used to +encrypt/decrypt. The passphrase is securely store in Azure key vault +using the `SetSecret` operation. At time of decrypt the passphrase is +retrieved from the key vault using the `GetSecret`operation. + +## Volume Delete Operation + +When the corresponding volume is deleted, the stored secret in the Azure Key +Vault will be deleted. + +> Note: Ceph-CSI solely deletes the secret without permanent removal (purging).