Public cluster links

[kadinsayani]

Summary

Adds public cluster link support. A public cluster link lets one cluster (A) reach another cluster (B) without presenting a client certificate, relying solely on TLS certificate pinning to authenticate B. B is completely unaware of the link; no identity or link row is created on B's side. This is useful when B exposes resources publicly, or when anonymous-style read access to B is sufficient.

Depends on #18195.

API extension: cluster_links_public

How it works

Creating a public link is a two-phase POST /1.0/cluster/links on A:

1. Fetch. A POST with a name, "type": "public" and remote_address (no cluster_certificate) creates a pending link. A fetches B's TLS certificate, verifies that the address actually serves the LXD API, and returns the certificate's fingerprint and PEM encoding (new ClusterLinkCertificate response type) for the user to verify. The certificate is held in volatile.pending_certificate but is not yet pinned, so the link stays inert.
2. Confirm. A second POST with the same name and remote_address, this time including the cluster_certificate from step 1, pins the certificate and activates the link. The resubmitted certificate must match the one fetched in step 1; a mismatch is rejected and the link remains pending.

The CLI performs both phases, prompting for confirmation of the fingerprint in between.

Example workflow

# On Cluster A: create a public link to B
lxc cluster link create image-host --public --remote-address 10.0.0.1:8443
# Confirm the certificate fingerprint when prompted

# Verify on A
lxc cluster link list
lxc cluster link show image-host    # type: public

# Cleanup (A only — B is unaware)
lxc cluster link delete image-host

[simondeziel]

How it works

1. Cluster A specifies B's address. LXD fetches B's TLS certificate via a new GET /1.0/cluster/links/certificate endpoint and returns the fingerprint for user confirmation.

2. A stores the link locally with B's pinned certificate. B is never contacted beyond the initial cert fetch.

This TOFU (Trust On First Use) with user verification provides authentication AFAIK. Is the "unauthenticated" bit here meaning there is no mTLS going on between the 2 clusters?

[kadinsayani]

How it works

1. Cluster A specifies B's address. LXD fetches B's TLS certificate via a new GET /1.0/cluster/links/certificate endpoint and returns the fingerprint for user confirmation.

2. A stores the link locally with B's pinned certificate. B is never contacted beyond the initial cert fetch.

This TOFU (Trust On First Use) with user verification provides authentication AFAIK. Is the "unauthenticated" bit here meaning there is no mTLS going on between the 2 clusters?

Yes, exactly. "unauthenticated" means no mTLS; cluster A does not present a client certificate when connecting to cluster B.

[simondeziel]

How it works

1. Cluster A specifies B's address. LXD fetches B's TLS certificate via a new GET /1.0/cluster/links/certificate endpoint and returns the fingerprint for user confirmation.

2. A stores the link locally with B's pinned certificate. B is never contacted beyond the initial cert fetch.

This TOFU (Trust On First Use) with user verification provides authentication AFAIK. Is the "unauthenticated" bit here meaning there is no mTLS going on between the 2 clusters?

Yes, exactly. "unauthenticated" means no mTLS; cluster A does not present a client certificate when connecting to cluster B.

OK good, that's better in terms of security and aligns nicely with the other widely known TOFU model popularized by SSH.

That said, I feels like a misnomer to call it "unauthenticated" then. "Unidirectional cluster link"? "One way cluster link"?

[kadinsayani]

How it works

1. Cluster A specifies B's address. LXD fetches B's TLS certificate via a new GET /1.0/cluster/links/certificate endpoint and returns the fingerprint for user confirmation.

2. A stores the link locally with B's pinned certificate. B is never contacted beyond the initial cert fetch.

This TOFU (Trust On First Use) with user verification provides authentication AFAIK. Is the "unauthenticated" bit here meaning there is no mTLS going on between the 2 clusters?

Yes, exactly. "unauthenticated" means no mTLS; cluster A does not present a client certificate when connecting to cluster B.

OK good, that's better in terms of security and aligns nicely with the other widely known TOFU model popularized by SSH.

That said, I feels like a misnomer to call it "unauthenticated" then. "Unidirectional cluster link"? "One way cluster link"?

Since we already have unidirectional as another type, how about "public"? @tomponline previously suggested this.

[simondeziel]

Yes, exactly. "unauthenticated" means no mTLS; cluster A does not present a client certificate when connecting to cluster B.

OK good, that's better in terms of security and aligns nicely with the other widely known TOFU model popularized by SSH.
That said, I feels like a misnomer to call it "unauthenticated" then. "Unidirectional cluster link"? "One way cluster link"?

Since we already have unidirectional as another type, how about "public"? @tomponline previously suggested this.

"Public cluster link" sounds good. There is also "anonymous cluster link" where the connecting side doesn't present its TLS cert.

[simondeziel]

The test LGTM, thanks!

[simondeziel]

Other than the "unauthenticated" bit that I find misleading, this LGTM (with a tiny nit).

[Copilot]

Pull request overview

Adds a new public cluster link type that allows one cluster to reach another without presenting a client certificate, relying on pinned server TLS certificates and a two-phase (fetch/confirm) creation flow. This extends the existing cluster-links feature set (and builds on unidirectional links) while explicitly preventing use of public links for replication features that require authenticated writes.

Changes:

• Introduces API extension cluster_links_public, new link type public, and a new ClusterLinkCertificate response for the pending fetch phase.
• Implements server-side pending/confirm handling with volatile pending state (volatile.pending_certificate, volatile.pending_address) and public-link connection args (no client cert).
• Updates CLI, docs, and integration tests to support and validate the new public flow (including rejection paths and replication/config-time guards).

Reviewed changes

Copilot reviewed 19 out of 19 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
test/suites/clustering.sh	Adds an end-to-end integration test covering public cluster link creation/confirmation, canonicalization, rejection paths, and replication restrictions.
test/includes/test-groups.sh	Adds the new clustering test to the cluster test group.
shared/version/api.go	Registers the new API extension cluster_links_public.
shared/api/cluster.go	Adds ClusterLinkTypePublic, RemoteAddress to request payload, and ClusterLinkCertificate response type.
lxd/metadata/configuration.json	Documents new volatile config keys for pending public links.
lxd/db/cluster/cluster_links.go	Adds DB type code mapping for public cluster links.
lxd/cluster/cluster_link.go	Adds server verification of remote being a LXD API, and public-link connection args (no client cert) for link refresh/connect flows.
lxd/api_replicators.go	Rejects public cluster links for replicators at config validation time.
lxd/api_project.go	Rejects public cluster links for project replication config (replica.cluster).
lxd/api_cluster_link.go	Adds pending/confirm public link request modes, validation, handlers, and volatile key validation.
lxc/cluster_link.go	Adds --public + --remote-address CLI flow with certificate fingerprint confirmation and cleanup behavior.
doc/rest-api.yaml	Documents the new ClusterLinkCertificate type and remote_address field in the REST API schema.
doc/metadata.txt	Documents new volatile config keys in generated metadata docs.
doc/howto/cluster_links_manage.md	Documents deletion behavior for public links.
doc/howto/cluster_links_create.md	Adds “Create a public cluster link” how-to section and updates link-type overview.
doc/explanation/clusters.md	Updates cluster-links explanation to include public links and their connection process.
doc/api-extensions.md	Documents the cluster_links_public extension and its two-phase behavior and restrictions.
client/lxd_cluster.go	Adds client support for pending public link creation and extension gating for public link creation.
client/interfaces.go	Extends InstanceServer interface with CreateClusterLinkPendingPublic.