Custom Domains

Tool availability: the default core profile covers the entire domain workflow — create_domain, update_domain, the route-edit trio (add_domain_route / update_domain_route / remove_domain_route), listener ports (add_domain_port / remove_domain_port), TLS (set_domain_tls / clear_domain_tls), and the generic list_resources / get_resource / delete_resource. Only CORS edits (set_domain_cors / clear_domain_cors) live in the full profile — if one is not advertised, reconnect with ?toolsets=full or use the cpln CLI fallback.

A domain is an org-level resource that binds a DNS name to workloads in one GVC. Created ≠ live: after the resource exists, the user still adds records at their DNS provider — read exactly which from status.dnsConfig and hand them over verbatim, never guessed. Every shape decision below is platform-enforced and a wrong combination is a rejected mutation, so decide BEFORE calling mcp__cpln__create_domain (the tool requires dnsMode and ports explicitly). Never set spec.domain on a GVC — that legacy field is deprecated; the Domain resource is the only path.

Decide the shape first

1. Apex or subdomain? The apex is the registrable root (example.com, example.co.uk); anything deeper is a subdomain (app.example.com).

2. `dnsMode` — who runs DNS:

dnsMode defaults to cname (to ns when gvcLink is set). The platform rejects ns on an apex, and rejects a cname domain nested under an existing NS domain (parent_ns_domain_exists).

3. Routing — exactly ONE of three. All routes in a domain must target workloads in the same GVC.

For an app, site, or API on serverless/standard, the answer is ports[].routes. Route-level workloadLink inside routes[] is a different field with no stateful restriction.

Ownership and create order

• `ns` subdomain: the apex domain resource must already exist in the org (apex_must_exist).
• Everything else: ownership is proven either by the org already owning the verified apex (subdomains then attach with no extra records), or by a TXT record — the create fails with must_prove_ownership listing the options: _cpln.{apex} / _verify.{apex}, or _cpln-{label}.{rest} / _verify-{label}.{rest} at any segment level, value = org GUID or org name (TTL 600). The user adds one, waits for propagation, and you retry the same create. mcp__cpln__create_domain surfaces these records in its error output.
• Apex owned by another org? The apex name itself is taken (globally unique), but subdomains still work: they go through the same TXT proof in this org — the standard multi-org pattern (keep the apex in the production org).
• `.internal` domains are strict same-org — apex and subdomains must live in one org (apex_owned_by_other_org, HTTP 409) — and: cname only, no gvcLink, certChallengeType forbidden; every TLS port needs tls.serverCertificate.secretLink (no ACME).

Manifest shape

kind: domain
name: app.example.com
spec:
  dnsMode: cname
  ports:                                # max 10 per domain
    - number: 443                       # default 443; 443 + http/http2 auto-gets a TLS block
      protocol: http2                   # http | http2 | tcp (tcp needs a dedicated load balancer)
      routes:                           # max 150 per port (200 with tag cpln/routeLimitOverride)
        - prefix: /api                  # prefix XOR regex (RE2); prefix defaults to "/"
          replacePrefix: /              # optional rewrite before forwarding
          workloadLink: //gvc/GVC/workload/API
          port: 8080                    # optional target container port
        - prefix: /
          workloadLink: //gvc/GVC/workload/FRONTEND

• Longest prefix wins — prefix routes are auto-sorted; regex routes are NOT sorted, written order matters. Duplicate prefix+host combinations are rejected (There are more than one routes for the prefix …).
• Listener ports other than 443/80 — and the `tcp` protocol — require a dedicated load balancer. Without one the domain deploys into warning (Unable to configure port …) instead of serving.
• Subdomain matching on one domain (hostPrefix / hostRegex, mutually exclusive) requires acceptAllHosts or acceptAllSubdomains (which exclude each other) AND a GVC with a dedicated load balancer. hostPrefix charset: alphanumeric, dot, underscore, hyphen.
• Header rewrites (headers.request.set): values may use only %REQUESTED_SERVER_NAME%, %DOWNSTREAM_REMOTE_ADDRESS_WITHOUT_PORT%, %START_TIME%.
• Traffic mirroring per route: mirror: [{workloadLink, percent 0-100, port}] — same GVC, response comes only from the primary.
• CORS per port: allowOrigins entries take exact XOR regex; header lists are lowercased; maxAge format is digits + h/m/s only.
• TLS per port: minProtocolVersion default TLSV1_2; custom cert = keypair secret (PEM) on serverCertificate.secretLink; clientCertificate enables mTLS verification — client cert details reach the workload in the XFCC header.

Certificates

• Let's Encrypt, auto-provisioned for port 443 once validation passes; ~90-day certs renewed automatically.
• cname defaults to http01: DNS must already resolve and /.well-known/acme-challenge/ must redirect to the platform solver (http01-solver.cpln.io) — a CDN/WAF forcing HTTPS or blocking the path breaks it; switch to dns01. ns always uses dns01. The tag cpln/skipDNSCheck: "true" skips the DNS-propagation gate in certificate processing.
• `dns01` on a `cname` domain adds an extra record: a _acme-challenge.{host} CNAME appears in status.dnsConfig — without it the certificate never issues.
• Wildcard certs come only from dns01 — that is why cname + gvcLink + http01 demands a custom certificate.

After create — DNS records and status

• Read the domain back and give the user the records from status.dnsConfig. CNAME mode points at the GVC endpoint alias. Via the MCP tools the alias is resolved for you, so the CNAME target comes back ready to paste (e.g. 0p2fpmbe7sr5c.t.cpln.app); via the cpln CLI the value is the literal <gvcAlias>.t.cpln.app placeholder — substitute the GVC's top-level alias field. Never hand the user a `<gvcAlias>` placeholder as a DNS record. cname + gvcLink needs one CNAME per workload; workloadLink adds per-replica records ({workload}-{i}-{location}).
• Many DNS providers refuse CNAME at the apex — the user needs ALIAS/ANAME support or a CDN in front.
• status.status: initializing, pendingDnsConfig (records not seen yet), pendingCertificate (validated, cert issuing), ready; warning/errored carry detail in status.warning; usedByGvc marks a domain referenced by the legacy GVC spec.domain. Pending states are expected, not errors. Misconfigurations that pass schema validation — routes to a missing GVC/workload, no valid routes, a disallowed port/protocol, an ignored hostPrefix — land as warning and increment the domain_warnings metric.
• Host header: serverless workloads receive the canonical endpoint as Host (the custom domain arrives in X-Forwarded-Host); standard/stateful receive the custom domain.
• Report honestly: "domain created, routes configured, DNS records pending at your provider" + the record list. Never claim the domain is serving before DNS exists.

Platform rejections and exact fixes

Verify

1. mcp__cpln__get_resource (kind domain) — status.status progressing, status.dnsConfig matches what the user added.
2. After the user adds records: dig TXT _cpln.DOMAIN / dig CNAME DOMAIN to confirm propagation before retrying or polling.
3. Once ready: curl -I https://DOMAIN/PATH and confirm each prefix lands on the intended workload.

Quick reference — MCP tools

CLI fallback (read the cpln skill first; CI/CD = CPLN_TOKEN + cpln apply): cpln domain create takes only --name/--description/--tag — spec changes go through cpln domain edit or cpln domain get -o yaml-slim + cpln apply. There is no cpln domain update.

Related skills

Documentation

• Domain Reference
• Configure a Domain Guide
• Custom Domain Quickstart
• cpln domain CLI