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 before subdomains can be created.

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

If multiple Orgs are creating subdomains with the same apex domain, the apex domain verification only needs to be performed in 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.
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 (HTTP2 or HTTP).
   • 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).

Refer to the Domain reference page for additional details.

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.

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.

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

copy
kind: domain
name: sub.example.com
description: Domain sub.example.com
tags: {}
spec:
  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
        minProtocolVersion: TLSV1_2

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:

Using the domain: sample.domain.com

To obtain the ORG_ID_GUID, run the CLI command: cpln org get ORG_NAME --output json.

The output of the command will display all the properties of the Org object. Use the value of the id key for the TXT value.