Add a Kubernetes (Pod Identity) Cluster
Last modified on April 30, 2025
This guide describes how to manage access to a Kubernetes (Pod Identity) cluster via the StrongDM Admin UI. This process involves creating and configuring a new cluster in the Admin UI and checking the connection to your Kubernetes API server. If you’d like to add a Kubernetes cluster to StrongDM by installing a node (relay, gateway, or proxy cluster) within your Kubernetes cluster and auto-registering it (with no manual setup within StrongDM), see the Helm chart on GitHub.
The Kubernetes (Pod Identity) resource type is a unique resource type that can be added to and accessed using StrongDM without exposing the underlying cluster’s private keys outside the cluster. This resource type is designed to work with clusters that already have a StrongDM relay running inside a pod on the cluster.
Kubectl 1.30 or higher defaults to using websockets, which the StrongDM client did not support before version 45.35.0. You can remedy this by taking one of the following actions:
- Update your client to version 45.35.0 or greater.
- Set the environment variable
KUBECTL_REMOTE_COMMAND_WEBSOCKETS=falseto restore the previous behavior in your kubectl.
Resource Setup
The Kubernetes (Pod Identity) resource type requires some preliminary setup on the cluster. Pod Identity works by running a StrongDM relay in a pod within your cluster. When the relay is set up within your cluster using the StrongDM relay Helm chart, it registers itself with StrongDM as a relay. Once the relay is registered, it can access the hosting cluster directly.
Note that because the relay sits within the cluster, from any relay’s perspective, the address of any hosting cluster is always kubernetes.default.svc. In order for StrongDM to differentiate between different Pod Identity clusters, the CA certificate of the cluster is required.
To set up your cluster, follow these steps:
- Use the StrongDM relay Helm chart to install a relay in a pod within your cluster.
- Verify the relay’s registration with StrongDM using the Admin UI (Networking > Relays) or the CLI (
sdm admin nodes list). - Create a Pod Identity cluster resource using the Admin UI (Resources > Clusters) or the CLI (
sdm admin cluster add k8spodidentity), making sure to provide the cluster’s CA certificate as an argument. - Grant access to the new resource to your StrongDM account via a role or temporary access grant and test access. Doing so grants you the same level of Kubernetes access as the pod that the relay sits in.
Managing Your Kubernetes Cluster in the StrongDM Admin UI
You can manage your cluster in the Admin UI. Log in to the StrongDM Admin UI and go to Infrastructure > Clusters. Here you can see a list of all of your clusters.
The Admin UI updates and shows your new cluster in a green or yellow state. Green indicates a successful connection. If the state is yellow, click the pencil icon to the right of the server to reopen the Connection Details screen. Then click Diagnostics to determine where the connection is failing.
You can select your Kubernetes (Pod Identity) cluster to edit its configuration.
Resource properties
Configuration properties are visible when you add a Cluster Type or when you click to view the cluster’s settings. The following table describes the settings available for your Kubernetes cluster.
| Property | Requirement | Description |
|---|---|---|
| Display Name | Required | Meaningful name to display the resource throughout StrongDM; exclude special characters like quotes (") or angle brackets (< or >) |
| Cluster Type | Required | Select Kubernetes (Pod Identity) |
| Port Override | Read only | Automatically generated with a value between 1024 to 59999 as long as that port is not used by another resource; preferred port can be modified later under Settings > Port Overrides; after specifying the port override number, you must also update the kubectl configuration, which you can learn more about in section Port Overrides |
| Secret Store | Optional | Credential store location; defaults to Strong Vault; to learn more, see the Secret Store section |
| Server CA | Required | Pasted server certificate (plaintext or Base64-encoded), or imported PEM file; you can either generate the server certificate on the API server or get it in Base64 format from your existing Kubernetes configuration (kubeconfig) file |
| Healthcheck Namespace | Optional | If enabled for your organization, the namespace used for the resource healthcheck; defaults to default if empty; supplied credentials must have the rights to perform one of the following kubectl commands in the specified namespace: get pods, get deployments, or describe namespace |
| Resource Tags | Optional | Resource tags consisting of key-value pairs <KEY>=<VALUE> (for example, env=dev) |
Display name
Some Kubernetes management interfaces, such as Visual Studio Code, do not function properly with cluster names containing spaces. If you run into problems, please choose a Display Name without spaces.
Client credentials
When your users connect to this cluster via StrongDM, they initially have exactly the same rights to the cluster as the pod that the relay sits in. Be sure to consider this prior to setup.
Server CA
How to get the Server CA from your kubeconfig file:
- Open the CLI and type
cat ~/.kube/configto view the contents of the file. - In the file, under
- cluster, copy thecertificate-authority-datavalue. That is the server certificate in Base64 encoding.
- cluster:
certificate-authority-data: ... SERVER CERT BASE64 ...
Secret Store
By default, server credentials are stored in StrongDM. Alternatively, save these credentials in a secrets management tool.
Non-StrongDM options appear in the Secret Store dropdown if they are created under Settings Credential Management. When you select another Secret Store type, it displays its unique properties. For more details, see Configure Secret Store Integrations.