file

Query Syntax: <supported-codec>:<data>

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:

#!/bin/sh
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": [
                "some: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
Statement:
  - Effect: Allow
    Action:
      - "some:Action"
    Resource: "{{MyResource}}"

Example

# 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