Choosing the Right Helm Resource For Your Use Case

The Kubernetes provider and SDK has supported a means to deploy Helm Charts since 2018 through the Helm Chart resource. This resource installs Helm charts by rendering the templates using the helm template command, and then installing them on the target Kubernetes environment directly.

In September 2021 we announced the public preview of a new Helm Release which adds an additional option to the mix for Pulumi’s Kubernetes users. As of v3.15.0 of the Pulumi Kubernetes SDK and Provider, this resource is now Generally Available.

Existing users of the Helm Chart can continue to use that resource. However, if you are deploying Helm Charts through Pulumi for new use cases, you have a new option to consider. This guide should help you choose the best option for your use case.

Helm Chart Resource

The Helm 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 provide a number of benefits for Pulumi users:

Benefits

1. Visibility into all resources encapsulated by the Chart in Pulumi’s state, allowing users 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. 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

We have seen significant adoption of Chart over the years. However, since these resources are not directly managed by Helm, the following limitations apply:

Limitations

1. No support for Helm Chart Hooks - i.e. 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 Kubernetes cluster. This addresses most of the limitations of the Chart resource:

Benefits

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

However, it has a few limitations:

Limitations

1. The ability to support transformations is limited to that offered by the Helm CLI (running helm install with --post-renderer postrenderer)
2. Since Pulumi is not directly managing the underlying Kubernetes resource installed by Helm, CrossGuard policies can’t be enforced on these resources.
3. Fine-grained preview support is limited, since the Helm client is responsible for managing the underlying Kubernetes resources.

What Helm Resource is Right For My Use Case?

Pulumi users have the flexibility to choose between the Chart and Release resource for their use case. It is important to note that both resources can be used within the same Pulumi program and since they are both offered by the Kubernetes provider, require no additional configuration to authenticate against the target cluster.

This section provides a simple framework for users to decide between the two classes of resources. If your usage falls outside of this or there are more subtle tradeoffs, please reach out for advice on on Community Slack or filing an issue on Github.

Recommendations by Use Case

Fire-and-forget Helm Chart Installation

In many cases, users simply want to install an unmodified Chart and manage its configuration in their IaC tool of choice by specifying the chart and the values in code. In this case, we recommend using Helm Release due to the broader support of Helm features such as hooks.

Interoperability with existing Helm releases

If you have existing Helm Releases deployed through a version of the Helm CLI and wish to now integrate them in Pulumi, the Helm Release resource is your best choice. Currently, ComponentResources like Chart don’t 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, Chart resources support transformations which allow program authors to programmatically manipulate resources before they are installed by Pulumi. This is a very powerful tool which has enabled several advanced use cases for our users. Chart is also able to apply a post-renderer command to customize the manifests.

Helm Release does not have the same flexibility in offering transformations support, aside from applying a post-renderer.

Similarly, Chart resources can enumerate underlying resources and their inputs, thus providing fine-grained diffs and richer previews.

If these are important for your use case, then the Helm 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 may apply via a transformation or via 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 on these resources with CrossGuard. Since Pulumi does not manage the underlying resources from Helm Release, you should choose Chart if you need to enforce policy on these resources.

Further reading

Helm Chart

• API Reference Docs with examples
• Provisioning Helm Charts
• Sample Project that installs Wordpress via Helm Chart in Typescript

Helm Release

• API Reference Docs with examples
• Installing Helm Releases
• Sample Project that installs Wordpress via Helm Release in Typescript