# Custom domains

> Attach a customer-owned domain to Apoxy's default Gateway with zero-downtime TLS provisioning.

A `DomainRecord` binds a hostname you own (e.g., `api.example.com`) to a Gateway, Proxy,
TunnelNode, VPCService, or EdgeFunction on Apoxy. Apoxy handles DNS delegation, ACME certificate
issuance, and renewal.

## How it works

For customer-owned hostnames, Apoxy uses a CNAME model. You keep authority over your zone;
Apoxy only needs you to point the hostname at a zone we control (`cname.apoxy.net`) so we can
serve traffic and issue certificates on your behalf.

Each hostname belongs to one project. The first project that proves control of the hostname
gets it, and a different project then gets `Ready=False` with reason `HostnameClaimed`. A
hostname inside a zone that a different project manages with a DomainZone is also refused.
Apoxy publishes the address records behind `<hostname>.cname.apoxy.net` only after your
project has the hostname, so the target of your CNAME resolves after the first ownership
proof, not when you apply the DomainRecord.

## Minimal setup

```yaml title="domain.yaml"
apiVersion: core.apoxy.dev/v1alpha3
kind: DomainRecord
spec:
  name: api.example.com
  tls: {}
  target:
    ref:
      group: gateway.apoxy.dev
      kind: Gateway
      name: default
```

Omit `metadata.name`. Apoxy generates the resource name from `spec.name` and the target type.

Apply the DomainRecord, then create the CNAME at your registrar:

```
api.example.com.   CNAME   api.example.com.cname.apoxy.net.
```

Inspect the generated record and target status by filtering on the hostname:

```bash title="terminal"
apoxy domain list \
  --field-selector spec.name=api.example.com \
  -o yaml
```

### Tunnel-backed targets

Pointing `target.ref` at a `TunnelNode` (group `core.apoxy.dev`) or a `VPCService` (group
`vpc.apoxy.dev`) routes the hostname through the default Gateway to endpoints behind your
tunnel agents - no explicit HTTPRoute needed. The controller wires the route automatically
and keeps the `TargetReady` condition on the `DomainRecord` in sync with the target's
endpoint health.

Once the CNAME propagates, Apoxy issues a TLS certificate using the ACME **HTTP-01** challenge
(Let's Encrypt / Google Trust Services). This takes roughly 30–60 seconds.

## Zero-downtime migration (pre-issuance)

The default HTTP-01 flow has a side effect: the certificate is only issued **after** you flip
your main CNAME. Until `status.conditions.TLSReady=True`, browsers hitting the new endpoint see
a certificate error - typically a 30–60 second window.

To eliminate that window, delegate the ACME validation to Apoxy **before** you cut over:

### Apply the DomainRecord

Same as above.

### Add the ACME challenge delegation CNAME

At your registrar, create an additional CNAME:

```
_acme-challenge.api.example.com.   CNAME   _acme-challenge.api.example.com.cname.apoxy.net.
```

**The target must be `_acme-challenge.<your-full-domain>.cname.apoxy.net.`** - include every
label of your hostname verbatim, including the TLD. Dropping the TLD or a mid-label is the
most common mistake and the delegation check will never pass.

<DocsTable>
| Hostname             | Correct target                                                | Common wrong target                                                            |
|----------------------|----------------------------------------------------------------|--------------------------------------------------------------------------------|
| `api.example.com`    | `_acme-challenge.api.example.com.cname.apoxy.net.`            | `_acme-challenge.api.example.cname.apoxy.net.` (missing `.com`)                |
| `app.example.co.uk`  | `_acme-challenge.app.example.co.uk.cname.apoxy.net.`          | `_acme-challenge.app.example.co.cname.apoxy.net.` (missing `.uk`)              |
</DocsTable>

The filtered record prints the exact target in the `ACMEChallengeReady` condition message.

This tells the ACME CA to look up the validation TXT record inside our zone, so we can prove
domain ownership via **DNS-01** without any traffic flowing through Apoxy yet.

### Wait for the certificate

Apoxy detects the delegation and pre-issues the certificate. Watch the conditions:

```bash title="terminal"
apoxy domain list \
  --field-selector spec.name=api.example.com \
  -o yaml
```

You should see:

```yaml
items:
- status:
    conditions:
    - type: ACMEChallengeReady
      status: "True"
      reason: ACMEChallengeConfigured
    - type: TLSReady
      status: "True"
      reason: CertificateIssued
    - type: CNAMEConfigured
      status: "False"
      reason: CNAMENotConfigured
```

`CNAMEConfigured=False` is expected before cutover. `TLSReady=True` lands first, so the certificate
is already on the gateway when you switch traffic.

### Flip the main CNAME

Now change your main record at your registrar:

```
api.example.com.   CNAME   api.example.com.cname.apoxy.net.
```

The next DNS resolution hits Apoxy. Our gateway serves the already-issued certificate from the
first request - no cert error, no refresh loop. For a hostname that receives steady traffic,
the gateway renews its copy of the certificate in the background, so renewal does not add
latency to client handshakes.

### Keep the delegation CNAME

Leave `_acme-challenge.api.example.com` pointing at our zone. Renewal uses the same DNS-01
path, so keeping the delegation means renewals stay zero-intervention.

## Zero-downtime migration - HTTP-only (no TLS)

TLS is the default: a `DomainRecord` that targets a Gateway, Proxy, TunnelNode, VPCService,
EdgeFunction, or another `DomainRecord` gets a managed certificate even if you omit the `tls` block
entirely. To serve a hostname over plain HTTP instead, ask for it explicitly:

```yaml
spec:
  tls:
    disabled: true
```

`disabled: true` and `certificateAuthority` are mutually exclusive - naming a CA while
switching issuance off is rejected at admission rather than silently honored one way.

`disabled` governs whether Apoxy provisions a certificate for a domain that does not have
one. It is not a way to remove a certificate you already have:

- No certificate is provisioned, and the domain settles at `Active` once ownership is proven
  rather than waiting on an issuance that will never happen.
- A domain that already holds a certificate keeps it, keeps serving it, and keeps renewing
  it. Letting a certificate that is still being served lapse would break HTTPS on a cliff, so
  renewal deliberately continues.
- Ownership is unaffected. A domain verified by an existing certificate stays verified and
  routable - disabling TLS never detaches a live hostname.
- Clearing the field starts issuance on the next reconcile.

To stop serving a certificate entirely, delete the `DomainRecord`.

Until a certificate exists, HTTPS requests for the hostname fail the TLS handshake; plain HTTP
serves normally.

With TLS off there is no ACME certificate whose issuance could double as proof of ownership.
Apoxy instead accepts an explicit ownership challenge at a dedicated label:

```
_apoxy-challenge.api.example.com.   CNAME   _apoxy-verify.cname.apoxy.net.
```

The target is a **single fixed string** - no FQDN embedding, no per-domain token. Copy it
verbatim.

Once the challenge resolves, the controller marks the `DomainRecord` with
`OwnershipVerified=True` and admits the hostname to the data plane. From that point, the
moment you flip your main CNAME the gateway starts serving traffic for it - the same
zero-downtime effect as the TLS flow, without needing a certificate.

TLS customers get `OwnershipVerified=True` as soon as their main CNAME resolves to our zone -
a CNAME pointing at us proves DNS control on its own, whether or not a certificate has been
issued yet. An issued, unexpired certificate also holds ownership on its own: ACME proved you
controlled the domain when it was issued, and that proof stands until the certificate expires.
A DNS blip - ours or your provider's - can therefore never de-verify a domain that holds a
valid certificate. Renewal requires a fresh DNS proof, so a domain you genuinely move away
detaches when its certificate lapses. Setting `_apoxy-challenge` in
addition is optional for TLS - the `_acme-challenge` delegation already covers both the
pre-issued cert and ownership.

You can leave the `_apoxy-challenge` delegation in place permanently; it's idempotent and
doesn't need to be touched across renewals or cutovers.

## Lifecycle phases

`status.phase` is the single answer to "where is my domain". Conditions (below) are the
observation log underneath it: each records one fact and when it last changed, which is what
explains *why* the record is in a given phase.

<DocsTable>
| Phase       | Meaning                                                                                                                                          | Routable |
|-------------|--------------------------------------------------------------------------------------------------------------------------------------------------|----------|
| `Pending`   | No ownership proof observed yet: no main CNAME, no challenge delegation. Or a different project holds the hostname (`HostnameClaimed`).          | No       |
| `Issuing`   | Ownership proven, certificate being minted (first issuance, or re-issuance after an expiry). Routable so the HTTP-01 challenge can be answered.  | Yes      |
| `Active`    | Everything on Apoxy's side is done: ownership proven, certificate stored (for TLS records). Traffic serves the moment it arrives.                | Yes      |
| `Detached`  | Every ownership proof is gone after the record was live, or a different project holds the hostname. Releases the hostname: a different project can use it 25 hours later. | No       |
</DocsTable>

Phase transitions require affirmative observations: if we cannot reach a resolver or the
certificate store, or get an answer we have reason to distrust, the phase holds rather
than regressing. The phase describes Apoxy's side
only. Two things it deliberately excludes are reported by conditions instead:

- **Cutover.** A pre-issued record whose main CNAME has not been flipped yet is `Active` with
  `CNAMEConfigured=False` - our side is finished; the remaining step is yours.
- **Backend health.** An `Active` record with an unhealthy backend stays `Active` and serves
  502s, reported by the `TargetReady` condition.

Records created before phases existed show an empty phase until their next reconcile.

## Condition reference

<DocsTable>
| Condition                       | Meaning                                                                                                                                                                                                                                                               |
|---------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `OwnershipVerified`             | True when Apoxy has proof you control this hostname - a valid `_apoxy-challenge` CNAME, a successful main-CNAME cutover, an issued unexpired certificate, or - for zone-managed records - a verified DomainZone for the zone itself (`reason: ZoneOwned`). This is the fact behind the routable phases. A hostname is provably yours before your first cert is issued, and a valid cert keeps it yours until expiry even through DNS blips. |
| `TLSReady`                      | A stored, unexpired certificate exists for this hostname. This is what gates HTTPS - until it is True, plain HTTP routes serve but TLS handshakes do not complete. It reflects the certificate only, so an unhealthy backend does not retract it: you get a 502 from the backend rather than a TLS error. Absent entirely on records with `tls.disabled: true`, which have no certificate lifecycle and go straight to `Active` once ownership is proven. |
| `ACMEChallengeReady`            | Your `_acme-challenge.<fqdn>` CNAME points into our managed zone, so we can pre-issue certs via DNS-01. Also absent when `tls.disabled: true`. |
| `CNAMEConfigured`               | Your main CNAME currently resolves to our zone. For CNAME-mode records this is one of the proofs that flips `OwnershipVerified` (above); on its own it does not decide whether traffic is served. |
| `TargetReady`                   | The backend (Gateway / Proxy / Tunnel / EdgeFunction) this record points at is healthy. |
| `Ready`                         | Aggregate: all of the customer-visible setup above is green. Dashboards and CLI show this; the data plane does not key on it. A zone-managed record whose DomainZone is not verified yet has `reason: ZoneNotClaimed`: Apoxy writes no DNS record of the zone until then, and writes the records within seconds after it. A zone-managed record whose DomainZone is in phase `Error` has `reason: ZoneError`: Apoxy writes no DNS record of the zone. A record whose hostname a different project holds, or released less than 25 hours ago, has `reason: HostnameClaimed` on `Ready` and on `OwnershipVerified`: Apoxy writes no DNS record and issues no certificate for it. Its `TLSReady` is True only when a certificate for the hostname is already stored; the record still serves no traffic. |
</DocsTable>

### How conditions behave when we can't read your DNS

Every condition above that is derived from a DNS lookup - `OwnershipVerified`,
`CNAMEConfigured`, `ACMEChallengeReady` - distinguishes two different negatives:

- **Your record is not published.** A resolver answered and told us nothing is there. The
  condition updates to reflect that. Remove your `_apoxy-challenge` delegation and
  `OwnershipVerified` will go `False` with reason `OwnershipNotVerified`, which also releases
  your claim on the hostname. A different project can use the hostname 25 hours after the
  release. Deleting the last DomainRecord of the hostname in your project releases it too.
- **We could not reach a resolver.** No answer came back at all, so nothing is known. The
  condition is held at its last observed value rather than retracted, and the status is not
  rewritten. A DNS outage on our side or a public-resolver blip therefore does not change
  what your domain reports, and does not interrupt serving.

The practical consequence: a condition that has not changed in a while is not necessarily a
condition we re-confirmed a moment ago. `lastTransitionTime` records when the value last
changed, not when it was last checked.

## Fallback

If you skip the ACME challenge delegation (no `_acme-challenge` CNAME), Apoxy falls back to
HTTP-01 after you flip
the main CNAME. That still works - we will try to create certificates on the fly and you just
get the standard 30–60s window between cutover and `TLSReady=True`.

## Troubleshooting

- **`ACMEChallengeReady=False` after adding the CNAME** - DNS caching. Wait up to
  the record's TTL at the customer resolver, then re-check with `dig CNAME
  _acme-challenge.api.example.com`.
- **`TLSReady=False` with reason `CertificateError`** - check the status message. Common
  causes: delegation CNAME points to the wrong target (verify it ends in
  `.<cname-zone-suffix>.` exactly using the label-match table above), or the ACME account
  is rate-limited.
- **Want to see what target to use** - Filter `apoxy domain list -o yaml` with
  `--field-selector spec.name=<hostname>` to see the delegation target in the condition message.
- **Fixed a typo in the delegation CNAME but it still shows `False`** - two DNS caches may
  hold stale answers until they expire:
  - The **old CNAME value** at recursive resolvers - pinned for the TTL you set at your
    registrar (commonly 300s–3600s).
  - The **NXDOMAIN for the broken target** inside `cname.apoxy.net` - cached up to the zone's
    SOA MINIMUM TTL, **300s (5 minutes)**.

  To minimize this window, drop your registrar's CNAME TTL (e.g. to 60s) **before** you first
  publish it, so any typo is easy to correct. If you've already been bitten, there's no
  shortcut - wait out the longer of the two TTLs, then run the filtered domain list again.
  `ACMEChallengeReady` should become `True` on the next reconcile (runs every ~30s).
- **`Ready=False` with reason `HostnameClaimed`** - a different project holds this hostname,
  or a zone that contains it, or released it less than 25 hours ago. The status message tells
  which. Use the project that holds it, or delete the DomainRecord there and wait 25 hours. If
  you control this domain and do not know the other project, contact support.
- **`<hostname>.cname.apoxy.net` does not resolve** - Apoxy publishes its addresses after the
  first ownership proof. Resolvers that asked before that cache the NXDOMAIN for up to
  **300s (5 minutes)**.
- **ACME rate-limit errors** - issuance workflows honor the CA's `Retry-After` header and
  sleep in-place instead of thrashing, so a single rate-limited domain will not burn the
  shared quota. A certificate that was in flight during a rate-limit event will resume
  automatically once the window clears. Check the filtered domain list; `TLSReady` becomes `True`
  without further action.

---

**Navigation** (Guides)

- Previous: [Deploying compute Services](/docs/guides/deploying-compute-services.md)
- Next: [HTTP to HTTPS redirect](/docs/guides/http-to-https-redirect.md)
- All pages: [index](/docs/llms.txt)
