README.md

GitLab CI template for Helm

This project implements a GitLab CI/CD template to build your Helm Charts and/or deploy your application to a Kubernetes platform using Helm.

Usage

In order to include this template in your project, add the following to your gitlab-ci.yml:

include:
  - project: 'to-be-continuous/helm'
    ref: '5.1.0'
    file: '/templates/gitlab-ci-helm.yml'

Understand

This chapter introduces key notions and principle to understand how this template works.

Managed deployment environments

This template implements continuous delivery/continuous deployment based on Helm for projects hosted on Kubernetes platforms.

Review environments

The template supports review environments: those are dynamic and ephemeral environments to deploy your ongoing developments (a.k.a. feature or topic branches).

When enabled, it deploys the result from upstream build stages to a dedicated and temporary environment. It is only active for non-production, non-integration branches.

It is a strict equivalent of GitLab's Review Apps feature.

It also comes with a cleanup job (accessible either from the environments page, or from the pipeline view).

Integration environment

If you're using a Git Workflow with an integration branch (such as Gitflow), the template supports an integration environment.

When enabled, it deploys the result from upstream build stages to a dedicated environment. It is only active for your integration branch (develop by default).

Production environments

Lastly, the template supports 2 environments associated to your production branch (master by default):

• a staging environment (an iso-prod environment meant for testing and validation purpose),
• the production environment.

You're free to enable whichever or both, and you can also choose your deployment-to-production policy:

• continuous deployment: automatic deployment to production (when the upstream pipeline is successful),
• continuous delivery: deployment to production can be triggered manually (when the upstream pipeline is successful).

Deployment context variables

In order to manage the various deployment environments, this template provides a couple of dynamic variables that you might use in your hook scripts and Helm charts (as values):

environment variable	template directive	description
$environment_name	{{ .Release.Name }}	a generated application name to use for the current deployment environment (ex: myproject-review-fix-bug-12 or myproject-staging). This is used as the Helm release name in deploy & delete jobs - details below
$environment_type	{{ .Values.environmentType }}	the current deployment environment type (review, integration, staging or production)
$hostname	{{ .Values.hostname }}	the environment hostame, extracted from the environment URL (if you specified the environment url statically)

Generated environment name

The ${environment_name} variable is generated to designate each deployment environment with a unique and meaningful application name. By construction, it is suitable for inclusion in DNS, URLs, Kubernetes labels... It is built from:

• the application base name (defaults to $CI_PROJECT_NAME but can be overridden globally and/or per deployment environment - see configuration variables)
• GitLab predefined $CI_ENVIRONMENT_SLUG variable (sluggified name, truncated to 24 characters)

The ${environment_name} variable is then evaluated as:

• <app base name> for the production environment
• <app base name>-$CI_ENVIRONMENT_SLUG for all other deployment environments
• 💡 ${environment_name} can also be overriden per environment with the appropriate configuration variable

Examples (with an application's base name myapp):

$environment_type	Branch	$CI_ENVIRONMENT_SLUG	$environment_name
review	feat/blabla	review-feat-bla-xmuzs6	myapp-review-feat-bla-xmuzs6
integration	develop	integration	myapp-integration
staging	main	staging	myapp-staging
production	main	production	myapp

Deployment and cleanup scripts

The Helm template requires you to provide a Helm chart (either in the project or located in an external repository) to deploy and delete the application.

The environment deployment is processed as follows:

1. optionally executes the helm-pre-deploy.sh script in your project to perform specific environment pre-initialization (for e.g. create required services),
2. helm upgrade the chart with the configured parameters, using $environment_name as release name,
3. optionally executes the helm-post-deploy.sh script in your project to perform specific environment post-initialization stuff,

The environment deletion is processed as follows:

1. optionally executes the helm-pre-delete.sh script in your project to perform specific environment pre-cleanup stuff,
2. helm uninstall, using $environment_name as release name,
3. optionally executes the helm-post-delete.sh script in your project to perform specific environment post-cleanup (for e.g. delete bound services).

⚠️ each of the above hook scripts needs to be executable, you can add flag execution with: git update-index --chmod=+x helm-pre-cleanup.sh

Using variables

You have to be aware that your deployment (and cleanup) scripts have to be able to cope with various environments (review, integration, staging and production), each with different application names, exposed routes, settings, ... Part of this complexity can be handled by the lookup policies described above (ex: one script/manifest per env) and also by using available environment variables in your scripts and values files:

1. deployment context variables provided by the template,
2. any GitLab CI variable
3. any custom variable (ex: ${SECRET_TOKEN} that you have set in your project CI/CD variables)

While your scripts may simply use any of those variables, your values files can use variable substitution with the syntax ${VARIABLE_NAME}. Each of those patterns will be dynamically replaced in your files by the template right before using it.

⚠️

In order to be properly replaced, variables in your YAML value files shall be written with curly braces (ex: ${MYVAR} and not $MYVAR). Multiline variables must be surrounded by double quotes and you might have to disable line-length rule of yamllint as they are rewritten on a single line.

 tlsKey: "${MYKEY}"  # yamllint disable-line rule:line-length

Environments URL management

The Helm template supports two ways of providing your environments url:

• a static way: when the environments url can be determined in advance, probably because you're exposing your routes through a DNS you manage,
• a dynamic way: when the url cannot be known before the deployment job is executed.

The static way can be implemented simply by setting the appropriate configuration variable(s) depending on the environment (see environments configuration chapters):

• $HELM_ENVIRONMENT_URL to define a default url pattern for all your envs,
• $HELM_REVIEW_ENVIRONMENT_URL, $HELM_INTEG_ENVIRONMENT_URL, $HELM_STAGING_ENVIRONMENT_URL and $HELM_PROD_ENVIRONMENT_URL to override the default.

ℹ️ Each of those variables support a late variable expansion mechanism with the %{somevar} syntax, allowing you to use any dynamically evaluated variables such as ${environment_name}.

Example:

variables:
  HELM_BASE_APP_NAME: "wonderapp"
  # global url for all environments
  HELM_ENVIRONMENT_URL: "https://%{environment_name}.nonprod.acme.domain"
  # override for prod (late expansion of $HELM_BASE_APP_NAME not needed here)
  HELM_PROD_ENVIRONMENT_URL: "https://$HELM_BASE_APP_NAME.acme.domain"
  # override for review (using separate resource paths)
  HELM_REVIEW_ENVIRONMENT_URL: "https://wonderapp-review.nonprod.acme.domain/%{environment_name}"

To implement the dynamic way, your deployment script shall simply generate a environment_url.txt file in the working directory, containing only the dynamically generated url. When detected by the template, it will use it as the newly deployed environment url.

Deployment output variables

Each deployment job produces output variables that are propagated to downstream jobs (using dotenv artifacts):

• $environment_type: set to the type of environment (review, integration, staging or production),
• $environment_name: the application name (see below),
• $environment_url: set to the environment URL (whether determined statically or dynamically).

Those variables may be freely used in downstream jobs (for instance to run acceptance tests against the latest deployed environment).

Working with repositories & OCI-based registries

The Helm template supports indifferently the use of chart repositories and OCI-based registries (requires Helm 3 or above).

Those can be used both for pulling and/or pushing charts.

Configuring pull repositories

The pulling repositories/registries can be configured with the $HELM_REPOS. The value is expected as a (whitespace-separated) list of repo_name@repo_url (defaults to stable@https://charts.helm.sh/stable bitnami@https://charts.bitnami.com/bitnami).