Show & Tell: Phase 8.4 — Docker/Helm containerisation deep-dive

[web3guru888]

Phase 8.4 — Docker/Helm: architecture walkthrough

This Show & Tell covers the containerisation and Kubernetes deployment design for ASI-Build Phase 8.4.

---

Component map

┌─────────────────────────────────────────────────────────────────────────┐
│  ASI-Build Deployment Stack (Phase 8.4)                                │
│                                                                         │
│  ┌─────────────────────┐    ┌───────────────────┐                      │
│  │   Dockerfile        │    │  docker-compose   │                      │
│  │  ┌───────────────┐  │    │  ┌─────────────┐  │                      │
│  │  │ Stage 0       │  │    │  │ asi-core    │  │                      │
│  │  │  builder      │  │    │  │ explain-api │  │                      │
│  │  │  pip install  │  │    │  │ prometheus  │  │                      │
│  │  │  compileall   │  │    │  │ grafana     │  │                      │
│  │  └───────┬───────┘  │    │  │ redis       │  │                      │
│  │          │ COPY     │    │  └─────────────┘  │                      │
│  │  ┌───────▼───────┐  │    └───────────────────┘                      │
│  │  │ Stage 1       │  │                                               │
│  │  │  runtime      │  │    ┌───────────────────────────────────────┐  │
│  │  │  uid=1000     │  │    │  Helm chart: charts/asi-build/        │  │
│  │  │  HEALTHCHECK  │  │    │  ┌──────────────┐  ┌───────────────┐  │  │
│  │  │  ≤350 MB      │  │    │  │ deployment   │  │ hpa           │  │  │
│  │  └───────────────┘  │    │  │ service      │  │ servicemonitor│  │  │
│  └─────────────────────┘    │  │ ingress      │  │ configmap     │  │  │
│                              │  └──────────────┘  └───────────────┘  │  │
│  ┌─────────────────────┐    └───────────────────────────────────────┘  │
│  │  .github/workflows  │                                               │
│  │  docker.yml         │    ┌───────────────────────────────────────┐  │
│  │  buildx multi-arch  │    │  Prometheus scrape                    │  │
│  │  helm lint          │    │  explain-api:8080/metrics             │  │
│  │  kind cluster test  │    │  asi-core:9100/metrics                │  │
│  │  docker scout CVE   │    └───────────────────────────────────────┘  │
│  └─────────────────────┘                                               │
└─────────────────────────────────────────────────────────────────────────┘

---

Why multi-stage Docker?

Concern	Single-stage	Multi-stage (our approach)
Image size	~900 MB (build tools included)	≤ 350 MB
Attack surface	gcc, pip, git all present	Runtime libs only
Build caching	Full rebuild on any change	Layer cache for pip install
Non-root	Manual setup required	useradd -u 1000 in stage 1

---

Healthcheck strategy

The HEALTHCHECK instruction in Dockerfile uses only stdlib (urllib.request) since the python:3.11-slim base image has no curl or wget.

HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
  CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8080/health')"

In Kubernetes, the same /health endpoint is reused for both livenessProbe and readinessProbe:

livenessProbe:
  httpGet: { path: /health, port: 8080 }
  initialDelaySeconds: 15
  periodSeconds: 20
readinessProbe:
  httpGet: { path: /health, port: 8080 }
  initialDelaySeconds: 5
  periodSeconds: 10

---

HPA autoscaling math

With targetCPUUtilizationPercentage: 70 and requests.cpu: 500m:

desiredReplicas = ceil(currentReplicas × currentCPU / targetCPU)
                = ceil(2 × 85% / 70%)
                = ceil(2.43)
                = 3

At peak (all 8 replicas): 8 × 500m = 4 CPU cores — fits in a 3-node cluster with 2 CPUs each.

---

Prometheus ServiceMonitor integration

The release: kube-prometheus-stack label on the ServiceMonitor must match the Prometheus Operator's serviceMonitorSelector. Check with:

kubectl get prometheus -n monitoring -o jsonpath="{.items[0].spec.serviceMonitorSelector}"
# expected: {"matchLabels":{"release":"kube-prometheus-stack"}}

All 5 Phase-8 metric families (DecisionTracer, CausalGraph, ExplainAPI, SleepOrchestrator, ReplayBuffer) are scraped via the single metrics port (9100 for core, 8080 for ExplainAPI).

---

Prometheus metrics added in Phase 8.4

Metric	Type	Description
asi_docker_build_duration_seconds	Histogram	Time taken for CI docker build
asi_image_size_bytes	Gauge	Final image size (pushed after build)
asi_helm_install_duration_seconds	Histogram	Time for helm upgrade --install
asi_pod_restarts_total	Counter	Pod restart events (liveness failures)
asi_hpa_replica_count	Gauge	Current HPA replica count

PromQL — pod restart alert

# Alert if any pod restarts > 3 times in 10 minutes
increase(asi_pod_restarts_total[10m]) > 3

---

Open questions

1. Base image: python:3.11-slim vs python:3.11-slim-bookworm — does the Debian version matter for security scanning?
2. Multi-arch: Is linux/arm64 required, or can we ship linux/amd64 only for Phase 8.4?
3. Helm registry: Should we push the chart to GHCR (oci://ghcr.io/...) or use a traditional Helm repo (gh-pages branch)?