Kubernetes relay guide

Connect EKS, AKS, GKE, OpenShift, Rancher, kubeadm, k3s, and other conformant Kubernetes clusters without uploading a kubeconfig or exposing the Kubernetes API publicly.

How it works

1. An organization administrator generates a short-lived installer in Connections.
2. The installer confirms the active kubectl context before it changes anything.
3. It creates one namespace, ServiceAccount, narrow RBAC, bootstrap Secret, state Secret, and relay Deployment.
4. The pod uses its in-cluster ServiceAccount, creates its private key locally, enrolls once, and deletes the bootstrap Secret.
5. The relay polls One Engineer over outbound mutual TLS. There is no inbound Service or customer firewall rule.

Installation and deterministic connection tests do not invoke a model and do not consume credits.

Requirements

• A current kubectl configured for the intended cluster.
• At least one Linux worker capable of running containers.
• Permission to create the displayed namespace, workload, ServiceAccount, and RBAC.
• Working DNS and time synchronization.

Allow outbound TCP 443 to:

• oneengineer.ai for enrollment and application APIs
• relay.oneengineer.ai for mutual-TLS heartbeat and job polling
• registry-1.docker.io and Docker Hub content-delivery hosts

Private or air-gapped networks can use the installer's HTTPS proxy option. A private registry mirror must contain the same reviewed image digest.

Install

1. Open Connections and select Kubernetes cluster.
2. Enter the cluster name and choose a permission profile.
3. Select Generate installer, then download the generated script.
4. Run bash one-engineer-relay-install.sh.
5. Read the displayed context and server, then type the exact context name to continue.
6. Return to Connections and watch the six verification stages complete.

The installer is single-use and expires. Regenerate it from the same screen if it expires before enrollment. Never post the script or enrollment token in a ticket or chat.

Permission profiles

Read plus remediation can read workloads, pods, logs, events, services, ingresses, metrics, namespaces, and nodes. It can patch or scale Deployments, delete Pods, and cordon or uncordon Nodes. One Engineer still requires explicit approval before every mutation.

Namespace-limited is available when cluster-wide RBAC cannot be installed. It restricts reads and remediation to one existing namespace and disables node and cluster-wide operations.

Neither profile grants pod exec, arbitrary workload creation, Secret access, or cluster-admin.

State and restarts

No PVC or StorageClass is used. The relay's mTLS identity, certificate rotation state, and bounded idempotency records are stored in one named Kubernetes Secret. Its Role can read and update only that Secret and can read and delete only the one-time bootstrap Secret. It cannot list or read other Secrets.

Stable operation IDs and compact completion records prevent an approved mutation from running twice after a pod restart or lost network response.

Verification

The guided status checks:

• Installed: the Deployment started and reached enrollment.
• Enrolled: a customer-side key received a short-lived client certificate.
• Online: One Engineer received a recent outbound heartbeat.
• Cluster reached: in-cluster authentication and the Kubernetes version API worked.
• Permissions verified: required reads and approved remediation capabilities passed.
• Ready: the Kubernetes connection was created and is available to the workspace.

Use Test connection at any time. The result includes Kubernetes version, node architecture, relay version, certificate expiry, and exact RBAC failures.

Diagnostics

kubectl -n one-engineer-relay get pods
kubectl -n one-engineer-relay get events --sort-by=.lastTimestamp
kubectl -n one-engineer-relay logs deployment/one-engineer-relay --tail=200

• Pending: check installer expiry, context confirmation, DNS, and outbound HTTPS.
• ImagePullBackOff: allow Docker Hub endpoints or mirror the exact digest.
• Admission rejected: compare the message with the non-root, restricted pod specification.
• Offline: check DNS, proxy configuration, time synchronization, and relay logs.
• Missing RBAC: install the reported permission or use namespace-limited mode.
• Certificate problem: restore outbound access for rotation or revoke and replace the relay.

Upgrade, revoke, and replace

Upgrades keep the named state Secret and replace only the Deployment image with the next signed immutable digest. A rollback uses the prior reviewed digest and the same state Secret.

Revocation immediately rejects the relay certificate. After revoking, remove the namespace only when its connection and audit history are no longer needed. A replacement installer refuses to adopt state belonging to another installation.

Other private systems

SSH hosts and internal HTTP services can use the host-based Docker relay shown underCustomer-private relays. Those connectors keep credentials in a local owner-only credentials.json file. Kubernetes uses the simpler in-cluster flow above and never needs that file.