Working with custom domain mappings

Domain mappings provide the URL route to your Code Engine application or function within a project. With Code Engine, these mappings are automatically created, by default, whenever you deploy an application or create a function. However, you can map your own custom domain to a Code Engine application or function to route requests from your custom URL to your application or function from the Code Engine console or CLI.

If you want to target your Code Engine application or function with a domain that you own, you can use a custom domain mapping. When you set a custom domain mapping in Code Engine, you define a 1-to-1 mapping between your fully qualified domain name (FQDN) and a Code Engine application or function in your project.

A custom domain mapping must point to only one Code Engine application or function. However, you can configure multiple domain mappings to a single application or function.

To work with custom domain mappings in Code Engine, complete the following steps. Notice that some steps are completed outside of Code Engine.

Review the Considerations before you use custom domain mappings in Code Engine.
Obtain your custom domain from a domain registrar (outside of Code Engine).
Configure a custom domain mapping in Code Engine for your application or function. (from the Code Engine console or CLI).
Complete the custom domain configuration with your domain registrar. (outside of Code Engine)

After you have completed the setup and configuration of your custom domain with your domain registrar, and you have completed the configuration of a domain mapping for your application or function in Code Engine, test the domain mapping.

In Code Engine, you can view, update, or delete domain mappings to your applications or functions.

Considerations before you use custom domain mappings in Code Engine

Before you implement custom domain mappings in Code Engine, be aware of the following considerations:

Code Engine supports custom domain mappings for domains that are protected with a SSL/TLS certificate, which is signed by a public, trusted certificate authority (CA).
You can define custom domain mappings that point to public domain names.
If your domain name can be resolved only by a nonpublic domain name system (DNS), you must provide a certificate that lists the domain name and is signed by a public, trusted CA.
You must provide the entire certificate chain, starting with the certificate that corresponds to the custom domain, followed by all intermediate certificates up to the root certificate.
You cannot use self-signed certificates.
You cannot use certificates that are signed by an untrusted or a nonpublic enterprise CA.
Your certificate must have an expiry date that is set.

Obtaining a custom domain and its TLS certificate and private key

Before you configure custom domain mappings in Code Engine, you must first obtain your custom domain from a domain registrar (outside of Code Engine).

From a domain registrar, obtain your custom domain; for example, www.example.com.
From your certificate authority (CA), you must obtain a signed SSL/TLS certificate for your custom domain. This certificate is a type of digital certificate that is used to establish communication privacy between a server and a client. Certificates contain information that is used to create trusted and secure connections between endpoints. You must also obtain a matching private key for the TLS certificate. For security reasons, Code Engine supports only custom domain mappings that are configured with a TLS/SSL certificate that is signed by a public, trusted CA.

How can I obtain a certificate for my custom domain?

In an enterprise environment, work with your corporate domain administrator to obtain the necessary certificates. However, if the custom domain is within your control and you want quickly create a certificate that is not self-certified, then you can optionally use the Let's Encrypt service and Certbot to obtain a certificate.

Install Certbot. Certbot is a client for the Automatic Certificate Management Environment (ACME) protocol for automating interactions between a CA and a server. The Let's Encrypt service uses this client to verify domain ownership and issue certificates. From the Certbot Instructions page, select Other as the software and select the operating system for your workstation to obtain the applicable information to install the Certbot command line.
Run the following command to create your certificate. This example command creates a certificate for the example.com and www.example.com custom domains. Be sure to update the command for your own custom domain.
```
certbot certonly --manual --preferred-challenges dns --email webmaster@example.com --server https://acme-v02.api.letsencrypt.org/directory --agree-tos --domain example.com --domain www.example.com
```
To verify that you own the domain, set a TXT record with your domain registrar for the domains that you requested in the previous step with values that were provided with the Certbot tool output; for example, _acme_challenge.example.com and _acme_challenge.ww.example.com. After you set the TXT record, continue with the Certbot command.
Certbot retrieves the certificate that is signed by Let's Encrypt. The location where the certificate is stored is provided by the Certbot output. Find the fullchain.pem and privkey.pem files.

Example command to run Certbot on an Ubuntu system

sudo certbot certonly --manual --preferred-challenges dns --email webmaster@example.com --server https://acme-v02.api.letsencrypt.org/directory --agree-tos --domain example.com --domain www.example.com

Example output for the certificate request for example.com and www.example.com

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Please deploy a DNS TXT record under the name:
_acme-challenge.example.com.
with the following value:
<MASKED>
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Press Enter to Continue
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Please deploy a DNS TXT record under the name:
_acme-challenge.www.example.com
with the following value:
<MASKED>
(This must be set up in addition to the previous challenges; do not remove,
replace, or undo the previous challenge tasks yet. Note that you might be
asked to create multiple distinct TXT records with the same name. This is
permitted by DNS standards.)
Before continuing, verify the TXT record has been deployed. Depending on the DNS
provider, this may take some time, from a few seconds to multiple minutes. You can
check if it has finished deploying with aid of online tools, such as the Google
Admin Toolbox: https://toolbox.googleapps.com/apps/dig/#TXT/_acme-challenge.www.example.com.
Look for one or more bolded line(s) below the line ';ANSWER'. It should show the
value(s) you've just added.
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Press Enter to Continue
Successfully received certificate.
Certificate is saved at: /etc/letsencrypt/live/example.com/fullchain.pem
Key is saved at: /etc/letsencrypt/live/example.com/privkey.pem
This certificate expires on 2023-02-01.
These files will be updated when the certificate renews.
NEXT STEPS:
- This certificate will not be renewed automatically. Autorenewal of --manual certificates requires the use of an authentication hook script (--manual-auth-hook) but one was not provided. To renew this certificate, repeat this same certbot command before the certificate's expiry date.
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
If you like Certbot, please consider supporting our work by:
 * Donating to ISRG / Let's Encrypt: https://letsencrypt.org/donate
 * Donating to EFF: https://eff.org/donate-le
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Your certificate is ready.

Can I use Cloud Internet Services (CIS) for domain management when I am using custom domain mapping with Code Engine?

Yes, you can use IBM Cloud Internet Services for domain management with custom domain mapping with Code Engine.

To enable a domain that is managed by CIS to point to a Code Engine application or function, set the TLS encryption mode to End-to-End CA signed within CIS. This mode requires that you obtain a certificate that is generated and signed by a public and trusted CA, outside of CIS.

Because origin certificates ordered in CIS are not signed by a public and trusted CA, those certificates cannot be used for a domain mapping in Code Engine. You must obtain a CA signed certificated, outside of CIS.

How can I use Cloud Internet Services (CIS) with custom domain mapping?

You cannot use the CIS TLS encryption mode of End-to-End flexible with Code Engine custom domain mappings because this mode uses self-signed certificates that are not allowed. Instead, you can use the default TLS encryption mode of End-to-End CA signed. If you use the CIS TLS mode of End-to-End-flexible, you can switch to use the CIS TLS End-to-End CA signed mode, and obtain a CA signed certificate that is created outside of Cloud Internet Services (CIS).

Create the TLS/SSL certificate outside of CIS. See How can I obtain a certificate for my custom domain?
Create a custom domain mapping in Code Engine for your application or function with the certificate chain and the private key.
Obtain the CNAME record for the custom domain mapping.
In CIS, update the DNS records to point to your Code Engine project. In CIS, go to the DNS records page (Reliability>DNS) and Add the CNAME record.
Change the CIS mode. Go to the TLS security page (Security>TLS). Select End-to-end CA signed as the TLS mode.

If you need to register multiple domains and subdomains, such as example.com and www.example.com, you must repeat the previous steps 2 and 3 for each subdomain. You can consider creating a single certificate that covers more than one domain. However, you can use that single certificate only one time in a region. If you plan to use your custom domains in more than one project in a single region, keep them separate.

How do I obtain the CNAME record for a custom domain mapping?

Code Engine provides the CNAME target for your defined custom domain mapping.

To obtain the CNAME record from the Code Engine console, open your defined custom domain mapping and view the Update domain mapping page. Open the Update domain mapping page in one of the following ways:

From the Domain mappings table, click in the row of your defined custom domain.
Click the Actions icon > Edit to edit the mapping.

From the Update domain mappings page, you can obtain the CNAME target value. For example, the www.example.com mapping has the custom.abcdabcdabc.us-east.codeengine.appdomain.cloud CNAME value, where abcdabcdabc is an automatically generated unique identifier and us-east is the region of your project.

To obtain the CNAME record with the CLI, use the ibmcloud ce domainmapping get command. For example,

ibmcloud ce domainmapping get --domain-name www.example.com

Example output

Getting domain mapping 'www.example.com'...
OK

Domain Name:  www.example.com  
CNAME:        custom.abcdabcdabc.us-south.codeengine.appdomain.cloud  
Target Name:  myapp  
Target Type:  app  
TLS Secret:   mytlssecret  
Status:       ready

After you have the CNAME target, you are ready to add the CNAME record entry to the DNS settings of your custom domain. Note that publishing of the CNAME record with the domain registrar can take some time to populate the DNS changes in the internet.

Configuring custom domain mappings in Code Engine

Now that you are familiar with the concepts of working with custom domain mappings and you have obtained your custom domain from a domain registrar, you can configure your Code Engine applications or functions to use custom domain mappings. See

Viewing domain mappings

Viewing domain mappings from the console

You can view a listing of all automatically generated and custom domain mappings for your application or function from the console. By default, the contents of the table are scoped to custom domain mappings. Use the Type filter to modify the view.

This view displays information about the expiration of the certificate that is associated with your mapping. When the certificate expires, the application or function is no longer reachable with the domain mapping, and this condition yields an SSL error. If you have a certificate that is about to expire, update the custom domain mapping to use an updated certificate.

This view also displays information about the specific application or function that is associated with the domain mapping, and the type of the domain mapping. For mappings that are generated by Code Engine, the type can be System-public, System-private, or System-internal. For custom domain mappings that you create, the type is Custom.

After your project is in Active status, click the name of your project on the Code Engine Projects page.
From the Overview page, click Domain mappings.
From the Domain mappings page, view a listing of the defined domain mappings for your existing applications or functions. The Type indicates whether the mapping is automatically generated or if it is a custom domain mapping.

Viewing domain mappings with the CLI

To view a listing of all custom domain mappings for your applications or functions with the CLI, use the ibmcloud ce domainmapping list command. For example,

ibmcloud ce domainmapping list

Example output

Listing domain mappings...
OK

Name              CNAME                                                        Target  Target-Type  Status  Secret Name  Age
www.example.com   custom.abcdabcdabc.us-south.codeengine.appdomain.cloud       myapp   app          ready   mytlssecret  36m

To view a listing of all domain mappings for your applications or functions, including both custom domain mappings that you create and automatically generated domain mappings that Code Engine creates, specify the --all option with the ibmcloud ce domainmapping list command. Custom domain mappings display a value for CNAME.

Updating domain mappings

When you create a custom domain mapping, the TLS secret is valid until the certificate expires. From the domain mapping page, you can view information about the remaining days until the certificate expires.

It is important to know whether the certificate that is used with your custom domain lists multiple domain names, or if it uses a wildcard certificate. When this case is true and your certificate is soon to expire (or has expired), you must update the existing TLS secret for the domain mapping with updated credentials, rather than creating a different TLS secret with updated credentials for your domain mapping.

Updating a domain mapping from the console

Suppose the custom domain mapping for www.example.com has a certificate that expires soon. You can update the domain mapping from the console to use an updated certificate or even replace the TLS secret for the mapping. You can also update your domain mapping to point to a different application or function in your project.

From the Code Engine Projects page, go to your project.
From the Overview page, click Domain mappings.
From the Domain mappings page, click the Actions icon > Edit to edit the mapping. Or, you can click in the row of your defined custom domain to update the mapping.
From the Update a domain mapping page, you can change the application or function that is associated with this domain mapping, or you can replace or update the TLS secret for this mapping.
Click Update to save your changes.

After you update the mapping, you can view the list of domain mappings for the latest changes.

Updating a domain mapping with the CLI

To update a custom domain mapping, use the ibmcloud ce domainmapping update command.

Suppose the custom domain mapping for www.example.com has a certificate that expires soon. You can update the domain mapping to use an updated certificate or even replace the TLS secret for the mapping with the --tls-secret option. You can also update your domain mapping to point to a different application or function in your project with the --target option.

The following example updates the www.example.com custom domain mapping to use an updated TLS secret, mytlssecret.

Update the TLS secret mytlssecret with updated certificate and private key information, which are contained in the mycertchain2.txt and myprivatekey2 files that reside on a local workstation.
```
ibmcloud ce secret update --name mytlssecret --cert-chain-file  mycertchain2.txt --private-key-file myprivatekey2.txt
```
Example output
```
Updating secret mytlssecret..
OK
```

Update the domain mapping to use the updated TLS secret.

ibmcloud ce domainmapping update --domain-name www.example.com --tls-secret mytlssecret2

Example output

Getting domain mapping 'www.example.com.org'...
Updating domain mapping 'www.example.com.org'...

Deleting domain mappings

When you delete a domain mapping, you are removing the association of your Code Engine application or function with your custom domain mapping within Code Engine. This action does not delete the associated application, function, or TLS secret.

If you delete an application or function that is referenced in a domain mapping, this action also deletes any custom domain mapping that is associated with the application or function.

When you delete a custom domain mapping, if the DNS settings of your domain are still configured, such that the CNAME points to the Code Engine project, your traffic still is routed to the Code Engine project. However, the request is answered with a 404 (not found) error message. Ensure that the associated CNAME record for the fully qualified domain name is updated in the DNS settings by the domain registrar.

Deleting domain mappings from the console

From the console, you can delete only domain mappings of type Custom. Domain mappings that are automatically generated by Code Engine cannot be deleted.

To delete a custom domain mapping from the console,

From the Code Engine Projects page, go to your project.
From the Overview page, click Domain mappings to view a listing of defined domain mappings.
(Optional) Click Type to filter the domain mappings by type.
From the Domain mappings page, delete the custom domain mapping that you want to remove from your application or function. Click the Actions icon > Delete to delete the mapping.

Deleting domain mappings with the CLI

To delete a custom domain mapping with the CLI, use the ibmcloud ce domainmapping delete command.

You can delete only custom domain mappings, and not domain mappings that are generated by Code Engine. Run the ibmcloud ce domainmapping list command to display a list of custom domain mappings with the CLI. A custom domain mapping has a generated CNAME record. In the CLI, you can obtain the generated CNAME value for a specified custom domain mapping by using the ibmcloud ce domainmapping get command.

ibmcloud ce domainmapping delete --domain-name www.example.com -f

Example output

Deleting domain mapping 'www.example.com'...
OK

Next steps

Now that you are familiar with working with custom domain mappings and you have obtained your a custom domain with its TLS certificate and private key, you are ready to configure a custom domain mapping in Code Engine for your application or function.