Choosing the Right Helm Resource

The Pulumi Kubernetes provider has supported deploying Helm charts since 2018 through the Chart resource, which installs charts by rendering their templates and applying them to the target cluster directly.

The Release resource adds another option to the mix. It uses an embedded version of the Helm SDK to natively manage Helm releases on the cluster. Both resources are generally available, and existing users of either can keep using it. If you’re deploying Helm charts through Pulumi for a new use case, though, this guide will help you choose the best option.

Helm Chart resource#

The Chart resource renders the templates from your chart and then manages the objects directly with the Pulumi Kubernetes provider. Chart is implemented as a component resource, which provides a number of benefits for Pulumi users.

Benefits#

1. Visibility into all resources encapsulated by the chart in Pulumi’s state, allowing you to directly query properties of individual resources.
2. Tight integration with Pulumi’s Policy-as-Code framework, CrossGuard, to enforce policies on all resources installed by Helm charts.
3. The ability to leverage transformations to programmatically manipulate resources installed by Helm charts in any of the Pulumi-supported programming languages.
4. Detailed previews and diffs rendered in the Pulumi CLI and Console for each Kubernetes resource resulting from Helm chart config changes.

Because these resources are not directly managed by Helm, however, the following limitations apply.

Limitations#

1. No support for Helm chart hooks — this is the equivalent of running helm install with the --no-hooks option.
2. No ability to import existing Helm releases into Pulumi state.
3. No interoperability using the Helm CLI on resources installed by Pulumi.

Helm Release resource#

The Pulumi Kubernetes provider uses an embedded version of the Helm SDK to natively manage Helm releases on the target cluster. This addresses most of the limitations of the Chart resource.

Benefits#

1. Because it uses Helm’s native support for installing charts, all the major features of Helm charts, such as hooks, are readily supported.
2. Existing Helm releases installed via the Helm CLI can be imported into Pulumi state.
3. Releases installed via Pulumi are serialized by the chosen Helm driver in the cluster and can be queried by the Helm CLI.

It does have a few limitations, though.

Limitations#

1. Support for transformations is limited to what the Helm CLI offers (running helm install with --post-renderer postrenderer).
2. Because Pulumi is not directly managing the underlying Kubernetes resources installed by Helm, CrossGuard policies can’t be enforced on those resources.
3. Fine-grained preview support is limited, since the Helm client is responsible for managing the underlying Kubernetes resources.

Which Helm resource is right for my use case?#

You have the flexibility to choose between the Chart and Release resources for your use case. Both can be used within the same Pulumi program, and because they’re both offered by the Kubernetes provider, neither requires additional configuration to authenticate against the target cluster.

This section provides a simple framework for deciding between the two. If your usage falls outside of this, or there are more subtle tradeoffs, reach out for advice on Community Slack or by filing an issue on GitHub.

Recommendations by use case#

Fire-and-forget Helm chart installation#

In many cases, you simply want to install an unmodified chart and manage its configuration in your IaC tool of choice by specifying the chart and its values in code. For this, we recommend the Release resource, due to its broader support for Helm features such as hooks.

Interoperability with existing Helm releases#

If you have existing Helm releases deployed through the Helm CLI and want to integrate them into Pulumi, the Release resource is your best choice. Component resources like Chart don’t currently offer the ability to import existing resources.

Fine-grained diffs and transformations#

Chart resources have direct access to the Kubernetes resources installed by the chart before installation. As a result, they support transformations, which let you programmatically manipulate resources before Pulumi installs them. This is a powerful tool that has enabled several advanced use cases. Chart can also apply a post-renderer command to customize the manifests.

The Release resource does not have the same flexibility for transformations, aside from applying a post-renderer.

Similarly, Chart resources can enumerate underlying resources and their inputs, providing fine-grained diffs and richer previews. If these matter for your use case, the Chart resource is preferred.

Resource ordering and readiness#

The order in which Kubernetes resources are applied by Pulumi is based on the dependency links between the resources. The Chart resource automatically creates some dependency links, based on this specification. It also supports the config.kubernetes.io/depends-on annotation, which you can apply via a transformation or a post-renderer to force one object to be installed before another.

When Pulumi creates a resource, it waits for the resource to be ready before proceeding to create any dependents. You can skip waiting for readiness on all chart resources with the skipAwait option, or on a specific resource by using the pulumi.com/skipAwait annotation.

Enforcing CrossGuard policies on Kubernetes resources#

Chart resources extract all Kubernetes objects and deploy them as Pulumi resources, allowing fine-grained policy enforcement with CrossGuard. Because Pulumi does not manage the underlying resources from the Release resource, choose Chart if you need to enforce policy on those resources.

Next steps#

Once you’ve decided which resource fits your use case, follow the matching hands-on tutorial to deploy a chart:

• Install Helm Charts using the Release resource — step-by-step with the Release resource.
• Install Helm Charts using the Chart resource — step-by-step with the Chart resource.

To go deeper, explore the API reference docs for the Chart and Release resources, or learn more in the Kubernetes documentation.