Kubernetes

sequenceDiagram
    participant User
    participant CLI as Infisical CLI
    participant Infisical
    participant Gateway as Infisical Gateway
    participant K8s as Kubernetes API Server

    User->>CLI: Request Kubernetes access
    CLI->>Infisical: Authenticate & request session
    Infisical-->>CLI: Session credentials & Gateway info
    CLI->>CLI: Start local proxy
    CLI->>Gateway: Establish secure tunnel
    User->>CLI: kubectl commands
    CLI->>Gateway: Proxy kubectl requests
    Gateway->>K8s: Forward with SA token
    K8s-->>Gateway: Response
    Gateway-->>CLI: Return response
    CLI-->>User: kubectl output

sequenceDiagram
    participant User
    participant CLI as Infisical CLI
    participant Infisical
    participant Gateway as Infisical Gateway
    participant K8s as Kubernetes API Server

    User->>CLI: Request Kubernetes access
    CLI->>Infisical: Authenticate & request session
    Infisical-->>CLI: Session credentials & Gateway info
    CLI->>CLI: Start local proxy
    CLI->>Gateway: Establish secure tunnel
    Gateway->>Infisical: Fetch session credentials (SA name + namespace)
    User->>CLI: kubectl commands
    CLI->>Gateway: Proxy kubectl requests
    Gateway->>K8s: Forward with own token + Impersonate-User header
    K8s->>K8s: Verify impersonation permission, apply target SA's RBAC
    K8s-->>Gateway: Response
    Gateway-->>CLI: Return response
    CLI-->>User: kubectl output

<Note>
  **SSL Verification**: You may need to disable SSL verification if your Kubernetes API server uses a self-signed certificate or an in-cluster CA. For Gateway auth with `https://kubernetes.default.svc.cluster.local`, disable SSL verification here — the Gateway will use strict TLS with the in-cluster CA certificate during sessions.
</Note>

### Create a Service Account

<Steps>
  <Step title="Create the Service Account YAML">
    Create a file named `sa.yaml` with the following content:

    ```yaml sa.yaml
    apiVersion: v1
    kind: ServiceAccount
    metadata:
      name: infisical-pam-sa
      namespace: kube-system
    ---
    # Bind the ServiceAccount to the desired ClusterRole
    # This example uses cluster-admin - adjust based on your needs
    apiVersion: rbac.authorization.k8s.io/v1
    kind: ClusterRoleBinding
    metadata:
      name: infisical-pam-binding
    subjects:
      - kind: ServiceAccount
        name: infisical-pam-sa
        namespace: kube-system
    roleRef:
      kind: ClusterRole
      name: cluster-admin  # Change this to a more restrictive role as needed
      apiGroup: rbac.authorization.k8s.io
    ---
    # Create a static, non-expiring token for the ServiceAccount
    apiVersion: v1
    kind: Secret
    metadata:
      name: infisical-pam-sa-token
      namespace: kube-system
      annotations:
        kubernetes.io/service-account.name: infisical-pam-sa
    type: kubernetes.io/service-account-token
    ```

    <Warning>
      **Security Best Practice**: The example above uses `cluster-admin` for simplicity. In production environments, you should create custom ClusterRoles or Roles with the minimum permissions required for each use case.
    </Warning>
  </Step>

  <Step title="Apply the Service Account">
    Apply the configuration to your cluster:

    ```bash
    kubectl apply -f sa.yaml
    ```

    This creates:
    - A ServiceAccount named `infisical-pam-sa` in the `kube-system` namespace
    - A ClusterRoleBinding that grants the service account its permissions
    - A Secret containing a static, non-expiring token for the service account
  </Step>

  <Step title="Retrieve the Service Account Token">
    Get the service account token that you'll use when creating the PAM account:

    ```bash
    kubectl -n kube-system get secret infisical-pam-sa-token -o jsonpath='{.data.token}' | base64 -d
    ```

    Copy this token - you'll need it in the next step.
  </Step>
</Steps>

<Info>
  When creating the resource in the step above, use `https://kubernetes.default.svc.cluster.local` as the URL and **disable SSL verification**. The Gateway handles TLS with the correct in-cluster CA automatically during sessions.
</Info>

### Set Up Impersonation Permissions

The Gateway's pod service account needs a ClusterRole that allows it to impersonate the target service accounts.

<Steps>
  <Step title="Create the Impersonation ClusterRole">
    Create a file named `gateway-impersonation.yaml`:

    ```yaml gateway-impersonation.yaml
    apiVersion: rbac.authorization.k8s.io/v1
    kind: ClusterRole
    metadata:
      name: infisical-gateway-impersonator
    rules:
      - apiGroups: [""]
        resources: ["serviceaccounts"]
        verbs: ["impersonate"]
        resourceNames:
          - "deploy-bot"       # Add each SA the gateway should be able to impersonate
          - "ci-runner"
      - apiGroups: [""]
        resources: ["groups"]
        verbs: ["impersonate"]
        resourceNames:
          - "system:serviceaccounts"
          - "system:serviceaccounts:default"  # Match the namespace(s) of the target SAs
          - "system:authenticated"
    ---
    apiVersion: rbac.authorization.k8s.io/v1
    kind: ClusterRoleBinding
    metadata:
      name: infisical-gateway-impersonator-binding
    subjects:
      - kind: ServiceAccount
        name: <gateway-pod-service-account>  # The Gateway pod's own service account
        namespace: <gateway-namespace>
    roleRef:
      kind: ClusterRole
      name: infisical-gateway-impersonator
      apiGroup: rbac.authorization.k8s.io
    ```

    <Note>
      **Scoped by `resourceNames`**: The `resourceNames` field limits which service accounts the Gateway can impersonate. If someone creates a PAM account pointing at a service account not in this list, the session will fail with a 403 from Kubernetes. This is how you control which accounts are accessible through Infisical.
    </Note>
  </Step>

  <Step title="Apply the ClusterRole">
    ```bash
    kubectl apply -f gateway-impersonation.yaml
    ```
  </Step>

  <Step title="Ensure target service accounts exist">
    The service accounts you want to impersonate must already exist in the cluster with their own RBAC permissions. For example:

    ```yaml
    apiVersion: v1
    kind: ServiceAccount
    metadata:
      name: deploy-bot
      namespace: default
    ---
    apiVersion: rbac.authorization.k8s.io/v1
    kind: ClusterRoleBinding
    metadata:
      name: deploy-bot-binding
    subjects:
      - kind: ServiceAccount
        name: deploy-bot
        namespace: default
    roleRef:
      kind: ClusterRole
      name: view  # Or whatever permissions this SA should have
      apiGroup: rbac.authorization.k8s.io
    ```

    The target SA's own RBAC rules determine what the user can do during the session.
  </Step>
</Steps>

- **Service Account Token** — paste the service account token you retrieved earlier.
- **Gateway** — enter the **Service Account Name** and **Namespace** of the Kubernetes service account you want to impersonate. No token is needed.

The CLI will:
1. Authenticate with Infisical
2. Establish a secure connection through the Gateway
3. Start a local proxy on your machine
4. Configure kubectl to use the proxy

```bash
kubectl get pods
kubectl get namespaces
kubectl describe deployment my-app
```

All commands are routed securely through the Infisical Gateway to your cluster.

You can view session logs in the **Sessions** page of your PAM project.