# Get wildcard certificates with Caddy

Let Caddy prove control of a hosted zone through DNS-01 challenges, so it gets wildcard certificates without another DNS provider.

Caddy writes the ACME challenge into your hosted zone as a `TXT` record at `_acme-challenge`, so a
certificate authority can issue it a certificate for `*.example.com`. Replace _example.com_ with
your zone.

## Prerequisites

- A hosted zone for the domain, delegated to the platform nameservers (see
  [Delegate a domain](delegate-a-domain.md)).
- For the access key Caddy uses, or the instance role of the machine it runs on: `dns:ListZones` on
  all hosted zones (the module lists them to find the zone's id; a statement that names only one
  zone does not allow the list), and `dns:ListRecords` and `dns:ChangeRecords` on the zone.
- Caddy built with the Deutsche Cloud DNS module, `caddy-dns-ews`, which is in the Deutsche Cloud
  repository and not published as a Caddy plugin:

```sh
xcaddy build --with github.com/deutschlandgpt/ews/caddy-dns-ews=./caddy-dns-ews
```

## Configure Caddy

On a Deutsche Cloud machine whose instance role has the permissions above, nothing else is needed: the
module exchanges the machine's identity for short-lived credentials.

```caddyfile
*.preview.example.com {
	tls {
		dns ews
	}
	reverse_proxy localhost:3000
}
```

Anywhere else, give it the Deutsche Cloud Console address and an access key (`EWS1…:<secret>`). With an
access key, `api_url` is required:

```caddyfile
tls {
	dns ews {
		api_url    https://console.example.com
		access_key {env.EWS_ACCESS_KEY}
	}
}
```

## Result

Caddy gets the certificate. A wildcard and its apex can be issued
together: the module adds and removes single `TXT` values in the `_acme-challenge` set instead of
replacing the set, and deletes the set once it is empty.

Certificates the platform issues for your apps' custom domains use their own challenge answers,
which the nameservers serve next to any `TXT` values you store at `_acme-challenge`.

## When Caddy cannot get the certificate

The module's errors in Caddy's log:

- `ews: api_url is required with an access_key`: add `api_url`.
- `ews: no access_key and no usable instance identity: …`: the machine is not a Deutsche Cloud
  machine, or its instance identity is missing; configure an access key instead.
- `ews: instance credentials refused (HTTP …): … — does the machine have an instance role?`: attach
  an instance role with the permissions above.
- `ews: no DNS zone "example.com" in this organization`: the key's organization has no hosted zone
  of that name; the module looks for the zone named in Caddy's site address.
- `ews: GET /dns/api/zones: HTTP 403: …` (or the same for `/records`): the key or role lacks one of
  the permissions above.

## Related

- [Install an add-on](/docs/eks/guide/install-an-add-on): cert-manager in a managed Kubernetes
  cluster has its own DNS-01 support.
- [Security](security.md)
