Questo contenuto non è disponibile nella lingua selezionata.
Chapter 6. External encryption key management
6.1. Kubernetes Key Management Service (KMS) v2 on OpenShift Container Platform Copia collegamentoCollegamento copiato negli appunti!
You can configure Kubernetes Key Management Service (KMS) v2 on OpenShift Container Platform to centralize encryption key management and meet regulatory compliance requirements.
Kubernetes KMS v2 is a Technology Preview feature only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.
For more information about the support scope of Red Hat Technology Preview features, see Technology Preview Features Support Scope.
6.1.1. About Kubernetes KMS v2 encryption Copia collegamentoCollegamento copiato negli appunti!
Kubernetes KMS v2 uses an external Key Management Service to encrypt etcd data and centralize key management.
Kubernetes KMS v2 provides:
- Customer-managed encryption keys stored in an external KMS
- Centralized key management and auditing
- Regulatory compliance support
6.1.1.1. KMS plugin architecture Copia collegamentoCollegamento copiato negli appunti!
The KMS plugin configuration is specified inline in the APIServer resource. Encryption controllers deploy the KMS plugin and manage encryption key secrets.
The workflow is consists of the following steps:
-
You create the credential secret and optional CA bundle in the
openshift-confignamespace. -
You configure the
APIServerresource with the KMS provider settings and plugin image. - The encryption controllers deploy the KMS plugin and begin encrypting etcd data.
HashiCorp Vault Enterprise is the only supported KMS provider. Vault Community Edition is not supported. Vault Enterprise must be externally hosted and must not run inside the cluster service network.
6.1.1.2. Encrypted resources Copia collegamentoCollegamento copiato negli appunti!
When you enable KMS encryption, OpenShift Container Platform encrypts the following resources in etcd:
- Secrets
- ConfigMaps
- Routes
- OAuth access tokens
- OAuth authorize tokens
Resource types, namespaces, and object names are not encrypted.
6.1.2. KMS Technology Preview limitations Copia collegamentoCollegamento copiato negli appunti!
Review the current Kubernetes KMS v2 limitations to plan deployments and avoid unsupported configurations.
KMS encryption is a Technology Preview feature only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.
For more information about the support scope of Red Hat Technology Preview features, see Technology Preview Features Support Scope.
6.1.2.1. Current limitations Copia collegamentoCollegamento copiato negli appunti!
- HashiCorp Vault Enterprise is the only supported KMS provider. Vault Community Edition is not supported.
- Vault Enterprise must be externally hosted. Hosting Vault inside the cluster service network is not supported.
- After rotating a Vault Transit encryption key, OpenShift Container Platform does not automatically re-encrypt existing etcd data with the new key version.
-
The KMS plugin image must be in pinned digest format, such as
registry.example.com/vault-plugin@sha256:<digest>. Image tags are not allowed. - In disconnected environments or clusters that use custom internal registries, you must manually mirror the KMS plugin image to an accessible registry.
- The KMS plugin does not expose Prometheus metrics in this Technology Preview phase.
-
Unused KMS plugins are not removed from the
EncryptionConfigurationafter migration. You must decommission old providers manually. -
The
KMSEncryptionfeature gate requires theTechPreviewNoUpgradefeature set. Clusters with this feature set cannot be upgraded.
6.2. Configuring Kubernetes KMS v2 Copia collegamentoCollegamento copiato negli appunti!
You can configure external KMS encryption for etcd to centralize key management and meet regulatory compliance requirements.
Kubernetes KMS v2 is a Technology Preview feature only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.
For more information about the support scope of Red Hat Technology Preview features, see Technology Preview Features Support Scope.
6.2.1. Enable KMS encryption Copia collegamentoCollegamento copiato negli appunti!
You can enable Key Management Service (KMS) encryption for etcd data to centralize key management and meet compliance requirements.
Prerequisites
-
You have access to the cluster as a user with the
cluster-adminrole. -
You have enabled the
TechPreviewNoUpgradefeature set, which activates theKMSEncryptionfeature gate. - You have a HashiCorp Vault Enterprise instance that is externally hosted and accessible from your cluster. Vault Enterprise must not be hosted inside the cluster service network. Vault Community Edition is not supported.
You have configured your Vault instance with:
-
Transit secrets engine enabled at a mount path, such as the default
transit/path -
Encryption key created with type
aes256-gcm96(recommended for FIPS 140-3 compliance) - Vault policy that allows the KMS plugin to encrypt, decrypt, and read key information
-
Authentication method, such as
AppRole, configured with the policy attached
-
Transit secrets engine enabled at a mount path, such as the default
- You have the fully qualified OCI image pull spec with SHA256 digest for the KMS plugin image. You can obtain the image from the Red Hat Ecosystem Catalog or from Docker Hub. For more information, see "HashiCorp Vault KMS plugin container image" and "Red Hat Ecosystem Catalog". In disconnected environments, the image is mirrored to an accessible registry.
-
You have the
skopeoandjqtools installed. You have configured a Vault policy with the following capabilities:
path "transit/encrypt/kms-key" { capabilities = ["update"] } path "transit/decrypt/kms-key" { capabilities = ["update"] } path "transit/keys/kms-key" { capabilities = ["read"] } path "sys/license/status" { capabilities = ["read"] }Replace
transitwith your Transit mount path andkms-keywith your Vault Transit key name.- You have created an etcd backup.
Procedure
Obtain the SHA256 digest for the KMS plugin image by entering the following command:
$ skopeo inspect docker://quay.io/redhat-isv-containers/698df066f8d1ddf179c15ef9:<version> | jq -r '.Digest'Replace
<version>with the plugin version compatible with your cluster, such as0.1.0-beta-ubi.Use the resulting digest to construct the fully qualified pull spec in the format
quay.io/redhat-isv-containers/698df066f8d1ddf179c15ef9@sha256:<digest>.Create a secret in the
openshift-confignamespace with your Vault authentication credentials by entering the following command:$ oc create secret generic vault-approle-secret \ --from-literal=role-id=<your_role_id> \ --from-literal=secret-id=<your_secret_id> \ -n openshift-configReplace
<your_role_id>and<your_secret_id>with your Vault AppRole credentials.Optional: If your Vault server uses a custom TLS certificate authority, create a config map in the
openshift-confignamespace with the CA bundle by entering the following command:$ oc create configmap vault-ca-bundle \ --from-file=ca-bundle.crt=<path_to_ca_bundle> \ -n openshift-configEdit the
APIServercustom resource by entering the following command:$ oc edit apiserver clusterAdd the KMS configuration to the
spec.encryptionsection:apiVersion: config.openshift.io/v1 kind: APIServer metadata: name: cluster spec: encryption: type: KMS kms: type: Vault vault: kmsPluginImage: <registry>/<repository>@sha256:<digest> vaultAddress: https://vault.example.com:8200 vaultNamespace: my-namespace vaultAuthNamespace: my-auth-namespace vaultKeyPath: transit/keys/kms-key tls: caBundle: name: vault-ca-bundle serverName: vault.example.com authentication: type: AppRole appRole: secret: name: vault-approle-secretwhere:
kmsPluginImage- Specifies the KMS plugin container image as a fully qualified OCI pull spec with SHA256 digest. Image tags and short names are not allowed. In disconnected environments, use the mirrored location.
vaultAddress- Specifies the HTTPS URL of the Vault server. Paths, query parameters, and fragments are not allowed.
vaultNamespace- Specifies the Vault namespace. This value is optional.
vaultAuthNamespace-
Specifies the Vault namespace for authentication when it differs from the Transit namespace. Defaults to the
vaultNamespacevalue. This value is optional. vaultKeyPath-
Specifies the Transit encryption key path in the format
<mount>/keys/<key_name>. tls.caBundle.name-
Specifies the config map in the
openshift-confignamespace containing the CA bundle. Required only if Vault uses a custom CA. tls.serverName- Specifies the TLS server name for certificate verification. This value is optional.
authentication.appRole.secret.name-
Specifies the secret name in the
openshift-confignamespace containing the AppRole credentials.
Save and exit.
The
kube-apiserver,openshift-apiserver, andauthenticationOperators validate the configuration and roll out new revisions.
Verification
Verify the encryption type by entering the following command:
$ oc get apiserver cluster -o jsonpath='{.spec.encryption.type}'The output shows
KMS.Check the KMS plugin health and configuration validation by entering the following command:
$ oc get kubeapiserver cluster -ojsonpath='{.status.encryptionStatus}' | jq .Verify that
preflight.result.statusshowsSucceededand all nodes inhealthReportsshowHealthy.Monitor the
kube-apiserverrollout progress by entering the following command:$ oc get co kube-apiserverExample output during rollout
NAME VERSION AVAILABLE PROGRESSING DEGRADED SINCE MESSAGE kube-apiserver 5.0.0-rc.4 True True False 35m NodeInstallerProgressing: 2 nodes are at revision 6; 1 node is at revision 7When
PROGRESSINGshowsFalse, the rollout is complete.Check the encryption migration status by entering the following command:
$ oc get kubeapiserver cluster -o jsonpath='{.status.conditions[?(@.type=="Encrypted")]}' | jq .Example output when complete
{ "lastTransitionTime": "2026-09-24T16:41:48Z", "message": "All resources encrypted: secrets, configmaps", "reason": "EncryptionCompleted", "status": "True", "type": "Encrypted" }Wait for
reasonto showEncryptionCompletedbefore you verify encryption in etcd.Verify that secrets are encrypted in etcd:
WarningWait for the
kube-apiserverrollout to complete on all control plane nodes before you verify encryption. Secrets created while nodes run an earlier revision are not encrypted with KMS.Create a test secret by entering the following command:
$ oc create secret generic test-secret --from-literal=key=value -n defaultGet an etcd pod name by entering the following command:
$ oc get pods -n openshift-etcd -l app=etcd -o name | head -1Check the secret data in etcd by entering the following command:
$ oc exec -n openshift-etcd <etcd_pod_name> -- etcdctl get /kubernetes.io/secrets/default/test-secret --print-value-only | hexdump -C | head -1Example output
00000000 6b 38 73 3a 65 6e 63 3a 6b 6d 73 3a 76 32 3a 31 |k8s:enc:kms:v2:1|The output begins with
k8s:enc:kms:v2:followed by encrypted binary data.Delete the test secret by entering the following command:
$ oc delete secret test-secret -n default
6.2.2. Rotate the Vault encryption key Copia collegamentoCollegamento copiato negli appunti!
You can rotate your Vault Transit encryption key to generate a new key version while maintaining access to data encrypted with earlier versions.
After rotating the Vault encryption key, OpenShift Container Platform does not automatically re-encrypt existing etcd data with the new key version. Existing data remains encrypted with the previous key version. The Vault-side rotation steps are safe to perform because Vault retains all previous key versions for decryption.
Prerequisites
-
You have access to the cluster as a user with the
cluster-adminrole. - You have access to your Vault instance with permissions to rotate keys.
- Kubernetes KMS v2 encryption is enabled and functioning.
Procedure
Rotate the Vault encryption key by entering the following command:
$ vault write -f transit/keys/kms-key/rotateReplace
kms-keywith your Vault Transit key name. Vault creates a new key version while retaining earlier versions for decryption.Verify the new key version by entering the following command:
$ vault read transit/keys/kms-keyThe
latest_versionfield shows the current key version number.
Verification
Verify that existing secrets remain accessible by entering the following command:
$ oc get secret -AAll secrets should be readable without errors. Vault maintains all key versions and automatically uses the appropriate version for decryption.
6.2.3. Migrate from local encryption to KMS encryption Copia collegamentoCollegamento copiato negli appunti!
You can migrate from local etcd encryption to KMS encryption to centralize key management.
Prerequisites
-
You have access to the cluster as a user with the
cluster-adminrole. -
You have enabled the
TechPreviewNoUpgradefeature set to enable theKMSEncryptionfeature gate. -
Your cluster is currently using
aescbcoraesgcmencryption. -
You have created the credential secret and optional CA bundle config map in the
openshift-confignamespace. - You have the fully qualified OCI image pull spec with SHA256 digest for the KMS plugin image.
Create an etcd backup before migrating.
Procedure
Back up the current etcd encryption configuration by entering the following command:
$ oc get apiserver cluster -o yaml > apiserver-backup.yamlEdit the APIServer custom resource by entering the following command:
$ oc edit apiserver clusterChange the encryption type from
aescbcoraesgcmtoKMSand add the inline Vault configuration by using the following example:apiVersion: config.openshift.io/v1 kind: APIServer metadata: name: cluster spec: encryption: type: KMS kms: type: Vault vault: kmsPluginImage: <registry>/<repository>@sha256:<digest> vaultAddress: https://vault.example.com:8200 vaultKeyPath: transit/keys/kms-key authentication: type: AppRole appRole: secret: name: vault-approle-secretSave and exit.
After configuration validation succeeds, migration starts.
Verification
Verify migration completion for the OpenShift API server by entering the following command:
$ oc get openshiftapiserver -o jsonpath='{range .items[0].status.conditions[?(@.type=="Encrypted")]}{.reason}{"\n"}{end}'Verify migration completion for the Kubernetes API server by entering the following command:
$ oc get kubeapiserver -o jsonpath='{range .items[0].status.conditions[?(@.type=="Encrypted")]}{.reason}{"\n"}{end}'Verify migration completion for the authentication Operator by entering the following command:
$ oc get authentication.operator.openshift.io -o jsonpath='{range .items[0].status.conditions[?(@.type=="Encrypted")]}{.reason}{"\n"}{end}'All outputs show
EncryptionCompleted.
6.2.4. Migrating between KMS providers Copia collegamentoCollegamento copiato negli appunti!
You can migrate between KMS providers without an intermediate local encryption step. During migration, OpenShift Container Platform runs both KMS plugins concurrently until re-encryption completes.
Prerequisites
-
You have access to the cluster as a user with the
cluster-adminrole. - KMS encryption is enabled and functioning with the current provider.
-
You have created the credential secret and optional CA bundle config map for the new provider in the
openshift-confignamespace. - You have the fully qualified OCI image pull spec with SHA256 digest for the new KMS plugin image.
- You have created an etcd backup.
Procedure
Edit the
APIServercustom resource by entering the following command:$ oc edit apiserver clusterUpdate the
kms.vaultconfiguration with the new provider settings by using the following example:apiVersion: config.openshift.io/v1 kind: APIServer metadata: name: cluster spec: encryption: type: KMS kms: type: Vault vault: kmsPluginImage: <registry>/<repository>@sha256:<digest> vaultAddress: https://vault.example.com:8200 vaultNamespace: my-namespace vaultAuthNamespace: my-auth-namespace vaultKeyPath: transit/keys/kms-key tls: caBundle: name: vault-ca-bundle serverName: vault.example.com authentication: type: AppRole appRole: secret: name: vault-approle-secretSave and exit.
After configuration validation succeeds, the new provider handles encryption while the old provider decrypts existing data.
Monitor migration progress by entering the following command:
$ oc get kubeapiserver cluster -o jsonpath='{.status.conditions[?(@.type=="Encrypted")]}' | jq .Wait for
reasonto showEncryptionCompleted.
Verification
Verify that the OpenShift API server has completed migration by entering the following command:
$ oc get openshiftapiserver -o jsonpath='{range .items[0].status.conditions[?(@.type=="Encrypted")]}{.reason}{"\n"}{end}'The output shows
EncryptionCompleted.Verify that the Kubernetes API server has completed migration by entering the following command:
$ oc get kubeapiserver -o jsonpath='{range .items[0].status.conditions[?(@.type=="Encrypted")]}{.reason}{"\n"}{end}'The output shows
EncryptionCompleted.Verify that the authentication Operator has completed migration by entering the following command:
$ oc get authentication.operator.openshift.io -o jsonpath='{range .items[0].status.conditions[?(@.type=="Encrypted")]}{.reason}{"\n"}{end}'The output shows
EncryptionCompleted.
Next steps
Delete the old credential secret by entering the following command:
$ oc delete secret <old_vault_secret_name> -n openshift-configReplace
<old_vault_secret_name>with the name of the previous provider’s credential secret.Optional: Delete the old CA bundle config map by entering the following command:
$ oc delete configmap <old_vault_configmap_name> -n openshift-configReplace
<old_vault_configmap_name>with the name of the previous provider’s CA bundle config map.After your backup retention period passes, decommission the old KMS key.
NoteDo not decommission the old KMS key until migration completes and all backups encrypted with the old key have expired.
6.2.5. Monitoring KMS encryption status Copia collegamentoCollegamento copiato negli appunti!
You can monitor KMS encryption status by inspecting operator encryption status conditions, health reports, and preflight results.
Prerequisites
-
You have access to the cluster as a user with the
cluster-adminrole. - KMS encryption is enabled.
Procedure
Check overall Operator status by entering the following command:
$ oc get co kube-apiserverThe
DEGRADEDcolumn showsTrueif KMS configuration or connectivity problems exist.Inspect KMS health reports and preflight results by entering the following command:
$ oc get kubeapiserver cluster -ojsonpath='{.status.encryptionStatus}' | jq .Example output
{ "healthReports": [ { "keyID": "1", "lastCheckedTime": "2026-09-24T16:44:19Z", "nodeName": "ip-10-0-1-198.us-east-2.compute.internal", "remoteKeyID": "CgQKAnYx...", "status": "Healthy" }, { "keyID": "1", "lastCheckedTime": "2026-09-24T16:44:45Z", "nodeName": "ip-10-0-77-162.us-east-2.compute.internal", "remoteKeyID": "CgQKAnYx...", "status": "Healthy" }, { "keyID": "1", "lastCheckedTime": "2026-09-24T16:44:25Z", "nodeName": "ip-10-0-97-236.us-east-2.compute.internal", "remoteKeyID": "CgQKAnYx...", "status": "Healthy" } ], "preflight": { "observedConfigHash": "GNja6Q==", "result": { "configHash": "GNja6Q==", "remoteKeyID": "always-succeed", "status": "Succeeded" } } }healthReports-
Shows KMS plugin health per control plane node. Each entry includes the node name, key ID, a
statusofHealthy,Unhealthy, orError, and an optionaldetailfield with additional diagnostic information when the status is notHealthy. preflight-
Shows whether the configured KMS settings are valid. The
preflight.result.statusfield showsSucceededwhen the plugin can connect to the external Vault instance and the credentials are valid, orFailedwhen connectivity problems or invalid credentials exist.
Verify the Kubernetes API server encryption status by entering the following command:
$ oc get kubeapiserver cluster -o jsonpath='{.status.conditions[?(@.type=="Encrypted")]}' | jq .Example output
{ "lastTransitionTime": "2026-09-24T16:41:48Z", "message": "All resources encrypted: secrets, configmaps", "reason": "EncryptionCompleted", "status": "True", "type": "Encrypted" }Wait for
reasonto showEncryptionCompleted.Verify the authentication Operator encryption status by entering the following command:
$ oc get authentication.operator.openshift.io cluster -o jsonpath='{.status.conditions[?(@.type=="Encrypted")]}' | jq .Example output
{ "lastTransitionTime": "2026-09-24T16:22:10Z", "message": "All resources encrypted: oauthaccesstokens.oauth.openshift.io, oauthauthorizetokens.oauth.openshift.io", "reason": "EncryptionCompleted", "status": "True", "type": "Encrypted" }The output shows
EncryptionCompleted.Verify the OpenShift API server encryption status by entering the following command:
$ oc get openshiftapiserver cluster -o jsonpath='{.status.conditions[?(@.type=="Encrypted")]}' | jq .Example output
{ "lastTransitionTime": "2026-09-24T16:25:54Z", "message": "All resources encrypted: routes.route.openshift.io", "reason": "EncryptionCompleted", "status": "True", "type": "Encrypted" }The output shows
EncryptionCompleted.
6.2.6. KMS encryption troubleshooting Copia collegamentoCollegamento copiato negli appunti!
You can diagnose and resolve common KMS encryption issues to maintain secure key management and cluster availability.
6.2.6.1. KMS encryption does not activate Copia collegamentoCollegamento copiato negli appunti!
Symptom: KMS encryption does not activate after configuring the APIServer resource. The kube-apiserver Operator reports a degraded condition.
Diagnosis: Check the encryption status, including health reports and preflight results by running the following command:
$ oc get kubeapiserver cluster -ojsonpath='{.status.encryptionStatus}' | jq .
The preflight.result.status field shows whether configuration validation succeeded. The healthReports array shows plugin health per control plane node.
If you need additional detail, check the kube-apiserver Operator logs by running the following command:
$ oc logs -n openshift-kube-apiserver-operator deploy/kube-apiserver-operator | grep -i "kms\|error"
Solutions:
- Verify that the Vault server is reachable from control plane nodes.
-
Verify that the credential secret in
openshift-confighas valid credentials. -
Verify that the Transit encryption key exists at the path specified in
vaultKeyPath. - Verify that the Vault policy grants encrypt, decrypt, and read permissions on the key.
6.2.6.2. Invalid KMS configuration Copia collegamentoCollegamento copiato negli appunti!
Symptom: APIServer resource shows validation errors.
Diagnosis: Check the preflight results in the encryption status by running the following command:
$ oc get kubeapiserver cluster -ojsonpath='{.status.encryptionStatus.preflight}' | jq .
The preflight.result.status field shows whether the configured KMS settings are valid. A failed preflight indicates connectivity problems with the external Vault instance or invalid credentials.
If you need additional detail, check kube-apiserver Operator logs by running the following command:
$ oc logs -n openshift-kube-apiserver-operator deploy/kube-apiserver-operator | grep -i "kms\|validation\|error"
Solutions:
-
Verify that the
kms.vaultconfiguration in theAPIServerresource has valid field values. -
Verify that
kmsPluginImageis a fully qualified OCI pull spec with a SHA256 digest. -
Verify that
vaultAddressis a valid HTTPS URL without path or query parameters. -
Verify that the credential secret referenced by
authentication.appRole.secret.nameexists in theopenshift-confignamespace.
6.2.6.3. KMS permissions errors Copia collegamentoCollegamento copiato negli appunti!
Symptom: Encryption migration fails with permission errors.
Diagnosis: Check Operator logs by running the following command:
$ oc logs -n openshift-kube-apiserver-operator deploy/kube-apiserver-operator | grep -i "kms\|permission\|access denied"
Solutions:
- Verify that the credential secret has valid and unexpired credentials.
- Verify that the Vault policy grants encrypt and decrypt permissions.
- Verify that the encryption key is enabled and not scheduled for deletion.
6.2.6.4. Expired or deleted KMS key Copia collegamentoCollegamento copiato negli appunti!
Symptom: API server cannot decrypt encrypted resources.
Diagnosis: Check API server logs and verify key status by running the following command:
$ oc logs -n openshift-kube-apiserver -l apiserver=true | grep -i "decrypt\|kms.*error"
Solutions:
- Re-enable the encryption key if it was disabled.
- Restore from backup if the key was permanently deleted.
- Cancel key deletion if it is scheduled.
- Ensure the KMS provider retains access to earlier key versions.
Deleted KMS keys prevent data recovery. Align key retention with backup policies.
6.2.6.5. API server degraded or unavailable Copia collegamentoCollegamento copiato negli appunti!
Symptom: API server becomes degraded or unresponsive after enabling KMS encryption.
Diagnosis: Check the encryption status health reports by running the following command:
$ oc get kubeapiserver cluster -ojsonpath='{.status.encryptionStatus.healthReports}' | jq .
Health reports show per-node plugin status. An Unhealthy status indicates connectivity or credential problems between that node and the Vault instance.
Check overall Operator status by running the following command:
$ oc get clusteroperator kube-apiserver
If you need additional detail, check API server logs by running the following command:
$ oc logs -n openshift-kube-apiserver -l apiserver=true --tail=200 | grep -i kms
Solutions:
- Check network connectivity between control plane nodes and Vault.
- Verify network policies and firewalls allow communication.
- Check Vault for rate limiting.
- Verify DNS resolution and TLS certificate validation.
6.2.6.6. Encryption migration stuck or slow Copia collegamentoCollegamento copiato negli appunti!
Symptom: Encryption migration takes unusually long or is stuck.
Diagnosis: Check Operator status and migration logs by running the following commands:
$ oc get clusteroperator kube-apiserver
$ oc logs -n openshift-kube-apiserver-operator deploy/kube-apiserver-operator | grep -i migration
Solutions:
- Migration time depends on data size. Monitor progress with Operator conditions.
- Check Vault audit logs for rate limiting or throttling.
- Check network performance between control plane nodes and Vault.
6.2.6.7. Collecting debug information Copia collegamentoCollegamento copiato negli appunti!
Collect cluster status and logs by running the following commands:
$ oc adm must-gather
$ oc get apiserver cluster -o yaml > apiserver.yaml
$ oc get kubeapiserver cluster -ojsonpath='{.status.encryptionStatus}' | jq . > encryption-status.json
$ oc logs -n openshift-kube-apiserver-operator deploy/kube-apiserver-operator > kube-apiserver-operator.log
$ oc logs -n openshift-kube-apiserver -l apiserver=true --tail=500 > kube-apiserver.log
Collect KMS provider information:
- Vault audit logs
- Vault key policy and permissions
- Authentication credentials status
- Network connectivity test results
Redact credentials, tokens, and sensitive data before sharing logs.
6.3. Disabling Kubernetes KMS v2 Copia collegamentoCollegamento copiato negli appunti!
You can disable KMS encryption and migrate to local etcd encryption to simplify operations or resolve external KMS connectivity issues.
Kubernetes KMS v2 is a Technology Preview feature only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.
For more information about the support scope of Red Hat Technology Preview features, see Technology Preview Features Support Scope.
6.3.1. Disable KMS encryption Copia collegamentoCollegamento copiato negli appunti!
You can disable KMS encryption and migrate to local encryption or disable encryption entirely to simplify operations or resolve connectivity issues.
Prerequisites
-
You have access to the cluster as a user with the
cluster-adminrole. - You have created an etcd backup.
Re-encryption of all etcd data occurs when you change the encryption type.
Procedure
Edit the
APIServercustom resource by entering the following command:$ oc edit apiserver clusterChange the encryption type and remove the
kmssection by using the following example:apiVersion: config.openshift.io/v1 kind: APIServer metadata: name: cluster spec: encryption: type: <encryption>Replace
<encryption>withaescbc,aesgcm, oridentity. Theaescbcandaesgcmtypes use locally managed encryption keys. Theidentitytype disables all encryption and stores data as plain text. You must remove the entirekmssection because the API rejects it when the encryption type is notKMS.Save and exit.
OpenShift Container Platform migrates etcd data. The KMS plugin remains as a read-only provider until migration completes.
Monitor the migration progress by entering the following command:
$ oc get kubeapiserver cluster -o jsonpath='{.status.conditions[?(@.type=="Encrypted")]}' | jq .Wait for
reasonto showEncryptionCompleted. Thekube-apiserveris typically the last to complete.Verify that the
kube-apiserverpods have rolled out by entering the following command:$ oc get pods -n openshift-kube-apiserver -l app=openshift-kube-apiserverAfter migration completes, clean up the KMS provider resources by using the following steps:
Delete the credential secret by entering the following command:
$ oc delete secret vault-approle-secret -n openshift-configOptional: Delete the CA bundle config map by entering the following command:
$ oc delete configmap vault-ca-bundle -n openshift-config- After your backup retention period passes, decommission the KMS key.
Verification
Verify the encryption type by entering the following command:
$ oc get apiserver cluster -o jsonpath='{.spec.encryption.type}'Verify that a test secret uses the new encryption type:
Create a test secret by entering the following command:
$ oc create secret generic encryption-test --from-literal=key=value -n defaultGet an etcd pod name by entering the following command:
$ oc get pods -n openshift-etcd -l app=etcd -o name | head -1Check the encryption prefix by entering the following command:
$ oc exec -n openshift-etcd <etcd_pod_name> -- etcdctl get /kubernetes.io/secrets/default/encryption-test --print-value-only | hexdump -C | head -1The output begins with
k8s:enc:aescbc:v1:,k8s:enc:aesgcm:v1:, or shows readable JSON foridentity.Delete the test secret by entering the following command:
$ oc delete secret encryption-test -n default
Do not delete the KMS key until migration completes.