If a Domain is not mapped to a GVC, the default domain names provided to Workloads are:
cpln.app
controlplane.us
Refer to the Configure a Domain guide for additional details.
An apex domain, also known as a root domain, refers to a domain name that does not have any subdomain prefix (e.g., example.com).
Even if the apex domain isn't served at Control Plane, it needs to be created and configured for verification. This verification is done by adding a TXT record to DNS.
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 one of the Orgs, but subdomains in Orgs that don't have the apex domain will require a TXT record be added to DNS for verification.
The hostname (HOST
) environment variable that will be set on a running workload will be based on the type of Workload
and which domain was used for the request.
For serverless workloads, even if the request was served using a custom domain, the hostname will be the canonical name.
For standard or stateful workloads, the hostname will be set to the name of domain used for the request.
Control Plane provides two routing modes for directing requests to your domain:
Path based routing allows requests to a specific path prefix be routed to a specific workload. Multiple paths can be defined, but there must be at least one path.
This is accomplished by adding a CNAME record to DNS.
Advantages of using Path Based routing:
Example URL endpoints:
sub.example.com
is configured to point to the GVC that contains workload_one
and workload_two
. The path workload_one
can be
configured to route requests to workload_one
and the path workload_two
can be configured route requests to workload_two
.All path prefix values must be unique and there must be at least one path defined.
A path prefix can be configured to be replaced when forwarding the request to the Workload.
For example: A request to the URL https://sub.example.com/users/
can have the path prefix /users/
replaced with the path prefix /v2/users/
when forwarding the request internally to the target Workload.
The /
path will match any unmatched path prefixes for the subdomain.
The order of the path prefix list is adjustable. When a request to the Domain is received, the first match will be processed.
When combining the /
path prefix with other path prefixes, the /
path will automatically be placed last in the list because it matches ALL requests.
Each route can have a port assigned which will route requests to the respective port at the running workload.
For serverless workloads, assigning the port is optional since only one port can serve traffic.
For standard and stateful workloads that serve traffic on multiple ports, specific ports can be assigned on a route. If no port is assigned, external requests will be routed to the first port configured on the container.
When a domain is serving path based requests, the domain port protocol must be compatible with the selected protocol of the port configured on the container. (i.e., HTTP2 is compatible with HTTP2 and GRPC, HTTP is compatible with HTTP, etc.)
Subdomain based routing allows a domain to be mapped to all workloads in a GVC.
The is accomplished by adding NS records to DNS which delegate DNS to Control Plane for this domain only.
Advantages of using Subdomain routing:
Example URL endpoints:
sub.example.com
is configured to the GVC that contains workloads named workload_one
and workload_two
, Control Plane will create
the following subdomains and route requests to the respective workloads:An apex domain (e.g., example.com) can serve requests to Workloads using either path based or subdomain based routing.
If subdomain based routing is desired, a Custom Server Certificate must be configured.
If your DNS provider does not allow apex domains to point to a CNAME record, a service such as CloudFront or Cloudflare must be used to proxy the apex domain to Control Plane.
These DNS providers do not allow apex domains to have a CNAME record:
Using the UI console, the port configuration section can be accessed when editing a domain and using Advanced Mode
.
Typically, TLS requests to a configured domain are served on the standard TLS port 443.
Refer to the dedicated load balancer section on which external ports can be used if dedicated load balancing is enabled.
The following protocols are supported:
The default TLS protocol version is 1.2. The minimum TLS protocol version is 1.0.
The minimum version should be set as high as possible and all modern browsers support the default of 1.2.
The following cipher suites are added by default and can be removed / re-added:
Additional ciphers which can be added:
If you need additional cipher suites, please contact support on Slack or email support@controlplane.com.
If there is an attempt to disable the TLS settings on a domain, it will always revert to the default configuration unless the domain is using a non-standard port and a non-HTTP protocol (e.g., using TCP with a dedicated load balancer).
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).
If a certificate authority PEM is not associated with a Domain, no verification is performed.
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 header can be checked against the allowed or revoked list and an allow / deny decision can be made.
To generate the certificate hash, execute the following command:
copyopenssl x509 -noout -fingerprint -sha256 -inform pem -in MyClientCert.pem | awk -F= '{print $2}' | tr -d ':' | tr '[:upper:]' '[:lower:]'`
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.
A Custom Server Certificate can be assigned to a Domain by selecting an exisiting TLS secret.
This certificate is used when configuring:
If a custom server certificate is configured on a domain, it is the responsibility of the user to ensure that the certificate is valid and not expired.
CORS stands for Cross-Origin Resource Sharing. It is a mechanism that allows web browsers to securely make requests to a different domain or origin than the one from which the web page was served.
By default, web browsers enforce a policy called the Same-Origin Policy, which restricts JavaScript code running in a web page from making requests to a different domain. CORS provides a way to relax this policy and enable cross-origin requests, but in a controlled and secure manner.
When a web page makes a cross-origin request, the server needs to include specific CORS headers in its response to indicate which origins are allowed to access its resources. These headers include information such as the allowed methods, allowed headers, and whether credentials (such as cookies or HTTP authentication) can be included in the request.
CORS helps to prevent malicious scripts from performing unauthorized actions on behalf of a user, while still allowing legitimate cross-origin requests between trusted domains. It plays a crucial role in enabling modern web applications to interact with APIs and services hosted on different domains.
The following are CORS properties that are configurable on the domain. Depending on the application being served, these setting could be configured from the application.
The following CORS properties can be configured:
*
https://example.com
When a GVC has the dedicated load balancer option enabled, additional settings are available for any domains using it.
See the GVC dedicated load balancer reference page for additional details.
The following external ports may be configured instead of only 443
and 80
.
Please contact support on Slack or email support@controlplane.com if you need to use a port that is not listed here.
When a dedicated load balancer is enabled on a GVC, the domains that are configured to serve workloads within that GVC will have the following options that can be configured:
Accept All Hosts
configures the domain to allow all traffic (i.e. wildcard support) to the configured workloads, regardless of what the Host header or SNI is for the request.
For domains using Path Based Routing the Host Prefix
will be enabled and can be used for each path
when the domain has the Accept All Hosts
property enabled.
This option allows forwarding traffic for different host headers to specific workloads.
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.