Access a cluster

This tutorial guides you through the steps required to retrieve credentials of a Kubernetes cluster which are needed to actually access and work with it.

Download the admin kubeconfig

Once you created a cluster, you can connect to it by retrieving its credentials. In Kubernetes, cluster credentials are usually stored in a kubeconfig file. To download the kubeconfig file:

Prerequisites

Before you begin, you need the following:

• Installed STACKIT CLI.
• An existing STACKIT Kubernetes Engine Cluster.
• A STACKIT user account with ske.cluster.kubeconfig.create permission in the project. It is part of the owner, editor, ske.admin and ske.editor roles.

STACKIT Portal

Steps

1. Go to STACKIT Portal.
2. Select your project.
3. Click on Runtime > Kubernetes Engine.
4. Download the kubeconfig by clicking on the three dots on the right side in the cluster panel, click Kubeconfig, select STACKIT CLI and click Download.

STACKIT CLI

Steps

1. Login with the STACKIT CLI.

   > stackit auth login
   Successfully logged into STACKIT CLI.

2. Download the kubeconfig for your cluster.

   # Replace value after PROJECT_ID and CLUSTER_NAME with the actual values of your cluster
   > PROJECT_ID=12345678-ffff-abcd-ffff-12345678
   > CLUSTER_NAME=cl-12345678
   > stackit ske kubeconfig create --project-id $PROJECT_ID $CLUSTER_NAME --login
   Are you sure you want to update your kubeconfig for SKE cluster "cl-12345678"? This will update your kubeconfig file.
   If it the kubeconfig file doesn't exists, it will create a new one. [y/N] y
   
   Set kubectl context to cl-12345678 with: kubectl config use-context cl-12345678
   Updated kubeconfig file for cluster cl-12345678 in "/home/username/.kube/config"

The downloaded kubeconfig does not contain secrets. Instead it uses the STACKIT CLI to request short-lived credentials on demand.

The kubeconfig always grants full administrative permissions in the cluster. Refer to Section “Provide cluster access to other users” on how to assign fine-grained permissions to users.

Revocation of admin kubeconfigs is only possible using the steps described in the Rotating Credentials Section. This process also invalidates all other admin kubeconfigs and Kubernetes Service Account Tokens.

Provide (limited) cluster access to users

Administrative privileges in a cluster should be used sparingly. Instead it is recommended to grant only the necessary permissions to users. This is possible by using the STACKIT IDP integration for STACKIT Kubernetes Engine clusters. It provides following benefits:

• User accounts are centrally managed in the STACKIT IDP.
• Fine-granular permission assignment using Kubernetes RBAC.
• Permissions can be revoked without rotating and invalidating all cluster credentials.
• Access to resources in the cluster can be granted independently from granting permissions to modify the cluster configuration itself.
• STACKIT IAM provides roles that only allow users to download a STACKIT IDP kubeconfig, but not modify the cluster configuration.

To use the STACKIT IDP integration, you first have to enable it for a cluster. Then use an admin kubeconfig to grant permissions to the user. Finally, download a STACKIT IDP kubeconfig to login to a cluster with user privileges.

Enable IDP integration in cluster

You first have to enable the STACKIT IDP integration for your cluster:

STACKIT CLI

Prerequisites

Before you begin, you need the following:

• A Unix terminal with installed STACKIT CLI with at least version 0.56.0 and jq.
• An existing STACKIT Kubernetes Engine Cluster.
• A STACKIT user account with ske.cluster.create and ske.cluster.kubeconfig.create permission in the project.

Steps

1. Login with the STACKIT CLI.

   > stackit auth login
   Successfully logged into STACKIT CLI.

2. Enable the STACKIT IDP integration for your cluster.

   # Replace value after PROJECT_ID and CLUSTER_NAME with the actual values of your cluster
   > PROJECT_ID=12345678-ffff-abcd-ffff-12345678
   > CLUSTER_NAME=cl-12345678
   > stackit ske cluster generate-payload --project-id $PROJECT_ID --cluster-name $CLUSTER_NAME --output-format json | jq ".access.idp.enabled = true | .access.idp.type = \"stackit\"" > config.json
   > stackit ske cluster update --project-id $PROJECT_ID $CLUSTER_NAME --payload "@config.json"
   Are you sure you want to update cluster "cl-12345678"? [y/N] y
   Updating cluster ✓
   Updated cluster "cl-12345678"

Assign permissions to users in cluster

When authenticating to a cluster using the STACKIT IDP, users are by default only granted the permissions of the system:authenticated group in Kubernetes. This group only allows querying the Kubernetes version and available resource types in the cluster. Any further access must be explicitly granted to the user using Kubernetes RBAC within the cluster.

STACKIT CLI

Prerequisites

Before you begin, you need the following:

• A Linux terminal with installed STACKIT CLI with at least version 0.56.0 and kubectl.
• The cluster from above.
• A STACKIT user account with ske.cluster.kubeconfig.create permission in the project.

Steps

1. Download the admin kubeconfig for your cluster.

   > stackit ske kubeconfig create --project-id $PROJECT_ID $CLUSTER_NAME --login --filepath kubeconfig-admin
   Are you sure you want to update your kubeconfig for SKE cluster "cl-12345678"? This will update your kubeconfig file.
   If it the kubeconfig file doesn't exists, it will create a new one. [y/N] y
   
   Set kubectl context to cl-12345678 with: kubectl config use-context cl-12345678
   Updated kubeconfig file for cluster cl-12345678 in "kubeconfig-admin"

2. Use kubectl to create a RoleBinding for the user.

   You need the email address of the user to grant permissions to. See the section below on how a user can inspect their identity and permissions inside the cluster.

   The following grants view permissions to all resources in the default namespace to the user with email user@example.com. Note that configuring the permissions requires usage of an admin kubeconfig. Refer to the Kubernetes RBAC documentation for details on the permissions themselves.

   > USER=user@example.com
   > kubectl --kubeconfig kubeconfig-admin create rolebinding user-view --namespace default --clusterrole view --user $USER
   rolebinding.rbac.authorization.k8s.io/user-view created

All users in the cluster’s STACKIT Organization that have access to a STACKIT IDP kubeconfig can authenticate to the cluster. These users are only assigned the default permissions of the system:authenticated group.

To prevent unintentionally granting permissions to all users in your organization, binding permissions to the group system:authenticated is blocked when the STACKIT IDP integration is enabled.

Login to cluster using STACKIT IDP

Now, download a kubeconfig to authenticate using the STACKIT IDP. This kubeconfig only grants the permissions that have been explicitly granted to the user above.

STACKIT CLI

Prerequisites

Before you begin, you need the following:

• A Linux terminal with installed STACKIT CLI with at least version 0.56.0 and kubectl.
• A STACKIT Kubernetes Engine Cluster with the configuration from above.
• A STACKIT user account with ske.cluster.kubeconfig.idp.create permission in the project.

Steps

1. Download the STACKIT IDP kubeconfig

   > stackit ske kubeconfig create --project-id $PROJECT_ID $CLUSTER_NAME --idp --filepath kubeconfig-idp
   Are you sure you want to update your kubeconfig for SKE cluster "cl-12345678"? This will update your kubeconfig file.
   If the kubeconfig file does not exists, it will create a new one. [y/N] y
   
   Set kubectl context to cl-12345678 with: kubectl config use-context cl-12345678
   Updated kubeconfig file for cluster cl-12345678 in "kubeconfig-idp"

2. Check your identity in the cluster

   > kubectl --kubeconfig kubeconfig-idp auth whoami
   ATTRIBUTE   VALUE
   Username    user@example.com
   UID         23456789-ffff-abcd-ffff-23456789
   Groups      [system:authenticated]

3. Check your permissions in the cluster

   > kubectl --kubeconfig kubeconfig-idp auth can-i --list
   Resources                                       Non-Resource URLs   Resource Names   Verbs
   selfsubjectreviews.authentication.k8s.io        []                  []               [create]
   selfsubjectaccessreviews.authorization.k8s.io   []                  []               [create]
   selfsubjectrulesreviews.authorization.k8s.io    []                  []               [create]
   [...]
   pods/log                                        []                  []               [get list watch]
   pods/status                                     []                  []               [get list watch]
   pods                                            []                  []               [get list watch]
   [...]
                                                   [/api/*]            []               [get]
                                                   [/api]              []               [get]
                                                   [/apis/*]           []               [get]
                                                   [/apis]             []               [get]
                                                   [/healthz]          []               [get]
                                                   [/healthz]          []               [get]
                                                   [/livez]            []               [get]
                                                   [/livez]            []               [get]
                                                   [/openapi/*]        []               [get]
                                                   [/openapi]          []               [get]
                                                   [/readyz]           []               [get]
                                                   [/readyz]           []               [get]
                                                   [/version/]         []               [get]
                                                   [/version/]         []               [get]
                                                   [/version]          []               [get]
                                                   [/version]          []               [get]

The permission ske.cluster.kubeconfig.idp.create only controls who can download a STACKIT IDP kubeconfig. All users with access to the cluster’s organization can use it to authenticate to a cluster.

The kubeconfig itself does not contain secrets and can be shared with other users in the same organization.

Download a static admin kubeconfig

In case you are unable to use the STACKIT CLI or need a static kubeconfig with extended validity, you can download such a kubeconfig file as follows:

STACKIT Portal

Prerequisites

Before you begin, you need the following:

• An existing STACKIT Kubernetes Engine Cluster.
• A STACKIT user account with ske.cluster.kubeconfig.create permission in the project.

Steps

1. Go to STACKIT Portal
2. Select your project
3. Click on Runtime > Kubernetes Engine
4. Download the kubeconfig by clicking on the three dots on the right side in the cluster panel, click Kubeconfig, select Kubeconfig, enter the required expiration and click Download.

STACKIT CLI

Prerequisites

Before you begin, you need the following:

• Installed STACKIT CLI.
• An existing STACKIT Kubernetes Engine Cluster.
• A STACKIT user account with ske.cluster.kubeconfig.create permission in the project.

Steps

1. Login with the STACKIT CLI.

   > stackit auth login
   Successfully logged into STACKIT CLI.

2. Download the kubeconfig for your cluster

   # Replace value after PROJECT_ID and CLUSTER_NAME with the actual values of your cluster
   > PROJECT_ID=12345678-ffff-abcd-ffff-12345678
   > CLUSTER_NAME=cl-12345678
   > stackit ske kubeconfig create --project-id $PROJECT_ID $CLUSTER_NAME --expiration 60m
   Are you sure you want to update your kubeconfig for SKE cluster "cl-12345678"? This will update your kubeconfig file.
   If it the kubeconfig file doesn't exists, it will create a new one. [y/N] y
   
   Set kubectl context to cl-12345678 with: kubectl config use-context cl-12345678
   Updated kubeconfig file for cluster cl-12345678 in "/home/username/.kube/config"

The requested kubeconfig can have a maximum expiration of 180 days. After it has expired you have to download a new one.

The kubeconfig file contains secrets and should be treated accordingly. It includes the email address of your STACKIT user account and must not be shared with others.

Revocation of admin kubeconfigs is only possible using the steps described in the Rotating Credentials Section. This process also invalidates all other admin kubeconfigs and Kubernetes Service Account Tokens.

Provide permissions for cluster operations to other users

All users of a STACKIT project who have one of the owner, editor, ske.admin or ske.editor roles are allowed to run all available cluster operations from the context menu. The only exception is that ske.editor does not permit deleting cluster. This means every member with theses roles in a project has the right to access the cluster with the kubeconfig (which provides admin access for the whole cluster) and also delete it. For information on how to add new users to your project please have a look at these instructions.

To allow a user to only view the cluster configuration and download a STACKIT IDP kubeconfig assign one of the roles reader or ske.reader to a user.

Rotate cluster credentials

To revoke all admin kubeconfigs for a cluster, you have the option to start a cluster credential rotation. This will invalidate all credentials (kubeconfig files) that are currently in use for your cluster and create new credentials.

For a successful rotation:

1. Go to STACKIT Portal.
2. Select your project.
3. Click on Runtime > Kubernetes Engine.
4. Trigger the rotation by opening the context menu of the cluster and click Start credentials rotation. The cluster will now change its state to Reconciling. Wait until the cluster’s state is Healthy again.
5. Download new kubeconfigs from the context menu.
6. Complete the rotation by clicking Complete credentials rotation. This will invalidate old admin kubeconfigs.

We recommend that you rotate your credentials regularly to increase your cluster’s security. Refer to How to rotate credentials for an in-depth description of the credentials rotation.

Use kubectl to interact with you cluster

To interact with you cluster

1. Make sure to download and install kubectl.
2. Place the previously downloaded kubeconfig in the path <Home>/.kube/config
   • for windows %USERPROFILE%/.kube/config (if you are using PowerShell, it also recognizes ~/.kube/config).
   • for linux/mac ~/.kube/config.
3. Now run kubectl get nodes and you should see the nodes running in your cluster.