GitLab CI template for Google Cloud Platform

This project implements a generic GitLab CI template for Google Cloud Platform environments.

Overview: managed 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).

Usage

Include

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

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

Global configuration

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

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

Deployment and cleanup jobs

The GitLab CI template for Google Cloud requires you to provide a shell script that fully implements your application deployment and cleanup using the gcloud CLI.

Lookup policy

The deployment script is searched as follows:

1. look for a specific gcp-deploy-$env.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-$env.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 script(s) shall use available dynamic variables.

Dynamic 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, you should use available environment variables:

1. any GitLab CI variable (ex: ${CI_ENVIRONMENT_URL} to retrieve the actual environment exposed route)
2. any custom variable (ex: ${SECRET_TOKEN} that you have set in your project CI/CD variables)
3. dynamic variables set by the template:
   • ${appname}: the application target name to use in this environment (ex: myproject-review-fix-bug-12 or myproject-staging)
   • ${env}: the environment type (review, integration, staging or production)
   • ${hostname}: the environment hostname, extracted from ${CI_ENVIRONMENT_URL} (has to be explicitly declared as environment:url in your .gitlab-ci.yml file)
   • ${gcp_project_id}: the current Google Cloud project ID associated to your environment

Static vs. Dynamic environment URLs

The Google Cloud template supports two ways of defining your environments url:

• a static way: when you know your environments url 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 variables depending on the environments (see environments configuration chapters below):

• $GCP_REVIEW_ENVIRONMENT_SCHEME and$GCP_REVIEW_ENVIRONMENT_DOMAIN for the review environments,
• $GCP_INTEG_ENVIRONMENT_URL, $GCP_STAGING_ENVIRONMENT_URL and $GCP_PROD_ENVIRONMENT_URL for others.

To implement the dynamic way, your deployment script shall simply generate a environment_url.txt file, containing only the dynamically generated 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 $CI_ENVIRONMENT_URL.

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

Environments configuration

As seen above, the Google Cloud template may support up to 4 environments (review, integration, staging and production).

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 disabled by default and can be enabled by setting the GCP_REVIEW_PROJECT variable (see below).

Here are variables supported to configure review environments:

Note: If you're managing your environment URLs statically, review environment URLs will be built as ${AWS_REVIEW_ENVIRONMENT_SCHEME}://${$CI_PROJECT_NAME}-${CI_ENVIRONMENT_SLUG}.${AWS_REVIEW_ENVIRONMENT_DOMAIN}

Integration environment

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:

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

Production environment

The production environment is the final deployment environment associated with your production branch (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:

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:
  # Include Google Cloud template
  - project: 'to-be-continuous/gcloud'
    ref: '1.6.2'
    file: '/templates/gitlab-ci-gcloud.yml'
  ...

# Global variables
variables:
  ...

  # Google Cloud
  # GCP_KEY_FILE defined as secret CI/CD variable
  GCP_REVIEW_PROJECT: "farm-12345" # enable review env
  GCP_STAGING_PROJECT: "farm-12345" # enable staging env
  GCP_PROD_PROJECT: "farm-12345" # enable production env
  GCP_STAGING_ENVIRONMENT_URL: "https://staging-dot-coockedoodledoo-dot-farmvoices-12345.ew.r.appspot.com"
  GCP_PROD_ENVIRONMENT_URL: "https://coockedoodledoo-dot-farmvoices-12345.ew.r.appspot.com"

  # Postman
  REVIEW_ENABLED: "true"

# Pipeline steps
stages:
  - build
  - test
  - deploy
  - acceptance
  - publish
  - production

# define 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.

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/gcloud'
    ref: '1.6.2'
    file: '/templates/gitlab-ci-gcloud.yml'
  # Vault variant
  - project: 'to-be-continuous/gcloud'
    ref: '1.6.2'
    file: '/templates/gitlab-ci-gcloud-vault.yml'

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"
    VAULT_BASE_URL: "https://vault.acme.host/v1"
    # $VAULT_ROLE_ID and $VAULT_SECRET_ID defined as a secret CI/CD variable