Helm Chart Guide

This guide explains how to deploy Cesivi Server using the Helm chart (recommended method).

For raw Kubernetes manifests, see KUBERNETES_DEPLOYMENT.md

Table of Contents

• What is Helm?
• Prerequisites
• Quick Start
• Installation
• Configuration
• Upgrading
• Uninstalling
• Examples
• Values Reference
• Troubleshooting
• Best Practices

What is Helm?

Helm is the package manager for Kubernetes. It simplifies deployment by: - Templating: Parametrize Kubernetes manifests - Versioning: Track releases and rollback - Dependencies: Manage Redis/PostgreSQL automatically - Reusability: One chart, multiple environments

Think of Helm as "apt/yum for Kubernetes" - install, upgrade, rollback with simple commands.

Prerequisites

Required

• Kubernetes cluster (v1.24+)
• Helm (v3.0+)
• kubectl configured to access your cluster

Install Helm

# macOS
brew install helm

# Linux
curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash

# Windows (Chocolatey)
choco install kubernetes-helm

# Windows (Scoop)
scoop install helm

# Verify installation
helm version

Optional

• nginx-ingress controller
• cert-manager for TLS
• Prometheus Operator for monitoring

Quick Start

1-Minute Deployment

# Clone repository
git clone https://github.com/your-org/cesivi.git
cd cesivi

# Install with defaults
helm install my-sharepoint ./charts/cesivi \
  --namespace cesivi \
  --create-namespace

# Wait for deployment
kubectl wait --for=condition=available \
  deployment/my-sharepoint-cesivi \
  -n cesivi \
  --timeout=5m

# Access via port-forward
kubectl port-forward -n cesivi \
  svc/my-sharepoint-cesivi 8080:80

# Open browser
open http://localhost:8080

That's it! Cesivi Server is now running.

Installation

Install from Local Chart

helm install <release-name> ./charts/cesivi \
  --namespace <namespace> \
  --create-namespace

Example:

helm install cesivi ./charts/cesivi \
  --namespace cesivi \
  --create-namespace

Install with Custom Values File

# Development
helm install cesivi ./charts/cesivi \
  -f ./charts/cesivi/values-dev.yaml \
  --namespace cesivi-dev \
  --create-namespace

# Staging
helm install cesivi ./charts/cesivi \
  -f ./charts/cesivi/values-staging.yaml \
  --namespace cesivi-staging \
  --create-namespace

# Production
helm install cesivi ./charts/cesivi \
  -f ./charts/cesivi/values-production.yaml \
  --namespace cesivi-prod \
  --create-namespace

Install with Inline Overrides

helm install cesivi ./charts/cesivi \
  --set replicaCount=5 \
  --set ingress.hosts[0].host=sharepoint.example.com \
  --set externalDatabase.enabled=true \
  --set externalDatabase.host=postgres.example.com \
  --namespace cesivi \
  --create-namespace

Dry Run (Test Before Install)

helm install cesivi ./charts/cesivi \
  --dry-run --debug \
  --namespace cesivi

This renders templates without deploying, useful for validation.

Wait for Deployment

helm install cesivi ./charts/cesivi \
  --wait --timeout 10m \
  --namespace cesivi \
  --create-namespace

Helm waits until all resources are ready before returning.

Configuration

Configuration Methods

1. Edit values.yaml (modify default values)
2. Create custom values file (override specific values)
3. Use --set flags (override via command line)

Priority (lowest to highest):

1. Default values in values.yaml
2. Values in custom file (-f custom-values.yaml)
3. Command-line overrides (--set key=value)

Common Configurations

Change Number of Replicas

helm install cesivi ./charts/cesivi \
  --set replicaCount=5 \
  --namespace cesivi \
  --create-namespace

Configure Ingress

helm install cesivi ./charts/cesivi \
  --set ingress.enabled=true \
  --set ingress.hosts[0].host=sharepoint.example.com \
  --set ingress.tls[0].secretName=sharepoint-tls \
  --set ingress.tls[0].hosts[0]=sharepoint.example.com \
  --namespace cesivi \
  --create-namespace

Use External Database

helm install cesivi ./charts/cesivi \
  --set postgresql.enabled=false \
  --set externalDatabase.enabled=true \
  --set externalDatabase.host=postgres-prod.example.com \
  --set externalDatabase.username=spm_user \
  --set externalDatabase.password=secure-password \
  --namespace cesivi \
  --create-namespace

Use External Redis

helm install cesivi ./charts/cesivi \
  --set redis.enabled=false \
  --set externalRedis.enabled=true \
  --set externalRedis.host=redis-prod.example.com \
  --set externalRedis.port=6379 \
  --namespace cesivi \
  --create-namespace

Enable Persistent Storage

helm install cesivi ./charts/cesivi \
  --set persistence.enabled=true \
  --set persistence.storageClass=premium-ssd \
  --set persistence.size=100Gi \
  --namespace cesivi \
  --create-namespace

Custom Resource Limits

helm install cesivi ./charts/cesivi \
  --set resources.requests.cpu=500m \
  --set resources.requests.memory=1Gi \
  --set resources.limits.cpu=2000m \
  --set resources.limits.memory=4Gi \
  --namespace cesivi \
  --create-namespace

Using Custom Values File

Create my-values.yaml:

replicaCount: 5

ingress:
  enabled: true
  hosts:
    - host: sharepoint.example.com
      paths:
        - path: /
          pathType: Prefix
  tls:
    - secretName: sharepoint-tls
      hosts:
        - sharepoint.example.com

resources:
  requests:
    cpu: 500m
    memory: 1Gi
  limits:
    cpu: 2000m
    memory: 4Gi

externalDatabase:
  enabled: true
  host: postgres.example.com
  username: spm_user
  password: secure-password

externalRedis:
  enabled: true
  host: redis.example.com

Install:

helm install cesivi ./charts/cesivi \
  -f my-values.yaml \
  --namespace cesivi \
  --create-namespace

Upgrading

Upgrade Release

helm upgrade cesivi ./charts/cesivi \
  --namespace cesivi

Upgrade with New Values

helm upgrade cesivi ./charts/cesivi \
  -f new-values.yaml \
  --namespace cesivi

Upgrade Specific Values

# Change replica count
helm upgrade cesivi ./charts/cesivi \
  --set replicaCount=10 \
  --reuse-values \
  --namespace cesivi

--reuse-values keeps existing values and only updates specified ones.

Upgrade Image Version

helm upgrade cesivi ./charts/cesivi \
  --set image.tag=1.1.0 \
  --reuse-values \
  --namespace cesivi

Force Recreation

helm upgrade cesivi ./charts/cesivi \
  --force \
  --namespace cesivi

Deletes and recreates resources. Use with caution!

Rollback

# View release history
helm history cesivi -n cesivi

# Rollback to previous version
helm rollback cesivi -n cesivi

# Rollback to specific revision
helm rollback cesivi 3 -n cesivi

Uninstalling

Uninstall Release

helm uninstall cesivi -n cesivi

This removes all Kubernetes resources created by the chart.

Note: PersistentVolumeClaims are not deleted automatically.

Delete PVCs

kubectl delete pvc -n cesivi \
  -l app.kubernetes.io/instance=cesivi

Delete Namespace

kubectl delete namespace cesivi

Examples

Example 1: Development Environment

Goal: Single replica, no persistence, Swagger enabled

helm install sharepoint-dev ./charts/cesivi \
  -f ./charts/cesivi/values-dev.yaml \
  --namespace sharepoint-dev \
  --create-namespace

values-dev.yaml contains:

replicaCount: 1
autoscaling:
  enabled: false
config:
  enableSwagger: true
redis:
  enabled: true
postgresql:
  enabled: true
persistence:
  enabled: false

Access:

kubectl port-forward -n sharepoint-dev svc/sharepoint-dev-cesivi 8080:80
open http://localhost:8080/swagger

Example 2: Staging Environment

Goal: 2 replicas, auto-scaling, persistent storage, real domain

helm install sharepoint-staging ./charts/cesivi \
  -f ./charts/cesivi/values-staging.yaml \
  --set ingress.hosts[0].host=sharepoint-staging.example.com \
  --namespace sharepoint-staging \
  --create-namespace

values-staging.yaml contains:

replicaCount: 2
autoscaling:
  enabled: true
  minReplicas: 2
  maxReplicas: 5
persistence:
  enabled: true
  size: 10Gi
redis:
  architecture: replication

Example 3: Production Environment

Goal: 3+ replicas, external services, high availability

helm install sharepoint-prod ./charts/cesivi \
  -f ./charts/cesivi/values-production.yaml \
  --set externalDatabase.host=postgres-prod.example.com \
  --set externalDatabase.password=SECRET_PASSWORD \
  --set externalRedis.host=redis-prod.example.com \
  --set ingress.hosts[0].host=sharepoint.example.com \
  --namespace sharepoint-prod \
  --create-namespace

values-production.yaml contains:

replicaCount: 3
autoscaling:
  enabled: true
  minReplicas: 3
  maxReplicas: 10
redis:
  enabled: false  # Using external Redis
postgresql:
  enabled: false  # Using external PostgreSQL
externalDatabase:
  enabled: true
  type: PostgreSQL
externalRedis:
  enabled: true
persistence:
  enabled: true
  storageClass: premium-ssd
  size: 100Gi

Example 4: Multi-Tenant Deployment

Deploy multiple isolated instances:

# Tenant A
helm install tenant-a ./charts/cesivi \
  --set ingress.hosts[0].host=tenant-a.sharepoint.example.com \
  --namespace tenant-a \
  --create-namespace

# Tenant B
helm install tenant-b ./charts/cesivi \
  --set ingress.hosts[0].host=tenant-b.sharepoint.example.com \
  --namespace tenant-b \
  --create-namespace

Each tenant gets isolated resources.

Example 5: High Performance Configuration

Goal: Maximum performance for large deployments

helm install sharepoint-perf ./charts/cesivi \
  --set replicaCount=10 \
  --set resources.requests.cpu=1000m \
  --set resources.requests.memory=2Gi \
  --set resources.limits.cpu=4000m \
  --set resources.limits.memory=8Gi \
  --set autoscaling.maxReplicas=20 \
  --set persistence.storageClass=ultra-ssd \
  --set redis.master.resources.requests.memory=4Gi \
  --set postgresql.primary.resources.requests.memory=8Gi \
  --namespace sharepoint-perf \
  --create-namespace

Values Reference

Core Settings

Parameter	Description	Default
replicaCount	Number of replicas	3
image.registry	Image registry	docker.io
image.repository	Image repository	cesivi/server
image.tag	Image tag	1.0.0
image.pullPolicy	Image pull policy	IfNotPresent

Service Settings

Parameter	Description	Default
service.type	Service type	ClusterIP
service.port	HTTP port	80
service.metricsPort	Metrics port	5000

Ingress Settings

Parameter	Description	Default
ingress.enabled	Enable ingress	true
ingress.className	Ingress class	nginx
ingress.hosts[0].host	Hostname	cesivi.local
ingress.tls	TLS configuration	[]

Resource Settings

Parameter	Description	Default
resources.requests.cpu	CPU request	250m
resources.requests.memory	Memory request	512Mi
resources.limits.cpu	CPU limit	1000m
resources.limits.memory	Memory limit	2Gi

Auto-Scaling Settings

Parameter	Description	Default
autoscaling.enabled	Enable HPA	true
autoscaling.minReplicas	Min replicas	3
autoscaling.maxReplicas	Max replicas	10
autoscaling.targetCPUUtilizationPercentage	CPU target	70
autoscaling.targetMemoryUtilizationPercentage	Memory target	80

Application Configuration

Parameter	Description	Default
config.baseUrl	Base URL	http://cesivi:5000
config.enableSwagger	Enable Swagger	false
config.enableHealthChecks	Enable health checks	true
config.enableMetrics	Enable metrics	true
config.enableTracing	Enable tracing	true

Storage Settings

Parameter	Description	Default
storage.provider	Storage provider	PostgreSQL
storage.enableCaching	Enable caching	true
storage.cacheExpiry	Cache expiry	00:05:00

Redis Settings

Parameter	Description	Default
redis.enabled	Enable Redis	true
redis.architecture	Architecture	standalone
redis.master.persistence.size	Storage size	10Gi

PostgreSQL Settings

Parameter	Description	Default
postgresql.enabled	Enable PostgreSQL	true
postgresql.auth.username	Username	sharepoint_mock
postgresql.auth.password	Password	changeme
postgresql.auth.database	Database name	Cesivi
postgresql.primary.persistence.size	Storage size	50Gi

External Database Settings

Parameter	Description	Default
externalDatabase.enabled	Use external DB	false
externalDatabase.type	DB type	PostgreSQL
externalDatabase.host	DB host	""
externalDatabase.port	DB port	5432
externalDatabase.username	DB username	""
externalDatabase.password	DB password	""
externalDatabase.database	DB name	Cesivi

External Redis Settings

Parameter	Description	Default
externalRedis.enabled	Use external Redis	false
externalRedis.host	Redis host	""
externalRedis.port	Redis port	6379
externalRedis.password	Redis password	""

Persistence Settings

Parameter	Description	Default
persistence.enabled	Enable PVC	false
persistence.storageClass	Storage class	""
persistence.size	PVC size	10Gi

Monitoring Settings

Parameter	Description	Default
prometheus.enabled	Enable metrics	true
prometheus.serviceMonitor.enabled	Enable ServiceMonitor	false
prometheus.serviceMonitor.interval	Scrape interval	30s

For complete values reference, see values.yaml.

Troubleshooting

Release Not Found

Error: Error: release: not found

Solution:

# List all releases
helm list -n cesivi

# If empty, release doesn't exist - install it
helm install cesivi ./charts/cesivi -n cesivi

Template Rendering Errors

Error: Error: template: ...

Solution:

# Validate template syntax
helm lint ./charts/cesivi

# Debug rendering
helm template cesivi ./charts/cesivi --debug

# Check specific values
helm template cesivi ./charts/cesivi \
  -f my-values.yaml \
  --debug

Dependency Issues

Error: Error: found in Chart.yaml, but missing in charts/ directory

Solution:

# Update dependencies
helm dependency update ./charts/cesivi

# This downloads Redis and PostgreSQL charts

Pods Not Starting

Diagnosis:

# Get release status
helm status cesivi -n cesivi

# Check pods
kubectl get pods -n cesivi

# Describe failed pod
kubectl describe pod <pod-name> -n cesivi

# Check logs
kubectl logs <pod-name> -n cesivi

Common Issues:

1. Image pull errors: Check image name/tag in values
2. Resource limits: Reduce requests or add nodes
3. Missing secrets: Verify external DB/Redis credentials

Values Not Applied

Problem: Changed values but pods unchanged

Solution:

# Upgrade doesn't automatically restart pods
# Force recreation:
helm upgrade cesivi ./charts/cesivi \
  -f new-values.yaml \
  --force \
  -n cesivi

# Or restart manually:
kubectl rollout restart deployment/cesivi-cesivi \
  -n cesivi

Upgrade Failed

Problem: Helm upgrade stuck or failed

Solution:

# Check release status
helm status cesivi -n cesivi

# View history
helm history cesivi -n cesivi

# Rollback to previous version
helm rollback cesivi -n cesivi

# Or rollback to specific revision
helm rollback cesivi 2 -n cesivi

Best Practices

1. Use Version Control

Store custom values files in git:

my-helm-values/
├── dev-values.yaml
├── staging-values.yaml
└── production-values.yaml

Track changes and review before applying.

2. Separate Secrets

Never commit secrets to git!

# Store in separate file (don't commit)
cat > secrets.yaml <<EOF
externalDatabase:
  password: "actual-password"
externalRedis:
  password: "actual-password"
EOF

# Install with secrets
helm install cesivi ./charts/cesivi \
  -f base-values.yaml \
  -f secrets.yaml \
  -n cesivi

Or use external secret management (HashiCorp Vault, AWS Secrets Manager, etc.).

3. Use Dry Run

Always test before deploying:

# Render templates
helm template cesivi ./charts/cesivi \
  -f my-values.yaml

# Dry run install
helm install cesivi ./charts/cesivi \
  -f my-values.yaml \
  --dry-run --debug \
  -n cesivi

4. Pin Chart Versions

# In requirements.yaml or Chart.yaml dependencies
dependencies:
  - name: redis
    version: "18.0.0"  # Exact version
    repository: "https://charts.bitnami.com/bitnami"

Prevents breaking changes from automatic updates.

5. Monitor Releases

# Watch release status
watch helm list -n cesivi

# Check deployment progress
kubectl get pods -n cesivi -w

6. Document Custom Values

Add comments to custom values files:

# Production values for Cesivi Server
# Last updated: 2025-01-11
# Owner: Platform Team

replicaCount: 5  # Increased for high availability

resources:
  requests:
    cpu: 1000m   # Based on load testing
    memory: 2Gi  # Baseline from monitoring

7. Use Namespaces

Deploy to dedicated namespaces:

# Dev
helm install sharepoint-dev ./charts/cesivi \
  -n sharepoint-dev --create-namespace

# Staging
helm install sharepoint-staging ./charts/cesivi \
  -n sharepoint-staging --create-namespace

# Production
helm install sharepoint-prod ./charts/cesivi \
  -n sharepoint-prod --create-namespace

Provides isolation and easier management.

8. Automate with CI/CD

# Example GitHub Actions workflow
name: Deploy to Production
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: azure/setup-helm@v3
      - uses: azure/setup-kubectl@v3
      - name: Deploy
        run: |
          helm upgrade --install sharepoint-prod ./charts/cesivi \
            -f production-values.yaml \
            --wait --timeout 10m \
            -n sharepoint-prod

9. Health Checks

Always verify deployment health:

# After install/upgrade
helm test cesivi -n cesivi

# Check health endpoints
kubectl port-forward -n cesivi svc/cesivi-cesivi 8080:80
curl http://localhost:8080/health

10. Backup Before Upgrade

# Backup current release
helm get values cesivi -n cesivi > current-values.yaml

# Backup namespace
kubectl get all -n cesivi -o yaml > namespace-backup.yaml

# Then upgrade
helm upgrade cesivi ./charts/cesivi -f new-values.yaml -n cesivi

Next Steps

• Kubernetes Guide: See KUBERNETES_DEPLOYMENT.md for manual deployment
• Observability: See OBSERVABILITY_GUIDE.md for monitoring setup
• API Reference: See API_REFERENCE.md for API documentation

Support

• GitHub Issues
• Documentation
• Helm Chart README