1# Docker & Kubernetes Examples
2
3This directory contains comprehensive, production-ready examples for Docker and Kubernetes, demonstrating best practices for containerization and orchestration.
4
5## Directory Structure
6
7```
8Docker/
9├── 01_multi_stage/ # Multi-stage Docker build
10│ ├── Dockerfile # Optimized multi-stage build
11│ ├── app.py # Flask application
12│ ├── requirements.txt # Python dependencies
13│ └── .dockerignore # Files to exclude from build
14│
15├── 02_compose/ # Docker Compose stack
16│ ├── docker-compose.yml # 3-tier application stack
17│ ├── app.py # Flask app with DB and cache
18│ ├── Dockerfile # Production-ready Dockerfile
19│ ├── requirements.txt # Dependencies
20│ └── .env.example # Environment variables template
21│
22├── 03_k8s/ # Kubernetes manifests
23│ ├── deployment.yaml # Deployment with HPA
24│ ├── service.yaml # Service definitions
25│ ├── ingress.yaml # Ingress with TLS
26│ └── configmap.yaml # Configuration and secrets
27│
28└── 04_ci_cd/ # CI/CD pipeline
29 └── .github/
30 └── workflows/
31 └── docker-ci.yml # GitHub Actions workflow
32```
33
34## Examples Overview
35
36### 1. Multi-stage Build (`01_multi_stage/`)
37
38Demonstrates Docker multi-stage builds for creating slim, secure production images.
39
40**Key Features:**
41- Multi-stage build pattern (builder + runtime)
42- Security best practices (non-root user, minimal base image)
43- Health checks for container orchestration
44- Proper signal handling for graceful shutdown
45- Optimized layer caching
46
47**Usage:**
48```bash
49cd 01_multi_stage
50
51# Build the image
52docker build -t flask-app:latest .
53
54# Run the container
55docker run -d -p 5000:5000 --name flask-app flask-app:latest
56
57# Test the application
58curl http://localhost:5000
59curl http://localhost:5000/health
60
61# View logs
62docker logs flask-app
63
64# Stop and remove
65docker stop flask-app
66docker rm flask-app
67```
68
69**Image size comparison:**
70- Without multi-stage: ~800MB
71- With multi-stage: ~150MB
72
73---
74
75### 2. Docker Compose (`02_compose/`)
76
77Complete 3-tier web application stack with Flask, PostgreSQL, and Redis.
78
79**Key Features:**
80- Multi-container orchestration
81- Service dependencies with health checks
82- Named volumes for data persistence
83- Environment-based configuration
84- Internal networking
85- Automatic restarts
86
87**Stack:**
88- **Web**: Flask application (Python 3.11)
89- **Database**: PostgreSQL 16
90- **Cache**: Redis 7
91
92**Usage:**
93```bash
94cd 02_compose
95
96# Create environment file
97cp .env.example .env
98# Edit .env with your own values
99
100# Start all services
101docker-compose up -d
102
103# View logs
104docker-compose logs -f
105
106# Check service health
107docker-compose ps
108
109# Test the application
110curl http://localhost:5000
111curl http://localhost:5000/stats
112
113# Scale the web service
114docker-compose up -d --scale web=3
115
116# Stop all services
117docker-compose down
118
119# Stop and remove volumes (WARNING: deletes data)
120docker-compose down -v
121```
122
123**Services:**
124- Web: http://localhost:5000
125- PostgreSQL: localhost:5432 (only if exposed)
126- Redis: localhost:6379 (only if exposed)
127
128---
129
130### 3. Kubernetes Manifests (`03_k8s/`)
131
132Production-ready Kubernetes deployment with all essential resources.
133
134**Key Features:**
135- Deployment with 3 replicas
136- Horizontal Pod Autoscaler (HPA)
137- Resource limits and requests
138- Liveness, readiness, and startup probes
139- Multiple service types (ClusterIP, NodePort, LoadBalancer)
140- Ingress with TLS termination
141- ConfigMap and Secret management
142- RBAC with ServiceAccount
143- Pod anti-affinity for high availability
144
145**Resources:**
146- Deployment + HPA
147- Services (ClusterIP, headless)
148- Ingress with NGINX controller
149- ConfigMap for configuration
150- Secret for sensitive data
151
152**Usage:**
153```bash
154cd 03_k8s
155
156# Create namespace (optional)
157kubectl create namespace flask-app
158
159# Apply ConfigMap and Secrets first
160kubectl apply -f configmap.yaml
161
162# Apply deployment
163kubectl apply -f deployment.yaml
164
165# Apply services
166kubectl apply -f service.yaml
167
168# Apply ingress (requires ingress controller)
169kubectl apply -f ingress.yaml
170
171# Check status
172kubectl get all -l app=flask-app
173kubectl get pods -l app=flask-app
174kubectl get svc flask-app
175kubectl get ingress flask-app-ingress
176
177# View logs
178kubectl logs -l app=flask-app -f
179
180# Port forward for local testing
181kubectl port-forward svc/flask-app 8080:80
182curl http://localhost:8080/health
183
184# Scale manually
185kubectl scale deployment flask-app --replicas=5
186
187# Update image
188kubectl set image deployment/flask-app flask-app=new-image:tag
189kubectl rollout status deployment/flask-app
190
191# Rollback if needed
192kubectl rollout undo deployment/flask-app
193
194# Delete all resources
195kubectl delete -f .
196```
197
198**Prerequisites:**
199- Kubernetes cluster (minikube, kind, or cloud provider)
200- kubectl configured
201- NGINX Ingress Controller (for ingress)
202- cert-manager (for TLS certificates)
203
204---
205
206### 4. CI/CD Pipeline (`04_ci_cd/`)
207
208Complete GitHub Actions workflow for automated Docker builds and deployments.
209
210**Key Features:**
211- Multi-platform builds (amd64, arm64)
212- Docker layer caching
213- Security scanning with Trivy
214- SBOM generation
215- Automated testing
216- Kubernetes deployment
217- GitHub Container Registry integration
218
219**Pipeline Stages:**
2201. Build multi-platform Docker image
2212. Run container tests
2223. Security vulnerability scanning
2234. Generate Software Bill of Materials (SBOM)
2245. Push to GitHub Container Registry
2256. Deploy to Kubernetes (production only)
226
227**Usage:**
228```bash
229# 1. Copy workflow to your repository
230cp -r 04_ci_cd/.github /path/to/your/repo/
231
232# 2. Set up GitHub secrets
233# Go to: Settings → Secrets and variables → Actions
234# Add the following secrets:
235# - KUBE_CONFIG: Base64-encoded kubeconfig
236# cat ~/.kube/config | base64 -w 0
237
238# 3. Push to trigger workflow
239git add .github/workflows/docker-ci.yml
240git commit -m "Add Docker CI/CD workflow"
241git push
242
243# 4. Monitor workflow
244# Go to: Actions tab in GitHub
245
246# 5. View built images
247# Go to: Packages tab in GitHub
248```
249
250**Supported Triggers:**
251- Push to main, develop, or release branches
252- Pull requests to main
253- Version tags (v1.0.0)
254- Manual workflow dispatch
255
256---
257
258## Best Practices Demonstrated
259
260### Security
261- Non-root user in containers
262- Read-only root filesystem
263- Security context with dropped capabilities
264- Secret management
265- Image vulnerability scanning
266- SBOM generation
267
268### Performance
269- Multi-stage builds for smaller images
270- Layer caching optimization
271- Resource limits and requests
272- Horizontal pod autoscaling
273- Redis caching
274
275### Reliability
276- Health checks (liveness, readiness, startup)
277- Graceful shutdown
278- Automatic restarts
279- Rolling updates
280- Pod anti-affinity
281
282### Observability
283- Structured logging
284- Health check endpoints
285- Prometheus annotations
286- Container insights
287
288## Prerequisites
289
290### Docker
291```bash
292# macOS
293brew install docker
294
295# Ubuntu
296sudo apt-get install docker.io docker-compose
297
298# Verify
299docker --version
300docker-compose --version
301```
302
303### Kubernetes (choose one)
304```bash
305# minikube (local)
306brew install minikube
307minikube start
308
309# kind (local)
310brew install kind
311kind create cluster
312
313# Cloud providers
314# - AWS EKS
315# - Google GKE
316# - Azure AKS
317```
318
319### Tools
320```bash
321# kubectl
322brew install kubectl
323
324# Helm
325brew install helm
326
327# NGINX Ingress Controller
328kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/deploy/static/provider/cloud/deploy.yaml
329
330# cert-manager (for TLS)
331kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.13.0/cert-manager.yaml
332```
333
334## Testing the Examples
335
336### Quick Test: Multi-stage Build
337```bash
338cd 01_multi_stage
339docker build -t test-flask .
340docker run -d -p 5000:5000 test-flask
341curl http://localhost:5000/health
342docker stop $(docker ps -q -f ancestor=test-flask)
343```
344
345### Quick Test: Docker Compose
346```bash
347cd 02_compose
348cp .env.example .env
349docker-compose up -d
350sleep 10
351curl http://localhost:5000/health
352curl http://localhost:5000/stats
353docker-compose down
354```
355
356### Quick Test: Kubernetes
357```bash
358cd 03_k8s
359kubectl apply -f configmap.yaml
360kubectl apply -f deployment.yaml
361kubectl apply -f service.yaml
362kubectl port-forward svc/flask-app 8080:80 &
363sleep 5
364curl http://localhost:8080/health
365kubectl delete -f .
366```
367
368## Troubleshooting
369
370### Docker Build Issues
371```bash
372# Clear build cache
373docker builder prune -a
374
375# Build without cache
376docker build --no-cache -t flask-app .
377
378# Check disk space
379docker system df
380```
381
382### Docker Compose Issues
383```bash
384# View logs
385docker-compose logs -f web
386
387# Restart specific service
388docker-compose restart web
389
390# Rebuild and restart
391docker-compose up -d --build
392```
393
394### Kubernetes Issues
395```bash
396# Check pod status
397kubectl get pods -l app=flask-app
398kubectl describe pod <pod-name>
399
400# View events
401kubectl get events --sort-by=.metadata.creationTimestamp
402
403# Check logs
404kubectl logs <pod-name> -f
405
406# Debug with ephemeral container
407kubectl debug <pod-name> -it --image=busybox
408```
409
410## Additional Resources
411
412- [Docker Documentation](https://docs.docker.com/)
413- [Kubernetes Documentation](https://kubernetes.io/docs/)
414- [Docker Compose Specification](https://docs.docker.com/compose/compose-file/)
415- [Kubernetes Best Practices](https://kubernetes.io/docs/concepts/configuration/overview/)
416- [NGINX Ingress Controller](https://kubernetes.github.io/ingress-nginx/)
417- [cert-manager](https://cert-manager.io/)
418
419## Related Learning Materials
420
421- [Docker Lessons](/opt/projects/01_Personal/03_Study/content/en/Docker/)
422- [PostgreSQL Examples](/opt/projects/01_Personal/03_Study/examples/PostgreSQL/)
423- [Git Workflows](/opt/projects/01_Personal/03_Study/content/en/Git/)
424
425## License
426
427These examples are provided under the MIT License. See the project root for details.