Vitron-Front/k8s/PLAN.md

Deployment Plan: New Project to K3s with CI/CD

Project Discovery Phase

1. Application Architecture Questions

Critical Questions to Answer:

1. What type of application is this?

   • Frontend (React/Vue/Angular/Next.js)?
   • Backend (Django/FastAPI/Node.js/Go)?
   • Monolith or microservices?
   • Static site or full-stack?

2. What are the runtime requirements?

   • Programming language and version?
   • Build tools needed?
   • Runtime dependencies?
   • Environment variables required?

3. Does it have a Dockerfile already?

   • If yes: Does it follow best practices (multi-stage build, non-root user)?
   • If no: We'll create one following your infrastructure patterns

4. What external services does it depend on?

   • Database (PostgreSQL/MySQL/MongoDB)?
   • Cache (Redis/Memcached)?
   • Message queue (RabbitMQ/Kafka)?
   • Search engine (Elasticsearch)?
   • Object storage (S3/SeaweedFS)?
   • Email service?

5. What are the data persistence requirements?

   • Application data (database)?
   • User uploads (S3-compatible)?
   • Static files (can be served from SeaweedFS)?
   • Logs (ephemeral or need retention)?

---

Infrastructure Assessment

2. Current Infrastructure Alignment

Based on Your Existing Setup:

✅ Available Infrastructure:

• Harbor registry at harbor.abrino.cloud (with SotoonTech organization)
• SeaweedFS S3 at s3.abrino.cloud (8333 endpoint)
• K3s 6-node HA cluster with NFS storage
• MetalLB for LoadBalancer services (20.0.50.0/24 pool)
• ingress-nginx for internal routing
• Traefik (external) for SSL termination and domain routing
• Headscale VPN (20.0.0.0/24) for developer access
• GitHub Actions runners connected to your cluster

Questions to Determine Resource Allocation:

6. What domain/subdomain should this application use?

   • Format: [subdomain].abrino.cloud
   • Need SSL certificate (Let's Encrypt via Traefik)

7. What are the expected resource requirements?

   • CPU: Small (0.5 core), Medium (1-2 cores), Large (4+ cores)?
   • Memory: Small (<512Mi), Medium (512Mi-2Gi), Large (2Gi+)?
   • Replicas: 1 for dev, 2+ for production HA?

8. Storage requirements?

   • Database size estimate?
   • User upload volume?
   • Backup frequency needed?

---

Deployment Strategy

3. Container Image Strategy

Following Vitrown-back Pattern:

Decision Tree:
1. Does Dockerfile exist?
   └─ Yes → Review and optimize (multi-stage, security, caching)
   └─ No → Create new Dockerfile based on language/framework

2. Image naming convention:
   harbor.abrino.cloud/[organization]/[project-name]:[tag]
   Example: harbor.abrino.cloud/sotoontech/new-project:latest

Dockerfile Checklist (will be created/reviewed):

• Multi-stage build for smaller final image
• Non-root user for security
• Proper layer caching (COPY requirements first, then code)
• Health check endpoint defined
• Production-ready settings (no debug mode)
• Static files handling strategy

---

4. Kubernetes Manifests Strategy

Required Manifests (following your infrastructure patterns):

k8s/
├── namespace.yaml              # Dedicated namespace for the project
├── configmap.yaml             # Non-sensitive configuration
├── secret.yaml                # Sensitive data (DB credentials, API keys)
├── deployment.yaml            # Application pods
├── service.yaml               # ClusterIP service
├── ingress.yaml               # ingress-nginx rules
├── pvc.yaml                   # NFS storage claims (if needed)
└── [database-specific].yaml   # PostgreSQL/Redis StatefulSets if needed

Questions for Manifest Configuration:

9. Database deployment approach?

   • Use existing PostgreSQL in cluster (shared instance)?
   • Deploy dedicated PostgreSQL StatefulSet for this project?
   • Use external managed database?

10. Configuration management approach?

    • Environment variables via ConfigMap/Secret?
    • Configuration files mounted as volumes?
    • External configuration service?

11. Scaling requirements?

    • Fixed replica count or HorizontalPodAutoscaler?
    • Resource limits appropriate for the workload?

---

5. CI/CD Pipeline Strategy

GitHub Actions Workflow Pattern (based on Vitrown-back success):

Pipeline Stages:
1. Trigger: Push to main/develop branch or PR merge
2. Build: Docker image with caching
3. Test: Run unit/integration tests in container
4. Push: To Harbor registry
5. Deploy: Update K3s deployment
6. Notify: NTFY notification on success/failure

Questions for CI/CD Configuration:

12. Branch strategy?

    • main → production deployment
    • develop → staging deployment
    • feature/* → no auto-deploy?

13. Testing requirements?

    • Unit tests to run?
    • Integration tests?
    • Test database needed?

14. Deployment strategy?

    • Rolling update (zero downtime)?
    • Blue-green deployment?
    • Canary deployment?

15. Notification preferences?

    • NTFY topic for this project?
    • Success and failure notifications?
    • Slack/Discord integration needed?

---

Security & Access Control

6. Security Considerations

Questions:

16. Authentication requirements?

    • Public application (no auth)?
    • Internal only (Headscale VPN access)?
    • OAuth/OIDC integration?
    • API key authentication?

17. Secrets management?

    • What sensitive data needs to be stored?
    • Database credentials?
    • API keys for third-party services?
    • SSL/TLS certificates (handled by Traefik)?

18. Network policies?

    • Restrict pod-to-pod communication?
    • Database access only from app pods?
    • External API access requirements?

---

Migration & Data Strategy

7. Data Migration (if applicable)

Questions:

19. Is there existing data to migrate?

    • From where (Docker Compose setup, another cluster, cloud)?
    • Database dump available?
    • User uploads/files to transfer?

20. Migration approach?

    • One-time migration before go-live?
    • Gradual migration with sync period?
    • Parallel run before cutover?

---

Monitoring & Maintenance

8. Operational Considerations

Questions:

21. Monitoring requirements?

    • Application metrics (Prometheus)?
    • Logging aggregation needed?
    • APM (Application Performance Monitoring)?

22. Backup strategy?

    • Database backup frequency?
    • Retention policy (following your minimal approach)?
    • S3/SeaweedFS data backup?

23. Update/rollback procedures?

    • Manual approval for production deploys?
    • Automatic rollback on failure?
    • Health check requirements?

---

Implementation Phases

Phase 1: Project Analysis (Current Phase)

• Answer all discovery questions above
• Review existing codebase structure
• Identify dependencies and services
• Determine resource requirements

Phase 2: Containerization

• Create/optimize Dockerfile
• Build and test image locally
• Push to Harbor registry
• Verify image works in isolated environment

Phase 3: Kubernetes Configuration

• Create namespace and resource quotas
• Generate ConfigMaps and Secrets
• Create deployment manifests
• Configure services and ingress
• Set up persistent storage (if needed)

Phase 4: Database Setup (if needed)

• Deploy database StatefulSet or use existing
• Initialize schema/migrations
• Configure backups
• Test connectivity from application pods

Phase 5: CI/CD Pipeline

• Create GitHub Actions workflow
• Configure Harbor credentials in GitHub Secrets
• Set up kubectl access to K3s cluster
• Test build and deployment process
• Configure NTFY notifications

Phase 6: Testing & Validation

• Deploy to staging environment first
• Run smoke tests
• Performance testing
• Security scanning
• Load testing (if applicable)

Phase 7: Production Deployment

• Final configuration review
• Deploy to production namespace
• Configure Traefik ingress for domain
• SSL certificate verification
• Monitor first deployment closely

Phase 8: Documentation

• Deployment procedure documentation
• Troubleshooting guide
• Rollback procedures
• Developer onboarding (Headscale access)
• Add to team Obsidian knowledge base

---

Risk Assessment

Potential Issues to Watch:

1. Resource Constraints:

   • Monitor abr-1 server resources (CPU/RAM/Storage)
   • Ensure NFS performance adequate for workload
   • MetalLB IP pool availability

2. Network Configuration:

   • Ensure proper routing through Traefik → ingress-nginx → service
   • Headscale VPN access for developers
   • External service connectivity (if needed)

3. Data Persistence:

   • NFS mount reliability
   • SeaweedFS bucket configuration and permissions
   • Database backup validation

4. CI/CD Reliability:

   • GitHub Actions runner availability
   • Harbor registry storage capacity
   • Network connectivity during deployments

---

Next Steps

To proceed, I need you to:

1. Share Project Information:

   • GitHub repository URL (if private, grant access)
   • Project type (frontend/backend/fullstack)
   • Programming language/framework
   • Current development setup (Docker Compose, local dev, etc.)

2. Answer Critical Questions:

   • Domain name preference: ?????.abrino.cloud
   • Database requirements (new or shared PostgreSQL?)
   • Expected user load and resource needs
   • Target deployment environment (production only or staging + production?)

3. Provide Access Information:

   • Harbor organization (create new or use existing?)
   • GitHub repository access for setting up Actions
   • NTFY topic preference for notifications

Once I have this information, we'll proceed step-by-step through each implementation phase, following the same systematic approach that successfully deployed Vitrown-back with <5 minute deployment times.

---

Expected Timeline

Estimated Time Per Phase:

• Phase 1 (Discovery): 30 minutes - 1 hour
• Phase 2 (Containerization): 1-2 hours
• Phase 3 (K8s Configuration): 2-3 hours
• Phase 4 (Database Setup): 1-2 hours (if needed)
• Phase 5 (CI/CD Pipeline): 2-3 hours
• Phase 6 (Testing): 2-4 hours
• Phase 7 (Production Deploy): 1 hour
• Phase 8 (Documentation): 1-2 hours

Total: 1-2 days for a complete, production-ready deployment with CI/CD.

---

Success Criteria

We'll know we're successful when:

• ✅ Developer pushes code → GitHub Actions builds → Harbor stores image → K3s deploys → Application accessible
• ✅ Deployment time < 5 minutes (matching Vitrown-back performance)
• ✅ Application accessible via HTTPS at assigned domain
• ✅ Health checks passing
• ✅ NTFY notifications working
• ✅ Rollback procedure tested and documented
• ✅ Team can access via Headscale VPN for development
• ✅ Documentation added to Obsidian knowledge base

---

Let's start with Phase 1. Please provide the project details and answer the critical questions above.