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.4.0'
    file: '/templates/gitlab-ci-helm.yml'

Global configuration

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

Charts publishing

The template builds a chart package that may be pushed as two distinct packages, depending on a certain workflow:

1. snapshot: the chart is first packaged and then pushed to some registry as the snapshot image. It can be seen as the raw result of the build, but still untested and unreliable.
2. release: once the snapshot chart has been thoroughly tested (both by package-test stage jobs and/or acceptance stage jobs after being deployed to some server), then the chart is pushed one more time as the release chart. This second push can be seen as the promotion of the snapshot chart being now tested and reliable.

Common variables for helm-package and helm-pusblish:

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.

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:

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:

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:

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:

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:

• $HELM_ENV_VALUE_NAME (set by default to env): the environment type (review, integration, staging or production)
• $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)

2. you should use available environment variables:

• any GitLab CI variable (ex: ${CI_ENVIRONMENT_URL} to retrieve the actual environment exposed route)
• 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:

helm-values-*-lint job

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

helm-*-score job

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

helm-package job

This job packages your chart into an archive, optionaly push it to a snapshot repository and uses the following variables:

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 push helm package to a release repository and uses the following variables:

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:

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:

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:

Example

include:
  # main template
  - project: 'to-be-continuous/helm'
    ref: '2.4.0'
    file: '/templates/gitlab-ci-helm.yml'
  # Vault variant
  - project: 'to-be-continuous/helm'
    ref: '2.4.0'
    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