Skip to content

GitLab CI template for Amazon Web Services

This project implements a generic GitLab CI template for Amazon Web Services environments.

Overview: managed environments

This template implements continuous delivery/continuous deployment for projects hosted on AWS.

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/aws'
    ref: '1.0.2'
    file: '/templates/gitlab-ci-aws.yml'

Global configuration

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

Name description default value
AWS_CLI_IMAGE the Docker image used to run AWS CLI commands amazon/aws-cli:latest
AWS_BASE_APP_NAME Base application name $CI_PROJECT_NAME (see GitLab doc)
AWS_SCRIPTS_DIR Directory where AWS scripts (deploy & cleanup) are located . (root project dir)

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 scripts

The AWS template requires you to provide a shell script that fully implements your application deployment and cleanup using the aws CLI and all other tools available in the selected Docker image.

Lookup policy

The deployment script is searched as follows:

  1. look for a specific aws-deploy-$env.sh in the $AWS_SCRIPTS_DIR directory in your project (e.g. aws-deploy-staging.sh for staging environment),
  2. if not found: look for a default aws-deploy.sh in the $AWS_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 aws-cleanup-$env.sh in the $AWS_SCRIPTS_DIR directory in your project (e.g. aws-cleanup-staging.sh for staging environment),
  2. if not found: look for a default aws-cleanup.sh in the $AWS_SCRIPTS_DIR directory in your project,
  3. if not found: the cleanup job will fail.

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)

AWS authentication

The AWS template does not manage AWS authentication.

That means you'll have to manage AWS authentication by yourself, according to the aws CLI configuration options (configuration file, CLI options, environment variables).

For credentials management, we strongly advise to use environment variables configuration, managed as GitLab CI secret variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, possibly AWS_ROLE_ARN).

If you have to manage different set of authentication credentials depending on managed environments, you shall either use GitLab scoped variables or our scoped variables syntax to limit/override some variables values, using $CI_ENVIRONMENT_NAME as the conditional variable.

Example: different credentials for production (declared as project variables)

# global AWS credentials
AWS_ACCESS_KEY_ID: "<my-nonprod-access-key-id>"
AWS_SECRET_ACCESS_KEY: "<my-nonprod-secret-access-key>"

# overridden configuration for production
scoped__AWS_ACCESS_KEY_ID__if__CI_ENVIRONMENT_NAME__equals__production: "<my-prod-access-key-id>"
scoped__AWS_SECRET_ACCESS_KEY__if__CI_ENVIRONMENT_NAME__equals__production: "<my-prod-secret-access-key>"

Static vs. Dynamic environment URLs

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

  • $AWS_REVIEW_ENVIRONMENT_SCHEME and$AWS_REVIEW_ENVIRONMENT_DOMAIN for the review environments,
  • $AWS_INTEG_ENVIRONMENT_URL, $AWS_STAGING_ENVIRONMENT_URL and $AWS_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 AWS template may support up to 4 predefined 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 AWS_REVIEW_ENABLED variable (see below).

Here are variables supported to configure review environments:

Name description default value
AWS_REVIEW_ENABLED AWS project ID for review env none (disabled)
AWS_REVIEW_APP_NAME Application name for review env "${AWS_BASE_APP_NAME}-${CI_ENVIRONMENT_SLUG}" (ex: myproject-review-fix-bug-12)
AWS_REVIEW_ENVIRONMENT_SCHEME The review environment protocol scheme.
For static environment URLs declaration
https
AWS_REVIEW_ENVIRONMENT_DOMAIN The review environment domain.
For static environment URLs declaration
none

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 AWS_INTEG_ENABLED variable (see below).

Here are variables supported to configure the integration environment:

Name description default value
AWS_INTEG_ENABLED AWS project ID for integration env none (disabled)
AWS_INTEG_APP_NAME Application name for integration env ${AWS_BASE_APP_NAME}-integration
 AWS_INTEG_ENVIRONMENT_URL The integration environment url (ex: https://my-application-integration.compute-1.amazonaws.com).
For static environment URLs declaration
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 disabled by default and can be enabled by setting the AWS_STAGING_ENABLED variable (see below).

Here are variables supported to configure the staging environment:

Name description default value
AWS_STAGING_ENABLED AWS project ID for staging env none (disabled)
AWS_STAGING_APP_NAME Application name for staging env ${AWS_BASE_APP_NAME}-staging
 AWS_STAGING_ENVIRONMENT_URL The staging environment url (ex: https://my-application-staging.compute-1.amazonaws.com).
For static environment URLs declaration
none

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 AWS_PROD_ENABLED variable (see below).

Here are variables supported to configure the production environment:

Name description default value
AWS_PROD_ENABLED AWS project ID for production env none (disabled)
AWS_PROD_APP_NAME Application name for production env $AWS_BASE_APP_NAME
AWS_PROD_ENVIRONMENT_URL  The production environment url (ex: https://my-application.compute-1.amazonaws.com).
For static environment URLs declaration
none
AUTODEPLOY_TO_PROD Set this variable to auto-deploy to production. If not set deployment to production will be manual (default behaviour). none (disabled)

Examples

AWS CloudFormation stack

This chapter gives some implementation hints to implement continuous deployment based on AWS CloudFormation.

It enables review, staging and production environments.

.gitlab-ci.yml

include:
  # Include AWS template
  - project: 'to-be-continuous/aws'
    ref: '1.0.2'
    file: '/templates/gitlab-ci-aws.yml'
  ...

# Global variables
variables:
  # AWS
  # AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY defined as secret CI/CD variable
  AWS_REVIEW_ENABLED: "true" # enable review env
  AWS_STAGING_ENABLED: "true" # enable staging env
  AWS_PROD_ENABLED: "true" # enable production env
  ...

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

AWS scripts

aws-deploy.sh

This script is executed by the template to perform the application(s) deployment based on aws CLI, and uses dynamic variables provided by the template (${appname} is used as the CloudFormation stack name).

It implements dynamic environment URLs, by generating the environment_url.txt file, containing the dynamically generated url at the end of the deployment script.

#!/usr/bin/env bash
set -e # fail on error

echo "[aws-deploy] Deploying $appname..."

# disable AWS CLI pager
export AWS_PAGER=""

template_file=file://MyStack.template
# retrieve environment type ($env) from template
# retrieve $AWS_KEYPAIR_NAME from project secret variables
params_opts="--parameters ParameterKey=EnvType,ParameterValue=$env ParameterKey=KeyName,ParameterValue=$AWS_KEYPAIR_NAME"

if aws cloudformation describe-stacks --output text --stack-name "$appname" > /dev/null
then
  echo -e "Stack exists: update..."
  aws cloudformation update-stack --output text --stack-name "$appname" --template-body $template_file $parameters

  echo "Waiting for stack to be updated..."
  aws cloudformation wait stack-update-complete --stack-name "$appname"
else
  echo -e "Stack doesn't exist: create..."
  aws cloudformation create-stack --output text --stack-name "$appname" --template-body $template_file $parameters

  echo "Waiting for stack to be created..."
  aws cloudformation wait stack-create-complete --stack-name "$appname"
fi

# Retrieve outputs (use cloudformation query)
webserver_url=$(aws cloudformation describe-stacks --output text --stack-name "$appname" --query 'Stacks[0].Outputs[?OutputKey==`WebServerUrl`].OutputValue')

echo "Stack created/updated:"
echo " - WebServerUrl: $webserver_url"

# Finally set the dynamically generated WebServer Url
echo "$webserver_url" > environment_url.txt
aws-cleanup.sh

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

#!/usr/bin/env bash
set -e # fail on error

echo "[aws-cleanup] Cleanup $appname..."

# disable AWS CLI pager
export AWS_PAGER=""

aws cloudformation delete-stack --stack-name "$appname"

AWS Serverless

This chapter gives some implementation hints to implement continuous deployment of a Serverless application based on Serverless Application Model.

It enables review, staging and production environments.

.gitlab-ci.yml

include:
  # Include AWS template
  - project: 'to-be-continuous/aws'
    ref: '1.0.2'
    file: '/templates/gitlab-ci-aws.yml'
  ...

# Global variables
variables:
  # AWS
  # use an image with both aws and sam CLI
  AWS_CLI_IMAGE: "pahud/aws-sam-cli:latest"
  # AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY defined as secret CI/CD variable
  AWS_REVIEW_ENABLED: "true" # enable review env
  AWS_STAGING_ENABLED: "true" # enable staging env
  AWS_PROD_ENABLED: "true" # enable production env
  ...

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

AWS scripts

aws-deploy.sh

This script is executed by the template to perform the application(s) deployment based on samand aws CLI, and uses dynamic variables provided by the template (${appname} is used as the SAM/CloudFormation stack name).

It implements dynamic environment URLs, by generating the environment_url.txt file, containing the dynamically generated url at the end of the deployment script.

#!/usr/bin/env bash
set -e # fail on error

echo "[aws-deploy] Deploy $appname..."

# disable AWS CLI pager
export AWS_PAGER=""

# 1: build
sam build ${TRACE+--debug}

# 2: deploy (each environment is a separate stack)
# AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY defined as secret CI/CD variable
# AWS_DEFAULT_REGION and AWS_SAM_BUCKET defined as project CI/CD variable
sam deploy ${TRACE+--debug} \
  --stack-name "$appname" \
  --region "$AWS_DEFAULT_REGION" \
  --s3-bucket "$AWS_SAM_BUCKET" \
  --no-fail-on-empty-changeset \
  --no-confirm-changeset \
  --tags "ci-job-url=$CI_JOB_URL environment=$env"

# Retrieve outputs (use cloudformation query)
api_url=$(aws cloudformation describe-stacks --stack-name "$appname" --output text --query 'Stacks[0].Outputs[?OutputKey==`MyProjectApiUrl`].OutputValue')

echo "Stack created/updated:"
echo " - Api URL: $api_url"

# Finally set the dynamically generated WebServer Url
echo "$api_url" > environment_url.txt
aws-cleanup.sh

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

#!/usr/bin/env bash
set -e # fail on error

echo "[aws-cleanup] Cleanup $appname..."

# disable AWS CLI pager
export AWS_PAGER=""

aws cloudformation delete-stack --stack-name "$appname"