How upcloudltd/sample-uks-microservices works
Purpose and Entry Points
This is an UpCloud Kubernetes Service (UKS) reference deployment: Terraform provisions a private Kubernetes environment and supporting services; two Go services implement an asynchronous orders flow. Primary operator entry points are Makefile, app/deploy.sh, infra/core/main.tf, infra/addons/k8s_providers.tf, and smoke/smoke.sh. Both app/ and infra/ are Git submodules.
Core Infrastructure Provisioning
Terraform’s core layer creates the UKS cluster, private networking, NAT-backed outbound access, firewalling, storage, database, queueing, and monitoring resources. UKS nodes intentionally lack public IPs; external access is mediated by the network/NAT design.
• infra/core/main.tf
• infra/core/network.tf
• infra/core/uks.tf
• infra/core/database.tf
• infra/core/queueing.tf
Core outputs supply the application boundary values: kubeconfig, RabbitMQ AMQP URL, Postgres DSN, and Grafana URL.
• infra/core/outputs.tf
• infra/core/locals.tf
Orders Application Runtime
The application consists of independently built Go container images. The API exposes an HTML/UI and /orders HTTP endpoints; it publishes submitted orders to RabbitMQ and reads persisted orders. The worker consumes queued messages and inserts orders into Postgres.
• app/orders-api/main.go
• app/orders-api/Dockerfile
• app/orders-worker/main.go
• app/orders-worker/Dockerfile
This separates synchronous request handling from durable background persistence, with RabbitMQ as the explicit asynchronous boundary and managed Postgres as the system of record.
Kubernetes Deployment Boundary
app/deploy.sh injects deployment-time environment values—image references, AMQP URL, and Postgres DSN—into Kubernetes manifests and applies them to the app-demo namespace. The workload manifests define the API and worker deployment/service topology; database migration is modeled as a Kubernetes job.
• app/deploy.sh
• app/k8s/app-demo.yaml
• app/k8s/orders-migrate-job.yaml
• app/k8s/orders-api-metrics-nodeport.yaml
Container images are built and pushed externally by the operator to a registry reachable by private UKS nodes; registry hosting is not provisioned here.
Observability Pipeline
A monitoring VM hosts Docker-based Grafana, Prometheus, Loki, and exporters for infrastructure dependencies. Kubernetes addon Terraform configures in-cluster Promtail to tail container logs and forward them to Loki, plus kube-state-metrics for cluster-state metrics.
• infra/core/monitoring.tf
• infra/addons/k8s_promtail.tf
• infra/addons/k8s-state-metric.tf
• infra/addons/kube-state-metrics-nodeport.tf
This creates two collection boundaries: VM-hosted exporters for Postgres/RabbitMQ/node metrics, and cluster-resident Promtail/kube-state-metrics for Kubernetes telemetry.
Lifecycle and Verification
Provisioning order is core Terraform, then addon Terraform; teardown reverses this order due to addon dependency on the cluster and core remote state. Deployment follows infrastructure outputs and image publication. The smoke script is the end-to-end control path, optionally applying infrastructure, deploying, exercising API → queue → worker → database, and optionally destroying resources.
• infra/addons/remote_state.tf
• smoke/smoke.sh
• Makefile
Components 18
Terraform infrastructure
- Core Terraform · Provisions the private UKS environment and managed dependencies.
infra/core/main.tf - Private network and NAT · Private UKS nodes use NAT-backed outbound access and firewalling.
infra/core/network.tf - UKS cluster
infra/core/uks.tf - Managed Postgres · System of record for orders.
infra/core/database.tf - Managed RabbitMQ · Durable asynchronous orders boundary.
infra/core/queueing.tf - Infrastructure outputs · Publishes kubeconfig, AMQP URL, Postgres DSN, and Grafana URL.
infra/core/outputs.tf - Addon Terraform · Configures cluster-resident observability after core provisioning.
infra/addons/k8s_providers.tf - Core remote state
infra/addons/remote_state.tf
UKS application runtime
- Application deploy · Injects images and infrastructure connection values into manifests.
app/deploy.sh - API and worker workloads · Deploys workloads into the app-demo namespace.
app/k8s/app-demo.yaml - Database migration job
app/k8s/orders-migrate-job.yaml - Orders API · Serves UI and /orders requests; publishes orders and reads history.
app/orders-api/main.go - Orders worker · Consumes submitted orders and persists them.
app/orders-worker/main.go
Observability
- Monitoring VM stack · Hosts Grafana, Prometheus, Loki, and dependency exporters.
infra/core/monitoring.tf - In-cluster Promtail · Tails container logs and forwards them to Loki.
infra/addons/k8s_promtail.tf - Kube-state-metrics
infra/addons/k8s-state-metric.tf
Other components
- Operator commands · Coordinates provisioning, deployment, smoke testing, and teardown.
Makefile - End-to-end smoke flow · Optionally provisions, deploys, exercises orders, and destroys resources.
smoke/smoke.sh
Connections 28
- Operator commands → Core Terraform: provisions
- Operator commands → End-to-end smoke flow: runs
- End-to-end smoke flow → Application deploy: deploys and verifies
- Core Terraform → Private network and NAT: creates
- Core Terraform → UKS cluster: creates
- Core Terraform → Managed Postgres: creates
- Core Terraform → Managed RabbitMQ: creates
- Core Terraform → Monitoring VM stack: creates
- Core Terraform → Infrastructure outputs: exports
- Private network and NAT → UKS cluster: private connectivity
- Infrastructure outputs → Application deploy: kubeconfig and connection values
- Infrastructure outputs → Core remote state: consumed by
- Core remote state → Addon Terraform: configures
- Addon Terraform → In-cluster Promtail: installs
- Addon Terraform → Kube-state-metrics: installs
- Application deploy → API and worker workloads: renders and applies
- Application deploy → Database migration job: applies
- API and worker workloads → Orders API: runs
- API and worker workloads → Orders worker: runs
- Orders API → Managed RabbitMQ: publishes orders
- Orders API → Managed Postgres: reads orders
- Managed RabbitMQ → Orders worker: delivers orders
- Orders worker → Managed Postgres: inserts orders
- Database migration job → Managed Postgres: migrates schema
- In-cluster Promtail → Monitoring VM stack: forwards logs to Loki
- Kube-state-metrics → Monitoring VM stack: exposes cluster metrics
- Managed Postgres → Monitoring VM stack: exporter metrics
- Managed RabbitMQ → Monitoring VM stack: exporter metrics