# kubectl Access

> Source: https://parallelworks.com/docs/kubernetes/kubectl-access

# kubectl Access

Use the PW CLI to authenticate with Kubernetes clusters managed by Parallel Works. The CLI handles kubeconfig generation, certificate management, and OIDC token-based authentication so you can use `kubectl` against your clusters without manual configuration.

## Prerequisites

- The [PW CLI](/docs/cli/pw) installed and configured
- `kubectl` installed on your local machine
- Access to at least one Kubernetes cluster in your organization

## Listing Available Clusters

To see which Kubernetes clusters you have access to, run:

```bash
pw kube ls
```

This lists all clusters available in your organization. You can control the output format:

```bash
# Output as JSON
pw kube ls -o json

# Output as a table (shows name, total vCPUs, total memory)
pw kube ls -o table
```

:::tip Quick Overview
Use `pw kube ls -o table` for a quick overview of cluster capacity.
:::

## Authenticating with a Cluster

The `pw kube auth` command configures your local kubeconfig with everything needed to connect to a cluster:

```bash
pw kube auth <cluster-name>
```

For example, to set up access to a cluster named **demo**:

```bash
pw kube auth demo
```

This command performs the following steps automatically:

1. Retrieves the cluster's CA certificate and API server endpoint from the platform
2. Adds or updates a cluster entry in your kubeconfig with the CA certificate embedded
3. Configures user credentials using the OIDC exec-credential plugin (calls `pw kube token` automatically when `kubectl` needs a token)
4. Creates a context named `pw#<cluster-name>` and switches to it

After running `pw kube auth`, you can immediately use `kubectl`:

```bash
kubectl get namespaces
kubectl get pods -n <namespace>
```

### Options

| Flag | Description |
|------|-------------|
| `--no-context-switch` | Configure the cluster without switching your active kubectl context |

:::info Context Naming
The context is named `pw#<cluster-name>`. You can switch between contexts with `kubectl config use-context pw#<cluster-name>`.
:::

## Manual Token Generation

If you need a raw OIDC token (for example, to use with a custom tool or API client), use:

```bash
pw kube token <cluster-name>
```

This outputs an `ExecCredential` JSON object compatible with the Kubernetes [client-go credential plugin](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#client-go-credential-plugins) protocol:

```json
{
  "apiVersion": "client.authentication.k8s.io/v1",
  "kind": "ExecCredential",
  "status": {
    "token": "<oidc-token>"
  }
}
```

:::warning Token Expiry
Tokens expire after **10 minutes**. The exec-credential plugin handles renewal automatically when you use `pw kube auth`, but if you use tokens manually you will need to regenerate them before they expire.
:::

## How Authentication Works

Parallel Works uses OIDC (OpenID Connect) tokens to authenticate users with Kubernetes clusters. Here is how the flow works:

1. When you run `pw kube auth <cluster-name>`, the CLI configures kubectl to use `pw kube token <cluster-name>` as an exec-based credential plugin.
2. Each time `kubectl` makes a request, it invokes `pw kube token` to obtain a fresh OIDC token.
3. The Kubernetes API server validates the token against the platform's OIDC provider.

### Token Claims

Each OIDC token contains the following claims:

| Claim | Value |
|-------|-------|
| `sub` (subject) | `user:<username>` |
| `aud` (audience) | The cluster ID |
| `iss` (issuer) | `https://<platform-host>/api/oidc` |
| `groups` | List of group names the user belongs to, plus `cluster-scope` |
| `platform_host` | The platform hostname |
| `exp` (expiry) | 10 minutes from issuance |

## Namespace Access

Access to namespaces is determined by your group memberships:

- Each group that has been granted access to a cluster gets a corresponding namespace (named after the group).
- You can access namespaces for any group you belong to that is shared with the cluster.
- Organization admins have access to all namespaces on the cluster.

To see which namespaces are available to you:

```bash
kubectl get namespaces
```

## Admin vs Regular User Permissions

| | Regular User | Organization Admin |
|---|---|---|
| **Cluster groups** | `cluster-scope` + group names | `cluster-scope` + `cluster-admins` + group names |
| **Namespace access** | Only namespaces matching their group memberships | All namespaces |
| **Use case** | Day-to-day workload management within group namespaces | Full cluster administration |

Organization admins are automatically added to the `cluster-admins` group, which grants elevated permissions across the cluster.

## Troubleshooting

### "kubectl not found"

The `pw kube auth` command requires `kubectl` to be installed and available on your `PATH`. Install it by following the [official Kubernetes documentation](https://kubernetes.io/docs/tasks/tools/).

### Token Errors

If you see authentication errors when running `kubectl` commands:

1. Verify that you are logged in to the PW CLI (`pw auth status`).
2. Re-run `pw kube auth <cluster-name>` to refresh your kubeconfig.
3. Confirm the cluster is still available with `pw kube ls`.

### Wrong Context

If `kubectl` is targeting the wrong cluster, check and switch your context:

```bash
kubectl config current-context
kubectl config use-context pw#<cluster-name>
```

## See Also

- [CLI Reference: pw kube auth](/docs/cli/pw/kube/auth)
- [CLI Reference: pw kube token](/docs/cli/pw/kube/token)
- [CLI Reference: pw kube ls](/docs/cli/pw/kube/ls)