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 — The Certificate Authority (CA) certificate for the cluster. This is used to establish a trusted TLS connection to the API server.
• 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 required fields:
   • Cluster Name — A lowercase alphanumeric name for the cluster (special characters are removed automatically).
   • Cluster Endpoint — The public HTTPS URL of your Kubernetes API server.
   • CA Certificate — Paste the full PEM-encoded CA certificate for your cluster.
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.

Sharing Clusters with Groups

Organization admins can share clusters with specific groups to control who has access. When a cluster is shared with a group:

1. A Kubernetes namespace is automatically created on the cluster, named after the group.
2. A RoleBinding is created in that namespace granting the group admin-level access within the namespace.
3. Members of the group can then view and manage resources within their namespace.

To share a cluster:

1. Navigate to the cluster's definition page.
2. Select the groups you want to share the cluster with.
3. Save the updated configuration.

When a group is removed from a cluster, the associated RoleBinding is deleted but the namespace is preserved to prevent accidental data loss.

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).
• 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, upgrade, rollback, and manage Helm releases.
• Quotas — Set resource quotas per namespace (admin only).

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 namespace-scoped RoleBindings that grant admin access within the corresponding namespace.

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