cloudflare/kubernetes-access-worker-example

cloudflare/kubernetes-access-worker-example

Description: Example implementation of an Access-protected private Kubernetes API

Language: TypeScript

License: NOASSERTION

Stars: 5

Forks: 1

Open issues: 1

Created: 2026-01-13T20:45:23Z

Pushed: 2026-04-23T21:01:26Z

Default branch: main

Fork: no

Archived: no

README:

Cloudflare Zero Trust Kubernetes Proxy

This repository contains a reference implementation for securely exposing a Kubernetes API server using Cloudflare Zero Trust, Cloudflare Workers, and Terraform.

Unlike a traditional VPN, this architecture places a Cloudflare Worker on the public internet, strictly shielded by Cloudflare Access. Users authenticate using their enrolled WARP client in your Zero Trust organization; Cloudflare Access reuses this authenticated WARP session to automatically authorize requests to the Worker for a configured session duration. Once authorized, Access injects a signed JWT into the request headers; the Worker then cryptographically validates this token to confirm the user's identity before proxying traffic to your Kubernetes API server using Impersonation headers.

🏗 Architecture

The flow of a request is as follows:

1. Developer runs kubectl on their laptop (connected to Cloudflare WARP). 2. WARP captures the request and attaches a secure device session identity. 3. Cloudflare Access checks the Zero Trust policy (i.e., "Must have valid WARP session") before sending the traffic to the Worker. 4. Cloudflare Worker (this [code](./src/index.ts)):

• Validates the Access JWT.
• Maps the user email to a Kubernetes identity (User/Group).
• Establishes a secure, private connection to the cluster via Cloudflare

Tunnel and Workers VPC (WVPC).

• Injects Impersonation headers.
• Handles WebSocket upgrades for streaming commands (kubectl exec, logs -f).

5. Kubernetes API receives the request. Once the Kubernetes API server verifies the pod's Service Account has permission to impersonate (e.g. ClusterRole with impersonate verb), it switches contexts and applies standard Kubernetes RBAC policies to the request effectively as if User X and Group Y had initiated it directly.

⚡️ The Worker (/src)

The heart of this solution is the Cloudflare Worker. It is responsible for bridging the gap between HTTP-based Zero Trust auth and Kubernetes-native RBAC.

Key Features

• Identity Mapping: Translates enrolled Zero Trust user's email (e.g. alice@mydomain.com) into a Kubernetes User (e.g. alice) and Groups (e.g. system:masters, developers).
• Header Sanitization: Removes dangerous headers to prevent spoofing and strips internal Cloudflare trace headers before they reach the cluster.
• WebSocket Support: Full support for interactive kubectl commands (exec, attach, port-forward) by manually handling the WebSocket handshake and subprotocol negotiation.
• Security: Verifies the JWT signature against your Team's JWKS to ensure requests are legitimate.

☁️ Infrastructure (Terraform)

The /terraform directory uses a modular approach to provision the entire stack.

1. DigitalOcean Cluster ([modules/digitalocean](./terraform/modules/digitalocean))

• Provisions a managed Kubernetes (DOKS) cluster for demo purposes.
• Configures VPC and node pools.

2. Kubernetes Resources ([modules/k8s](./terraform/modules/k8s))

• Cloudflare Tunnel: Creates the [Cloudflare

Tunnel](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/) and credentials.

• Tunnel Pod (Sidecar Architecture): Deploys a single Pod containing two

containers to bridge traffic from the edge to the API server:

• Container 1 (`cloudflared`): Establishes the encrypted outbound

tunnel to Cloudflare. It receives traffic from the edge and forwards it locally via plaintext HTTP to the sidecar (traffic is fully encrypted in transit through the tunnel).

• Container 2 (`kubectl proxy`): Runs the [`kubectl

proxy](https://kubernetes.io/docs/reference/kubectl/generated/kubectl_proxy/) command. It listens for the plaintext traffic from cloudflared` and proxies it to the actual upstream Kubernetes API Server. This sidecar validates the Kube API's TLS certificate.

• Service Account: Creates the high-privilege Service Account the Worker

uses to "impersonate" other users. It is bound to the pod; the Worker does not see the secret ServiceAccount token.

• RBAC: Binds the necessary ClusterRole to allow the pod to perform

impersonation.

3. Worker Infrastructure ([modules/worker](./terraform/modules/worker))

• Worker Custom Domain: Maps the Worker to a custom domain (e.g.,

kube.mydomain.com). This is a prerequisite for placing the Worker behind Cloudflare Access.

• Access Application: Protects the Worker's public endpoint by enforcing

Zero Trust policies. It strictly verifies that incoming requests have a valid, authenticated WARP session before they ever reach the Worker code.

• Workers VPC Service: Configures a [Workers VPC

Service](https://developers.cloudflare.com/workers-vpc/configuration/vpc-services/) to create a secure, private binding (env.KUBE_API). This allows the Worker to communicate directly with the Cloudflare Tunnel inside the cluster over a private network, ensuring traffic between the proxy and the cluster never traverses the public internet.

🚀 Deployment Guide

🛠️ Step 0: Prerequisites & Setup

Prerequisites:

• Zero Trust Admin: You must be an Administrator in your Cloudflare Zero Trust Organization.
• Cloudflare Zone: You need an active domain onboarded to Cloudflare. This

is required to assign a public custom domain (e.g., kube.mydomain.com) to the Worker later.

• *Guide: Add a site to Cloudflare*
• WARP sessions: Enable WARP authentication identity as an allowed login

method in your Zero Trust Organization. This allows users to log in to Access applications using their…