Skip to content
Recommender Tutorial

Deployment operations

The deployment operations module is the operator path for the tutorial. It starts with k3s on the Tinys cluster so the reader can practise Kubernetes-shaped operations on real local hardware while keeping the repo’s platform decisions intact: DuckDB-readable Parquet, FastAPI app contract, Dagster orchestration, static analytical surfaces, and the TypeScript editor.

This is not the fastest way to author every lesson. The fast loop remains uv, DuckDB/Parquet, Docker Compose where needed, and static builds on Spark or the laptop. The laptop is the thin operator surface. Spark is the jumpbox and heavy AI/local-inference workstation. K3s is the runtime boundary for operator work.

Relationship to existing deployment work

Section titled “Relationship to existing deployment work”
  • ADR-0014 names the Tinys cluster as the local operator substrate.
  • ADR-0028 names Azure as the cloud deployment target.
  • ADR-0034 names Flux as the GitOps portability layer from Tinys k3s to AKS or Azure Arc-enabled Kubernetes.
  • deploy/azure/ remains the validateable Azure artefact area.
  • tutorial/deployment/ is the local Kubernetes path that helps explain what changes when the runtime boundary becomes a cluster.

The important constraint is that k3s changes packaging and operations, not the platform architecture. The app contract and analytical contract keep the same meaning.

Azure remains the migration target when the Tinys cluster needs more compute, more VMs, or managed reliability. The first cloud step is reliability around the Tinys cluster, not moving workloads: offsite backups, external registry hosting, DNS, identity, object storage, and observability sinks can move first. Flux is the deployment-control bridge: it reconciles the Tinys cluster from Git first, then gives the enterprise Azure path a natural AKS + Flux lane.

What the code looks like

Section titled “What the code looks like”

The module begins with operator prose and narrow k3s manifests for the app-contract service, local data persistence, and the dlt/dbt batch Job:

  • README.md maps Kamal, k3s, and the rest of the repo back to one deployment decision: single-server deploy or cluster-shaped operation.
  • lesson-00-kamal-single-server-baseline.md is the plain-server baseline the Kubernetes lessons compare against.
  • lesson-01-k3s-local-cluster.md installs or attaches to the Tinys k3s cluster, creates the fos-workbench namespace, and maps Kubernetes objects to the tutorial vocabulary.
  • Kubernetes primer on the Tinys slows down the vocabulary: node, pod, Deployment, Service, Job, PVC, control plane, etcd, HA, quorum, Flux, GitRepository, Kustomization, snapshots, Azure, and power posture, all with Tinys examples.
  • tutorial-webserver.md documents the stable Spark-hosted tutorial webserver and the Spark tailnet URL used from the laptop.
  • lesson-02-app-contract-service.md deploys the FastAPI app contract as a Deployment and ClusterIP Service, using /healthz probes and leaving the persistent data/ story for the next lesson.
  • lesson-03-host-data-mount.md swaps the pod’s temporary empty data folder for the repo’s host data/ folder so /articles returns rows.
  • lesson-03-data-persistence.md mounts the same DuckDB-readable Parquet data/ paths into the k3s app-contract pod through a local PersistentVolumeClaim.
  • lesson-04-dlt-dbt-batch-job.md runs the existing dlt publisher loads and dbt build as a Kubernetes Job against the same local rehearsal PVC.
  • lesson-05-flux-gitops-portability.md moves durable cluster state into Flux and maps the Tinys GitOps path to Container Apps, AKS + Flux, and optional Azure Arc.
  • lesson-06-tinys-power-idle.md records the power-idle plan: measure first, scale workloads down in Git, and treat host tuning as a cautious follow-up.
  • k8s/app-contract.yaml is the first Kubernetes manifest in the tutorial path.
  • k8s/app-contract-local-data.yaml is the local rehearsal storage variant; Azure storage remains the ADLS Gen2 mapping named by ADR-0028.
  • k8s/dlt-dbt-job.yaml is the operator-run batch Job for refreshing the same DuckDB/Parquet data layout in k3s.
  • AGENTS.md tells future agents not to run live cluster-changing commands as routine verification.

After this module

Section titled “After this module”

Follow-up lessons should compare the k3s mapping with the Azure Container Apps and AKS + Flux lanes. Kubernetes should stay the runtime shape, not become a new analytical product.