sam-patterns-cli

DEPRECATION NOTICE - This tool has been renamed as samp-cli. samp-cli contains all the features of sam-patterns-cli as well as all future features. To install, run npm i -g samp-cli.

Note: this is an early version of a CLI backed by an early version of a community driven resource; https://serverlessland.com/patterns/. There might be bugs

This tool lets you browse the content of the Serverless Patterns Collection and Serverless Workflow Collection and inject patterns directly into your SAM template. Support for both JSON and YAML.

Installation

npm install -g sam-patterns-cli

Acquire a Github access token from here and either store it in environment variable GITHUB_TOKEN or configure the tool using sam-patterns configure --github-token <token> (recommended). This is not strictly required, but if you don't you'll be rate limited to 60 requests per hour. Note that SSH auth is not supported by by the OctoKit SDK.

Usage

sam-patterns init

Initialises a SAM project based on a cookiecutter template. By default the tool gives access to the same AWS managed templates that are used by sam-cli.

You can add custom template locations by using the --add-repository flag.

Usage: sam-patterns init [options]

Initialises a SAM project from a quick-start template. See https://github.com/aws/aws-sam-cli-app-templates for examples and structure.

Options:
  -r, --add-repository  GitHub repository where your templates are located (default: false)
  -h, --help            display help for command

sam-patterns import

Imports a serverless pattern into an existing template. You can merge one or more resources in the imported pattern with existing resources in your template by adding the --merge flag to, for example, combine sqs-lambda and lambda-dynamodb as one sqs-lambda-dynamodb pattern.

Usage: sam-patterns import|i [options]

Imports a pattern from https://github.com/aws-samples/serverless-patterns/

Options:
  -t, --template [template]            SAM template file (default: "template.yaml")
  -m, --merge                          Merge pattern with existing template resource(s) (default: false)
  -a, --asl-format [asl-format]        Output format for StepFunctions ASL definitions (YAML or JSON) (default: "YAML")
  -f, --source-filter [source-filter]  Filter text to match against source collection names. Optional (default: "")
  -h, --help                           display help for command

sam-patterns invoke

Invokes a Lambda function or StepFunctions state machine in your CloudFormation stack. If a samconfig.toml file is present, it will use the stack name and region from that file. Otherwise you will have to specify them using the --stack-name and --region flags.

You can pass a variety of inputs to the function / state machine:

• A path to a local JSON file
• JSON string
• Shared Lambda test event. These test events become available for other developers with access to the same AWS account. This command also introduces the same sharable test events for StepFunctions.
• For StepFunctions, you can select to re-run the input from a recent execution from the state machine.

Usage: sampat invoke|in [options]

Invokes a Lambda function or a StepFunctions state machine

Options:
  -s, --stack-name [stackName]  The name of the deployed stack. Optional if a samconfig.toml file is present
  -pl, --payload [payload]      The payload to send to the function. Could be stringified JSON,
                                a file path to a JSON file or the name of a shared test event. Optional
  -p, --profile [profile]       AWS profile to use. Optional (default: "default")
  --region [region]             The AWS region to use. Falls back on AWS_REGION environment
                                variable if not specified
  -h, --help                    display help for command

sam-patterns local

This lets you test your Lambda functions locally with real events from your AWS account. You can step through your code using breakpoints and enjoy sub-second code reloads on changes. If a samconfig.toml file is present, it will use the stack name and region from that file. Otherwise you will have to specify them using the --stack-name and --region flags.

• NOTE: this command temporarily replaces your function code in the cloud with a proxy function that relays events to your local machine over AWS IoT (MQTT). Please only use on development stacks. Never use on production functions! *

Usage: sampat local|l [options]

Sets up a debugging session where the Lambda invocations in the cloud gets executed on your local machine

Options:
  -s, --stack-name [stackName]  The name of the deployed stack
  -fr, --force-restore          Force restore of the original Lambda code (default: false)
  -p, --profile [profile]       AWS profile to use
  --region [region]             The AWS region to use. Falls back on AWS_REGION environment variable if not
                                specified
  -h, --help                    display help for command

The --force-restore flag is useful if you want to restore the original Lambda code in the cloud after you've finished debugging. This is normally done automatically when you finish your session (CTRL+C), but in the case of a crash or unexpected exit, you can use this flag to restore the original code.

Debugging with VS Code

sam-patterns explore

Lets you browse and explore your serverless patterns repositories.

Usage: sam-patterns explore|e [options]

Explores and visualises patterns from https://github.com/aws-samples/serverless-patterns/

Options:
  -h, --help  display help for command

sam-patterns console

Launches the AWS console for the selected SAM resource. If a samconfig.toml file is present, it will use the stack name and region from that file. Otherwise you will have to specify them using the --stack-name and --region flags.

Usage: sampat console|c [options]

Opens the AWS console for a deployed resource in your SAM template.

Options:
  -t, --template-file [templateFile]  Path to SAM template file (default: "template.yaml")
  -s, --stack-name [stackName]        The name of the deployed stack
  -p, --profile [profile]             AWS profile to use (default: "default")
  --region [region]                   The AWS region to use. Falls back on AWS_REGION environment variable if not specified
  -h, --help                          display help for command

![Demo](images/demo-console.gif

sam-patterns generate

Generates SAM resources, CDK code, StepFunctions ASL and Lambda functions in any language based on a query to ChatGPT. If you ask for SAM resources, it will merges them into your existing template.

This is an experimental feature and requires a ChatGPT API key. You can get one here. Make sure to validate the output before deploying your template as it might contain errors or things that could incur cost

Usage: sampat generate|g [options]

Generates resources from a ChatGPT response

Options:
  -t, --template [template]         SAM template file (default: "template.yaml")
  -q, --query [query]               Question to ask ChatGPT. I.e "a lambda function that's triggered by an S3 event"
  -m, --model [model]               OpenAI model to use. Valid values are 'gpt-3.5-turbo' and 'gpt-4'. Note that gpt-3.5-turbo is fine for
                                    most use cases and that gpt-4 is slower and more expensive (default: "gpt-3.5-turbo")
  -o, --output [output]             Output feature. Valid values are 'SAM', 'CDK', 'lambda-<language>' or 'ASL'. If not 'SAM', set
                                    --output-file (default: "SAM")
  -of, --output-file [output-file]  Output file. Only applicable if --output is CDK
  -h, --help                        display help for command

Examples

• To generate SAM resources for a Lambda function that reads off a DynamoDB table: sam-patterns generate -q "a lambda function that reads off a dynamodb table"
• To generate a CDK stack for the same: sam-patterns generate -q "a lambda function that reads off a dynamodb table" --output CDK --output-file cdk-stack.ts
• To generate a Lambda function in Rust that reads off a DynamoDB table: sam-patterns generate -q "a lambda function that reads off a dynamodb table" --output lambda-rust --output-file lambda.py
• To generate a StepFunctions ASL definition that reads off a DynamoDB table: sam-patterns generate -q "a lambda function that reads off a dynamodb table" --output ASL --output-file asl.yaml

Note that quality of results may vary and that you sometimes have to run the command a few times to get a good result.

sam-patterns describe

Describes a pattern using ChatGPT and gives suggestions on how to improve security.

Usage: sampat describe|d [options]

Describes a SAM template using ChatGPT

Options:
  -t, --template [template]           SAM template file (default: "template.yaml")
  -r, --repository-path [repository]  Github repository path, i.e "aws-samples/serverless-patterns/apigw-sfn"
  -m, --model [model]                 OpenAI model to use. Valid values are 'gpt-3.5-turbo' and 'gpt-4'. Note that gpt-3.5-turbo is fine for most use cases and that gpt-4 is slower and more expensive (default: "gpt-3.5-turbo")
  -h, --help                          display help for command

sam-patterns source

Lets you add more sources. This could be public repositories, such as Jeremy Daly's Serverless Reference Architectures or a private repository for company specific patterns.

Example how to add Jeremy Daly's reference architectures as a source:

? GitHub owner: serverless-architecture
? GitHub repo: reference-architectures
? Root: folder /
? Relative path to template file: /sam
? Template filename(s): template.yaml,template.yml
? URL (use #PATTERN_NAME# as placeholder): https://jeremydaly.com/the-#PATTERN_NAME#-pattern

The configuration gets stored in ~/.sam-patterns-cli/settings.json

If you create your own collection you need to follow this structure:

  The repository should follow the following structure. (README.md is optional):
  ├── pattern-1
  | ├── README.md
  │ └── template.yaml
  ├── pattern-2
  | ├── README.md
  │ └── template.yaml
  └── pattern-3
    ├── README.md
    └── template.yaml

sam-patterns policy

Lets you quickly build IAM polices, find SAM policy templates or generate SAM Connectors based on the resources you have in your template. The generated policy can be attached to supported resource types.

Usage: sam-patterns policy|p [options]

Opens a wizard thet help you to create and attach a new IAM policy to a resource in your template

Options:
  -t, --template <filename>         Template file name (default: "template.yaml")
  -f, --format <JSON|YAML>          Output format (default: "JSON")
  -o, --output <console|clipboard>  Policy output (default: "console")
  -h, --help                        display help for command

sam-patterns return-values

Lets you browse the return values of a resource and send the intrinsic function that retrieves it to your stdout or clipboard

Usage: sampat return-values|rv [options]

Browses the return values and the intrinsic functions of a CloudFormation/SAM resource

Options:
  -t, --template [template]  SAM template file (default: "template.yaml")
  -c, --clipboard            Send the return value's intrinsic function to the clipboard (default: false)
  -h, --help                 display help for command

sam-patterns share

Lets you share patterns from an existing CloudFormation/SAM template with the world or your colleagues.

Example usage

In this example we have a stack with the following resources:

• OrderPutFunction [AWS::Serverless::Function]
• OrderTable [AWS::DynamoDB::Table]
• MySnsTopic [AWS::SNS::Topic]
• EventRule [AWS::Events::Rule]
• EventBridgeToToSnsPolicy [AWS::SNS::TopicPolicy]

We've identified that OrderPutFunction and OrderTable together make up a reusable pattern that we want to share, so we run sam-patterns share:

We select the components making up our pattern and hit .

Next, we want to make the pattern generic so the developer importing it can customise it their way. In this case we created the pattern from an stack dealing with 'order' items. The next user of this pattern might work on a stack bound to 'products'.

From a quick look at the resources we can see a pattern that they both start with Order. The rest of their names are generic and is referring to the resource type, so we select Order.

Now we're prompted to name the placeholder for 'Order'. Here is a good idea to use something unique and not a short string like 'My'. This is because the import command will make a naive find/replace on the placeholder name.

Next we're asked to enter a string prompting the user to set the value. You can hit for the default string Set value for 'MyItem' placeholder.

We want to change some default values of some properties or make some values customisable for the user during import. Here we get prompted with a flattened list of the components we've chosen.

Once done, hit Done, select a name for the pattern and a source where to commit it to. Note that your GITHUB_TOKEN needs permission to push to the selected repository. Refer to sam-patterns source on how to link repositories.

The new pattern has now been pushed and is ready to be used by someone else using sam-patterns import

NOTE If you create patterns that aren't specific to your business use cases, please consider sharing them with the community over at Serverless Pattern Collection

Customise pattern imports using placeholders and property manipulation

Say you host a pattern that creates an SQS queue and a Lambda function and sets the queue as an event source:

AWSTemplateFormatVersion: 2010-09-09
Transform:
  - AWS::Serverless-2016-10-31
Resources:
  The_Consumer:
    Type: AWS::Serverless::Function
    Properties:
      Runtime: nodejs14.x
      CodeUri: src/
      Handler: The_Consumer.handler
      Timeout: 3
      Events:
        SQS:
          Type: SQS
          Properties: 
            BatchSize: 10
            Queue: !GetAtt The_Queue.Arn
  The_Queue:
    Type: AWS::SQS::Queue

When a user of this snippet imports it into their template they are likely to jump straight at renaming the resources to something that semantically describes the type of messages the queue is handling. Also, the runtime is likely to be something different.

As a pattern producer you can help out with this by defining a Metadata object on the pattern template:

Metadata:
  PatternTransform:
    Placeholders:
      - Placeholder: The_
        Message: Message type
    Properties:
      - JSONPath: $.Resources.The_Consumer.Properties.Events.SQS.Properties.BatchSize
        InputType: number
        Message: Enter batch size
      - JSONPath: $.Resources.The_Consumer.Properties.CodeUri
        InputType: string
        Message: Enter CodeUri

PatternTransform.Placeholders (array)

• Placeholder: the string to be replaced
• Message: A message to be displayed (optional)

PatternTransform.Properties (array)

• JSONPath: The JSONPath to the property to be modified
• Message: A message to be displayed (optional)
• InputType: The datatype. Currently supports string, number or runtime-select

The input type runtime-select lets the user select a valid Lambda runtime. This metadata is automatically applied to all patterns, so there's no need to explicitly add it. If the user always writes code in a specific language they can export environment variable SAM_PATTERNS_DEFAULT_RUNTIME to a valid Lambda runtime identifier.

Known issues and limitations

• Comments in YAML disappear when parsing the template
• Only content from the template.yaml file will be imported. Any supporting files like lambda functions or openapi schemas will be skipped.
• Only works with SAM templates