Skip to content

GitLab CI template for Google Cloud Platform

This project implements a GitLab CI/CD template to deploy your application to the Google Cloud platform.

Usage

This template can be used both as a CI/CD component or using the legacy include:project syntax.

Use as a CI/CD component

Add the following to your gitlab-ci.yml:

include:
  # 1: include the component
  - component: gitlab.com/to-be-continuous/gcloud/gitlab-ci-gcloud@5.2.1
    # 2: set/override component inputs
    inputs:
      # ⚠ this is only an example
      base-app-name: wonderapp
      review-project: "prj-12345" # enable review env
      staging-project: "prj-12345" # enable staging env
      prod-project: "prj-12345" # enable production env

Use as a CI/CD template (legacy)

Add the following to your gitlab-ci.yml:

include:
  # 1: include the template
  - project: 'to-be-continuous/gcloud'
    ref: '5.2.1'
    file: '/templates/gitlab-ci-gcloud.yml'

variables:
  # 2: set/override template variables
  # ⚠ this is only an example
  GCP_BASE_APP_NAME: wonderapp
  GCP_REVIEW_PROJECT: "prj-12345" # enable review env
  GCP_STAGING_PROJECT: "prj-12345" # enable staging env
  GCP_PROD_PROJECT: "prj-12345" # enable production env

Understand

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

Managed deployment environments

This template implements continuous delivery/continuous deployment for projects hosted on Google Cloud Platform.

It allows you to manage automatic deployment & cleanup of standard predefined environments. Each environment can be enabled/disabled by configuration. If you're not satisfied with predefined environments and/or their associated Git workflow, you may implement you own environments and workflow, by reusing/extending the base (hidden) jobs. This is advanced usage and will not be covered by this documentation.

The following chapters present the managed predefined environments and their associated Git workflow.

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

Supported authentication methods

The Google Cloud Platform template supports two kinds of authentication:

  1. basic authentication with Service Account key file,
  2. or federated authentication using OpenID Connect.

Service account authentication

To use this authentication method, simply generate and provide Service Account key file as secret GitLab CI/CD variables (of type File), using the appropriate variables (see doc below).

Can be provided globally and/or per environment.

Federated authentication using OpenID Connect

The GCP template supports a federated authentication using OpenID Connect.

If you wish to use this authentication mode, please activate and configure the OIDC variant.

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, deployment manifests and other deployment resources:

  • ${environment_type}: the current deployment environment type (review, integration, staging or production)
  • ${environment_name}: a generated application name to use for the current deployment environment (ex: myapp-review-fix-bug-12 or myapp-staging) - details below

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 Google Cloud template requires you to provide a shell script that fully implements your application deployment and cleanup using the gcloud CLI and all other tools available in the selected Docker image.

The deployment script is searched as follows:

  1. look for a specific gcp-deploy-$environment_type.sh in the $GCP_SCRIPTS_DIR directory in your project (e.g. gcp-deploy-staging.sh for staging environment),
  2. if not found: look for a default gcp-deploy.sh in the $GCP_SCRIPTS_DIR directory in your project,
  3. if not found: the deployment job will fail.

The cleanup script is searched as follows:

  1. look for a specific gcp-cleanup-$environment_type.sh in the $GCP_SCRIPTS_DIR directory in your project (e.g. gcp-cleanup-staging.sh for staging environment),
  2. if not found: look for a default gcp-cleanup.sh in the $GCP_SCRIPTS_DIR directory in your project,
  3. if not found: the cleanup job will fail.

ℹ Your deployment (and cleanup) scripts have to be able to cope with various environments, each with different application names, exposed routes, settings, ... Part of this complexity can be handled by the lookup policies described above (ex: one script per env) and also by using available environment variables:

  1. deployment context variables provided by the template:
    • ${environment_type}: the current environment type (review, integration, staging or production)
    • ${environment_name}: the application name to use for the current environment (ex: myproject-review-fix-bug-12 or myproject-staging)
    • ${hostname}: the environment hostname, extracted from the current environment url (after late variable expansion - see below)
  2. any GitLab CI variable
  3. any custom variable (ex: ${SECRET_TOKEN} that you have set in your project CI/CD variables)

Environments URL management

The GCP 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):

  • $GCP_ENVIRONMENT_URL to define a default url pattern for all your envs,
  • $GCP_REVIEW_ENVIRONMENT_URL, $GCP_INTEG_ENVIRONMENT_URL, $GCP_STAGING_ENVIRONMENT_URL and $GCP_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:
  GCP_BASE_APP_NAME: "wonderapp"
  # global url for all environments
  GCP_ENVIRONMENT_URL: "https://%{environment_name}.nonprod.acme.domain"
  # override for prod (late expansion of $GCP_BASE_APP_NAME not needed here)
  GCP_PROD_ENVIRONMENT_URL: "https://$GCP_BASE_APP_NAME.acme.domain"
  # override for review (using separate resource paths)
  GCP_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).

You may also add and propagate your own custom variables, by pushing them to the gcloud.env file in your deployment script.

Configuration reference

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

Global configuration

The Google Cloud template uses some global configuration used throughout all jobs.

Input / Variable Description Default value
cli-image / GCP_CLI_IMAGE the Docker image used to run Google Cloud CLI commands gcr.io/google.com/cloudsdktool/cloud-sdk:latest
🔒 GCP_KEY_FILE Default Service Account key file none
base-app-name / GCP_BASE_APP_NAME Base application name $CI_PROJECT_NAME (see GitLab doc)
environment-url / GCP_ENVIRONMENT_URL Default environments url (only define for static environment URLs declaration)
supports late variable expansion (ex: https://%{environment_name}.gcloud.acme.com)
none
scripts-dir / GCP_SCRIPTS_DIR Directory where Google Cloud scripts (deploy & cleanup) are located . (root project dir)

Review environments configuration

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

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

Here are variables supported to configure review environments:

Input / Variable Description Default value
review-project / GCP_REVIEW_PROJECT Google Cloud project ID for review env none (disabled)
🔒 GCP_REVIEW_KEY_FILE Service Account key file to authenticate on review env (only define to override default) $GCP_KEY_FILE
review-app-name / GCP_REVIEW_APP_NAME Application name for review env "${GCP_BASE_APP_NAME}-${CI_ENVIRONMENT_SLUG}" (ex: myproject-review-fix-bug-12)
review-environment-url / GCP_REVIEW_ENVIRONMENT_URL The review environments url (only define for static environment URLs declaration and if different from default) $GCP_ENVIRONMENT_URL
review-autostop-duration / GCP_REVIEW_AUTOSTOP_DURATION The amount of time before GitLab will automatically stop review environments 4 hours

Integration environment configuration

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

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

Here are variables supported to configure the integration environment:

Input / Variable Description Default value
integ-project / GCP_INTEG_PROJECT Google Cloud project ID for integration env none (disabled)
🔒 GCP_INTEG_KEY_FILE Service Account key file to authenticate on integration env (only define to override default) $GCP_KEY_FILE
integ-app-name / GCP_INTEG_APP_NAME Application name for integration env ${GCP_BASE_APP_NAME}-integration
integ-environment-url / GCP_INTEG_ENVIRONMENT_URL The integration environment url (only define for static environment URLs declaration and if different from default) $GCP_ENVIRONMENT_URL

Staging environment configuration

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

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

Here are variables supported to configure the staging environment:

Input / Variable Description Default value
staging-project / GCP_STAGING_PROJECT Google Cloud project ID for staging env none (disabled)
🔒 GCP_STAGING_KEY_FILE Service Account key file to authenticate on staging env (only define to override default) $GCP_KEY_FILE
staging-app-name / GCP_STAGING_APP_NAME Application name for staging env ${GCP_BASE_APP_NAME}-staging
staging-environment-url / GCP_STAGING_ENVIRONMENT_URL The staging environment url (only define for static environment URLs declaration and if different from default) $GCP_ENVIRONMENT_URL

Production environment configuration

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

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

Here are variables supported to configure the production environment:

Input / Variable Description Default value
prod-project / GCP_PROD_PROJECT Google Cloud project ID for production env none (disabled)
🔒 GCP_PROD_KEY_FILE Service Account key file to authenticate on production env (only define to override default) $GCP_KEY_FILE
prod-app-name / GCP_PROD_APP_NAME Application name for production env $GCP_BASE_APP_NAME
prod-environment-url / GCP_PROD_ENVIRONMENT_URL The production environment url (only define for static environment URLs declaration and if different from default) $GCP_ENVIRONMENT_URL
prod-deploy-strategy / GCP_PROD_DEPLOY_STRATEGY Defines the deployment to production strategy. One of manual (i.e. one-click) or auto. manual

Examples

Google AppEngine application

Context

Let's imagine a backend service:

  • named coockedoodledoo,
  • developped in whichever language,
  • part of project named farmvoices
  • hosted on Google AppEngine with project ID farmvoices-12345
  • with review, staging and production environments enabled.

.gitlab-ci.yml

include:
  - component: gitlab.com/to-be-continuous/gcloud/gitlab-ci-gcloud@5.2.1
    inputs:
      base-app-name: coockedoodledoo
      review-project: "farm-12345" # enable review env
      staging-project: "farm-12345" # enable staging env
      prod-project: "farm-12345" # enable production env
      staging-environment-url: "https://staging-dot-coockedoodledoo-dot-farmvoices-12345.ew.r.appspot.com"
      prod-environment-url: "https://coockedoodledoo-dot-farmvoices-12345.ew.r.appspot.com"
      # GCP_KEY_FILE defined as secret CI/CD variable

# override review environment url (uses $CI_ENVIRONMENT_SLUG as app version)
gcp-review:
  environment:
    url: "https://$CI_ENVIRONMENT_SLUG-dot-coockedoodledoo-dot-farmvoices-12345.ew.r.appspot.com"

AppEngine manifest

# Google AppEngine manifest
# see: https://cloud.google.com/appengine/docs/standard/java11/config/appref
runtime: TODO # depends on languages
instance_class: F2
service: coockedoodledoo

...

variables:
  # this is an example of hardcoded (non-sensitive) configuration variable
  SOME_CONFIG: "some-value"
  # this is an example of variabilized (secret) configuration variable
  # will be replaced programmatically during deployment
  SOME_SECRET: "${SOME_SECRET}"

hook scripts

gcp-deploy.sh

This script is executed by the template to perform the application(s) deployment based on gcloud CLI.

#!/usr/bin/env bash
echo "[gcp-deploy] Deploy burger/$CI_ENVIRONMENT_SLUG..."

# prepare GAE deployment directory (copy build output)
mkdir -p gae
cp build/* gae

# copy manifest with variables substitution
awk '{while(match($0,"[$]{[^}]*}")) {var=substr($0,RSTART+2,RLENGTH-3);gsub("[$]{"var"}",ENVIRON[var])}}1' < src/app.yaml > gae/app.yaml

# gcloud deploy
# use $CI_ENVIRONMENT_SLUG as the version
cd gae

if [[ "$CI_ENVIRONMENT_SLUG" == "production" ]]
then
  promote_opt="--promote"
else
  promote_opt="--no-promote"
fi

gcloud --quiet app deploy --project=${gcp_project_id} --version=${CI_ENVIRONMENT_SLUG} $promote_opt
gcp-cleanup.sh

This script is executed by the template to perform the application(s) cleanup based on gcloud CLI (review env only).

#!/usr/bin/env bash
echo "[gcp-cleanup] Cleanup burger/$CI_ENVIRONMENT_SLUG..."

# use $CI_ENVIRONMENT_SLUG as the version
gcloud --quiet app versions delete --project=${gcp_project_id} --service=coockedoodledoo ${CI_ENVIRONMENT_SLUG}

Variants

The Google Cloud template can be used in conjunction with template variants to cover specific cases.

OIDC variant

This variant enables federated authentication using OpenID Connect.

If you wish to use this authentication mode, please follow carefully the GitLab guide, then configure appropriately the related variables:

  • GPC_OIDC_PROVIDER / GPC_OIDC_ACCOUNT for any global/common access,
  • GPC_<env>_OIDC_PROVIDER / GPC_<env>_OIDC_ACCOUNT if you wish to use separate settings with any of your environments.

The GPC_OIDC_PROVIDER & GPC_<env>_OIDC_PROVIDER variable shall be of the form:

projects/<PROJECT_NUMBER>/locations/global/workloadIdentityPools/<POOL_ID>/providers/<PROVIDER_ID>

The following commands may help you retrieve the different values:

  • gcloud projects describe $GCP_PROJECT --format="value(projectNumber)" will return the PROJECT_NUMBER value
  • gcloud iam workload-identity-pools list --location=global --format="value(name)" will list you POOL_IDs available on your GCP_PROJECT
  • gcloud iam workload-identity-pools providers list --workload-identity-pool=<my-pool> --location=global --format="value(name)" will return the list of available PROVIDER_ID for one POOL_ID

Configuration

The variant supports the following configuration:

Input / Variable Description Default value
oidc-aud / GCP_OIDC_AUD The aud claim for the JWT $CI_SERVER_URL
oidc-provider / GCP_OIDC_PROVIDER Default Workload Identity Provider associated with GitLab to authenticate with OpenID Connect none
oidc-account / GCP_OIDC_ACCOUNT Default Service Account to which impersonate with OpenID Connect authentication none
review-oidc-provider / GCP_REVIEW_OIDC_PROVIDER Workload Identity Provider associated with GitLab to authenticate with OpenID Connect on review environment none
review-oidc-account / GCP_REVIEW_OIDC_ACCOUNT Service Account to which impersonate with OpenID Connect authentication on review environment none
integ-oidc-provider / GCP_INTEG_OIDC_PROVIDER Workload Identity Provider associated with GitLab to authenticate with OpenID Connect on integration environment none
integ-oidc-account / GCP_INTEG_OIDC_ACCOUNT Service Account to which impersonate with OpenID Connect authentication on integration environment none
staging-oidc-provider / GCP_STAGING_OIDC_PROVIDER Workload Identity Provider associated with GitLab to authenticate with OpenID Connect on staging environment none
staging-oidc-account / GCP_STAGING_OIDC_ACCOUNT Service Account to which impersonate with OpenID Connect authentication on staging environment none
prod-oidc-provider / GCP_PROD_OIDC_PROVIDER Workload Identity Provider associated with GitLab to authenticate with OpenID Connect on production environment none
prod-oidc-account / GCP_PROD_OIDC_ACCOUNT Service Account to which impersonate with OpenID Connect authentication on production environment none

Example

include:
  # main template
  - component: gitlab.com/to-be-continuous/gcloud/gitlab-ci-gcloud@5.2.1
  # OIDC variant
  - component: gitlab.com/to-be-continuous/gcloud/gitlab-ci-gcloud-oidc@5.2.1
    inputs:
      # audience claim for JWT
      oidc-aud: "https://iam.googleapis.com"
      # common OIDC config for non-prod envs
      oidc-provider: "projects/<gcp_nonprod_proj_id>/locations/global/workloadIdentityPools/<pool_id>/providers/<provider_id>"
      oidc-account: "<name>@$<gcp_nonprod_proj_id>.iam.gserviceaccount.com"
      # specific OIDC config for prod
      prod-oidc-provider: "projects/<gcp_prod_proj_id>/locations/global/workloadIdentityPools/<pool_id>/providers/<provider_id>"
      prod-oidc-account: "<name>@$<gcp_prod_proj_id>.iam.gserviceaccount.com"

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:

Input / Variable Description Default value
TBC_VAULT_IMAGE The Vault Secrets Provider image to use (can be overridden) registry.gitlab.com/to-be-continuous/tools/vault-secrets-provider:master
vault-base-url / VAULT_BASE_URL The Vault server base API url none
vault-oidc-aud / VAULT_OIDC_AUD The aud claim for the JWT $CI_SERVER_URL
🔒 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:

Parameter 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
  - component: gitlab.com/to-be-continuous/gcloud/gitlab-ci-gcloud@5.2.1
  # Vault variant
  - component: gitlab.com/to-be-continuous/gcloud/gitlab-ci-gcloud-vault@5.2.1
    inputs:
      # audience claim for JWT
      vault-oidc-aud: "https://vault.acme.host"
      vault-base-url: "https://vault.acme.host/v1"
      # $VAULT_ROLE_ID and $VAULT_SECRET_ID defined as a secret CI/CD variable

variables:
  # Secrets managed by Vault
  SOME_SECRET_USED_IN_MY_APP: "@url@http://vault-secrets-provider/api/secrets/b7ecb6ebabc231/prod/gcloud/secret?field=my.app.secret"