AWS SAM skill for Codex

Done well means: the template passes sam validate --lint, every function can be invoked locally with a realistic event, dev iterates with sam sync while staging and production deploy only through reviewed change sets, and production functions shift traffic gradually with alarms that roll back.

Before changing anything

1. Read AGENTS.md, template.yaml (or template.yml), samconfig.toml and each function’s CodeUri folder with its lockfile.
2. Check the toolchain: sam --version, Docker running (docker info) for local emulation and container builds, the language runtime locally for non-container builds.
3. Run sam validate --lint and sam build on the untouched project to know the baseline. sam build with local runtimes works offline if dependencies are cached; it needs network to install packages, and --use-container needs network to pull images.

Template shape

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

Parameters:
  Stage:
    Type: String
    AllowedValues: [dev, staging, prod]

Globals:
  Function:
    Runtime: nodejs22.x
    Architectures: [arm64]
    MemorySize: 512
    Timeout: 10
    Tracing: Active
    LoggingConfig:
      LogFormat: JSON
    Environment:
      Variables:
        TABLE_NAME: !Ref OrdersTable
        POWERTOOLS_SERVICE_NAME: orders

Resources:
  OrdersApi:
    Type: AWS::Serverless::HttpApi

  CreateOrderFunction:
    Type: AWS::Serverless::Function
    Metadata:
      BuildMethod: esbuild
      BuildProperties:
        Minify: true
        Target: es2022
        Sourcemap: true
        EntryPoints: [src/handlers/create-order.ts]
    Properties:
      CodeUri: ./
      Handler: create-order.handler
      AutoPublishAlias: live
      DeploymentPreference:
        Type: Canary10Percent5Minutes
        Alarms: [!Ref CreateOrderErrorsAlarm]
      Policies:
        - DynamoDBWritePolicy:
            TableName: !Ref OrdersTable
      Events:
        Create:
          Type: HttpApi
          Properties:
            ApiId: !Ref OrdersApi
            Path: /orders
            Method: POST

  OrdersTable:
    Type: AWS::DynamoDB::Table
    DeletionPolicy: Retain
    UpdateReplacePolicy: Retain
    Properties:
      BillingMode: PAY_PER_REQUEST
      AttributeDefinitions: [{ AttributeName: pk, AttributeType: S }]
      KeySchema: [{ AttributeName: pk, KeyType: HASH }]

  CreateOrderLogs:
    Type: AWS::Logs::LogGroup
    Properties:
      LogGroupName: !Sub /aws/lambda/${CreateOrderFunction}
      RetentionInDays: 30

Outputs:
  ApiUrl:
    Value: !Sub https://${OrdersApi}.execute-api.${AWS::Region}.amazonaws.com

Rules:

• Put shared function settings in Globals; override per function only where needed.
• Permissions: SAM policy templates (DynamoDBReadPolicy, DynamoDBCrudPolicy, SQSPollerPolicy, SQSSendMessagePolicy, S3ReadPolicy, SSMParameterReadPolicy) scope to one resource. AWS::Serverless::Connector expresses “function A writes to table B” and generates the policy. Avoid managed policies like AmazonDynamoDBFullAccess.
• DeletionPolicy: Retain and UpdateReplacePolicy: Retain on tables and buckets with data.
• Declare the log group yourself (as above) to control retention; on an existing stack whose function already created /aws/lambda/<name>, import or delete that group first (with confirmation) or the deploy fails with already exists.
• Esbuild builds need esbuild in the project’s dev dependencies (npm i -D esbuild).

Build decisions

Situation	Build with
TypeScript/JavaScript	BuildMethod: esbuild (bundled, tree-shaken)
Python with pure-Python deps	sam build (uses local Python matching the runtime)
Native deps, or local runtime differs from Lambda’s	sam build --use-container
Custom tooling (Rust, Go with flags, monorepo builds)	BuildMethod: makefile with a build-<LogicalId> target
Container image functions	PackageType: Image with Metadata: Dockerfile/DockerContext

sam build --cached --parallel speeds up repeated builds.

Local testing

sam build
sam local generate-event apigateway http-api-proxy > events/create-order.json   # edit body
sam local invoke CreateOrderFunction -e events/create-order.json --env-vars env.local.json
sam local start-api --port 3000           # HTTP routes on localhost, needs Docker
sam local start-lambda                    # Lambda endpoint for SDK-driven tests

env.local.json overrides environment variables per function:

{ "CreateOrderFunction": { "TABLE_NAME": "orders-local", "AWS_ENDPOINT_URL_DYNAMODB": "http://host.docker.internal:8000" } }

Local emulation runs the function code but not IAM, authorizers or real event source mappings. Test those in a deployed dev stack. Unit tests for handlers should not need SAM at all.

Deploy configuration

samconfig.toml holds per-environment settings so deploys are one short command:

version = 0.1

[default.global.parameters]
stack_name = "orders-dev"

[default.deploy.parameters]
resolve_s3 = true
capabilities = "CAPABILITY_IAM CAPABILITY_AUTO_EXPAND"
parameter_overrides = "Stage=dev"
confirm_changeset = false

[prod.deploy.parameters]
stack_name = "orders-prod"
resolve_s3 = true
capabilities = "CAPABILITY_IAM CAPABILITY_AUTO_EXPAND"
parameter_overrides = "Stage=prod"
confirm_changeset = true

Environment	Command	Notes
Personal dev stack	sam sync --stack-name orders-dev-$USER --watch	Fast code-only updates, bypasses CloudFormation for code; dev only
Shared dev	sam deploy	Uses [default]
Production	sam deploy --config-env prod	Change set shown for confirmation
CI	sam deploy --config-env prod --no-confirm-changeset --no-fail-on-empty-changeset	Only after review in the pipeline

Deploy workflow for staging and production:

• sam validate --lint passes
• Unit tests pass; sam build succeeds
• sam deploy --config-env prod creates the change set; read it for Replacement: True and deletions of stateful resources
• User approves the change set explicitly
• Watch the CodeDeploy deployment; the alarm-based rollback must stay enabled
• Smoke-test the outputs (sam list stack-outputs --stack-name orders-prod)

Never run sam sync against production: it skips change set review and creates drift. sam delete removes the whole stack; confirm the stack name with the user and check retained resources first.

Gradual deployments

AutoPublishAlias publishes a version per code change and points the alias at it. DeploymentPreference uses CodeDeploy to shift traffic: Canary10Percent5Minutes, Linear10PercentEvery1Minute, AllAtOnce and similar. Add:

• Alarms: error rate or latency alarms on the alias; an alarm in ALARM rolls back.
• Hooks.PreTraffic / PostTraffic: Lambda functions that run checks and report status with codedeploy:PutLifecycleEventHookExecutionStatus.

Event sources must target the alias (SAM wires this automatically when AutoPublishAlias is set).

Troubleshooting

Error	Fix
Requires capabilities : [CAPABILITY_AUTO_EXPAND]	Add it to capabilities (needed for the transform and nested apps)
Error: Unable to upload artifact ... S3 Bucket not specified	resolve_s3 = true or --s3-bucket
Binary validation failed for python	Install the runtime’s Python version locally or use --use-container
esbuild: not found	Add esbuild to devDependencies and install
Stack in ROLLBACK_COMPLETE on first deploy	It cannot be updated; delete it (with confirmation) and redeploy
No changes to deploy failing CI	--no-fail-on-empty-changeset
Local invoke cannot reach other containers	Use host.docker.internal or --docker-network

Read the failing resource’s status reason: aws cloudformation describe-stack-events --stack-name orders-prod --query "StackEvents[?contains(ResourceStatus,'FAILED')].[LogicalResourceId,ResourceStatusReason]" --output table.

Useful extras

• sam logs -n CreateOrderFunction --stack-name orders-dev --tail streams logs.
• sam remote invoke CreateOrderFunction --stack-name orders-dev --event-file events/create-order.json invokes the deployed function.
• sam pipeline init --bootstrap scaffolds CI pipelines with per-stage roles; review the generated IAM before using it.