Query Syntax


The file lookup type allows the loading of arbitrary data from files. The lookup additionally supports using a codec to parse and/or manipulate the file contents prior to returning it. The parameterized-b64 codec is particularly useful to allow the interpolation of CloudFormation parameters in a UserData attribute of an instance or launch configuration.

If the file can be read locally, the <data> portion of the query should look something like file://./path/to/file. The file:// prefix tells CFNgin that it needs to open the file located at the provide path and read it’s contents before continuing. For a relative path, it will be relative to the current working directory (usually the root of the CFNgin module being processed).

If <data> is not prefixed with file://, it will be treated as the contents of the file. This enables lookups to be chained together to retrieve data and still take advantage of a codec to further parse and/or manipulate it as needed. For example, the value of an SSM Parameter can be parsed as json-parameterized before it is returned by the lookup with the following ${file json-parameterized:${ssm /parameter/name}}.

Supported Codecs

  • plain - Load the contents of the file untouched. This is the only codec that should be used with raw Cloudformation templates (the other codecs are intended for blueprints).

  • base64 - Encode the plain text file at the given path with base64 prior to returning it.

  • parameterized - The same as plain, but additionally supports referencing CloudFormation parameters to create userdata that’s supplemented with information from the template, as is commonly needed in EC2 UserData. For example, given a template parameter of BucketName, the file could contain the following text:

    aws s3 sync s3://{{BucketName}}/somepath /somepath

    and then you could use something like this in the YAML config file:

    UserData: ${file parameterized:file://path/to/file}

    resulting in the UserData parameter being defined as:

        "Fn::Join" : [
                "#!/bin/sh\naws s3 sync s3://",
                    "Ref" : "BucketName"
                "/somepath /somepath"
  • parameterized-b64 - The same as parameterized, with the results additionally wrapped in { "Fn::Base64": ... }, which can be used as EC2 UserData.

    When using parameterized-b64 for UserData, you should use a parameter defined as such.

    from troposphere import AWSHelperFn
    "UserData": {
        "type": AWSHelperFn,
        "description": "Instance user data",
        "default": Ref("AWS::NoValue")

    Then set UserData in a LaunchConfiguration or Instance to self.variables["UserData"]. Note that we use AWSHelperFn as the type because the parameterized-b64 codec returns either a Base64 or a GenericHelperFn troposphere object.

  • json - Decode the file as JSON and return the resulting object.

  • json-parameterized - Same as json, but applying templating rules from parameterized to every object value. Note that object keys are not modified.

    Example (an external PolicyDocument):

        "Version": "2012-10-17",
        "Statement": [
                "Effect": "Allow",
                "Action": [
                "Resource": "{{MyResource}}"
  • yaml - Decode the file as YAML and return the resulting object.

  • yaml-parameterized - Same as json-parameterized, but using YAML.

    Version: 2012-10-17
      - Effect: Allow
          - "some:Action"
        Resource: "{{MyResource}}"


# We've written a file to /some/path:
$ echo "hello there" > /some/path

# In CFNgin we would reference the contents of this file with the following
conf_key: ${file plain:file://some/path}

# The above would resolve to
conf_key: hello there

# Or, if we used wanted a base64 encoded copy of the file data
conf_key: ${file base64:file://some/path}

# The above would resolve to
conf_key: aGVsbG8gdGhlcmUK