# Using CI/CD systems and pipelines to deploy with AWS SAM AWS SAM helps organizations create pipelines for their preferred CI/CD systems, so that they can realize the benefits of CI/CD with minimal effort, such as accelerating deployment frequency, shortening lead time for changes, and reducing deployment errors. AWS SAM simplifies CI/CD tasks for serverless applications with the help of build container images. The images that AWS SAM provides include the AWS SAM CLI and build tools for a number of supported AWS Lambda runtimes. This makes it easier to build and package serverless applications using the AWS SAM CLI. These images also alleviate the need for teams to create and manage their own images for CI/CD systems. For more information about AWS SAM build container images, see [Image repositories for AWS SAM](serverless-image-repositories.md). Multiple CI/CD systems support AWS SAM build container images. Which CI/CD system you should use depends on several factors. These include whether your application uses a single runtime or multiple runtimes, or whether you want to build your application within a container image or directly on a host machine, either a virtual machine (VM) or bare metal host. AWS SAM also provides a set of default pipeline templates for multiple CI/CD systems that encapsulate AWS's deployment best practices. These default pipeline templates use standard JSON/YAML pipeline configuration formats, and the built-in best practices help perform multi-account and multi-region deployments, and verify that pipelines cannot make unintended changes to infrastructure. You have two main options for using AWS SAM to deploy your serverless applications: 1) Modify your existing pipeline configuration to use AWS SAM CLI commands, or 2) Generate an example CI/CD pipeline configuration that you can use as a starting point for your own application. **Topics** + [What is a pipeline?](#deploying-whatis-pipeline) + [How AWS SAM uploads local files at deployment](deploy-upload-local-files.md) + [Generate a starter CI/CD pipeline with AWS SAM](serverless-generating-example-ci-cd.md) + [How to customize starter pipelines with AWS SAM](serverless-customizing-starter-pipelines.md) + [Automate the deployment of your AWS SAM application](serverless-deploying-modify-pipeline.md) + [How to use OIDC authentication with AWS SAM pipelines](deploying-with-oidc.md) ## What is a pipeline? A pipeline is an automated sequence of steps that are performed to release a new version of an application. With AWS SAM, you can use many common CI/CD systems to deploy your applications, including [AWS CodePipeline](https://aws.amazon.com/codepipeline), [Jenkins](https://www.jenkins.io/), [GitLab CI/CD](https://docs.gitlab.com/ee/ci/), and [GitHub Actions](https://github.com/features/actions). Pipeline templates include AWS deployment best practices to help with multi-account and multi-Region deployments. AWS environments such as dev and production typically exist in different AWS accounts. This allows development teams to configure safe deployment pipelines, without making unintended changes to infrastructure. You can also supply your own custom pipeline templates to help to standardize pipelines across development teams. # How AWS SAM uploads local files at deployment When you deploy your application to the AWS Cloud, AWS CloudFormation requires that your local files are first uploaded to an accessible AWS service, such as Amazon Simple Storage Service (Amazon S3). This includes local files your AWS SAM template references. To meet this requirement, the AWS SAM CLI does the following when you use the `sam deploy` or `sam package` command: 1. Automatically uploads your local files to an accessible AWS service. 1. Automatically updates your application template to reference the new file path. **Topics** + [Demo: Use the AWS SAM CLI to upload Lambda function code](#deploy-upload-local-files-demo) + [Supported use cases](#deploy-upload-local-files-use) + [Learn more](#deploy-upload-local-files-learn) ## Demo: Use the AWS SAM CLI to upload Lambda function code In this demo, we initialize the sample Hello World application using a .zip package type for our Lambda function. We use the AWS SAM CLI to automatically upload our Lambda function code to Amazon S3 and reference its new path in our application template. First, we run `sam init` to initialize our Hello World application. ``` $ sam init ... Which template source would you like to use? 1 - AWS Quick Start Templates 2 - Custom Template Location Choice: 1 Choose an AWS Quick Start application template 1 - Hello World Example 2 - Multi-step workflow ... Template: 1 Use the most popular runtime and package type? (Python and zip) [y/N]: y Would you like to enable X-Ray tracing on the function(s) in your application? [y/N]: ENTER Would you like to enable monitoring using CloudWatch Application Insights? For more info, please view https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/cloudwatch-application-insights.html [y/N]: ENTER Project name [sam-app]: demo ----------------------- Generating application: ----------------------- Name: demo Runtime: python3.9 Architectures: x86_64 Dependency Manager: pip Application Template: hello-world Output Directory: . Configuration file: demo/samconfig.toml ... ``` Our Lambda function code is organized in the `hello_world` subdirectory of our project. ``` demo ├── README.md ├── hello_world │ ├── __init__.py │ ├── app.py │ └── requirements.txt ├── template.yaml └── tests ``` Within our AWS SAM template, we reference the local path to our Lambda function code using the `CodeUri` property. ``` AWSTemplateFormatVersion: '2010-09-09' Transform: AWS::Serverless-2016-10-31 ... Resources: HelloWorldFunction: Type: AWS::Serverless::Function # More info about Function Resource: https://github.com/awslabs/serverless-application-model/blob/master/versions/2016-10-31.md#awsserverlessfunction Properties: CodeUri: hello_world/ Handler: app.lambda_handler Runtime: python3.9 ... ``` Next, we run `sam build` to build our application and prepare for deployment. ``` $ sam build Starting Build use cache Manifest file is changed (new hash: 3298f13049d19cffaa37ca931dd4d421) or dependency folder (.aws-sam/deps/7896875f-9bcc-4350-8adb-2c1d543627a1) is missing for (HelloWorldFunction), downloading dependencies and copying/building source Building codeuri: /Users/.../demo/hello_world runtime: python3.9 metadata: {} architecture: x86_64 functions: HelloWorldFunction Running PythonPipBuilder:CleanUp Running PythonPipBuilder:ResolveDependencies Running PythonPipBuilder:CopySource Running PythonPipBuilder:CopySource Build Succeeded Built Artifacts : .aws-sam/build Built Template : .aws-sam/build/template.yaml ... ``` Next, we run `sam deploy --guided` to deploy our application. ``` $ sam deploy --guided Configuring SAM deploy ====================== Looking for config file [samconfig.toml] : Found Reading default arguments : Success Setting default arguments for 'sam deploy' ========================================= Stack Name [demo]: ENTER AWS Region [us-west-2]: ENTER #Shows you resources changes to be deployed and require a 'Y' to initiate deploy Confirm changes before deploy [Y/n]: n #SAM needs permission to be able to create roles to connect to the resources in your template Allow SAM CLI IAM role creation [Y/n]: ENTER #Preserves the state of previously provisioned resources when an operation fails Disable rollback [y/N]: ENTER HelloWorldFunction may not have authorization defined, Is this okay? [y/N]: y Save arguments to configuration file [Y/n]: ENTER SAM configuration file [samconfig.toml]: ENTER SAM configuration environment [default]: ENTER Looking for resources needed for deployment: ... Saved arguments to config file Running 'sam deploy' for future deployments will use the parameters saved above. The above parameters can be changed by modifying samconfig.toml Learn more about samconfig.toml syntax at https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-config.html File with same data already exists at demo/da3c598813f1c2151579b73ad788cac8, skipping upload Deploying with following values =============================== Stack name : demo Region : us-west-2 Confirm changeset : False Disable rollback : False Deployment s3 bucket : aws-sam-cli-managed-default-samclisam-s3-demo-bucket-1a4x26zbcdkqr Capabilities : ["CAPABILITY_IAM"] Parameter overrides : {} Signing Profiles : {} Initiating deployment ===================== ... Waiting for changeset to be created.. CloudFormation stack changeset ------------------------------------------------------------------------------------------------- Operation LogicalResourceId ResourceType Replacement ------------------------------------------------------------------------------------------------- + Add HelloWorldFunctionHell AWS::Lambda::Permissio N/A oWorldPermissionProd n + Add HelloWorldFunctionRole AWS::IAM::Role N/A ... ------------------------------------------------------------------------------------------------- Changeset created successfully. arn:aws:cloudformation:us-west-2:012345678910:changeSet/samcli-deploy1680906292/1164338d-72e7-4593-a372-f2b3e67f542f 2023-04-07 12:24:58 - Waiting for stack create/update to complete CloudFormation events from stack operations (refresh every 5.0 seconds) ------------------------------------------------------------------------------------------------- ResourceStatus ResourceType LogicalResourceId ResourceStatusReason ------------------------------------------------------------------------------------------------- CREATE_IN_PROGRESS AWS::IAM::Role HelloWorldFunctionRole - CREATE_IN_PROGRESS AWS::IAM::Role HelloWorldFunctionRole Resource creation Initiated ... ------------------------------------------------------------------------------------------------- CloudFormation outputs from deployed stack ------------------------------------------------------------------------------------------------- Outputs ------------------------------------------------------------------------------------------------- Key HelloWorldFunctionIamRole Description Implicit IAM Role created for Hello World function Value arn:aws:iam::012345678910:role/demo-HelloWorldFunctionRole-VQ4CU7UY7S2K Key HelloWorldApi Description API Gateway endpoint URL for Prod stage for Hello World function Value https://satnon55e9.execute-api.us-west-2.amazonaws.com/Prod/hello/ Key HelloWorldFunction Description Hello World Lambda Function ARN Value arn:aws:lambda:us-west-2:012345678910:function:demo- HelloWorldFunction-G14inKTmSQvK ------------------------------------------------------------------------------------------------- Successfully created/updated stack - demo in us-west-2 ``` During deployment, the AWS SAM CLI automatically uploads our Lambda function code to Amazon S3 and updates our template. Our modified template in the CloudFormation console reflects the Amazon S3 bucket path. ``` AWSTemplateFormatVersion: '2010-09-09' Transform: AWS::Serverless-2016-10-31 ... Resources: HelloWorldFunction: Type: AWS::Serverless::Function Properties: CodeUri: s3://aws-sam-cli-managed-default-samclisam-s3-demo-bucket-1a4x26zbcdkqr/demo/da3c598813f1c2151579b73ad788cac8 Handler: app.lambda_handler ... ``` ## Supported use cases The AWS SAM CLI can automatically facilitate this process for a number of file types, CloudFormation resource types, and CloudFormation macros. ### File types Application files and Docker images are supported. ### CloudFormation resource types The following is a list of the supported resource types and their properties: | Resource | Properties | | --- | --- | | AWS::ApiGateway::RestApi | BodyS3Location | | AWS::ApiGatewayV2::Api | BodyS3Location | | AWS::AppSync:FunctionConfiguration | `CodeS3Location` `RequestMappingTemplateS3Location` `ResponseMappingTemplateS3Location` | | AWS::AppSync::GraphQLSchema | DefinitionS3Location | | AWS::AppSync::Resolver | `CodeS3Location` `RequestMappingTemplateS3Location` `ResponseMappingTemplateS3Location` | | AWS::CloudFormation::ModuleVersion | ModulePackage | | AWS::CloudFormation::ResourceVersion | SchemaHandlerPackage | | AWS::ECR::Repository | RepositoryName | | AWS::ElasticBeanstalk::ApplicationVersion | SourceBundle | | AWS::Glue::Job | Command.ScriptLocation | | AWS::Lambda::Function | `Code` `Code.ImageUri` | | AWS::Lambda::LayerVersion | Content | | AWS::Serverless::Api | DefinitionUri | | AWS::Serverless::Function | `CodeUri` `ImageUri` | | AWS::Serverless::GraphQLApi | `SchemaUri` `Function.CodeUri` `Resolver.CodeUri` | | AWS::Serverless::HttpApi | DefinitionUri | | AWS::Serverless::LayerVersion | ContentUri | | AWS::Serverless::StateMachine | DefinitionUri | | AWS::StepFunctions::StateMachine | DefinitionS3Location | ### CloudFormation macros Files referenced using the `AWS::Include` transform macro are supported. ## Learn more To learn more about the `AWS::Include` transform, see [ AWS::Include transform](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/create-reusable-transform-function-snippets-and-add-to-your-template-with-aws-include-transform.html) in the *AWS CloudFormation User Guide*. To see an example of using the `AWS::Include` transform in an AWS SAM template, see the [API Gateway HTTP API to SQS](https://serverlessland.com/patterns/apigw-sqs) pattern at * Serverless Land*. # Generate a starter CI/CD pipeline with AWS SAM When you are ready automate deployment, you can use one of AWS SAM’s starter pipeline templates to generate a deployment pipeline for the CI/CD system you choose to use. Your deployment pipeline is what you configure and use to automate the deployment of your serverless application. A starter pipeline template is pre-configured to help you quickly set up your deployment pipeline for your serverless application. With a starter pipeline template, you can generate pipelines in minutes using the [sam pipeline init](sam-cli-command-reference-sam-pipeline-init.md) command. The starter pipeline templates use the familiar JSON/YAML syntax of the CI/CD system, and incorporate best practices such as managing artifacts across multiple accounts and regions, and using the minimum amount of permissions required to deploy the application. Currently, the AWS SAM CLI supports generating starter CI/CD pipeline configurations for [AWS CodePipeline](https://aws.amazon.com/codepipeline), [Jenkins](https://www.jenkins.io/), [GitLab CI/CD](https://docs.gitlab.com/ee/ci/), [GitHub Actions](https://github.com/features/actions), and [Bitbucket Pipelines](https://support.atlassian.com/bitbucket-cloud/docs/get-started-with-bitbucket-pipelines/). Here are the high-level tasks you need to perform to generate a starter pipeline configuration: 1. **Create infrastructure resources** – Your pipeline requires certain AWS resources, for example the IAM user and roles with necessary permissions, an Amazon S3 bucket, and optionally an Amazon ECR repository. 1. **Connect your Git repository with your CI/CD system** – Your CI/CD system needs to know which Git repository will trigger the pipeline to run. Note that this step may not be necessary, depending on which combination of Git repository and CI/CD system you are using. 1. **Generate your pipeline configuration** – This step generates a starter pipeline configuration that includes two deployment stages. 1. **Commit your pipeline configuration to your Git repository** – This step is necessary to ensure your CI/CD system is aware of your pipeline configuration, and will run when changes are committed. After you've generated the starter pipeline configuration and committed it to your Git repository, whenever someone commits a code change to that repository your pipeline will be triggered to run automatically. The ordering of these steps, and details of each step, vary based on your CI/CD system: + If you are using AWS CodePipeline, see [Generating starter pipeline for AWS CodePipeline in AWS SAM](serverless-generating-example-ci-cd-codepipeline.md). + If you are using Jenkins, GitLab CI/CD, GitHub Actions, or Bitbucket Pipelines, see [Use AWS SAM to generate starter pipelines for Jenkins, GitLab CI/CD, GitHub Actions, Bitbucket Pipelines](serverless-generating-example-ci-cd-others.md). # Generating starter pipeline for AWS CodePipeline in AWS SAM To generate a starter pipeline configuration for AWS CodePipeline, perform the following tasks in this order: 1. Create infrastructure resources 1. Generate the pipeline configuration 1. Commit your pipeline configuration to Git 1. Connect your Git repository with your CI/CD system **Note** The following procedure utilizes two AWS SAM CLI commands, `sam pipeline bootstrap` and `sam pipeline init`. The reason there are two commands is to handle the use case where administrators (that is, users who need permission to set up infrastructure AWS resource like IAM users and roles) have more permission that developers (that is, users who just need permission to set up individual pipelines, but not the required infrastructure AWS resources). ## Step 1: Create infrastructure resources Pipelines that use AWS SAM require certain AWS resources, like an IAM user and roles with necessary permissions, an Amazon S3 bucket, and optionally an Amazon ECR repository. You must have a set of infrastructure resources for each deployment stage of the pipeline. You can run the following command to help with this setup: ``` sam pipeline bootstrap ``` **Note** Run the previous command for each deployment stage of your pipeline. ## Step 2: Generate the pipeline configuration To generate the pipeline configuration, run the following command: ``` sam pipeline init ``` ## Step 3: Commit your pipeline configuration to Git repository This step is necessary to ensure your CI/CD system is aware of your pipeline configuration, and will run when changes are committed. ## Step 4: Connect your Git repository with your CI/CD system For AWS CodePipeline you can now create the connection by running the following command: ``` sam deploy -t codepipeline.yaml --stack-name --capabilities=CAPABILITY_IAM --region ``` If you are using GitHub or Bitbucket, after running the **sam deploy** command previously, complete the connection by following the steps under **To complete a connection** found on the [Update a pending connection](https://docs.aws.amazon.com/dtconsole/latest/userguide/connections-update.html) topic in the *Developer Tools console user guide*. In addition, store a copy of the `CodeStarConnectionArn` from the output of the **sam deploy** command, because you will need it if you want to use AWS CodePipeline with another branch than `main`. ## Configuring other branches By default, AWS CodePipeline uses the `main` branch with AWS SAM. If you want to use a branch other than `main`, you must run the **sam deploy** command again. Note that depending on which Git repository you are using, you may also need to provide the `CodeStarConnectionArn`: ``` # For GitHub and Bitbucket sam deploy -t codepipeline.yaml --stack-name --capabilities=CAPABILITY_IAM --parameter-overrides="FeatureGitBranch= CodeStarConnectionArn=" # For AWS CodeCommit sam deploy -t codepipeline.yaml --stack-name --capabilities=CAPABILITY_IAM --parameter-overrides="FeatureGitBranch=" ``` ## Learn more For a hands-on example of setting up a CI/CD pipeline, see [ CI/CD with AWS CodePipeline](https://catalog.workshops.aws/complete-aws-sam/en-US/module-4-cicd) in *The Complete AWS SAM Workshop*. # Use AWS SAM to generate starter pipelines for Jenkins, GitLab CI/CD, GitHub Actions, Bitbucket Pipelines To generate a starter pipeline configuration for Jenkins, GitLab CI/CD, GitHub Actions, or Bitbucket Pipelines perform the following tasks in this order: 1. Create infrastructure resources 1. Connect your Git repository with your CI/CD system 1. Create credential objects 1. Generate the pipeline configuration 1. Commit your pipeline configuration to Git repository **Note** The following procedure utilizes two AWS SAM CLI commands, `sam pipeline bootstrap` and `sam pipeline init`. The reason there are two commands is to handle the use case where administrators (that is, users who need permission to set up infrastructure AWS resource like IAM users and roles) have more permission that developers (that is, users who just need permission to set up individual pipelines, but not the required infrastructure AWS resources). ## Step 1: Create infrastructure resources Pipelines that use AWS SAM require certain AWS resources, like an IAM user and roles with necessary permissions, an Amazon S3 bucket, and optionally an Amazon ECR repository. You must have a set of infrastructure resources for each deployment stage of the pipeline. You can run the following command to help with this setup: ``` sam pipeline bootstrap ``` **Note** Run the previous command for each deployment stage of your pipeline. You must capture the AWS credentials (key id and secret key) for the pipeline users for each deployment stage of your pipeline, because they are needed for subsequent steps. ## Step 2: Connect your Git repository with your CI/CD system Connecting your Git repository to your CI/CD system is necessary so that the CI/CD system is able to access your application source code for builds and deployments. **Note** You can skip this step if you are using one of the following combinations, because the connection is done for you automatically: GitHub Actions with GitHub repository GitLab CI/CD with GitLab repository Bitbucket Pipelines with a Bitbucket repository To connect your Git repository with your CI/CD system, do one of the following: + If you're using Jenkins, see the [Jenkins documentation](https://www.jenkins.io/doc/book/pipeline/multibranch/) for "Adding a branch source." + If you're using GitLab CI/CD and a Git repository other than GitLab, see the [GitLab documentation](https://docs.gitlab.com/ee/ci/ci_cd_for_external_repos/) for "connecting an external repository." ## Step 3: Create credential objects Each CI/CD system has its own way of managing credentials needed for the CI/CD system to access your Git repository. To create the necessary credential objects, do one of the following: + If you're using Jenkins, create a single "credential" that stores both the key id and secret key. Follow the instructions in the [Building a Jenkins Pipeline with AWS SAM](https://aws.amazon.com/blogs/compute/building-a-jenkins-pipeline-with-aws-sam/) blog, in the **Configure Jenkins** section. You will need the "Credential id" for the next step. + If you're using GitLab CI/CD, create two "protected variables", one for each of key id and secret key. Follow the instructions in the [GitLab documentation](https://docs.gitlab.com/ee/ci/variables/) – you will need two "variable keys" for the next step. + If you're using GitHub Actions, create two "encrypted secrets", one for each of key and secret key. Follow the instructions in the [GitHub documentation](https://docs.github.com/en/actions/reference/encrypted-secrets) - you will need two "secret names" for the next step. + If you're using Bitbucket Pipelines, create two "secure variables", one for each of key id and secret key. Follow the instructions in the [Variables and secrets ](https://support.atlassian.com/bitbucket-cloud/docs/variables-and-secrets) - you will need two "secret names" for the next step. ## Step 4: Generate the pipeline configuration To generate the pipeline configuration, run the following command. You will need to input the credential object that you created in the previous step: ``` sam pipeline init ``` ## Step 5: Commit your pipeline configuration to Git repository This step is necessary to ensure your CI/CD system is aware of your pipeline configuration, and will run when changes are committed. ## Learn more For a hands-on example of setting up a CI/CD pipeline using GitHub Actions, see [CI/CD with GitHub](https://s12d.com/sam-ws-en-gh) in *The Complete AWS SAM Workshop*. # How to customize starter pipelines with AWS SAM As a CI/CD administrator, you may want to customize a starter pipeline template, and associated guided prompts, that developers in your organization can use to create pipeline configurations. The AWS SAM CLI uses Cookiecutter templates when creating starter templates. For details about cookie cutter templates, [Cookiecutter](https://cookiecutter.readthedocs.io/en/latest/README.html). You can also customize the prompts that the AWS SAM CLI displays to users when creating pipeline configurations using the `sam pipeline init` command. To customize user prompts, do the following: 1. **Create a `questions.json` file** – The `questions.json` file must be in the root of the project respository. This is the same directory as the `cookiecutter.json` file. To view the schema for the `questions.json` file, see [questions.json.schema](https://github.com/aws/aws-sam-cli/blob/2b831b29f76ac9c4e0cbcbd68b37f8f664e136d8/samcli/lib/pipeline/init/questions.json.schema). To view an example `questions.json` file, see [questions.json](https://github.com/aws/aws-sam-cli-pipeline-init-templates/blob/main/Jenkins/two-stage-pipeline-template/questions.json). 1. **Map question keys with cookiecutter names** – Each object in the `questions.json` file needs a key that matches a name in the cookiecutter template. This key matching is how the AWS SAM CLI maps user prompt responses to the cookie cutter template. To see examples of this key matching, see the [Example files](#serverless-customizing-starter-pipelines-example-files) section later in this topic. 1. **Create a `metadata.json` file** – Declare the number of stages the pipeline will have in the `metadata.json` file. The number of stages instructs the `sam pipeline init` command how many stages to prompt information about, or in the case of the `--bootstrap` option, how many stages to create infrastructure resources for. To view an example `metadata.json` file that declares a pipeline with two stages, see [metadata.json](https://github.com/aws/aws-sam-cli-pipeline-init-templates/blob/main/Jenkins/two-stage-pipeline-template/metadata.json). ## Example projects Here are example projects, which each include a Cookiecutter template, a `questions.json` file, and a `metadata.json` file: + Jenkins example: [Two-stage Jenkins pipeline template](https://github.com/aws/aws-sam-cli-pipeline-init-templates/tree/main/Jenkins/two-stage-pipeline-template) + CodePipeline example: [Two stage CodePipeline pipeline template](https://github.com/aws/aws-sam-cli-pipeline-init-templates/tree/main/AWS-CodePipeline/two-stage-pipeline-template) ## Example files The following set of files show how questions in the `questions.json` file are associated with entries in the Cookiecutter template file. Note that these examples are file snippets, not full files. To see examples of full files, see the [Example projects](#serverless-customizing-starter-pipelines-example-projects) section earlier in this topic. Example **`questions.json`**: ``` { "questions": [{ "key": "intro", "question": "\nThis template configures a pipeline that deploys a serverless application to a testing and a production stage.\n", "kind": "info" }, { "key": "pipeline_user_jenkins_credential_id", "question": "What is the Jenkins credential ID (via Jenkins plugin \"aws-credentials\") for pipeline user access key?", "isRequired": true }, { "key": "sam_template", "question": "What is the template file path?", "default": "template.yaml" }, { ... ``` Example **`cookiecutter.json`**: ``` { "outputDir": "aws-sam-pipeline", "pipeline_user_jenkins_credential_id": "", "sam_template": "", ... ``` Example **`Jenkinsfile`**: ``` pipeline { agent any environment { PIPELINE_USER_CREDENTIAL_ID = '{{cookiecutter.pipeline_user_jenkins_credential_id}}' SAM_TEMPLATE = '{{cookiecutter.sam_template}}' ... ``` # Automate the deployment of your AWS SAM application In AWS SAM, how you automate the deployment of your AWS SAM application varies depending on the CI/CD system you are using. For this reason, the examples in this section show you how to configure various CI/CD systems to automate building serverless applications in an AWS SAM build container image. These build container images make it easier to build and package serverless applications using the AWS SAM CLI. The procedures for your existing CI/CD pipeline to deploy serverless applications using AWS SAM are slightly different depending on which CI/CD system you are using. The following topics provide examples for configuring your CI/CD system to build serverless applications within an AWS SAM build container image: **Topics** + [Using AWS CodePipeline to deploy with AWS SAM](deploying-using-codepipeline.md) + [Using Bitbucket Pipelines to deploying with AWS SAM](deploying-using-bitbucket.md) + [Using Jenkins to deploy with AWS SAM](deploying-using-jenkins.md) + [Using GitLab CI/CD to deploy with AWS SAM](deploying-using-gitlab.md) + [Using GitHub Actions to deploy with AWS SAM](deploying-using-github.md) # Using AWS CodePipeline to deploy with AWS SAM To configure your [AWS CodePipeline](https://docs.aws.amazon.com/codepipeline/latest/userguide/welcome.html) pipeline to automate the build and deployment of your AWS SAM application, your CloudFormation template and `buildspec.yml` file must contain lines that do the following: 1. Reference a build container image with the necessary runtime from the available images. The following example uses the `public.ecr.aws/sam/build-nodejs20.x` build container image. 1. Configure the pipeline stages to run the necessary AWS SAM command line interface (CLI) commands. The following example runs two AWS SAM CLI commands: **sam build** and **sam deploy** (with necessary options). This example assumes that you have declared all functions and layers in your AWS SAM template file with `runtime: nodejs20.x`. **CloudFormation template snippet:** ``` CodeBuildProject: Type: AWS::CodeBuild::Project Properties: Environment: ComputeType: BUILD_GENERAL1_SMALL Image: public.ecr.aws/sam/build-nodejs20.x Type: LINUX_CONTAINER ... ``` **`buildspec.yml` snippet:** ``` version: 0.2 phases: build: commands: - sam build - sam deploy --no-confirm-changeset --no-fail-on-empty-changeset ``` For a list of available Amazon Elastic Container Registry (Amazon ECR) build container images for different runtimes, see [Image repositories for AWS SAM](serverless-image-repositories.md). # Using Bitbucket Pipelines to deploying with AWS SAM To configure your [Bitbucket Pipeline](https://support.atlassian.com/bitbucket-cloud/docs/get-started-with-bitbucket-pipelines/) to automate the build and deployment of your AWS SAM application, your `bitbucket-pipelines.yml` file must contain lines that do the following: 1. Reference a build container image with the necessary runtime from the available images. The following example uses the `public.ecr.aws/sam/build-nodejs20.x` build container image. 1. Configure the pipeline stages to run the necessary AWS SAM command line interface (CLI) commands. The following example runs two AWS SAM CLI commands: **sam build** and **sam deploy** (with necessary options). This example assumes that you have declared all functions and layers in your AWS SAM template file with `runtime: nodejs20.x`. ``` image: public.ecr.aws/sam/build-nodejs20.x pipelines: branches: main: # branch name - step: name: Build and Package script: - sam build - sam deploy --no-confirm-changeset --no-fail-on-empty-changeset ``` For a list of available Amazon Elastic Container Registry (Amazon ECR) build container images for different runtimes, see [Image repositories for AWS SAM](serverless-image-repositories.md). # Using Jenkins to deploy with AWS SAM To configure your [Jenkins](https://www.jenkins.io/) pipeline to automate the build and deployment of your AWS SAM application, your `Jenkinsfile` must contain lines that do the following: 1. Reference a build container image with the necessary runtime from the available images. The following example uses the `public.ecr.aws/sam/build-nodejs20.x` build container image. 1. Configure the pipeline stages to run the necessary AWS SAM command line interface (CLI) commands. The following example runs two AWS SAM CLI commands: **sam build** and **sam deploy** (with necessary options). This example assumes that you have declared all functions and layers in your AWS SAM template file with `runtime: nodejs20.x`. ``` pipeline { agent { docker { image 'public.ecr.aws/sam/build-nodejs20.x' } } stages { stage('build') { steps { sh 'sam build' sh 'sam deploy --no-confirm-changeset --no-fail-on-empty-changeset' } } } } ``` For a list of available Amazon Elastic Container Registry (Amazon ECR) build container images for different runtimes, see [Image repositories for AWS SAM](serverless-image-repositories.md). # Using GitLab CI/CD to deploy with AWS SAM To configure your [GitLab](https://about.gitlab.com) pipeline to automate the build and deployment of your AWS SAM application, your `gitlab-ci.yml` file must contain lines that do the following: 1. Reference a build container image with the necessary runtime from the available images. The following example uses the `public.ecr.aws/sam/build-nodejs20.x` build container image. 1. Configure the pipeline stages to run the necessary AWS SAM command line interface (CLI) commands. The following example runs two AWS SAM CLI commands: **sam build** and **sam deploy** (with necessary options). This example assumes that you have declared all functions and layers in your AWS SAM template file with `runtime: nodejs20.x`. ``` image: public.ecr.aws/sam/build-nodejs20.x deploy: script: - sam build - sam deploy --no-confirm-changeset --no-fail-on-empty-changeset ``` For a list of available Amazon Elastic Container Registry (Amazon ECR) build container images for different runtimes, see [Image repositories for AWS SAM](serverless-image-repositories.md). # Using GitHub Actions to deploy with AWS SAM To configure your [GitHub](https://github.com/) pipeline to automate the build and deployment of your AWS SAM application, you must first install the AWS SAM command line interface (CLI) on your host. You can use [GitHub Actions](https://github.com/features/actions) in your GitHub workflow to help with this setup. The following example GitHub workflow sets up an Ubuntu host using a series of GitHub Actions, then runs AWS SAM CLI commands to build and deploy an AWS SAM application: ``` on: push: branches: - main jobs: deploy: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - uses: actions/setup-python@v3 - uses: aws-actions/setup-sam@v2 - uses: aws-actions/configure-aws-credentials@v1 with: aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }} aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }} aws-region: us-east-2 - run: sam build --use-container - run: sam deploy --no-confirm-changeset --no-fail-on-empty-changeset ``` For a list of available Amazon Elastic Container Registry (Amazon ECR) build container images for different runtimes, see [Image repositories for AWS SAM](serverless-image-repositories.md). # How to use OIDC authentication with AWS SAM pipelines AWS Serverless Application Model (AWS SAM) supports OpenID Connect (OIDC) user authentication for Bitbucket, GitHub Actions, and GitLab continuous integration and continuous delivery (CI/CD) platforms. With this support, you can use authorized CI/CD user accounts from any of these platforms to manage your serverless application pipelines. Otherwise, you would need to create and manage multiple AWS Identity and Access Management (IAM) users to control access to AWS SAM pipelines. ## Set up OIDC with AWS SAM pipeline During the `sam pipeline bootstrap` configuration process, do the following to set up OIDC with your AWS SAM pipeline. 1. When prompted to choose an identity provider, select **OIDC**. 1. Next, select a supported OIDC provider. 1. Enter the OIDC provider URL, beginning with **https://**. **Note** AWS SAM references this URL when it generates the `AWS::IAM::OIDCProvider` resource type. 1. Next, follow the prompts and enter the CI/CD platform information needed to access the selected platform. These details vary by platform and can include: + OIDC client ID. + Code repository name or universally unique identifier (UUID). + Group or Organization name associated with the repository. + GitHub organization that the code repository belongs to. + GitHub repository name. + Branch that deployments will occur from. 1. AWS SAM displays a summary of the entered OIDC configuration. Enter the number for a setting to edit it, or press Enter to continue. 1. When prompted to confirm the creation of resources needed to support the entered OIDC connection, press Y to continue. AWS SAM generates an `AWS::IAM::OIDCProvider` AWS CloudFormation resource with the provided configuration that assumes the pipeline execution role. To learn more about this CloudFormation resource type, see [AWS::IAM::OIDCProvider](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-iam-oidcprovider.html) in the *AWS CloudFormation User Guide*. **Note** If the identity provider (IdP) resource already exists in your AWS account, AWS SAM references it instead of creating a new resource. ## Example The following is an example of setting up OIDC with AWS SAM pipeline. ``` Select a permissions provider: 1 - IAM (default) 2 - OpenID Connect (OIDC) Choice (1, 2): 2 Select an OIDC provider: 1 - GitHub Actions 2 - GitLab 3 - Bitbucket Choice (1, 2, 3): 1 Enter the URL of the OIDC provider [https://token.actions.githubusercontent.com]: Enter the OIDC client ID (sometimes called audience) [sts.amazonaws.com]: Enter the GitHub organization that the code repository belongs to. If there is no organization enter your username instead: my-org Enter GitHub repository name: testing Enter the name of the branch that deployments will occur from [main]: [3] Reference application build resources Enter the pipeline execution role ARN if you have previously created one, or we will create one for you []: Enter the CloudFormation execution role ARN if you have previously created one, or we will create one for you []: Please enter the artifact bucket ARN for your Lambda function. If you do not have a bucket, we will create one for you []: Does your application contain any IMAGE type Lambda functions? [y/N]: [4] Summary Below is the summary of the answers: 1 - Account: 123456 2 - Stage configuration name: dev 3 - Region: us-east-1 4 - OIDC identity provider URL: https://token.actions.githubusercontent.com 5 - OIDC client ID: sts.amazonaws.com 6 - GitHub organization: my-org 7 - GitHub repository: testing 8 - Deployment branch: main 9 - Pipeline execution role: [to be created] 10 - CloudFormation execution role: [to be created] 11 - Artifacts bucket: [to be created] 12 - ECR image repository: [skipped] Press enter to confirm the values above, or select an item to edit the value: This will create the following required resources for the 'dev' configuration: - IAM OIDC Identity Provider - Pipeline execution role - CloudFormation execution role - Artifact bucket Should we proceed with the creation? [y/N]: ``` ## Learn more For more information on using OIDC with AWS SAM pipeline, see [sam pipeline bootstrap](sam-cli-command-reference-sam-pipeline-bootstrap.md).