Kubernetes — Overview¶

OWNER: gerco (dev), thijmen (staging), rutger (production)
ALSO_USED_BY: arjan, alex, tjitte
LAST_VERIFIED: 2026-03-26
GE_STACK_VERSION: k3s v1.34.x (Zone 1 dev), UpCloud Managed Kubernetes (Zones 2+3)

Overview¶

Kubernetes is GE's container orchestration layer across all three deployment zones.
Zone 1 (dev) runs k3s single-node on bare metal.
Zones 2 and 3 (staging and production) run UpCloud Managed Kubernetes (UKS).
All clusters are EU-hosted for data sovereignty compliance (ISO 27001 A.8.31).

Three-Zone Architecture¶

GE operates a three-zone model aligned with ISO 27001 Annex A.8.31:

Zone	Environment	Platform	Owner	Location
1	Development	k3s single-node	gerco	EU bare metal
2	Staging	UpCloud Managed K8s	thijmen	UpCloud EU DC
3	Production	UpCloud Managed K8s	rutger	UpCloud EU DC

IF: deploying a new service
THEN: start in Zone 1 (k3s dev), promote to Zone 2, then Zone 3

IF: Zone 1 behaviour differs from Zone 2/3
THEN: check k3s-specific pitfalls — k3s bundles Traefik, CoreDNS, local-path-provisioner
READ_ALSO: wiki/docs/stack/kubernetes/pitfalls.md

k3s in Zone 1¶

k3s is a lightweight CNCF-certified Kubernetes distribution.
GE pins to the v1.34.x line for dev. Key bundled components:

Traefik v3.6.x as Ingress controller
CoreDNS v1.14.x for cluster DNS
local-path-provisioner for PersistentVolumeClaims
Containerd v2.1.x as container runtime
Flannel for CNI networking

CHECK: k3s version matches pinned line
RUN: k3s --version

CHECK: all system pods are running
RUN: kubectl get pods -n kube-system

UpCloud Managed K8s in Zones 2+3¶

UpCloud provides a CNCF-conformant managed Kubernetes service.
Control plane is free. Worker nodes billed by server plan (hourly).

Key differences from k3s:

Aspect	k3s (Zone 1)	UKS (Zones 2+3)
Ingress controller	Traefik (bundled)	UpCloud Managed Load Balancer
Storage	local-path-provisioner	UpCloud Block Storage CSI
Networking	Flannel	UpCloud CNI
Node scaling	Manual	Node groups with auto-scaling
Control plane	Self-managed	UpCloud-managed (free)

READ_ALSO: wiki/docs/stack/terraform-upcloud/upcloud-resources.md

GE Namespaces¶

Namespace	Purpose	Zone(s)
`ge-system`	Admin UI, orchestrator, wiki	1, 2, 3
`ge-agents`	Agent executor pods	1, 2, 3
`ge-data`	PostgreSQL, Redis	1, 2, 3
`ge-monitoring`	Metrics, health checks	1, 2, 3
`kube-system`	K8s system components	1, 2, 3

CHECK: every new resource goes into the correct namespace
IF: unsure which namespace
THEN: ask the zone owner before deploying

GE Version Pinning¶

GE pins Kubernetes versions per zone. When upgrading:

Joshua (Innovation) proposes the upgrade
Discussion with gerco, thijmen, rutger
Upgrade Zone 1 first, soak for 1 week
Promote to Zone 2, soak for 1 week
Promote to Zone 3
Update GE_STACK_VERSION in all wiki pages under wiki/docs/stack/kubernetes/

ANTI_PATTERN: upgrading all zones simultaneously
FIX: always follow the zone promotion path

Key Ports (Zone 1)¶

CHECK: ports match config/ports.yaml — never hardcode

Service	Port	Notes
Redis	6381	NOT default 6379
Wiki (MkDocs)	8000	NodePort 30080 for LAN
Admin UI	3000	ClusterIP
PostgreSQL	5432	Standard

Container Image Workflow¶

IF: deploying new or modified Python code to k3s
THEN: ALWAYS rebuild the container image
RUN: bash ge-ops/infrastructure/local/k3s/executor/build-executor.sh
RUN: kubectl rollout restart deployment/ge-executor -n ge-agents

ANTI_PATTERN: using kubectl cp to hot-patch running pods
FIX: rebuild image — Python caches modules in sys.modules at startup

Cross-References¶

READ_ALSO: wiki/docs/stack/kubernetes/manifests.md
READ_ALSO: wiki/docs/stack/kubernetes/networking.md
READ_ALSO: wiki/docs/stack/kubernetes/operations.md
READ_ALSO: wiki/docs/stack/kubernetes/security.md
READ_ALSO: wiki/docs/stack/kubernetes/pitfalls.md
READ_ALSO: wiki/docs/stack/kubernetes/checklist.md
READ_ALSO: wiki/docs/stack/terraform-upcloud/index.md
READ_ALSO: wiki/docs/stack/bunnynet/index.md