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.
  • Access to a domain name and the ability to update its DNS records.
  • Optional:
    • Install the CLI.

Step One - APEX Domain Verification

Follow step one in the domain quick start to create and verify the apex domain name using the Console UI.

The CLI can also be used to create the apex domain for verification and routing configuration. See the sample manifiest files below.

Refer to the Domain Verification section within the Domain reference page for additional details.

Step Two - Create Domain

A Domain can be created using the following methods:

Create using the UI Console

Follow step two in the domain quick start for detailed instruction on how to create and configure your domain name using the console UI.

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 TXT DNS records must exist and be propagated only for the apex domain. The DNS entries for the subdomain will not be verified on creation. Routing and certificate generation will not occur until the records have been added, propagated, and the target workload is in a ready state and can serve requests.

APEX Verification Only

Configure Domain for APEX Verification

  • Substitute example.com with your domain.
copy
kind: domain
name: example.com
description: example.com
spec:
dnsMode: cname

APEX Verification and Path Based Routing

Configure Domain for APEX Verification and Path Based Routing.

  • Substitute example.com with your domain, GVC_NAME, and WORKLOAD_NAME
  • The example YAML manifest below assumes there is a workload named WORKLOAD_NAME serving requests on port 4200 in the GVC named GVC_NAME.
copy
kind: domain
name: example.com
description: example.com
tags: {}
spec:
acceptAllHosts: false
dnsMode: cname
ports:
- number: 443
protocol: http2
routes:
- port: 4200
prefix: /
workloadLink: //gvc/GVC_NAME/workload/WORKLOAD_NAME

APEX Verification and Subdomain Based Routing

Configure Domain for APEX Verification and Subdomain Based Routing.

  • Substitute example.com with your domain, GVC_NAME, and TLS_SECRET
  • Notice that the dnsMode is set to cname and a TLS secret is required.
copy
kind: domain
name: example.com
description: example.com
tags: {}
spec:
dnsMode: cname
gvcLink: //gvc/GVC_NAME
ports:
- number: 443
tls:
serverCertificate:
secretLink: //secret/TLS_SECRET

Subdomain and Path Based Routing

Configure a subdomain for path based routing.

  • Substitute sub.example.com with your domain, GVC_NAME, and WORKLOAD_NAME.
  • The example YAML manifest below assumes there is a workload named WORKLOAD_NAME in the GVC named GVC_NAME.
copy
kind: domain
name: sub.example.com
description: sub.example.com
tags: {}
spec:
dnsMode: cname
ports:
- routes:
- prefix: /
workloadLink: //gvc/GVC_NAME/workload/WORKLOAD_NAME

Subdomain and Subdomain Based Routing

Configure a subdomain for subdomain based routing.

  • Substitute sub.example.com with your domain and GVC_NAME.
  • All workloads within the GVC will have endpoints created with the subdomain in the format: https://WORKLOAD_NAME.sub.example.com/.
copy
kind: domain
name: sub.example.com
description: sub.example.com
tags: {}
spec:
dnsMode: ns
gvcLink: //gvc/GVC_NAME

Complete Domain YAML Manifest

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

NOTE

The examples above use the minimum properties required to create/update a domain based on your requirements.

The complete YAML manifest templates below contain both the required and optional properties.

Notes:

  • dnsMode can either be cname (for path based) or ns (for subdomain based). For an apex domain, it must be cname.
  • acceptAllHosts will only be active if the dedicated load balancer is enabled on the GVC.
  • For the routes configued for path based routing, the hostPrefix will only be active if the dedicated load balancer is enabled on the GVC and the acceptAllHosts propert is set to true.
  • Path Based Routing
copy
kind: domain
name: sub.domain.com
description: sub.domain.com
tags: {}
spec:
acceptAllHosts: false
dnsMode: cname
ports:
- cors:
allowCredentials: true
allowHeaders:
- '*'
allowMethods:
- '*'
allowOrigins:
- exact: '*'
exposeHeaders:
- '*'
maxAge: 24h
number: 443
protocol: http2
routes:
- hostPrefix: example
port: 4200
prefix: /example
replacePrefix: /v1/example
workloadLink: //gvc/GVC_NAME/workload/WORKLOAD_NAME_01
- prefix: /
workloadLink: //gvc/GVC_NAME/workload/WORKLOAD_NAME_02
tls:
cipherSuites:
- ECDHE-ECDSA-AES256-GCM-SHA384
- ECDHE-ECDSA-CHACHA20-POLY1305
- ECDHE-ECDSA-AES128-GCM-SHA256
- ECDHE-RSA-AES256-GCM-SHA384
- ECDHE-RSA-CHACHA20-POLY1305
- ECDHE-RSA-AES128-GCM-SHA256
- AES256-GCM-SHA384
- AES128-GCM-SHA256
clientCertificate:
secretLink: //secret/TLS_SECRET_CLIENT_CERTIFICATE
minProtocolVersion: TLSV1_2
serverCertificate:
secretLink: //secret/TLS_SECRET_SERVER_CERTIFICATE
  • Subdomain Based Routing
copy
kind: domain
name: sub.example.com
description: sub.example.com
tags: {}
spec:
acceptAllHosts: true
dnsMode: ns
gvcLink: //gvc/GVC_NAME
ports:
- cors:
allowCredentials: false
allowHeaders:
- '*'
allowMethods:
- '*'
allowOrigins:
- exact: '*'
exposeHeaders:
- '*'
maxAge: 24h
number: 443
protocol: http2
tls:
cipherSuites:
- ECDHE-ECDSA-AES256-GCM-SHA384
- ECDHE-ECDSA-CHACHA20-POLY1305
- ECDHE-ECDSA-AES128-GCM-SHA256
- ECDHE-RSA-AES256-GCM-SHA384
- ECDHE-RSA-CHACHA20-POLY1305
- ECDHE-RSA-AES128-GCM-SHA256
- AES256-GCM-SHA384
- AES128-GCM-SHA256
clientCertificate:
secretLink: //secret/TLS_SECRET_CLIENT_CERTIFICATE
minProtocolVersion: TLSV1_2
serverCertificate:
secretLink: //secret/TLS_SECRET_SERVER_CERTIFICATE

Required DNS Records

To successfully add a Domain to your Org, DNS records are required to be added.

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.

When created the domain with the console UI, the final step will display the DNS records that need to be added.

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

Example:

  • Apex Domain - CNAME Mode Only:
RECORD/HOSTTYPETTLVALUE
_cplnTXT600ORG_ID_GUID
  • Subdomain (e.g., sample.domain.com) - CNAME Mode (Path Based Routing)
RECORD/HOSTTYPETTLVALUE
_cpln-sampleTXT600ORG_ID_GUID
sampleCNAME600GVC_ALIAS.cpln.app

Note: The GVC_ALIAS can be obtain from the console UI by clicking on the GVC and it will be displayed on the Info page. Using the CLI, executing the command cpln gvc get GVC_NAME will output the alias.

  • Subdomain (e.g., sample.domain.com) - NS Mode (Subdomain Based Routing)
RECORD/HOSTTYPETTLVALUE
_cpln-sampleTXT600ORG_ID_GUID
sampleNS1800ns1.cpln.cloud
sampleNS1800ns2.cpln.cloud
sampleNS1800ns1.cpln.live
sampleNS1800ns2.cpln.live
NOTE

In the examples above, the TXT record for the subdomain is only required if the domain is created in an Org that doesn't contain the apex domain. ORG_ID_GUID should be set to theid value of the Org object. The record _cpln-sample is generated from the last segment of the domain, _cpln-${lastSegment}. In the case of an apex domain, the TXT record to add is _cpln.

The TXT record can include the ID of multiple Orgs in cases where the domain is allowed to be used in multiple Orgs.

The verification record can exist at any segment of the Domain.

For example, the subdomain, two.sample.domain.com can be verified using any of the following TXT records:

  • _cpln-two.sample.domain.com
  • _cpln-sample.domain.com
  • _cpln.domain.com
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 a Content Delivery Network (CDN) Domain

Refer to the Configure a CDN guide.

Advanced Mode

When editing a domain within the console UI, the following options are available when clicking Advanced Mode:

Dedicated Load Balancing

Refer to the following pages for details on enabling dedicated load balancing:

Additional Setting

  • The accept all hosts setting (acceptAllHosts in the above example manifest) can be enabled when dedicated load balancing is enabled.

  • Add additional ports configured with other supported protocols (TCP, etc.) when using a dedicated load balancer.
    • For each port, configure TLS Settings which includes setting the TLS version, forwarding client certificates, using custom server certificates, and allowed cipher suites.

    • For each port, configure custom CORS settings.

  • When using Path Based Routing:

    • Additional routes can be added with unique prefixes and, optionally, a replace prefix.
    • When dedicated load balancing is enabled, a host prefix (hostPrefix in the above example manifest) can be optionally defined.
Copyright © 2024 Control Plane Corporation. All rights reserved. Revision 49289c07
Contents