Cluster storage for Caddy

Starting with Uncloud v0.22.0, Caddy uses cluster storage by default.

The Uncloud storage module lets Caddy instances share TLS certificates, private keys, and ACME challenge tokens through Uncloud's cluster store.

This matters when you run Caddy on multiple machines and distribute traffic between them using DNS or a load balancer. In this case, an ACME challenge can reach a different Caddy instance from the one requesting the certificate. Cluster storage lets any Caddy instance read the challenge token from the shared cluster store and complete the ACME challenge. It uses distributed locks to coordinate certificate issuance. Once one instance obtains a certificate, the others can use it too.

Upgrading from earlier versions

Starting with Uncloud v0.22.0, uc caddy deploy deploys the Uncloud Caddy image ( ghcr.io/unlabs-dev/caddy-uncloud) with cluster storage enabled by default.

Earlier versions deployed the official caddy image with local certificate storage. Upgrading Uncloud does not change the running Caddy service. Redeploy it to switch to the new default image and cluster storage.

Before you deploy, upgrade the uc CLI and the daemon on all machines to v0.22.0 or newer. Follow the upgrade instructions for daemon upgrades, including any required migrations from older releases. Check current versions with uc version and uc machine ls.

The first uc caddy deploy after the upgrade doesn't know the values you set with earlier versions of uc. It replaces your image, global config, and machine list with the defaults unless you pass them as flags. If you deployed Caddy only to some machines, add --machine with the same machines to every uc caddy deploy command below.

If you already use storage uncloud, your certificates stay where they are. Run uc caddy deploy and pass the global config you deployed it with, unless it only contains storage uncloud:

uc caddy deploy --caddyfile global.Caddyfile

Quick upgrade

Caddy does not copy certificates when you change storage backends. Unless you migrate them first, Caddy will reissue them. HTTPS may fail for those domains until that finishes, and a large number of certificates can hit Let's Encrypt rate limits.

Run the command below if you don't mind reissuing all certificates:

uc caddy deploy

Migrating certificates

Follow these steps to keep your existing certificates and avoid HTTPS failures:

Deploy the new image but stay on local storage. Use your existing global config if you have one, or an empty file:
```
touch local.Caddyfile
uc caddy deploy --caddyfile local.Caddyfile
```
Find the ID of the Caddy container on each machine:
```
uc inspect caddy
```

Copy the certificates to cluster storage by running this command for each container ID. Each machine stores its own certificates, so don't skip any of them. These caddy storage commands are experimental.

uc exec -T --container CONTAINER_ID caddy sh -c '
  printf "{\n\tstorage uncloud\n}\n" > /tmp/Caddyfile.cluster
  caddy storage export --config /etc/caddy/Caddyfile --output - |
    caddy storage import --config /tmp/Caddyfile.cluster --input -
  rm /tmp/Caddyfile.cluster
'

Check that all your certificates are in cluster storage:
```
uc caddy cert ls
```
Switch Caddy to cluster storage. If you have a custom global config, add storage uncloud to it and pass it with --caddyfile global.Caddyfile instead. The command warns that all certificates will be reissued. You can ignore this because you've already copied them.
```
uc caddy deploy --caddyfile ""
```
Check that the Caddy config includes storage uncloud and doesn't show any config load warnings:
```
uc caddy config
```

Upgrading a Compose deployment

If you manage Caddy with Compose, keep using uc deploy and update your Compose file to match the Compose example. To keep your certificates, follow the migration steps with these changes:

In step 1, update the image and add the /run/uncloud/api:/run/uncloud/api:ro volume mount but leave out storage uncloud in your global Caddy config (x-caddy). Then run uc deploy.
In step 5, add storage uncloud to your global Caddy config, then run uc deploy.

Keeping local storage

To keep local storage, pass a custom Caddyfile without storage uncloud using --caddyfile. The default Uncloud Caddy image supports local storage too. If you use the official caddy image, you must also provide a Caddyfile without storage uncloud.

Deployments using uc caddy deploy keep the /data mount so local certificates survive container updates. For Compose deployments using local storage, keep or add /var/lib/uncloud/caddy:/data.

5.2 KiB Raw Blame History