Further Sections of 'template.yaml'
After the transformation comes the template description:
Sample SAM Template for sam-app
Description section contains a free-form explanation of the template. This section is useful if you want to publish the template or give it to another team, but it isn’t necessary. You can safely skip it when creating templates for small experiments.
YAML files usually contain text values on the same line as the corresponding key. You can use the right angle bracket (
>) or a pipe (
|) to signal that what follows is multi-line text, indented one level. The difference is that
>removes line breaks from the result, and
|preserves line breaks.
After the description, the example SAM template contains global application settings. This is a SAM-specific extension to CloudFormation and enables you to reduce the overall template file size by listing common settings in a single place instead of repeating them for each Lambda function. The example template contains just a single function, so adding global values doesn’t make a lot of difference, but this section is useful for more complex applications. The sample template usually contains a global
Timeout setting, the number of seconds the function is allowed to run in Lambda:
Next comes the
Resources section, which lists the services or resources for CloudFormation to configure:
This is where things become really interesting. With CloudFormation, each resource starts with its own block. The first line specifying a resource is the logical ID of the resource. In the sample template,
HelloWorldFunction is a logical ID of a Lambda function. The logical ID is an internal name that CloudFormation uses to refer to a resource in a single template. It is effectively a variable name, and you can use it to refer to a resource when connecting it with other resources within the same template.
CloudFormation will create the actual (‘physical’) function name using a randomised string based on the logical ID. This makes it possible to create several instances of the same infrastructure in a single AWS account (for example, for development, testing and production), without causing any resource conflicts.
CloudFormation allows you to specify names for many resource types, including functions, using the
Nameproperty. Unless there is a very specific reason why you need this, avoid setting physical names. Letting CloudFormation set random names makes it easy to create several stacks based on the same template and avoid resource naming conflicts.
Each resource needs to specify a
Type property which tells CloudFormation what to create. For the
HelloWorldFunction, the type is
AWS::Serverless::Function. This is another SAM extension to CloudFormation, making it easy to set up Lambda functions. You will almost always use this type when creating Lambda functions with SAM.
Following the type, a template usually lists configuration properties for a resource, depending on its type. The following three properties are required for a Lambda function:
CodeUripoints to the source code package for the function. This is usually a local directory with the source code, relative to the SAM template file.
Runtimeis the execution engine for the function.
Handleris the main execution entry point.
The Lambda handler is the main function responsible for processing incoming requests. The format of this setting depends on the runtime type. For Node.js, the format is
moduleis the file name (without the
.jsextension). The previous example points at
app.lambdaHandler, meaning the function
Serverless functions can have some other properties, which will be introduced in the following chapters. For now, only the
Events property is important. Lambda functions usually run in response to some external events. The
Events property configures a set of triggers for the function. Structurally, this property resembles the main
Resources section. Each event has a logical ID followed by
Properties, which are type-specific event configuration attributes.
The example template sets up an HTTPS service, so it automatically declares an
Api event type. This represents API Gateway, an AWS service that can accept client HTTP requests. You will use a browser to send HTTPS requests to API Gateway, and the gateway will pass requests to your Lambda function. For
Api event types, it’s important to specify the HTTP method and request path. The example template sets up a Lambda call when clients request the
/hello path, using the
This template involves another AWS service, which is not explicitly listed. It is called Identity and Access Management (IAM). IAM lets you configure access policies for AWS resources. If you just create a Lambda function without configuring IAM, no other AWS service will be allowed to invoke it. To actually make the function do something useful, you need to let IAM know who is allowed to send requests to it. SAM makes this easy because it will automatically set up the correct security privileges from event definitions. Because you have a single event configured to invoke a Lambda function from API Gateway, SAM will tell IAM to allow this connection automatically.