Example Helm Chart¶ ↑
This is an example Helm Chart. Helm sits a layer above Kubernetes, and provides a simpler interface for defining Kubernetes entities across environments. It also provides a mechanism for declaring dependencies between Kubernetes services, although we're not currently using that feature. You can think of Helm as a package manager and deployment tool for Kubernetes entities.
Currently, we use Helm to manage deployments and updates to our On Demand Environments (ODEs). Production deploys use Kubernetes directly, except for graphapi which is also using Helm.
If you'd like your service to deploy to an ODE (you should!), you'll need to build a Chart for it and reference that chart from our Charts repo. See this branch for a reference on how to do this.
General Chart Overview¶ ↑
There are a couple files that constitute a Chart. Here is an overview:
(Project Root) └── kubernetes └── helm ├── charts │ ├── db-migrate-0.2.2.tgz │ ├── mysql-1.6.9.tgz ├── templates │ ├── hooks │ │ ├── db-prepare.yaml │ ├── _env.yaml │ ├── _helpers.tpl │ ├── autoscaler.yaml │ ├── deployment.yaml │ ├── NOTES.txt │ └── service.yaml ├── .helmignore ├── Chart.yaml ├── README.md ├── requirements.lock ├── requirements.yaml ├── values.prod.yaml ├── values.staging.yaml └── values.yaml
Chart.yaml¶ ↑
This is Helm's entrypoint to the Chart. Here the high level metadata is specified, including the Chart name and description.
values.yaml¶ ↑
Here you can configure any variables that your Chart will depend on. This includes properties like application secrets, and endpoint configuration of service dependencies. These variables can then be referenced in the Chart definition, to construct your Kubernetes entity.
Usually, you want different configurations for different deployment environments. We use values.yaml
to configure a standard production deployment, and then use values.{env}.yaml
to override values where a given environment differs from production. In this service, we have created values.dev.yaml
for configuring ODE deployments and values.staging.yaml
to configure deployments to staging.
Secrets¶ ↑
See this wiki page for information on how to define a secret in Kubernetes. After adding the secret to the cluster, you can reference it in a values
file which will cause it to be passed to your application as an environmental variable:
secrets: - name: BUGSNAG_API_KEY valueFrom: secretKeyRef: name: service-template-node-bugsnag key: apiKey
If you wish to use a secret in ODEs environnments as well, will need to use the copy-secrets
dependency chart so that the secrets are copied from the default namespace when a user spins up an ODE. See the documentation for the chart for more information. A service which needed a secret called super-secret
when running in ODEs would have something like this in its values.dev.yaml
file:
secrets: - name: SUPER_SECRET valueFrom: secretKeyRef: name: super-secret key: key copy-secrets: secrets: - super-secret
/templates¶ ↑
Helm will process all files in this directory, and combine them into a Kubernetes entity definition. These files might look like the Kube deployment specifications you're used to (e.g. for tpt-frontend), with one major difference: they can reference variables. These variables can come from a couple places, described in more detail below.
requirements.yaml¶ ↑
This optional file lists dependencies for your chart. After adding or changing an entry in this file, you can download all dependencies into the charts
folder and update requirements.lock
with the command helm dependency update
. Right now, the only dependency included is the copy-secrets
chart mentioned above.
Template file syntax¶ ↑
The meat of the Helm Chart is the /templates
directory, which contains all the resources needed for Helm to construct and deploy a Kubernetes resource. These files mostly look like Kubernetes entity definitions, but with reference to variables. You can find documentation on what's available here, but below are couple common patterns you'll see.
myProperty: {{ .Values.foo.bar }}¶ ↑
Inserts someValue
as the value of myProperty, where someValue
was defined in your values.yaml
file:
foo: bar: someValue
myProperty: {{ template “foo.bar” }}¶ ↑
References a property that was specified by _helpers.tpl
{{- define "foo.bar" -}} {{- if .Values.fullnameOverride -}} {{- .Values.fullnameOverride -}} {{- else -}} {{- .Values.nameOverride -}} {{- end -}} {{- end -}}
This is a good way of bringing in variables that need a bit of processing to transform them from raw values.yaml
properties.
myProperty: “{{ .Release.Name }}”¶ ↑
References Helm defined variables
Testing Your Helm Charts¶ ↑
If this prints the contents of your helm charts without erroring, there are no syntax errors.
helm install --dry-run --debug </path/to/helm/chart/dir>
The TpT-CLI tool should be used to ensure your service will work with TpT ODEs v2.
Testing Your Service¶ ↑
Contract and API Functional Testing (IN PROGRESS)¶ ↑
Helm test charts can be used to test your service in isolation. If you have tests defined in Postman (SUPPORTED) or your service repo (IN PROGRESS), you can execute them using the TpT-CLI test command (IN PROGRESS).
Do not use helm test
directly to run tests. This requires some extra coordination to not leave test pods running and still have access to test results. TpT-CLI will be updated with a tet command to handle this orchestration.
Usage¶ ↑
1) Create a helm test chart under templates/tests. See test.apiFunctional.postman.yaml 2) Add any test configuration to the appropriate values.yaml. 3) Verify your changes using tpt project check
. 4) Commit your changes. 5) Release your charts using tpt project push
. 6) (IN PROGRESS) Execute the tests via the TPT-CLI test command.