Part 4: Chart Dependencies and Repositories

Series Navigation: ← Part 3: Advanced Templates and Values | Back to Series Overview | Part 5: Production Best Practices →

Introduction

In the previous parts, we built self-contained Charts. But real-world applications rarely run in isolation. Your TypeScript API likely needs Redis for caching, PostgreSQL for data, or other supporting services. That's where Chart dependencies come in.

In this article, I'll share how I manage dependencies, work with Chart repositories, and build reusable Charts. These patterns have helped me maintain consistency across dozens of microservices.

Understanding Chart Dependencies

Chart dependencies allow your Chart to install and configure other Charts automatically. Instead of manually installing Redis and your API separately, you define Redis as a dependency, and Helm handles both.

Why Use Dependencies?

From my experience deploying TypeScript applications:

Consistency: Same Redis configuration across all environments
Simplicity: One helm install deploys complete stack
Version Control: Lock dependency versions for reproducibility
Configuration Management: Override dependency values from parent chart
Testing: Deploy complete application stack in CI/CD

Defining Dependencies

Dependencies are defined in Chart.yaml.

Basic Dependency Declaration

Chart.yaml:

apiVersion: v2
name: typescript-api
description: TypeScript API with dependencies
type: application
version: 0.2.0
appVersion: "1.0.0"

dependencies:
  - name: redis
    version: 18.6.1
    repository: https://charts.bitnami.com/bitnami
    condition: redis.enabled
  
  - name: postgresql
    version: 13.2.24
    repository: https://charts.bitnami.com/bitnami
    condition: postgresql.enabled
  
  - name: common
    version: 2.x.x
    repository: https://charts.bitnami.com/bitnami
    tags:
      - library

Dependency Fields

name: Chart name (must match chart name in repository)
version: Chart version (supports ranges: 1.2.3, ~1.2.3, ^1.2.3, 1.x.x)
repository: Repository URL or alias
condition: Enable/disable dependency via values
tags: Categorize dependencies for bulk enable/disable
alias: Use different name for dependency (for multiple instances)
import-values: Import values from dependency

Managing Dependencies

Download Dependencies

# Download dependencies to charts/ directory
helm dependency update ./typescript-api

# Or shorter version
helm dep up ./typescript-api

# List dependencies
helm dependency list ./typescript-api

This creates:

charts/ directory with downloaded chart archives
Chart.lock file tracking exact versions

Chart.lock File

After running helm dependency update, Helm creates Chart.lock:

dependencies:
- name: redis
  repository: https://charts.bitnami.com/bitnami
  version: 18.6.1
- name: postgresql
  repository: https://charts.bitnami.com/bitnami
  version: 13.2.24
digest: sha256:abc123...
generated: "2026-02-05T10:30:00Z"

Best practices:

✅ Commit Chart.lock to version control
✅ Run helm dep update after changing Chart.yaml
✅ Use specific versions in production
❌ Don't commit charts/ directory (add to .helmignore)

Configuring Dependencies

Configure dependency values in your parent values.yaml.

Parent values.yaml

values.yaml:

# Enable/disable dependencies
redis:
  enabled: true
  architecture: standalone
  auth:
    enabled: true
    password: ""  # Will be auto-generated if empty
  master:
    persistence:
      enabled: true
      size: 8Gi
    resources:
      limits:
        cpu: 100m
        memory: 128Mi
      requests:
        cpu: 50m
        memory: 64Mi

postgresql:
  enabled: true
  auth:
    username: apiuser
    password: ""  # Will be auto-generated if empty
    database: apidb
  primary:
    persistence:
      enabled: true
      size: 10Gi
    resources:
      limits:
        cpu: 200m
        memory: 256Mi
      requests:
        cpu: 100m
        memory: 128Mi

# Your application config
replicaCount: 2

image:
  repository: your-registry/typescript-api
  tag: "1.0.0"

env:
  - name: NODE_ENV
    value: "production"
  
  # Redis connection (reference dependency)
  - name: REDIS_HOST
    value: "{{ .Release.Name }}-redis-master"
  - name: REDIS_PORT
    value: "6379"
  
  # PostgreSQL connection (reference dependency)
  - name: DB_HOST
    value: "{{ .Release.Name }}-postgresql"
  - name: DB_PORT
    value: "5432"
  - name: DB_NAME
    value: "apidb"
  - name: DB_USER
    value: "apiuser"

# Database password from secret
envFrom:
  - secretRef:
      name: "{{ .Release.Name }}-postgresql"

Using Dependency Values in Templates

templates/deployment.yaml:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{ include "typescript-api.fullname" . }}
spec:
  template:
    spec:
      containers:
      - name: {{ .Chart.Name }}
        env:
        {{- if .Values.redis.enabled }}
        - name: REDIS_HOST
          value: {{ .Release.Name }}-redis-master
        - name: REDIS_PORT
          value: "6379"
        {{- if .Values.redis.auth.enabled }}
        - name: REDIS_PASSWORD
          valueFrom:
            secretKeyRef:
              name: {{ .Release.Name }}-redis
              key: redis-password
        {{- end }}
        {{- end }}
        
        {{- if .Values.postgresql.enabled }}
        - name: DB_HOST
          value: {{ .Release.Name }}-postgresql
        - name: DB_PORT
          value: "5432"
        - name: DB_NAME
          value: {{ .Values.postgresql.auth.database }}
        - name: DB_USER
          value: {{ .Values.postgresql.auth.username }}
        - name: DB_PASSWORD
          valueFrom:
            secretKeyRef:
              name: {{ .Release.Name }}-postgresql
              key: password
        {{- end }}

Dependency Conditions and Tags

Conditional Dependencies

Enable/disable individual dependencies:

Chart.yaml:

dependencies:
  - name: redis
    version: 18.6.1
    repository: https://charts.bitnami.com/bitnami
    condition: redis.enabled
  
  - name: postgresql
    version: 13.2.24
    repository: https://charts.bitnami.com/bitnami
    condition: postgresql.enabled

Install with conditions:

# Install with Redis only
helm install my-api ./typescript-api --set redis.enabled=true --set postgresql.enabled=false

# Install with PostgreSQL only
helm install my-api ./typescript-api --set redis.enabled=false --set postgresql.enabled=true

# Install with both (default)
helm install my-api ./typescript-api

Tags for Bulk Control

Group dependencies with tags:

Chart.yaml:

dependencies:
  - name: redis
    version: 18.6.1
    repository: https://charts.bitnami.com/bitnami
    tags:
      - cache
  
  - name: memcached
    version: 6.7.0
    repository: https://charts.bitnami.com/bitnami
    tags:
      - cache
  
  - name: postgresql
    version: 13.2.24
    repository: https://charts.bitnami.com/bitnami
    tags:
      - database
  
  - name: mongodb
    version: 14.8.3
    repository: https://charts.bitnami.com/bitnami
    tags:
      - database

values.yaml:

tags:
  cache: true
  database: true

Install with tag control:

# Install only cache dependencies
helm install my-api ./typescript-api --set tags.cache=true --set tags.database=false

# Install only database dependencies
helm install my-api ./typescript-api --set tags.cache=false --set tags.database=true

Multiple Instances with Aliases

Use aliases to include the same chart multiple times:

Chart.yaml:

dependencies:
  - name: redis
    version: 18.6.1
    repository: https://charts.bitnami.com/bitnami
    alias: redis-cache
    condition: redisCache.enabled
  
  - name: redis
    version: 18.6.1
    repository: https://charts.bitnami.com/bitnami
    alias: redis-session
    condition: redisSession.enabled

values.yaml:

redisCache:
  enabled: true
  master:
    persistence:
      enabled: false
    resources:
      limits:
        cpu: 100m
        memory: 128Mi

redisSession:
  enabled: true
  master:
    persistence:
      enabled: true
      size: 5Gi
    resources:
      limits:
        cpu: 50m
        memory: 64Mi

Importing Values from Dependencies

Share values between parent and child charts:

Child chart values.yaml (dependency):

exports:
  redis:
    host: "{{ .Release.Name }}-redis-master"
    port: 6379

Parent Chart.yaml:

dependencies:
  - name: redis
    version: 18.6.1
    repository: https://charts.bitnami.com/bitnami
    import-values:
      - child: exports.redis
        parent: redisConnection

Parent template usage:

env:
  - name: REDIS_HOST
    value: {{ .Values.redisConnection.host }}
  - name: REDIS_PORT
    value: {{ .Values.redisConnection.port | quote }}

Chart Repositories

Chart repositories host and distribute Helm Charts.

Repository Types

HTTP/HTTPS Repositories: Traditional index-based repos
OCI Registries: Store charts as OCI artifacts (Docker-style)
Git Repositories: Charts stored in Git repos
Artifact Hub: Central discovery portal

Adding Repositories

# Add official Bitnami repository
helm repo add bitnami https://charts.bitnami.com/bitnami

# Add custom repository
helm repo add my-charts https://charts.example.com

# Update repository index
helm repo update

# List repositories
helm repo list

# Remove repository
helm repo remove bitnami

# Search repository
helm search repo redis

# Search Artifact Hub
helm search hub nginx

Using Repository Aliases

In Chart.yaml, use repository aliases:

dependencies:
  - name: redis
    version: 18.6.1
    repository: "@bitnami"  # Uses bitnami repo alias

Creating Your Own Chart Repository

I maintain private repositories for internal Charts.

HTTP Repository

1. Package your charts:

# Package chart
helm package ./typescript-api

# Output: typescript-api-0.2.0.tgz

2. Create repository index:

# Create index.yaml
helm repo index . --url https://charts.example.com

# This creates index.yaml listing all .tgz files

3. Host files:

# Upload to web server or cloud storage
# - index.yaml
# - typescript-api-0.2.0.tgz
# - other-chart-1.0.0.tgz

4. Use repository:

helm repo add my-charts https://charts.example.com
helm repo update
helm search repo my-charts

GitHub Pages Repository

I use GitHub Pages for public Charts:

1. Create repository structure:

my-helm-charts/
├── charts/
│   └── typescript-api/
└── docs/
    ├── index.yaml
    └── typescript-api-0.2.0.tgz

2. Package and index:

# Package chart
helm package charts/typescript-api -d docs/

# Generate index
helm repo index docs/ --url https://username.github.io/my-helm-charts/

3. Enable GitHub Pages pointing to /docs directory

4. Use repository:

helm repo add my-charts https://username.github.io/my-helm-charts/

OCI Registry (Recommended)

Modern approach using container registries:

1. Package chart:

helm package ./typescript-api

2. Login to registry:

# Docker Hub
helm registry login registry-1.docker.io -u username

# GitHub Container Registry
echo $GITHUB_TOKEN | helm registry login ghcr.io -u username --password-stdin

# Azure Container Registry
helm registry login myregistry.azurecr.io -u username

3. Push chart:

# Push to OCI registry
helm push typescript-api-0.2.0.tgz oci://registry-1.docker.io/username

# Or GitHub
helm push typescript-api-0.2.0.tgz oci://ghcr.io/username/charts

4. Install from OCI registry:

# No need to add repository
helm install my-api oci://registry-1.docker.io/username/typescript-api --version 0.2.0

# Or use in dependencies

Chart.yaml with OCI:

dependencies:
  - name: typescript-api
    version: 0.2.0
    repository: oci://ghcr.io/username/charts

Chart Versioning Strategy

Versioning is critical for production deployments.

Semantic Versioning

I follow SemVer for Chart versions:

MAJOR: Incompatible changes (breaking)
MINOR: Backwards-compatible features
PATCH: Backwards-compatible fixes

Chart.yaml:

# Chart version
version: 1.2.3

# Application version (separate)
appVersion: "2.5.1"

Version Ranges in Dependencies

dependencies:
  # Exact version
  - name: redis
    version: 18.6.1
    repository: "@bitnami"
  
  # Patch updates allowed (~)
  - name: postgresql
    version: ~13.2.24  # Allows 13.2.25, 13.2.26, but not 13.3.0
    repository: "@bitnami"
  
  # Minor updates allowed (^)
  - name: mongodb
    version: ^14.8.3  # Allows 14.9.0, but not 15.0.0
    repository: "@bitnami"
  
  # Wildcard
  - name: common
    version: 2.x.x  # Any 2.x.x version
    repository: "@bitnami"

Versioning Workflow

My workflow for versioning:

# 1. Make changes to chart
vim charts/typescript-api/templates/deployment.yaml

# 2. Update Chart version
vim charts/typescript-api/Chart.yaml
# Increment version: 0.1.0 -> 0.2.0

# 3. Update dependencies if needed
helm dependency update charts/typescript-api

# 4. Test chart
helm lint charts/typescript-api
helm template test charts/typescript-api --debug

# 5. Package
helm package charts/typescript-api

# 6. Push to repository
helm push typescript-api-0.2.0.tgz oci://ghcr.io/username/charts

# 7. Tag in Git
git tag -a typescript-api-0.2.0 -m "Release typescript-api v0.2.0"
git push origin typescript-api-0.2.0

Practical Example: Complete Stack

Here's a complete Chart for a TypeScript API with all dependencies:

Chart.yaml:

apiVersion: v2
name: typescript-api-stack
description: Complete TypeScript API stack with dependencies
type: application
version: 1.0.0
appVersion: "1.0.0"

keywords:
  - typescript
  - api
  - nodejs

dependencies:
  # Cache layer
  - name: redis
    version: ~18.6.0
    repository: https://charts.bitnami.com/bitnami
    condition: redis.enabled
    tags:
      - cache
  
  # Primary database
  - name: postgresql
    version: ~13.2.0
    repository: https://charts.bitnami.com/bitnami
    condition: postgresql.enabled
    tags:
      - database
  
  # Monitoring
  - name: prometheus
    version: ~25.8.0
    repository: https://prometheus-community.github.io/helm-charts
    condition: prometheus.enabled
    tags:
      - monitoring
  
  # Common library
  - name: common
    version: 2.x.x
    repository: https://charts.bitnami.com/bitnami

values.yaml:

# Enable/disable components
redis:
  enabled: true
  architecture: standalone
  auth:
    enabled: true
  master:
    persistence:
      enabled: true
      size: 5Gi
    resources:
      limits:
        cpu: 100m
        memory: 128Mi

postgresql:
  enabled: true
  auth:
    username: apiuser
    database: apidb
  primary:
    persistence:
      enabled: true
      size: 10Gi
    resources:
      limits:
        cpu: 250m
        memory: 256Mi

prometheus:
  enabled: false  # Optional for production

# Application settings
replicaCount: 3

image:
  repository: ghcr.io/username/typescript-api
  tag: "1.0.0"

service:
  type: ClusterIP
  port: 80

resources:
  limits:
    cpu: 500m
    memory: 512Mi
  requests:
    cpu: 200m
    memory: 256Mi

autoscaling:
  enabled: true
  minReplicas: 3
  maxReplicas: 10

# Feature flags
features:
  caching: true
  metrics: true
  tracing: false

Install complete stack:

# Update dependencies
helm dependency update ./typescript-api-stack

# Install with all dependencies
helm install prod-api ./typescript-api-stack \
  --namespace production \
  --create-namespace \
  -f values-production.yaml

# Install without optional monitoring
helm install prod-api ./typescript-api-stack \
  --set prometheus.enabled=false

Managing Subcharts

Subcharts in charts/ directory are managed automatically.

Local Subcharts

Create local subcharts for shared components:

# Create subchart
mkdir -p charts/common-config
helm create charts/common-config

Parent Chart.yaml:

dependencies:
  - name: common-config
    version: 0.1.0
    repository: file://./charts/common-config

Local subcharts don't need helm dep update.

Best Practices

From my experience managing Charts:

Pin Dependency Versions: Use exact versions in production
Commit Chart.lock: Ensures reproducible builds
Use Conditions: Allow flexible dependency management
OCI Registries: Modern, efficient chart distribution
Version Semantically: Clear versioning prevents confusion
Document Dependencies: README should list required dependencies
Test Combinations: Verify charts work with/without dependencies
Namespace Isolation: Test dependencies don't conflict
Resource Limits: Always set limits for dependencies
Security Scanning: Scan dependencies for vulnerabilities

What's Next?

We've covered dependencies and repositories comprehensively. In the final part (Part 5), we'll explore production-ready patterns:

Secrets management and encryption
Security best practices
Rollback strategies
CI/CD integration
Chart testing and validation
Performance optimization
Troubleshooting production issues

Series Navigation: ← Part 3: Advanced Templates and Values | Back to Series Overview | Part 5: Production Best Practices →

Key Takeaways

✅ Dependencies automate installation of supporting services
✅ Chart.lock ensures reproducible deployments
✅ Conditions and tags provide flexible dependency management
✅ OCI registries are the modern approach for chart distribution
✅ Semantic versioning clarifies compatibility
✅ Repository management enables sharing charts across teams
✅ Aliases allow multiple instances of same chart
✅ Always pin versions in production environments

PreviousPart 3: Advanced Templates and Values NextPart 5: Production Best Practices and Security

Last updated 12 days ago

hashtagIntroduction

hashtagUnderstanding Chart Dependencies

hashtagWhy Use Dependencies?

hashtagDefining Dependencies

hashtagBasic Dependency Declaration

hashtagDependency Fields

hashtagManaging Dependencies

hashtagDownload Dependencies

hashtagChart.lock File

hashtagConfiguring Dependencies

hashtagParent values.yaml

hashtagUsing Dependency Values in Templates

hashtagDependency Conditions and Tags

hashtagConditional Dependencies

hashtagTags for Bulk Control

hashtagMultiple Instances with Aliases

hashtagImporting Values from Dependencies

hashtagChart Repositories

hashtagRepository Types

hashtagAdding Repositories

hashtagUsing Repository Aliases

hashtagCreating Your Own Chart Repository

hashtagHTTP Repository

hashtagGitHub Pages Repository

hashtagOCI Registry (Recommended)

hashtagChart Versioning Strategy

hashtagSemantic Versioning

hashtagVersion Ranges in Dependencies

hashtagVersioning Workflow

hashtagPractical Example: Complete Stack

hashtagManaging Subcharts

hashtagLocal Subcharts

hashtagBest Practices

hashtagWhat's Next?

hashtagKey Takeaways

Introduction

Understanding Chart Dependencies

Why Use Dependencies?

Defining Dependencies

Basic Dependency Declaration

Dependency Fields

Managing Dependencies

Download Dependencies

Chart.lock File

Configuring Dependencies

Parent values.yaml

Using Dependency Values in Templates

Dependency Conditions and Tags

Conditional Dependencies

Tags for Bulk Control

Multiple Instances with Aliases

Importing Values from Dependencies

Chart Repositories

Repository Types

Adding Repositories

Using Repository Aliases

Creating Your Own Chart Repository

HTTP Repository

GitHub Pages Repository

OCI Registry (Recommended)

Chart Versioning Strategy

Semantic Versioning

Version Ranges in Dependencies

Versioning Workflow

Practical Example: Complete Stack

Managing Subcharts

Local Subcharts

Best Practices

What's Next?

Key Takeaways