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 (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.

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.

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
WARNING

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

  • 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):
RECORD/HOSTTYPETTLVALUE
_cplnTXT600ORG_ID_GUID
  • Using the domain (non-Apex): sample.domain.com
RECORD/HOSTTYPETTLVALUE
_cpln-sampleTXT600ORG_ID_GUID
sampleNS1800ns1.cpln.cloud
sampleNS1800ns2.cpln.cloud
sampleNS1800ns1.cpln.live
sampleNS1800ns2.cpln.live

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.

TIP

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.

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.

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