Update apps/demo-nginx/docs/README.md
This commit is contained in:
593
apps/demo-nginx/docs/README.md
Normal file
593
apps/demo-nginx/docs/README.md
Normal file
@@ -0,0 +1,593 @@
|
||||
# 🚀 Demo Nginx - CI/CD Pipeline Documentation
|
||||
|
||||
## 📋 Overview
|
||||
|
||||
This is a complete CI/CD pipeline for deploying Nginx application using:
|
||||
- **Jenkins** - CI/CD orchestration
|
||||
- **Gitea** - Git repository and GitOps manifests
|
||||
- **ArgoCD** - GitOps deployment
|
||||
- **Kubernetes** - Container orchestration
|
||||
- **Docker** - Container runtime
|
||||
|
||||
---
|
||||
|
||||
## 🏗️ Architecture
|
||||
|
||||
```
|
||||
┌─────────────┐ ┌──────────────┐ ┌─────────────┐ ┌────────────┐
|
||||
│ Developer │─────▶│ Gitea │─────▶│ Jenkins │─────▶│ Docker │
|
||||
│ (commit) │ │ (k3s-gitops) │ │ (pipeline) │ │ Registry │
|
||||
└─────────────┘ └──────────────┘ └──────┬──────┘ └─────┬──────┘
|
||||
│ │
|
||||
│ Update │ Pull
|
||||
│ manifests │ image
|
||||
▼ │
|
||||
┌──────────────┐ │
|
||||
│ Gitea │ │
|
||||
│ (manifests) │ │
|
||||
└──────┬───────┘ │
|
||||
│ │
|
||||
│ Watch │
|
||||
▼ │
|
||||
┌──────────────┐ │
|
||||
│ ArgoCD │────────────┘
|
||||
│ (sync) │
|
||||
└──────┬───────┘
|
||||
│
|
||||
│ Apply
|
||||
▼
|
||||
┌──────────────┐
|
||||
│ Kubernetes │
|
||||
│ Cluster │
|
||||
└──────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📁 Repository Structure
|
||||
|
||||
```
|
||||
k3s-gitops/
|
||||
└── apps/
|
||||
└── demo-nginx/
|
||||
├── namespace.yaml # Kubernetes namespace
|
||||
├── deployment.yaml # Deployment + Service
|
||||
├── ingress.yaml # Ingress with TLS
|
||||
├── application.yaml # ArgoCD Application
|
||||
├── Jenkinsfile # CI/CD Pipeline
|
||||
└── README.md # This file
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔧 Prerequisites
|
||||
|
||||
### 1. Jenkins Configuration
|
||||
|
||||
#### Required Plugins:
|
||||
- Git Plugin
|
||||
- Docker Plugin
|
||||
- Kubernetes Plugin
|
||||
- Pipeline Plugin
|
||||
- Credentials Plugin
|
||||
|
||||
#### Required Credentials in Jenkins:
|
||||
|
||||
**Docker Registry Credentials:**
|
||||
```
|
||||
ID: docker-registry-credentials
|
||||
Type: Username with password
|
||||
Username: <your-docker-hub-username>
|
||||
Password: <your-docker-hub-token>
|
||||
```
|
||||
|
||||
**Gitea Credentials:**
|
||||
```
|
||||
ID: gitea-credentials
|
||||
Type: Username with password
|
||||
Username: admin
|
||||
Password: <gitea-password>
|
||||
```
|
||||
|
||||
#### Create Credentials in Jenkins:
|
||||
1. Jenkins → Manage Jenkins → Credentials
|
||||
2. (global) → Add Credentials
|
||||
3. Select "Username with password"
|
||||
4. Fill in details and save
|
||||
|
||||
### 2. Docker Registry
|
||||
|
||||
**Option A: Docker Hub**
|
||||
- Free for public images
|
||||
- URL: docker.io
|
||||
- Create account: https://hub.docker.com/signup
|
||||
|
||||
**Option B: Harbor (Local)**
|
||||
- Already installed in cluster
|
||||
- URL: harbor.thedevops.dev
|
||||
- Create project: demo-nginx
|
||||
|
||||
### 3. Kubernetes Access
|
||||
|
||||
Jenkins needs kubectl access to cluster:
|
||||
|
||||
```bash
|
||||
# Copy kubeconfig to Jenkins
|
||||
kubectl create secret generic kubeconfig \
|
||||
--from-file=config=$HOME/.kube/config \
|
||||
-n jenkins
|
||||
|
||||
# Or configure ServiceAccount with proper RBAC
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Setup Instructions
|
||||
|
||||
### Step 1: Apply ArgoCD Application
|
||||
|
||||
```bash
|
||||
kubectl apply -f apps/demo-nginx/application.yaml
|
||||
```
|
||||
|
||||
Verify:
|
||||
```bash
|
||||
kubectl get application demo-nginx -n argocd
|
||||
```
|
||||
|
||||
### Step 2: Configure Jenkins Job
|
||||
|
||||
#### Method A: Multibranch Pipeline (Recommended)
|
||||
|
||||
1. **Jenkins → New Item**
|
||||
2. **Enter name**: `demo-nginx`
|
||||
3. **Select**: Multibranch Pipeline
|
||||
4. **Click**: OK
|
||||
|
||||
5. **Branch Sources**:
|
||||
- Add source: Git
|
||||
- Project Repository: `http://gitea-http.gitea.svc.cluster.local:3000/admin/k3s-gitops`
|
||||
- Credentials: Select gitea-credentials
|
||||
- Behaviors: Discover branches
|
||||
|
||||
6. **Build Configuration**:
|
||||
- Mode: by Jenkinsfile
|
||||
- Script Path: `apps/demo-nginx/Jenkinsfile`
|
||||
|
||||
7. **Scan Multibranch Pipeline Triggers**:
|
||||
- ✅ Periodically if not otherwise run
|
||||
- Interval: 1 minute
|
||||
|
||||
8. **Save**
|
||||
|
||||
#### Method B: Pipeline Job
|
||||
|
||||
1. **Jenkins → New Item**
|
||||
2. **Enter name**: `demo-nginx-pipeline`
|
||||
3. **Select**: Pipeline
|
||||
4. **Click**: OK
|
||||
|
||||
5. **Pipeline**:
|
||||
- Definition: Pipeline script from SCM
|
||||
- SCM: Git
|
||||
- Repository URL: `http://gitea-http.gitea.svc.cluster.local:3000/admin/k3s-gitops`
|
||||
- Credentials: gitea-credentials
|
||||
- Branch: `*/main`
|
||||
- Script Path: `apps/demo-nginx/Jenkinsfile`
|
||||
|
||||
6. **Build Triggers**:
|
||||
- ✅ Poll SCM
|
||||
- Schedule: `H/5 * * * *` (every 5 minutes)
|
||||
|
||||
7. **Save**
|
||||
|
||||
### Step 3: Configure Webhook (Optional)
|
||||
|
||||
For instant builds on git push:
|
||||
|
||||
**In Gitea:**
|
||||
1. Repository Settings → Webhooks
|
||||
2. Add Webhook → Gitea
|
||||
3. URL: `http://jenkins.jenkins.svc.cluster.local:8080/gitea-webhook/post`
|
||||
4. Events: Push
|
||||
5. Active: ✅
|
||||
|
||||
**In Jenkins:**
|
||||
- Build Triggers → ✅ Build when a change is pushed to Gitea
|
||||
|
||||
---
|
||||
|
||||
## 🏃 Running the Pipeline
|
||||
|
||||
### Trigger Build
|
||||
|
||||
**Option 1: Manual Trigger**
|
||||
```bash
|
||||
# In Jenkins UI
|
||||
Jenkins → demo-nginx → Build Now
|
||||
```
|
||||
|
||||
**Option 2: Git Push**
|
||||
```bash
|
||||
# Make any change to trigger pipeline
|
||||
git commit --allow-empty -m "Trigger pipeline"
|
||||
git push origin main
|
||||
```
|
||||
|
||||
**Option 3: API Trigger**
|
||||
```bash
|
||||
curl -X POST http://jenkins.jenkins.svc.cluster.local:8080/job/demo-nginx/build \
|
||||
--user admin:your-token
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📊 Pipeline Stages
|
||||
|
||||
### 1. Checkout Source
|
||||
- Clones repository
|
||||
- Creates Dockerfile and nginx.conf
|
||||
|
||||
### 2. Build Docker Image
|
||||
- Builds image with version tag
|
||||
- Tags: `${IMAGE_TAG}` and `latest`
|
||||
|
||||
### 3. Test Image
|
||||
- Runs container locally
|
||||
- Tests HTTP endpoints
|
||||
- Verifies health check
|
||||
|
||||
### 4. Push to Registry
|
||||
- **Only on main branch**
|
||||
- Logs in to Docker registry
|
||||
- Pushes both tags
|
||||
- Cleans up credentials
|
||||
|
||||
### 5. Update GitOps Manifests
|
||||
- **Only on main branch**
|
||||
- Clones k3s-gitops repository
|
||||
- Updates deployment.yaml with new image tag
|
||||
- Commits and pushes changes
|
||||
|
||||
### 6. Wait for ArgoCD Sync
|
||||
- Monitors ArgoCD application status
|
||||
- Waits for Synced + Healthy state
|
||||
- Timeout: 5 minutes
|
||||
|
||||
### 7. Verify Deployment
|
||||
- Checks rollout status
|
||||
- Verifies deployed image version
|
||||
- Lists running pods
|
||||
|
||||
---
|
||||
|
||||
## 🔍 Pipeline Variables
|
||||
|
||||
You can customize these in Jenkinsfile:
|
||||
|
||||
| Variable | Default | Description |
|
||||
|----------|---------|-------------|
|
||||
| APP_NAME | demo-nginx | Application name |
|
||||
| NAMESPACE | demo-app | Kubernetes namespace |
|
||||
| DOCKER_REGISTRY | docker.io | Docker registry URL |
|
||||
| DOCKER_REPO | vladimiras | Docker repository/username |
|
||||
| GITEA_URL | http://gitea-http... | Gitea service URL |
|
||||
| GITEA_REPO | admin/k3s-gitops | GitOps repository |
|
||||
|
||||
**To customize:**
|
||||
```groovy
|
||||
environment {
|
||||
DOCKER_REGISTRY = 'harbor.thedevops.dev'
|
||||
DOCKER_REPO = 'library'
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🧪 Testing
|
||||
|
||||
### Test Locally
|
||||
|
||||
```bash
|
||||
# Build image
|
||||
docker build -t demo-nginx:test .
|
||||
|
||||
# Run container
|
||||
docker run -d -p 8080:80 demo-nginx:test
|
||||
|
||||
# Test
|
||||
curl http://localhost:8080/
|
||||
curl http://localhost:8080/health
|
||||
|
||||
# Cleanup
|
||||
docker stop $(docker ps -q --filter ancestor=demo-nginx:test)
|
||||
```
|
||||
|
||||
### Test in Cluster
|
||||
|
||||
```bash
|
||||
# Port-forward to service
|
||||
kubectl port-forward svc/demo-nginx 8080:80 -n demo-app
|
||||
|
||||
# Test
|
||||
curl http://localhost:8080/
|
||||
```
|
||||
|
||||
### Access via Ingress
|
||||
|
||||
```bash
|
||||
# Add to /etc/hosts
|
||||
echo "5.182.17.194 demo-nginx.thedevops.dev" | sudo tee -a /etc/hosts
|
||||
|
||||
# Test (after DNS is configured)
|
||||
curl https://demo-nginx.thedevops.dev/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📈 Monitoring
|
||||
|
||||
### Check Pipeline Status
|
||||
|
||||
```bash
|
||||
# Jenkins CLI
|
||||
java -jar jenkins-cli.jar -s http://jenkins:8080/ \
|
||||
-auth admin:token \
|
||||
build demo-nginx -s -v
|
||||
|
||||
# Or via Web UI
|
||||
# Jenkins → demo-nginx → Build History
|
||||
```
|
||||
|
||||
### Check ArgoCD Sync
|
||||
|
||||
```bash
|
||||
# Get application status
|
||||
kubectl get application demo-nginx -n argocd -o yaml
|
||||
|
||||
# Watch sync status
|
||||
watch -n 2 'kubectl get application demo-nginx -n argocd'
|
||||
|
||||
# ArgoCD UI
|
||||
# Open: https://argocd.thedevops.dev
|
||||
# Applications → demo-nginx
|
||||
```
|
||||
|
||||
### Check Deployment
|
||||
|
||||
```bash
|
||||
# Deployment status
|
||||
kubectl get deployment demo-nginx -n demo-app
|
||||
|
||||
# Pods
|
||||
kubectl get pods -n demo-app -l app=demo-nginx
|
||||
|
||||
# Logs
|
||||
kubectl logs -n demo-app -l app=demo-nginx --tail=50
|
||||
|
||||
# Events
|
||||
kubectl get events -n demo-app --sort-by='.lastTimestamp'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🐛 Troubleshooting
|
||||
|
||||
### Pipeline Fails at "Build Docker Image"
|
||||
|
||||
**Problem:** Docker not available in Jenkins
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
# Ensure Docker socket is mounted in Jenkins pod
|
||||
kubectl edit deployment jenkins -n jenkins
|
||||
|
||||
# Add volume:
|
||||
volumes:
|
||||
- name: docker-sock
|
||||
hostPath:
|
||||
path: /var/run/docker.sock
|
||||
|
||||
# Add volumeMount:
|
||||
volumeMounts:
|
||||
- name: docker-sock
|
||||
mountPath: /var/run/docker.sock
|
||||
```
|
||||
|
||||
### Pipeline Fails at "Push to Registry"
|
||||
|
||||
**Problem:** Invalid credentials
|
||||
|
||||
**Solution:**
|
||||
1. Verify credentials in Jenkins
|
||||
2. Test manually:
|
||||
```bash
|
||||
docker login docker.io -u username -p password
|
||||
```
|
||||
|
||||
### Pipeline Fails at "Update GitOps Manifests"
|
||||
|
||||
**Problem:** Git authentication failed
|
||||
|
||||
**Solution:**
|
||||
1. Check Gitea credentials in Jenkins
|
||||
2. Test Git access:
|
||||
```bash
|
||||
git clone http://username:password@gitea-http.gitea.svc.cluster.local:3000/admin/k3s-gitops
|
||||
```
|
||||
|
||||
### ArgoCD Not Syncing
|
||||
|
||||
**Problem:** ArgoCD not watching repository
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
# Refresh ArgoCD app
|
||||
kubectl patch application demo-nginx -n argocd \
|
||||
--type merge -p '{"operation":{"initiatedBy":{"username":"admin"},"sync":{"revision":"HEAD"}}}'
|
||||
|
||||
# Or via ArgoCD UI
|
||||
# Click "Refresh" button
|
||||
```
|
||||
|
||||
### Deployment Not Rolling Out
|
||||
|
||||
**Problem:** Image pull error
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
# Check pod events
|
||||
kubectl describe pod -n demo-app -l app=demo-nginx
|
||||
|
||||
# Check if image exists
|
||||
docker pull vladimiras/demo-nginx:main-123
|
||||
|
||||
# Check ImagePullSecrets (if using private registry)
|
||||
kubectl get deployment demo-nginx -n demo-app -o yaml | grep -A 5 imagePullSecrets
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔐 Security Best Practices
|
||||
|
||||
### 1. Use Private Registry
|
||||
|
||||
```groovy
|
||||
environment {
|
||||
DOCKER_REGISTRY = 'harbor.thedevops.dev'
|
||||
DOCKER_REPO = 'library'
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Scan Images for Vulnerabilities
|
||||
|
||||
Add to pipeline:
|
||||
```groovy
|
||||
stage('Security Scan') {
|
||||
steps {
|
||||
sh 'trivy image ${DOCKER_REGISTRY}/${DOCKER_REPO}/${APP_NAME}:${IMAGE_TAG}'
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Use ImagePullSecrets
|
||||
|
||||
```bash
|
||||
kubectl create secret docker-registry regcred \
|
||||
--docker-server=harbor.thedevops.dev \
|
||||
--docker-username=admin \
|
||||
--docker-password=password \
|
||||
-n demo-app
|
||||
|
||||
# Add to deployment.yaml:
|
||||
spec:
|
||||
imagePullSecrets:
|
||||
- name: regcred
|
||||
```
|
||||
|
||||
### 4. Don't Hardcode Secrets
|
||||
|
||||
Use Jenkins Credentials:
|
||||
```groovy
|
||||
withCredentials([string(credentialsId: 'api-token', variable: 'TOKEN')]) {
|
||||
sh 'curl -H "Authorization: Bearer $TOKEN" api.example.com'
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📝 Customization
|
||||
|
||||
### Change Application
|
||||
|
||||
Edit `Dockerfile` in Jenkinsfile:
|
||||
```groovy
|
||||
stage('Checkout Source') {
|
||||
steps {
|
||||
// Clone your app repository
|
||||
git branch: 'main',
|
||||
url: 'http://gitea-http.gitea.svc.cluster.local:3000/admin/your-app'
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Add Tests
|
||||
|
||||
```groovy
|
||||
stage('Unit Tests') {
|
||||
steps {
|
||||
sh 'npm test'
|
||||
}
|
||||
}
|
||||
|
||||
stage('Integration Tests') {
|
||||
steps {
|
||||
sh 'npm run test:integration'
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Add Linting
|
||||
|
||||
```groovy
|
||||
stage('Lint') {
|
||||
steps {
|
||||
sh 'npm run lint'
|
||||
sh 'hadolint Dockerfile'
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Multi-Environment Deploy
|
||||
|
||||
```groovy
|
||||
stage('Deploy to Dev') {
|
||||
when { branch 'develop' }
|
||||
steps {
|
||||
sh 'sed -i "s|namespace: .*|namespace: dev|" apps/demo-nginx/deployment.yaml'
|
||||
// ... update and push
|
||||
}
|
||||
}
|
||||
|
||||
stage('Deploy to Production') {
|
||||
when { branch 'main' }
|
||||
steps {
|
||||
input message: 'Deploy to production?'
|
||||
// ... deploy
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Next Steps
|
||||
|
||||
1. ✅ **Configure DNS**: Point `demo-nginx.thedevops.dev` to your cluster IP
|
||||
2. ✅ **Set up monitoring**: Add Prometheus metrics
|
||||
3. ✅ **Add alerts**: Configure alerting for failures
|
||||
4. ✅ **Implement blue-green**: Add traffic splitting
|
||||
5. ✅ **Add rollback**: Implement automatic rollback on failures
|
||||
|
||||
---
|
||||
|
||||
## 📚 References
|
||||
|
||||
- [Jenkins Pipeline Syntax](https://www.jenkins.io/doc/book/pipeline/syntax/)
|
||||
- [ArgoCD Documentation](https://argo-cd.readthedocs.io/)
|
||||
- [Kubernetes Documentation](https://kubernetes.io/docs/)
|
||||
- [Docker Documentation](https://docs.docker.com/)
|
||||
|
||||
---
|
||||
|
||||
## 🤝 Contributing
|
||||
|
||||
To improve this pipeline:
|
||||
1. Fork the repository
|
||||
2. Create feature branch
|
||||
3. Make changes
|
||||
4. Test thoroughly
|
||||
5. Submit pull request
|
||||
|
||||
---
|
||||
|
||||
**Happy Deploying! 🚀**
|
||||
Reference in New Issue
Block a user