Connect to the cluster

You can access your cluster using the official Kubernetes client, kubectl, and a configuration file containing the authentication token for your cluster.

Requirements

A cluster with the status Running

Hinweis
As long as the cluster is still being provisioned, the configuration file is not available for download.
kubectl installed; see the official installation guide

1. Install kubectl

Check an existing installation:

kubectl version --client

kubectl supports a difference of one minor version in either direction from the cluster version. For a cluster with version 1.33, client versions 1.32 to 1.34 are therefore compatible.

2. Download the configuration file

You have two options:

Tab Overview – In the Configuration section, via Download Config File
Actions menu – Top right of the cluster details view, via Download Config

The file is saved under the name <cluster-name>-kubeconfig.yaml.

Warnung

The configuration file contains an authentication token with extensive privileges on your cluster. Treat it as you would a password: do not commit it to version control and do not share it via unencrypted channels.

Set the file permissions to be restrictive:

chmod 600 /<pfad>/<cluster-name>-kubeconfig.yaml

3. Point `kubectl` to the file

Replace <pfad-zum-verzeichnis> with the file’s location:

kubectl --kubeconfig=/<pfad-zum-verzeichnis>/<cluster-name>-kubeconfig.yaml get nodes

To avoid having to specify the path every time the programme is called, set the environment variable KUBECONFIG:

export KUBECONFIG=/<pfad-zum-verzeichnis>/<cluster-name>-kubeconfig.yaml

For permanent use, add this line to your shell configuration, such as ~/.bashrc or ~/.zshrc.

Alternatively, you can copy the content into the standard file ~/.kube/config if you are managing several clusters in parallel.

4. Check the connection

The following commands confirm that the connection is working:

Command	Purpose
`kubectl config get-contexts`	Lists the cluster name, users and namespaces
`kubectl cluster-info`	Displays the addresses of the control plane and cluster services
`kubectl version`	Displays the client and server versions
`kubectl get nodes`	Lists all nodes in the cluster
`kubectl help`	Displays the available commands

When kubectl get nodes is active, all nodes should have the status Ready:

NAME                    STATUS   ROLES    AGE   VERSION
node-pool-1-abc123      Ready    <none>   5m    v1.33.1
node-pool-1-def456      Ready    <none>   5m    v1.33.1

Managing multiple clusters

If you are using multiple clusters, switch between contexts:

# Verfügbare Kontexte auflisten
kubectl config get-contexts

# Kontext wechseln
kubectl config use-context <kontext-name>

# Standard-Namespace für den aktuellen Kontext setzen
kubectl config set-context --current --namespace=<namespace>

Troubleshooting

Symptom	Possible cause
`The connection to the server ... was refused`	The cluster has not yet been fully provisioned; check the status in the overview
`error: You must be logged in to the server (Unauthorized)`	The configuration file is out of date – download it again
`Unable to connect to the server: dial tcp ... i/o timeout`	Access to the API endpoint is blocked – check your network and firewall configuration
Nodes with status `NotReady`	See Node Remediation
Version discrepancy warning	Your `kubectl` version differs by more than one minor version

Requirements​

1. Install kubectl​

2. Download the configuration file​

3. Point kubectl to the file​

4. Check the connection​

Managing multiple clusters​

Troubleshooting​

Next steps​