Skip to content
Stackship documentation Svenska

Stackship platformAdministrators

Connect a cluster

Register a Kubernetes cluster so that boundaries can be projected onto it and resources placed there.

Requires: kernel/clusters/write

Registering a cluster needs kernel/clusters/write at the platform root, which only Platform Owner holds. The first cluster is usually registered in the first-run wizard — see Getting started; this page registers any further one.

Before you start

For a cluster other than the one the platform runs in, you need:

  • the URL of its Kubernetes API server, reachable from the platform — not the Stackship API;
  • its CA certificate, base64-encoded (the PEM text itself is not accepted);
  • an API server that trusts the platform's identity provider, https://auth.example.com: the platform forwards your own sign-in token to it — see Credentials.

Register the cluster

  1. Open Settings → Platform Settings in the sidebar and the Clusters tab.
  2. Choose Register cluster.
  3. Enter a Name — unique across the platform, for example prod-eu-west — and a Region.
  4. Leave Connectivity on Direct.
  5. Choose how the platform reaches the API server:
    • For the cluster the platform runs in, leave Use an external (out-of-cluster) API server off. No URL or certificate is needed.
    • For any other cluster, turn it on and fill in API server URL and CA certificate. Fill in the certificate even though the form marks it optional: the platform cannot open a connection to an external API server without it.
  6. If the cluster can host a Crosslink hub, turn on Accepts inbound links (Crosslink hub eligible) and enter its Inbound endpoint as host:port — see Accepts inbound links.
  7. Choose Register cluster.

The cluster appears in the list with Direct in the Connectivity column. Nothing is installed on it yet: a boundary is made available on the cluster by projecting it there — see Add a projection.

Verify the connection

The Clusters list does not test the connection; the first request that reaches the cluster does — projecting a boundary onto it, or opening a resource placed there. That request fails if the platform cannot reach the API server, if the certificate does not verify, or if the API server does not accept the token.

With the CLI you can confirm the registration itself:

bash
stsh cluster get prod-eu-west

Agent clusters

Choosing Agent under Connectivity registers the cluster and immediately issues a join token, shown once in a dialog that cannot be closed until you tick I have copied the join token. Only a hash of the token is stored; a token is single-use and expires after an hour.

Important

An agent cannot be enrolled with what the dialog shows. The command it prints installs the operator from a Helm chart that is not published, and on installations where the agent dispatch address is not configured it shows This control plane does not know its own address instead of a command. Register clusters as Direct.

Next steps