initial commit
Change-Id: I9c68c43e939d2c1a3b95a68b71ecc5ba861a4df5
This commit is contained in:
Scaffolder
384
docs/deployment.md
Normal file
384
docs/deployment.md
Normal file
@@ -0,0 +1,384 @@
|
||||
# Deployment Guide
|
||||
|
||||
This guide covers deploying online-boutique to Azure Kubernetes Service via Humanitec or ArgoCD.
|
||||
|
||||
## Deployment Methods
|
||||
|
||||
### 1. Humanitec Platform Orchestrator (Primary)
|
||||
|
||||
Humanitec manages deployments using the `score.yaml` specification, automatically provisioning resources and handling promotions across environments.
|
||||
|
||||
#### Prerequisites
|
||||
|
||||
- Humanitec Organization: `kyn-cjot`
|
||||
- Application registered in Humanitec
|
||||
- Environments created (development, staging, production)
|
||||
- Gitea Actions configured with HUMANITEC_TOKEN secret
|
||||
|
||||
#### Automatic Deployment (via Gitea Actions)
|
||||
|
||||
Push to trigger workflows:
|
||||
|
||||
```bash
|
||||
git add .
|
||||
git commit -m "feat: new feature"
|
||||
git push origin main
|
||||
```
|
||||
|
||||
**Build & Push Workflow** (`.gitea/workflows/build-push.yml`):
|
||||
1. Maven build & test
|
||||
2. Docker image build
|
||||
3. Push to Azure Container Registry (ACR)
|
||||
4. Tags: `latest`, `git-SHA`, `semantic-version`
|
||||
|
||||
**Deploy Workflow** (`.gitea/workflows/deploy-humanitec.yml`):
|
||||
1. Parses image from build
|
||||
2. Updates score.yaml with image reference
|
||||
3. Deploys to Humanitec environment
|
||||
4. Triggers orchestration
|
||||
|
||||
#### Manual Deployment with humctl CLI
|
||||
|
||||
Install Humanitec CLI:
|
||||
|
||||
```bash
|
||||
# macOS
|
||||
brew install humanitec/tap/humctl
|
||||
|
||||
# Linux/Windows
|
||||
curl -s https://get.humanitec.io/install.sh | bash
|
||||
```
|
||||
|
||||
Login:
|
||||
|
||||
```bash
|
||||
humctl login --org kyn-cjot
|
||||
```
|
||||
|
||||
Deploy from Score:
|
||||
|
||||
```bash
|
||||
humctl score deploy \
|
||||
--org kyn-cjot \
|
||||
--app online-boutique \
|
||||
--env development \
|
||||
--file score.yaml \
|
||||
--image bstagecjotdevacr.azurecr.io/online-boutique:latest \
|
||||
--message "Manual deployment from local"
|
||||
```
|
||||
|
||||
Deploy specific version:
|
||||
|
||||
```bash
|
||||
humctl score deploy \
|
||||
--org kyn-cjot \
|
||||
--app online-boutique \
|
||||
--env production \
|
||||
--file score.yaml \
|
||||
--image bstagecjotdevacr.azurecr.io/online-boutique:v1.2.3 \
|
||||
--message "Production release v1.2.3"
|
||||
```
|
||||
|
||||
#### Environment Promotion
|
||||
|
||||
Promote from development → staging:
|
||||
|
||||
```bash
|
||||
humctl deploy \
|
||||
--org kyn-cjot \
|
||||
--app online-boutique \
|
||||
--env staging \
|
||||
--from development \
|
||||
--message "Promote to staging after testing"
|
||||
```
|
||||
|
||||
Promote to production:
|
||||
|
||||
```bash
|
||||
humctl deploy \
|
||||
--org kyn-cjot \
|
||||
--app online-boutique \
|
||||
--env production \
|
||||
--from staging \
|
||||
--message "Production release"
|
||||
```
|
||||
|
||||
#### Check Deployment Status
|
||||
|
||||
```bash
|
||||
# List deployments
|
||||
humctl get deployments \
|
||||
--org kyn-cjot \
|
||||
--app online-boutique \
|
||||
--env development
|
||||
|
||||
# Get specific deployment
|
||||
humctl get deployment <DEPLOYMENT_ID> \
|
||||
--org kyn-cjot \
|
||||
--app online-boutique \
|
||||
--env development
|
||||
|
||||
# View deployment logs
|
||||
humctl logs \
|
||||
--org kyn-cjot \
|
||||
--app online-boutique \
|
||||
--env development
|
||||
```
|
||||
|
||||
### 2. ArgoCD GitOps (Fallback)
|
||||
|
||||
If Humanitec is unavailable, use ArgoCD with Kubernetes manifests in `deploy/`.
|
||||
|
||||
#### Create ArgoCD Application
|
||||
|
||||
```yaml
|
||||
apiVersion: argoproj.io/v1alpha1
|
||||
kind: Application
|
||||
metadata:
|
||||
name: online-boutique
|
||||
namespace: argocd
|
||||
spec:
|
||||
project: default
|
||||
source:
|
||||
repoURL: https://gitea.kyndemo.live/validate/online-boutique.git
|
||||
targetRevision: main
|
||||
path: deploy
|
||||
destination:
|
||||
server: https://kubernetes.default.svc
|
||||
namespace:
|
||||
syncPolicy:
|
||||
automated:
|
||||
prune: true
|
||||
selfHeal: true
|
||||
syncOptions:
|
||||
- CreateNamespace=true
|
||||
```
|
||||
|
||||
Apply:
|
||||
|
||||
```bash
|
||||
kubectl apply -f argocd-app.yaml
|
||||
```
|
||||
|
||||
#### Manual Deploy with kubectl
|
||||
|
||||
Update image in `deploy/kustomization.yaml`:
|
||||
|
||||
```yaml
|
||||
images:
|
||||
- name: app-image
|
||||
newName: bstagecjotdevacr.azurecr.io/online-boutique
|
||||
newTag: v1.2.3
|
||||
```
|
||||
|
||||
Deploy:
|
||||
|
||||
```bash
|
||||
kubectl apply -k deploy/
|
||||
```
|
||||
|
||||
Verify:
|
||||
|
||||
```bash
|
||||
kubectl -n get pods
|
||||
kubectl -n get svc
|
||||
kubectl -n get ing
|
||||
```
|
||||
|
||||
## Kubernetes Access
|
||||
|
||||
### Get AKS Credentials
|
||||
|
||||
```bash
|
||||
az aks get-credentials \
|
||||
--resource-group bstage-cjot-dev \
|
||||
--name bstage-cjot-dev-aks \
|
||||
--overwrite-existing
|
||||
```
|
||||
|
||||
### View Application
|
||||
|
||||
```bash
|
||||
# List pods
|
||||
kubectl -n get pods
|
||||
|
||||
# Check pod logs
|
||||
kubectl -n logs -f deployment/online-boutique
|
||||
|
||||
# Describe deployment
|
||||
kubectl -n describe deployment online-boutique
|
||||
|
||||
# Port-forward for local access
|
||||
kubectl -n port-forward svc/online-boutique-service 8080:80
|
||||
```
|
||||
|
||||
### Check Health
|
||||
|
||||
```bash
|
||||
# Health endpoint
|
||||
kubectl -n exec -it deployment/online-boutique -- \
|
||||
curl http://localhost:8080/actuator/health
|
||||
|
||||
# Metrics endpoint
|
||||
kubectl -n exec -it deployment/online-boutique -- \
|
||||
curl http://localhost:8080/actuator/prometheus
|
||||
```
|
||||
|
||||
## Environment Configuration
|
||||
|
||||
### Development
|
||||
|
||||
- **Purpose**: Active development, frequent deployments
|
||||
- **Image Tag**: `latest` or `git-SHA`
|
||||
- **Replicas**: 1
|
||||
- **Resources**: Minimal (requests: 256Mi RAM, 250m CPU)
|
||||
- **Monitoring**: Prometheus scraping enabled
|
||||
|
||||
### Staging
|
||||
|
||||
- **Purpose**: Pre-production testing, integration tests
|
||||
- **Image Tag**: Semantic version (e.g., `v1.2.3-rc.1`)
|
||||
- **Replicas**: 2
|
||||
- **Resources**: Production-like (requests: 512Mi RAM, 500m CPU)
|
||||
- **Monitoring**: Full observability stack
|
||||
|
||||
### Production
|
||||
|
||||
- **Purpose**: Live traffic, stable releases
|
||||
- **Image Tag**: Semantic version (e.g., `v1.2.3`)
|
||||
- **Replicas**: 3+ (autoscaling)
|
||||
- **Resources**: Right-sized (requests: 1Gi RAM, 1 CPU)
|
||||
- **Monitoring**: Alerts enabled, SLO tracking
|
||||
|
||||
## Rollback Procedures
|
||||
|
||||
### Humanitec Rollback
|
||||
|
||||
```bash
|
||||
# List previous deployments
|
||||
humctl get deployments \
|
||||
--org kyn-cjot \
|
||||
--app online-boutique \
|
||||
--env production
|
||||
|
||||
# Rollback to specific deployment
|
||||
humctl deploy \
|
||||
--org kyn-cjot \
|
||||
--app online-boutique \
|
||||
--env production \
|
||||
--deployment-id <PREVIOUS_DEPLOYMENT_ID> \
|
||||
--message "Rollback due to issue"
|
||||
```
|
||||
|
||||
### Kubernetes Rollback
|
||||
|
||||
```bash
|
||||
# Rollback to previous revision
|
||||
kubectl -n rollout undo deployment/online-boutique
|
||||
|
||||
# Rollback to specific revision
|
||||
kubectl -n rollout undo deployment/online-boutique --to-revision=2
|
||||
|
||||
# Check rollout status
|
||||
kubectl -n rollout status deployment/online-boutique
|
||||
|
||||
# View rollout history
|
||||
kubectl -n rollout history deployment/online-boutique
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Pod Not Starting
|
||||
|
||||
```bash
|
||||
# Check pod events
|
||||
kubectl -n describe pod <POD_NAME>
|
||||
|
||||
# Check logs
|
||||
kubectl -n logs <POD_NAME>
|
||||
|
||||
# Check previous container logs (if restarting)
|
||||
kubectl -n logs <POD_NAME> --previous
|
||||
```
|
||||
|
||||
### Image Pull Errors
|
||||
|
||||
```bash
|
||||
# Verify ACR access
|
||||
az acr login --name bstagecjotdevacr
|
||||
|
||||
# Check image exists
|
||||
az acr repository show-tags --name bstagecjotdevacr --repository online-boutique
|
||||
|
||||
# Verify AKS ACR integration
|
||||
az aks check-acr \
|
||||
--resource-group bstage-cjot-dev \
|
||||
--name bstage-cjot-dev-aks \
|
||||
--acr bstagecjotdevacr.azurecr.io
|
||||
```
|
||||
|
||||
### Service Not Accessible
|
||||
|
||||
```bash
|
||||
# Check service endpoints
|
||||
kubectl -n get endpoints online-boutique-service
|
||||
|
||||
# Check ingress
|
||||
kubectl -n describe ingress online-boutique-ingress
|
||||
|
||||
# Test internal connectivity
|
||||
kubectl -n run curl-test --image=curlimages/curl:latest --rm -it --restart=Never -- \
|
||||
curl http://online-boutique-service/actuator/health
|
||||
```
|
||||
|
||||
### Humanitec Deployment Stuck
|
||||
|
||||
```bash
|
||||
# Check deployment status
|
||||
humctl get deployment <DEPLOYMENT_ID> \
|
||||
--org kyn-cjot \
|
||||
--app online-boutique \
|
||||
--env development
|
||||
|
||||
# View error logs
|
||||
humctl logs \
|
||||
--org kyn-cjot \
|
||||
--app online-boutique \
|
||||
--env development \
|
||||
--deployment-id <DEPLOYMENT_ID>
|
||||
|
||||
# Cancel stuck deployment
|
||||
humctl delete deployment <DEPLOYMENT_ID> \
|
||||
--org kyn-cjot \
|
||||
--app online-boutique \
|
||||
--env development
|
||||
```
|
||||
|
||||
### Resource Issues
|
||||
|
||||
```bash
|
||||
# Check resource usage
|
||||
kubectl -n top pods
|
||||
|
||||
# Describe pod for resource constraints
|
||||
kubectl -n describe pod <POD_NAME> | grep -A 10 "Conditions:"
|
||||
|
||||
# Check node capacity
|
||||
kubectl describe nodes | grep -A 10 "Allocated resources:"
|
||||
```
|
||||
|
||||
## Blue-Green Deployments
|
||||
|
||||
For zero-downtime deployments with Humanitec:
|
||||
|
||||
1. Deploy new version to staging
|
||||
2. Run smoke tests
|
||||
3. Promote to production with traffic splitting
|
||||
4. Monitor metrics
|
||||
5. Complete cutover or rollback
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [Configure monitoring](monitoring.md)
|
||||
- [Review architecture](architecture.md)
|
||||
- [Return to overview](index.md)
|
||||
Reference in New Issue
Block a user