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.
kubectl installed on your local machineTo see which Kubernetes clusters you have access to, run:
pw kube lsThis 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 tableQuick Overview
Use pw kube ls -o table for a quick overview of cluster capacity.
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 demoThis command performs the following steps automatically:
pw kube token automatically when kubectl needs a token)pw#<cluster-name> and switches to itAfter running pw kube auth, you can immediately use kubectl:
kubectl get namespaces
kubectl get pods -n <namespace>| Flag | Description |
|---|---|
--no-context-switch | Configure the cluster without switching your active kubectl context |
Context Naming
The context is named pw#<cluster-name>. You can switch between contexts with kubectl config use-context pw#<cluster-name>.
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>"
}
}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.
Parallel Works uses OIDC (OpenID Connect) tokens to authenticate users with Kubernetes clusters. Here is how the flow works:
pw kube auth <cluster-name>, the CLI configures kubectl to use pw kube token <cluster-name> as an exec-based credential plugin.kubectl makes a request, it invokes pw kube token to obtain a fresh OIDC token.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 |
Access to namespaces is determined by your group memberships:
To see which namespaces are available to you:
kubectl get namespaces| 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.
The pw kube auth command requires kubectl to be installed and available on your PATH. Install it by following the official Kubernetes documentation.
If you see authentication errors when running kubectl commands:
pw auth status).pw kube auth <cluster-name> to refresh your kubeconfig.pw kube ls.If kubectl is targeting the wrong cluster, check and switch your context:
kubectl config current-context
kubectl config use-context pw#<cluster-name>