Domains

Overview

Workloads can be accessed using any domain names you own. Domains are scoped to an Org.

A Domain can only be mapped to one GVC and, in turn, can be used and mapped to one or more Workloads within the GVC.

There are two different dnsMode settings for Domains.

dnsModeDescriptionRestrictions
cnameA cname record will be configured in your dns for each specific endpoint.Subdomain mapped domains must provide their own server certificate.
nsAn NS record will be configured in DNS to instruct clients to query Control Plane DNS servers for this domain and all subdomains of this domain.Only DNS records configured by Control Plane will be able to be queried for this subdomain.

Default Domain Names

If a Domain is not mapped to a GVC, the default domain names provided to Workloads are:

  • Global and canonical endpoints: cpln.app
  • Individual location endpoints: controlplane.us

Configure a Domain

Refer to the Configure a Domain guide for additional details.

Configuration Notes

TIP

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 used by any workloads on 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.

When initially adding a custom domain, the console will display the required DNS entries and, during creation, verify that TXT verification records were created and can be resolved.

The DNS link will display the required DNS entries for reference anytime.

Subdomain Based Routing

Subdomain based routing allows a domain to be mapped to all workloads in a GVC.

The associated Workload's global endpoint URL will follow the format:

https://${WORKLOAD_NAME}.${DOMAIN_NAME}

If you prefer to use the base domain as https://${DOMAIN_NAME}, use path based routing instead (below).

Path Based Routing

Path based routing allows requests to a specific path prefix be routed to a specific workload.

When path based routing is enabled, the global endpoint URL will follow the format:

https://DOMAIN/PATH_PREFIX, where the PATH_PREFIX is mapped to a Workload.

For example:

A request to https://DOMAIN/foo/... can be routed to Workload A, and a request to https://DOMAIN/bar/... can be routed to Workload B.

NOTE: All path prefix values must be unique.

Path Prefix Replacement

A path prefix can be configured to be replaced when forwarding the request to the Workload.

For example:

A request to the domain https://DOMAIN/users/ can have the path prefix /users/ replaced with the path prefix /v2/users/ when forwarding the request to the target Workload.

Root Path Prefix

The / path will match any unmatched path prefixes for the subdomain.

Path Order

The order of the path prefix list is adjustable. When a request to the Domain is received, the first match will be processed.

Note: When using the / path prefix, along with other path prefixes, that entry should be last in the list since it will match ALL requests.

Port Configuration

External Port

TLS requests to a configured Domain are served on the standard TLS port 443.

This port will be configurable in the future.

Protocol

The following protocols are suppored and can be configured on a Domain:

  1. HTTP2
  2. HTTP

TLS Settings

The minimum TLS protocol version is 1.1.

The minimum version shoudl be set as high as possible and all moderm browsers support the default of 1.2.

Cipher Suites

The following cipher suites are added by default and can be removed / re-added.

  1. ECDHE-ECDSA-AES256-GCM-SHA384
  2. ECDHE-ECDSA-CHACHA20-POLY1305
  3. ECDHE-ECDSA-AES128-GCM-SHA256
  4. ECDHE-RSA-AES256-GCM-SHA384
  5. ECDHE-RSA-CHACHA20-POLY1305
  6. ECDHE-RSA-AES128-GCM-SHA256
  7. AES256-GCM-SHA384
  8. AES128-GCM-SHA256

Additional ciphers which can be added

  1. DES-CBC3-SHA
  2. ECDHE-RSA-AES128-SHA
  3. ECDHE-RSA-AES256-SHA
  4. AES128-SHA
  5. AES256-SHA

If you need additional cipher suites, please email support@controlplane.com or reach out to us with you normal support channel.

Client Certificate Forwarding

Client certificates included in a request to a Domain can be configured to be forwarded to the destination Workload.

The x-forwarded-client-cert (XFCC) HTTP header will contain the client certificate details.

The certificate authority PEM, stored as a TLS Secret, can be associated with the Domain and used to verify the authority of the client certificate.

The only verification performed checks that the CN of the PEM matches the Domain (i.e., CN=*.DOMAIN).

CRL lists are not verified / checked, but they can be checked by the Workload by keeping a list of allowed or revoked client certificate hashes. When a request is received by the Workload, the hash field in the XFCC can be checked against the allowed or revoked list and an allow / deny decision can be made.

To generate the hash, execute the following command:

copy
openssl x509 -noout -fingerprint -sha256 -inform pem -in MyClientCert.pem | awk -F= '{print $2}' | tr -d ':' | tr '[:upper:]' '[:lower:]'`

NOTE: If a certificate authority PEM is not associated with a Domain, no verification is performed.

TIP

Verify that the CA certificate includes the correct x509 key usage fields (critical, digitalSignature, keyEncipherment) + extendedKeyUsage = serverAuth and that the CN of the client certificate matches the domain name selected.

Custom Server Certificate

Custom Server Certificates can be assigned to a Domain by selecting an exisiting TLS secret.

This certificate is used when configuring:

  1. An apex domain.
  2. A domain that is fronted by a proxy (such as CloudFlare).
  3. A domain not wanting to use a Control Plane generated certificate.
NOTE

When using the CNAME DNS mode and Subdomain Based Routing, a TLS secret must be assigned with the domain.

Permissions

The permissions below are used to define policies together with one or more of the four principal types:

PermissionDescriptionImplies
createCreate new domain
deleteDelete a domain
editModify existing domains (only tags can be changed)view, use
manageFull accesscreate, delete, edit, manage, use, view
useAllow a principal to use this domainview
viewRead-only access

Access Report

Displays the permissions granted to principals for the domain.

CLI

To view the CLI documentation for domains, click here

Copyright © 2023 Control Plane Corporation. All rights reserved. Revision f723392e
Contents