6. Configure a custom domain

Overview

This part is optional. Your application is already accessible at its cpln.app endpoint. Follow these steps to connect a domain you own.

Since part 2 your application has answered on a generated cpln.app endpoint. This part puts it behind a name you own. example.com is a placeholder, so wherever it appears on this page, in a form, a file, or a command, use a domain you own. The domain is what makes the deployment production-facing. Users reach your name, and Control Plane issues and renews the certificate for it once a DNS record proves the domain is yours. What you’ll build:

Your domain (example.com) verified with Control Plane and routed to the frontend workload, with a TLS certificate issued and renewed for you and the same geo-routed load balancing your application already has.
The DNS records at your provider that make it resolve.

A TXT record at _cpln.example.com verifies domain ownership, and a CNAME record points example.com at abc123xyz.cpln.app. The domain routes to the frontend workload, with a certificate Control Plane manages.

Prerequisites

A domain name you own, at a DNS provider that accepts a CNAME (or ALIAS) record on the domain itself.
Completed 2. Deploy your own application with the frontend workload running. That is all this part needs, so you can come here straight after part 2 or after finishing the series at 5. Observe your workload.

If your DNS provider does not accept a CNAME record on the domain itself, route a subdomain instead: use app.example.com wherever this part says example.com, and the CNAME host becomes app instead of @.

Console
CLI
Terraform
Pulumi
AI Agent

Step 1: Describe the domain

Open the domain form

Click Domains in the left menu, then click New.

Name the domain and pick the workload

Enter your domain as the Domain (this quickstart uses example.com), then select the frontend workload from the quickstart-gvc GVC.

Read the records the domain needs

Click Create, or click anywhere outside the workload field. The form checks the domain before creating anything and lists what it needs. Under Ownership Config is a TXT record whose value is your org’s name; it proves you own the domain. Under DNS Config is the CNAME record that points the domain at your GVC, with your GVC’s alias already filled in. Export Zone File downloads both.

Step 2: Add the DNS records

Add both records at your DNS provider and wait for them to propagate.

Step 3: Create the domain

Click Create again. If the TXT record has not propagated yet, the Console refuses with You need to prove ownership of the domain example.com by setting one of the following TXT records; wait and try again. Once created, Control Plane issues the domain’s TLS certificate as soon as the CNAME resolves and the workload is ready.

Create the domain in your production org as a best practice.

Step 1: Write the domain configuration

Create domain.yaml:

kind: domain
name: example.com
spec:
  dnsMode: cname
  ports:
    - number: 443
      protocol: http2
      routes:
        - prefix: /
          workloadLink: //gvc/quickstart-gvc/workload/frontend

Step 2: Read the records the domain needs

Apply the configuration:

cpln apply -f domain.yaml

The command fails with You need to prove ownership of the domain example.com by setting one of the following TXT records and lists everything the domain needs: two TXT records at _cpln.example.com, either of which proves ownership, and a CNAME record:

type: CNAME
host: "@"
value: <gvcAlias>.cpln.app
ttl: 300

<gvcAlias> stands for your GVC’s alias. Read it from the GVC:

cpln gvc get quickstart-gvc -o yaml

alias: abc123xyz

Step 3: Add the DNS records

At your DNS provider, add one of the TXT records from the error and the CNAME record, with your alias in place of abc123xyz:

Type	Host	Value	TTL
CNAME	@	`abc123xyz.cpln.app`	300

Step 4: Create the domain

After the records propagate, apply the configuration again:

cpln apply -f domain.yaml

The domain is created, and Control Plane issues its TLS certificate once the workload is ready.

Step 1: Define the domain and its route

Add the following to your main.tf:

resource "cpln_domain" "site" {
  name        = "example.com"
  description = "The application's domain"

  spec {
    dns_mode = "cname"

    ports {
      number   = 443
      protocol = "http2"

      tls {}
    }
  }
}

resource "cpln_domain_route" "site" {
  depends_on = [cpln_domain.site]

  domain_link   = cpln_domain.site.self_link
  domain_port   = 443
  prefix        = "/"
  workload_link = cpln_workload.frontend.self_link
}

output "domain_endpoint" {
  value = "https://example.com"
}

output "dns_cname_record" {
  value = "Type: CNAME | Host: @ | Value: ${cpln_gvc.quickstart.alias}.cpln.app | TTL: 300"
}

Step 2: Read the records the domain needs

terraform apply

The apply fails until you prove ownership: the error lists two TXT records at _cpln.example.com, either of which works.

Step 3: Add the DNS records

At your DNS provider, add one of the TXT records and the CNAME record from the dns_cname_record output, whose value has the form <gvcAlias>.cpln.app.

Step 4: Create the domain

After the records propagate, apply again:

terraform apply

The Terraform Registry documentation lists every domain option.

Step 1: Define the domain and its route

TypeScript
Python
Go
C#

Add to your index.ts:

// The application's domain
const siteDomain = new cpln.Domain("site-domain", {
  name: "example.com",
  description: "The application's domain",
  spec: {
    dnsMode: "cname",
    ports: [
      {
        number: 443,
        protocol: "http2",
        tls: {},
      },
    ],
  },
});

// Route it to the application
const siteRoute = new cpln.DomainRoute("site-route", {
  domainLink: siteDomain.selfLink,
  domainPort: 443,
  prefix: "/",
  workloadLink: frontend.selfLink,
}, { dependsOn: [siteDomain] });

export const domain_endpoint = "https://example.com";
export const dns_cname_record = gvc.alias.apply(
  alias => `Type: CNAME | Host: @ | Value: ${alias}.cpln.app | TTL: 300`
);

Add to your __main__.py:

# The application's domain
site_domain = cpln.Domain("site-domain",
    name="example.com",
    description="The application's domain",
    spec=cpln.DomainSpecArgs(
        dns_mode="cname",
        ports=[cpln.DomainSpecPortArgs(
            number=443,
            protocol="http2",
            tls=cpln.DomainSpecPortTlsArgs(),
        )],
    ))

# Route it to the application
site_route = cpln.DomainRoute("site-route",
    domain_link=site_domain.self_link,
    domain_port=443,
    prefix="/",
    workload_link=frontend.self_link,
    opts=pulumi.ResourceOptions(depends_on=[site_domain]))

pulumi.export("domain_endpoint", "https://example.com")
pulumi.export("dns_cname_record", gvc.alias.apply(
    lambda alias: f"Type: CNAME | Host: @ | Value: {alias}.cpln.app | TTL: 300"
))

Add fmt to your imports, which the dns_cname_record output below uses, then add to your main.go:

// The application's domain
siteDomain, err := cpln.NewDomain(ctx, "site-domain", &cpln.DomainArgs{
	Name:        pulumi.String("example.com"),
	Description: pulumi.String("The application's domain"),
	Spec: &cpln.DomainSpecArgs{
		DnsMode: pulumi.String("cname"),
		Ports: cpln.DomainSpecPortArray{
			&cpln.DomainSpecPortArgs{
				Number:   pulumi.Int(443),
				Protocol: pulumi.String("http2"),
				Tls:      &cpln.DomainSpecPortTlsArgs{},
			},
		},
	},
})
if err != nil {
	return err
}

// Route it to the application
_, err = cpln.NewDomainRoute(ctx, "site-route", &cpln.DomainRouteArgs{
	DomainLink:   siteDomain.SelfLink,
	DomainPort:   pulumi.Int(443),
	Prefix:       pulumi.String("/"),
	WorkloadLink: frontend.SelfLink,
}, pulumi.DependsOn([]pulumi.Resource{siteDomain}))
if err != nil {
	return err
}

ctx.Export("domain_endpoint", pulumi.String("https://example.com"))
ctx.Export("dns_cname_record", gvc.Alias.ApplyT(func(alias string) string {
	return fmt.Sprintf("Type: CNAME | Host: @ | Value: %s.cpln.app | TTL: 300", alias)
}).(pulumi.StringOutput))

Add to your Program.cs:

// The application's domain
var siteDomain = new Domain("site-domain", new DomainArgs
{
    Name = "example.com",
    Description = "The application's domain",
    Spec = new DomainSpecArgs
    {
        DnsMode = "cname",
        Ports = new[]
        {
            new DomainSpecPortArgs
            {
                Number = 443,
                Protocol = "http2",
                Tls = new DomainSpecPortTlsArgs {}
            }
        }
    }
});

// Route it to the application
var siteRoute = new DomainRoute("site-route", new DomainRouteArgs
{
    DomainLink = siteDomain.SelfLink,
    DomainPort = 443,
    Prefix = "/",
    WorkloadLink = frontend.SelfLink
}, new CustomResourceOptions { DependsOn = { siteDomain } });

Update your return dictionary to include the new outputs:

return new Dictionary<string, object?>
{
    ["canonical_endpoint"] = web.Statuses.Apply(s => s[0].CanonicalEndpoint),
    ["frontend_endpoint"] = frontend.Statuses.Apply(s => s[0].CanonicalEndpoint),
    ["domain_endpoint"] = "https://example.com",
    ["dns_cname_record"] = gvc.Alias.Apply(alias =>
        $"Type: CNAME | Host: @ | Value: {alias}.cpln.app | TTL: 300")
};

Step 2: Read the records the domain needs

pulumi up

The deployment fails until you prove ownership: the error lists two TXT records at _cpln.example.com, either of which works.

Step 3: Add the DNS records

At your DNS provider, add one of the TXT records and the CNAME record from the dns_cname_record output, whose value has the form <gvcAlias>.cpln.app.

Step 4: Create the domain

After the records propagate, deploy again:

pulumi up

The Pulumi Registry documentation lists every domain option.

Step 1: Describe the domain

The first prompt names your org and the domain, so it works in a new conversation too. Replace my-org with your org name and example.com with your domain, here and in every prompt that follows:

Using org "my-org", put the domain "example.com" in front of
the frontend workload in GVC "quickstart-gvc", using a CNAME
record at my DNS provider.

The agent submits the domain, and Control Plane refuses it until a DNS record proves the domain is yours.

Step 2: Read the records the domain needs

The refusal lists what the domain needs, and the agent passes it on: a TXT record at _cpln.example.com with your org’s name or its ID as the value, either of which proves ownership, and a CNAME record for the domain itself. The CNAME value has the form <gvcAlias>.cpln.app, and the agent reads your GVC’s alias to fill it in. If the value it gives you still shows <gvcAlias>, ask for your GVC’s alias.

Step 3: Add the DNS records

Add the TXT record and the CNAME record at your DNS provider and wait for them to propagate. If the agent offered two TXT records, one is enough.

Step 4: Create the domain

The DNS records are in place. Create the domain again.

The agent submits the same domain again. If the TXT record has not propagated yet, Control Plane refuses once more. Wait and try again. Once created, Control Plane issues the domain’s TLS certificate as soon as the CNAME resolves and the workload is ready. Ask for the status while you wait:

What is the status of the domain now?

The agent reads the domain back and reports pendingCertificate until the certificate is issued, then ready.

Verify

Once the certificate is issued, open the domain in your browser. Your application loads over HTTPS with a valid TLS certificate, and its footer still names the location that served the request.

Your application is served on your own domain with an automatic TLS certificate and geo-routed load balancing.

Routing modes

Control Plane supports two routing modes:

Mode	DNS record	Best for
Path-based	CNAME	Multiple workloads on different paths (`/api`, `/web`)
Subdomain-based	NS	A unique subdomain per workload (`api.example.com`)

Path-based routing examples

Route different paths to different workloads:

https://example.com/api routes to the API workload.
https://example.com/web routes to the frontend workload.
https://example.com/ routes to the default workload.

Subdomain-based routing examples

Each workload receives its own subdomain automatically:

https://api.example.com routes to the API workload.
https://web.example.com routes to the frontend workload.

Requires NS record delegation to Control Plane.

What you’ve learned

Ownership before certificates: Control Plane issues a certificate for a name only after a TXT record proves you control it, and refuses the domain until that record resolves.
The CNAME carries everything: pointing the domain at the GVC’s alias brings the TLS termination, the certificate renewal, and the geo-routing the generated endpoint had.
One domain, many workloads: a domain splits across workloads by path or by subdomain.

Next steps

3. Service-to-service communication

If you came here straight after part 2, this is where the series continues: the API, kept off the internet, reached by the frontend through the mesh.

Domain reference

Every domain option: NS mode, subdomain routing, your own certificate, CORS, and the ports a domain can expose.

Clean up

To remove everything the series has created. If you came here before finishing parts 3, 4, and 5, skip the policy, the release, the quickstart-db GVC, the secret, and the api image, since they do not exist yet:

Console
CLI
Terraform
Pulumi
AI Agent

Delete the domain

Open Domains, select your domain, click Actions, then Delete, and confirm.

Delete the policy

Open Policies, select api-db-policy, click Actions, then Delete, and confirm.

Uninstall the database release

Under Templates, click Releases, open db, click Actions, then Uninstall, and confirm.

Delete the database GVC

Open quickstart-db, click Actions, then Delete, type the GVC name to confirm, and click Delete.

Delete the application GVC

Open quickstart-gvc, click Actions, then Delete, type the GVC name to confirm, and click Delete. web, frontend, api, api-identity, and the tracing setting go with it.

Delete the secret

Open Secrets, select db-credentials, click Actions, then Delete, and confirm.

Delete the images

Open Images, select frontend, and click Actions, then Delete to remove all its tags. Repeat for api.

cpln domain delete example.com
cpln policy delete api-db-policy
cpln helm uninstall db
cpln gvc delete quickstart-db
cpln gvc delete quickstart-gvc
cpln secret delete db-credentials
cpln image delete frontend:1.0
cpln image delete frontend:1.1
cpln image delete api:1.0

Replace example.com with your domain.

terraform destroy

The images were built by the CLI, so delete them with it: cpln image delete frontend:1.0, cpln image delete frontend:1.1, and cpln image delete api:1.0.

pulumi destroy

The images were built by the CLI, so delete them with it: cpln image delete frontend:1.0, cpln image delete frontend:1.1, and cpln image delete api:1.0.

Delete the domain "example.com" and the policy "api-db-policy",
uninstall the release "db", then delete the GVCs "quickstart-db"
and "quickstart-gvc" and the images frontend:1.0, frontend:1.1,
and api:1.0.

Replace example.com with your domain. The agent lists what goes, including the release’s volume set and the data on it and the tracing setting with its GVC, and asks you to confirm. The agent cannot delete a secret, so remove that yourself:

cpln secret delete db-credentials

Uninstalling the release removes its volume set and the data on it. Remove the DNS records from your DNS provider after deleting the domain. A --remote build also pushes the build cache images frontend-cache:latest and api-cache:latest; delete those too if you built without Docker.

Getting Started

Quickstart

Concepts

Core

Reference

6. Configure a custom domain

Overview

Prerequisites

Step 1: Describe the domain

Step 2: Add the DNS records

Step 3: Create the domain

Step 1: Write the domain configuration

Step 2: Read the records the domain needs

Step 3: Add the DNS records

Step 4: Create the domain

Step 1: Define the domain and its route

Step 2: Read the records the domain needs

Step 3: Add the DNS records

Step 4: Create the domain

Step 1: Define the domain and its route

Step 2: Read the records the domain needs

Step 3: Add the DNS records

Step 4: Create the domain

Step 1: Describe the domain

Step 2: Read the records the domain needs

Step 3: Add the DNS records

Step 4: Create the domain

Verify

Routing modes

What you’ve learned

Next steps

3. Service-to-service communication

Domain reference

Clean up

​Overview

​Prerequisites

​Step 1: Describe the domain

​Step 2: Add the DNS records

​Step 3: Create the domain

​Step 1: Write the domain configuration

​Step 2: Read the records the domain needs

​Step 3: Add the DNS records

​Step 4: Create the domain

​Step 1: Define the domain and its route

​Step 2: Read the records the domain needs

​Step 3: Add the DNS records

​Step 4: Create the domain

​Step 1: Define the domain and its route

​Step 2: Read the records the domain needs

​Step 3: Add the DNS records

​Step 4: Create the domain

​Step 1: Describe the domain

​Step 2: Read the records the domain needs

​Step 3: Add the DNS records

​Step 4: Create the domain

​Verify

​Routing modes

​What you’ve learned

​Next steps

3. Service-to-service communication

Domain reference

​Clean up

Overview

Prerequisites

Step 1: Describe the domain

Step 2: Add the DNS records

Step 3: Create the domain

Step 1: Write the domain configuration

Step 2: Read the records the domain needs

Step 3: Add the DNS records

Step 4: Create the domain

Step 1: Define the domain and its route

Step 2: Read the records the domain needs

Step 3: Add the DNS records

Step 4: Create the domain

Step 1: Define the domain and its route

Step 2: Read the records the domain needs

Step 3: Add the DNS records

Step 4: Create the domain

Step 1: Describe the domain

Step 2: Read the records the domain needs

Step 3: Add the DNS records

Step 4: Create the domain

Verify

Routing modes

What you’ve learned

Next steps

Clean up