⎈
    Helm Designer
    Back to Home

    Documentation

    Learn how to design and manage Helm charts with Helm Designer.

    Getting Started

    Quick Start Guide

    1. Create a Template - Start by creating a new template from the dashboard. A template defines the structure of your Helm chart including registry settings, shared port, and optional features like Nginx Gateway or Redis.
    2. Add Services - Define your microservices with their routes, environment variables, health checks, and resource configurations.
    3. Configure Resources - Add ConfigMaps for configuration data and Secrets (TLS or Opaque) for sensitive information.
    4. Set Up Ingress - Define ingress rules to expose your services with TLS support.
    5. Create a Version - Generate a chart version with specific image tags and configuration values ready for deployment.

    Templates

    Understanding Templates

    Templates are the foundation of your Helm charts. Each template defines:

    Name & Description:Identify your template
    Shared Port:The common port all services expose (e.g., 8080)
    Registry Settings:Container registry URL and project path
    Registry Secret:Credentials for pulling images
    Feature Flags:Enable/disable Nginx Gateway and Redis

    Creating a Template

    1. Click "New Template" from the dashboard
    2. Fill in the basic information
    3. Configure your registry settings
    4. Enable optional features as needed
    5. Save and start adding resources

    Services

    Microservices Configuration

    Services represent your application's microservices. Each service includes:

    Basic Settings

    Name:DNS-safe name (used for image name and Kubernetes resources)
    Routes:URL paths the service handles (e.g., /api/v1, /health)
    Deploy as StatefulSet:Option to deploy as StatefulSet instead of Deployment

    Environment Variables

    Define environment variables that will be available in the container. Values are set when creating chart versions.

    Health Checks

    Liveness Path:Endpoint for liveness probes (e.g., /health)
    Readiness Path:Endpoint for readiness probes (e.g., /ready)

    Environment Sources

    ConfigMaps:Mount all keys from selected ConfigMaps as environment variables
    Secrets:Mount all keys from selected Opaque Secrets as environment variables

    Image Naming

    Images follow the pattern: {registryUrl}/{registryProject}/{serviceName}:{tag}

    ConfigMaps

    ConfigMap Management

    ConfigMaps store non-sensitive configuration data as key-value pairs.

    Use Cases

    • Application configuration files (config.yaml, settings.json)
    • Environment-specific settings
    • Feature flags

    Creating ConfigMaps

    1. Go to the ConfigMaps tab in your template
    2. Click "Add ConfigMap"
    3. Enter a name and add keys
    4. Values are assigned when creating chart versions

    Mounting to Services

    ConfigMaps can be mounted to services in two ways:

    As Environment Variables:All keys become environment variables
    As Volume Mounts:Keys become files in a mounted directory (configured in chart generation)

    Secrets

    Secret Management

    Helm Designer supports three types of secrets:

    Registry Secret

    Automatically created with your template. Contains credentials for pulling container images from your registry.

    TLS Secrets

    For HTTPS/TLS termination at ingress level:

    Name:Secret identifier
    Certificate (tls.crt):PEM-encoded certificate
    Private Key (tls.key):PEM-encoded private key

    Opaque Secrets

    For sensitive application data:

    Name:Secret identifier
    Keys:Define key names (e.g., DATABASE_PASSWORD, API_KEY)
    Values:Assigned when creating chart versions

    Mounting to Services

    Opaque Secrets can be mounted to services to inject sensitive data as environment variables.

    Ingresses

    Ingress Configuration

    Ingresses define how external traffic reaches your services.

    Routing Modes

    Via Nginx Gateway:Routes through the Nginx Gateway service (requires enableNginxGateway)
    Direct to Services:Routes directly to individual services

    TLS Configuration

    Enable HTTPS by:

    1. Creating a TLS Secret with certificate and key
    2. Enabling TLS on the ingress
    3. Selecting the TLS secret

    Routing Rules

    Define which paths route to which services:

    Use All Routes:Automatically include all routes from all services
    Manual Rules:Select specific service routes or enter custom paths

    Hosts

    Default host is specified at template level. Actual hosts are assigned when creating chart versions.

    Chart Versions

    Creating Chart Versions

    Chart versions are deployable releases of your template with specific values.

    Version Configuration

    Version Name:Semantic version (e.g., 1.0.0)
    App Version:Application version tag

    Values to Set

    When creating a version, you'll specify:

    Image Tags:Specific version tags for each service
    Environment Values:Actual values for service environment variables
    ConfigMap Values:Values for each ConfigMap key
    Secret Values:Values for TLS certificates and Opaque secret keys
    Ingress Hosts:Actual hostnames for each ingress

    Exporting Charts

    Once created, you can download the complete Helm chart as a ZIP file containing:

    • Chart.yaml
    • values.yaml
    • templates/ directory with all Kubernetes manifests

    Nginx Gateway

    Nginx Gateway Configuration

    When enabled, the Nginx Gateway provides a unified entry point for all services.

    Features

    Dynamic Configuration:nginx.conf is generated based on service routes
    Load Balancing:Distributes traffic across service replicas
    Path-Based Routing:Routes requests to appropriate backends

    Generated Configuration

    The Nginx Config tab shows the dynamically generated configuration including:

    • Upstream definitions for each service
    • Location blocks for each route
    • Proxy settings and timeouts

    Best Practices

    • Use consistent route prefixes per service
    • Enable health checks for all services
    • Configure appropriate timeouts for your workloads

    Service Accounts

    Service Accounts for Registry Access

    Service accounts enable external services and CI/CD pipelines to authenticate with your private Helm registry.

    What Are Service Accounts?

    Service accounts are machine credentials that allow automated systems to:

    • Pull Helm charts from your private registry
    • Access the chart index for specific templates
    • Download chart packages for deployment

    Creating a Service Account

    1. Navigate to Service Accounts in the sidebar
    2. Click "New Service Account"
    3. Enter a name and optional description
    4. Save to generate an API key

    Important: The API key is shown only once. Store it securely!

    Managing Template Access

    Each service account can access specific templates:

    • Click "Manage Access" on a service account
    • Select which templates the account can access
    • Only assigned templates will be available via the registry API

    API Key Format

    API keys are prefixed for identification:

    • Format: sa_xxxxxxxxxxxx
    • The prefix appears in logs for auditing
    • Keys are securely hashed before storage

    Deactivating Accounts

    Service accounts can be:

    Deactivated:Temporarily disable access without deleting
    Deleted:Permanently remove the account and revoke access

    Helm Registry

    Private Helm Registry

    Helm Designer includes a built-in private Helm registry that serves your chart templates.

    Registry URL Structure

    Your registry endpoints follow this pattern:

    Base URL: https://qhlmyvbnulhngkfqrpjv.supabase.co/functions/v1/helm-registry

    Available Endpoints

    Chart Index

    GET /{template-id}/index.yaml

    Returns the Helm repository index with all available versions.

    Chart Package

    GET /{template-id}/charts/{chart-name}-{version}.tgz

    Downloads the packaged Helm chart for a specific version.

    Authentication

    All registry endpoints require API key authentication:

    Authorization: Bearer sa_your_api_key_here

    Adding the Repository to Helm

    1. Create a service account and get the API key
    2. Grant access to the desired template
    3. Add the repository:
    helm repo add my-charts \
  https://qhlmyvbnulhngkfqrpjv.supabase.co/functions/v1/helm-registry/{template-id} \
  --username sa --password sa_your_api_key_here

    Installing Charts

    Once added, install charts normally:

    helm repo update
helm install my-release my-charts/{chart-name} --version 1.0.0

    CI/CD Integration

    For automated deployments:

    1. Store the API key as a CI/CD secret
    2. Use environment variables for authentication
    3. Include helm repo add in your pipeline

    Example GitHub Actions:

    - name: Add Helm Repo
  run: |
    helm repo add private-charts \
      ${{ secrets.HELM_REGISTRY_URL }} \
      --username sa \
      --password ${{ secrets.HELM_API_KEY }}

    Security Best Practices

    • Rotate API keys periodically
    • Use separate service accounts per environment
    • Grant minimal template access (principle of least privilege)
    • Monitor access logs for suspicious activity