Last chance to meet us at TailscaleUp!Grab your ticket ->

Access a Kubernetes cluster using Tailscale PAM

Last validated:
Tailscale PAM is currently in beta.

Tailscale PAM gives users identity-based access to Kubernetes clusters without requiring them to manage cluster credentials or maintain and distribute kubeconfig files.

Users use their Tailscale identity to access the Kubernetes cluster, and the PAM connector communicates with the Kubernetes API on their behalf. You can use Tailscale PAM grants in your tailnet access policy to control what each user or group is allowed to do, including which Kubernetes API operations, namespaces, and resources they can access.

Users can keep working with the Kubernetes tools they already use, including kubectl, Lens, K9s, and other Kubernetes clients. They can also use the Tailscale browser client to interact with the cluster directly from their browser.

Supported Kubernetes service types

Tailscale PAM supports a few different ways to connect to Kubernetes. Choose the service type that matches where your connector runs and how it reaches the cluster:

  • Kubernetes - Standard: Use this for a Kubernetes cluster that the connector can already reach and authenticate to. This works with self-managed Kubernetes as well as managed Kubernetes services.
  • Kubernetes - AWS EKS within cluster: Use this when the PAM connector runs inside the EKS cluster you want to access. If the connector runs inside the cluster, it can use its in-cluster configuration and service account.
  • Kubernetes - AWS EKS outside cluster: Use this when the PAM connector runs outside the EKS cluster and uses AWS credentials to discover and authenticate to it. If it runs outside the cluster, it needs a network path to the Kubernetes API and credentials that the cluster accepts.

Prerequisites

Before you begin, make sure you have:

  • A Tailscale PAM connector that is installed and online.
  • A connector that can communicate with the Kubernetes API for the cluster.
  • A Kubernetes identity for the connector with the permissions required for the operations users will do.
  • Tailscale installed and signed in on the device you'll use to connect, if you plan to use kubectl or another local Kubernetes client.
  • A Tailscale PAM grant that gives users access to the Kubernetes PAM service.

For an EKS cluster with the connector running outside the cluster, the connector also needs an AWS identity that can discover and authenticate to the EKS cluster.

Configure Kubernetes permissions for the connector

The PAM connector is what communicates with the Kubernetes API, so it needs enough Kubernetes permissions to do the operations you want users to be able to do.

Tailscale PAM grants sit on top of those permissions. They can narrow what a user or group is allowed to do, but they can't give the connector permissions that Kubernetes itself hasn't granted it.

For example, if you want Tailscale PAM to handle the per-user authorization, you can give the connector a broad ClusterRole:

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: tailscale-pam-connector
rules:
  - apiGroups: ["*"]
    resources: ["*"]
    verbs: ["*"]

Bind the role to the Kubernetes identity used by your Tailscale PAM connector.

This gives the connector broad access to the cluster, while your Tailscale PAM grants determine what individual users and groups can do through the PAM service.

You don't have to give the connector full cluster access. If users only need access to a smaller set of Kubernetes resources, you can give the connector a more restrictive Kubernetes role instead.

Use Kubernetes impersonation

You can also enable impersonation for the Kubernetes PAM service.

Without impersonation, Kubernetes sees requests as coming from the connector's Kubernetes identity, and Tailscale PAM grants provide the per-user authorization.

With impersonation enabled, Tailscale PAM sends Kubernetes impersonation headers such as Impersonate-User and Impersonate-Group. This lets Kubernetes apply its own role-based access control (RBAC) rules to the impersonated user or groups, in addition to the access controls you define with Tailscale PAM.

This is useful if you already use Kubernetes RBAC and want to keep those permissions as part of the authorization decision.

The connector's Kubernetes identity needs permission to impersonate users and groups. For example:

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: tailscale-pam-impersonator
rules:
  - apiGroups: [""]
    resources:
      - users
      - groups
    verbs:
      - impersonate

Bind this ClusterRole to the Kubernetes identity used by your PAM connector. You can then use your existing Kubernetes Role, ClusterRole, RoleBinding, and ClusterRoleBinding resources to control what the impersonated users and groups are allowed to do.

Create a Kubernetes PAM service

To create the Kubernetes PAM service:

  1. Open the Services page of the admin console.

  2. Select Add service.

  3. Select PAM service.

  4. Choose the appropriate Kubernetes service type:

    • Kubernetes - Standard
    • Kubernetes - AWS EKS within cluster
    • Kubernetes - AWS EKS outside cluster

  5. Select Continue.

  6. Enter a name for the service.

  7. (Optional) Enter a description.

  8. Choose whether to enable session recording.

  9. (Optional) Enable Enable impersonation if you want Tailscale PAM to use Kubernetes impersonation.

  10. From Connect via, select one or more PAM connectors.

    Every connector selected for the service must be able to reach and authenticate to the Kubernetes API.

  11. Select Continue.

  12. How you configure the Kubernetes target depends on the Kubernetes service type you selected.

    Kubernetes - StandardKubernetes - AWS EKS within clusterKubernetes - AWS EKS outside cluster

    Use this option when the connector already has Kubernetes configuration for the target cluster.

    For a connector using its current Kubernetes context, configure values for the following:

    • Configuration source: Select System's kubeconfig with current context.
    • Target selection strategy: Select Kubernetes context.
    • Authentication strategy: Select Kubernetes context.

    This tells the connector to use its existing Kubernetes configuration to determine the API server and upstream authentication credentials.

  13. When you're finished configuring the Kubernetes target, select Save.

The Kubernetes service is ready to proxy requests to the cluster through the connector.

Grant access to the Kubernetes service

Before users can connect, create a Tailscale PAM grant that gives them access to the Kubernetes service.

For example, an unrestricted Kubernetes permission looks like:

{
  "src": ["*"],
  "dst": ["*"],
  "ip": ["*"],
  "app": {
    "tailscale.com/cap/pam": [
      {
        "version": "v1",
        "permissions": {
          "kubernetes": {}
        }
      }
    ]
  }
}

This gives the user access to the Kubernetes operations available through the service. The connector still can't do anything that its Kubernetes identity isn't allowed to do.

This is a useful grant for getting started. In production, restrict src and dst so the grant applies only to the users, groups, devices, and Kubernetes services that need it.

For information about editing grants, refer to Edit access control policies in your tailnet policy file.

You can use the visual policy editor to manage your tailnet policy file. Refer to the visual editor reference for guidance on using the visual editor.

Control what users can do in Kubernetes

You don't have to give users unrestricted Kubernetes access. Tailscale PAM grants can control operations based on:

  • Kubernetes verbs, such as get, list, create, or delete.
  • Namespaces.
  • Resource types, such as pods, deployments, and services.
  • Resource names.
  • Kubernetes API groups.

When you add Kubernetes rules, a request must match at least one rule to be allowed.

For example, the following grant limits access to the staging namespace:

{
  "src": ["*"],
  "dst": ["*"],
  "ip": ["*"],
  "app": {
    "tailscale.com/cap/pam": [
      {
        "version": "v1",
        "permissions": {
          "kubernetes": {
            "rules": [
              {
                "api_groups": ["*"],
                "namespaces": ["staging"],
                "verbs": ["*"],
                "resources": ["*"],
                "resource_names": ["*"]
              }
            ]
          }
        }
      }
    ]
  }
}

This permits Kubernetes operations only when they match the staging namespace rule.

You can make this much more specific. For example, you could let developers get, list, and watch pods and deployments in staging, while preventing them from creating or deleting resources.

Tailscale PAM and Kubernetes RBAC work together. The PAM grant must allow the request, and the connector or impersonated Kubernetes identity must also have permission to do it.

For more Kubernetes grant examples and information about fine-grained Kubernetes access controls, refer to Control access to Tailscale PAM services.

Connect to the Kubernetes cluster

Once a user has access, they can keep working with the Kubernetes tools they already use or connect directly from their browser.

  1. Open the Tailscale client.
  2. Select Services.
  3. Select the Kubernetes service.
  4. Choose kubectl or Web client.

Use kubectl and other Kubernetes tools

Select kubectl to add the Kubernetes service to your local kubeconfig.

Tailscale automatically configures the cluster for you. You can also choose to make it your current Kubernetes context.

Once it's configured, use kubectl as you normally would:

kubectl get pods

For example:

kubectl get deployments -n staging

Because the cluster is added to your kubeconfig, other Kubernetes tools that usekubeconfig, such as Lens or K9s, can use the same configuration.

You don't need separate cluster credentials. Your requests are authorized using your Tailscale identity and the Kubernetes permissions in your PAM grants.

Connect from the browser

Open the Tailscale PAM browser client to interact with the Kubernetes cluster directly from your browser.

You don't need to install kubectl or configure a local kubeconfig.

The same PAM grants apply whether you connect with kubectl or the web client, so users can only do the Kubernetes operations their access policy permits.

Review Kubernetes sessions

Tailscale PAM gives you a central place to review who accessed your Kubernetes services and what happened during each session.

Open the Sessions page of the admin console, and select a session that you want to inspect. From there, you can review details such as the Tailscale identity that connected, the originating device, the connection time, and the Kubernetes service that was accessed.

When session recording is enabled, Tailscale PAM also captures the activity that took place during the session.

For Kubernetes API activity, you can review each API call along with its HTTP response code. This gives you a detailed record of how the user interacted with the cluster and how Kubernetes responded.

Interactive activity is recorded as well. For example, if a user starts an interactive kubectl exec session in a pod, you can replay the recorded session and review what happened inside the container.

Together, the session details, Kubernetes API activity, and interactive session recordings give you a clear record of:

  • Who accessed the cluster.
  • What they did.
  • What Kubernetes returned.

Troubleshooting

If you can't connect to a Kubernetes service, start by checking that the PAM connector is online and can reach the Kubernetes API.

Then check that the connector can authenticate to the cluster and that its Kubernetes identity has permission to do the operation you're trying to run.

Also make sure your Tailscale PAM grant permits access to the service. If you've added Kubernetes rules, check that the requested verb, namespace, resource, resource name, and API group match one of those rules.

If impersonation is enabled, verify that:

  • The connector's Kubernetes identity can impersonate the required users or groups.
  • The impersonated identity has the appropriate Kubernetes RoleBinding or ClusterRoleBinding.
  • Kubernetes RBAC permits the requested action.

If you use the AWS EKS outside cluster option, also verify that:

  • The configured AWS credentials are valid.
  • The connector can list and describe the EKS cluster.
  • The connector's AWS IAM identity is authorized to access the EKS Kubernetes API.
  • The connector can reach the EKS API endpoint.

If none of the troubleshooting steps mentioned above resolve your issue, review the connector logs and the details for the failed session in the Tailscale PAM session logs. These can help you tell whether the request was blocked by Tailscale PAM, Kubernetes RBAC, impersonation, authentication, or connectivity.