Add a Kubernetes (Pod Identity) Cluster
Last modified on May 16, 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. Pod Identity works by running a StrongDM node in a pod within your cluster. Once the node and the cluster are registered with StrongDM, whether automatically by using the StrongDM node Helm chart or manually (such as with the Admin UI), the node can then access the hosting cluster directly.
Note that because the node sits within the cluster, from any node’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 must be provided.
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=false
to restore the previous behavior in your kubectl.
Set up With the Helm Chart
The preferred way to set up a Kubernetes (Pod Identity) resource in StrongDM is to use the Helm chart to automatically create and register a StrongDM node within your cluster, and then in turn, to automatically register the cluster as a resource with StrongDM. To set up your node and register your cluster using the Helm chart, follow these steps:
- Use the StrongDM relay Helm chart to install a node in a pod within your cluster.
- Verify the node’s registration with StrongDM using the Admin UI by going to Networking > Relays or using the CLI by running
sdm admin nodes list
. This step is optional, but suggested while testing this configuration. - The Kubernetes (Pod Identity) resource in StrongDM should also be created by the Helm chart. You can verify this resource has been registered using the Admin UI by going to Resources > Clusters or using the CLI by running
sdm admin clusters list
. Again, verifying this manually is just for the purposes of this test. - 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 node sits in. This step can be automated by using roles that have dynamic access rules that can give the users in a role access to newly created resources based on their type or tag.
Set up With the Admin UI
To set up your cluster using the Admin UI, follow these steps:
- Install a StrongDM node (a relay or gateway, or a proxy cluster within a pod in the Kubernetes cluster and register it with StrongDM.
- Verify the node’s registration with StrongDM using the Admin UI by going to Networking > Relays or using the CLI by running
sdm admin nodes list
to ensure that it is reachable and healthy. This step is optional, but suggested while testing this configuration. - Create the Kubernetes (Pod Identity) resource in the StrongDM Admin UI by going to Resources > Clusters or using the CLI by running
sdm admin clusters add
, being sure to provide the Server CA as an argument, as that is how the node and the cluster will be connected. - 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 node sits in. This step can be automated by using roles that have dynamic access rules that can give the users in a role access to newly created resources based on their type or tag.
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 node 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/config
to view the contents of the file. - In the file, under
- cluster
, copy thecertificate-authority-data
value. 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.