Deploying a worker on Kubernetes:
the distributor-pull path, explained

01The whole idea

One sentence, then the consequence.

That is the difference between a toy and a cloud runtime. The image baked into the pod knows nothing about which packs it runs — that's decided by control-plane state and resolved at runtime. The same immutable image can serve any tenant, any revision, any bundle. Nothing about the workload is welded into the container.

Greentic's layering makes this clean. Each layer is a sealed artifact the one above composes:

The demo exercises the bottom-right of that chain: the Operator authors desired state, the Runner (a greentic-start pod) pulls the Bundle and brings it to life.

02Why pull at boot, instead of baking the bundle in?

The constraint that shapes the entire design.

03What happens when the worker boots

The core mechanism — greentic-start start --env local, step by step.

The pod's container command is just greentic-start start --env <id>. It reads the env store, finds an empty runtime-config, and the boot seam takes over:

04The commands — authoring the deployment

Every op verb the operator runs, in order, and what it records.

All authoring happens on the control-plane host with the deployer's op verbs. Each verb writes to the env store (the thing that becomes the in-cluster ConfigMap). Nothing touches a cluster until reconcile.

Authoring a pullable revision (Track 1 — loopback HTTP distributor)

# 1. env + trust root
op env create            # writes environment.json
op trust-root bootstrap local

# 2. a routing target
op bundles add            # route_binding.path_prefixes = ["/"]  → deployment_id

# 3. THE M2 STEP — stage a PULLABLE revision
op revisions stage \
   bundle_path=perf-smoke-bundle.gtbundle     # → pins its sha256 as bundle_digest \
   bundle_source_uri=http://127.0.0.1:8090/bundle.gtbundle   # where to pull

# 4. ready it, then send 100% of traffic (only routed revs are pulled)
op revisions warm         # staged → ready
op traffic set            # weight_bps = 10000 → revision_id

Three transports for bundle_source_uri

The worker fetches the bundle from whatever scheme the URI uses — the digest-gate is the same for all three:

Extra verbs for the real demo

When the bundle is real (with a flow, a messaging endpoint, and secrets), a few more op verbs come into play — see section 09:

05Two tracks — and what each one proves

The demo can run the same pull code in two places. ./demo.sh <cmd>.

The whole demo, end to end

cd /home/vampik/greenticai/my_demos/k8s-deploy-demo

./demo.sh host-pull     # Track 1 — start here. ~10s, no Kubernetes needed.
./demo.sh host-stop     # stop the worker it leaves running

./demo.sh kind-up       # Track 2 — create a kind cluster + load the :develop runtime image
./demo.sh kind-serve    #          prove a worker POD boots + serves /healthz   (local-green)
./demo.sh kind-pull     #          full in-cluster pull                          (CI-green)
./demo.sh kind-down     # delete the cluster

06Inside Kubernetes — control-plane vs data-plane

The split that holds true on real cloud too.

Visually — what lives where during a K8s deploy:

The K8s-only delta vs the host track

# Bind the K8s deployer — THIS makes the env a Kubernetes env
op env-packs add \
   slot=deployer kind=greentic.deployer.k8s@1.0.0 pack_ref=builtin \
   answers_ref=deployer-answers.json     # pins runtime_image for the rendered pods

# …author the revision exactly as Track 1…

# The ONLY verb that touches the cluster:
op env reconcile local       # server-side apply → 14 objects

# Watch a real Greentic worker come up inside Kubernetes:
kubectl rollout status deployment/gtc-worker-<revid> -n gtc-local
kubectl logs deployment/gtc-worker-<revid> -n gtc-local | grep "revision(s) for env"
# SUCCESS:  serving 1 revision(s) for env `local`     (NOT "serving probes only")

The worker Deployment is named after the revision ULID: gtc-worker-<lowercased revision_id>. Both router and worker pods boot the same start --env command.

07What reconcile applies — the 14 objects

12 env-level objects + 2 per warmed revision.

08How the local demo maps to real cloud

Every local stand-in, and its production counterpart.

09The real demo — a bundle + Telegram + Webchat new this week

Same K8s flow, upgraded from the empty fixture to a real worker that talks back. See RUN-REAL-FISH.md.

Everything so far proved delivery with the empty perf-smoke bundle. The new runbook swaps in a real bundle — webchat-bot.gtbundle (~4.9 MB, a real flow + WASM components) — pulled oci:// from public ghcr, and wires up two ways to actually talk to it: a Telegram messaging endpoint and the built-in Webchat /chat GUI.

Talking to the worker

Webchat, headless flow, and the Telegram webhook gate

# Webchat GUI — the welcome card renders on load
xdg-open http://127.0.0.1:8080/chat

# Headless — run the flow directly
curl -s -X POST http://127.0.0.1:8080/workers/invoke -d '{...HostWorkerRequest...}' | jq .

# Telegram webhook: correct secret-token -> 200, wrong -> 401
curl -s -o /dev/null -w '%{http_code}\n' -X POST http://127.0.0.1:8080/webhook/telegram \
  -H "x-telegram-bot-api-secret-token: $WHVAL" -d '{"update_id":1,"message":{...}}'   # 200

For a live bot, a cloudflared tunnel exposes the worker to the internet and setWebhook points Telegram at <tunnel>/webhook/telegram — then messaging the bot returns the welcome card.

The one wrinkle: bridging secrets into the pod

A fully-scripted bash equivalent lives next door at ../k8s-telegram-webchat-demo/ (demo.sh + its own RUN-IN-K8S.md). RUN-REAL-FISH.md is the copy-paste fish version.

10The milestone ladder — now through M4

What a 200-with-a-flow-error meant, and how M3 + M4 closed it.

While the worker runs you can poke it. /status confirms it activated a real revision:

Probe the running worker

curl -s http://127.0.0.1:8080/status
{"bundles_active":1,"deployments_routed":1,"env_id":"local","revisions_active":1,...}

curl -s -X POST http://127.0.0.1:8080/ -H 'content-type: application/json' -d '{"text":"hi"}'
# HTTP 200, body:
[{"kind":{"kind":"custom","action":"response"},
  "payload":{"metadata":{"error_kind":"flow_execution_failed",
                         "error_message":"flow main has no start node",...}}}]

The ladder — all four shipped