Skip to content

GitLab CI template for Helm

This project implements a generic GitLab CI template for Helm.

Overview

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

It provides several features, usable in different modes (by configuration).

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).

Usage

Include

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

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

Global configuration

The Helm template uses some global configuration used throughout all jobs.

Name description default value
HELM_CLI_IMAGE The Docker image used to run Helm
⚠️ set the version required by your Kubernetes server
alpine/helm:latest
HELM_CHART_DIR The folder in which is stored the Helm chart .
HELM_ENV_VALUE_NAME The environment type variable set to helm env
HELM_HOSTNAME_VALUE_NAME The hostname variable set to helm hostname

Secrets management

Here are some advices about your secrets (variables marked with a πŸ”’):

  1. Manage them as project or group CI/CD variables:
    • masked to prevent them from being inadvertently displayed in your job logs,
    • protected if you want to secure some secrets you don't want everyone in the project to have access to (for instance production secrets).
  2. In case a secret contains characters that prevent it from being masked, simply define its value as the Base64 encoded value prefixed with @b64@: it will then be possible to mask it and the template will automatically decode it prior to using it.
  3. Don't forget to escape special characters (ex: $ -> $$).

⚠️ your Values files may contain variable patterns such as ${MY_SECRET}. If so, those patterns will be evaluated (replaced) with actual environment values. This is a safe way of managing your application secrets.

Deploy & cleanup jobs

The Helm template declares deployment & cleanup jobs for each supported environment.

It supports 2 deployment cases:

  • using an external Helm chart (retrieved from a repository),
  • using an internal Helm chart (located in the project).

Here are global configuration variables for deploy jobs.

Name description default value
KUBE_NAMESPACE The default Kubernetes namespace to use none but this variable is automatically set by GitLab Kubernetes integration when enabled
πŸ”’ HELM_DEFAULT_KUBE_CONFIG The default kubeconfig content to use $KUBECONFIG (thus supports the GitLab Kubernetes integration when enabled)
HELM_DEPLOY_ARGS The Helm command with options to deploy the application (without dynamic arguments such as release name and chart) upgrade --install --atomic --timeout 120s
HELM_DELETE_ARGS The Helm command with options to cleanup the application (without dynamic arguments such as release name) uninstall
HELM_DEPLOY_CHART The Helm chart to deploy. Only required if you want to deploy an external chart. none
HELM_REPOS The Helm chart repositories to use (formatted as repo_name_1@:repo_url_1 repo_name_2@:repo_url_2 ...) stable@https://charts.helm.sh/stable bitnami@https://charts.bitnami.com/bitnami
HELM_BASE_APP_NAME Base application name $CI_PROJECT_NAME (see GitLab doc)

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 $CI_ENVIRONMENT_URL.

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

Here are configuration details for each environment.

Review environments

Review environments are dynamic and ephemeral environments to deploy your ongoing developments (a.k.a. feature or topic branches).

They are enabled by default and can be disabled by setting the HELM_REVIEW_DISABLED variable (see below).

Here are variables supported to configure review environments:

Name description default value
HELM_REVIEW_DISABLED Set to true to disable review env none (enabled)
HELM_REVIEW_APP_NAME Application name for review env "${HELM_BASE_APP_NAME}-${CI_ENVIRONMENT_SLUG}" (ex: myproject-review-fix-bug-12)
HELM_REVIEW_NAMESPACE The Kubernetes namespace to use for review env (only define to override default) $KUBE_NAMESPACE
πŸ”’ HELM_REVIEW_KUBE_CONFIG kubeconfig content used for review env (only define to override default) $HELM_DEFAULT_KUBE_CONFIG
HELM_REVIEW_VALUES The Values file to use with review environments none
HELM_REVIEW_ENVIRONMENT_SCHEME The review environment protocol scheme https
HELM_REVIEW_ENVIRONMENT_DOMAIN The review environment domain none

Note: By default review environment.url will be built as ${HELM_REVIEW_ENVIRONMENT_SCHEME}://${$CI_PROJECT_NAME}-${CI_ENVIRONMENT_SLUG}.${HELM_REVIEW_ENVIRONMENT_DOMAIN}

Integration environment

The integration environment is the environment associated to your integration branch (develop by default).

It is enabled by default and can be disabled by setting the HELM_INTEG_DISABLED variable (see below).

Here are variables supported to configure the integration environment:

Name description default value
HELM_INTEG_DISABLED Set to true to disable integration env none (enabled)
HELM_INTEG_APP_NAME Application name for integration env $HELM_BASE_APP_NAME-integration
HELM_INTEG_NAMESPACE The Kubernetes namespace to use for integration env (only define to override default) $KUBE_NAMESPACE
πŸ”’ HELM_INTEG_KUBE_CONFIG kubeconfig content used for integration env (only define to override default) $HELM_DEFAULT_KUBE_CONFIG
HELM_INTEG_VALUES The Values file to use with the integration environment none
Β HELM_INTEG_ENVIRONMENT_URL The integration environment url including scheme (ex: https://my-application-integration.nonpublic.k8s.domain.com). Do not use variable inside variable definition as it will result in a two level cascade variable and gitlab does not allow that. none

Staging environment

The staging environment is an iso-prod environment meant for testing and validation purpose associated to your production branch (master by default).

It is enabled by default and can be disabled by setting the HELM_STAGING_DISABLED variable (see below).

Here are variables supported to configure the staging environment:

Name description default value
HELM_STAGING_DISABLED Set to true to disable staging env none (enabled)
HELM_STAGING_APP_NAME Application name for staging env $HELM_BASE_APP_NAME-staging
HELM_STAGING_NAMESPACE The Kubernetes namespace to use for staging env (only define to override default) $KUBE_NAMESPACE
πŸ”’ HELM_STAGING_KUBE_CONFIG kubeconfig content used for staging env (only define to override default) $HELM_DEFAULT_KUBE_CONFIG
HELM_STAGING_VALUES The Values file to use with the staging environment none
Β HELM_STAGING_ENVIRONMENT_URL The staging environment url including scheme (ex: https://my-application-staging.nonpublic.k8s.domain.com). Do not use variable inside variable definition as it will result in a two level cascade variable and gitlab does not allow that. none

Production environment

The production environment is the final deployment environment associated with your production branch (master by default).

It is enabled by default and can be disabled by setting the HELM_PROD_DISABLED variable (see below).

Here are variables supported to configure the production environment:

Name description default value
HELM_PROD_DISABLED Set to true to disable production env none (enabled)
HELM_PROD_APP_NAME Application name for production env $HELM_BASE_APP_NAME
HELM_PROD_NAMESPACE The Kubernetes namespace to use for production env (only define to override default) $KUBE_NAMESPACE
πŸ”’ HELM_PROD_KUBE_CONFIG kubeconfig content used for production env (only define to override default) $HELM_DEFAULT_KUBE_CONFIG
AUTODEPLOY_TO_PROD Set this variable to auto-deploy to production. If not set deployment to production will be manual (default behaviour). none (disabled)
HELM_PROD_VALUES The Values file to use with the production environment none
HELM_PROD_ENVIRONMENT_URL Β The production environment url including scheme (ex: https://my-application.public.k8s.domain.com) Do not use variable inside variable definition as it will result in a two level cascade variable and gitlab does not allow that. none

Dynamic Values and 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 resource per env).

In order to be able to implement some genericity in your scripts and templates:

  1. you should use generic values dynamically set and passed by the template:

  2. $HELM_ENV_VALUE_NAME (set by default to env): the environment type (review, integration, staging or production)

  3. $HELM_HOSTNAME_VALUE_NAME (set by default to hostname): the environment hostname, extracted from ${CI_ENVIRONMENT_URL} (got from environment:url - see OS_REVIEW_ENVIRONMENT_SCHEME, OS_REVIEW_ENVIRONMENT_DOMAIN, OS_STAGING_ENVIRONMENT_URL and OS_PROD_ENVIRONMENT_URL)

  4. you should use available environment variables:

  5. any GitLab CI variable (ex: ${CI_ENVIRONMENT_URL} to retrieve the actual environment exposed route)

  6. any custom variable (ex: ${SECRET_TOKEN} that you have set in your project CI/CD variables)

⚠️

In order to be properly replaced, variables in your YAML value file 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

helm-lint job

This job examines your chart for possible issues and uses the following variables:

Name description default value
HELM_LINT_DISABLED Set to true to disable Helm lint none (enabled)
HELM_LINT_ARGS The Helm command with options to trigger the analysis (without dynamic arguments such as the chart path) lint --strict
HELM_DEPENDENCY_ARGS The Helm command with options to update on-disk the chart dependencies (without dynamic arguments such as the chart path) dependency update

helm-values-*-lint job

These jobs perform a Yaml Lint of your Helm values file and uses the following variables:

Name description default value
HELM_YAMLLINT_IMAGE The Docker image used to run YamlLint test cytopia/yamllint
HELM_YAMLLINT_DISABLED Set to true to disable Yaml lint none (enabled)
HELM_YAMLLINT_CONFIG Config used with the yamllint tool {extends: relaxed, rules: {line-length: {max: 160}}}
HELM_YAMLLINT_ARGS Arguments used by the lint job -f colored --strict

helm-*-score job

This job runs Kube-Score on the resources to be created by Helm and uses the following variables:

Name description default value
HELM_KUBE_SCORE_DISABLED Set to true to disable Kube-Score none (enabled)
HELM_KUBE_SCORE_IMAGE The Docker image used to run Kube-Score zegl/kube-score:latest-helm3
HELM_KUBE_SCORE_ARGS Arguments used by the helm-score job none

helm-package job

This job packages your chart into an archive and uses the following variables:

Name description default value
HELM_PACKAGE_ARGS The Helm command with options to perform the packaging (without dynamic arguments such as the chart path) package --dependency-update

| HELM_SEMREL_RELEASE_DISABLED | Set to true to disable usage of semrel release info for helm package | none (enabled) |

semantic-release integration

If you activate the semantic-release-info job from the semantic-release template, the mvn-release job will automatically use the generated next version info for both application version (--app-version) and chart version (--version).

If no next version info is generated by semantic-release, the package will be created either, but without versionning info.

Note: You can disable the semantic-release integration (as it's the helm-packagejob that will perform the release) with the HELM_SEMREL_RELEASE_DISABLED variable.

helm-publish job

This job uses the following variables:

Name description default value
HELM_PUBLISH_ARGS Arguments used by the Helm publish job none
HELM_PUBLISH_DIR The folder in which the job will publish the chart .
HELM_PUBLISH_URL The URL of the the chart to publish none

helm-test job

This job runs Helm tests. The job definition must contain the helm test hook annotation: helm.sh/hook: test You are welcome to nest your test suite under a tests/ directory like $HELM_CHART_DIR/templates/tests/ for more isolation.

It is disabled by default and can be enabled by setting the HELM_TEST_ENABLED variable (see below).

It uses the following variables:

Name description default value
HELM_TEST_ENABLED Set to true to enable Helm test none (disabled)
HELM_TEST_ARGS The Helm command with options to perform acceptance test (without dynamic arguments such as the chart path) test

Variants

Vault variant

This variant allows delegating your secrets management to a Vault server.

Configuration

In order to be able to communicate with the Vault server, the variant requires the additional configuration parameters:

Name description default value
VAULT_BASE_URL The Vault server base API url none
πŸ”’ VAULT_ROLE_ID The AppRole RoleID must be defined
πŸ”’ VAULT_SECRET_ID The AppRole SecretID must be defined

Usage

Then you may retrieve any of your secret(s) from Vault using the following syntax:

@url@http://vault-secrets-provider/api/secrets/{secret_path}?field={field}

With:

Name description
secret_path (path parameter) this is your secret location in the Vault server
field (query parameter) parameter to access a single basic field from the secret JSON payload

Example

include:
  # main template
  - project: 'to-be-continuous/helm'
    ref: '2.0.3'
    file: '/templates/gitlab-ci-helm.yml'
  # Vault variant
  - project: 'to-be-continuous/helm'
    ref: '2.0.3'
    file: '/templates/gitlab-ci-helm-vault.yml'

variables:
    # Secrets managed by Vault
    HELM_DEFAULT_KUBE_CONFIG: "@url@http://vault-secrets-provider/api/secrets/b7ecb6ebabc231/my-app/helm/noprod?field=kube_config"
    HELM_PROD_KUBE_CONFIG: "@url@http://vault-secrets-provider/api/secrets/b7ecb6ebabc231/my-app/helm/prod?field=kube_config"
    VAULT_BASE_URL: "https://vault.acme.host/v1"
    # $VAULT_ROLE_ID and $VAULT_SECRET_ID defined as a secret CI/CD variable

GitLab compatibility

ℹ️ This template is actually tested and validated on GitLab Community Edition instance version 13.12.11