21: Infrastructure Reference & Glossary¶
This section serves as a complete reference guide for all infrastructure components, terminology, commands, and system diagrams used throughout the LocalCloudLab platform.
It is designed as a quick lookup manual, summarizing everything in a structured, easy-to-find format.
21.1 High-Level Architecture Diagram (Textual Representation)¶
LocalCloudLab Platform:
┌───────────────────────────────────────────────────────────────┐
│ Client / Browser │
└───────────────────────────────────────────────────────────────┘
│ HTTPS (TLS via Envoy)
▼
┌───────────────────────────────────────────────────────────────┐
│ Envoy Gateway (L7 LB) │
└───────────────────────────────────────────────────────────────┘
│ Routes to services via HTTPRoutes
▼
┌───────────────────────────┬────────────────────────────────────┐
│ Search.API │ Checkin.API │
│ Namespace: search │ Namespace: checkin │
└───────────────────────────┴────────────────────────────────────┘
│ │
▼ ▼
┌───────────────────────────────┬────────────────────────────────┐
│ PostgreSQL (db namespace) │ Redis (caching namespace) │
└───────────────────────────────┴────────────────────────────────┘
│ │
▼ ▼
RabbitMQ (messaging namespace) Jaeger/Loki/Grafana
(monitoring)
21.2 Namespaces Summary¶
Namespace Purpose
search Search.Api deployment, Service, Config, HPA, PDB, secrets checkin Checkin.Api deployment, Service, Config, HPA, PDB, secrets db PostgreSQL StatefulSet, PVCs, backups caching Redis StatefulSet, PVCs, cluster config messaging RabbitMQ StatefulSet, PVCs, definitions infra MetalLB, cert-manager, gateway config monitoring prometheus, grafana, loki, promtail, tempo/jaeger default Empty / unused for production workloads
21.3 Core Kubernetes Objects Used in LocalCloudLab¶
Object Type Purpose ------------------ -------------------------------------------------------------- Deployment Runs stateless apps (Search.Api, Checkin.Api) StatefulSet Runs stateful systems (PostgreSQL, Redis, RabbitMQ) Service Internal networking abstraction (ClusterIP) HTTPRoute Envoy Gateway routing rules Gateway Entry point for external traffic ConfigMap Non-sensitive configuration Secret Sensitive data (connection strings, passwords) HPA Horizontal scaling rules PDB Ensures minimum pod availability PVC Storage volumes for DB/Redis/RabbitMQ CronJob Scheduled backups or tasks BackendPolicy Envoy retries, timeouts, circuit breaking
21.4 Observability Components¶
Component Purpose
Grafana Visualization & dashboards Loki Log database (JSON logs from Serilog) Promtail Collects logs from containers → sends to Loki Prometheus Metrics collection (CPU, RAM, service metrics) Tempo/Jaeger Distributed tracing (OpenTelemetry) OTel SDK .NET instrumentation (HTTP, EF, Redis, custom spans)
21.5 Networking Components¶
Component Purpose
MetalLB LoadBalancer IP for k3s cluster Envoy Gateway Entry point, routing, TLS termination NetworkPolicy Pod-to-pod communication restrictions ClusterIP Exposes services internally ExternalDNS (Optional) Auto-manages DNS records
21.6 Storage Components¶
Component Purpose
PVC Persistent storage allocation StorageClass Defines storage backend (local-path) PostgreSQL PVC Durable DB storage Redis PVC Cache persistence (RDB/AOF) RabbitMQ PVC Queue durability
21.7 Secrets & Encryption Glossary¶
Term Meaning
Base64 Encoding only — NOT encryption Encryption-at-rest Encrypt secrets in k3s on disk Sealed Secret Encrypted secret safe to store in Git SecretRef Reference to Kubernetes Secret in Deployment VolumeMount Mounting secrets/config as files
21.8 CI/CD Glossary¶
Term Meaning
GHCR GitHub Container Registry GitHub Actions CI/CD engine Path Filter Only triggers pipeline when certain folders change KUBECONFIG_B64 Base64 kubeconfig stored as GitHub secret docker build/push Builds and uploads images to registry kubectl set image Rolling update of Deployment
CI/CD Pipelines in LocalCloudLab:
• search-api-deploy.yml
• checkin-api-deploy.yml
• infra-deploy.yml
21.9 Common Troubleshooting Commands¶
Pods & Deployments¶
kubectl get pods -A
kubectl describe pod <name> -n <ns>
kubectl logs <pod>
kubectl rollout status deployment/<name> -n <ns>
HPAs¶
kubectl get hpa -n search
kubectl describe hpa search-api-hpa
Services & Routes¶
kubectl get svc -A
kubectl get httproutes -A
kubectl describe httproute <name> -n <ns>
Persistent Storage¶
kubectl get pvc -A
kubectl describe pvc <name> -n <ns>
Secrets¶
kubectl get secrets -A
kubectl describe secret <name> -n <ns>
Logs & Traces¶
Check logs: {app="search-api"} |= "error"
Check traces: Search API panel → click “View Trace”
21.10 Glossary of Key Terms¶
Term Definition
Pod Smallest unit of deployment in Kubernetes Deployment Controller for stateless apps StatefulSet Controller for stateful apps requiring stable IDs Service Network abstraction inside the cluster ClusterIP Default service type (internal only) LoadBalancer Exposes service externally using MetalLB Ingress/Gateway Routes external traffic into the cluster HTTPRoute Envoy Gateway routing object Namespace Logical partition of resources ConfigMap Non-sensitive configuration Secret Sensitive configuration (passwords) PVC PersistentVolumeClaim — allocated storage HPA Horizontal Pod Autoscaler PDB PodDisruptionBudget TLS Transport Layer Security (HTTPS) OTel OpenTelemetry tracing/metrics/logging standard Loki Log storage Promtail Log collector Grafana Dashboards and analytics
21.11 LocalCloudLab Infrastructure Summary Diagram (Text Version)¶
+--------------------------------------------------------------+
| External Clients |
+----------------------------+---------------------------------+
|
HTTPS (TLS)
|
+---------------------+
| Envoy Gateway |
+---------------------+
|¶
| |
+-------------+ +-------------+
| Search API | | Checkin API |
+-------------+ +-------------+
| |
| |
+-------------+ +-------------+
| PostgreSQL | | Redis |
+-------------+ +-------------+
\ //
\ //
+------------------------+
| RabbitMQ Bus |
+------------------------+
|
+----------------------+
| Observability Stack |
| Grafana, Loki, Tempo |
+----------------------+
21.12 Summary of Section 21¶
This section provided a complete reference guide, including:
✔ Architecture overview
✔ Namespaces & components
✔ Kubernetes resource glossary
✔ Observability glossary
✔ CI/CD glossary
✔ Troubleshooting commands
✔ Infrastructure diagrams
✔ Security terminology
This is the quick-reference “cheat sheet” for anyone operating or developing LocalCloudLab.
Next section (automatically continuing):
Section 22 — Final Notes, Future Improvements & Expansion Roadmap