> ## Documentation Index > Fetch the complete documentation index at: https://docs.controlplane.com/llms.txt > Use this file to discover all available pages before exploring further. # Domain > Domain configuration for workloads with TLS certificates, geo-routing, path-based routing, and DNS verification modes (CNAME and NS delegation). ## Domain Overview [Workloads](/concepts/workload) managed at Control Plane can be configured to serve requests using any domain name you own. Domains are scoped to an [org](/reference/org) and are associated with **one** [GVC](/reference/gvc). The domain can then be configured to handle requests for one or multiple [Workloads](/concepts/workload) within that [GVC](/reference/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](/reference/location) assigned to the [GVC](/reference/gvc). Geo-routing behavior can be customized per location using [location routing options](/reference/gvc#location-routing-options) to configure priority-based failover and latency adjustments. ### Domain Name Validation Domain names must be valid domain names with TLDs allowed. The domain name validation follows standard DNS domain name rules. ## Default Domain Names If a Domain is not mapped to a [GVC](/reference/gvc), the default domain names provided to [Workloads](/concepts/workload) are: * Canonical endpoints (Global): `cpln.app` * Individual location endpoints: `controlplane.us` ## Configure a Domain Refer to the [Configure a Domain](/guides/configure-domain) guide for additional details. ## Domain Configuration Example Here's a comprehensive example of a domain configuration: ```yaml theme={null} kind: domain name: my-domain spec: dnsMode: cname # or "ns" certChallengeType: http01 # or "dns01" gvcLink: //gvc/my-gvc ports: - number: 443 protocol: http2 tls: minProtocolVersion: TLSV1_2 cipherSuites: - ECDHE-ECDSA-AES256-GCM-SHA384 - ECDHE-RSA-AES256-GCM-SHA384 clientCertificate: secretLink: //secret/client-ca-cert serverCertificate: secretLink: //secret/server-cert cors: allowCredentials: true maxAge: 24h allowOrigins: - exact: https://example.com - regex: "https://.*\\.example\\.com" allowMethods: - GET - POST - PUT - DELETE allowHeaders: - Authorization - Content-Type exposeHeaders: - X-Custom-Header routes: - prefix: /api/ replacePrefix: /v2/api/ port: 443 workloadLink: //gvc/my-gvc/workload/api-service headers: request: set: X-Custom-Header: "value" X-Client-IP: "%DOWNSTREAM_REMOTE_ADDRESS_WITHOUT_PORT%" - prefix: /web port: 3000 workloadLink: //gvc/my-gvc/workload/web-service - prefix: / port: 8080 workloadLink: //gvc/my-gvc/workload/default-service mirror: - workloadLink: //gvc/my-gvc/workload/mirror-service percent: 50 ``` ## 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](/reference/org) 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 verification TXT record can be named `_cpln.` or `_verify.` and must have the value of the org name or org id. When creating domains with the CLI, the operation fails if the required TXT and CNAME records are missing from your DNS. The error message prints the exact records that must be added; update your DNS with those values and rerun the command. As a best practice, create the apex domain in the org designated for your production environment. ## Hostname Behavior The `Host` header that will be sent in the request to the target workload will depend 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 `Host` header will be the canonical endpoint of the workload. For **standard** or **stateful** workloads, the `Host` header will be the name of domain used for the request. Whenever the `Host` header is manipulated, the `X-Forwarded-Host` header will be appended with the original `Host` from the request. ## Routing Modes Control Plane provides two routing modes for directing requests to your domain: 1. [Path Based Routing](#path-based-routing) 2. [Subdomain 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 and configuring the domain with `dnsMode: cname`. 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_one)** * **[https://sub.example.com/workload\_two](https://sub.example.com/workload_two)** All path prefix values must be unique and there must be at least one path defined. Routes are automatically sorted by prefix length (longest first), then by host prefix length, then by trailing slash preference. #### Path Prefix Replacement The `replacePrefix` property allows a path prefix to be replaced when forwarding the request to the [Workload](/concepts/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](/concepts/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 The `port` property allows each route to specify a port that 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 in the container's port list (in declaration order). #### Replica Selection The `replica` property allows **stateful** workloads with replicaDirect enabled to specify a replica number to route traffic directly to a specific replica. The replica number must be an integer greater than or equal to 0. If no replica is specified, traffic will be routed to all replicas of the workload. #### Header Operations The `headers` property allows routes to be configured to manipulate HTTP headers for all requests to that route. Header operations allow you to set or override headers before forwarding requests to the workload. **Supported Operations:** * **`set`**: Sets or overrides headers to all HTTP requests for this route **Header Value Wildcards:** Header values support the following wildcards: * `%REQUESTED_SERVER_NAME%`: The server name requested by the client * `%DOWNSTREAM_REMOTE_ADDRESS_WITHOUT_PORT%`: The client IP address without port * `%START_TIME%`: The request start time **Example:** ```yaml theme={null} headers: request: set: X-Custom-Header: "value" X-Client-IP: "%DOWNSTREAM_REMOTE_ADDRESS_WITHOUT_PORT%" X-Server-Name: "%REQUESTED_SERVER_NAME%" ``` When a domain is serving path based requests, the [domain port protocol](#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.) #### Mirror Routing The `mirror` property allows a route to be configured to mirror requests to another workload. **For example:** A request to the URL `https://sub.example.com/` can be mirrored to the workload `api-service-v2` 50% of the time. This can be useful for testing new versions of a workload before promoting it to the main workload. An optional `port` property can be added to the mirror configuration to specify which port the mirrored request should be sent to on the target workload. If not specified, it will default to first listed port on the target workload. **Example:** ```yaml theme={null} routes: - prefix: /api workloadLink: //gvc/my-gvc/workload/api-service mirror: - workloadLink: //gvc/my-gvc/workload/api-service-v2 percent: 50 - workloadLink: //gvc/my-gvc/workload/api-service-v3 percent: 25 port: 8081 ``` The mirrored workload must be in the same gvc as the main workload. If you need to mirror to a workload in a different gvc, please contact support ### Regex Based Routing Instead of specifying routes based on a path prefix, paths can be specified using [regex](https://github.com/google/re2/wiki/Syntax). **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. You must specify either a prefix OR regex for each route, but not both. ### Subdomain Based Routing Subdomain based routing allows a domain to be mapped to all workloads in a [GVC](/reference/gvc). This is accomplished by adding **NS** records to DNS which delegate DNS to Control Plane for this domain **only** and configuring the domain with `dnsMode: ns`. 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_one.sub.example.com)** * **[https://workload\_two.sub.example.com](https://workload_two.sub.example.com)** ## DNS Modes Control Plane supports two DNS modes for domain configuration: ### CNAME Mode (`dnsMode: cname`) In CNAME mode, Control Plane will configure workloads to accept traffic for the domain but will not manage DNS records for the domain. End users configure CNAME records in their own DNS pointed to the canonical workload endpoint. **Certificate Challenge Types:** * `certChallengeType: http01`: Uses HTTP-01 challenge for certificate validation * `certChallengeType: dns01`: Uses DNS-01 challenge for certificate validation When using CNAME mode with subdomain based routing (`gvcLink`), a custom server certificate must be configured for all ports that enable TLS. **Constraints:** * A CNAME domain cannot be created as a subdomain of a domain that is already configured in NS mode. ### NS Mode (`dnsMode: ns`) In NS mode, Control Plane will manage the subdomains and create all necessary DNS records. End users configure an NS record to forward DNS requests to the Control Plane managed DNS servers. HTTP-01 challenge type is not supported for NS mode domains. ## Certificate Challenge Type The `certChallengeType` property controls both the certificate validation method and whether a wildcard certificate is generated: * **`dns01`**: Uses DNS-01 challenge and generates a wildcard certificate * **`http01`**: Uses HTTP-01 challenge and generates a standard certificate for just the domain name (not supported for NS mode) * **unset**: Defaults to wildcard certificate for NS domains, standard certificate for CNAME domains ## APEX Domain Considerations * An apex domain (e.g., **example.com**) can serve requests to workloads using either [path based](#path-based-routing) or [subdomain based](#subdomain-based-routing) routing. * If subdomain based routing is desired, a [Custom Server Certificate](#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](https://docs.aws.amazon.com/cloudfront/index.html) or [Cloudflare](https://cloudflare.com) must be used to proxy the apex domain to Control Plane. * Apex domains can only use CNAME mode (`dnsMode: cname`). 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 The `number` property specifies the external port number. Typically, TLS requests to a configured domain are served on the standard TLS port 443. **Default Configuration:** * Port number: `443` (default) * Protocol: `http2` (default) Refer to the [dedicated load balancer](#dedicated-load-balancer-options) section on which external ports can be used if dedicated load balancing is enabled. ### Protocol The `protocol` property specifies the protocol used for the port. The following protocols are supported: 1. **`http2`** (default) 2. **`http`** 3. **`tcp`** (when using a [dedicated load balancer](#dedicated-load-balancer-options)) ### TLS Settings The default TLS protocol version is **`minProtocolVersion: TLSV1_2`**. The minimum TLS protocol version is **`TLSV1_0`**. The minimum version should be set as high as possible, with a maximum supported value of **`TLSV1_3`**. All modern browsers support the default of **`TLSV1_2`**. Supported TLS protocol versions: * **`TLSV1_3`** (TLS 1.3) * **`TLSV1_2`** (TLS 1.2) - Default * **`TLSV1_1`** (TLS 1.1) * **`TLSV1_0`** (TLS 1.0) #### Cipher Suites The `cipherSuites` property configures the allowed cipher suites for TLS connections. 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 contact support on Slack or email [support@controlplane.com](mailto: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](#dedicated-load-balancer-options)). #### Client Certificate Forwarding The `clientCertificate` property configures client certificate forwarding for TLS connections. Client certificates included in a request to a Domain can be configured to be forwarded to the destination [Workload](/concepts/workload). The `x-forwarded-client-cert` (XFCC) HTTP header will contain the client certificate details. The certificate authority PEM, stored as a [Secret](/reference/secret) of type `keypair`, can be associated with the Domain via the `secretLink` property and used to verify the authority of the client certificate. The secret must contain a client certificate authority cert in PEM format used to verify requests which include client certificates. The key subject must match the domain and the key usage properties must be configured for client certificate authorization. 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](/concepts/workload) by keeping a list of allowed or revoked client certificate hashes. When a request is received by the [Workload](/concepts/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: ```bash theme={null} 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 The `serverCertificate` property configures a custom server certificate for the domain. A Custom Server Certificate can be assigned to a Domain by selecting an existing [Secret](/reference/secret) of type `keypair` via the `secretLink` property. This certificate is used when configuring: 1. An apex domain that is configured with [subdomain based routing](#subdomain-based-routing). 2. A domain that is fronted by a proxy (such as CloudFlare). 3. A domain that prefers not to use a certificate generated by Control Plane. The secret must contain PEM encoded content and be of type `keypair`. When the port number is 443 and this is not supplied, a certificate is provisioned automatically. 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: * **`allowCredentials`** * 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. * **`maxAge`** * Maximum amount of time that a preflight request result can be cached by the client browser. Must match the regex pattern: `^[\d\.]+[wdhm]+$` (e.g., "24h", "1d", "3600s") * **`allowOrigins`** * Determines which origins are allowed to access a particular resource on a server from a web browser. * Each origin can be specified as either: * `exact`: A specific origin string (e.g., `https://example.com`) * `regex`: A regex pattern to match origins * Examples: * Wildcard Origin: `*` * Specific Origin: `https://example.com` * **`allowMethods`** * Specifies the HTTP methods (such as GET, POST, PUT, DELETE, etc.) that are allowed for a cross-origin request to a specific resource. * **`allowHeaders`** * Specifies the custom HTTP headers that are allowed in a cross-origin request to a specific resource. Header names are automatically converted to lowercase. * **`exposeHeaders`** * Specifies which response headers are exposed to the client-side code (typically running in a web browser) in a cross-origin request. Header names are automatically converted to lowercase. ## 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/gvc#dedicated-load-balancer) reference page for additional details. ### NumTrustedProxies The `numTrustedProxies` property 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 Any custom port number can be used with the exception of the following excluded ports: * 8012 * 8022 * 9090 * 9091 * 15000 * 15001 * 15006 * 15020 * 15021 * 15090 * 41000 Please contact support on Slack or email [support@controlplane.com](mailto:support@controlplane.com) if you need to use a port that is not listed here. ### Dedicated Load Balancer 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: 1. [`acceptAllHosts`](#acceptallhosts) 2. [`acceptAllSubdomains`](#acceptallsubdomains) 3. [`hostPrefix`](#hostprefix) 4. [`hostRegex`](#hostregex) #### acceptAllHosts The `acceptAllHosts` property 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. There should only ever be at most one Domain configured with this setting for a single GVC. If there are multiple, then requests will only route for one of the two Domains. #### acceptAllSubdomains The `acceptAllSubdomains` property configures the domain to allow all traffic to `*.${Domain}` for the domain. No other Domains in the same GVC should be configured for any subdomains of this Domain since their routing rules will be ignored. #### hostPrefix For domains using [Path Based Routing](#path-based-routing) the `hostPrefix` property will be enabled and can be used for each path when the domain has the `acceptAllHosts` or `acceptAllSubdomains` property enabled. This option allows forwarding traffic for different host header prefixes to specific workloads. The host prefix must match the regex pattern: `^[0-9a-zA-Z-\._]*$` You cannot use both `hostPrefix` and `hostRegex` on the same route. #### hostRegex For domains using [Path Based Routing](#path-based-routing) the `hostRegex` property will be enabled and can be used for each path when the domain has the `acceptAllHosts` or `acceptAllSubdomains` property enabled. This option allows forwarding traffic for different host headers to specific workloads by regular expression. You cannot use both `hostPrefix` and `hostRegex` on the same route. ## 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. Control Plane also provides built-in per-replica endpoints under `controlplane.us` when `spec.loadBalancer.replicaDirect` is enabled on the workload — no custom domain required. See [Replica-Direct Endpoints](/reference/workload/general#replica-direct-endpoints) in the workload reference. ### 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 exactly one route per port. **Validation Rules:** * When `workloadLink` is configured, `certChallengeType` cannot be `http01` * Every port must have exactly one route * All routes must reference the same workload as the domain's `workloadLink` * The domain cannot have both `gvcLink` and `workloadLink` configured #### Example ```yaml theme={null} kind: domain name: my-domain 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: `--.` #### Example `my-workload-0-aws-us-west-2.example.com` ## DNS records Replica direct domains require specific DNS records in order to work correctly. 1. One **CNAME** record to redirect the dns01 certificate challenge to Control Plane | Host | TTL | Type | Value | | :--------------- | :-- | :---- | :------------------------ | | \_acme-challenge | 300 | CNAME | \_acme-challenge.cpln.app | 2. 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-\-0.aws-us-west-2.controlplane.us | | my-workload-1-aws-us-west-2 | 300 | CNAME | my-workload-\-1.aws-us-west-2.controlplane.us | | my-workload-2-aws-us-west-2 | 300 | CNAME | my-workload-\-2.aws-us-west-2.controlplane.us | ## Permissions The permissions below are used to define [policies](/reference/policy) together with one or more of the four [principal types](/concepts/access-control): | 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. ## Domain Status The domain status field indicates the current state of the domain configuration and deployment. **Supported Status Values:** * `initializing`: Domain is being set up * `ready`: Domain is fully configured * `pendingDnsConfig`: Waiting for DNS configuration to be verified, this may happen if DNS is updated but has not yet propagated * `pendingCertificate`: Waiting for certificate provisioning * `usedByGvc`: Domain is being used by a GVC with legacy configuration * `warning`: Domain has configuration warnings * `errored`: Domain configuration has errors **Status Fields:** * `endpoints`: Array of endpoint URLs and their associated workload links * `warning`: Warning message describing any issues * `locations`: Array of location-specific certificate status information * `fingerprint`: Unique identifier for the domain configuration * `dnsConfig`: Array of DNS configuration records required for the domain ### DNS Configuration Records The `dnsConfig` field contains the DNS records that need to be configured for the domain to function properly. **DNS Record Structure:** * `type`: DNS record type (e.g., "CNAME", "NS", "TXT") * `ttl`: Time to live value (positive integer) * `host`: Hostname for the DNS record * `value`: DNS record value **Example DNS Configuration:** ```json theme={null} { "dnsConfig": [ { "type": "CNAME", "ttl": 300, "host": "sub.example.com", "value": "cpln.app" }, { "type": "TXT", "ttl": 300, "host": "_acme-challenge.sub.example.com", "value": "challenge-token-value" } ] } ``` ## Special Tags Control Plane supports special tags prefixed with `cpln/` that modify domain behavior. | Tag | Value | Description | | :------------------ | :----- | :------------------------------------------------------------------------------------------------------------------------------------ | | `cpln/skipDNSCheck` | `true` | Skip DNS validation checks during domain configuration. Useful when DNS propagation is delayed or when using external DNS management. | | `cpln/wildcard` | `true` | Enable wildcard certificate for custom ingress domains. Only applicable for domains with custom ingress enabled. | ## CLI To view the CLI documentation for domains, see the [Domain CLI reference](/cli-reference/commands/domain). ## 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](https://letsencrypt.org/docs/acme-protocol-updates/) protocol to automatically create and renew certificates for Domains. Any certificates issued by Let's Encrypt are published to the [Certificate Transparency](https://www.certificate-transparency.org/) logs and discoverable by the public. If you prefer to use a different certificate authority, you can configure a [custom server certificate](#custom-server-certificate) on the Domain. * **NS Domains**: Control Plane utilizes the Let's Encrypt [DNS-01](https://letsencrypt.org/docs/challenge-types/#dns-01-challenge) 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. See [Certificate Challenge Type](#certificate-challenge-type) for details on wildcard vs standard certificate behavior. * **CNAME Domains**: Control Plane uses the Let's Encrypt [HTTP-01](https://letsencrypt.org/docs/challenge-types/#http-01-challenge) 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 Validation Rules The following validation rules apply to domain configuration: ### Route Limits * Maximum of 150 routes per domain * Routes must be unique (no duplicate prefix/regex and host combinations) * All routes must reference workloads within the same GVC ### Port Configuration Limits * Maximum of 10 ports per domain * Each port can have a maximum of 150 routes ### DNS Mode Constraints * Apex domains can only use CNAME mode (`dnsMode: cname`) * NS mode requires DNS-01 certificate challenge type * CNAME mode with subdomain routing requires custom server certificate ### Workload Link Constraints * Cannot configure both `gvcLink` and `workloadLink` on the same domain * When `workloadLink` is configured: * Cannot use HTTP-01 certificate challenge type * Every port must have exactly one route * All routes must reference the same workload ### Wildcard Support Constraints * Cannot enable both `acceptAllHosts` and `acceptAllSubdomains` simultaneously * `hostPrefix` and `hostRegex` can only be used when `acceptAllHosts` or `acceptAllSubdomains` is enabled ## 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: ```bash theme={null} 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 theme={null} < 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 theme={null} < 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 theme={null} 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 theme={null} {"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.