Configure a Custom Domain

Overview

This quick start will demonstrate how to:

• Create and configure a domain resource within Control Plane using both path and subdomain based routing to serve requests to your workload.
• Review and test your configured domain.

Prerequisites

• A running Workload. If you don't have one, follow this Quick Start.
• Access to a domain name and the ability to update its DNS records.
• Review:
  • Configure a Domain Guide.
  • Domain Reference.

Step One - Register your APEX Domain

An apex domain, also known as a root domain, refers to a domain name that does not have any subdomain prefix (e.g., example.com).

Even if the apex domain isn't served at Control Plane, it needs to be created and configured for verification. This verification is done by adding a TXT record to DNS.

For this quick start guide, we'll set up the apex domain solely for verification, without configuring any routing.

1. Create a new Domain resource by using one of the following methods:

   • Clicking Domains in the left menu and click New, or
   • Click the Create dropdown in the upper right corner and select Domain.

2. The console will prompt for the domain name (e.g., example.com). Enter your apex domain and click Continue.

3. The console will display the necessary TXT record to be added to DNS. Once you've added it, wait a few minutes for it to propagate online. Afterward, press the "I Configured DNS, Continue" button to allow Control Plane to verify the apex domain.

4. After verification, the console will default to show the configuration for Path Based Routing. Since the apex domain will not be routed to a workload, click the Edit button to the right of DNS & ROUTING MODES, then click Advanced Mode, then click Show More Options.

5. Select None for the Routing Mode, and click Continue.

6. The console will show the default setting for advanced mode. Scroll to the bottom of the page and click Create.

Your APEX domain has been successfully created at Control Plane and sub-domains of the apex domain can now be created.

Step Two - Review Routing Modes

Control Plane provides two routing modes for directing requests to your domain. Read the descriptions below to determine the best mode for your needs.

1. Path Routing

   • A CNAME records is added to DNS.
   • Best choice when path based routing is required.
   • You maintain full control of DNS for the domain.
   • CDN / WAF Compatible.
   • Examples:
     • https://sub.example.com/workload_one
     • https://sub.example.com/workload_two
   • Refer to Step Three for configuration instructions.

2. Subdomain Routing

   • NS records are added to your DNS to delegate DNS to Control Plane for this domain only.
   • Best choice when a unique DNS subdomain is required for each workload.
   • One-time configuration.
   • Works for all current and future workloads in a GVC.
   • Examples:
     • https://workload_one.sub.example.com
     • https://workload_two.sub.example.com
   • Refer to Step Four for configuration instructions.

Step Three - Configure Path Routing

1. Create a new domain resource by using one of the following methods:

   • Clicking Domains in the left menu and click New, or
   • Click the Create dropdown in the upper right corner and select Domain.

2. The console will prompt for the desired domain name (e.g., path.example.com). Click Continue.

3. The console will display the two routing modes. Click Use CNAME Record & Path Routing.

4. The console will prompt you to select the GVC which contains the workload that the domain will be routed to.

5. Once the GVC is selected, the console will prompt you to select the workload. After the workload is selected, click Continue.

6. The required CNAME record will be displayed. This record will need to be added by the person who is responsible for maintaining DNS for the domain. After adding it, allow a few minutes for propagation across the Internet. Click the I have created the DNS record checkbox and then click Create.

Your domain has been successfully created at Control Plane and will serve the selected workload on the path "/" once DNS is updated and the certificates have been generated.

Additional routes and advanced domain configuration options are available by clicking the Edit link and clicking the Advanced Mode button. For additional details on path based routing, click here.

Step Four - Configure Subdomain Routing

1. Create a new domain resource by using one of the following methods:

   • Clicking Domains in the left menu and click New, or
   • Click the Create dropdown in the upper right corner and select Domain.

2. The console will prompt for the desired domain name (e.g., sub.example.com). Click Continue.

3. The console will display the two routing modes. Click Use NS Records & Subdomain Routing.

4. The console will prompt you to select the GVC which contains the workloads that the domain will be routed to. Click Continue.

5. The required NS records will be displayed. These records will need to be added by the person who is responsible for maintaining DNS for the domain. After adding it, allow a few minutes for propagation across the Internet. Click the I have created the DNS record checkbox and then click Create.

Your domain has been successfully created at Control Plane and will serve all the workloads within the GVC using the pattern: https://WORKLOAD_NAME.sub.example.com.

Advanced domain configuration options are available by clicking the Edit link and clicking the Advanced Mode button. For additional details on subdomain routing, click here.

Step Five - Review and Test Domains

1. In the left menu, click on Workloads and choose the workload specified during the domain configuration. If your org has multiple GVCs, ensure the GVC currently selected matches the one chosen during the domain configuration.

2. The Workload Info page will be displayed which includes the list of URLs that will route to this workload.

   • Internal Name: Use this URL to call another workload within your Org. See the service-to-service quick start for more information.
   • Canonical Endpoint (Global): This URL uses the default Control Plane domain cpln.app and is typically used for troubleshooting or when there is no domain serving the workload.
   • The rest of the list displays the URLs configured for path-based or subdomain-based routing.
   • This list of URLs are automatically secured using TLS certificates, load balanced, and DNS geo-routed to the nearest healthy location.

3. Click Deployments. This page shows the providers this Workload is deployed to. Next to each provider is the location specific URL. Clicking the Open link will load the Workload only in that location. These links can be used for troubleshooting.

Summary

By taking the step to configure your custom domain name enables a secure and reliable pathway to access your Workload. This not only enhances the integrity and reliability of your operations but also ensures that every interaction is seamlessly aligned with the identity and branding of your organization. This practice fosters trust and consistency, especially when dealing with external stakeholders or customers who recognize and resonate with your brand's identity.