Docs / Clouds

On-prem Kubernetes

Connect a private Kubernetes cluster through an outbound relay, with no public API server.

Use this for a cluster whose API server is not reachable from the internet. You run one small pod in the cluster. The pod dials out to Pangea, and nothing dials in. It needs no inbound port, no Service and no privileges. Do not open the API server publicly just to connect it.

An Administrator opens Connectors → Connect → Kubernetes. The dialog, Connect a Kubernetes cluster, has three steps. It proves the outbound tunnel works before it accepts a cluster credential.

Enroll the cluster

1. Name it

Use lowercase letters, digits and dashes, for example acme-dc1. The name becomes the kubectl context the agent uses, onprem/<name>/cluster, so pick something unambiguous.

2. Install the agent

The dialog shows a kubectl apply command with a manifest made for this cluster. Review it, then run it against the cluster as someone who can create a namespace. The manifest creates one namespace, one Secret with the enrollment token, and one Deployment for the relay agent.

• The token is shown once. Pangea keeps no copy.
• Do not reuse another cluster's command. Each one carries its own enrollment values.

Wait until the dialog says Agent connected.

3. Grant access

The tunnel carries bytes. It does not authenticate to Kubernetes. The dialog shows a script that creates a persistent ServiceAccount credential and prints a kubeconfig. Run it, then paste the kubeconfig into the field. It must contain the server address, a CA and a token.

• The script binds the ServiceAccount to cluster-admin. Full access is required for resource management, terminals, port forwarding and agent operations. Pangea still applies your permission and confirmation settings before privileged actions.
• The server address is the one that works inside the cluster, for example https://kubernetes.default.svc. It never has to be publicly resolvable.
• Do not use kubectl create token here. Many clusters cap its lifetime at one hour, which later causes HTTP 401 errors.

Click Save and check access. Pangea shows what Kubernetes itself says the credential can do: identity, permissions and visible namespaces. Widen or narrow it with RBAC in your cluster and check again.

If you close the dialog partway through, the connection can be resumed. Return to that entry instead of installing a second agent.

Verify

Read a known namespace with the new context. Check both the relay status and the real RBAC permissions. An online relay does not grant any access by itself. The cluster appears in the shared Kubernetes browser.

Troubleshoot

• Waiting for the agent to connect. Check the relay pod's health and the cluster's outbound connectivity before you replace any credential.
• Pangea cannot reach its own relay right now. The problem is on Pangea's side, not in your cluster.
• Access denied. Inspect the ServiceAccount's RoleBindings and ClusterRoleBindings.

Cut off and retire

• To cut access off right away, scale the relay Deployment to zero. It is instant and needs nothing from Pangea.
• To revoke the credential, delete the ServiceAccount's token Secret.
• To decommission, remove the connection in Pangea, then delete the relay namespace and any RBAC you no longer need. The resource names are at the top of the manifest and the script. Removing the connection in the app does not clean up the cluster.