Skip to main content

Headless access to Syself Autopilot

Inspect 1.36

Some environments and workflows require programmatic or terminal-only access to Kubernetes clusters without relying on browser-based authentication. This is particularly important for CI/CD pipelines, remote systems without a graphical interface, or users working over SSH.

By default, our platform uses OIDC-based authentication, which prompts a login flow through your local browser. While this approach is secure and user-friendly for interactive sessions, it isn't always suitable for automated or headless environments.

How to use headless access to Syself Autopilot#

We provide headless access via a Kubernetes Service Account token. This approach bypasses the OIDC browser flow and enables direct access through a generated kubeconfig file.

The service account we expose is the same one used by GitOps tools that need to make changes to the Management Cluster. By reusing this account, you gain authenticated, stable, and non-interactive access without managing user credentials.

This account is scoped to your organization namespace: it can apply and patch manifests there, such as your Cluster declarations, but it is not a cluster-admin. Use it to manage your own resources, not for cluster-wide operations like a helm install against the management cluster.

You can generate a kubeconfig from this account with the following command:

		$ SERVER=$(kubectl config view --minify -o jsonpath='{.clusters[0].cluster.server}') && \
CA_CRT=$(kubectl get secret gitops-sa-secret -o jsonpath='{.data.ca\.crt}') && \
TOKEN=$(kubectl get secret gitops-sa-secret -o jsonpath='{.data.token}' | base64 --decode) && \
cat <<EOF > syself-headless-kubeconfig.yaml
apiVersion: v1
kind: Config
clusters:
- name: syself-autopilot
  cluster:
    certificate-authority-data: $CA_CRT
    server: $SERVER
users:
- name: sa-user
  user:
    token: $TOKEN
contexts:
- name: sa-context
  context:
    cluster: syself-autopilot
    user: sa-user
current-context: sa-context
EOF

This will create a syself-headless-kubeconfig.yaml file you can use with kubectl or in CI/CD pipelines:

		$ KUBECONFIG=syself-headless-kubeconfig.yaml kubectl get clusters
Tip

This is also the kubeconfig you give Argo CD when you add the management cluster as a remote destination. See .

Security considerations#

This is a persistent token. Unlike OIDC flows that expire and require reauthentication, a service account token does not expire unless manually revoked.

Treat the token like a password. Anyone with access to this kubeconfig has the same permissions as the service account. Store it securely and avoid committing it to version control.

Prefer OIDC for human users. This headless access method is best suited for automation. For human users, browser-based login remains the safest and most auditable path.

Rotate a compromised token#

If the token leaks, revoke it by deleting the gitops-sa-secret Secret in the management cluster. A fresh token is issued in its place, and you regenerate the kubeconfig with the command above. Any kubeconfig built from the old token stops working, so update your CI secrets with the new one. If the Secret is not reissued, contact Syself support.

Related#

Self-managed GitOps

Deploy Argo CD with Helm and build a GitOps workflow that manages the cluster from Git.

Cluster creation fails

Diagnose why your Syself Autopilot cluster is not coming up, from missing Hetzner secrets and quota limits to stuck machines.