Trey t
8d9ca2e6ed
Update the deployment book and glossary to reflect the goose-based schema migration flow shipped in 12b2f9d/0f7450a: - ch07: clarify startup probe assumes migrations ran out-of-band - ch08: drop AutoMigrate-with-advisory-lock prose; describe goose Job - ch12: pod startup checks goose_db_version, no longer runs migrations - ch14: document the Job→wait→roll deploy gate and how to debug failures - ch16: add "Migrate Job fails during deploy" + "Schema precondition failed" failure modes - ch17: new runbook entries §26 (run migrations manually), §27 (recover from failed/dirty migration), §28 (bootstrap goose on fresh clone) - ch19: postscript on §13 noting MigrateWithLock approach is superseded - ch20: mark "Migration Job for schema changes" task done - glossary: add `goose` and `goose_db_version`; flag AutoMigrate as tests-only - references: add goose links; flag AutoMigrate as tests-only
7.0 KiB
Appendix A — Glossary
Alphabetical. Cross-referenced to chapters where each term is used in detail.
Kubernetes / k3s
ClusterIP: Internal IP of a Kubernetes Service. Stable; load- balances to backing pods. (Chapter 3)
containerd: Container runtime bundled with k3s. Replaces Docker for the runtime layer. (Chapter 2)
ConfigMap: Kubernetes resource holding non-sensitive config (env
vars). Mounted into pods via envFrom. (Chapter 10)
CoreDNS: Cluster-internal DNS resolver. Every pod's
/etc/resolv.conf points to the CoreDNS Service. (Chapter 3)
CRD (Custom Resource Definition): Kubernetes extension mechanism
for third-party resource types. Traefik's IngressRoute and
Middleware are CRDs. (Chapter 6)
DaemonSet: Workload that runs exactly one pod per node. We use it for Traefik so each node has its own ingress pod. (Chapter 6)
Deployment: Kubernetes workload for stateless pods. Supports rolling updates. Most of our services are Deployments. (Chapter 7)
Endpoints: The actual pod IPs backing a Service's ClusterIP. Dynamically updated as pods come and go. (Chapter 3)
etcd: Distributed key-value store holding cluster state. K3s embeds it. Raft-replicated across server nodes. (Chapter 2)
Flannel: Kubernetes CNI (Container Network Interface) plugin for pod-to-pod networking. Uses VXLAN tunneling. (Chapter 3)
HPA (HorizontalPodAutoscaler): K8s resource that scales Deployment replicas based on CPU/memory usage. Not currently enabled for us. (Chapter 7)
Ingress: K8s resource describing external-to-internal routing rules. Traefik watches Ingresses and programs itself accordingly. (Chapter 6)
IPVS: Linux kernel feature for in-kernel L4 load balancing. Our kube-proxy uses it. (Chapter 3)
k3s: Lightweight Kubernetes distribution by Rancher/SUSE. What we run. (Chapter 2)
kubectl: Kubernetes CLI tool. Runs on operator workstation. (Chapter 17)
kubelet: Agent running on each node, responsible for pod lifecycle. (Chapter 2)
kube-proxy: Service-to-pod routing component. Runs on each node in IPVS mode. (Chapter 3)
Namespace: Kubernetes logical grouping. Our app lives in honeydue.
System services in kube-system. (Chapter 7)
NetworkPolicy: K8s resource defining allowed traffic between pods. Not currently applied. (Chapter 5)
Node: A physical or virtual machine running Kubernetes. We have 3. (Chapter 1)
PDB (PodDisruptionBudget): Constraint on voluntary pod disruptions (drain, upgrade). Keeps N replicas available. (Chapter 7)
Pod: Smallest Kubernetes unit — one or more containers sharing network and storage. Our pods are usually one-container. (Chapter 7)
PVC (PersistentVolumeClaim): Request for persistent storage. Redis uses one. (Chapter 7)
RBAC: Role-Based Access Control. Governs who/what can do what via the Kubernetes API. (Chapter 5)
ReplicaSet: Managed by a Deployment; ensures N pods of a template are running. Each deploy creates a new ReplicaSet. (Chapter 14)
Secret: K8s resource holding sensitive values. Base64-encoded; stored in etcd (unencrypted by default). (Chapter 10)
Service: K8s resource providing a stable endpoint (ClusterIP) for a set of pods. (Chapter 3)
ServiceAccount: Identity used by pods to authenticate to the Kubernetes API. We disable token mounting for our app pods. (Chapter 5)
Taint / Toleration: Mechanism to prevent pods from being scheduled on certain nodes. Not used in our setup. (Chapter 7)
Docker / Swarm
libnetwork: Docker's networking library. Provides overlay networking for Swarm. Source of the DNS ghost bug (Chapter 19).
mode: global: Swarm deploy mode for services running one pod per node. (Chapter 19)
mode: host: Port publishing mode that binds to node's real interface, bypassing the ingress mesh. (Chapter 4)
Overlay network: Encrypted or unencrypted virtual network spanning Swarm nodes. (Chapter 19)
Swarm: Docker's built-in orchestrator. What we used to run. (Chapter 19)
VXLAN: Virtual Extensible LAN. Layer-2 over Layer-3 tunneling. Used by both Swarm overlay and Kubernetes Flannel. (Chapter 3)
Cloudflare
Flexible SSL: CF SSL mode where CF↔origin is HTTP. Our current setup. (Chapter 13)
Full (strict) SSL: CF SSL mode where CF↔origin is HTTPS with cert verification. Our target. (Chapter 13)
Origin CA: CF-internal certificate authority that issues certs CF's edge trusts. Used for Full strict mode. (Chapter 13)
POP (Point of Presence): A CF edge location. ~300 globally. (Chapter 13)
Proxied (orange cloud): DNS record with CF proxying on. Traffic goes through CF. (Chapter 13)
Workers: CF's serverless compute at the edge. We don't use yet. (Chapter 20)
Hetzner
CX33: Hetzner Cloud instance type. 4 vCPU, 8 GB RAM, 80 GB SSD. (Chapter 1)
Cloud Firewall: Hetzner's provider-level firewall feature. We use UFW on nodes instead. (Chapter 4)
nbg1: Nuremberg datacenter code. Our region. (Chapter 1)
Neon
Branch: Neon's isolation primitive. Each project can have multiple branches (prod, staging, dev). (Chapter 8)
CU (Compute Unit): Neon's pricing unit for compute. (Chapter 8)
Launch plan: Neon's entry-level paid plan. $5 min + usage. (Chapter 8)
Pooler: Neon's built-in PgBouncer instance at the -pooler hostname
suffix. (Chapter 8)
Backblaze B2
B2: Backblaze's object storage. What we use for uploads. (Chapter 9)
App key: B2's bucket-scoped credential. Not an IAM-flavored role. (Chapter 9)
S3-compatible: API that speaks AWS S3 protocol. B2 supports it. (Chapter 9)
Go + Asynq
AutoMigrate: GORM function that syncs DB schema to Go structs.
We used this in production until 2026-04, replaced by goose. Tests
still use it via testutil.SetupTestDB. (Chapter 8)
Asynq: Go library for background job queues. Redis-backed. (Chapter 7)
goose: pressly/goose — the SQL migration tool we use in production
(commit 12b2f9d onward). Migration files live in migrations/, one
file per version with -- +goose Up / -- +goose Down markers.
(Chapter 8)
goose_db_version: goose's version-tracking table. One row per
applied migration. RequireSchemaApplied reads the latest row at
api/worker startup to fail fast on a stale schema. (Chapter 8)
GORM: Go ORM we use. (Chapter 8)
pgx: Go Postgres driver used by GORM. (Chapter 8)
sync.Once: Go stdlib primitive for "run this exactly once." Source of bug #6 (Chapter 19).
Other
advisory lock: A Postgres lock that doesn't block rows but lets apps coordinate voluntarily. We use for migration serialization. (Chapter 8)
AOF (Append-Only File): Redis persistence mode that logs every write. (Chapter 7)
MTU: Maximum Transmission Unit. Packet size limit. VXLAN reduces effective MTU by 50 bytes. (Chapter 3)
Raft: Consensus algorithm. Used by etcd. (Chapter 2)
STARTTLS: SMTP upgrade from plain to TLS. Used for Fastmail. (Chapter 5)
UFW: Uncomplicated Firewall. Frontend for iptables. (Chapter 4)
VXLAN: See Docker/Swarm section.