Deploying Applications with Helm
Warning
This content is part of the legacy version of Waypoint that is no longer actively maintained. For additional information on the new vision of Waypoint, check out this blog post and the HCP Waypoint documentation.
Waypoint can deploy your applications onto Kubernetes using Helm. Waypoint then tracks and shows you the health of all the resources that the Helm chart created.
If you're already using Helm, this lets you adopt Waypoint with very little friction since you can reuse your existing Helm charts for your applications. Another benefit of using Helm with Waypoint is that you can set chart values more dynamically, such as setting different settings per environment, referencing the most recently built artifacts, etc.
Not a Helm user? No problem! Waypoint supports many other mechanisms
for deploying to Kubernetes. You can use the
kubernetes
plugin for highly opinionated, no YAML deployments. Or you can use
kubernetes-apply
with
a directory of YAML files.
Why Helm?
The Helm deployment plugin for Waypoint is aimed primarily at people
who either already use Helm or need to use a tool that lets them specify
any custom Kubernetes resources. If you don't know Helm and are just trying
to deploy a typical web service, you can use the YAML-less
kubernetes
plugin. And you can always switch
deployment plugins later, so you don't need to be worried about making a
"wrong" decision.
For people who are familiar with Helm or would prefer to use Helm, you might still ask: but why would I use Helm with Waypoint? Why not use Helm directly? There are many reasons:
Dynamic Chart values. Waypoint makes it easy to set chart values based on dynamic information such as metadata about the most recent artifact build, Git commit information, or just computed or templated information using HCL functions.
Environments. Waypoint handles the higher level multi-environment abstraction for you, so you can deploy your chart to multiple environments but manage and see them all using the same tool and UI.
Single Workflow Configuration. While you still have to write Helm charts, you can invoke Helm using the same tool you're using to invoke builds, release management, etc.
Other Waypoint features. You can take advantage of other Waypoint features such as remote operations, logs, exec, input variables, and more.
Using Helm with Waypoint
The example below shows a waypoint.hcl
configuration that uses a
Helm chart in the "helm" directory. We set two Chart values image.repository
and image.tag
to point to the artifact we just built (see
here for more information on artifact variables). Notice that with the
set
Chart values, we could use any Waypoint variables, HCL functions, etc.
to dynamically set chart configuration.
With this set, you can run waypoint deploy
(if you have an artifact
built already) and Waypoint will use Helm to deploy your application.
Note: The set
syntax is the same as the --set
flag used
with the helm
CLI. This is documented on the Helm website here. You can also specify
values YAML files.
Chart Repositories
The chart doesn't have to be local. You can also use a chart from a Helm chart repository:
Entrypoint Variables
If you want to use the Waypoint entrypoint functionality, you must manually inject the entrypoint environment variables. The opinionated Kubernetes plugin does this automatically but since with Helm you're writing manual Kubernetes resources with YAML, we can't automatically inject the environment variables.
A map of the environment variables to set are exposed in the waypoint.hcl
as entrypoint.env
. This can be
passed into your Helm chart either as values or templating your YAML templates.
The recommended approach is to use Helm values, to avoid templating a template.
A full example is available in the waypoint-examples
repository,
but an incomplete example is shown below to briefly explain the process.
Note: This also requires that the entrypoint binary is already
injected into the image as part of the build process. This happens automatically
for docker
or pack
builders. If you're using an externally built image,
you must inject the entrypoint manually.
And values.yaml.tpl
:
And your Deployment template in your Helm chart:
The key thing we do is setup a values.yaml
override that templates our
entrypoint.env
variables. This is then passed into the Helm installation
and used within the deployment template to set the proper environment
variables. This is equivalent to running helm install
with the -f
flag
to specify a values YAML file.
Reference Documentation
To view a full list of the available options for the Helm plugin, please see the plugin reference documentation. This documentation is more dense and has less examples, but is an exhaustive list of the available options.