Native Helm Deployment

Native Helm is an alternative deployment method that runs Helm deployments directly within Kubernetes jobs, eliminating the need for external CI/CD systems. This provides a more self-contained and portable deployment solution.

Overview

When enabled, Native Helm:

• Creates Kubernetes jobs to execute Helm deployments
• Runs in ephemeral namespaces with proper RBAC
• Provides real-time deployment logs via WebSocket
• Handles concurrent deployments automatically
• Supports all standard Helm chart types

Quickstart

Want to try native Helm deployment? Here’s the fastest way to get started:

This configuration:

1. Enables native Helm for the my-api service
2. Uses a local Helm chart from your repository
3. Applies values from ./helm/values.yaml
4. Runs deployment as a Kubernetes job

Configuration

Enabling Native Helm

There are two ways to enable native Helm deployment:

Per Service Configuration

Enable native Helm for individual services:

Global Configuration

Enable native Helm for all services:

Configuration Precedence

Lifecycle uses a hierarchical configuration system with three levels of precedence:

1. helmDefaults - Base defaults for all deployments (database: global_config table)
2. Chart-specific config - Per-chart defaults (database: global_config table)
3. Service YAML config - Service-specific overrides (highest priority)

Global Configuration (Database)

Global configurations are stored in the global_config table in the database. Each configuration is stored as a row with:

• key: The configuration name (e.g., ‘helmDefaults’, ‘postgresql’, ‘redis’)
• config: JSON object containing the configuration

helmDefaults Configuration

Stored in database with key helmDefaults:

Field Descriptions:

• enabled: Enables default native Helm behavior in global config. Services still typically opt in with deploymentMethod: "native" or service-level native Helm settings.
• defaultArgs: Arguments automatically appended to every Helm command (appears before service-specific args)
• defaultHelmVersion: The Helm version to use when not specified at the service or chart level
• image: Custom runner image for the native Helm job
• postRenderer.enabled: Enables or disables the configured Helm post-renderer
• postRenderer.command: Executable passed to Helm with --post-renderer
• postRenderer.args: Arguments passed to Helm as repeated --post-renderer-args flags

Chart-specific Configuration

Example: PostgreSQL configuration stored with key postgresql:

Custom Runner Images and Post-Renderers

Native Helm supports two related customization points:

• nativeHelm.image changes the container image used for the Helm job
• nativeHelm.postRenderer configures Helm’s --post-renderer integration

This keeps the model aligned with Helm itself: Lifecycle configures the runner image and optionally tells Helm which post-renderer executable to invoke.

Global Defaults Only

Services can then opt into native Helm without repeating the runner image:

Global Custom Image with Post-Renderer

Service-Level Override

Service config can override either the image or the post-renderer settings:

Disable an Inherited Post-Renderer

If a post-renderer is defined globally, a service can explicitly disable it:

Usage Examples

Quick Experiment: Deploy Jenkins!

Want to see native Helm in action? Let’s deploy everyone’s favorite CI/CD tool - Jenkins! This example shows how easy it is to deploy popular applications using native Helm.

To access your Jenkins instance:

1. Check the deployment status in your PR comment
2. Click the Deploy Logs link to monitor the deployment
3. Once deployed, Jenkins will be available at the internal hostname

Basic Service Deployment

PostgreSQL with Overrides

Custom Environment Variables

Lifecycle supports flexible environment variable formatting through the envMapping configuration. This feature allows you to control how environment variables from your service configuration are passed to your Helm chart.

Default envMapping Configuration

You can define default envMapping configurations in the global_config database table. These defaults apply to all services using that chart unless overridden at the service level.

Example: Setting defaults for your organization’s chart

With this configuration, any service using the myorg-web-app chart will automatically use array format for environment variables:

Array Format

Best for charts that expect Kubernetes-style env arrays.

This produces the following Helm values:

Your chart’s values.yaml would use it like:

Map Format

Best for charts that expect a simple key-value object.

This produces the following Helm values:

Your chart’s values.yaml would use it like:

Complete Example with Multiple Services

Chart Types

Lifecycle automatically detects and handles three chart types:

Troubleshooting

Deployment Fails with “Another Operation in Progress”

Symptom: Helm reports an existing operation is blocking deployment

Solution: Native Helm automatically handles this by killing existing jobs. If the issue persists:

Environment Variables Not Working

Symptom: Environment variables not passed to the deployment

Common Issues:

1. envMapping placed under chart instead of directly under helm
2. Incorrect format specification (array vs map)
3. Missing path configuration

Correct Configuration:

Migration Example

Here’s a complete example showing how to migrate from GitHub-type services to Helm-type services:

Before: GitHub-type Services

After: Helm-type Services with Native Deployment

Key Migration Points

1. Service Type Change: Changed from github: to helm: configuration
2. Repository Location: repository and branchName move from under github: to directly under helm:
3. Deployment Method: Added deploymentMethod: "native" to enable native Helm
4. Chart Configuration: Added chart: section with local or public charts
5. Environment Mapping: Added envMapping: to control how environment variables are passed
6. Helm Arguments: Added args: for Helm command customization
7. Docker Configuration: Kept existing docker: config for build process