mirror of
https://github.com/psviderski/uncloud.git
synced 2026-11-10 20:54:17 +00:00
121 lines
5.2 KiB
Markdown
121 lines
5.2 KiB
Markdown
# Cluster storage for Caddy
|
|
|
|
Starting with Uncloud [v0.22.0](https://github.com/psviderski/uncloud/releases/tag/v0.22.0), Caddy uses cluster storage
|
|
by default.
|
|
|
|
The [Uncloud storage module](https://github.com/unlabs-dev/caddy-uncloud) 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`](https://github.com/unlabs-dev/caddy-uncloud/pkgs/container/caddy-uncloud)) with
|
|
cluster storage enabled by default.
|
|
|
|
Earlier versions deployed the official [`caddy`](https://hub.docker.com/_/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](../../2-getting-started/1-install-cli.md) and the daemon on all machines to
|
|
v0.22.0 or newer. Follow the [upgrade instructions](https://github.com/psviderski/uncloud/releases/latest) 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`:
|
|
|
|
```shell
|
|
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](https://letsencrypt.org/docs/rate-limits/).
|
|
|
|
Run the command below if you don't mind reissuing all certificates:
|
|
|
|
```shell
|
|
uc caddy deploy
|
|
```
|
|
|
|
### Migrating certificates
|
|
|
|
Follow these steps to keep your existing certificates and avoid HTTPS failures:
|
|
|
|
1. Deploy the new image but stay on local storage. Use your existing global config if you have one, or an empty file:
|
|
|
|
```shell
|
|
touch local.Caddyfile
|
|
uc caddy deploy --caddyfile local.Caddyfile
|
|
```
|
|
|
|
2. Find the ID of the Caddy container on each machine:
|
|
|
|
```shell
|
|
uc inspect caddy
|
|
```
|
|
|
|
3. 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`](https://caddyserver.com/docs/command-line#caddy-storage) commands are experimental.
|
|
|
|
```shell
|
|
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
|
|
'
|
|
```
|
|
|
|
4. Check that all your certificates are in cluster storage:
|
|
|
|
```shell
|
|
uc caddy cert ls
|
|
```
|
|
|
|
5. 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.
|
|
|
|
```shell
|
|
uc caddy deploy --caddyfile ""
|
|
```
|
|
|
|
6. Check that the Caddy config includes `storage uncloud` and doesn't show any config load warnings:
|
|
|
|
```shell
|
|
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](3-managing-caddy.md#managing-caddy-with-compose). To keep your certificates, follow the
|
|
[migration steps](#migrating-certificates) 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`.
|