Key Management System
Rook has the ability to encrypt OSDs of clusters running on PVC via the flag (
encrypted: true) in your
storageClassDeviceSets template. Rook also has the ability to rotate encryption keys of OSDs using a cron job per OSD. By default, the Key Encryption Keys (also known as Data Encryption Keys) are stored in a Kubernetes Secret. However, if a Key Management System exists Rook is capable of using it.
security section contains settings related to encryption of the cluster.
kms: Key Management System settings
connectionDetails: the list of parameters representing kms connection details
tokenSecretName: the name of the Kubernetes Secret containing the kms authentication token
keyRotation: Key Rotation settings
enabled: whether key rotation is enabled or not, default is
schedule: the schedule, written in cron format, with which key rotation CronJob is created, default value is
Currently key rotation is only supported for the default type, where the Key Encryption Keys are stored in a Kubernetes Secret.
Supported KMS providers:
- Authentication methods
- General Vault configuration
- TLS configuration
- IBM Key Protect
- Key Management Interoperability Protocol
Rook supports storing OSD encryption keys in HashiCorp Vault KMS.
Rook support two authentication methods:
- token-based: a token is provided by the user and is stored in a Kubernetes Secret. It's used to authenticate the KMS by the Rook operator. This has several pitfalls such as:
- when the token expires it must be renewed, so the secret holding it must be updated
- no token automatic rotation
- Kubernetes Service Account uses Vault Kubernetes native authentication mechanism and alleviate some of the limitations from the token authentication such as token automatic renewal. This method is generally recommended over the token-based authentication.
When using the token-based authentication, a Kubernetes Secret must be created to hold the token. This is governed by the
Note: Rook supports all the Vault environment variables.
The Kubernetes Secret
rook-vault-token should contain:
You can create a token in Vault by running the following command:
Refer to the official vault document for more details on how to create a token. For which policy to apply see the next section.
In order for Rook to connect to Vault, you must configure the following in your
In order to use the Kubernetes Service Account authentication method, the following must be run to properly configure Vault:
Once done, your
CephCluster CR should look like:
VAULT_ADDR value above assumes that Vault is accessible within the cluster itself on the default port (8200). If running elsewhere, please update the URL accordingly.
General Vault configuration¶
As part of the token, here is an example of a policy that can be used:
You can write the policy like so and then create a token:
In the above example, Vault's secret backend path name is
rook. It must be enabled with the following:
If a different path is used, the
VAULT_BACKEND_PATH key in
connectionDetails must be changed.
This is an advanced but recommended configuration for production deployments, in this case the
vault-connection-details will look like:
Each secret keys are expected to be:
VAULT_CACERT Secret named
vault-tls-ca-certificate will look like:
Note: if you are using self-signed certificates (not known/approved by a proper CA) you must pass
VAULT_SKIP_VERIFY: true. Communications will remain encrypted but the validity of the certificate will not be verified.
IBM Key Protect¶
Rook supports storing OSD encryption keys in IBM Key Protect. The current implementation stores OSD encryption keys as Standard Keys using the Bring Your Own Key (BYOK) method. This means that the Key Protect instance policy must have Standard Imported Key enabled.
First, you need to provision the Key Protect service on the IBM Cloud. Once completed, retrieve the instance ID. Make a record of it; we need it in the CRD.
On the IBM Cloud, the user must create a Service ID, then assign an Access Policy to this service. Ultimately, a Service API Key needs to be generated. All the steps are summarized in the official documentation.
The Service ID must be granted access to the Key Protect Service. Once the Service API Key is generated, store it in a Kubernetes Secret.
In order for Rook to connect to IBM Key Protect, you must configure the following in your
More options are supported such as:
IBM_BASE_URL: the base URL of the Key Protect instance, depending on your region. Defaults to
IBM_TOKEN_URL: the URL of the Key Protect instance to retrieve the token. Defaults to
https://iam.cloud.ibm.com/oidc/token. Only needed for private instances.
Key Management Interoperability Protocol¶
Rook supports storing OSD encryption keys in Key Management Interoperability Protocol (KMIP) supported KMS. The current implementation stores OSD encryption keys using the Register operation. Key is fetched and deleted using Get and Destroy operations respectively.
The Secret with credentials for the KMIP KMS is expected to contain the following.
In order for Rook to connect to KMIP, you must configure the following in your