Skip to content

AWS SAM & CloudFormation: A Crash Course

Since this is your first exposure to these tools, this guide breaks down exactly what is happening "under the hood" when you run those magical commands.

1. The Big Picture: Infrastructure as Code (IaC)

In the "old days," you would click buttons in the AWS Console to create a database, then click more buttons to create a function, and then try to remember exactly what settings you clicked so you could do it again for production.

Infrastructure as Code (IaC) solves this. You define your entire infrastructure in a text file (like template.yaml). This file is:

  • Version Controlled: It lives in Git with your code.
  • Reproducible: You can spin up an identical copy of your app in a different region in minutes.
  • Declarative: You tell AWS what you want (e.g., "I want a table"), not how to build it.

2. AWS CloudFormation (The Engine)

CloudFormation is the AWS service that reads your template file and actually creates the resources.

  • The Stack: When you deploy a template, CloudFormation creates a "Stack." This is a container for all your resources. If you delete the Stack, AWS deletes everything inside it (Table, Function, API) automatically.
  • The Template: The YAML file that lists resources.
  • Drift: CloudFormation remembers the state of your stack. If you manually change a setting in the AWS Console, your stack has "drifted" from your code. Rule of thumb: Once you start using IaC, stop changing things manually in the Console.

Why did your deployment fail earlier?

CloudFormation follows a strict rule: "I must own what I create." When you tried to deploy the stack, CloudFormation looked at your template and saw it needed to create a table named MinimalCalorieMeals. It checked AWS, saw that a table with that name already existed (created manually), and halted. It didn't want to accidentally overwrite or mess up existing infrastructure it didn't create.

3. AWS SAM (The Developer Tool)

Writing raw CloudFormation is verbose. To define a simple Lambda function and an API Gateway in raw CloudFormation might take 50-100 lines of JSON/YAML.

SAM (Serverless Application Model) is an extension (or "superset") of CloudFormation designed specifically for Serverless.

  • The "Transform": Notice the line Transform: AWS::Serverless-2016-10-31 at the top of your template? That tells CloudFormation: "Hey, this file uses SAM shorthand. Please expand it into full CloudFormation before you deploy."
  • Shorthand: SAM lets you define an API, a Function, and an IAM Permission Policy in a single block of YAML.

4. Dissecting Your template.yaml

Let's look at your actual code to see these concepts in action.

A. The Function (AWS::Serverless::Function)

CalorieTrackerFunction:
  Type: AWS::Serverless::Function # <--- SAM Resource Type
  Properties:
    CodeUri: lambda/
    Environment:
      Variables:
        # Dynamic Reference (The cool secret injection part)
        SECRET_TOKEN: '{{resolve:secretsmanager:...}}'
    Events:
      PostMeal:
        Type: HttpApi # <--- Implicitly creates an API Gateway!
        Properties:
          Path: /meals
          Method: post

What SAM does here:

  1. Zips up your lambda/ folder.
  2. Uploads it to S3.
  3. Creates the Lambda Function.
  4. Automatically creates an API Gateway (because you defined an HttpApi event).
  5. Automatically creates the IAM Roles allowing the API Gateway to invoke the Lambda.

B. The Database (AWS::DynamoDB::Table)

MinimalCalorieMeals:
  Type: AWS::DynamoDB::Table # <--- Standard CloudFormation (not SAM specific)
  Properties:
    TableName: MinimalCalorieMeals
    BillingMode: PAY_PER_REQUEST

This is standard CloudFormation. SAM allows you to mix standard resources (S3 buckets, Tables, Queues) with SAM resources seamlessly.

5. The Workflow: Build vs. Deploy

sam build

  • What it does: It prepares your application dependencies.
  • In your case: It goes into lambda/, sees package.json, runs npm install, and copies everything to a hidden folder .aws-sam/build.
  • Why: AWS Lambda needs node_modules to run. You don't commit node_modules to Git, so sam build generates them for the deployment package.

sam deploy --guided

  1. Packaging: It zips the .aws-sam/build folder and uploads it to a managed S3 bucket.
  2. ChangeSet: It compares your current template with what is already running in AWS.
  3. Execution: It applies only the changes (e.g., "Update the Lambda code, but leave the DynamoDB table alone").

Summary Glossary

  • Resource: An AWS component (Lambda, Table, Bucket).
  • Stack: A collection of resources managed as a single unit.
  • Template: The YAML blueprint.
  • SAM: The framework that makes writing templates easier.
  • CloudFormation: The AWS service that executes the templates.