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 by all Workloads within the GVC.
To deploy Workloads with different domains, they must be placed into separate GVCs.
If a Domain is not mapped to a GVC, the default domain names used by Workloads are:
cpln.app
controlplane.us
Refer to the Configure a Domain guide for additional details.
In order for DNS to work, the apex domain (e.g., example.com) needs to be created in Control Plane and verified before subdomains can be created.
Once the apex domain is verified, subdomains can be added to the same Org without needing the extra TXT record verification step.
If multiple Orgs are creating subdomains with the same apex domain, the apex domain verification only needs to be performed in one of the Orgs.
When initially adding a custom domain, the console will display the required DNS entries and, during creation, verify that the entries were created and can be resolved.
If the DNS entries need to be recreated, the DNS link will display the required DNS entries. Another verification will not be performed after the initial create.
Subdomain based routing allows a domain to be mapped to a GVC.
The associated Workload's global endpoint URL will follow the format:
https://WORKLOAD_NAME.SUB_DOMAIN.DOMAIN
The system offers the ability to have a Workload resolve to only the subdomain.
To accomplish this:
index
.https://SUB_DOMAIN.DOMAIN
./
path.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 the domain https://DOMAIN/foo
can be routed to Workload A, and
a request to the domain https://DOMAIN/bar
can be routed to Workload B.
NOTE: All path prefix values must be unique.
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/foo
can have the path prefix /foo
replaced with the path prefix /bar
when forwarding the request to the target Workload.
The /
path will resolve the specified Workload to the subdomain. This mimics the Workload named index
functionality when only using Subdomain Based Routing.
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.
TLS requests to a configured Domain are served on the standard TLS port 443.
This port will be configurable in the future.
The following protocols are suppored and can be configured on a Domain:
The minimum TLS protocol version is 1.2.
The minimum version will be configurable in the future.
The following cipher suites are added by default and can be removed / re-added.
To have additional cipher suites provisioned, please email support@controlplane.com.
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:
copyopenssl 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.
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 Certificates can be assigned to a Domain by selecting an exisiting TLS secret.
This certificate is used when configuring:
When using the CNAME
DNS mode, a TLS secret must be assigned with the domain.
The permissions below are used to define policies together with one or more of the four principal types:
Permission | Description | Implies |
---|---|---|
create | Create new domain | |
delete | Delete a domain | |
edit | Modify existing domains (only tags can be changed) | view, use |
manage | Full access | create, delete, edit, manage, use, view |
use | Allow a principal to use this domain | view |
view | Read-only access |
Displays the permissions granted to principals for the domain.
To view the CLI documentation for domains, click here