Configure a Domain

Overview

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

Prerequisites

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).
TIP

When creating an apex domain for verification:

  1. Select CNAME for the DNS Mode.
  2. Select None for the Routing Mode.
  3. Follow the instruction in the DNS page to create the _cpln TXT record.
TIP

To create:

  1. An apex domain that will be routed to a workload, or
  2. A domain that is fronted by a proxy (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, a TLS secret must be assigned to the domain.

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
WARNING

Before using the CLI's apply command, the DNS entries must exist and propagated.

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

RECORD/HOSTTYPETTLVALUE
_cpln-sampleTXT600ORG_ID_GUID
sampleNS1800ns1.cpln.cloud
sampleNS1800ns2.cpln.cloud
sampleNS1800ns1.cpln.live
sampleNS1800ns2.cpln.live

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.

NOTE

After the DNS records have been created, the propagation time for the changes to take effect depends on the cache setting of your domain's DNS Start of Authority (SOA) record.

Once the records are fully propagated, any DNS changes to your subdomain will be reflected within a few seconds.

Copyright © 2022 Control Plane Corporation. All rights reserved. Revision 68a8865b
Contents