385 lines
7.7 KiB
Markdown
385 lines
7.7 KiB
Markdown
# 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)
|