AWS CloudFormation Concepts Intrinsic Functions

From NovaOrdis Knowledge Base
Jump to navigation Jump to search

External

Intrinsic Function Reference

Internal

Overview

All intrinsic functions have full function name:

Fn::ImportValue: stack_output_export_name

and a short form:

!ImportValue stack_output_export_name

Note that because of ":" presence in the full function syntax, the full function forms cannot be used as YAML map values, as such:

SomeKey: Fn::ImportValue: something

The template validation will fail with:

An error occurred (ValidationError) when calling the CreateStack operation: Template format error: YAML not well-formed. (line 15, column 24)

To use the full function form, the value must be placed on a subsequent line, and indented as such:

SomeKey:
  Fn::ImportValue: something

There are situations when two short function names cannot be used together. The following will generate an invalid result:

...
LogGroupName: !Sub ${SomeParameter}-!ImportValue SomeOutput

Ref:, !Ref

Ref

The intrinsic function Ref: returns the value of the object it refers to, such as a parameter or resource. When a parameter logical name is specified, it returns the value of the parameter. When a resource logical name is specified, it returns a value that can be typically used to refer to that resource, such as a physical ID.

The full form of the function is:

Ref: reference

Note that Ref is the only intrinsic function that does not have a Fn::Name: as full form.

The short form of the function is:

!Ref reference

Note that no "${...}" should be used around the reference, the parser will actually detect that as syntax error.

Examples:

!Ref AWS::StackName
!Ref MyParameter
!Ref MyResourceName

Fn::Sub:, !Sub

Sub

The intrinsic function Fn::Sub: substitutes variables in an input string with specified values.

The full form of the function is:

Fn::Sub: ${reference1} is a ${reference2}

The short form of the function is:

!Sub ${reference1} is a ${reference2}

If only template parameters, resource logical IDs and resource attributes are substituted in the String parameter, no variable map is required:

!Sub '${TemplateParameterA} is a ${TemplateParameterB}'
!Sub '${AWS::Region}-something'

Fn::Sub: can be used as a replacement for Fn::GetAtt:, as it seems to extract the attributes of a resource and place them in a string just fine. This is an example of how to obtain the ARN of a resource created in the same template:

Using Sub to Configure the ARN of a Resource Created by the Template

Resources:

  # this resource has an ARN
  AccessLogGroup:
    ...

  ...
  
  # this resource needs the ARN
  Stage:
    Type: AWS::ApiGateway::Stage
    Properties:
      ...
      AccessLogSetting:
        DestinationArn: !Sub '${AccessLogGroup.Arn}'
        ...

Fn::GetAtt:, !GetAtt

GetAtt

An intrinsic function that returns arbitrary attributes of a resource (Ref returns just important value associated with the resource). The function takes two parameters: the logical name of the resource and the attribute to be retrieved, as an array.

Using GetAtt to Configure the ARN of a Resource Created by the Template

Resources:

  # this resource has an ARN
  AccessLogGroup:
    ...

  ...
  
  # this resource needs the ARN
  Stage:
    Type: AWS::ApiGateway::Stage
    Properties:
      ...
      AccessLogSetting:
        DestinationArn: !GetAtt AccessLogGroup.Arn
        ...

Fn::Join:, !Join

Join

The Fn::Join function takes two parameters, a delimiter that separates the values you want to concatenate and an array of values in the order that you want them to appear.

!Join [ delimiter, [ comma-delimited list of values ] ]
!Join ['-', [ a, b, c ]]
!Join ['-', !Split ['/', !Sub '${something}-something-else']]

returns "a:b:c"

Fn::Split:, !Spit

Split
!Split ['.', "www.example.com"]
!Split ['/', !Sub '${something}-something-else']

returns ["www", "example", "com"].

Fn::Select:, !Select

Select

Fn::ImportValue:, !ImportValue

ImportValue

The Fn::ImportValue returns the value of an output exported by another stack. The function is used to create cross-stack references.

Can be used as a key in a YAML structure:

...
ServiceRole:
  Fn::ImportValue: ...

or a value:

...
EnvironmentVariables:
  - Name: TARGET_BUCKET
     Value:
       Fn::ImportValue: !Sub '${AWS::Region}-BuildBucket'

Fn::FindInMap:, !FindInMap

!FindInMap [ MapName, TopLevelKey, SecondLevelKey ]