Kubernetes Reference

Run the full Cloud Health Office platform on Docker Desktop Kubernetes — the same service shape, namespace, and reference manifests used for cloud-deployment evaluation. No Azure account needed.

What You Get

All services communicate over Kubernetes DNS (service-name.cloudhealthoffice) — the same service-discovery pattern used by the reference cloud deployment.

Prerequisites

1. Enable Kubernetes in Docker Desktop

# Verify context
kubectl config current-context
# Expected: docker-desktop

# Verify cluster
kubectl cluster-info
# Expected: Kubernetes control plane is running at https://127.0.0.1:6443

2. Configure Credentials (Optional)

cp .env.local.example .env.local
# Edit .env.local with your Azure AD app registration and Stripe test keys

3. Build & Deploy

./scripts/deploy-local.sh

watch kubectl get pods -n cloudhealthoffice

4. Access the Platform

# Portal (Blazor Server UI)
kubectl port-forward -n cloudhealthoffice svc/portal 8080:80

# Core API services
kubectl port-forward -n cloudhealthoffice svc/claims-service 5001:80
kubectl port-forward -n cloudhealthoffice svc/benefit-plan-service 5002:80
kubectl port-forward -n cloudhealthoffice svc/member-service 5003:80
kubectl port-forward -n cloudhealthoffice svc/provider-service 5004:80
kubectl port-forward -n cloudhealthoffice svc/eligibility-service 5005:80
kubectl port-forward -n cloudhealthoffice svc/payment-service 5006:80

# MongoDB (for direct access)
kubectl port-forward -n cloudhealthoffice svc/mongodb 27017:27017

5. Seed Demo Data & Test Adjudication

CLAIMS_URL=http://localhost:5001 \
BENEFIT_URL=http://localhost:5002 \
./scripts/seed-local.sh --tenant demo

6. Verify System Health

# All pods
kubectl get pods -n cloudhealthoffice

# All services
kubectl get svc -n cloudhealthoffice

# Portal logs
kubectl logs -n cloudhealthoffice -l app=portal --tail=50

# Claims service logs
kubectl logs -n cloudhealthoffice -l app=claims-service --tail=50

# Find errors across all services
kubectl logs -n cloudhealthoffice --all-containers --tail=20 | grep -i error

How This Maps to a Cloud Deployment

Common Tasks

Rebuild and redeploy a single service

# Rebuild just the claims service
docker build -t clouhealthoffice.azurecr.io/cloudhealthoffice-claims-service:latest \
  -f src/services/claims-service/Dockerfile .

# Restart the deployment to pick up the new image
kubectl rollout restart deployment/claims-service -n cloudhealthoffice
kubectl rollout status deployment/claims-service -n cloudhealthoffice

Connect to MongoDB

kubectl port-forward -n cloudhealthoffice svc/mongodb 27017:27017

# In another terminal:
mongosh "mongodb://admin:localdev123@localhost:27017/?authSource=admin"

Scale a service

kubectl scale deployment/claims-service -n cloudhealthoffice --replicas=3

Apply a manifest change

kubectl apply -f src/services/claims-service/k8s/claims-service-deployment.yaml

Troubleshooting

Pods stuck in ImagePullBackOff

Images are built locally but the manifest says imagePullPolicy: Always. The deploy script patches this automatically. If you applied a manifest manually:

kubectl patch deployment claims-service -n cloudhealthoffice \
  -p '{"spec":{"template":{"spec":{"containers":[{"name":"claims-service","imagePullPolicy":"IfNotPresent"}]}}}}'

Pods in CrashLoopBackOff

Usually a missing secret or MongoDB not ready yet:

# Check what's failing
kubectl describe pod -n cloudhealthoffice -l app=claims-service
kubectl logs -n cloudhealthoffice -l app=claims-service --previous

# Verify secrets exist
kubectl get secrets -n cloudhealthoffice

MongoDB not starting

kubectl describe statefulset mongodb -n cloudhealthoffice
kubectl logs -n cloudhealthoffice mongodb-0

If PVC issues on Docker Desktop: Settings > Kubernetes > Reset Kubernetes Cluster.

Port-forward drops

Port-forwards disconnect when pods restart. Re-run the command, or use kubefwd for automatic forwarding.

Services can't reach each other

kubectl run -n cloudhealthoffice dns-test --rm -it --image=busybox -- \
  nslookup claims-service.cloudhealthoffice

Docker Desktop running slow

Increase resources in Docker Desktop > Settings > Resources: 4+ CPU cores, 8+ GB memory.

Tear Down

Stop local workloads (keep the MongoDB PVC)

kubectl scale deployment --all --replicas=0 -n cloudhealthoffice
kubectl scale statefulset mongodb --replicas=0 -n cloudhealthoffice

The PVC remains while the workloads are scaled down. Re-run ./scripts/deploy-local.sh --skip-build to restore the local manifests and replica counts.

Full reset (delete everything including data)

kubectl delete namespace cloudhealthoffice
docker volume prune -f

Deleting the namespace requests deletion of namespaced PVCs. Whether an underlying volume remains depends on the storage class reclaim policy; do not treat it as recoverable unless an independent backup has been tested.

Next Steps