Skip to content

connecting to a cluster

Jump to bottom
Kadyapam edited this page May 28, 2026 · 2 revisions

Connecting to a NoETL cluster

There are three supported ways to point the CLI at a NoETL deployment. Pick the one that matches your access — the rest of the wiki assumes you've gone through the right path at least once.

Path Use when Trust
Gateway-authenticated Operators behind Auth0, dashboards on the public internet, multi-tenant clusters. Per-user Auth0 identity; gateway validates every request.
Port-forward Operators with kubectl access who want a direct TCP path to the in-cluster noetl service. In-cluster RBAC + your local kubeconfig.
Direct Local noetl server running on your workstation. Localhost only.

The three paths are interchangeable per context — set up one context for each deployment you reach, and switch with noetl context use <name> or the per-command noetl --context <name> override.

Path 1 — Gateway-authenticated

The gateway is the gatekeeper. It validates Auth0 tokens, attaches session identity, and proxies into the in-cluster noetl runtime.

One-command bootstrap

If the gateway exposes its runtime contract (gateway v2.10+):

noetl context init prod --from-gateway https://gateway.acme.com --set-current
noetl auth login --browser-pkce

context init --from-gateway reads the gateway's GET /api/runtime/contract, parses the auth0 block, prints what it's about to write, and persists the context. See noetl context init --from-gateway.

Manual bootstrap (older gateways)

noetl context add prod \
  --server-url=https://gateway.acme.com \
  --auth0-domain=acme.us.auth0.com \
  --auth0-client-id=Abc123XYZ \
  --auth0-redirect-uri=https://app.acme.com/login \
  --auth0-audience=https://api.acme.com \
  --runtime=distributed \
  --set-current
noetl auth login --browser-pkce

Use it

noetl catalog list Playbook
noetl exec catalog://itinerary-planner@latest --runtime distributed

After login — no need to export the token

A successful auth login caches the session token onto the context file. Subsequent CLI calls read it from there automatically.

The export NOETL_SESSION_TOKEN=… hint the CLI prints after login is for other tools (curl, scripts) that read the env var — not for the CLI itself. See auth login → After a successful login for the full explanation.

When the session expires

A 401 from the gateway causes the CLI to exit with code 77 and a hint to re-login. Scripts can branch on that exit code. See Exit codes.

Path 2 — Port-forward to the in-cluster server

When you have kubectl access to the cluster but the gateway either isn't appropriate (admin task, smoke test, latency-sensitive iteration) or isn't reachable from where you're sitting.

Set up

# 1. Create the context with a loopback server URL and kube fields
noetl context add gke-pf \
  --server-url=http://127.0.0.1:18082 \
  --runtime=distributed \
  --kube-context=gke_acme_us-central1_prod \
  --kube-namespace=noetl \
  --kube-service=noetl \
  --kube-remote-port=8082

# 2. Bring the tunnel up in the background
noetl context port-forward gke-pf --detach

Use it

# Per-command override
noetl --context gke-pf catalog list Playbook

# Or make it current
noetl context use gke-pf
noetl catalog list Playbook

Tear down

noetl context port-forward gke-pf --stop

See noetl context port-forward for --status, the port-conflict probe, and the PID-file layout.

Path 3 — Direct (local dev server)

Running noetl server on your workstation, or pointing the CLI at a local kind cluster's NodePort:

noetl context add local --server-url=http://localhost:8082 --runtime=local --set-current
noetl exec ./playbooks/foo.yaml

No login needed when the local server is configured without auth, or when you've set GATEWAY_AUTH_BYPASS=true on a local gateway used purely for development. Don't deploy that into shared environments.

Quick reference

Goal Command
Create context from gateway URL noetl context init <name> --from-gateway <url> --set-current
Create context manually noetl context add <name> --server-url=… [--auth0-…]
Patch a field noetl context update <name> --auth0-client-id=… --kube-namespace=…
Log in (gateway path) noetl auth login --browser-pkce
Start port-forward noetl context port-forward <name> --detach
Stop port-forward noetl context port-forward <name> --stop
List contexts noetl context list
Switch context noetl context use <name>
One-off context noetl --context <name> <cmd>
Show current noetl context current

Sanity-check after setup

noetl context current                                         # right context?
noetl catalog list Playbook                                   # gateway / server reachable?
noetl exec catalog://hello-world@latest --runtime distributed # full round trip?

If catalog list fails:

  • gateway path — re-login (noetl auth login --browser-pkce). Exit code 77 means session expired; any other failure check the CORS / DNS path.
  • port-forward path — check the tunnel (noetl context port-forward <name> --status); restart with --stop then --detach if stale.
  • direct path — confirm noetl server is running and bound to the URL in the context.

See also

NoETL CLI

Contexts

Auth

Architecture

Cross-wiki

Clone this wiki locally