/aws-sam-plugin

Primary LanguageJavaMIT LicenseMIT

AWS SAM plugin for Jenkins

License Wiki Build Status

Note

This plugin is DEPRECATED as of February 12, 2024.

We recommend using the AWS SAM build images directly using Jenkins Pipeline.

See here for more information.

The AWS Serverless Application Model (SAM) is an open-source framework you can use to build serverless applications on AWS.

This plugin helps you automate the deployments of your applications that are defined using SAM.

Features

  • Custom build step
  • samDeploy Pipeline step
  • Deploy SAM applications to AWS
  • Package SAM applications to a S3 bucket
    • Use specific or auto-created S3 bucket (if not given, a bucket will be automatically created in your account for you)
  • Template parameters support
  • Template tags support
  • Deploy to a specific region
  • Use an S3 prefix for packaged artifacts to have fine-grained control of where artifacts are uploaded
  • Use a specific KMS key for encrypting packaged artifacts at rest in S3
  • Configurable deployment role

Installation

  1. Navigate to your Jenkins server
  2. On the left, click "Manage Jenkins"
  3. Scroll down to find "Manage Plugins" and click it
  4. Look for the "AWS SAM" plugin

Requirements

AWS account

In order to deploy to AWS you must have an AWS account. Visit https://aws.amazon.com if you do not have one.

AWS credential configuration

Before you can start building, you must have your AWS credentials set up in Jenkins. To do this:

  1. From the main page of your jenkins server go to "Manage Jenkins" > "Manage Credentials" and then click on "Global" domain.
  2. Click "Add Credentials."
  3. Select from the "Kind" dropdown "AWS Credentials". If "AWS Credentials" do not exist, please check if you have AWS SAM plugin installed
  4. Finish the form with your AWS access keys and click "OK."

IAM setup

For deployment you'll need access to an S3 bucket (or permission to create one), CloudFormation and ChangeSet IAM lifecycle actions, as well as any IAM permissions required to create the resources in your SAM (CloudFormation) template.

S3 policy (you may want to limit Resource to specific S3 Buckets)

Version: '2012-10-17'
Statement:
  - Sid: SAMS3Actions
    Resource: '*'
    Effect: Allow
    Action:
      - s3:CreateBucket
      - s3:GetBucketLocation
      - s3:ListBucket
      - s3:PutObject
      - s3:PutObjectAcl
      - s3:PutObjectTagging

CloudFormation policy (you may want to limit Resource to specific stacks)

Version: '2012-10-17'
Statement:
  - Sid: SAMCloudFormationActions
    Resource: '*'
    Effect: Allow
    Action:
      - cloudformation:ValidateTemplate
      - cloudformation:DescribeStacks
      - cloudformation:CreateChangeSet
      - cloudformation:DescribeChangeSet
      - cloudformation:ExecuteChangeSet

Project configuration

There are a few steps to configuring your build.

  1. In your project configuration, scroll down to build steps.
  2. Add the "AWS SAM deploy application" build step.

Configuring the build step

  1. Select your AWS Credentials from the dropdown.
  2. Select the target region to deploy to.
  3. Give the build step a stack name.
  4. Optional: Enter an S3 bucket name to package the artifacts to.
    1. If you leave this blank, the S3 bucket will be auto-generated.
  5. Give the path to the SAM template file.

  1. Optional: If your template has parameters, add parameters where necessary.
  2. Optional: Add any tags to the stack you'd like.

  1. Optional: Finish the "Advanced" configuration
    1. Give an S3 prefix to package the artifacts in the bucket under.
    2. Give a KMS Key ID to encrypt the packaged artifacts.
    3. Give a Role Arn that will be assumed by CloudFormation when executing the changeset.
  2. Select an output template file for the package step to output to.