Native Helm deployment

Deploy Services with Helm directly in Kubernetes without an external CI/CD deployment pipeline.

Native Helm deploys a Helm release without an external CI/CD deployment pipeline. Lifecycle runs the deployment in the Environment namespace and shows its logs with the Service.

Before you start

Make sure that these conditions are true:

Your Lifecycle deployment supports native Helm.
The Lifecycle deployment can pull the necessary Helm runner image.
The chart and its value files are available to Lifecycle.
The chart can operate with namespace-scoped permissions.

An operator can make native Helm the installation default. An explicit helm.deploymentMethod value for a Service takes precedence over that default.

⚠️

A chart can create or change Kubernetes resources. Examine the chart, its dependencies, and its values before deployment.

Deploy a public chart

This example deploys a public PostgreSQL chart:

The two version fields have different purposes:

helm.version selects the Helm version for the deployment Job.
helm.chart.version selects the chart version.

Pin both versions. Before an upgrade, read the chart release notes and test the upgrade with non-sensitive data.

Deploy a chart from a repository

Set the repository and branch for a chart that is in source control:

Use paths relative to the checked-out repository. If the chart path or value file is missing, the deployment fails before Helm can apply the release.

Configuration reference

These Service fields control a native Helm deployment:

Field	Purpose
`helm.deploymentMethod`	Select `native` or `ci` deployment
`helm.version`	Select the Helm version
`helm.args`	Add Helm arguments for this Service
`helm.repository`	Select the chart source repository
`helm.branchName`	Select the chart source branch
`helm.chart.name`	Set a chart name or relative chart path
`helm.chart.repoUrl`	Set the repository URL for a public chart
`helm.chart.version`	Select the chart version
`helm.chart.values`	Add `key=value` settings
`helm.chart.valueFiles`	Add value files from the checked-out repository
`helm.nativeHelm.image`	Override the Helm runner image
`helm.nativeHelm.postRenderer`	Configure a post-renderer for this Service
`helm.nativeHelm.defaultArgs`	Set fallback Helm arguments for this Service
`helm.nativeHelm.defaultHelmVersion`	Set a fallback Helm version for this Service

Service configuration overrides matching installation defaults. If an operator manages a field centrally, get the approved value before you override it.

⚠️

Do not put a root-level helm block in lifecycle.yaml. Put Helm configuration under each applicable services[] entry.

Pass application environment values

For a local chart with helm.docker, helm.envMapping maps Service environment values into chart values. Select the format that the chart expects.

Array format

Use array for a chart that expects Kubernetes name and value entries:

Lifecycle adds entries under deployment.env for API_MODE and DATABASE_HOST.

Map format

Use map for a chart that expects a key-value object:

In map format, Lifecycle changes each underscore in a variable name to two underscores. For example, API_MODE becomes API__MODE.

envMapping applies only to a local chart that has helm.docker configuration. It does not change values for a public chart.

Use secret-backed chart values

Native Helm supports a cloud secret reference as the complete value after =. Lifecycle gives the secret value to Helm through a file.

Partial secret interpolation is not supported. Put a complete composite value in the secret provider and reference that value directly.

⚠️

Do not use --debug or --dry-run with secret-backed chart values. Lifecycle rejects this combination because Helm can print rendered values.

See Cloud secrets for provider syntax and failure behavior.

Use a custom runner or post-renderer

An approved runner image can contain a required plugin or post-renderer:

The runner image must contain Helm and the configured executable. The post-renderer must not depend on a repository file that the Job cannot access.

To disable an inherited post-renderer for one Service, set helm.nativeHelm.postRenderer.enabled to false.

Migrate a Service to native Helm

For a Service that currently uses github, complete these changes:

Replace the github block with a helm block.
Move repository and branchName into the helm block.
Set deploymentMethod to native.
Set the Helm version.
Add the chart name, version, values, and value files.
If Lifecycle builds an image, keep the docker block under helm.
If the local chart needs Service environment values, add envMapping.
Validate lifecycle.yaml.
Deploy the change in a test Environment.

Check the generated release, Service URL, readiness, and deployment logs. Do not remove the previous deployment path until the native Helm test succeeds.

Troubleshooting

Lifecycle does not use native Helm: Check helm.deploymentMethod. Then, ask the operator whether the release supports native Helm.
The Helm version is missing: Set helm.version. If the operator supplies a custom runner, use the approved runner configuration.
A local chart or value file is missing: Check repository, branchName, and each relative path.
Environment values are absent: Make sure that the chart is local and has helm.docker. Check the envMapping format and path.
Helm reports another operation in progress: Examine the current Deploy logs. If an earlier Job is stuck, give its Environment and Service names to the operator.
A secret-backed value fails: Check the provider, path, key, and complete value syntax. Remove --debug and --dry-run.

Service Dependencies Cloud secrets