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.

TpT-CLI Github Repo

ODE v2 Reference

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.

Example Postman Tests

tptapis.postman.co/collections/5817358-93d711ed-3181-480d-bba5-ab68b0a29eae?version=latest&workspace=d9a6b5ae-1a22-4d0b-b706-2cc818031f79