Request for guide to Cloudflare fronted openshell remote gateways?

[oidebrett]

Hi, is there a tutorial/ guide on setting up a cloudflare fronted openshell gateways with authentication? I have read this architecture document https://github.com/NVIDIA/OpenShell/blob/main/architecture/gateway-security.md but it's not very clear what needs to be set up on cloudflare.

Rgds
Oide

[Advait251206]

There isn’t (at least currently) a step-by-step official tutorial specifically for “Cloudflare-fronted OpenShell gateways with authentication” beyond the architecture notes you already referenced.

That said, the architecture in gateway-security.md implies a fairly standard pattern: OpenShell expects the gateway layer to sit behind an authenticated reverse proxy / edge layer, and Cloudflare is just one way to implement that.

How this is generally expected to be set up

At a high level, the setup usually looks like:

Client
  ↓
Cloudflare (WAF + Access + Auth)
  ↓
Cloudflare Tunnel / Load Balancer
  ↓
OpenShell Gateway (internal service)
  ↓
Sandbox / Execution layer

What you typically need on Cloudflare

You would normally configure three things:

1. Cloudflare Access (authentication layer)

This is the part that replaces “gateway authentication”:

• Define an Access Application for the gateway domain
• Choose an identity provider (Google, GitHub, OIDC, etc.)
• Enforce login rules (email domain, group membership, service tokens, etc.)

This handles who is allowed to reach OpenShell at all.

---

2. Cloudflare Tunnel (recommended instead of public ingress)

Instead of exposing the gateway publicly:

• Install cloudflared inside the cluster or VM running OpenShell gateway
• Create a tunnel to Cloudflare
• Map it to the internal gateway service

This avoids exposing Kubernetes ingress directly.

---

3. Optional: Service tokens for machine-to-machine access

For programmatic access (CLI, agents, CI):

• Create Cloudflare Access Service Tokens
• Pass them via headers:
  • CF-Access-Client-Id
  • CF-Access-Client-Secret

This is usually how non-browser clients authenticate.

---

What OpenShell expects (based on architecture doc)

From the OpenShell side, the gateway generally assumes:

• It is already behind an authenticated edge
• It receives trusted identity headers (or at least pre-authenticated traffic)
• It does not itself act as the primary identity provider in Cloudflare setups

So Cloudflare becomes the identity + perimeter security layer, while OpenShell focuses on sandbox orchestration.

---

Common missing pieces (where people usually get stuck)

1. Not forwarding identity headers correctly

   • Cloudflare Access injects headers, but backend must trust them explicitly.

2. Tunnel routing mismatch

   • Gateway service not correctly mapped to internal Kubernetes service/port.

3. CORS / websocket issues

   • OpenShell gateway traffic is often long-lived (streams), so Cloudflare settings must allow it.

4. Double authentication confusion

   • Mixing OpenShell gateway auth + Cloudflare Access auth can cause conflicts if both are enabled.

---

Is there an official guide?

As of now, the repo only provides:

• Architecture-level description (gateway-security.md)
• No Cloudflare-specific walkthrough
• No reference Terraform / Helm / cloudflared config

So what you’re trying to do is valid, but it’s currently in the category of “reference architecture, not turnkey guide.”

---

Recommendation

If you’re implementing this, the cleanest pattern is:

• Cloudflare Access → handles identity
• Cloudflare Tunnel → handles secure ingress
• OpenShell Gateway → assumes trusted traffic only

And avoid duplicating auth logic inside the gateway unless explicitly required.

---

If this answer helped or pointed you in the right direction, I'd appreciate it if you could mark it as the accepted answer so it's easier for others with the same issue to find.

Also, if you found my contribution useful, I'd appreciate it if you could check out my GitHub profile, follow me, and star any repositories you find interesting.

GitHub: https://github.com/Advait251206