Configure a Domain

Overview

Follow the steps below to configure a custom Domain within your Org.

Prerequisites

• Review the Domain reference page.
• Permissions to configure a Domain.
• Optional:
  • Install the CLI.

APEX Domain Verification

In order for DNS to work, the apex domain (e.g., example.com) needs to be created in Control Plane and verified (using a TXT record) before subdomains can be created. This is required even if the apex domain is not served from Control Plane.

Once the apex domain is verified, subdomains can be added to the same Org without needing the TXT record verification step.

If multiple Orgs are creating subdomains using the same apex domain, the apex domain verification only needs to be performed in only one of the Orgs.

Create using the UI Console

Create a new Domain 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.

The console will prompt you for the desired domain name to associate with your Org.

After clicking Next, the Spec page will be displayed.

On this page, the following can be configured:

1. The DNS Mode (Note: When creating an apex domain, only CNAME is allowed.)
   • CNAME: Canonical Name Record. Maps one domain name (alias) to another.
   • NS: Nameserver Record. Indicates which DNS server is authoritative for that domain. Using this mode will allow Control Plane to manage the certificates for the domain unless a customer server certificate is configured (step 3 below).
2. Routing Mode
   • None: No routing is perfomed.
   • Subdomain Based: Maps the Domain to a GVC.
     • This mode exposes each Workload as: https://WORKLOAD_NAME.SUB_DOMAIN.DOMAIN
   • Path Based: Maps a path to a specific workload.
     • This mode is configured as an ordered list of path to workload mapping (i.e., sub.example.com/foo goes to workload A).
     • A Replace Prefix can be provided that will replace the given path string before forwarding to the destination Workload.
     • Note: A request will be served by the first path match. A path defined as / should be placed at the end of the list if multiple paths are configured.
3. Port Configuration
   • Endpoint Protocol (select HTTP2 or HTTP).
   • Configure CORS:

• Configure TLS:
  • Add/Remove Cipher Suites.
  • Allow Forwarding of Client Certificates (with an optional certificate authority PEM, stored as a TLS Secret).
  • Allow Custom Server Certificate (requires a TLS server certificate, stored as a TLS Secret).

After clicking Next, any required DNS entries will be displayed.

Once the DNS entries are added and the changes are propagated, click on the acceptance checkbox and click Create. The platform will verify the DNS entries and, if successful, add the domain to your Org.

Refer to the Domain reference page for additional details.

Create using the CLI

A Domain can be created / updated using the CLI's apply command.

Below are a few sample Domain manifests (in YAML) that can be used as input to the CLI's apply command.

After updating and saving the manifests to a local file, execute the following command to apply:

copy
cpln apply -f FILE_NAME.yaml --org ORG_NAME

• Map Domain to a GVC (substitute sub.example.com and GVC_NAME):

copy
kind: domain
name: sub.example.com
spec:
  dnsMode: ns
  gvcLink: //gvc/GVC_NAME

• Map Domain to a GVC with Path Based Routing (substitute sub.example.com, GVC_NAME, and WORKLOAD_NAME):

NOTE: The port number and minimum TLS are currently static. This will be modifiable in the future.

copy
kind: domain
name: sub.example.com
description: Domain sub.example.com
tags: {}
spec:
  ports:
    - number: 443
      protocol: http2
      routes:
        - prefix: /
          workloadLink: //gvc/GVC_NAME/workload/WORKLOAD_NAME
      tls:
        cipherSuites:
          - TLS_RSA_WITH_AES_256_GCM_SHA384
          - TLS_RSA_WITH_AES_128_GCM_SHA256
          - TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
          - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
          - TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
          - TLS_CHACHA20_POLY1305_SHA256
          - TLS_AES_256_GCM_SHA384
          - TLS_AES_128_GCM_SHA256

• Configure Domain for APEX Verification (substitute example.com):

copy
kind: domain
name: example.com
spec:
  dnsMode: cname

• Complete Domain YAML Manifest:

Use the manifest YAML template below to create a Domain per your requirements.

copy
kind: domain
name: sub.example.com
description: Domain Description
tags: {}
spec:
  dnsMode: ns
  gvcLink: //gvc/GVC_NAME
  ports:
    - cors:
        allowCredentials: true
        allowHeaders:
          - ALLOWED_HEADER
        allowMethods:
          - GET
          - POST
        allowOrigins:
          - exact: example-origin.com
        exposeHeaders:
          - EXPOSED_HEADER
        maxAge: 24h
      protocol: http2  
      tls:
        cipherSuites:
          - TLS_RSA_WITH_AES_256_GCM_SHA384
          - TLS_RSA_WITH_AES_128_GCM_SHA256
          - TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
          - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
          - TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
          - TLS_CHACHA20_POLY1305_SHA256
          - TLS_AES_256_GCM_SHA384
          - TLS_AES_128_GCM_SHA256
        clientCertificate:
          secretLink: //secret/TLS_SECRET_CLIENT_CERTIFICATE
        serverCertificate:
          secretLink: //secret/TLS_SECRET_SERVER_CERTIFICATE

Required DNS Entries

To successfully add a Domain to your Org using the NS DNS Mode, the following DNS entries are required.

The values in the sample below might not correspond to the entries necessary for your domain. Use the values that are presented during the creation of the domain.

These records will need to be sent to the network administrator in charge of handling the domain's DNS configuration.

Example:

• Apex Domain (using the CNAME DNS Mode):

• Using the domain (non-Apex): sample.domain.com

NOTE: The record _cpln-sample is based on the sub-domain. The text after _cpln- will be the sub-domain (i.e., _cpln-SUB_DOMAIN). This record (_cpln-SUB_DOMAIN) is optional if the Apex Domain has been verified in one of your Orgs.

Configure APEX / CDN / Custom Cert Domains

To create:

1. An apex domain that will be routed to a workload, or
2. A domain that is fronted by a CDN (such as CloudFlare), or
3. A domain using a certificate not generated by Control Plane

Select CNAME for the DNS Mode and select either Subdomain Based or Path Based and configure as necessary.

When using the CNAME mode:

1. A TLS secret must be assigned to the domain by:

   • From the Domain's Spec page:
     • Toggle the Configure TLS switch, then
     • Toggle the Use Custom Server Certificate, then
     • Select the desired TLS secret.

2. A CNAME record must be created at the Domain's hosted DNS. The value of this record will be the Global Endpoint URL of the target Workload.