Connect to Kubernetes

This page provides instructions on how to connect to a Kubernetes cluster and use kubectl via StrongDM.

Prerequisites

Before you begin, ensure that your StrongDM administrator has granted you access to at least one Kubernetes cluster.

The Connection Process

1. Open the StrongDM Desktop application and log in.
2. Connect to the Kubernetes cluster by either clicking the cluster's display name in the desktop app or running sdm connect <KUBERNETES_CLUSTER_NAME> in the CLI.

Note that it is not necessary to run either the sdm connect or sdm disconnect commands for this resource except in specific instances.

1. Update the kubectl configuration using either the desktop app or the CLI.

   • If using the desktop app, go to the Account menu and select Update kubectl configuration.

The Update kubectl configuration option is displayed if cluster resources are available to you. This option adds StrongDM-specific sections to your existing ~/.kube/config file or creates a new one if it does not yet exist. Note that you need kubectl to be in your PATH before starting the desktop app and/or CLI in order for this option to work.

• If using the CLI and you want to update the config file for all clusters to which you are currently connected through StrongDM, run:

  sdm kubernetes update-config

• If using the CLI and you want to add or update the config file for a single cluster, run the same command but additionally specify the cluster name as a parameter:

  sdm kubernetes update-config <CLUSTER_NAME>

If this command fails, see section Manual Configuration Update.

Once you have updated your kubectl configuration and are connected, you should be able to run kubectl commands directly on the StrongDM-managed cluster.

Example:

$ kubectl get pods
NAME                                     READY     STATUS    RESTARTS   AGE
imprecise-bunny-mysql-6b65b5ff54-wflb9   1/1       Running   0          38d
imprecise-bunny-mysql-test               0/1       Pending   0          17d
redis-master-6b464554c8-9w7k8            1/1       Running   0          34d
shell-demo                               1/1       Running   0          39d

Manual Configuration Update

If the Update kubectl configuration option fails, it is likely because you are using a separate Kubernetes configuration manager. In this case, you can manually update your ~/.kube/config file as follows.

1. For each Kubernetes cluster you wish to configure, record its port as reported in the Admin UI or the CLI after running sdm status.
2. In your config file for each cluster:

   • Add a cluster item:

     - cluster:
       server: http://localhost:port
       name: cluster-name

   • Add a context item:

     - context:
       cluster: sdm-k8s-1
       user: sdm-user
       name: StrongDM Kubernetes 1

   • Add a single user item for the sdm-user name:

     - name: sdm-user
       user: {}

3. Save and exit the editor.

Now you should be able to switch contexts to a StrongDM-managed cluster and connect normally.

Example

The following is an example of a kubectl configuration file with two StrongDM-managed clusters.

apiVersion: v1
clusters:
- cluster:
  server: http://localhost:<port1>
  name: sdm-k8s-1
- cluster:
  server: http://localhost:<port2>
  name: sdm-k8s-2
contexts:
- context:
  cluster: sdm-k8s-1
  user: sdm-user
  name: StrongDM Kubernetes 1
- context:
  cluster: sdm-k8s-2
  user: sdm-user
  name: StrongDM Kubernetes 2
current-context: StrongDM Kubernetes 1
kind: Config
preferences: {}
users:
- name: sdm-user
  user: {}

Troubleshooting

This section provides troubleshooting guidance for kubectl cp, kubectl exec, kubectl attach, kubectl port-forward, and connection reset by peer, on kubectl 1.36 or higher.

Symptom

Running kubectl cp, kubectl exec, kubectl attach, or kubectl port-forward through StrongDM fails with connection reset by peer, often partway through a transfer. Copying multiple files is the most common trigger. The same command succeeds when run against the cluster directly, bypassing StrongDM.

Cause

kubectl 1.30 and later attempt a WebSocket connection for these commands instead of the legacy SPDY protocol. Earlier kubectl versions fell back to SPDY when the WebSocket upgrade failed; on version 1.36 and higher, the upgrade succeeds through StrongDM, so no fallback occurs, and a known issue in StrongDM's WebSocket proxy resets the connection before the transfer finishes.

Workaround

Force kubectl back to SPDY by setting the matching environment variable for the command you are running.

Command	Environment variable
kubectl exec, kubectl attach, kubectl cp	KUBECTL_REMOTE_COMMAND_WEBSOCKETS=false
kubectl port-forward	KUBECTL_PORT_FORWARD_WEBSOCKETS=false

Per command:

KUBECTL_REMOTE_COMMAND_WEBSOCKETS=false kubectl cp <NAMESPACE>/<POD>:/path/to/source ./destination

For the current shell session:

export KUBECTL_REMOTE_COMMAND_WEBSOCKETS=false
export KUBECTL_PORT_FORWARD_WEBSOCKETS=false

To confirm which protocol kubectl negotiated, re-run with -v=7 and check the upgrade request in the output.

This is a temporary workaround, not a permanent configuration. These variables are escape hatches provided by the Kubernetes SPDY-to-WebSocket migration and are expected to be removed once the migration completes. Do not set them in shared shell profiles, CI images, or golden AMIs without a plan to remove them. StrongDM is addressing the underlying proxy issue; remove these variables once a fixed client is released.

For the full list of environment variables StrongDM recognizes, see Environment Variables.

Privilege Levels

When connecting to a Kubernetes cluster, you have the same groups and privileges within the cluster as the credentials that were used to configure the cluster in StrongDM.

If your organization has set up privilege levels, they provide you with the ability to request privilege levels to provide you with additional groups and the associated permissions when you connect to the cluster.

For clusters with privilege levels available, you may select one or more when making an access request via the Admin UI or integrations. If using the CLI to make your access request, you may add a flag to your request command to request privilege levels. When viewing the catalog of StrongDM resources in the CLI (sdm access catalog) you can see the privileges that are available to you for a cluster. When making an access request at the CLI, with sdm access to, you can append a --k8sGroup=foo flag to request a specific privilege level with your request.

Multiple -k8sGroup flags can be added to a request made using the CLI to request multiple privilege levels.