From 9f57a5b411696d968b036b0790e30181effcb75e Mon Sep 17 00:00:00 2001 From: gitea_admin Date: Fri, 6 Feb 2026 17:23:19 +0000 Subject: [PATCH] first commit --- README.md | 270 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 270 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..4fa3187 --- /dev/null +++ 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 +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 -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