Creating a ROSA HCP cluster with custom KMS key

Last edited: March 19, 2026
Published: March 16, 2026
Authors: Nerav Doshi

Tags:

This content is authored by Red Hat experts, but has not yet been tested on every supported configuration.

This guide walks you through deploying a Red Hat OpenShift Service on AWS (ROSA) with Hosted Control Planes (HCP) using a customer-managed AWS KMS key. The KMS key can be used to encrypt:

Worker node root volumes
etcd database (control plane encryption)
PersistentVolumes (via custom StorageClass)

Tip: For official documentation, see Creating ROSA HCP clusters using a custom AWS KMS encryption key .

Note: This guide is specifically for ROSA with Hosted Control Planes (HCP).

Prerequisites

AWS CLI installed and configured
ROSA CLI v1.2.0 or higher
OpenShift CLI (oc)
AWS account with ROSA enabled
Red Hat account linked to AWS via the ROSA console

Verify Prerequisites

Verify ROSA CLI version (must be 1.2.0+)

Verify AWS CLI is configured

Verify ROSA is enabled in your AWS account

Set Environment Variables

Set the following environment variables to use throughout this guide:

Step 1: Create a VPC

You need a VPC with at least one private subnet (and optionally public subnets for public clusters).

Option A: Using ROSA CLI (Recommended)

After completion, capture the subnet IDs:

Option B: Using Terraform

Tag Your Subnets

Ensure subnets are properly tagged:

Step 2: Create Account-Wide Roles

Create the account-wide IAM roles required for ROSA HCP:

Step 3: Create OIDC Configuration

Create the OpenID Connect configuration:

Step 4: Create Operator Roles

Create the operator IAM roles for ROSA HCP:

Verify Operator Roles

List the created operator roles to note their exact names (important for KMS policy):

You should see roles including:

<prefix>-openshift-cluster-csi-drivers-ebs-cloud-credentials
<prefix>-kube-system-kube-controller-manager
<prefix>-kube-system-kms-provider
<prefix>-kube-system-capa-controller-manager

Tip: Role names may be truncated if the prefix is long. Use the above command to get exact names.

Step 5: Create KMS Key

Create a customer-managed KMS key:

Important: The tag red-hat=true is required for ROSA to use the KMS key.

Create KMS Alias (Optional)

Step 6: Configure KMS Key Policy

Create a comprehensive KMS key policy that includes all required ROSA HCP roles:

Apply the key policy:

Verify Key Policy

Step 7: Create the ROSA HCP Cluster

Create the cluster with KMS encryption enabled:

Parameters explained:

--kms-key-arn: Encrypts worker node root volumes
--etcd-encryption-kms-arn: Encrypts the etcd database (optional, can use same or different key)

Note: If your cluster name is longer than 15 characters, use --domain-prefix to customize the subdomain.

Monitor Cluster Installation

Installation typically takes 10-15 minutes for ROSA HCP.

Step 8: Configure Encrypted StorageClass for PersistentVolumes

Important: ROSA does not automatically configure the default StorageClass to encrypt PersistentVolumes with your KMS key. You must create a custom StorageClass.

Create Encrypted StorageClass

Remove Default from Existing StorageClass

Verify StorageClasses

Expected output:

Step 9: Validate the Cluster

Create Admin User

Save the credentials and login:

Verify Node Root Volume Encryption

Test PersistentVolume Encryption

Expected output should show Encrypted: true and your KMS key ARN.

Cleanup Test Resources

Troubleshooting

PVC Stuck in Pending

If PVCs are stuck in Pending state:

Cleanup

Delete Cluster

Delete Operator Roles

Delete OIDC Provider

Delete OIDC Config

Delete Account Roles (Optional)

Only delete if not shared with other clusters:

Delete KMS Key (Optional)

Delete VPC

If created with ROSA CLI:

If created with Terraform:

Additional Resources

Key takeaways:

The KMS key policy must include all ROSA operator roles that need encryption access
The EBS CSI driver role is often overlooked but required for PV encryption
ROSA does not auto-configure the default StorageClass for KMS encryption
Always verify role names as they may be truncated based on prefix length