From 87e99ae3696ccf3efbb7ec159c1efbad0d877ef3 Mon Sep 17 00:00:00 2001 From: Pasha Sviderski Date: Fri, 2 Oct 2026 13:27:07 +1000 Subject: [PATCH] docs(caddy): new page Cluster storage for Caddy --- .../docs/3-concepts/2-ingress/1-overview.md | 8 +++ .../3-concepts/2-ingress/3-managing-caddy.md | 7 ++- .../2-ingress/4-cluster-storage-for-caddy.md | 58 +++++++++++++++++++ 3 files changed, 71 insertions(+), 2 deletions(-) create mode 100644 website/docs/3-concepts/2-ingress/4-cluster-storage-for-caddy.md diff --git a/website/docs/3-concepts/2-ingress/1-overview.md b/website/docs/3-concepts/2-ingress/1-overview.md index 50189a57..16e1978e 100644 --- a/website/docs/3-concepts/2-ingress/1-overview.md +++ b/website/docs/3-concepts/2-ingress/1-overview.md @@ -24,3 +24,11 @@ When you [publish a service port](2-publishing-services.md), Uncloud automatical For advanced use cases, Uncloud allows to customise the Caddy config using the `x-caddy` extension in Compose files. See [Custom Caddy configuration](2-publishing-services.md#custom-caddy-configuration) for details. + +:::tip Shared TLS certificates + +Uncloud also provides native cluster storage for Caddy. It shares TLS certificates and ACME challenge tokens across +machines and coordinates certificate issuance. See [Cluster storage for Caddy](4-cluster-storage-for-caddy.md) +to enable it. + +::: diff --git a/website/docs/3-concepts/2-ingress/3-managing-caddy.md b/website/docs/3-concepts/2-ingress/3-managing-caddy.md index 90fb4e35..8659f7a2 100644 --- a/website/docs/3-concepts/2-ingress/3-managing-caddy.md +++ b/website/docs/3-concepts/2-ingress/3-managing-caddy.md @@ -3,6 +3,10 @@ Caddy is automatically deployed as a global service `caddy` when you initialise a cluster with `uc machine init`. By default, it runs on every machine to handle incoming HTTP/HTTPS traffic and route it to your services. +Since [v0.21.0](https://github.com/psviderski/uncloud/releases/tag/v0.21.0), Uncloud provides native +[cluster storage for Caddy](4-cluster-storage-for-caddy.md) (opt-in) to share TLS certificates and coordinate +certificate issuance across machines. + ## Checking status View the `caddy` service status and which machines it's running on: @@ -158,8 +162,7 @@ The image must include `curl` for the healthcheck and start Caddy with `/etc/cad official [Caddy image](https://hub.docker.com/_/caddy) do both by default. Keep the `/data` mount while using Caddy's default local storage so TLS certificates survive container updates. You can -remove this mount when using the [Uncloud storage module](https://github.com/unlabs-dev/caddy-uncloud) with -`storage uncloud` in your global Caddy config. +remove this mount when using [cluster storage for Caddy](4-cluster-storage-for-caddy.md). ::: diff --git a/website/docs/3-concepts/2-ingress/4-cluster-storage-for-caddy.md b/website/docs/3-concepts/2-ingress/4-cluster-storage-for-caddy.md new file mode 100644 index 00000000..06e7707f --- /dev/null +++ b/website/docs/3-concepts/2-ingress/4-cluster-storage-for-caddy.md @@ -0,0 +1,58 @@ +# Cluster storage for Caddy + +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. It uses distributed locks to coordinate +certificate issuance. Once one instance obtains a certificate, the others can use it too. + +## Why use cluster storage? + +By default, each Caddy instance stores its certificates locally. When DNS points to multiple machines or a load balancer +distributes traffic between them, an ACME challenge can reach a different instance from the one requesting the +certificate. That instance may not have the challenge token, which can delay or prevent certificate issuance. + +Cluster storage is optional. The default Caddy image does not include the module, so you need to deploy an image that +includes it and configure Caddy to use it. + +## Enabling cluster storage + +:::info Requirements + +Cluster storage requires Uncloud **v0.21.0 or newer** for both the `uc` CLI and the daemon on every cluster machine. +Check your CLI version with `uc version` and daemon versions with `uc machine ls`. Upgrade older versions before +enabling cluster storage. + +::: + +Create a global Caddyfile, or add `storage uncloud` to the global options in your existing one: + +```caddyfile title="global.Caddyfile" +{ + storage uncloud + + # Uncomment to enable debug logs useful for troubleshooting storage operations: + # debug +} +``` + +Deploy Caddy with the pre-built module image and your global config: + +```shell +uc caddy deploy --image ghcr.io/unlabs-dev/caddy-uncloud:0.1.1 --caddyfile global.Caddyfile +``` + +See the [module README](https://github.com/unlabs-dev/caddy-uncloud#usage) for custom image builds, Compose deployment, +and additional storage options. + +## Verifying storage + +Check that `storage uncloud` appears in the Caddy config: + +```shell +uc caddy config +``` + +List issued certificates in cluster storage with [`uc caddy cert ls`](../../9-cli-reference/uc_caddy_cert_ls.md): + +```shell +uc caddy cert ls +```