Setting up a domain for your cluster

When you create a cluster, an Ingress subdomain is registered by default for your cluster in the format <cluster_name>.<globally_unique_account_HASH>-0000.<region>.containers.appdomain.cloud. Additionally, you can make your apps reachable at a custom domain by creating your own domain registered with IBM Cloud's internal domain provider, or a domain registered with an external provider. You can also add an existing domain to your cluster.

This functionality is available in beta and is subject to change.

IBM Cloud provides a managed, internal provider that you can use to create your own domains. With the managed domain provider, you do not need to create and maintain an account with an external provider. You can also utilize health check monitoring for your managed domains. When creating a domain with the internal provider, you specify a subdomain name, such as exampledomain, and the new domain is named in the format exampledomain.<zone>.containers.appdomain.cloud.

You can also use your own external DNS provider. You must have an account with the external provider that you want to use. The following external providers are supported:

Akamai
Cloudflare
CIS

You can also use the service.kubernetes.io/ibm-load-balancer-cloud-provider-dns-name VPC load balancer annotation to create a new domain or register an existing domain to your VPC load balancer. For more information, see the annotation description in the VPC ALB or VPC NLB documentation.

Accessing domains in the console

Navigate to the your cluster's Domains page to create and manage domains.

In the console, navigate to your clusters tab.
Click on the cluster where you want to create or change a domain.
Click Ingress.
Click the Domains tab. From here, you can manage the domains associated with the cluster.

Creating domains in the console

Use the IBM Cloud console to create your own domain in your cluster, or add a domain that already exists in your provider account. Follow the console instructions to make the following domain configurations.

If you are using the IBM Cloud Internet Services provider, you must first set up service-to-service authorization for your IBM Cloud Internet Services instance. Set the source service as Kubernetes Service, and the target as Internet services. Assign the Manager role.

Domain details

Domain name: The name of the domain to create or add to your cluster. This can be a domain that exists in your provider account, or a new domain.
Provider: Choose a provider for your domain. To create a managed domain with IBM Cloud's internal provider, choose Managed. To use an external provider, choose from the remaining provider types. To use an external provider, such as Cloudflare, you must have an account with that provider and you must enter your provider credentials. IBM Cloud uses these credentials to register domains and update records in your DNS provider.
Set as default: Choose whether you want to set the domain as the default for the cluster. The default Ingress domain is used to form a unique URL for each of your apps and is the domain that is referenced by the IP addresses of any public ALBs in your cluster. You can change which domain is set as the default at any time. Setting a default domain replaces the current default.

Registration details

Add one or more IP addresses (for Classic or VPC clusters) or Hostnames (for VPC clusters) to register to the domain. You can update which IP addresses or hostnames are registered.
Secret namespace: Specify the namespace that the TLS secret for the domain is created in. If you don't specify a namespace, the secret is created in the default namespace.

Credentials

Your DNS credentials are required to create or add a domain with external providers, such as Cloudflare or Akamai. Red Hat OpenShift on IBM Cloud uses these credentials to provision or access a domain from the external provider on your behalf. You must use the same set of credentials for each domain in a cluster.

Different providers might require different credentials, such as access tokens or secrets. Red Hat OpenShift on IBM Cloud does not provide the credentials; you must acquire them from the external provider.

Required credentials for Akamai

Follow the steps to find the required Akamai credentials.

Gather the required access token, client token, client secret, and host from Akamai by following the steps to create authentication credentials in the Akamai documentation.
In your Akamai account dashboard, find the DNS zone to add to your provider credentials. Note the full zone name, such as example.external.adppdomain.cloud.

Required credentials for Cloudflare

Follow the steps to find the required Cloudflare credentials.

Find the Cloudflare API access token to add to your provider credentials. For more information, see Create an API token in the Cloudflare documentation.
In your Cloudflare account, find the DNS zone to add to your provider credentials. For steps to find the DNS zone, see Find zone and account IDs in the Cloudflare documentation.

Managing your domain in the console

You can complete the following actions to manage your domain.

Delete a domain: If you delete a domain from a cluster, the domain cannot be recovered. If you later need the domain, you must reprovision it. If delete a domain that is registered with the managed provider, you cannot reuse that domain name. Note that you cannot delete a cluster's default domain. If you want to delete the domain that is currently registered as the default, you must first assign a different default domain.
Update a domain's IP addresses or hostname: When you update the IP addresses or hostnames, you must include any IPs or hostnames that are currently registered to the domain. The domain updates with the exact values specified, so any current IP addresses or hostnames are overwritten if they are not included. For example, if 52.137.182.166 is currently registered to your domain and you want to add 52.137.182.270, you must specify both IP addresses.
Change a cluster's default domain: You can change the default domain to any domain that exists in your cluster. This change might take up to five minutes to apply. During that time, your domain might experience downtime.

Setting up domains with the managed IBM Cloud internal provider

IBM Cloud provides a managed, internal provider that you can use to create your own domains. You can use the ibmcloud oc ingress domain create command to create a new domain, or you can specify an existing domain that you want to add to your cluster. When you create a domain with the internal provider, you might specify a subdomain name, such as exampledomain, or provide the fully qualified domain name. The new domain is named in the format exampledomain.<zone>.containers.appdomain.cloud.

The IBM Cloud internal managed domain provider is Akamai. You can also use your own Akamai account to create or add domains. When you get the details of a domain, you might see the provider type listed as akamai or akamai-ext. The akamai provider type refers to the internal IBM Cloud domain provider, and akamai-ext refers to your own external Akamai account that you directly register the domain with. If you provide the fully qualified domain name, the zone of your domain must match the zone your cluster was created in.

ibmcloud oc ingress domain create --cluster CLUSTER [--is-default] [--domain DOMAIN] [--hostname HOSTNAME] [--ip IP] [--output OUTPUT] [-q] [--secret-namespace NAMESPACE]

-c, --cluster CLUSTER: Required. The name or ID of the cluster where you want to create the domain.
--is-default: Optional. Include this option to set the relevant domain as the default domain for the cluster.
--domain DOMAIN: The domain to create or add to your cluster. This can be a domain that exists in your provider account, or a new domain.
--hostname HOSTNAME: Optional. For VPC clusters. The hostname to register for the domain.
--ip IP: Optional. The IP addresses to register for the domain.
--output OUTPUT: Optional: Prints the command output in JSON format.
--secret-namespace NAMESPACE: Optional. The namespace that the domain TLS secret is created in. If no namespace is specified, the secret is created in the default namespace.

Setting up domains with IBM Cloud Internet Services

Follow the steps to create a domain with IBM Cloud Internet Services.

Set up service-to-service authorization

Creating a domain with IBM Cloud Internet Services requires you to set up service-to-service authorization for your IBM Cloud Internet Services instance. Set the source service as Kubernetes Service, and the target as Internet services. Assign the Manager role.

Create a domain

Create a new domain, or specify an existing domain that you want to add to your cluster. To specify an existing domain, include the full domain name with the external provider zone, such as exampledomain.externalzone.com. To create a new domain, you must still include the external provider zone, but you can customize the subdomain portion, such as custom.exampledomain.externalzone.com. Note that the domain name must be unique in the zone it is registered in.

If you delete a domain that is registered with the IBM internal provider, you cannot reuse the domain name.

ibmcloud oc ingress domain create --cluster CLUSTER [--crn CRN] [--is-default] [--domain DOMAIN] [--hostname HOSTNAME] [--ip IP] [--output OUTPUT] [--domain-provider PROVIDER] [-q] [--secret-namespace NAMESPACE] [--zone ZONE]

-c, --cluster CLUSTER: Required. The name or ID of the cluster where you want to create the domain.
--crn CRN: Required for IBM Cloud Internet Services domains. The CRN for the IBM Cloud Internet Services instance.
--is-default: Optional. Include this option to set the relevant domain as the default domain for the cluster.
--domain DOMAIN: The domain to create or add to your cluster. This can be a domain that exists in your provider account, or a new domain.
--hostname HOSTNAME: For VPC clusters. The hostname to register for the domain.
--ip IP: The IP addresses to register for the domain.
--output OUTPUT: Optional: Prints the command output in JSON format.
--domain-provider PROVIDER: Required. The external DNS provider type. Specify --cis-ext.
--secret-namespace NAMESPACE: Optional. The namespace that the domain TLS secret is created in. If no namespace is specified, the secret is created in the default namespace.
--domain-zone ZONE: Optional. The Domain ID for your IBM Cloud Internet Services instance. This is a GUID value.

Adding credentials and setting up domains from other external providers

To use a domain that is registered with an external provider such as Akamai or Cloudflare, you must add the external provider credentials to your cluster. Red Hat OpenShift on IBM Cloud uses these credentials to provision or access a domain from the external provider on your behalf. You can only add one set of credentials to your cluster. Different providers might require different credentials, such as access tokens or secrets. Red Hat OpenShift on IBM Cloud does not provide the credentials; you must acquire them from the external provider.

After you add external credentials to your cluster, you can add or create domains that are registered with your external account.

Adding Akamai credentials

Akamai Add Akamai provider credentials to your cluster.

Note that registering credentials for Akamai requires the READ-WRITE permission for /config-dns endpoint in your external Akamai account.

Gather the required access token, client token, client secret, and host from Akamai by following the steps to create authentication credentials in the Akamai documentation.
In your Akamai account dashboard, find the DNS zone to add to your provider credentials. Note the full zone name, such as example.external.adppdomain.cloud.
Run the following command to add the provider credentials to your cluster. Specify the token, secret, and DNS zone values you found in the previous steps.

ibmcloud oc ingress domain credential set akamai --cluster CLUSTER --access-token TOKEN --client-secret SECRET --client-token TOKEN --host HOST --zone AKAMAI_ZONE [-q]

This command is only required when creating an external domain with the Akamai provider.

-c, --cluster CLUSTER: Required. The name or ID of the cluster where you want to add the credentials.
--access-token TOKEN: The access token for the Akamai API Client credentials. This token is provided by Akamai.
--client-secret SECRET: The client secret for the Akamai API Client credentials. This token is provided by Akamai.
--client-token TOKEN: The client token for the Akamai API Client credentials. This token is provided by Akamai.
--host HOST: The host for the Akamai API Client credentials. This value is provided by Akamai.
-q: Optional: Do not show the message of the day or update reminders.
--domain-zone ZONE: The DNS zone that exists in your Akamai account. Specify the full zone name, such as example.external.adppdomain.cloud.

Adding Cloudflare credentials

Cloudflare Add Cloudflare provider credentials to your cluster.

Note that registering credentials for Cloudflare requires the following permissions in your external Cloudflare account: Zone Settings: Read, Zone: Read, DNS: Read, Zone: Edit, DNS: Edit, API Tokens: Read.

Find the Cloudflare API access token to add to your provider credentials. For more information, see Create an API token in the Cloudflare documentation.
In your Cloudflare account, find the DNS zone to add to your provider credentials. For steps to find the DNS zone, see Find zone and account IDs in the Cloudflare documentation.
Run the following command to add the provider credentials to your cluster. Specify the access token and DNS zone values you found in the previous steps.

ibmcloud oc ingress domain credential set cloudflare --cluster CLUSTER --token TOKEN --zone CLOUDFLARE_ZONE [-q]

-c, --cluster CLUSTER: Required: The name or ID of the cluster where you want to add the credentials.
-q: Optional: Do not show the message of the day or update reminders.
--token TOKEN: The access token for Cloudflare credentials. This token is provided by Cloudflare.
--domain-zone ZONE: The DNS zone that exists in your Cloudflare account and is specified in your provider credentials. This is a GUID value.

Verifying your provider credentials

Verify that the provider credentials were added to your cluster.

ibmcloud oc ingress domain credential get --cluster CLUSTER [--output OUTPUT] [-q]

Creating a domain, or adding an existing domain

Create or add a domain to your cluster with the ibmcloud oc ingress domain create. If you already have a domain provisioned with an internal or external provider and have set up any necessary credentials, you can use this command to add that domain to your cluster. Or, you can provision a new domain in both your cluster and in your provider account. To specify an existing domain, include the full domain name with the external provider zone, such as exampledomain.externalzone.com. To create a new domain, you must still include the external provider zone, but you can customize the subdomain portion, such as new-exampledomain.externalzone.com.

ibmcloud oc ingress domain create --cluster CLUSTER [--is-default] [--domain DOMAIN] [--hostname HOSTNAME] [--ip IP] [--output OUTPUT] [--domain-provider PROVIDER] [-q] [--secret-namespace NAMESPACE]

-c, --cluster CLUSTER: Required. The name or ID of the cluster where you want to create the domain.
--is-default: Optional. Include this option to set the relevant domain as the default domain for the cluster.
--domain DOMAIN: The domain to create or add to your cluster. This can be a domain that exists in your provider account, or a new domain.
--hostname HOSTNAME: For VPC clusters. The hostname to register for the domain.
--ip IP: The IP addresses to register for the domain.
--output OUTPUT: Optional: Prints the command output in JSON format.
--domain-provider PROVIDER: Optional. The external DNS provider type. Specify akamai-ext for Akamai or cloudflare-ext for Cloudflare.
--secret-namespace NAMESPACE: Optional. The namespace that the domain TLS secret is created in. If no namespace is specified, the secret is created in the default namespace.

Managing domains

Learn how to manage the domains that exist in your cluster.

Listing all domains in a cluster

For more details and command options, see the CLI reference.

ibmcloud oc ingress domain ls --cluster CLUSTER

Getting the details of a single domain

For more details and command options, see the CLI reference.

ibmcloud oc ingress domain credential get --cluster CLUSTER

Removing a domain from a cluster

If you delete a domain from a cluster, the domain cannot be recovered. If you later need the domain, you must reprovision it. Note that you cannot delete a cluster's default domain. If you want to delete the domain that is currently registered as the default, you must first assign a different default domain.

If you delete a domain that is registered with the IBM internal provider, you cannot reuse the domain name.

For more details and command options, see the CLI reference.

ibmcloud oc ingress domain rm --cluster CLUSTER --domain DOMAIN

Updating a domain's IP addresses or hostname

You can update a domain's registered IP addresses (for Classic or VPC clusters) or hostname (for VPC clusters) after the domain is created or added to the cluster. This command updates all the resources in your cluster with the specified IP addresses or hostnames and changes your app URLs.

For more information and command options, see the CLI reference.

Note that when you add IP addresses or hostnames, you must include any IPs or hostnames that are currently registered to the domain. The domain updates with the exact values specified, so any current IP addresses or hostnames are overwritten if they are not included. For example, if 52.137.182.166 is currently registered to your domain and you want to add 52.137.182.270, you must specify --ip 52.137.182.166 --ip 52.137.182.270 in the command.

ibmcloud oc ingress domain update --cluster CLUSTER --domain DOMAIN [--hostname HOSTNAME] [--ip IP]

Changing a cluster's default domain

The default Ingress domain is used to form a unique URL for each of your apps and is the domain that is referenced by the IP addresses of any public ALBs in your cluster. When you provision a cluster, the default Ingress domain is automatically created for you, but you can change the default domain to any domain that exists in your cluster. To check your cluster's default domain, run ibmcloud oc cluster get and find the Ingress subdomain in the output.

For more details and command options, see the CLI reference.

It can take up to five minutes for the default domain to update. During that time, your domain might experience downtime.

ibmcloud oc ingress domain default replace --cluster CLUSTER --domain DOMAIN

Managing external provider credentials

Learn how to manage the provider credentials that exist in your cluster.

Viewing external provider credentials

Get the details of the provider credentials that are added to your cluster. Note that only one set of credentials can be added to a cluster at a time.

For more details and command options, see the CLI reference.

ibmcloud oc ingress domain credential get --cluster CLUSTER

Removing external provider credentials

You can remove external provider credentials from your cluster. Note that removing credentials causes any domains registered with those credentials to enter an Error state. The domain status resolves when the credentials are reapplied.

For more details and command options, see the CLI reference.

ibmcloud oc ingress domain credential rm --cluster CLUSTER

Managing domain secrets and certificates

Learn how to manage the TLS certificate for your Ingress domain.

Regenerating the certificate for an Ingress domain

Regenerate the domain certificate to generate a new token in your DNS provider and apply it to your cluster.

For more details and command options, see the CLI reference

ibmcloud oc ingress domain secret regenerate --cluster CLUSTER --domain DOMAIN

Deleting an Ingress domain secret

Delete the secret for an Ingress domain and prevent future renewal of the certificate.

For more details and command options, see the CLI reference

ibmcloud oc ingress domain secret rm --cluster CLUSTER --domain DOMAIN