# upcloudltd/sample-uks-microservices architecture

> Architecture diagram of the GitHub repository upcloudltd/sample-uks-microservices, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/upcloudltd/sample-uks-microservices
- Repository: https://github.com/upcloudltd/sample-uks-microservices

## Overview

#### 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`

Main entry points: [`infra/core/main.tf`](https://github.com/upcloudltd/sample-uks-microservices/blob/main/infra/core/main.tf) (Core Terraform), [`infra/core/database.tf`](https://github.com/upcloudltd/sample-uks-microservices/blob/main/infra/core/database.tf) (Managed Postgres), [`infra/core/monitoring.tf`](https://github.com/upcloudltd/sample-uks-microservices/blob/main/infra/core/monitoring.tf) (Monitoring VM stack), [`infra/core/queueing.tf`](https://github.com/upcloudltd/sample-uks-microservices/blob/main/infra/core/queueing.tf) (Managed RabbitMQ)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_infra["Terraform infrastructure"]
  node_core_tf["Core Terraform<br/>Terraform root<br/>[main.tf]"]
  node_network{{"Private network and NAT<br/>Terraform resources<br/>[network.tf]"}}
  node_uks{{"UKS cluster<br/>managed Kubernetes<br/>[uks.tf]"}}
  node_postgres[("Managed Postgres<br/>database<br/>[database.tf]")]
  node_rabbitmq["Managed RabbitMQ<br/>message queue<br/>[queueing.tf]"]
  node_core_outputs["Infrastructure outputs<br/>Terraform outputs<br/>[outputs.tf]"]
  node_addons_tf["Addon Terraform<br/>Terraform providers<br/>[k8s_providers.tf]"]
  node_remote_state["Core remote state<br/>Terraform state input<br/>[remote_state.tf]"]
end

subgraph group_runtime["UKS application runtime"]
  node_deploy["Application deploy<br/>shell script<br/>[deploy.sh]"]
  node_manifests["API and worker workloads<br/>Kubernetes manifests<br/>[app-demo.yaml]"]
  node_migration["Database migration job<br/>Kubernetes Job"]
  node_api["Orders API<br/>Go container service<br/>[main.go]"]
  node_worker["Orders worker<br/>Go container worker<br/>[main.go]"]
end

subgraph group_observability["Observability"]
  node_monitoring_vm["Monitoring VM stack<br/>Docker observability stack<br/>[monitoring.tf]"]
  node_promtail["In-cluster Promtail<br/>log collector<br/>[k8s_promtail.tf]"]
  node_kube_state["Kube-state-metrics<br/>cluster metrics collector"]
end

node_makefile["Operator commands<br/>Makefile"]
node_smoke["End-to-end smoke flow<br/>shell script<br/>[smoke.sh]"]

node_makefile -->|"provisions"| node_core_tf
node_makefile -->|"runs"| node_smoke
node_smoke -->|"deploys and verifies"| node_deploy
node_core_tf -->|"creates"| node_network
node_core_tf -->|"creates"| node_uks
node_core_tf -->|"creates"| node_postgres
node_core_tf -->|"creates"| node_rabbitmq
node_core_tf -->|"creates"| node_monitoring_vm
node_core_tf -->|"exports"| node_core_outputs
node_network -->|"private connectivity"| node_uks
node_core_outputs -->|"kubeconfig and connection values"| node_deploy
node_core_outputs -->|"consumed by"| node_remote_state
node_remote_state -->|"configures"| node_addons_tf
node_addons_tf -->|"installs"| node_promtail
node_addons_tf -->|"installs"| node_kube_state
node_deploy -->|"renders and applies"| node_manifests
node_deploy -->|"applies"| node_migration
node_manifests -->|"runs"| node_api
node_manifests -->|"runs"| node_worker
node_api -->|"publishes orders"| node_rabbitmq
node_api -->|"reads orders"| node_postgres
node_rabbitmq -->|"delivers orders"| node_worker
node_worker -->|"inserts orders"| node_postgres
node_migration -->|"migrates schema"| node_postgres
node_promtail -->|"forwards logs to Loki"| node_monitoring_vm
node_kube_state -->|"exposes cluster metrics"| node_monitoring_vm
node_postgres -->|"exporter metrics"| node_monitoring_vm
node_rabbitmq -->|"exporter metrics"| node_monitoring_vm

click node_makefile "https://github.com/upcloudltd/sample-uks-microservices/blob/main/Makefile"
click node_smoke "https://github.com/upcloudltd/sample-uks-microservices/blob/main/smoke/smoke.sh"
click node_core_tf "https://github.com/upcloudltd/sample-uks-microservices/blob/main/infra/core/main.tf"
click node_network "https://github.com/upcloudltd/sample-uks-microservices/blob/main/infra/core/network.tf"
click node_uks "https://github.com/upcloudltd/sample-uks-microservices/blob/main/infra/core/uks.tf"
click node_postgres "https://github.com/upcloudltd/sample-uks-microservices/blob/main/infra/core/database.tf"
click node_rabbitmq "https://github.com/upcloudltd/sample-uks-microservices/blob/main/infra/core/queueing.tf"
click node_core_outputs "https://github.com/upcloudltd/sample-uks-microservices/blob/main/infra/core/outputs.tf"
click node_addons_tf "https://github.com/upcloudltd/sample-uks-microservices/blob/main/infra/addons/k8s_providers.tf"
click node_remote_state "https://github.com/upcloudltd/sample-uks-microservices/blob/main/infra/addons/remote_state.tf"
click node_deploy "https://github.com/upcloudltd/sample-uks-microservices/blob/main/app/deploy.sh"
click node_manifests "https://github.com/upcloudltd/sample-uks-microservices/blob/main/app/k8s/app-demo.yaml"
click node_migration "https://github.com/upcloudltd/sample-uks-microservices/blob/main/app/k8s/orders-migrate-job.yaml"
click node_api "https://github.com/upcloudltd/sample-uks-microservices/blob/main/app/orders-api/main.go"
click node_worker "https://github.com/upcloudltd/sample-uks-microservices/blob/main/app/orders-worker/main.go"
click node_monitoring_vm "https://github.com/upcloudltd/sample-uks-microservices/blob/main/infra/core/monitoring.tf"
click node_promtail "https://github.com/upcloudltd/sample-uks-microservices/blob/main/infra/addons/k8s_promtail.tf"
click node_kube_state "https://github.com/upcloudltd/sample-uks-microservices/blob/main/infra/addons/k8s-state-metric.tf"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_core_tf,node_network,node_uks,node_postgres,node_rabbitmq,node_core_outputs,node_addons_tf,node_remote_state toneBlue
class node_deploy,node_manifests,node_migration,node_api,node_worker toneAmber
class node_monitoring_vm,node_promtail,node_kube_state toneMint
class node_makefile,node_smoke toneNeutral
```

## Components

### Terraform infrastructure

- [Core Terraform](https://github.com/upcloudltd/sample-uks-microservices/blob/main/infra/core/main.tf): Terraform root · Provisions the private UKS environment and managed dependencies. · `infra/core/main.tf`
- [Private network and NAT](https://github.com/upcloudltd/sample-uks-microservices/blob/main/infra/core/network.tf): Terraform resources · Private UKS nodes use NAT-backed outbound access and firewalling. · `infra/core/network.tf`
- [UKS cluster](https://github.com/upcloudltd/sample-uks-microservices/blob/main/infra/core/uks.tf): managed Kubernetes · `infra/core/uks.tf`
- [Managed Postgres](https://github.com/upcloudltd/sample-uks-microservices/blob/main/infra/core/database.tf): database · System of record for orders. · `infra/core/database.tf`
- [Managed RabbitMQ](https://github.com/upcloudltd/sample-uks-microservices/blob/main/infra/core/queueing.tf): message queue · Durable asynchronous orders boundary. · `infra/core/queueing.tf`
- [Infrastructure outputs](https://github.com/upcloudltd/sample-uks-microservices/blob/main/infra/core/outputs.tf): Terraform outputs · Publishes kubeconfig, AMQP URL, Postgres DSN, and Grafana URL. · `infra/core/outputs.tf`
- [Addon Terraform](https://github.com/upcloudltd/sample-uks-microservices/blob/main/infra/addons/k8s_providers.tf): Terraform providers · Configures cluster-resident observability after core provisioning. · `infra/addons/k8s_providers.tf`
- [Core remote state](https://github.com/upcloudltd/sample-uks-microservices/blob/main/infra/addons/remote_state.tf): Terraform state input · `infra/addons/remote_state.tf`

### UKS application runtime

- [Application deploy](https://github.com/upcloudltd/sample-uks-microservices/blob/main/app/deploy.sh): shell script · Injects images and infrastructure connection values into manifests. · `app/deploy.sh`
- [API and worker workloads](https://github.com/upcloudltd/sample-uks-microservices/blob/main/app/k8s/app-demo.yaml): Kubernetes manifests · Deploys workloads into the app-demo namespace. · `app/k8s/app-demo.yaml`
- [Database migration job](https://github.com/upcloudltd/sample-uks-microservices/blob/main/app/k8s/orders-migrate-job.yaml): Kubernetes Job · `app/k8s/orders-migrate-job.yaml`
- [Orders API](https://github.com/upcloudltd/sample-uks-microservices/blob/main/app/orders-api/main.go): Go container service · Serves UI and /orders requests; publishes orders and reads history. · `app/orders-api/main.go`
- [Orders worker](https://github.com/upcloudltd/sample-uks-microservices/blob/main/app/orders-worker/main.go): Go container worker · Consumes submitted orders and persists them. · `app/orders-worker/main.go`

### Observability

- [Monitoring VM stack](https://github.com/upcloudltd/sample-uks-microservices/blob/main/infra/core/monitoring.tf): Docker observability stack · Hosts Grafana, Prometheus, Loki, and dependency exporters. · `infra/core/monitoring.tf`
- [In-cluster Promtail](https://github.com/upcloudltd/sample-uks-microservices/blob/main/infra/addons/k8s_promtail.tf): log collector · Tails container logs and forwards them to Loki. · `infra/addons/k8s_promtail.tf`
- [Kube-state-metrics](https://github.com/upcloudltd/sample-uks-microservices/blob/main/infra/addons/k8s-state-metric.tf): cluster metrics collector · `infra/addons/k8s-state-metric.tf`

### Other components

- [Operator commands](https://github.com/upcloudltd/sample-uks-microservices/blob/main/Makefile): Makefile · Coordinates provisioning, deployment, smoke testing, and teardown. · `Makefile`
- [End-to-end smoke flow](https://github.com/upcloudltd/sample-uks-microservices/blob/main/smoke/smoke.sh): shell script · Optionally provisions, deploys, exercises orders, and destroys resources. · `smoke/smoke.sh`

## Connections

- 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
