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 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:

pw kube ls

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

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

Authenticating with a Cluster

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

pw kube auth <cluster-name>

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

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:

kubectl get namespaces
kubectl get pods -n <namespace>

Options

Manual Token Generation

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

pw kube token <cluster-name>

This outputs an ExecCredential JSON object compatible with the Kubernetes client-go credential plugin protocol:

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

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:

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:

kubectl get namespaces

Admin vs Regular User Permissions

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.

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:

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

See Also

• CLI Reference: pw kube auth
• CLI Reference: pw kube token
• CLI Reference: pw kube ls