Using GitLab CI/CD Pipeline to Deploy AWS SAM Applications

In order to deliver serverless applications, customers often turn to DevOps principles to efficiently build, deploy, operate, and iterate on features and changes.

About AWS Serverless Application Model

A serverless application is comprised of multiple resources, which can include functions, event sources, datastores, and other resources that work together to perform tasks.

Serverless applications are more than just AWS Lambda functions—they can include additional resources, such as APIs, databases, and event source mappings.

AWS Serverless Application Model is an open source framework for building serverless applications. SAM includes the AWS SAM Template Specification and AWS SAM Command Line Interface (CLI).

The AWS SAM Template Specification is an extension of AWS CloudFormation used to define your serverless application resources as a template. It provides a more convenient and concise syntax to express functions, APIs, databases, and event source mapping when compared to typical CloudFormation template.

The CLI enables you to build, test, and deploy serverless applications that are defined using a SAM template.

Getting Started

To get started, ensure you have your own GitLab account and AWS account. This post assumes you have required permissions to configure Gitlab CI/CD pipelines and create AWS resources in your account.

We will create a sample serverless application using the SAM CLI and deploy it to an AWS account using GitLab CI/CD pipeline. We’ll use GitLab as the repository for our source code.

When a developer checks in their new code, the GitLab continuous integration fetches the source code from the repository, and then build, package, and deploy to the AWS account.

These are the steps in this procedure:

Install and configure the SAM CLI.
Create an AWS serverless application using SAM CLI.
Craft the .gitlab-ci.yml file.
Set up your AWS credentials in your GitLab account.
Test locally.
Deploy your application.
Test your deployment.

Step 1: Install and Configure the SAM CLI

Some steps in this documentation use the SAM CLI. Please follow the instructions on installing SAM CLI.

If you use AWS Cloud9 as your integrated development environment (IDE), the AWS Command Line Interface (CLI), SAM CLI, Docker, and necessary Docker images are installed for you.

Create an Amazon Simple Storage Service (Amazon S3) bucket in your AWS account to store the built package for deployment. Provide required permissions to the user you will be using in later steps to deploy the SAM application to write to this bucket.

Step 2: Creating an AWS SAM Application Using SAM CLI

You can create a serverless application by defining all required resources in an AWS SAM template. AWS SAM also provides some quick-start templates to create an application. In this post, we’ll use one of those templates to create a sample application.

Before you create a SAM application, create a new GitLab project and clone it to your local environment. To create a SAM app from the CLI, open a terminal, change to the newly cloned project, and enter the following text:

sam init -r python3.8 -n gitlab-example --app-template "hello-world"

This creates a SAM app named gitlab-example using the default configuration, a single Python 3.8 function invoked by an Amazon API Gateway endpoint.

To see additional runtimes supported by SAM and options for sam init, enter sam init -h.

Git push the application back to the GitLab project.

Step 3: Crafting the .gitlab-ci.yml File

GitLab CI/CD pipelines are configured using a YAML file called .gitlab-ci.yml within each project. This defines the structure and order of the pipelines.

In a .gitlab-ci.yml file in the root of your project, place the following code and replace the #S3Bucket# with the Amazon S3 bucket name you created to store the package:

image: python:3.8

stages:
  - deploy

production:
  stage: deploy
  before_script:
    - pip3 install awscli --upgrade
    - pip3 install aws-sam-cli --upgrade
  script:
    - sam build
    - sam package --output-template-file packaged.yaml --s3-bucket #S3Bucket#
    - sam deploy --template-file packaged.yaml --stack-name gitlab-example --s3-bucket #S3Bucket# --capabilities CAPABILITY_IAM --region us-east-1
  environment: production

Let’s examine the config file more closely:

The Docker image to use for this build is specified and pulled from the Docker hub. The image with Python 3.8 is used in this example since the sample application is written in Python 3.8.
AWS Command Line Interface and AWS SAM CLI are installed in the script section.
SAM builds, packages, and deploys the application.

As part of the CI/CD process, we recommend you scan your code for quality and vulnerabilities in bundled libraries. You can find these security offerings from our AWS Lambda Technology Partners.

Step 4: Setting Up Your AWS Credentials with GitLab

To interact with your AWS account, the GitLab CI/CD pipelines require both AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY to be defined in your GitLab project settings. You can do this under Settings > CI/CD > Variables. For more information, please see this GitLab ReadMe.

The AWS credentials you provide must include AWS Identity and Access Management (IAM) policies that provision correct access control to AWS Lambda, Amazon API Gateway, AWS CloudFormation, and IAM resources.

Step 5: Testing Locally

SAM provides functionality to test your applications locally. As we mentioned earlier, you must have SAM CLI installed locally for you to test locally.

SAM provides a default event in events/event.json that includes a message body of {\"message\": \"hello world\"}. If you pass that event into the HelloWorldFunction, it should respond with the same body:

sam local invoke HelloWorldFunction -e events/event.json

Output should be:

{"message": "hello world"}

After you confirm the Lambda function is working as expected, you can test the API Gateway using the following steps.

First start the API locally:

sam local start-api

SAM again launches a Docker container, this time with a mocked API Gateway listening on localhost:3000. Now, you can call the hello API as follows:

curl http://127.0.0.1:3000/hello

Output again should be:

{"message": "hello world"}

Step 6: Deploying Your Application

Git push the changes to your GitLab repository, and the GitLab pipeline will automatically deploy your application. If your build and deploy are successful, go to the next step to test your deployed application.

If your build fails, please take a look at the build log to see why it failed. Some common reasons are:

Incompatible versions of software (for example, the Python runtime version may be different from the Python on the build machine). Address this by installing the proper versions of the software. If your build machine has an incompatible version of the software, install the proper version via the .gitlab-ci.yml file.
You may not be able to access your AWS account from GitLab. Check the environment variables you configured with AWS credentials under the CI/CD settings in GitLab.
You may not have permission to deploy a serverless application. Make sure you provide all required permissions to deploy a serverless application. Your credentials must have permissions to the S3 bucket, in addition to being able to create the necessary resources of the sample SAM app.

Step 7: Testing Your Application

To test the application you deployed, go to the build log and click on Show Complete Raw in the upper right corner.

Look for the HelloWorldApi – API Gateway endpoint similar to shown below.

Finally, use curl to test the API:

curl https://<api-id>.execute-api.us-east-1.amazonaws.com/Prod/hello/

Output should be:

{"message": "hello world"}

Conclusion

In this post, you used GitLab continuous integration and AWS Serverless Application Model to create, build, test, and deploy a serverless application. With GitLab, users can build and deploy serverless applications with minimal configuration to take advantage of continuous integration for serverless application development.

Learn more about GitLab and AWS Serverless Application Model (SAM).

.

.

GitLab – APN Partner Spotlight

GitLab is an AWS DevOps Competency Partner. Its continuous integration offering provides a rich set of features for automating how new code is incorporated into your software and how new versions of your software get built and deployed.

Contact GitLab | Solution Overview | AWS Marketplace

*Already worked with GitLab? Rate this Partner

*To review an APN Partner, you must be an AWS customer that has worked with them directly on a project.

This complimentary resource is offered by GitLab, an AWS Community Partner. This content first appeared here.