Domains - Control Plane

Overview

Workloads managed at Control Plane can be configured to serve requests using any domain name you own. Domains are scoped to an Org and are associated with one GVC. The domain can then be configured to handle requests for one or multiple Workloads within that GVC. Domains that are configured at Control Plane are automatically secured using TLS certificates, load balanced, and DNS geo-routed to the nearest healthy location assigned to the GVC.

Default Domain Names

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

Canonical endpoints (Global): cpln.app
Individual location endpoints: controlplane.us

Configure a Domain

Refer to the Configure a Domain guide for additional details.

Domain Verification

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). If you want to use subdomains configured in NS mode, you must create and verify the apex domain in the org. Even if the apex domain is not used for any workloads, it must be verified to allow these subdomains to be created. 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.

As a best practice, create the apex domain in the Org designated for your production environment.

Hostname Behavior

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.

Routing Modes

Control Plane provides two routing modes for directing requests to your domain:

Path Based Routing
Subdomain Based Routing

Path Based Routing

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:

You maintain full control of DNS for the domain.
CDN / WAF Compatible.

Example URL endpoints:

If the domain 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.
- https://sub.example.com/workload_one
- https://sub.example.com/workload_two

All path prefix values must be unique and there must be at least one path defined.

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 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.

This does not work for regex-based paths

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.

When combining the / path prefix with other path prefixes, the / path will automatically be placed last in the list because it matches ALL requests.

Port Selection

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.)

Regex Based Routing

Instead of specifying routes based on a path prefix, paths can be specified using regex. For example: A path regex can be specified as: /user/.*/profile to match routes like: /user/bob/profile or /user/mary/profile

If at least one regex path is found, routes will not be sorted.

Subdomain Based Routing

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:

Best choice when a unique DNS subdomain is required for each workload.
One-time configuration.
Works for all current and future workloads in a GVC.

Example URL endpoints:

If the domain 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:
- https://workload_one.sub.example.com
- https://workload_two.sub.example.com

APEX Domain Considerations

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:

GoDaddy
Route53

Port Configuration

Using the UI console, the port configuration section can be accessed when editing a domain and using Advanced Mode.

External Port

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.

Protocol

The following protocols are supported:

HTTP2
HTTP
TCP (when using a dedicated load balancer)

TLS Settings

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, with a maximum supported value of 1.3. All modern browsers support the default of 1.2.

Cipher Suites

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

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

Additional ciphers which can be added:

DES-CBC3-SHA
ECDHE-RSA-AES128-SHA
ECDHE-RSA-AES256-SHA
AES128-SHA
AES256-SHA

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 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). 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:

openssl 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.

Custom Server Certificate

A Custom Server Certificate can be assigned to a Domain by selecting an existing TLS secret. This certificate is used when configuring:

An apex domain that is configured with subdomain based routing.
A domain that is fronted by a proxy (such as CloudFlare).
A domain that prefers not to use a certificate generated by Control Plane.

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 Settings

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:

Allow Credentials
- Determines whether the client-side code (typically running in a web browser) is allowed to include credentials (such as cookies, HTTP authentication, or client-side SSL certificates) in cross-origin requests.
Max Age
- Maximum amount of time, in seconds, that a preflight request result can be cached by the client browser. (Default: 24 hours)
Allow Origins
- Determines which origins are allowed to access a particular resource on a server from a web browser.
  - Examples:
    - Wildcard Origin: *
    - Specific Origin: https://example.com
Allow Methods
- Specifies the HTTP methods (such as GET, POST, PUT, DELETE, etc.) that are allowed for a cross-origin request to a specific resource.
Allow Headers
- Specifies the custom HTTP headers that are allowed in a cross-origin request to a specific resource.
Expose Headers
- Specifies which response headers are exposed to the client-side code (typically running in a web browser) in a cross-origin request.

Dedicated Load Balancer Options

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.

NumTrustedProxies

This gives control over the number of trusted proxies that are configured in front of Control Plane. Changing it, controls the source ip address used for request logging, firewall settings and for the X-Envoy-External-Address header passed to workloads. If set to 1, then the last address in an existing X-Forwarded-For header will be used in place of the source client IP address. If set to 2, then the second to last address in an existing X-Forwarded-For header will be used in place of the source client IP address. When set to 2, any request where the XFF header does not have at least two addresses or does not exist then the source client IP address will be used instead.

Custom Ports

The following external ports may be configured instead of only 443 and 80.

1443
3000
3001
3002
3003
3004
5912
8443
8444
50051
50052

Please contact support on Slack or email support@controlplane.com if you need to use a port that is not listed here.

Configuration Options

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
Host Prefix

Accept All Hosts

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.

Host Prefix

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.

Replica Direct Routing

Domains can be configured, in conjunction with a stateful workload, for replica direct endpoints. These links will direct traffic directly to the specified replica of a workload.

Configuration

To configure a Domain for replica direct routing, you need to set the workloadLink property on the Domain to the link of the workload. The domain will also need to be configured as a cname domain with the dns01 cert challenge type. The domain needs at least one port with at least one route to work.

Example

spec:
  certChallengeType: dns01
  dnsMode: cname
  workloadLink: //gvc/my-gvc/workload/my-workload
  ports:
    - number: 443
      protocol: http2
      routes:
        - port: 8080
          prefix: /
          workloadLink: //gvc/my-gvc/workload/my-workload # must match the top level workloadLink

DNS names

When a Domain is configured for replica direct routing, the DNS names for each replica will be: <workload-name>-<replica>-<location>.<domain>

Example

my-workload-0-aws-us-west-2.example.com

DNS records

Replica direct domains require specific DNS records in order to work correctly.

One CNAME record to redirect the dns01 certificate challenge to Control Plane
Host TTL Type Value
_acme-challenge 300 CNAME _acme-challenge.cpln.app

Host	TTL	Type	Value
_acme-challenge	300	CNAME	_acme-challenge.cpln.app

A CNAME record for EACH replica of the workload to redirect traffic to Control Plane

Host	TTL	Type	Value
my-workload-0-aws-us-west-2	300	CNAME	my-workload-<gvcAlias>-0.aws-us-west-2.controlplane.us
my-workload-1-aws-us-west-2	300	CNAME	my-workload-<gvcAlias>-1.aws-us-west-2.controlplane.us
my-workload-2-aws-us-west-2	300	CNAME	my-workload-<gvcAlias>-2.aws-us-west-2.controlplane.us

Permissions

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

Access Report

Displays the permissions granted to principals for the domain.

CLI

To view the CLI documentation for domains, click here.

Domain Certificate Management

Control Plane automatically handles the creation and renewal of TLS certificates for Domains. This ensures that your Domains are always secured with up-to-date certificates without requiring manual intervention. The certificates issued are valid for 90 days and refresh every 60 days.

Certificate Creation and Renewal Process

Control Plane uses the Let’s Encrypt ACME protocol to automatically create and renew certificates for Domains. Any certificates issued by Let’s Encrypt are published to the Certificate Transparency logs and discoverable by the public. If you prefer to use a different certificate authority, you can configure a custom server certificate on the Domain.

NS Domains: Control Plane utilizes the Let’s Encrypt DNS-01 verification process. This involves creating a DNS TXT record at _acme-challenge.${domain} to prove Domain ownership, allowing Let’s Encrypt to issue a certificate. Control Plane manages the creation of the DNS record, and the certificate is issued by Let’s Encrypt. When the Domain is attached to a GVC to have a subdomain for each workload, the certificate includes a wildcard for the subdomain.
CNAME Domains: Control Plane uses the Let’s Encrypt HTTP-01 verification process. This involves serving a specific HTTP resource to prove Domain ownership at http://${domain}/.well-known/acme-challenge/, allowing Let’s Encrypt to issue a certificate. Control Plane configures the Domain with a redirect to our HTTP-01 solver, and then the certificate is issued by Let’s Encrypt. Wildcard certificates cannot be created using the HTTP-01 verification process, so CNAME Domains should not be attached to a GVC unless a custom server certificate is used.

If you choose to use a custom server certificate, ensure you monitor its expiration and renew it as necessary to avoid service disruptions.

Domain Configuration Errors

During the Domain configuration process, several errors might occur. These errors are viewable in the UI/API as a result of the Domain status being modified and are also available in Grafana as the domain_warning metric. A default alert is also created to notify the default contact when any Domain is in a warning state. Below are some common issues and their implications:

Common Errors

Certificate Renewal Blocked: The Domain’s certificate renewal is blocked. This can occur if the Domain is using a CNAME DNS mode and the renewal is blocked due to firewall or external CDN/WAF configurations. To test if the request from Let’s Encrypt is being blocked, you can use the following curl command:
```
curl -v https://${domain}/.well-known/acme-challenge/
```


If the request is blocked, you will see an error message in the response, the request will hang, or the `location:` in the response will NOT be targeted to `http01-solver.cpln.io`.

Example of an **invalid** redirect to HTTPS:

```bash
< HTTP/1.1 301 Moved Permanently
< location: https://${domain}/.well-known/acme-challenge/test
```

Example of a **valid** redirect to the Control Plane solver:

```bash
< HTTP/1.1 301 Moved Permanently
< location: http://http01-solver.cpln.io/.well-known/acme-challenge/test
```

As another test, you can run the following curl which includes the `-L` flag to follow the redirect:

```bash
curl -L https://${domain}/.well-known/acme-challenge/
```

The response should be an error message like the following, indicating that the request made it to our certificate solver:

```bash
{"message":"error downloading file: NoSuchKey: The specified key does not exist.\n\tstatus code: 404, request id: REDACTED, host id: REDACTED"}
```

Any other response indicates that the request was blocked.

- **Domain Used by GVC**: This Domain is currently in use by a GVC using the legacy configuration of the GVC `spec.domain` property.
  The Domain configuration will be ignored until no GVC is using it.
  This results in a `usedByGvc` status with a warning message indicating the Domain's current usage.

- **Invalid GVC**: At least one of the configured routes does not map to a valid GVC.
  Check the routes and verify that the GVC and workloads targeted by the Domain or routes exist.

- **No Valid Routes Configured**: No valid routes are configured for the Domain.
  Routes need to be added or updated for the Domain to be usable.

- **Disallowed Port or Protocol**: A port other than 443 or 80 is used, or the protocol is set to TCP and the GVC assigned is not configured with a [dedicated load balancer](#dedicated-load-balancer-options).
  If you need to use a port other than 443 or 80, you can enable [dedicated load balancer](#dedicated-load-balancer-options) on the GVC.

- **Invalid Workload**: A route is not mapped to a valid workload and will not be included in the configuration.
  This requires updating the route to map to a valid workload or removing the route that is no longer needed.

- **HostPrefix Ignored**: If the GVC does not have [dedicated load balancer](#dedicated-load-balancer-options) enabled and the Domain is not configured for wildcard support, any hostPrefix for a route is ignored.

### Logging and Monitoring

Errors and warnings are displayed in the status of the Domain objects and are displayed in the UI.
A Grafana metric of `domain_warning` is updated for each Domain.
An alarm is configured to notify the default contact using this metric when any Domain is in a warning state.

Quickstart

Concepts

Guides

External Logging

Kubernetes (Managed)

Bring your Own Kubernetes (BYOK)

Terraform Provider

Pulumi Provider

Kubernetes Operator

Reference

​Overview

​Default Domain Names

​Configure a Domain

​Domain Verification

​Hostname Behavior

​Routing Modes

​Path Based Routing

​Path Prefix Replacement

​Root Path Prefix

​Path Order

​Port Selection

​Regex Based Routing

​Subdomain Based Routing

​APEX Domain Considerations

​Port Configuration

​External Port

​Protocol

​TLS Settings

​Cipher Suites

​Client Certificate Forwarding

​Custom Server Certificate

​CORS Settings

​Dedicated Load Balancer Options

​NumTrustedProxies

​Custom Ports

​Configuration Options

​Accept All Hosts

​Host Prefix

​Replica Direct Routing

​Configuration

​Example

​DNS names

​Example

​DNS records

​Permissions

​Access Report

​CLI

​Domain Certificate Management

​Certificate Creation and Renewal Process

​Domain Configuration Errors

​Common Errors

Overview

Default Domain Names

Configure a Domain

Domain Verification

Hostname Behavior

Routing Modes

Path Based Routing

Path Prefix Replacement

Root Path Prefix

Path Order

Port Selection

Regex Based Routing

Subdomain Based Routing

APEX Domain Considerations

Port Configuration

External Port

Protocol

TLS Settings

Cipher Suites

Client Certificate Forwarding

Custom Server Certificate

CORS Settings

Dedicated Load Balancer Options

NumTrustedProxies

Custom Ports

Configuration Options

Accept All Hosts

Host Prefix

Replica Direct Routing

Configuration

Example

DNS names

Example

DNS records

Permissions

Access Report

CLI

Domain Certificate Management

Certificate Creation and Renewal Process

Domain Configuration Errors

Common Errors