AWS SAM Hands-On: Building & Shipping Serverless Apps Fast

You can build a serverless API in raw CloudFormation, but the first time you try it you write about 120 lines of YAML to stand up one Lambda behind one route: the function, its IAM role, the role’s trust and permission policies, the log group, the API, its stage, the deployment, the integration, the route, and the lambda:InvokeFunction permission that lets the API call the code. Nine resources, hand-wired, for one HTTP endpoint. AWS SAM — the Serverless Application Model — collapses all of that into roughly a dozen lines, because SAM is a CloudFormation transform: a macro named AWS::Serverless-2016-10-31 that expands a handful of short-hand resource types into the full CloudFormation you would otherwise type by hand.

That is the whole idea, and it is worth saying precisely because people misfile SAM as “a different IaC tool.” It is not. A SAM template is a CloudFormation template with one extra Transform: line and permission to use five or six special resource types like AWS::Serverless::Function and AWS::Serverless::HttpApi. When you deploy, AWS runs the transform server-side, the short-hand explodes into ordinary AWS::Lambda::Function, AWS::IAM::Role, AWS::ApiGatewayV2::Api and the rest, and from that point on it is a normal CloudFormation stack — same drift detection, same rollback, same change sets. You get CloudFormation’s guarantees with a fraction of CloudFormation’s typing.

The second half of SAM is the SAM CLI (sam), and it is where the day-to-day speed comes from: sam init scaffolds an app, sam build compiles each function per-runtime (esbuild for TypeScript, pip for Python, containers when you ask), sam local start-api runs the whole API on your laptop inside the real Lambda Docker image so you can curl it before you deploy, sam deploy --guided walks you through your first ship and writes a samconfig.toml so every later deploy is one command, and sam sync — Accelerate mode — gives you a sub-ten-second inner loop by pushing code-only changes straight to the service and skipping the full CloudFormation update. By the end of this article you will have built a Lambda + HttpApi + DynamoDB SimpleTable app, run it locally, shipped it, changed a line and watched sam sync update it in seconds, then torn it down — and you will have a 16-row troubleshooting playbook for when sam build can’t find Docker, the transform rejects your Events shape, or a too-narrow policy template throws AccessDenied in production.

Here is the entire SAM surface on one screen — every moving part, what it is, and the beginner trap attached to it:

What problem this solves

The pain SAM removes is boilerplate density plus a broken inner loop. Raw CloudFormation is verbose by design — it makes no assumptions — so a serverless app that is conceptually “three functions, one API, one table” becomes several hundred lines in which the interesting five lines (the code path, the permission, the route) are buried under role trust policies and API stage plumbing you copy-paste and never read. Worse, CloudFormation has no local story: to test a change you aws cloudformation deploy and wait two to four minutes for a stack update, every time, for a one-character fix. That feedback loop is where serverless productivity goes to die.

What breaks without SAM is not that things are impossible — it is that they are slow and error-prone in ways that compound. You hand-write an IAM role and give it dynamodb:* on * because scoping it correctly is fiddly, and now you have a least-privilege violation in every service. You wire an S3 trigger and forget the AWS::Lambda::Permission, so the bucket silently never invokes the function. You want to try the handler against a realistic API Gateway event and you have no way to do it except deploy-and-curl. Each of these is a half-hour tax, several times a day. SAM’s Policies templates make the scoped role a one-liner, its Events block wires the trigger and the permission for you, and sam local plus sam local generate-event let you replay a real event shape on your laptop.

Here is exactly what the transform collapses — the raw CloudFormation resources SAM generates for you from each line of shorthand, and roughly how much typing it saves:

Learning objectives

By the end of this article you can:

• Explain that SAM is a CloudFormation transform (AWS::Serverless-2016-10-31), why a SAM template is a superset of a CloudFormation template, and how the macro expands short-hand into ordinary resources server-side at deploy time.
• Author every SAM resource type — AWS::Serverless::Function (with Events, Policies, Layers, Environment), Api and HttpApi, SimpleTable, StateMachine, LayerVersion and Application (from the Serverless Application Repository) — and know when to reach past shorthand to a raw CFN resource.
• Use the Globals section to set fleet-wide defaults and predict exactly which resource types and properties it applies to.
• Choose policy templates for least-privilege IAM the easy way, mix them with raw IAM statements and managed-policy ARNs, and diagnose the classic “too-narrow template → runtime AccessDenied.”
• Run the full SAM CLI loop — sam init, sam validate --lint, sam build (per-runtime and --use-container), sam local invoke / start-api / generate-event, sam deploy --guided (+ samconfig.toml), sam sync/Accelerate, sam logs, sam traces.
• Build, locally test, deploy, hot-update with sam sync, and tear down a Lambda + HttpApi + DynamoDB app end to end.
• Decide SAM vs CDK vs raw CloudFormation vs the Serverless Framework from a real trade-off matrix, and bootstrap CI/CD with sam pipeline.
• Work a symptom → cause → confirm → fix playbook for the dozen-plus ways a first SAM app breaks.

Prerequisites & where this fits

You need an AWS account with permission to create IAM roles, Lambda functions, API Gateway APIs and DynamoDB tables (a personal or dev sandbox — never straight into production), the AWS CLI v2 configured (aws configure or aws sso login), the AWS SAM CLI installed (brew install aws-sam-cli, or the MSI/pip installer — check with sam --version, you want ≥ 1.100), Docker running (SAM’s local emulation and container builds need it), and Node.js 20 if you follow the TypeScript lab (or Python 3.12 for the Python variant). Everything here is free-tier-friendly: Lambda’s always-free tier, HTTP API’s first million requests, and DynamoDB on-demand at a few reads/writes cost effectively nothing; the only lingering line items are CloudWatch Logs storage and the tiny S3 objects SAM uploads.

Where this sits: SAM is the fastest on-ramp to Infrastructure as Code for serverless specifically. It assumes you already understand a Lambda function’s anatomy — if the handler signature, execution role and CloudWatch Logs are new, build one by hand first with Your First AWS Lambda Function: Handlers, Triggers, Roles & Logs Hands-On. SAM’s most common front door is API Gateway, so the flavors, authorizers and throttling in Amazon API Gateway Hands-On: REST vs HTTP APIs, Authorizers & Throttling are the layer SAM’s Events shorthand is generating for you. SAM is one way to write IaC on AWS; the general-purpose engine underneath it is CloudFormation, covered in AWS CloudFormation: Your First Stack Hands-On, and the imperative alternative that generates CloudFormation from TypeScript is in AWS CDK with TypeScript: Infrastructure as Code Hands-On — read that one for the SAM-vs-CDK decision from the CDK side.

A quick map of who owns what in a SAM project, so when something misbehaves you look in the right place:

Core concepts

SAM is a transform, not a separate system

Every SAM template starts with two lines that make it a SAM template rather than a plain CloudFormation template:

AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31

Transform is a standard CloudFormation feature — it names a macro that CloudFormation runs against your template before it creates resources. AWS::Serverless-2016-10-31 is a macro AWS hosts for you. When you deploy, CloudFormation sends the template to that macro, the macro finds every AWS::Serverless::* resource and rewrites it into ordinary resources, and CloudFormation then processes the expanded template. Because it is a macro, deploying a SAM template through raw CloudFormation requires the CAPABILITY_AUTO_EXPAND capability (you are telling CloudFormation “yes, I know a macro will change my template”), on top of CAPABILITY_IAM for the roles it generates. The sam CLI passes both for you; this is why people who try to aws cloudformation deploy a SAM template directly hit a capability error.

The practical consequences of “it’s just CloudFormation underneath” are worth internalizing:

The SAM resource types

There are only a handful of short-hand types. Learn what each one expands into and you can predict its behavior:

The Globals section

Globals is a top-level block that sets default properties applied to every resource of a supported type in the file, so you write Timeout, Runtime, MemorySize, Tracing and shared env vars once instead of on each function. It only applies to five resource types, and a per-resource property overrides (or, for maps/lists, merges with) the global. The single most common Globals surprise is expecting it to cover a property or a resource type it does not — for example it applies to Function but there is no global for SimpleTable’s PrimaryKey.

The SAM template, section by section

A SAM template has the same top-level sections as any CloudFormation template — Transform and Globals are the only SAM-specific additions. Master these and you can read any SAM file:

The intrinsic functions you will actually reach for, since a SAM template is CloudFormation:

That last row is a genuine gotcha and worth flagging early: when a function declares an HttpApi (or Api) event without pointing at an explicit API resource, SAM creates one implicitly with the logical ID ServerlessHttpApi (or ServerlessRestApi for REST). You reference it by that name in Outputs and !Ref. People spend twenty minutes looking for an API resource they never wrote — it is the implicit one the transform generated.

AWS::Serverless::Function in depth

This is the resource you will write most, so know every property. A function is your code plus its configuration plus its triggers plus its permissions, all in one block.

Event sources — the Events block

Events is where SAM earns its keep: each entry both configures the trigger and generates the AWS::Lambda::Permission (or event-source mapping) that lets it invoke your function. The Type determines the shape of Properties. Get the shape wrong and the source silently never fires — the number-one “it works in the console but not from the trigger” bug.

Policies — least privilege the easy way

The Policies property accepts four different forms, and you can mix them in one list. This flexibility is the whole point: reach for a policy template for the common case, drop to a raw inline statement when the template does not fit.

Policy templates are named, parameterized, least-privilege snippets. There are around a hundred; these are the ones you will use constantly:

The failure mode to burn into memory: a policy template scoped too narrow (say DynamoDBReadPolicy on a function that also writes) passes sam validate, deploys clean, works in every read test, then throws AccessDeniedException: User is not authorized to perform: dynamodb:PutItem the first time it writes in production. The template is doing its job — least privilege — you just picked the wrong one. The fix is the Crud variant or an added inline statement, never dynamodb:* on *.

Build metadata

For compiled/bundled runtimes, sam build reads the function’s Metadata block to know how to build it. For TypeScript this is where you turn on esbuild:

The other resource types

Serverless::Api vs Serverless::HttpApi

Both put an API in front of your functions, but they expand into different services (ApiGateway::RestApi vs ApiGatewayV2::Api) with different features and costs. Pick HttpApi unless you need a REST-only feature.

SimpleTable

SimpleTable is deliberately minimal: a DynamoDB table with exactly one primary key and on-demand billing. It is perfect for a lookup or a first table and a trap the moment you need a second access pattern.

The moment you need a sort key, a GSI, streams, or TTL, graduate to the raw AWS::DynamoDB::Table — you can keep it in the same SAM file and still reference it with !Ref/!GetAtt.

StateMachine

AWS::Serverless::StateMachine wires a Step Functions workflow with the same Events/Policies conveniences as a function.

LayerVersion and Application (SAR)

The SAM CLI workflow

The CLI is the half of SAM you touch every day. Here is the full command surface, then the flags that matter for the three you run most.

sam build

sam build reads each function’s Runtime/Metadata, resolves its dependencies, and writes a self-contained artifact per function under .aws-sam/build, plus a rewritten template.yaml that points CodeUri at those artifacts.

sam local

Everything under sam local runs your function inside the real Lambda runtime Docker image, so a missing Docker daemon is the first failure. start-api reads your Events of type Api/HttpApi and serves them.

sam deploy and samconfig.toml

sam deploy --guided is the first-run wizard: it prompts for stack name, region, capabilities, and whether to save the answers, then writes samconfig.toml so every later sam deploy is parameter-free. Under the hood it uploads artifacts to S3, expands the transform, creates a change set, and executes it.

sam sync / Accelerate — the fast inner loop

sam sync is the productivity headline. Instead of a full CloudFormation update (minutes) for every change, sam sync watches your files and, for a code-only change, calls the Lambda service API (UpdateFunctionCode) directly, skipping CloudFormation entirely — a two-to-ten-second update. For a template change it falls back to a real stack update. It is a development tool: because code-only syncs bypass CloudFormation, the deployed function can drift from what a clean sam deploy of the same template would produce, which is exactly why you never point sam sync at production.

sam logs and sam traces close the loop: sam logs --stack-name <s> --tail streams every function’s CloudWatch Logs (add --name <LogicalId> to narrow), and sam traces --tail pulls X-Ray traces so you can see the API-GW → Lambda → DynamoDB latency breakdown without leaving the terminal.

Policy templates vs raw IAM — the decision

Both express the function’s permissions; the question is which to reach for. Templates are least-privilege by construction but only cover common grants; raw IAM covers anything but you own the scoping.

AWS::Serverless::Connector (and the Connectors shorthand) deserves a mention: instead of hand-picking a policy template, you declare “this function needs to write to this table” and SAM computes the minimal IAM for the link. It is the newest and often cleanest way to express intent:

PutItemFunction:
  Type: AWS::Serverless::Function
  Connectors:
    TableConn:
      Properties:
        Destination:
          Id: ItemsTable
        Permissions:
          - Write

SAM ↔ CloudFormation interop and sam pipeline

Because SAM is a transform, a SAM template is a place you can put any CloudFormation resource. This is the escape hatch that means you never outgrow SAM for the non-serverless bits of a serverless app.

For CI/CD, sam pipeline bootstraps the plumbing so you are not hand-writing OIDC roles and artifact buckets:

SAM vs CDK vs raw CloudFormation vs Serverless Framework

There is no single winner; there is a right tool per team and workload. All four ultimately produce CloudFormation (except Serverless Framework, which can target multiple clouds). Decide on language, scope and team.

The short version: SAM when the app is serverless and you value a great local loop and minimal YAML; CDK when infrastructure is complex enough that loops, functions and typed abstractions in a real language pay off (see the CDK-side view in AWS CDK with TypeScript: Infrastructure as Code Hands-On); raw CloudFormation when you want zero abstraction or you are templating non-serverless estates (covered in AWS CloudFormation: Your First Stack Hands-On); Serverless Framework when you already run it or genuinely need multi-cloud.

Architecture at a glance

The diagram traces both the workflow (left) and the deployed system (right), because in SAM they are the same story: what you author on the left becomes what runs on the right. You write a compact template.yaml with AWS::Serverless::* shorthand, a Globals block and policy templates. The SAM CLI builds each function per-runtime into .aws-sam/build (esbuild for TypeScript here) and can serve the whole API locally in Docker for curl testing. On sam deploy, the AWS::Serverless-2016-10-31 transform expands the shorthand — each function becomes a Lambda + IAM role + log group + the API permission, the HttpApi becomes a real API Gateway v2 API, and the SimpleTable becomes a DynamoDB table — and CloudFormation drives a change set that creates the stack. At runtime a request hits the HttpApi’s $default stage, invokes the arm64 Node.js function, which writes to the on-demand DynamoDB table via the SDK using exactly the permissions the DynamoDBCrudPolicy template scoped for it. Each numbered badge marks a place a first SAM app breaks; the legend narrates symptom, confirm and fix.

Real-world scenario

Meridian Freight, a mid-size logistics firm, ran a “shipment events” microservice on a hand-written CloudFormation template: three Lambdas (ingest, enrich, notify), a REST API, a DynamoDB table and an SQS queue, spread across 640 lines of YAML that two engineers understood and nobody else touched. Deploys took four minutes; a one-line handler fix meant a four-minute wait to see it live, so developers batched changes, which made every failed deploy a hunt through five commits. Their IAM was the tell-tale sign of CloudFormation fatigue: every function’s role had dynamodb:* and sqs:* on *, because scoping each one by hand was too tedious to bother with — a finding their first security review flagged as high risk.

They migrated to SAM over a sprint. The 640-line template became 180 lines: functions collapsed into AWS::Serverless::Function blocks with Events wiring the API, queue and stream triggers (deleting ~200 lines of AWS::Lambda::Permission and event-source-mapping boilerplate), and the wildcard roles became DynamoDBCrudPolicy and SQSSendMessagePolicy one-liners scoped to the exact table and queue ARNs — the security finding closed itself. The behavioural change that the team felt most, though, was sam sync --watch: the inner loop for a handler tweak went from four minutes to about seven seconds, so engineers stopped batching and started shipping one change at a time, and the “which of these five commits broke it” problem evaporated.

Two things bit them during the migration, and both are instructive. First, a developer moved the notify function’s policy from DynamoDBCrudPolicy to DynamoDBReadPolicy while “tightening” permissions, not realizing notify also wrote a “last notified” timestamp back to the table; it passed every test (all reads) and threw AccessDeniedException on dynamodb:UpdateItem in production during the first real notification — a five-minute fix once they read the CloudWatch line, but a reminder that “least privilege” means right privilege, not less. Second, someone ran sam sync against the staging stack to “quickly test” a change, then a teammate ran a normal sam deploy of a slightly older template branch, and the code-only drift from the sync got overwritten — they adopted the rule “sam sync on personal dev stacks only; staging and prod ship exclusively through the sam pipeline-generated GitHub Actions workflow.” A year on, the service is 180 lines anyone on the team can read, deploys through a reviewed pipeline, and no role has a wildcard on it.

Advantages and disadvantages

SAM’s advantages compound for a team building a serverless-first system: the local loop and sam sync change how fast you iterate, the policy templates change your security posture for free, and “it’s just CloudFormation” means you keep every operational guarantee. The disadvantages matter most at the edges — if your estate is mostly VPCs, EC2 fleets and RDS with a little Lambda, the shorthand buys you little and CDK or raw CloudFormation fits better; if you need constructs, loops and typed reuse, CDK’s real-language authoring wins; if you must target more than AWS, only the Serverless Framework does that.

Hands-on lab

You will scaffold a TypeScript app, replace the template with a Lambda + HttpApi + DynamoDB SimpleTable, build it, run the API locally and curl it, deploy it, hit the live URL, then change a line and watch sam sync update it in seconds — and tear it all down. Everything here is free-tier-friendly. A Python variant is noted at the end.

⚠️ Costs money only if you leave it running long enough to matter: nothing here does at test volume (Lambda free tier, HTTP API’s first million requests, DynamoDB on-demand pennies, a few tiny S3 objects). sam delete at the end removes it all.

Step 0 — Prerequisites check

sam --version          # want >= 1.100
aws sts get-caller-identity   # confirms creds + account
docker ps              # must succeed — sam local & container builds need Docker
node --version         # want v20.x for the TS lab

Expected: sam --version prints something like SAM CLI, version 1.135.0, get-caller-identity prints your account/ARN, docker ps prints a (possibly empty) container table without an error.

Step 1 — Scaffold the app

sam init \
  --name sam-items \
  --runtime nodejs20.x \
  --dependency-manager npm \
  --app-template hello-world \
  --package-type Zip
cd sam-items

Expected: SAM generates a project tree (template.yaml, hello-world/, events/, samconfig later). We are going to replace the template and source with our own.

Step 2 — Write the SAM template

Replace template.yaml with this. Note the Transform line, the Globals defaults, the SimpleTable, the two functions with HttpApi events, the esbuild build metadata, the scoped policy templates, and the Outputs referencing the implicit ServerlessHttpApi.

AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Description: SAM hands-on — HttpApi + Lambda + DynamoDB SimpleTable

Globals:
  Function:
    Runtime: nodejs20.x
    Architectures: [arm64]
    MemorySize: 512
    Timeout: 10
    Tracing: Active
    Environment:
      Variables:
        TABLE_NAME: !Ref ItemsTable

Resources:
  ItemsTable:
    Type: AWS::Serverless::SimpleTable
    Properties:
      PrimaryKey:
        Name: id
        Type: String
      # No ProvisionedThroughput => PAY_PER_REQUEST (on-demand)

  PutItemFunction:
    Type: AWS::Serverless::Function
    Metadata:
      BuildMethod: esbuild
      BuildProperties:
        Minify: true
        Target: es2022
        Sourcemap: true
        EntryPoints: [src/put-item.ts]
    Properties:
      Handler: put-item.handler
      CodeUri: .
      Policies:
        - DynamoDBCrudPolicy:
            TableName: !Ref ItemsTable
      Events:
        PutItem:
          Type: HttpApi
          Properties:
            Path: /items
            Method: post

  GetItemFunction:
    Type: AWS::Serverless::Function
    Metadata:
      BuildMethod: esbuild
      BuildProperties:
        EntryPoints: [src/get-item.ts]
    Properties:
      Handler: get-item.handler
      CodeUri: .
      Policies:
        - DynamoDBReadPolicy:
            TableName: !Ref ItemsTable
      Events:
        GetItem:
          Type: HttpApi
          Properties:
            Path: /items/{id}
            Method: get

Outputs:
  ApiUrl:
    Description: HttpApi base URL
    Value: !Sub "https://${ServerlessHttpApi}.execute-api.${AWS::Region}.amazonaws.com"

Step 3 — Write the handlers and package.json

Create src/put-item.ts:

import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { DynamoDBDocumentClient, PutCommand } from "@aws-sdk/lib-dynamodb";
import { randomUUID } from "node:crypto";

const ddb = DynamoDBDocumentClient.from(new DynamoDBClient({}));
const TABLE = process.env.TABLE_NAME!;

export const handler = async (event: any) => {
  const body = JSON.parse(event.body ?? "{}");
  const id = body.id ?? randomUUID();
  await ddb.send(new PutCommand({ TableName: TABLE, Item: { id, ...body } }));
  return { statusCode: 201, body: JSON.stringify({ id }) };
};

Create src/get-item.ts:

import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { DynamoDBDocumentClient, GetCommand } from "@aws-sdk/lib-dynamodb";

const ddb = DynamoDBDocumentClient.from(new DynamoDBClient({}));
const TABLE = process.env.TABLE_NAME!;

export const handler = async (event: any) => {
  const id = event.pathParameters?.id;
  const res = await ddb.send(new GetCommand({ TableName: TABLE, Key: { id } }));
  if (!res.Item) return { statusCode: 404, body: JSON.stringify({ error: "not found" }) };
  return { statusCode: 200, body: JSON.stringify(res.Item) };
};

Create package.json (esbuild bundles the SDK, so it stays out of the deployed zip if you mark it external — here we keep it simple and bundle):

{
  "name": "sam-items",
  "version": "1.0.0",
  "dependencies": {
    "@aws-sdk/client-dynamodb": "^3.600.0",
    "@aws-sdk/lib-dynamodb": "^3.600.0"
  },
  "devDependencies": { "esbuild": "^0.23.0" }
}

Then npm install. Delete the scaffolded hello-world/ directory so only your src/ remains.

Step 4 — Validate and build

sam validate --lint
sam build

Expected: validate prints template.yaml is a valid SAM Template; build prints per-function Building codeuri: … Runtime: nodejs20.x … Build method: esbuild, then:

Build Succeeded
Built Artifacts  : .aws-sam/build
Built Template   : .aws-sam/build/template.yaml
Commands you can use next
=========================
[*] Invoke Function: sam local invoke
[*] Deploy: sam deploy --guided

Step 5 — Run the API locally and curl it

sam local start-api reads your HttpApi events and serves them on :3000 inside Docker (it will pull the Lambda image the first time). For the local write to reach a real table you would point TABLE_NAME at DynamoDB Local; to keep this step pure-local we just confirm the route wiring and handler execution.

sam local start-api          # in one terminal
# in another terminal:
curl -s -XPOST http://127.0.0.1:3000/items -d '{"name":"widget","qty":3}'

Expected: the start-api terminal logs Mounting PutItemFunction at http://127.0.0.1:3000/items [POST] and, on the request, spins a container and prints START/END/REPORT lines; the curl returns {"id":"<uuid>"} (or a DynamoDB credentials/endpoint error if you pointed it at real AWS without creds — that still proves the route and handler ran). Stop the server with Ctrl-C.

Step 6 — Deploy for real (guided)

sam deploy --guided

Answer the prompts: stack name sam-items, your region, Allow SAM CLI IAM role creation = Y (this is the CAPABILITY_IAM consent), Disable rollback = N, allow the functions to have no auth for this demo (HttpApi has no authorization defined, Is this okay? = y), and Save arguments to configuration file = Y. SAM creates the managed S3 bucket, uploads, expands the transform, and drives the change set.

Expected: a change-set preview listing AWS::Lambda::Function, AWS::IAM::Role, AWS::ApiGatewayV2::Api, AWS::DynamoDB::Table and permissions being Added, then Successfully created/updated stack - sam-items and an Outputs table:

Key                 ApiUrl
Description         HttpApi base URL
Value              https://ab12cd34ef.execute-api.ap-south-1.amazonaws.com

A samconfig.toml now exists — every later sam deploy needs no flags.

Step 7 — Hit the live API

API=$(aws cloudformation describe-stacks --stack-name sam-items \
  --query "Stacks[0].Outputs[?OutputKey=='ApiUrl'].OutputValue" --output text)

curl -s -XPOST "$API/items" -d '{"name":"widget","qty":3}'    # -> {"id":"<uuid>"}
ID=<paste-the-uuid>
curl -s "$API/items/$ID"                                       # -> {"id":"…","name":"widget","qty":3}

Expected: the POST returns a fresh id; the GET returns the stored item from the real DynamoDB table. You just proved the scoped DynamoDBCrudPolicy/DynamoDBReadPolicy grants work end to end.

Step 8 — The fast inner loop with sam sync

Change put-item.ts to also stamp a timestamp, e.g. add createdAt: new Date().toISOString() into the Item. Then:

sam sync --watch --stack-name sam-items

Expected: on the first run SAM asks to confirm (it warns this is for dev), then on save it prints something like Syncing Function PutItemFunction and Finished syncing … 0m6s — a code-only update via UpdateFunctionCode, no CloudFormation change set. curl the POST again and the response item now carries createdAt. Stop with Ctrl-C.

Step 9 — Logs and traces

sam logs --stack-name sam-items --name PutItemFunction --tail
sam traces --tail        # X-Ray, since Tracing: Active is set globally

Expected: sam logs streams the function’s CloudWatch log events (including your START/REPORT); sam traces shows the API-GW → Lambda → DynamoDB segment timings.

Step 10 — Teardown

sam delete --stack-name sam-items

Expected: SAM asks to confirm, deletes the CloudFormation stack (Lambda, role, API, table, log groups) and the artifacts it uploaded, and prints Deleted successfully. Verify with aws cloudformation describe-stacks --stack-name sam-items returning a does not exist error.

Python variant: sam init --runtime python3.12 --dependency-manager pip, drop the esbuild Metadata (Python builds from requirements.txt), set Handler: app.handler, CodeUri: src/, and use boto3 in app.py. Everything else — Globals, SimpleTable, Events, Policies, the whole CLI loop — is identical.

Common mistakes & troubleshooting

This is the section you will come back to. First the structured playbook, then an error-string reference, then a decision table and prose on the three nastiest.

Error/status reference — the strings you will actually see and what they mean:

Decision table — you see X, it’s probably Y, do Z:

The three nastiest, in prose. First, the too-narrow policy template: it is insidious precisely because everything green-lights it. sam validate passes, the deploy succeeds, every read test works, and it fails only on the first write in production with AccessDeniedException: dynamodb:UpdateItem. The lesson is that “least privilege” is correct privilege — read the code, enumerate every action it performs, and pick the template (or write the inline statement) that grants exactly those. The confirm is always the same: sam logs --name <Fn> --tail and read the exact action the SDK error names.

Second, the silently un-wired event source: you write an Events block with a slightly wrong Type or property (say Queue where SAM expects a !GetAtt Queue.Arn, or S3 without Bucket), the transform accepts it as some valid shape, and no AWS::Lambda::Permission gets generated — so the trigger fires into the void and your function is simply never invoked, with nothing in the logs because it never ran. The confirm is not in the function’s logs (there are none); it is aws lambda get-policy --function-name <fn> — if the source’s permission statement is missing, the wiring is broken. Compare your Events block against the SAM spec property-by-property.

Third, sam sync drift: sam sync --code pushes straight to the Lambda service, skipping CloudFormation, so the deployed function no longer matches what a clean sam deploy of your template would produce. On a personal dev stack that is exactly what you want (speed). The trap is running it against a shared stack: the next real sam deploy — from CI, or a colleague, or you on a different branch — reconciles the stack back to the template and silently discards your synced changes, or worse, someone debugging “prod” is looking at code that exists in no commit. Rule: sam sync on ephemeral personal stacks only; staging and prod ship exclusively through sam deploy in a pipeline.

Best practices

• Treat template.yaml as the source of truth and ship prod only via sam deploy (ideally through a sam pipeline-generated workflow). Reserve sam sync for personal dev stacks.
• Pick the right policy template, then verify it against the code’s actual actions. Never fall back to dynamodb:*/s3:* on *; if no template fits, write a scoped inline Statement.
• Prefer HttpApi over Api unless you need a REST-only feature (VTL, API keys, caching, private endpoints, WAF).
• Put shared config in Globals (runtime, memory, timeout, tracing, common env vars) and override per-function only where it differs — but know Globals’ supported types.
• Turn on Tracing: Active and structured logging from day one; sam traces/sam logs are only as good as what you emit.
• Use arm64 (Graviton) for new functions — cheaper and usually faster; only stay on x86_64 for an incompatible native dependency.
• Build reproducibly in CI with --use-container so the artifact matches the Lambda runtime exactly, and split sam package / sam deploy if your pipeline separates artifact-build from release.
• Keep samconfig.toml in git but never put secrets in it or in parameter_overrides; use SSM Parameter Store / Secrets Manager dynamic references instead.
• Graduate from SimpleTable to raw AWS::DynamoDB::Table the moment you need a sort key, GSI, streams or TTL — in the same template.
• Reference the implicit API by its real logical ID (ServerlessHttpApi / ServerlessRestApi), or declare an explicit API resource when you need to configure it.
• Run sam validate --lint in CI to catch shorthand and property errors before the server-side transform does.
• Pin runtime and SDK versions; a silent runtime bump can change behaviour on the next build.

Security notes

SAM’s security story is mostly IAM ergonomics plus CloudFormation’s guarantees, and the controls are the ones that keep a serverless app least-privileged and auditable:

The single highest-value habit is the policy-template discipline: because SAM makes a scoped role a one-liner, there is no longer any excuse for the wildcard roles that raw-CloudFormation fatigue used to produce. Read each function’s code, grant exactly its actions on exactly its resources, and let the generated per-function role isolate blast radius.

Cost & sizing

SAM itself is free — you pay only for what the stack deploys. The cost drivers are the runtime resources, and the sizing levers are the function properties:

Sizing guidance and free-tier reality:

For the lab in this article, the total cost at test volume rounds to zero — a few dozen invocations, a few DynamoDB requests, a megabyte of logs and a tiny S3 object, all inside the free tier. In INR terms a light dev app that stays within the always-free Lambda and first-million HTTP-API tiers is often ₹0–₹50/month; the bill only grows when real traffic, verbose logging, or an under-sized memory setting (paying for long durations) kicks in. The performance-and-cost dials live in AWS Lambda Memory, Timeout & Concurrency Tuning — SAM just makes them one-line properties.

Interview & exam questions

1. What exactly is AWS SAM? A CloudFormation transform (AWS::Serverless-2016-10-31) plus a CLI. The transform is a macro that expands short-hand AWS::Serverless::* resource types into full CloudFormation at deploy time; a SAM template is therefore a superset of a CloudFormation template. (DVA-C02)

2. Why does deploying a SAM template need CAPABILITY_AUTO_EXPAND? Because SAM is implemented as a macro, and CloudFormation requires CAPABILITY_AUTO_EXPAND to run any macro that rewrites your template — on top of CAPABILITY_IAM for the roles SAM generates. The sam CLI passes both automatically. (DVA-C02)

3. What does AWS::Serverless::Function expand into? At minimum an AWS::Lambda::Function, an AWS::IAM::Role (with a trust policy and your Policies), and a LogGroup; plus, per Events entry, the trigger resources and the AWS::Lambda::Permission/event-source-mapping that wire it. (DVA-C02)

4. When would you choose Serverless::Api over Serverless::HttpApi? When you need a REST-only feature: VTL request/response mapping, API keys and usage plans, response caching, private (VPC) endpoints, or native WAF/edge integration. Otherwise HttpApi is cheaper, faster and the default. (SAA-C03, DVA-C02)

5. What are policy templates and why prefer them? Named, parameterized least-privilege IAM snippets (e.g. DynamoDBCrudPolicy: {TableName: …}) that expand to a scoped inline policy on the function’s role. They make correct least-privilege a one-liner instead of hand-written IAM, reducing the temptation to use wildcards. (SCS-C02, DVA-C02)

6. What’s the difference between sam deploy and sam sync? sam deploy packages to S3, expands the transform and drives a full CloudFormation change set (minutes) — the way you ship. sam sync (Accelerate) is a dev inner loop: for code-only changes it calls the service API directly (UpdateFunctionCode), skipping CloudFormation for a seconds-fast update, at the cost of possible drift — never for prod. (DVA-C02)

7. What does Globals do and what are its limits? It sets default properties applied to every resource of a supported type (Function, Api, HttpApi, SimpleTable, StateMachine). Per-resource properties override globals. It does not cover every property (e.g. not Policies/Events on functions) or every resource type. (DVA-C02)

8. How do you use a raw CloudFormation resource in a SAM template? Just declare it — a SAM template is CloudFormation, so AWS::S3::Bucket or a full AWS::DynamoDB::Table with a GSI coexists with shorthand, and you cross-reference with !Ref/!GetAtt. This is how you handle anything SAM’s shorthand doesn’t express. (DVA-C02, SAP-C02)

9. Your S3-triggered function never runs and has no logs. Diagnose it. No logs means it never invoked; the usual cause is a wrong Events shape so no AWS::Lambda::Permission was generated. Confirm with aws lambda get-policy --function-name <fn> — a missing source permission proves the wiring. Fix the Events block and redeploy. (DVA-C02)

10. SAM vs CDK — how do you choose? SAM for serverless-first apps that value minimal YAML and a great local loop (sam local, sam sync); CDK when infrastructure is complex enough that authoring it as real typed code with constructs, loops and grant* methods pays off. Both compile to CloudFormation. (SAP-C02)

11. What’s a SimpleTable and when do you outgrow it? A DynamoDB table with a single partition key and on-demand billing, expressed in a few lines. You outgrow it the instant you need a sort key, a GSI, streams or TTL — then switch to raw AWS::DynamoDB::Table in the same file. (DVA-C02)

12. How does SAM support CI/CD? sam pipeline bootstrap provisions per-stage IAM roles and artifact resources; sam pipeline init generates a pipeline definition for your CI provider (GitHub Actions, GitLab, Jenkins, CodePipeline). Combined with --config-env, you promote the same artifact across environments through reviewed sam deploys. (DVA-C02, SAP-C02)

Quick check

1. What single line turns a CloudFormation template into a SAM template, and what capability does deploying it therefore require?
2. Name the resource type that expands into a Lambda function plus its role, log group and event wiring.
3. Why might a function pass every test yet throw AccessDeniedException in production, and how do you confirm which action is denied?
4. What is the key operational difference between sam deploy and sam sync, and why is sam sync unsafe for prod?
5. A function’s HttpApi event route works, but !Ref ServerlessHttpApi in Outputs errors. What’s going on?

Answers

1. Transform: AWS::Serverless-2016-10-31; because it is a macro, deploying it requires CAPABILITY_AUTO_EXPAND (plus CAPABILITY_IAM for the generated roles).
2. AWS::Serverless::Function — it expands into AWS::Lambda::Function + AWS::IAM::Role + LogGroup + per-event trigger resources and AWS::Lambda::Permission.
3. A policy template scoped too narrow (e.g. DynamoDBReadPolicy on a function that also writes) passes read tests and fails on the first write; confirm with sam logs --name <Fn> --tail and read the exact dynamodb:* action the SDK error names, then use the Crud variant or an inline statement.
4. sam deploy drives a full CloudFormation change set (the way you ship); sam sync pushes code-only changes directly to the Lambda service, skipping CloudFormation for a seconds-fast dev loop — which causes drift from the template, so it’s dev-only.
5. You are referencing the wrong logical ID — this errors only if the routes are actually on an explicit API you declared (or none exists); when routes use an implicit API, SAM creates it as ServerlessHttpApi, which is exactly what you reference. Use sam list resources to see the real logical ID.

Glossary

Next steps

• Build the Lambda underneath the shorthand by hand first: Your First AWS Lambda Function: Handlers, Triggers, Roles & Logs Hands-On.
• Go deep on the API layer SAM’s Events generates: Amazon API Gateway Hands-On: REST vs HTTP APIs, Authorizers & Throttling.
• Learn the engine underneath SAM: AWS CloudFormation: Your First Stack Hands-On.
• Compare the imperative alternative that generates CloudFormation from code: AWS CDK with TypeScript: Infrastructure as Code Hands-On.
• Tune the functions SAM deploys: AWS Lambda Memory, Timeout & Concurrency Tuning.