README.md

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: 'Orange-OpenSource/tbc/helm'
    ref: '1.0.0'
    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	alpine/helm:latest - it is highly recommended to set the CLI version compatible with your Kubernetes server
HELM_CHART_DIR	The folder in which is stored the Helm chart	.

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

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, you should use generic values dynamically set and passed by the template:

• env: the environment type (review, integration, staging or production)
• 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)

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 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 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 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 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 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: 'Orange-OpenSource/tbc/helm'
    ref: '1.0.0'
    file: '/templates/gitlab-ci-helm.yml'
  # Vault variant
  - project: 'Orange-OpenSource/tbc/helm'
    ref: '1.0.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