first commit

2026-02-06 17:23:19 +00:00
commit 9f57a5b411
1 changed files with 270 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,270 @@
+# Kubernetes Manifests for Inventory App
+
+GitOps repository for inventory management system deployment. Managed by ArgoCD.
+
+## Structure
+
+```
+k8s-manifests/
+├── base/
+│   ├── mysql/          # MySQL StatefulSet + Service + Secret
+│   ├── backend/        # Backend Deployment + Service + ConfigMap
+│   └── frontend/       # Frontend Deployment + Service + Ingress
+├── overlays/
+│   ├── prod/           # Production configuration
+│   ├── dev/            # Development configuration (optional)
+│   └── staging/        # Staging configuration (optional)
+└── argocd/
+    └── applications/   # ArgoCD Application manifests
+```
+
+## Components
+
+### MySQL (StatefulSet)
+- **Image**: mysql:8.0
+- **Storage**: 10Gi PVC
+- **Replicas**: 1 (StatefulSet)
+- **Service**: Headless ClusterIP
+- **Secrets**: Root password, app user credentials
+
+### Backend (Deployment)
+- **Image**: Updated by CI/CD pipeline
+- **Replicas**: 3 (prod), 2 (base)
+- **Service**: ClusterIP on port 3000
+- **InitContainer**: Wait for MySQL readiness
+- **Probes**:
+  - Liveness: `/health`
+  - Readiness: `/ready` (checks DB)
+
+### Frontend (Deployment)
+- **Image**: Updated by CI/CD pipeline
+- **Replicas**: 3 (prod), 2 (base)
+- **Service**: ClusterIP on port 80
+- **Ingress**: Routes `/api` to backend, `/` to frontend
+
+## Deployment Flow
+
+1. **CI/CD pushes code** → Triggers Gitea Actions
+2. **Build & test** → Docker image created
+3. **Image pushed** → Gitea container registry
+4. **Update manifests** → CI updates image tag in `overlays/prod/kustomization.yaml`
+5. **ArgoCD detects change** → Syncs cluster to Git state
+6. **Rollout** → Kubernetes deploys new version
+
+## Image Tagging Strategy
+
+CI/CD pipeline tags images as:
+```
+{branch}-{git-sha}     # e.g., main-a3f5c21 (immutable)
+{branch}               # e.g., main (moving)
+latest                 # Latest on main branch
+```
+
+Kustomize uses immutable SHA tags for predictable rollbacks.
+
+## Manual Deployment (Without ArgoCD)
+
+```bash
+# Create namespace
+kubectl create namespace inventory
+
+# Deploy base + production overlay
+kubectl apply -k overlays/prod
+
+# Check status
+kubectl get all -n inventory
+
+# View logs
+kubectl logs -n inventory deployment/backend
+kubectl logs -n inventory deployment/frontend
+kubectl logs -n inventory mysql-0
+```
+
+## Deploy with ArgoCD
+
+```bash
+# Apply ArgoCD application
+kubectl apply -f argocd/applications/inventory-app.yaml
+
+# Check sync status
+argocd app get inventory-app
+
+# Manual sync (if auto-sync disabled)
+argocd app sync inventory-app
+
+# View history
+argocd app history inventory-app
+```
+
+## Rollback Procedures
+
+### Method 1: ArgoCD UI
+1. Open ArgoCD → Select `inventory-app`
+2. Click "History and Rollback"
+3. Select previous healthy revision
+4. Click "Rollback"
+
+### Method 2: Git Revert (GitOps)
+```bash
+# Find bad commit
+git log overlays/prod/kustomization.yaml
+
+# Revert to previous state
+git revert <bad-commit-sha>
+git push
+
+# ArgoCD auto-syncs within 3 minutes
+```
+
+### Method 3: Manual Image Update
+```bash
+# Edit overlays/prod/kustomization.yaml
+vim overlays/prod/kustomization.yaml
+
+# Change image tags to previous working SHA
+images:
+  - name: gitea.example.com/inventory/backend
+    newTag: main-abc1234  # Previous working version
+
+git add overlays/prod/kustomization.yaml
+git commit -m "Rollback to known-good version"
+git push
+```
+
+### Method 4: Emergency kubectl (Last Resort)
+```bash
+# Rollback deployment
+kubectl rollout undo deployment/backend -n inventory
+
+# Update Git to match (important for GitOps!)
+# Otherwise ArgoCD will revert back
+```
+
+## Configuration Management
+
+### Secrets
+MySQL credentials stored in `base/mysql/secret.yaml`:
+- **IMPORTANT**: Replace placeholder passwords before deploying!
+- Consider using external secret management (Sealed Secrets, Vault)
+
+```bash
+# Generate secure passwords
+openssl rand -base64 32
+```
+
+### ConfigMaps
+Backend configuration in `base/backend/configmap.yaml`:
+- Database host
+- Database name
+
+### Environment-Specific Overrides
+Use Kustomize overlays to customize per environment:
+```yaml
+# overlays/prod/kustomization.yaml
+replicas:
+  - name: backend
+    count: 3
+```
+
+## Ingress Configuration
+
+Default host: `inventory.local`
+
+**Change for your domain:**
+```yaml
+# base/frontend/ingress.yaml
+spec:
+  rules:
+  - host: inventory.yourdomain.com  # Update this
+```
+
+Routes:
+- `inventory.local/api/*` → Backend service
+- `inventory.local/health` → Backend health
+- `inventory.local/ready` → Backend readiness
+- `inventory.local/*` → Frontend (catch-all)
+
+## Monitoring & Troubleshooting
+
+### Check pod status
+```bash
+kubectl get pods -n inventory
+kubectl describe pod <pod-name> -n inventory
+```
+
+### View logs
+```bash
+# Backend logs
+kubectl logs -f deployment/backend -n inventory
+
+# Frontend logs
+kubectl logs -f deployment/frontend -n inventory
+
+# MySQL logs
+kubectl logs -f mysql-0 -n inventory
+```
+
+### Test connectivity
+```bash
+# Port-forward backend
+kubectl port-forward -n inventory svc/backend 3000:3000
+
+# Test API
+curl http://localhost:3000/health
+curl http://localhost:3000/api/items
+
+# Port-forward frontend
+kubectl port-forward -n inventory svc/frontend 8080:80
+# Open http://localhost:8080
+```
+
+### Check ArgoCD sync status
+```bash
+argocd app get inventory-app
+argocd app diff inventory-app
+argocd app sync inventory-app --dry-run
+```
+
+## Resource Requirements
+
+### Minimal Cluster Size
+- **Nodes**: 2+ (for HA)
+- **CPU**: 2 cores minimum
+- **Memory**: 4GB minimum
+- **Storage**: 20GB for MySQL PVC
+
+### Production Recommendations
+- **Nodes**: 3+ (one per replica)
+- **CPU**: 4+ cores
+- **Memory**: 8GB+
+- **Storage**: StorageClass with backup support
+
+## CI/CD Integration
+
+CI pipeline automatically updates this repo:
+```bash
+# In Gitea Actions
+sed -i "s|newTag:.*|newTag: ${BRANCH}-${SHA}|" overlays/prod/kustomization.yaml
+git commit -m "Update image to ${BRANCH}-${SHA}"
+git push
+```
+
+ArgoCD polls Git every 3 minutes or receives webhooks for instant sync.
+
+## Security Considerations
+
+- ✓ Non-root containers
+- ✓ Resource limits enforced
+- ✓ Network policies (optional, add if needed)
+- ✓ Secrets not in Git (use external secrets in production)
+- ✓ Ingress TLS (add cert-manager for HTTPS)
+- ✓ RBAC for ArgoCD service accounts
+
+## Next Steps
+
+1. **Replace secret passwords** in `base/mysql/secret.yaml`
+2. **Update Ingress host** to your domain
+3. **Configure TLS** with cert-manager
+4. **Set up monitoring** (Prometheus, Grafana)
+5. **Add network policies** for pod isolation
+6. **Configure backup** for MySQL PVC