file/lbl-01/DEPLOYMENT.md

Label Studio Helm Chart Deployment Guide

This guide provides step-by-step instructions for deploying Label Studio using the Helm chart.

Prerequisites

Before deploying Label Studio, ensure you have:

1. Kubernetes cluster (v1.19+)
2. Helm (v3.0+)
3. kubectl configured to access your cluster
4. PostgreSQL database (can be deployed separately or use managed service)
5. Redis instance (can be deployed separately or use managed service)
6. Storage class available in your cluster

Quick Start

1. Clone or Download the Chart

# If you have the chart locally
cd /path/to/helm-chart/lbl-01

# Or download from repository
helm repo add label-studio https://your-repo-url
helm repo update

2. Create Namespace

kubectl create namespace label-studio

3. Deploy Dependencies

PostgreSQL (using Bitnami chart)

helm repo add bitnami https://charts.bitnami.com/bitnami
helm repo update

helm install postgresql bitnami/postgresql \
  --namespace label-studio \
  --set auth.postgresPassword=labelstudio123 \
  --set auth.username=labelstudio \
  --set auth.password=labelstudio123 \
  --set auth.database=labelstudio \
  --set primary.persistence.enabled=true \
  --set primary.persistence.size=20Gi

Redis (using Bitnami chart)

helm install redis bitnami/redis \
  --namespace label-studio \
  --set auth.password=redis123 \
  --set master.persistence.enabled=true \
  --set master.persistence.size=8Gi

4. Create Secrets

# PostgreSQL secret
kubectl create secret generic postgresql-secret \
  --from-literal=password=labelstudio123 \
  --namespace label-studio

# Redis secret
kubectl create secret generic redis-secret \
  --from-literal=password=redis123 \
  --namespace label-studio

5. Customize Values

Copy the example values file and customize it:

cp values-example.yaml my-values.yaml

Edit my-values.yaml to match your environment:

# Update these values according to your setup
global:
  pgConfig:
    host: "postgresql.label-studio.svc.cluster.local"
    password:
      secretName: "postgresql-secret"
      secretKey: "password"
  
  redisConfig:
    host: "redis://redis-master.label-studio.svc.cluster.local:6379/1"
    password:
      secretName: "redis-secret"
      secretKey: "password"

ingress:
  enabled: true
  hosts:
    - host: label-studio.yourdomain.com  # Change this
      paths:
        - path: /
          pathType: ImplementationSpecific
  tls:
    - secretName: label-studio-tls
      hosts:
        - label-studio.yourdomain.com  # Change this

env:
  LABEL_STUDIO_HOST: "https://label-studio.yourdomain.com"  # Change this
  LABEL_STUDIO_USERNAME: "admin@yourdomain.com"  # Change this
  LABEL_STUDIO_PASSWORD: "your-secure-password"  # Change this

6. Deploy Label Studio

helm install label-studio . \
  --namespace label-studio \
  --values my-values.yaml

7. Verify Deployment

# Check pods
kubectl get pods -n label-studio

# Check services
kubectl get svc -n label-studio

# Check ingress
kubectl get ingress -n label-studio

# View logs
kubectl logs -f deployment/label-studio -n label-studio

Advanced Deployment Scenarios

Production Deployment with External Database

For production environments, use managed database services:

global:
  pgConfig:
    host: "your-rds-endpoint.amazonaws.com"
    port: 5432
    dbName: "labelstudio"
    userName: "labelstudio"
    password:
      secretName: "external-db-secret"
      secretKey: "password"
  
  redisConfig:
    host: "redis://your-elasticache-endpoint:6379/1"
    password:
      secretName: "external-redis-secret"
      secretKey: "password"

resources:
  limits:
    cpu: 4000m
    memory: 8Gi
  requests:
    cpu: 2000m
    memory: 4Gi

autoscaling:
  enabled: true
  minReplicas: 3
  maxReplicas: 20
  targetCPUUtilizationPercentage: 70

High Availability Setup

replicaCount: 3

affinity:
  podAntiAffinity:
    preferredDuringSchedulingIgnoredDuringExecution:
    - weight: 100
      podAffinityTerm:
        labelSelector:
          matchExpressions:
          - key: app.kubernetes.io/name
            operator: In
            values:
            - label-studio
        topologyKey: kubernetes.io/hostname

resources:
  limits:
    cpu: 2000m
    memory: 4Gi
  requests:
    cpu: 1000m
    memory: 2Gi

Storage Configuration

S3 Storage

global:
  persistence:
    enabled: true
    type: s3
    config:
      s3:
        bucket: "your-s3-bucket"
        region: "us-west-2"
        accessKey:
          secretName: "s3-credentials"
          secretKey: "access-key"
        secretKey:
          secretName: "s3-credentials"
          secretKey: "secret-key"

env:
  USE_S3: "true"
  S3_BUCKET: "your-s3-bucket"
  S3_REGION: "us-west-2"

Azure Blob Storage

global:
  persistence:
    enabled: true
    type: azure
    config:
      azure:
        accountName: "yourstorageaccount"
        containerName: "labelstudio"
        accountKey:
          secretName: "azure-storage-secret"
          secretKey: "account-key"

env:
  USE_AZURE: "true"
  AZURE_ACCOUNT_NAME: "yourstorageaccount"
  AZURE_CONTAINER: "labelstudio"

Monitoring and Observability

Enable Prometheus Metrics

env:
  PROMETHEUS_METRICS_ENABLED: "true"
  PROMETHEUS_METRICS_PORT: "9090"

service:
  annotations:
    prometheus.io/scrape: "true"
    prometheus.io/port: "9090"
    prometheus.io/path: "/metrics"

Logging Configuration

env:
  LOG_LEVEL: "INFO"
  LOG_FORMAT: "json"
  PYTHONUNBUFFERED: "1"

Troubleshooting

Common Issues

1. Pod not starting

   kubectl describe pod <pod-name> -n label-studio
   kubectl logs <pod-name> -n label-studio
   

2. Database connection issues

   # Test database connectivity
   kubectl run -it --rm debug --image=postgres:13 --restart=Never -- psql -h postgresql.label-studio.svc.cluster.local -U labelstudio -d labelstudio
   

3. Redis connection issues

   # Test Redis connectivity
   kubectl run -it --rm debug --image=redis:6 --restart=Never -- redis-cli -h redis-master.label-studio.svc.cluster.local -a redis123
   

4. Ingress not working

   kubectl describe ingress label-studio -n label-studio
   kubectl get events -n label-studio
   

Health Checks

# Check application health
kubectl exec -it deployment/label-studio -n label-studio -- curl http://localhost:8080/health

# Run Helm tests
helm test label-studio -n label-studio

Upgrading

Upgrade the Chart

# Update values if needed
helm upgrade label-studio . \
  --namespace label-studio \
  --values my-values.yaml

# Check upgrade status
helm status label-studio -n label-studio

Rollback

# List releases
helm history label-studio -n label-studio

# Rollback to previous version
helm rollback label-studio 1 -n label-studio

Uninstalling

# Uninstall Label Studio
helm uninstall label-studio -n label-studio

# Uninstall dependencies (if installed via Helm)
helm uninstall postgresql -n label-studio
helm uninstall redis -n label-studio

# Delete namespace
kubectl delete namespace label-studio

Security Considerations

1. Use strong passwords for database and Redis
2. Enable TLS for ingress
3. Use secrets for sensitive data
4. Configure RBAC appropriately
5. Enable pod security policies
6. Use non-root containers
7. Scan images for vulnerabilities

Performance Tuning

Resource Optimization

resources:
  limits:
    cpu: 2000m
    memory: 4Gi
  requests:
    cpu: 1000m
    memory: 2Gi

# For high-traffic environments
autoscaling:
  enabled: true
  minReplicas: 5
  maxReplicas: 50
  targetCPUUtilizationPercentage: 60
  targetMemoryUtilizationPercentage: 70

Database Optimization

env:
  DJANGO_DB_CONN_MAX_AGE: "600"
  DJANGO_DB_OPTIONS: '{"MAX_CONNS": 20}'

Support

For issues and questions:

• Check the Label Studio documentation
• Review the GitHub issues
• Join the Label Studio community

Contributing

To contribute to this Helm chart:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request