Kubernetes Demo API

A simple Node.js Express application demonstrating Kubernetes deployment with Docker containerization, health checks, and service discovery.

🚀 Features

• Express.js API with health check endpoints
• Docker containerization with multi-stage build
• Kubernetes deployment with 2 replicas for high availability
• Resource management with CPU and memory limits
• Health monitoring with readiness and liveness probes
• Service discovery with NodePort service
• Environment variable injection including dynamic pod names

📋 Prerequisites

• Docker Desktop
• Kubernetes cluster (minikube, Docker Desktop, or cloud provider)
• kubectl CLI tool
• Node.js 18+ (for local development)

🏗️ Project Structure

kubernetes-demo/
├── k8s/
│   ├── deployment.yaml    # Kubernetes deployment configuration
│   └── service.yaml       # Kubernetes service configuration
├── index.js              # Express application
├── package.json          # Node.js dependencies
├── Dockerfile            # Docker image configuration
├── docker-compose.yaml   # Local development setup
├── deploy.sh            # Deployment script (bash)
└── deploy.ps1           # Deployment script (PowerShell)

🐳 Docker Configuration

Dockerfile Features

• Alpine Linux base image for minimal size
• Multi-stage build for optimized production image
• Non-root user for security
• Dependency caching for faster builds

Build Image

docker build -t tesfa892/kubernetes-demo-api:latest .

☸️ Kubernetes Configuration

Deployment Features

• 2 replicas for high availability
• Resource requests: 100m CPU, 128Mi memory
• Resource limits: 500m CPU, 512Mi memory
• Rolling updates strategy
• Health checks with custom endpoints

Service Features

• NodePort type for external access
• Load balancing across pod replicas
• Service discovery with stable DNS name

🚀 Deployment

Quick Deploy

# Using npm script
npm run deploy

# Or directly
bash deploy.sh

Manual Deployment

# Build and push Docker image
docker build -t tesfa892/kubernetes-demo-api:latest .
docker push tesfa892/kubernetes-demo-api:latest

# Apply Kubernetes configurations
kubectl apply -f k8s/deployment.yaml
kubectl apply -f k8s/service.yaml

🔍 Monitoring

Check Deployment Status

# View pods
kubectl get pods

# View services
kubectl get services

# Check pod logs
kubectl logs -l app=kubernetes-demo-api

# Watch pod status
kubectl get pods -w

Health Check Endpoints

• Readiness: GET /readyz - Returns 200 when ready for traffic
• Liveness: GET /healthz - Returns 200 when application is healthy
• Main API: GET / - Returns JSON with pod information

🌐 Access Application

Get Service URL

# For minikube
minikube service kubernetes-demo-api-service --url

# For Docker Desktop
kubectl get service kubernetes-demo-api-service
# Access via localhost:<NodePort>

Example Response

{
  "message": "Hello from a container!",
  "service": "hello-node",
  "pod": "kubernetes-demo-api-684d4db89f-6hcbl",
  "time": "2024-01-15T10:30:00.000Z"
}

🛠️ Local Development

Using Docker Compose

docker-compose up --build

Using Node.js directly

npm install
npm run dev

📊 Resource Management

Pod Resources

• CPU Request: 100m (0.1 cores) - Guaranteed minimum
• CPU Limit: 500m (0.5 cores) - Maximum allowed
• Memory Request: 128Mi - Guaranteed minimum
• Memory Limit: 512Mi - Maximum allowed

Scaling

# Scale to 3 replicas
kubectl scale deployment kubernetes-demo-api --replicas=3

# Auto-scaling (if HPA is configured)
kubectl autoscale deployment kubernetes-demo-api --cpu-percent=50 --min=2 --max=10

🔧 Configuration

Environment Variables

• NODE_ENV: Set to "production" in Kubernetes
• POD_NAME: Dynamically injected pod name
• PORT: Application port (defaults to 3000)

Health Check Configuration

• Readiness Probe: 5s initial delay, 10s interval
• Liveness Probe: 10s initial delay, 20s interval

🚨 Troubleshooting

Common Issues

Pods in CrashLoopBackOff

kubectl logs <pod-name>
kubectl describe pod <pod-name>

Service Not Accessible

kubectl get endpoints kubernetes-demo-api-service
kubectl describe service kubernetes-demo-api-service

Image Pull Errors

# Check if image exists
docker pull tesfa892/kubernetes-demo-api:latest

# Update deployment with new image
kubectl set image deployment/kubernetes-demo-api kubernetes-demo-api=tesfa892/kubernetes-demo-api:latest

📝 API Endpoints

Endpoint	Method	Description
/	GET	Main API endpoint with pod info
/readyz	GET	Readiness probe endpoint
/healthz	GET	Liveness probe endpoint

🏷️ Labels and Selectors

The application uses consistent labeling:

• App Label: app: kubernetes-demo-api
• Used by: Deployment, Service, and Pod selectors
• Purpose: Service discovery and traffic routing

📈 Monitoring and Observability

Kubernetes Native

# Resource usage
kubectl top pods
kubectl top nodes

# Events
kubectl get events --sort-by=.metadata.creationTimestamp

# Describe resources
kubectl describe deployment kubernetes-demo-api

🔄 CI/CD Integration

The deployment scripts can be integrated into CI/CD pipelines:

• Build and push Docker images
• Apply Kubernetes manifests
• Verify deployment health
• Run integration tests

📚 Learning Resources

This project demonstrates:

• Containerization best practices
• Kubernetes deployment patterns
• Service mesh basics
• Health monitoring strategies
• Resource management in Kubernetes

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test the deployment
5. Submit a pull request

📄 License

This project is licensed under the ISC License - see the package.json file for details.