379 lines
11 KiB
Markdown
379 lines
11 KiB
Markdown
# 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):**
|
|
|
|
```yaml
|
|
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.**
|