If you are using Serverless Framework, it already has a built-in preview deployment feature with Serverless CI. You can read A Guide to Preview Deployments with Serverless CI/CD for more information.
Serverless CI supports GitHub and Bitbucket out of the box and you can manage it from Serverless Dashboard by going to your project's CI/CD settings.
In this post, you will be reading about how to implement preview deployments by using GitLab CI/CD. The setup may change depending on your requirements so this will be just a simple example regarding how to achieve this integration. I will assume that you have a basic understanding of GitLab's CI Jobs.
serverless.yml initial setup
We will be using custom domain manager plugin serverless-domain-manager to build our preview domains as well as staging and production domains.
yarn add serverless-domain-manager or npm i serverless-domain-manager
# serverless.yml
org: myorg
service: my-service
app: my-service
plugins:
- serverless-domain-manager
provider:
name: aws
stage: ${opt:stage, 'local'}
region: ${opt:region, 'eu-central-1'}
endpointType: REGIONAL
environment:
STAGE: ${sls:stage, 'local'}
Adding custom domain settings
We will have four targets for the type of domain names. production, staging, preview and local. Each preview deployment will be a different stage and you will be seeing them like this on Serverless Dashboard:
The domains will be created in these formats regarding their stages:
Domain target: production.
Stage: production.
Domain: production-api.myapp.org.
Domain target: staging.
Stage staging.
Domain: staging-api.myapp.org
Domain target: preview.
Stage preview-1.
Domain preview-1-api.myapp.org.
(1 is your merge request ID coming from GitLab's predefined variables)
Addition:
custom:
domains:
production: production-api.myapp.org
staging: staging-api.myapp.org
preview: "preview-${env:CI_MERGE_REQUEST_IID, ''}-api.myapp.org"
local: localhost
customDomain:
domainName: ${self:custom.domains.${env:DOMAIN_TARGET_TYPE, 'local'}}
basePath: ""
stage: ${sls:stage, 'local'}
createRoute53Record: true
If you would like to have multi-regions, you can expand customDomain with these options:
customDomain:
# ...
endpointType: "regional"
certificateRegion: ${opt:region, 'eu-central-1'}
route53Params:
routingPolicy: latency
.gitlab-ci setup
Now we have our serverless.yml ready (assuming that you have completed the rest of settings for your needs such as functions, etc.), we can start building our GitLab CI/CD file.
We will create a .gitlab-ci file and add a deploy stage. When a merge request is created, we will automatically deploy our preview deployment eu_preview_deployment with two main commands:
DOMAIN_TARGET_TYPE=preview serverless create_domain --stage preview-${CI_MERGE_REQUEST_IID} --region eu-central-1
and
DOMAIN_TARGET_TYPE=preview serverless deploy --stage preview-${CI_MERGE_REQUEST_IID} --region eu-central-1
Domain target type is retrieved from environment variables as you can see. The first one creates the domain, the second one deploys the application. Here, you can give any name to your stages. It doesn't have to start with preview.
After our merge request is closed or merged, we will be calling our job stop_eu_preview_deployment which is referred by eu_preview_deployment in environment.on_stop: stop_eu_preview_deployment. Both of the jobs must be in the same environment.
The stopping job will call two commands:
DOMAIN_TARGET_TYPE=preview serverless delete_domain --stage preview-${CI_MERGE_REQUEST_IID} --region eu-central-1
and
DOMAIN_TARGET_TYPE=preview serverless remove --stage preview-${CI_MERGE_REQUEST_IID} --region eu-central-1
The first one will remove the custom domain, and the second one will remove the preview deployment.
image: node:14-alpine
.install_serverless: &install-serverless
before_script:
- yarn global add serverless --prefix /usr/local
stages:
- deploy
eu_preview_deployment:
<<: *install-serverless
stage: deploy
script:
- DOMAIN_TARGET_TYPE=preview serverless create_domain --stage preview-${CI_MERGE_REQUEST_IID} --region eu-central-1
- DOMAIN_TARGET_TYPE=preview serverless deploy --stage preview-${CI_MERGE_REQUEST_IID} --region eu-central-1
environment:
on_stop: stop_eu_preview_deployment
name: development
url: https://preview-${CI_MERGE_REQUEST_IID}-api.myapp.org
only:
- merge_requests
stop_eu_preview_deployment:
<<: *install-serverless
stage: deploy
variables:
GIT_STRATEGY: none
when: manual
script:
- DOMAIN_TARGET_TYPE=preview serverless delete_domain --stage preview-${CI_MERGE_REQUEST_IID} --region eu-central-1
- DOMAIN_TARGET_TYPE=preview serverless remove --stage preview-${CI_MERGE_REQUEST_IID} --region eu-central-1
environment:
name: development
action: stop
only:
- merge_requests
That's it... Now you have a preview deployment setup.
As an example, I will add staging and production deployment setups for .gitlab-ci.yml:
deploy_to_staging_eu:
<<: *install-serverless
only:
- staging
stage: deploy
script:
- DOMAIN_TARGET_TYPE=staging serverless create_domain --stage staging --region us-east-1
- DOMAIN_TARGET_TYPE=staging serverless deploy --stage staging --region us-east-1
environment:
name: development
url: https://staging-api.myapp.org
only:
- branches
- merge_requests
deploy_to_production_eu:
<<: *install-serverless
only:
- master
stage: deploy
script:
- DOMAIN_TARGET_TYPE=production serverless create_domain --stage production --region eu-central-1
- DOMAIN_TARGET_TYPE=production serverless deploy --stage production --region eu-central-1
environment:
name: production
url: https://production-api.myapp.org
You can change the rules of the setup regarding your needs. You can read more about .gitlab-ci.yml keyword references here. You can also change the stages and everything as you wish.
I hope this small tutorial will give you an idea regarding preview deployments on GitLab. Let me know if you have a better approach. :)
Top comments (0)