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 V3 Chart resource. This resource simulated Helm installation by retrieving the templates for underlying resources from the chart and 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 V3 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
Helm V3 Chart resource renders the templates from your chart and then manage them directly with the Pulumi Kubernetes provider.
Chart is implemented as a
Component Resource which provide a number of benefits for Pulumi users:
- Visibility into all resources encapsulated by the Chart in Pulumi’s state, allowing users to directly query properties of individual resources.
- Tight integration with Pulumi’s Policy-as-Code framework -
CrossGuardto enforce policies on all resources installed by Helm charts
- Ability to leverage transformations to programmatically manipulate resources installed by Helm charts in any of the Pulumi supported programming languages
- 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:
- No support for Helm Chart Hooks - i.e. equivalent of running
helm installwith the
- No ability to import existing Helm releases into Pulumi state
- 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
- Since we use Helm’s native support for downloading, processing and installing charts, all the major features of Helm Charts such as hooks can be readily supported
- Existing Helm releases installed via the Helm CLI can be imported into Pulumi state as of v3.12.1 of the Pulumi Kubernetes SDK
- 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:
- The ability to support transformations is limited to that offered by the
- Since Pulumi is not directly managing the underlying Kubernetes resource installed by
CrossGuardpolicies can’t be enforced on these resources.
- 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
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. Unfortunately,
Helm Release does not have the same flexibility in offering transformations support.
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.
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.
- API Reference Docs with examples
- Provisioning Helm Charts
- Sample Project that installs Wordpress via Helm Chart in Typescript