​
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:

cpln apply -f FILE_NAME.yaml --org ORG_NAME

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.
YAML
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.
YAML
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.
YAML
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.
YAML
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/.
kind: domain
name: sub.example.com
description: sub.example.com
tags: {}
spec:
  dnsMode: ns
  gvcLink: //gvc/GVC_NAME

​
Setting Custom Headers

Set custom headers on any domain route.

  • Substitute sub.example.com with your domain, GVC_NAME, and WORKLOAD_NAME.
  • Substitute HEADER with your header, VALUE with your value. You may add headers as well.
  • The example YAML manifest below assumes there is a workload named WORKLOAD_NAME in the GVC named GVC_NAME.
YAML
kind: domain
name: sub.example.com
description: sub.example.com
tags: {}
  spec:
  dnsMode: cname
  ports:
    - routes:
        - prefix: /
          workloadLink: //gvc/GVC_NAME/workload/WORKLOAD_NAME
          headers: 
            request:
              set:
                HEADER: VALUE

​
Complete Domain YAML Manifest

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

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
YAML
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
          headers:
            request:
              set:
                EXAMPLE_HEADER: EXAMPLE_VALUE
        - regex: /user/.*/profile
          workloadLink: //gvc/GVC_NAME/workload/WORKLOAD_NAME_02
        - prefix: /
          workloadLink: //gvc/GVC_NAME/workload/WORKLOAD_NAME_03
      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
YAML
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.

Examples:

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

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.

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.