Connecting Clusters

Parallel Works lets you bring your own Kubernetes clusters and manage them through a unified interface. Once connected, you can deploy workloads, manage access through groups, and monitor resources across all of your clusters from a single pane of glass.

Prerequisites

Before connecting a cluster, make sure you have the following:

• Cluster endpoint URL — The public HTTPS endpoint of your Kubernetes API server (e.g. https://k8s.example.com:6443).
• CA certificate (if needed) — The Certificate Authority (CA) certificate for the cluster, used to establish a trusted TLS connection to the API server. If the API server presents a publicly trusted certificate, no CA certificate is required.
• Network connectivity — The Parallel Works platform must be able to reach your cluster endpoint over the network. Make sure that any firewalls or security groups allow inbound connections to the API server from the platform.
• Organization admin permissions — Only organization admins can add or modify clusters.

Adding a Cluster

1. Navigate to Kubernetes > Clusters in the sidebar.
2. Click Add Cluster to open the cluster registration drawer.
3. Fill in the fields:
   • Cluster Name — A name for the cluster using lowercase letters, numbers, and hyphens (other characters are removed automatically).
   • Cluster Endpoint — The public HTTPS URL of your Kubernetes API server.
   • CA Certificate (optional) — Paste the PEM-encoded CA certificate for your cluster, or click Discover from endpoint to fetch it automatically from the API server. Leave it blank if the cluster uses a publicly trusted certificate.
4. Click Add Cluster to save.

After the cluster is added, you are redirected to the cluster definition page where you can verify the connection and configure access.

Verifying Connectivity

Once a cluster is added, Parallel Works verifies the connection by querying the Kubernetes API for the cluster's node list. On the Clusters page, each connected cluster displays:

• vCPUs — Total CPU capacity across all nodes.
• Memory — Total memory capacity across all nodes.

If the platform cannot reach the cluster, the cluster still appears in the list but shows zero resources. This typically indicates a network connectivity issue or an invalid CA certificate.

Each reachable cluster also has a Connect button that displays the pw kube auth command for configuring local kubectl access.

Granting Users Access

Access to a connected cluster is controlled in two layers:

1. Cluster sharing — Share the cluster with the groups that should be able to see and use it. Group members can then browse the cluster's resources, and their group memberships are included in the OIDC tokens used to authenticate against the cluster (see Security Model below).
2. Namespace role bindings — Organization admins create namespaces and grant each group a Kubernetes role (admin, edit, or view) within specific namespaces on the Namespaces page.

Multi-Cluster Management

The Kubernetes section provides a unified view across all connected clusters. From the sidebar, you can access:

• Clusters — View and manage all connected clusters.
• Nodes — Inspect node details and GPU operator configuration (admin only).
• Quotas — Set resource quotas per namespace (admin only).
• Namespaces — Create namespaces and manage group access (admin only).
• Workloads — List deployments, stateful sets, daemon sets, replica sets, jobs, cron jobs, and pods across clusters.
• Services — View services across clusters.
• Storages — Manage PersistentVolumeClaims and PersistentVolumes.
• ConfigMaps & Secrets — Browse configuration resources.
• Helm Charts — Install, rollback, and manage Helm releases.

All resource views support filtering by cluster and namespace, making it straightforward to manage resources across a large fleet of clusters.

Security Model

Parallel Works uses OIDC token federation to authenticate users against connected Kubernetes clusters. This eliminates the need to distribute long-lived kubeconfig files or service account tokens.

How It Works

1. When a user accesses a connected cluster, the platform generates a short-lived OIDC JWT token on behalf of the user.
2. The token is signed by the platform's OIDC issuer (https://<platform-host>/api/oidc).
3. The token is scoped to the specific cluster (using the cluster ID as the JWT audience).
4. The connected cluster validates the token using the platform's OIDC discovery endpoint and public keys.

Token Properties

Group-Based Access Control

Each OIDC token includes group claims that map to Kubernetes RBAC:

• cluster-scope — Included in every token. Grants read-only access to cluster-scoped resources like storage classes and runtime classes via a dedicated ClusterRole.
• cluster-admins — Included for organization admins and platform admins. Grants full administrative access to the cluster.
• Group names — If the user belongs to groups that the cluster is shared with, those group names are included as claims. These map to the namespace-scoped RoleBindings managed on the Namespaces page, granting each group its assigned role (admin, edit, or view) within the corresponding namespaces.

This model ensures that regular users can only access namespaces their groups have been granted, while organization admins retain full cluster-level access. All tokens are short-lived, reducing the risk associated with credential leakage.