Glossary
Plain-language definitions for everything used in this guide. Future-you will thank present-you. Terms are alphabetical.
The protocol Let’s Encrypt uses to issue TLS certificates automatically. The server proves it controls a domain (see HTTP-01), and gets a cert in return.
AnalysisTemplate
Section titled “AnalysisTemplate”An Argo Rollouts resource that defines a metric query (e.g. “success rate ≥ 95%”) used to automatically pass or fail a canary.
Argo CD
Section titled “Argo CD”The GitOps engine. It watches a Git repo and continuously makes the cluster match it. If Git and the cluster differ, Argo CD applies the difference.
Argo Rollouts
Section titled “Argo Rollouts”A controller that replaces a plain Kubernetes Deployment with smarter rollout strategies — here, a canary that shifts traffic gradually and checks metrics.
barman / barman-cloud
Section titled “barman / barman-cloud”The backup tool CNPG uses to push Postgres base backups and WAL to object storage (S3-compatible).
Canary
Section titled “Canary”A deployment strategy: send a small slice of traffic to the new version first, check it’s healthy (via metrics), then ramp up — or roll back automatically if it’s bad.
cert-manager
Section titled “cert-manager”A Kubernetes controller that obtains and auto-renews TLS certificates (from Let’s Encrypt) and stores them as Secrets for Traefik to serve.
CloudNativePG — the Postgres operator. You declare a Cluster resource;
CNPG provisions and manages the actual Postgres pods, failover, backups, and a connection
Secret.
CR / CRD
Section titled “CR / CRD”Custom Resource — a Kubernetes object type added by an operator (e.g. a
CNPG Cluster, a Keycloak Keycloak). CRD = Custom Resource Definition, the schema
that registers that new type.
Destination NAT — a firewall (iptables) rule that rewrites a packet’s destination. k3s’s ServiceLB uses it to grab host ports 80/443, which can silently bypass other host services.
GitHub Container Registry (ghcr.io) — where CI publishes the app’s container images for
the cluster to pull.
GitOps
Section titled “GitOps”The core idea: Git is the desired state; a controller continuously reconciles the
cluster to match. You change infrastructure by committing YAML, not by running
kubectl commands by hand.
A package manager for Kubernetes (installs apps as versioned “charts”). Used here to bootstrap the platform layer (cert-manager, Prometheus, Argo).
HTTP-01
Section titled “HTTP-01”An ACME challenge type: Let’s Encrypt verifies you own a domain by fetching a
token from http://<domain>/.well-known/... on port 80. Needs public DNS + port 80
open.
Ingress
Section titled “Ingress”A Kubernetes object that maps a hostname/path to a Service. Traefik reads Ingress objects and routes external traffic accordingly.
A lightweight, single-binary Kubernetes distribution — ideal for one small node. Bundles Traefik and a load balancer.
Keycloak
Section titled “Keycloak”The identity provider (auth server). Issues tokens to apps via OIDC/PKCE; apps validate those tokens. Runs in-cluster, managed by its operator.
kubectl
Section titled “kubectl”The command-line tool for talking to the Kubernetes API (inspect/apply/delete resources).
Namespace
Section titled “Namespace”A virtual partition inside a cluster that isolates a group of resources (e.g. the
penvoice namespace holds that app’s pods, Postgres, and Secrets).
OpenID Connect — the identity layer on top of OAuth2 that Keycloak speaks. Apps get a signed token proving who the user is.
Operator
Section titled “Operator”Software that extends Kubernetes to manage a complex app for you: you declare a CR (“I want a Postgres cluster”), the operator does the work and keeps it healthy. Think “robot DBA/admin.”
Point-In-Time Recovery — restoring a database to any moment within a retention window, by replaying WAL on top of a base backup.
Proof Key for Code Exchange — the secure OAuth2 flow for browser apps (no client secret in the browser). The web app uses it to log in against Keycloak.
Prometheus
Section titled “Prometheus”The metrics database. It scrapes /metrics from apps; Argo Rollouts
queries it to decide if a canary is healthy.
Reconcile
Section titled “Reconcile”The continuous loop where a controller compares desired state (Git) to actual state (cluster) and applies the difference. The heart of GitOps.
Secret (Kubernetes)
Section titled “Secret (Kubernetes)”An object holding sensitive data (passwords, keys). Referenced by pods at runtime. Rule here: secret values never live in Git — they’re created out-of-band or sealed.
ServiceLB (klipper)
Section titled “ServiceLB (klipper)”k3s’s built-in load balancer (its internal name is “klipper”). It claims host ports 80/443 (via DNAT) and forwards them to Traefik. (Cause of a classic “who owns port 443?” gotcha.)
AWS Signature Version 4 — how S3 (and S3-compatible stores like Oracle) authenticate requests. Sensitive to correct keys and region.
Tailscale
Section titled “Tailscale”A mesh VPN. Here it makes the Kubernetes API reachable privately from your laptops — the API port (6443) is never exposed publicly.
Transport Layer Security — the encryption behind HTTPS. cert-manager obtains the certs; Traefik terminates TLS at the edge.
Traefik
Section titled “Traefik”The reverse proxy / Ingress controller bundled with k3s. The platform’s single “front door”: it terminates TLS and routes every hostname to the right Service.
Write-Ahead Log — Postgres’s stream of every change. Archiving it continuously enables PITR: replay the WAL to reach any point in time.