How do I configure a TLS certificate with a custom domain in a Kubernetes cluster so that I can access an application with the custom domain?
The short answer is defining a DNS alias for your custom domain, creating a secret with a TLS certificate of the custom domain and defining an Ingress resource that uses the custom domain to route incoming network traffic to the service of your application.
In this article, I will demonstrate the detailed steps for how to configure a TLS certificate with a custom domain in a Kubernetes cluster so that you can clearly understand how to set it up on your IBM Cloud Kubernetes Service cluster.
Steps
- Register a custom domain.
- Define a DNS alias for your custom domain by specifying the IBM-provided domain.
- Create a secret in the namespace to use TLS termination where your application exists.
- Define an Ingress resource that uses your custom domain to route incoming network traffic to the service of your application.
Step 1: Register a custom domain
Register your custom domain with any Domain Name Service (DNS) provider or IBM Cloud Classic Infrastructure Domain Name Service. If you don’t have a custom domain yet, you can register a domain here.
I am going to use my custom domain tnexample.com
in the IBM Cloud Domain Name Registration service:
Step 2. Define an alias for your custom domain
Define an alias for the custom domain by specifying the IBM-provided Ingress subdomain as a Canonical Name record (CNAME) in DNS:
- Verify the Ingress Subdomain host for your cluster:
- From the dashboard in the IBM Cloud console, click the Menu icon and select Classic Infrastructure to get to the Classic Infrastructure landing page.
- In the Classic Infrastructure navigation, select Network > DNS > Forward Zones.
- Select the domain
tnexample.com
. - In Add New Record section, select Resource Type: CNAME, type Host: *, Resource Type: CNAME and Points To: mycluster-tn-5be51ad3139a99d89cdf8f97c78ef71c-0000.au-syd.containers.appdomain.cloud. Note: You need add
.
at the end of the Ingress Subdomain host: - Confirm if the DNS works by using the commands
nslookup
andping
. You see the custom domain URL can be reached via the custom domain:Alternatively, You can use IBM Cloud Internet Services (CIS), which offers capabilities to enhance your workflow — security, reliability and performance, including DNS management. See more details here.
Step 3. Create a secret in the namespace to use TLS termination
Create a secret in the namespace to use TLS termination where your apps exist that contains your own TLS certificate.
Granting service access to classic infrastructure
If you manage domains by using the classic infrastructure DNS service, you must grant service access to its DNS service so that IBM Cloud Secrets Manager can validate the ownership of your domains. You’ll need your classic infrastructure account credentials before you can grant access. To obtain your classic infrastructure username and API key, you can use the Access (IAM) section of the console.
- In the console, go to Manage > Access (IAM) > Users, then select the user’s name.
- In the VPN password section, copy the Username value. In most cases, your classic infrastructure username is your <account_id>_<email_address> or IBM<number>:
- In the API keys section, create a classic infrastructure API key or find your existing key.
- Click the Actions icon > Details to copy the API key value:
- Assign your user permissions to manage DNS in the account. For more information about managing classic infrastructure access, see Classic infrastructure permissions:
- Click the Classic infrastructure tab to manage your classic infrastructure permissions.
- In the Services section, ensure that the Manage DNS permission is selected.
Adding DNS provider configurations to your Secrets Manager instance
- In the console, click the Menu icon > Resource List.
- From the list of services, select your instance of Secrets Manager (or create a Secret Manager instance).
- On the Secrets engines page, click the Public certificates tab.
- In the DNS providers table, click Add:
- Enter name and Select the DNS provider: IBM Cloud classic infrastructure and click Next:
- Enter the classic infrastructure username and API key and click Add:
- You should see the DNS provider configuration added:
Connecting third-party certificate authorities
Connect to a third-party certificate authority by adding a configuration to your instance with IBM Cloud Secrets Manager. A certificate authority (CA) is the entity that signs and issues your TLS certificates. By adding a CA configuration, you can specify the authority that you want to use when you order public certificates through Secrets Manager.
Creating a Let’s Encrypt ACME account
Secrets Manager uses the Automatic Certificate Management Environment (ACME) protocol. The ACME protocol makes it possible to automatically obtain browser trusted certificates from a certificate authority without human intervention.
Create an account by using the ACME account creation tool. Once you create the account, keep the Account information (json file) and the Private key (pem file) in a safe place:
Adding a certificate authority configuration
Add certificate authority configurations to your service instance by using the Secrets Manager UI:
- In the console, click the Menu icon > Resource List.
- From the list of services, select your instance of Secrets Manager.
- On the Secrets engines page, click the Public certificates tab.
- In the Certificate authorities table, click Add.
- Enter name and select Let’s Encrypt for the Certificate authority:
- Add the private key file in PEM format that’s associated with your ACME account:
- Click Add. You should see the certificate authority configured.
Ordering public certificates from third parties
You can also order a certificate by using Secrets Manager. When you order a certificate, domain validation takes place to verify the ownership of your selected domains. This process can take a few minutes to complete.
- In the console, click the Menu icon > Resource List.
- From the list of services, select your instance of Secrets Manager.
- In the Secrets table, click Add:
- From the list of secret types, click the TLS certificates tile:
- Click the Order a public certificate tile:
- Enter the details of your certificate:
- Add a name and description to easily identify your certificate.
- Select a certificate authority configuration: LetEncrypt.
- Select a DNS provider configuration: ClassicInfraDNS.
- Add the domains to include in your request: *.tnexample.com.
- Click Order:
- After you submit your certificate details, Secrets Manager sends your request to the selected certificate authority.
- After a certificate is issued, you can check the issuance details of your certificate by clicking the Actions icon > View details:
- Copy the certificate CRN value:
Creating a secret in the cluster
- Make sure the Secrets Manager instance is registered as an Ingress instance in the cluster:
- Create a secret with the certificate. I have a sample hello-world service running in the cluster. Refer to this blog post to use this sample:
- Set CERTCRN as I copied the certificate CRN value in the previous step:
- Run the command to create a secret:
- Verify the secret:
4. Define an Ingress resource that uses your custom domain to route incoming network traffic to the service
Create an Ingress resource to define the routing rules that use your custom domain to route traffic to your application.
- Create an Ingress with the custom domain host and the custom domain secret. The following is an example configuration for the Ingress resource (hello-world-ingress.yaml):
- Apply the ingress configuration:
- Verify by accessing your app with the Ingress subdomain and the path https://CUSTOM-DOMAIN-HOST/APP-PATH, and you should see the HTTPS connection is established with the valid custom domain certificate:
Learn more
I hope that you now understand how you can configure a TLS certificate with a custom domain in a Kubernetes cluster so that you can access an application with the custom domain. If you want to learn more, the following links will help:
- IBM Cloud Secrets Manager
- Publicly exposing apps with ALBs that run the Kubernetes Ingress image
- How to Use the Ingress Application Load Balancer to Expose an App Outside a Kubernetes Cluster
- Managing TLS and Opaque certificates and secrets with IBM Cloud Secrets Manager
- Getting started with Domain Name Registration
- What is a secrets engine?