Configuring Custom Web Console and Downloads Routes on ROSA HCP

ROSA HCP clusters expose the web console and CLI downloads page on automatically generated hostnames under the cluster’s base domain, for example console-openshift-console.apps.<cluster-domain>. For organizations with strict enterprise domain policies, compliance requirements, or teams migrating from ROSA Classic clusters that already use custom routes, replacing these default hostnames with organization-controlled names and certificates is a common day-2 requirement.

This guide walks through deploying a public ROSA HCP cluster using the rh-mobb/terraform-rosa Terraform module, obtaining a trusted TLS certificate via Let’s Encrypt, and configuring custom DNS names for the console and downloads routes: the two component routes supported on HCP.

Prerequisites

• AWS CLI configured with permissions to create IAM roles and manage Route 53
• ROSA CLI v1.2.65 or later, logged in (rosa login)
• A Red Hat OCM service account client_id and client_secret — create one at console.redhat.com/iam/service-accounts
• Terraform v1.5.0 or later
• OpenShift CLI (oc)
• certbot with the certbot-dns-route53 plugin installed via pipx
• A Route 53 public hosted zone for a domain you control
• ROSA HCP enabled on your AWS account; verify with rosa verify quota --region us-west-2

Set Environment Variables

Set these once and reuse them throughout the guide.

Deploy a ROSA HCP Cluster

Clone the rh-mobb/terraform-rosa module. It handles networking, HCP account IAM roles, OIDC configuration, operator roles, cluster creation, and the default machine pool in a single make command.

Create a terraform.tfvars file for a public single-AZ HCP cluster:

Deploy the cluster:

Expected output:

Verify the Cluster is Ready

Expected output:

Log in to the cluster using the make helper:

Or manually:

Capture the cluster domain for later steps. The terraform-rosa module does not expose cluster_domain directly, so derive it from cluster_console_url:

Obtain TLS Certificates

Use Let’s Encrypt with the Route 53 DNS-01 challenge. Certbot automatically creates and cleans up the _acme-challenge TXT record in Route 53; no HTTP server or firewall changes are needed.

Request Certificates

Verify the certificates were issued:

Expected output:

Configure DNS Records

Get the Ingress Load Balancer Hostname

Create Route 53 CNAME Records

Verify DNS propagation (allow approximately 60 seconds):

Expected output:

Create TLS Secrets on the Cluster

The TLS secrets must exist in the openshift-config namespace on the hosted cluster before Terraform applies the component route configuration. OpenShift reads these secrets when routing TLS traffic for the custom hostnames.

Verify both secrets exist:

Expected output:

Configure Custom Component Routes

Add a new Terraform file to the cloned terraform-rosa directory. The local.cluster_id value is already defined in the module’s 04-cluster.tf and resolves to the HCP cluster ID.

Apply with the route variables:

Expected output:

Verify the Configuration

Check the Cluster Ingress Config

Expected output:

Confirm the Custom Routes Were Created

Expected output:

Verify the Default Route Redirects to the Custom Hostname

The original auto-generated route now issues an HTTP 301 redirect:

Expected output:

Access the Console on the Custom Hostname

Expected output:

What to observe:

1. The browser navigates directly to https://console.example.com without passing through the default cluster domain.
2. The TLS certificate in the browser shows your organization’s domain (issued by Let’s Encrypt) rather than the ROSA wildcard certificate.
3. The downloads page at https://downloads.example.com serves the oc, kubectl, and rosa CLI binaries correctly.
4. Logging in via the console still functions normally; authentication is unaffected by the route change.

Removing Custom Routes

To revert both routes to cluster defaults, pass null values and re-apply:

OpenShift immediately restores the auto-generated hostnames under the cluster domain. No rolling restart is required.

Certificate Renewal

Let’s Encrypt certificates expire after 90 days. Use --dry-run=client -o yaml | oc apply -f - to update secrets in-place rather than erroring on a duplicate resource:

Cleanup

Summary

Additional Resources

• RHCS provider: rhcs_hcp_default_ingress resource
• rh-mobb/terraform-rosa module
• OpenShift documentation: Customizing the ingress controller
• certbot-dns-route53 plugin documentation