Energy Service

A Kubernetes learning project demonstrating production-grade infrastructure setup and deployment patterns using Go and Kind (Kubernetes in Docker).

This project focuses on Kubernetes orchestration, containerization, and observability rather than application logic - featuring a minimal Go service with health checks, structured logging, and runtime profiling capabilities deployed to a local K8s cluster.

🎯 Project Focus

• Kubernetes Infrastructure: Complete K8s setup with namespaces, deployments, services, and probes
• Local Development: Kind-based cluster for rapid iteration
• Observability: Integrated pprof and statsviz for runtime monitoring
• Production Patterns: Graceful shutdown, health checks, structured logging
• Containerization: Multi-stage Docker builds with non-root user

🏗️ Architecture

├── api/services/          # Minimal Go HTTP service
│   ├── main.go           # Service entry point with graceful shutdown
│   ├── debug/            # Debug endpoints (pprof, statsviz)
│   └── server/           # Health check endpoints (liveness/readiness)
├── infra/
│   ├── k8s/              # Kubernetes manifests
│   │   ├── base.yaml     # Deployment, Service, Namespace
│   │   ├── kind-config.yaml
│   │   └── kustomization.yaml
│   └── docker/           # Multi-stage Dockerfile
└── platform/
    ├── logger/           # Structured logging (slog-based)
    └── web/              # HTTP utilities

🚀 Quick Start

Prerequisites

• Docker
• Kind
• kubectl
• Go 1.21+

Deploy to Kubernetes

1. Build the Docker image

   make all

2. Create Kind cluster

   make dev-up

3. Load image into cluster

   make dev-load

4. Deploy to Kubernetes

   make dev-apply

5. Verify deployment

   kubectl get pods -n ns-energy-europe
   kubectl logs -n ns-energy-europe -l app=energy --all-containers=true -f

Local Development

Run the service directly (without K8s):

make run

Access endpoints:

• Debug Dashboard: http://localhost:3011/debug/statsviz/
• Profiling: http://localhost:3011/debug/pprof/
• Liveness: http://localhost:3000/liveness
• Readiness: http://localhost:3000/readiness

📋 Available Commands

Command	Description
make all	Build Docker image
make dev-up	Create Kind cluster
make dev-load	Load image into Kind
make dev-apply	Apply K8s manifests
make dev-down	Delete Kind cluster
make dev-status	Check pod status
make dev-logs	Stream pod logs
make dev-restart	Restart deployment
make run	Run service locally

🔍 Kubernetes Features Demonstrated

• Namespaces: Isolated environment (ns-energy-europe)
• Deployments: Declarative pod management
• Services: Internal service discovery
• Health Probes: Liveness and readiness checks
• Resource Management: CPU/memory limits via Kustomize patches
• Port Forwarding: Local access to cluster services
• Graceful Shutdown: SIGTERM handling with 60s grace period

📝 Configuration

Service configuration via environment variables (prefix: ENERGY_):

• ENERGY_WEB_API_HOST: API server address (default: 0.0.0.0:3000)
• ENERGY_WEB_DEBUG_HOST: Debug server address (default: 0.0.0.0:3011)
• ENERGY_WEB_READ_TIMEOUT: Read timeout (default: 5s)
• ENERGY_WEB_WRITE_TIMEOUT: Write timeout (default: 10s)
• ENERGY_WEB_SHUTDOWN_TIMEOUT: Graceful shutdown timeout (default: 20s)

🎓 Learning Outcomes

This project demonstrates:

• Setting up local Kubernetes development environments
• Multi-stage Docker builds for Go applications
• Kubernetes deployment patterns and best practices
• Service health monitoring and observability
• Graceful shutdown and signal handling
• Structured logging in containerized environments