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:

• Console UI
• CLI
• Terraform Provider

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

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.

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

• Subdomain (e.g., sample.domain.com) - CNAME Mode (Path Based Routing)

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)

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:

• Configuring the GVC for dedicated load balancing.
• After enabling, these additional domain configuration options will be available for configuration.

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.