Add comprehensive Warehouse13 Helm chart with configurable images
Features: - Complete Helm chart at helm/warehouse13/ with Warehouse13 branding - Configurable images for all components (PostgreSQL, MinIO, API, Frontend) - Support for 3 deployment scenarios: dev, production, air-gapped - 14 Kubernetes templates: Deployments, StatefulSets, Services, Ingress - Persistent storage with configurable storage classes - Health checks for all services - Ingress with TLS support - Security contexts and RBAC - Comprehensive documentation: - HELM-DEPLOYMENT.md (main Kubernetes guide) - helm/warehouse13/README.md (full chart docs) - helm/warehouse13/QUICKSTART.md (5-min deployment) - Example values files (dev, production, air-gapped) - Updated main README.md with Helm deployment instructions - Marked old helm chart as deprecated All component images fully configurable via values.yaml: - postgres:15-alpine - minio/minio:latest - warehouse13/api:latest - warehouse13/frontend:latest 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
517
HELM-DEPLOYMENT.md
Normal file
517
HELM-DEPLOYMENT.md
Normal file
@@ -0,0 +1,517 @@
|
||||
# Warehouse13 - Kubernetes Deployment with Helm
|
||||
|
||||
This guide covers deploying Warehouse13 to Kubernetes using the official Helm chart.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [Prerequisites](#prerequisites)
|
||||
2. [Quick Start](#quick-start)
|
||||
3. [Deployment Scenarios](#deployment-scenarios)
|
||||
4. [Configuration](#configuration)
|
||||
5. [Post-Deployment](#post-deployment)
|
||||
6. [Upgrading](#upgrading)
|
||||
7. [Troubleshooting](#troubleshooting)
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Kubernetes 1.19+ cluster
|
||||
- Helm 3.0+
|
||||
- kubectl configured to access your cluster
|
||||
- Persistent volume provisioner (for production deployments)
|
||||
|
||||
### Installing Helm
|
||||
|
||||
```bash
|
||||
# macOS
|
||||
brew install helm
|
||||
|
||||
# Linux
|
||||
curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash
|
||||
|
||||
# Windows
|
||||
choco install kubernetes-helm
|
||||
```
|
||||
|
||||
## Quick Start
|
||||
|
||||
### 1. Standard Deployment (Internet Access)
|
||||
|
||||
```bash
|
||||
# Create namespace
|
||||
kubectl create namespace warehouse13
|
||||
|
||||
# Install with default values
|
||||
helm install warehouse13 ./helm/warehouse13 \
|
||||
--namespace warehouse13
|
||||
|
||||
# Wait for pods to be ready
|
||||
kubectl wait --for=condition=ready pod \
|
||||
--all --namespace warehouse13 --timeout=300s
|
||||
```
|
||||
|
||||
### 2. Access the Application
|
||||
|
||||
```bash
|
||||
# Frontend
|
||||
kubectl port-forward -n warehouse13 svc/warehouse13-frontend 4200:80
|
||||
|
||||
# API
|
||||
kubectl port-forward -n warehouse13 svc/warehouse13-api 8000:8000
|
||||
|
||||
# MinIO Console
|
||||
kubectl port-forward -n warehouse13 svc/warehouse13-minio 9001:9001
|
||||
```
|
||||
|
||||
Then visit:
|
||||
- Frontend: http://localhost:4200
|
||||
- API Docs: http://localhost:8000/docs
|
||||
- MinIO Console: http://localhost:9001
|
||||
|
||||
## Deployment Scenarios
|
||||
|
||||
### Development Environment
|
||||
|
||||
For local testing or CI/CD:
|
||||
|
||||
```bash
|
||||
helm install warehouse13-dev ./helm/warehouse13 \
|
||||
--namespace warehouse13-dev \
|
||||
--create-namespace \
|
||||
--values ./helm/warehouse13/values-dev.yaml
|
||||
```
|
||||
|
||||
**Features:**
|
||||
- Single replica for all services
|
||||
- emptyDir storage (no persistence)
|
||||
- Minimal resource requests
|
||||
- Always pull latest dev images
|
||||
|
||||
### Production Environment
|
||||
|
||||
For production with ingress and high availability:
|
||||
|
||||
```bash
|
||||
# First, update the values file with your domain and secrets
|
||||
cp ./helm/warehouse13/values-production.yaml ./my-production-values.yaml
|
||||
|
||||
# Edit the file:
|
||||
# - Set postgres.auth.password
|
||||
# - Set minio.auth.rootUser and rootPassword
|
||||
# - Set ingress.hosts[0].host to your domain
|
||||
# - Update storageClass for your environment
|
||||
|
||||
# Install
|
||||
helm install warehouse13 ./helm/warehouse13 \
|
||||
--namespace warehouse13 \
|
||||
--create-namespace \
|
||||
--values ./my-production-values.yaml
|
||||
```
|
||||
|
||||
**Features:**
|
||||
- 3 replicas for API and frontend
|
||||
- Persistent storage with PVCs
|
||||
- Ingress with TLS support
|
||||
- Resource limits and requests
|
||||
- Health checks enabled
|
||||
- Pod anti-affinity for distribution
|
||||
|
||||
### Air-Gapped Environment
|
||||
|
||||
For restricted/disconnected environments:
|
||||
|
||||
```bash
|
||||
# 1. First, push images to your internal registry
|
||||
# Example using harbor.internal.example.com
|
||||
|
||||
# Pull images (on internet-connected machine)
|
||||
docker pull postgres:15-alpine
|
||||
docker pull minio/minio:latest
|
||||
docker pull warehouse13/api:v1.0.0
|
||||
docker pull warehouse13/frontend:v1.0.0
|
||||
|
||||
# Tag for internal registry
|
||||
docker tag postgres:15-alpine harbor.internal.example.com/library/postgres:15-alpine
|
||||
docker tag minio/minio:latest harbor.internal.example.com/library/minio:latest
|
||||
docker tag warehouse13/api:v1.0.0 harbor.internal.example.com/warehouse13/api:v1.0.0
|
||||
docker tag warehouse13/frontend:v1.0.0 harbor.internal.example.com/warehouse13/frontend:v1.0.0
|
||||
|
||||
# Push to internal registry
|
||||
docker push harbor.internal.example.com/library/postgres:15-alpine
|
||||
docker push harbor.internal.example.com/library/minio:latest
|
||||
docker push harbor.internal.example.com/warehouse13/api:v1.0.0
|
||||
docker push harbor.internal.example.com/warehouse13/frontend:v1.0.0
|
||||
|
||||
# 2. Update the values file with your registry
|
||||
cp ./helm/warehouse13/values-airgapped.yaml ./my-airgapped-values.yaml
|
||||
|
||||
# Edit to match your environment:
|
||||
# - Update all image.repository values
|
||||
# - Set secure passwords
|
||||
# - Configure storage classes
|
||||
# - Add node selectors/tolerations if needed
|
||||
|
||||
# 3. Install on air-gapped cluster
|
||||
helm install warehouse13 ./helm/warehouse13 \
|
||||
--namespace warehouse13 \
|
||||
--create-namespace \
|
||||
--values ./my-airgapped-values.yaml
|
||||
```
|
||||
|
||||
**Features:**
|
||||
- All images from custom registry
|
||||
- Local storage class support
|
||||
- Node selectors for specific nodes
|
||||
- Tolerations for tainted nodes
|
||||
|
||||
## Configuration
|
||||
|
||||
### Configurable Images
|
||||
|
||||
All component images can be customized:
|
||||
|
||||
```yaml
|
||||
# PostgreSQL
|
||||
postgres:
|
||||
image:
|
||||
repository: postgres # or your-registry/postgres
|
||||
tag: 15-alpine
|
||||
pullPolicy: IfNotPresent
|
||||
|
||||
# MinIO
|
||||
minio:
|
||||
image:
|
||||
repository: minio/minio # or your-registry/minio
|
||||
tag: latest
|
||||
pullPolicy: IfNotPresent
|
||||
|
||||
# API Backend
|
||||
api:
|
||||
image:
|
||||
repository: warehouse13/api # or your-registry/warehouse13-api
|
||||
tag: v1.0.0
|
||||
pullPolicy: IfNotPresent
|
||||
|
||||
# Frontend
|
||||
frontend:
|
||||
image:
|
||||
repository: warehouse13/frontend # or your-registry/warehouse13-frontend
|
||||
tag: v1.0.0
|
||||
pullPolicy: IfNotPresent
|
||||
```
|
||||
|
||||
### Quick Image Override
|
||||
|
||||
```bash
|
||||
# Override images from command line
|
||||
helm install warehouse13 ./helm/warehouse13 \
|
||||
--set postgres.image.repository=myregistry.com/postgres \
|
||||
--set postgres.image.tag=15-alpine \
|
||||
--set minio.image.repository=myregistry.com/minio \
|
||||
--set minio.image.tag=latest \
|
||||
--set api.image.repository=myregistry.com/warehouse13-api \
|
||||
--set api.image.tag=v1.0.0 \
|
||||
--set frontend.image.repository=myregistry.com/warehouse13-frontend \
|
||||
--set frontend.image.tag=v1.0.0
|
||||
```
|
||||
|
||||
### Storage Configuration
|
||||
|
||||
```yaml
|
||||
# PostgreSQL storage
|
||||
postgres:
|
||||
persistence:
|
||||
enabled: true
|
||||
size: 50Gi
|
||||
storageClass: "fast-ssd" # or "" for default
|
||||
|
||||
# MinIO storage
|
||||
minio:
|
||||
persistence:
|
||||
enabled: true
|
||||
size: 500Gi
|
||||
storageClass: "bulk-storage" # or "" for default
|
||||
```
|
||||
|
||||
### Resource Configuration
|
||||
|
||||
```yaml
|
||||
# API resources
|
||||
api:
|
||||
resources:
|
||||
requests:
|
||||
memory: "512Mi"
|
||||
cpu: "500m"
|
||||
limits:
|
||||
memory: "1Gi"
|
||||
cpu: "1000m"
|
||||
|
||||
# Frontend resources
|
||||
frontend:
|
||||
resources:
|
||||
requests:
|
||||
memory: "256Mi"
|
||||
cpu: "250m"
|
||||
limits:
|
||||
memory: "512Mi"
|
||||
cpu: "500m"
|
||||
```
|
||||
|
||||
### Ingress Configuration
|
||||
|
||||
```yaml
|
||||
ingress:
|
||||
enabled: true
|
||||
className: "nginx"
|
||||
annotations:
|
||||
cert-manager.io/cluster-issuer: "letsencrypt-prod"
|
||||
nginx.ingress.kubernetes.io/ssl-redirect: "true"
|
||||
hosts:
|
||||
- host: warehouse13.example.com
|
||||
paths:
|
||||
- path: /
|
||||
pathType: Prefix
|
||||
backend: frontend
|
||||
- path: /api
|
||||
pathType: Prefix
|
||||
backend: api
|
||||
tls:
|
||||
- secretName: warehouse13-tls
|
||||
hosts:
|
||||
- warehouse13.example.com
|
||||
```
|
||||
|
||||
## Post-Deployment
|
||||
|
||||
### Verify Installation
|
||||
|
||||
```bash
|
||||
# Check all pods are running
|
||||
kubectl get pods -n warehouse13
|
||||
|
||||
# Check services
|
||||
kubectl get svc -n warehouse13
|
||||
|
||||
# Check PVCs
|
||||
kubectl get pvc -n warehouse13
|
||||
|
||||
# Check ingress (if enabled)
|
||||
kubectl get ingress -n warehouse13
|
||||
```
|
||||
|
||||
### View Logs
|
||||
|
||||
```bash
|
||||
# API logs
|
||||
kubectl logs -n warehouse13 -l app.kubernetes.io/component=api --tail=100 -f
|
||||
|
||||
# Frontend logs
|
||||
kubectl logs -n warehouse13 -l app.kubernetes.io/component=frontend --tail=100 -f
|
||||
|
||||
# PostgreSQL logs
|
||||
kubectl logs -n warehouse13 warehouse13-postgres-0 --tail=100 -f
|
||||
|
||||
# MinIO logs
|
||||
kubectl logs -n warehouse13 warehouse13-minio-0 --tail=100 -f
|
||||
```
|
||||
|
||||
### Initialize MinIO Bucket
|
||||
|
||||
```bash
|
||||
# Port-forward to MinIO console
|
||||
kubectl port-forward -n warehouse13 svc/warehouse13-minio 9001:9001
|
||||
|
||||
# Open http://localhost:9001
|
||||
# Login with credentials from values.yaml
|
||||
# Create bucket: "artifacts"
|
||||
```
|
||||
|
||||
## Upgrading
|
||||
|
||||
### Upgrade to New Version
|
||||
|
||||
```bash
|
||||
# Update image tags in values file
|
||||
# Then run upgrade
|
||||
helm upgrade warehouse13 ./helm/warehouse13 \
|
||||
--namespace warehouse13 \
|
||||
--values ./my-production-values.yaml \
|
||||
--wait \
|
||||
--timeout 10m
|
||||
|
||||
# Check rollout status
|
||||
kubectl rollout status deployment/warehouse13-api -n warehouse13
|
||||
kubectl rollout status deployment/warehouse13-frontend -n warehouse13
|
||||
```
|
||||
|
||||
### Rollback
|
||||
|
||||
```bash
|
||||
# View revision history
|
||||
helm history warehouse13 -n warehouse13
|
||||
|
||||
# Rollback to previous version
|
||||
helm rollback warehouse13 -n warehouse13
|
||||
|
||||
# Rollback to specific revision
|
||||
helm rollback warehouse13 2 -n warehouse13
|
||||
```
|
||||
|
||||
### Update Values Only
|
||||
|
||||
```bash
|
||||
# Update configuration without changing images
|
||||
helm upgrade warehouse13 ./helm/warehouse13 \
|
||||
--namespace warehouse13 \
|
||||
--values ./my-updated-values.yaml \
|
||||
--reuse-values
|
||||
```
|
||||
|
||||
## Backup and Restore
|
||||
|
||||
### PostgreSQL Backup
|
||||
|
||||
```bash
|
||||
# Create backup
|
||||
kubectl exec -n warehouse13 warehouse13-postgres-0 -- \
|
||||
pg_dump -U warehouse13user warehouse13 > backup-$(date +%Y%m%d).sql
|
||||
|
||||
# Restore
|
||||
cat backup-20241016.sql | kubectl exec -i -n warehouse13 warehouse13-postgres-0 -- \
|
||||
psql -U warehouse13user warehouse13
|
||||
```
|
||||
|
||||
### MinIO Backup
|
||||
|
||||
```bash
|
||||
# Install MinIO Client
|
||||
wget https://dl.min.io/client/mc/release/linux-amd64/mc
|
||||
chmod +x mc
|
||||
|
||||
# Configure
|
||||
kubectl port-forward -n warehouse13 svc/warehouse13-minio 9000:9000
|
||||
mc alias set w13 http://localhost:9000 <access-key> <secret-key>
|
||||
|
||||
# Backup bucket
|
||||
mc mirror w13/artifacts ./backup/artifacts-$(date +%Y%m%d)
|
||||
|
||||
# Restore
|
||||
mc mirror ./backup/artifacts-20241016 w13/artifacts
|
||||
```
|
||||
|
||||
### Full Backup
|
||||
|
||||
```bash
|
||||
# Backup all PVCs
|
||||
for pvc in $(kubectl get pvc -n warehouse13 -o name); do
|
||||
pvc_name=$(basename $pvc)
|
||||
kubectl get -n warehouse13 $pvc -o yaml > backup-${pvc_name}.yaml
|
||||
done
|
||||
|
||||
# Backup Helm values
|
||||
helm get values warehouse13 -n warehouse13 > backup-values.yaml
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Pods Not Starting
|
||||
|
||||
```bash
|
||||
# Check pod status
|
||||
kubectl get pods -n warehouse13
|
||||
|
||||
# Describe pod for events
|
||||
kubectl describe pod <pod-name> -n warehouse13
|
||||
|
||||
# Check logs
|
||||
kubectl logs <pod-name> -n warehouse13
|
||||
|
||||
# Common issues:
|
||||
# - ImagePullBackOff: Check image repository and credentials
|
||||
# - Pending: Check PVC status and node resources
|
||||
# - CrashLoopBackOff: Check application logs
|
||||
```
|
||||
|
||||
### PVC Issues
|
||||
|
||||
```bash
|
||||
# Check PVC status
|
||||
kubectl get pvc -n warehouse13
|
||||
|
||||
# Describe PVC
|
||||
kubectl describe pvc <pvc-name> -n warehouse13
|
||||
|
||||
# Common issues:
|
||||
# - Pending: No storage class or insufficient storage
|
||||
# - Bound: PVC is healthy
|
||||
```
|
||||
|
||||
### Database Connection Issues
|
||||
|
||||
```bash
|
||||
# Test PostgreSQL connection
|
||||
kubectl exec -it -n warehouse13 warehouse13-postgres-0 -- \
|
||||
psql -U warehouse13user -d warehouse13
|
||||
|
||||
# Check database logs
|
||||
kubectl logs -n warehouse13 warehouse13-postgres-0 --tail=100
|
||||
|
||||
# Verify secret
|
||||
kubectl get secret -n warehouse13 warehouse13-secrets -o yaml
|
||||
```
|
||||
|
||||
### Ingress Not Working
|
||||
|
||||
```bash
|
||||
# Check ingress status
|
||||
kubectl get ingress -n warehouse13
|
||||
kubectl describe ingress -n warehouse13 warehouse13-ingress
|
||||
|
||||
# Check ingress controller logs
|
||||
kubectl logs -n ingress-nginx -l app.kubernetes.io/component=controller
|
||||
|
||||
# Verify TLS certificate
|
||||
kubectl get certificate -n warehouse13
|
||||
kubectl describe certificate -n warehouse13 warehouse13-tls
|
||||
```
|
||||
|
||||
### Performance Issues
|
||||
|
||||
```bash
|
||||
# Check resource usage
|
||||
kubectl top pods -n warehouse13
|
||||
kubectl top nodes
|
||||
|
||||
# Check if pods are being throttled
|
||||
kubectl describe pod <pod-name> -n warehouse13 | grep -A 5 "State:"
|
||||
|
||||
# Increase resources
|
||||
helm upgrade warehouse13 ./helm/warehouse13 \
|
||||
--set api.resources.limits.memory=2Gi \
|
||||
--set api.resources.limits.cpu=2000m
|
||||
```
|
||||
|
||||
## Uninstalling
|
||||
|
||||
```bash
|
||||
# Uninstall the release
|
||||
helm uninstall warehouse13 -n warehouse13
|
||||
|
||||
# Delete PVCs (data will be lost!)
|
||||
kubectl delete pvc -n warehouse13 -l app.kubernetes.io/instance=warehouse13
|
||||
|
||||
# Delete namespace
|
||||
kubectl delete namespace warehouse13
|
||||
```
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- [Helm Chart README](./helm/warehouse13/README.md)
|
||||
- [Values Documentation](./helm/warehouse13/values.yaml)
|
||||
- [Docker Deployment Guide](./DEPLOYMENT.md)
|
||||
- [Main README](./README.md)
|
||||
|
||||
## Support
|
||||
|
||||
For issues and questions:
|
||||
- GitHub Issues: https://github.com/yourusername/warehouse13/issues
|
||||
- Helm Chart Issues: Tag with `helm` label
|
||||
Reference in New Issue
Block a user