Configuring Customer KMS Key for the OpenShift Image Registry on ROSA (Classic and HCP)

By default, ROSA clusters (Classic and HCP) store container images in an S3 bucket encrypted with an AWS-managed key. Organizations with compliance or data-sovereignty requirements may need to use a customer-managed AWS KMS key instead, giving them full control over key rotation, access policies, and audit trails.

This guide walks through creating a customer-managed KMS key and configuring the ROSA image registry to use it for server-side encryption of all stored container images.

Prerequisites

You need:

• A ROSA cluster (running and logged into)
• The rosa CLI
• The oc CLI
• The AWS CLI
• AWS permissions to create and manage KMS keys
• AWS permissions to modify IAM role policies

Set environment variables

Set the following environment variables to match your cluster:

Create a customer-managed KMS key

1. Create the KMS key:

2. Create an alias for easier identification:

3. Get the full KMS key ARN:

4. Ensure the KMS key policy allows IAM roles in your account to use the key:

Grant the image registry operator KMS permissions

The image registry operator role needs permissions to encrypt and decrypt objects using the customer KMS key.

1. Identify the image registry operator role:

2. Attach a KMS policy to the role:

Configure the image registry to use the KMS key

ROSA configures the default image registry with S3 encryption enabled (spec.storage.s3.encrypt: true). This procedure changes the encryption key used by the existing registry S3 backend by setting spec.storage.s3.keyID.

1. Patch the image registry operator configuration to use the customer KMS key:

2. Monitor the image registry operator rollout:

   Wait until the operator shows AVAILABLE=True, PROGRESSING=False, and DEGRADED=False.

Verify KMS encryption

1. Confirm the image registry configuration includes the KMS key:

   The output should include "keyID" set to your KMS key ID.

2. Check the S3 bucket default encryption:

   Expected output:

3. Build and push an image to the internal registry to create objects encrypted with the customer KMS key. Objects written before the KMS configuration was applied retain their original encryption.

4. Verify that the newly written object is encrypted with the customer KMS key:

   Expected output:

Cleanup

If you want to revert the image registry back to the default AWS-managed encryption:

1. Remove the keyID from the image registry configuration:

2. Remove the KMS policy from the image registry operator role:

3. Optionally, schedule the KMS key for deletion:

   Do not delete the KMS key while the image registry is still using it. Deleting the key renders all encrypted images in the registry permanently unreadable.