From bf7e5d9301bddc8e54bb103973ce123a7c66b5da 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 --- docs/deploy-rbd.md | 27 +++++++++ .../encryption-with-azure-keyvault.md | 58 +++++++++++++++++++ 2 files changed, 85 insertions(+) create mode 100644 docs/design/proposals/encryption-with-azure-keyvault.md diff --git a/docs/deploy-rbd.md b/docs/deploy-rbd.md index 7a8512a5f2c5..025db0154715 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. `encryptionKMSType`: should be set to `azure-kv`. +1. `AZURE_CERT_SECRET_NAME`: name of the Kubernetes Secret (in the Namespace where + PVC is created) 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. `AZURE_CLIENT_CERTIFICATE`: The client certificate used for authentication + with Azure Key Vault. + +This Secret is expected to be created by the tenant/user in each namespace +where PV's are created. + #### 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 000000000000..120bbe309e6e --- /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` 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. + +* AZURE_CLIENT_CERTIFICATE +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 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 + +CephCSI 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 also be permanently removed. + +> Note: Ceph-CSI solely deletes the secret without permanent removal (purging).