SOMOD serverless/template.yaml

The developer creates the serverless resources in /serverless/template.yaml. The SOMOD build command will validate the /serverless/template.yaml and generate /build/serverless/template.json. When preparing AWS SAM's template.yaml, The SOMOD prepare command combines templates from all dependency modules.

There is a difference between /serverless/template.yaml and /template.yaml. /serverless/template.yaml is created by the module developer and adheres to SOMOD's template anatomy. Whereas /template.yaml is generated by SOMOD's prepare command to match the anatomy of AWS SAM's template.yaml.

Anatomy of the serverless/template.yaml

SOMOD defines the anatomy of the serverless/template.yaml with reusability in focus.

SOMOD's serverless/template.yaml file closely follows the structure of an AWS SAM template file, which is described in the Template Anatomy Section of AWS SAM Documentation. The primary difference is that SOMOD's template has only two section, Resources and Outputs.

Resources

This section is similar to the Resources section of AWS SAM templates.

Resources:
  MyResource1: # Resource Logical Id
    Type: AWS::Serverless::Function # Type of the resource
    Properties:
      # Properties of the Resource

In the prepared SAM template.yaml, the resource logical ids must be unique.

SOMOD Generates resource ids in SAM template using the following formula

SAMResourceLogicalId = "r" + (1st 8 characters in the sha256 hash of the module name) + SOMODResourceLogicalId

Keywords

Keywords helps to pre-process the template before creating the final SAM template.yaml. Along with Common Keywords, SOMOD defines following keywords for serverless/template.yaml

• SOMOD::DependsOn
  Replaces AWS Cloudformation DependsOn attribute

  Resources:
    MyResource1:
      Type: ValidResourceType
      # SOMOD::DependsOn must be used only as a property of a Resource
      SOMOD::DependsOn: # list of dependency {module, resource} tuplets
        - module: my-module
          resource: MyResource2
        - resource: MyResourceInSameModule # module is optional, when not provided same module is considerred
      Properties:
        # ...
  

• SOMOD::Extend
  In SOMOD, a module can extend a resource created in the dependency module to alter its properties

  Resources:
    MyResource1:
      Type: ValidResourceType
      # SOMOD::Extend must be used only as a property of a Resource
      SOMOD::Extend: # This resource is not included in prepared template, instead its properties are merged with the extended resource
        module: my-module
        resource: MyResource2
      Properties:
        # ...
  

• SOMOD::Output
  Each Resource in the AWS SAM template specification has some return values. Other resources can refer to these return values. SOMOD::Output restricts which of the return values are to be referred.

  Resources:
    MyResource1:
      Type: ValidResourceType
      # SOMOD::Output must be used only as a property of a Resource
      SOMOD::Output:
        default: true # if true, default return value can be referred
        attributes: [] # list of attributes to refer to. This must be a subset of what actual Resource returns
      Properties:
        # ...
  

  Check the SOMOD::Ref keyword to know on how to refer the output values.

• SOMOD::Access
  SOMOD::Access controls the accessibility of SOMOD resources. It has three levels of access.

  Resources:
    MyResource1:
      Type: ValidResourceType
      # SOMOD::Access must be used only as a property of a Resource
      SOMOD::Access: module
      Properties:
        # ...
  

  1. module - Only the resources in the same module are allowed to refer to this Resource.
  2. scope - With this access, the Resource can be referenced by any modules in the same scope. The scope groups of similar modules under a single scope name. Read more about the scope in NPM documentation.
  3. public - Can be referenced from any module

  If not specified, scope is the default value. SOMOD::Access applies to references created using the following SOMOD keywords only. SOMOD::DependsOn, SOMOD::Extend, SOMOD::Ref.

• SOMOD::CreateIf
  Create the resource in prepared template.yaml only if the provided condition is truthy

  Resources:
    MyResource1:
      Type: ValidResourceType
      # SOMOD::CreateIf must be used only as a property of a Resource
      SOMOD::CreateIf:
        # any SOMOD common keywords
      Properties:
        # ...
  

• SOMOD::Ref
  Replaces Ref and Fn::GetAtt to refer to other resources. SOMOD::Ref can refer to resources in the same or other dependency modules.

  Resources:
    MyResource1:
      Type: ValidResourceType
      Properties:
        Prop1:
          # SOMOD::Ref can be used in the places where the value has to be read from the output of another resource
          SOMOD::Ref:
            module: my-module
            resource: MyResource2
            attribute: Name
        # ...
  

  In the prepared template, SOMOD generates Fn::GetAtt when the attribute is referred, otherwise generates Ref.

  Use AWS CloudFormation's Ref to refer to Pseudo Parameters

• SOMOD::ResourceName
  Use it to generate a unique resource name.

  Resources:
    MyResource1:
      Type: ValidResourceType
      Properties:
        Name:
          # SOMOD::ResourceName can be used to define the name of the resource being created, example DynamoDb Table name, Lambda Function Name, ...etc
          SOMOD::ResourceName: MyResource
        # ...
  

  When deployed, the physical resource names must be unique withh in an AWS Account.

  SOMOD Generates resource name in SAM template using the following formula

  SAMResourceName = "somod"+ CloudFormationStackId + (1st 8 characters in the sha256 hash of the module name) + SOMODResourceName
  

  SOMOD prepare command replaces the SOMOD::Parameter object with the parameter value from parameters.json.

• SOMOD::Function
  For a Resource of type AWS::Serverless::Function, CodeUri Property must be SOMOD::Function.

  Resources:
    MyResource1:
      Type: AWS::Serverless::Function
      Properties:
        CodeUri:
          # SOMOD::Function must be used only as a value of CodeUri property of AWS::Serverless::Function
          SOMOD::Function:
            name: getUser
            customResources: # If this function provides Custom resources, define the JSONSchema for each Custom Resource Type provided by this function
              MyCustomResource:
                # valid schema for a Custom resource Properties
        # ...
  

  • The name must be the filename under the serverless/functions directory (excluding the extension).
  • If a function defines the code for Custom Cloudformation Resources, the developer can specify the schema of the custom resource using the customResources property. The customResources is a map of Custom Resource Name to Schema.

  SOMOD prepare command bundles the function at .somod/serverless/function/{moduleName}/{functionName} path

  In the prepared template, SOMOD replaces this keyword with the directory path of the bundled function

• SOMOD::FunctionLayer
  For a Resource of type AWS::Serverless::LayerVersion, ContentUri Property must be SOMOD::FunctionLayer.

  Resources:
    MyResource1:
      Type: AWS::Serverless::LayerVersion
      Properties:
        ContentUri:
          # SOMOD::FunctionLayer must be used only as a value of ContentUri property of AWS::Serverless::LayerVersion
          SOMOD::FunctionLayer:
            name: getUser
            libraries: # list of npm libraries to pack inside the layer.
              - my-lib1
            content: # Map of file path to file content
              "/path/to/my/content1": "MyFileContent1",
              "/path/to/my/content1":
                # Any valid Common SOMOD keywords to get the content
        # ...
  

  • layer name must be provided

  • libraries must have a list of npm library names as a value. The prepare command generates the content of the layer at .somod/serverless/functionLayers/{moduleName}/{layerName}. All of the libraries must be in the devDependecies of the current module to help the SOMOD to pick up the specific version during build.

  • files from content are created under layer directory .somod/serverless/functionLayers/{moduleName}/{layerName}

    either of libraries or content must be provided

    In the prepared template, SOMOD replaces this keyword with the directory path of the bundled functionLayer

Let us understand how to work with Lambda Functions in our next chapter.