username/flaskpaste
1
0
Fork 1
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add kubernetes deployment guide

Browse Source
This commit is contained in:
Username
2026-01-17 16:27:56 +01:00
parent 7812af2e47
commit a736bce346
1 changed files with 387 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

387
documentation/kubernetes-deployment.md Normal file
View File

@@ -0,0 +1,387 @@
# Kubernetes Deployment
Deploy FlaskPaste to a Kubernetes cluster using images from Harbor registry.
---
## Architecture
```
┌─────────────────────────────────────────────────────────────────────────────┐
│ Traffic Flow │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ Internet → odin (public IP) → WireGuard → mymx HAProxy │
│ │ │
│ ↓ │
│ K8s NodePort :30500 │
│ │ │
│ ┌──────────┼──────────┐ │
│ ↓ ↓ ↓ │
│ k8s-master k8s-worker-1 k8s-worker-2 │
│ │ │ │ │
│ └──────────┼──────────┘ │
│ ↓ │
│ flaskpaste pod │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
```
---
## Prerequisites
- Kubernetes cluster with kubectl access
- Harbor registry with flaskpaste image (see [harbor-registry.md](harbor-registry.md))
- `local-path` StorageClass (or equivalent)
- Network access from HAProxy to K8s nodes
---
## Deployment
### 1. Create Namespace and Secrets
```bash
# Create namespace
kubectl create namespace flaskpaste
# Create Harbor pull secret
kubectl create secret docker-registry harbor-creds \
--namespace flaskpaste \
--docker-server=192.168.122.154:30443 \
--docker-username=admin \
--docker-password=Harbor12345 \
--docker-email=admin@example.com
```
### 2. Apply Manifest
```bash
kubectl apply -f kubernetes.yaml
```
### 3. Verify Deployment
```bash
# Check pod status
kubectl get pods -n flaskpaste
# Check service
kubectl get svc -n flaskpaste
# View logs
kubectl logs -n flaskpaste -l app=flaskpaste
# Test API
kubectl run test --rm -it --image=alpine --restart=Never -- \
wget -qO- http://flaskpaste.flaskpaste.svc:80/
```
---
## Manifest Components
### Namespace
```yaml
apiVersion: v1
kind: Namespace
metadata:
name: flaskpaste
```
### ConfigMap
Environment configuration:
```yaml
apiVersion: v1
kind: ConfigMap
metadata:
name: flaskpaste-config
namespace: flaskpaste
data:
FLASK_ENV: "production"
FLASKPASTE_URL_PREFIX: "/paste"
FLASKPASTE_EXPIRY_ANON: "432000"
FLASKPASTE_MAX_ANON: "3145728"
FLASKPASTE_MAX_AUTH: "52428800"
```
### PersistentVolumeClaim
```yaml
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
name: flaskpaste-data
namespace: flaskpaste
spec:
storageClassName: local-path
accessModes:
- ReadWriteOnce
resources:
requests:
storage: 1Gi
```
### Deployment
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: flaskpaste
namespace: flaskpaste
spec:
replicas: 1
selector:
matchLabels:
app: flaskpaste
template:
metadata:
labels:
app: flaskpaste
spec:
securityContext:
runAsUser: 999
runAsGroup: 999
fsGroup: 999
imagePullSecrets:
- name: harbor-creds
containers:
- name: flaskpaste
image: 192.168.122.154:30443/library/flaskpaste:latest
ports:
- containerPort: 5000
envFrom:
- configMapRef:
name: flaskpaste-config
volumeMounts:
- name: data
mountPath: /app/data
resources:
limits:
memory: "256Mi"
cpu: "1000m"
requests:
memory: "64Mi"
cpu: "250m"
livenessProbe:
httpGet:
path: /
port: 5000
initialDelaySeconds: 10
periodSeconds: 30
readinessProbe:
httpGet:
path: /
port: 5000
initialDelaySeconds: 5
periodSeconds: 10
volumes:
- name: data
persistentVolumeClaim:
claimName: flaskpaste-data
```
### Service (NodePort)
```yaml
apiVersion: v1
kind: Service
metadata:
name: flaskpaste
namespace: flaskpaste
spec:
selector:
app: flaskpaste
ports:
- protocol: TCP
port: 80
targetPort: 5000
nodePort: 30500
type: NodePort
```
---
## HAProxy Configuration
Route `/paste` path to K8s NodePort with failover:
```haproxy
frontend https
bind *:443 ssl crt /etc/haproxy/certs/
acl is_paste path_beg /paste
use_backend backend-flaskpaste if is_paste { req.hdr(Host) -i mymx.me }
backend backend-flaskpaste
mode http
timeout connect 5000
timeout server 30000
# Strip /paste prefix before forwarding
http-request replace-path /paste(.*) \1
http-request set-path / if { path -m len 0 }
# Request tracing
http-request set-header X-Request-ID %[uuid()] unless { req.hdr(X-Request-ID) -m found }
http-request set-var(txn.request_id) req.hdr(X-Request-ID)
http-response set-header X-Request-ID %[var(txn.request_id)]
# Proxy trust secret
http-request set-header X-Proxy-Secret <your-secret-here>
# K8s NodePort backends with failover
server k8s-master 192.168.122.154:30500 check
server k8s-worker-1 192.168.122.80:30500 check backup
server k8s-worker-2 192.168.122.219:30500 check backup
```
### Verify HAProxy Backend Status
```bash
echo "show stat" | nc -U /run/haproxy/admin.sock | grep flaskpaste
```
---
## containerd Registry Configuration
For self-signed Harbor certificates, configure containerd on all K8s nodes:
```toml
# /etc/containerd/config.toml
[plugins."io.containerd.grpc.v1.cri".registry]
[plugins."io.containerd.grpc.v1.cri".registry.configs]
[plugins."io.containerd.grpc.v1.cri".registry.configs."192.168.122.154:30443"]
[plugins."io.containerd.grpc.v1.cri".registry.configs."192.168.122.154:30443".tls]
insecure_skip_verify = true
```
Restart containerd after changes:
```bash
sudo systemctl restart containerd
```
---
## Operations
### Scale Deployment
```bash
kubectl scale deployment flaskpaste -n flaskpaste --replicas=3
```
### Rolling Update
```bash
# Update image
kubectl set image deployment/flaskpaste \
-n flaskpaste \
flaskpaste=192.168.122.154:30443/library/flaskpaste:v2.0.0
# Watch rollout
kubectl rollout status deployment/flaskpaste -n flaskpaste
# Rollback if needed
kubectl rollout undo deployment/flaskpaste -n flaskpaste
```
### View Events
```bash
kubectl get events -n flaskpaste --sort-by='.lastTimestamp'
```
### Shell Access
```bash
kubectl exec -it -n flaskpaste deploy/flaskpaste -- /bin/sh
```
### Database Backup
```bash
# Copy database from pod
kubectl cp flaskpaste/$(kubectl get pod -n flaskpaste -l app=flaskpaste -o jsonpath='{.items[0].metadata.name}'):/app/data/pastes.db ./backup-pastes.db
```
---
## Troubleshooting
### Image Pull Errors
```bash
# Check pod events
kubectl describe pod -n flaskpaste -l app=flaskpaste | grep -A10 Events
# Common issues:
# - x509 certificate error → configure containerd insecure registry
# - ImagePullBackOff → check harbor-creds secret exists
# - ErrImagePull → verify image exists in Harbor
```
### Pod Not Starting
```bash
# Check logs
kubectl logs -n flaskpaste -l app=flaskpaste --previous
# Check PVC binding
kubectl get pvc -n flaskpaste
# Check resource constraints
kubectl describe pod -n flaskpaste -l app=flaskpaste
```
### Health Probe Failures
```bash
# Test endpoint directly
kubectl exec -n flaskpaste deploy/flaskpaste -- wget -qO- http://localhost:5000/
# Check probe configuration
kubectl get deployment flaskpaste -n flaskpaste -o yaml | grep -A5 Probe
```
### HAProxy Connection Issues
```bash
# Test from HAProxy host to NodePort
curl -s http://192.168.122.154:30500/
# Check HAProxy backend status
echo "show stat" | nc -U /run/haproxy/admin.sock | grep -E "flaskpaste.*(UP|DOWN)"
# Check HAProxy logs
journalctl -u haproxy -f
```
---
## Resource Summary
| Resource | Name | Namespace |
|----------|------|-----------|
| Namespace | flaskpaste | - |
| ConfigMap | flaskpaste-config | flaskpaste |
| PVC | flaskpaste-data | flaskpaste |
| Deployment | flaskpaste | flaskpaste |
| Service | flaskpaste (NodePort 30500) | flaskpaste |
| Secret | harbor-creds | flaskpaste |
---
## Related Documentation
- [Harbor Registry](harbor-registry.md) - Building and pushing images
- [API Reference](api.md) - FlaskPaste API documentation
- [Deployment Guide](deployment.md) - Non-K8s deployment options