Greentic on Kubernetes:
deployment guide & reproducible demo

01Mental model — two independent axes

The single most important thing to internalize.

"The cluster and the environment id are two independent axes." They are frequently conflated; they are not the same thing. One decides which cluster the objects land in; the other decides the logical environment name that drives the namespace and the store partition.

A local store is single-operator: its authorization boundary is OS filesystem ownership, so named environments are first-class — you may keep the id local while targeting a remote production cluster, or give it a real name like prod. A shared, multi-operator control plane (an operator-store server with RBAC) is a separate, still-future effort.

The store vs. the cluster

The deployer separates authoring (writes the store) from applying (writes the cluster):

02What gets rendered onto the cluster

op env reconcile <id> renders a fixed set of objects into namespace gtc-<env-id>. From a webchat+Telegram env this is 15 objects.

Key facts about the rendered topology

• Services are ClusterIP on port 8080. The deployer renders no Ingress and no LoadBalancer — external exposure is bring-your-own (§8).
• No imagePullPolicy is set. A non-digest tag (e.g. :develop) defaults to IfNotPresent, and a warm node can serve a stale cached layer. Pin runtime_image to a digest for deterministic pulls in production.
• The worker pulls its bundle over OCI at boot. Reconcile records a bundle_source_uri; the worker (greentic-start) fetches the .gtbundle, re-verifies it against the recorded bundle_digest (two-point integrity), materializes it, and serves the revision.
• Pod security: distroless image, runs as uid 65532 with readOnlyRootFilesystem: true; HOME (/var/greentic) is a writable emptyDir.

Namespace derivation

namespace_for_env(env_id) (src/env_packs/k8s/manifests.rs):

• Clean ids (lowercase [a-z0-9-], no leading/trailing -, and gtc-<id> ≤ 63 chars) → gtc-<id> verbatim. local → gtc-local, prod → gtc-prod.
• Ids needing lossy sanitization (uppercase, ., _) or exceeding the RFC 1123 63-char limit → a collision-proof hash suffix: gtc-<sanitized-prefix>-<hash8>. Distinct ids that sanitize identically still get unique namespaces.

03Prerequisites

What you need before the two-command flow.

• kubectl with a working context for the target cluster (kubectl config get-contexts).
• The gtc CLI with an up-to-date deployer. Recommended path: install / refresh the prebuilt nextgen-deployer toolchain release so the gtc op … router and its embedded deployer/operator are current — this ships the OCI-bundle (URI-only) support, the cloudflared-in-image runtime, and the loopback-admin-listener split this guide relies on.
• Cluster internet egress — the worker pulls the runtime image and the bundle from public ghcr.io at boot.
• A runtime image. Default is ghcr.io/greenticai/greentic-start-distroless:develop. For Telegram-via-tunnel you need an image that ships cloudflared (the :develop distroless image carries it).

install / refresh the deployer toolchain

gtc-dev install --release nextgen-deployer
# add --force to overwrite an already-installed toolchain

Build from source instead? Use default features — the k8s-client feature is default-on and required by reconcile:

cargo build -p greentic-deployer --bin greentic-deployer
# binary at target/debug/greentic-deployer; invoke `… op …`
# a stale --no-default-features build fails reconcile with:
#   conflict: this build was compiled without the k8s-client feature

04The demo — my_demos/k8s-deploy-demo

The fastest path: 2 JSON files, 2 commands (plus one-time cluster bring-up). Brings up Webchat and Telegram — the K8s analog of the local setup --answers … && start --cloudflared on two-liner.

What collapsed into two files

Why Telegram is hands-off

Three things the runtime does for you on K8s — the same way local does:

05Reproduce the demo on your PC

A complete, copy-paste fish walk-through against a local kind cluster. One token-bearing command; everything else is store + cluster plumbing.

walk-through · fish

# ── config (paths are fixed) ───────────────────────────────────────────────
set -gx STORE /tmp/gtc-k8s-demo/.greentic/environments

# ── one-time only: create the cluster (skip if `kind get clusters` shows gtc-demo)
kind create cluster --name gtc-demo
kind export kubeconfig --name gtc-demo

# ── refresh the runtime image (kind won't re-pull a mutable :develop tag itself)
docker pull ghcr.io/greenticai/greentic-start-distroless:develop
kind load docker-image ghcr.io/greenticai/greentic-start-distroless:develop --name gtc-demo

# ── 1. author the env (THE one token-bearing command — inline your bot token) ─
env TELEGRAM_DEMO_BOT_TOKEN=<YOUR_BOT_TOKEN> \
    gtc-dev op --store-root $STORE --answers /home/vampik/greenticai/my_demos/k8s-deploy-demo/declarative/k8s.env.json env apply --yes

# ── 2. reconcile onto the live cluster ──────────────────────────────────────
gtc-dev op --store-root $STORE env reconcile local

# ── wait for the worker, then port-forward the webchat admin listener ────────
set WORKER (kubectl -n gtc-local get deploy -o name | string match '*worker*')
kubectl -n gtc-local rollout status $WORKER --timeout=240s
kubectl -n gtc-local port-forward $WORKER 8081:8081
#   → open http://localhost:8081/chat   (webchat — works alongside the tunnel)
#   → Telegram: just message the bot (worker auto-registered the webhook at boot)

Clean up

teardown + Telegram hygiene · fish

# stop any running port-forward (Ctrl+C in its terminal, or:)
pkill -f 'port-forward.*gtc-worker'

# nuke everything (cluster + node image cache)
kind delete cluster --name gtc-demo
rm -rf /tmp/gtc-k8s-demo

# Telegram hygiene — unpoint the bot from the now-dead tunnel (token-bearing, yours)
curl -s "https://api.telegram.org/bot<YOUR_BOT_TOKEN>/deleteWebhook"

# ── clean slate: drop any prior env from cluster + store ────────────────────
kubectl delete ns gtc-local --ignore-not-found --wait
rm -rf $STORE; mkdir -p $STORE

06The demo's config files

Two files under declarative/. Secret values never appear here — only a from_env pointer that's read at apply time.

the env-manifest · declarative/k8s.env.json

{
  "schema": "greentic.env-manifest.v1",
  "environment": {
    "id": "local",
    "name": "k8s",
    "gui_enabled": true
  },
  "trust_root": "bootstrap",
  "packs": [
    {
      "slot": "deployer",
      "kind": "greentic.deployer.k8s@1.0.0",
      "pack_ref": "builtin",
      "answers_ref": "deployer-answers.json"
    },
    {
      "slot": "secrets",
      "kind": "greentic.secrets.dev-store@1.0.0",
      "pack_ref": "builtin"
    }
  ],
  "bundles": [
    {
      "bundle_id": "webchat-bot",
      "bundle_source_uri": "oci://ghcr.io/greenticai/greentic-demo-bundles/webchat-bot:v1",
      "bundle_digest": "sha256:4f560749ec709e75b6063cdeccab15ed5074c2e60bc5f772c2d3b7d4bd992363",
      "route_binding": {
        "hosts": [],
        "path_prefixes": ["/"],
        "tenant_selector": { "tenant": "tenant-default", "team": "default" }
      }
    }
  ],
  "secrets": [
    {
      "path": "tenant-default/_/messaging-telegram/telegram_bot_token",
      "from_env": "TELEGRAM_DEMO_BOT_TOKEN"
    }
  ],
  "messaging_endpoints": [
    {
      "name": "webchat-bot",
      "provider_type": "messaging.telegram.bot",
      "links": ["webchat-bot"]
    }
  ]
}

the deployer pack's answers · declarative/deployer-answers.json

{
  "runtime_image": "ghcr.io/greenticai/greentic-start-distroless:develop",
  "tunnel": "cloudflared"
}

Field-by-field

07Secrets — the dev-store bridge

The K8s model does not yet integrate a real secrets backend (AWS SM / Vault / native secretKeyRef). When an env binds greentic.secrets.dev-store@1.0.0:

08Reaching the worker

Two surfaces, two trust postures.

The loopback-trust rule

The revision server trusts a caller only when (peer is loopback) AND (no public tunnel fronts this listener):

• No tunnel: the console is on the main serve port (8080); a port-forward 8080:8080 is a genuine loopback peer and gets /chat + 200.
• Tunnel up: the main port is fronted by cloudflared, so it serves provider webhooks only (/chat → 405, /workers/invoke → 403). A separate loopback-only admin listener (main port + 1 = 8081) keeps serving the console. port-forward 8081:8081 for /chat; the boot banner prints the exact admin port. This lets webchat and Telegram run simultaneously.

Deliberate security posture: cloudflared forwards from loopback, so public tunnel traffic would otherwise read as loopback and bypass the /workers/invoke gate. Routing the console to an untunneled, loopback-scoped admin listener closes that without exposing anything new to the network.

09Configuration reference

Every key, sourced from src/env_packs/k8s/.

Deployer answers — greentic.deployer.k8s@1.0.0 (answers_ref)

A flat JSON object keyed by wizard question id. All keys optional; unknown keys are rejected (fail closed on version skew).

Env-manifest — greentic.env-manifest.v1 (K8s-relevant fields)

10Known gaps & production caveats

All verified in source. None silently broken — each is a deliberate current limitation with a workaround.

Reconcile authenticates as your ambient kubeconfig identity.

11Troubleshooting

Symptom → cause → fix.

12Glossary