Deploying a SAM Application

Step 3: Deploy

You now have a single CloudFormation template (output.yaml) which describes the entire infrastructure and links to a packaged version of the function code. To create a running instance of your application, you’ll need to create a new CloudFormation stack based on this template. To do that, run the following command in the directory that contains the packaged template (output.yaml):

sam deploy --template-file output.yaml --stack-name sam-test-1 --capabilities CAPABILITY_IAM

This command has three arguments:

• --template-file is the template to deploy. You want to use the result of the package command here, hence output.yaml.
• --stack-name is a name for the target stack. If a stack with the specified name does not yet exist in your AWS account, CloudFormation will create it. If you use the same name the next time you deploy, CloudFormation will update the existing resources instead of creating new ones.
• --capabilities CAPABILITY_IAM allows CloudFormation to create IAM policies. SAM needs this to let the API Gateway call Lambda functions. Note that these are not security capabilities of the Lambda function, but instead the privileges required by the deployment process.

Note that you will use sam-test-1 as the stack name to run all the commands in this course.

In a few moments, you will see that SAM has started deploying your project:

$ sam deploy --template-file output.yaml --stack-name sam-test-1 --capabilities CAPABILITY_IAM

Waiting for changeset to be created..
Waiting for stack create/update to complete
Successfully created/updated stack - sam-test-1

If you see permission errors instead of a successful result, make sure that you have configured access credentials for the command line tools correctly, and that your AWS access user has permissions to modify AWS resources. You can find instructions on configuring access credentials in Chapter 2.

SAM or CloudFormation deployment

The sam deploy command is more than just an alias for aws cloudformation deploy. It can store deployment parameters for your project in a configuration file (samconfig.toml) in your project’s root directory for easier reuse.

Modern SAM deployment workflow

The deployment process shown above follows a legacy two-step workflow (sam package → sam deploy) to help illustrate what happens behind the scenes with AWS SAM CLI.

In modern usage, this process has been simplified. The recommended approach is to deploy your application directly after building it, using:

sam deploy --guided

The --guided flag enables an interactive deployment experience that:

• Automatically packages your application (no separate sam package step required)
• Prompts you for required configuration values
• Saves your answers to a samconfig.toml file for reuse
• Deploys your application using AWS CloudFormation

When running sam deploy --guided for the first time, you’ll be asked to provide:

• Stack name (use sam-test-1 for consistency in this course)
• AWS Region
• Confirmation preferences
• Permission to create IAM roles (equivalent to CAPABILITY_IAM)

These settings are saved locally, so you won’t need to re-enter them later.

That’s it for deploying a SAM application. In the next lesson, you’ll inspect the stack you created.