aws functions

The functions in the aws namespace interface with various Amazon Web Services APIs to make it possible for a template to render differently based on the AWS environment and metadata.

Configuring AWS

A number of environment variables can be used to control how gomplate communicates with AWS APIs. A few are documented here for convenience. See the aws-sdk-go documentation for details.

Environment Variable	Description
`AWS_ANON`	Set to `true` when accessing services that do not need authentication, such as with public S3 buckets. Not part of the AWS SDK.
`AWS_TIMEOUT`	(Default `500`) Adjusts timeout for API requests, in milliseconds. Not part of the AWS SDK.
`AWS_PROFILE`	Profile name the SDK should use when loading shared config from the configuration files. If not provided `default` will be used as the profile name.
`AWS_REGION`	Specifies where to send requests. See this list. Note that the region must be set for AWS functions to work correctly, either through this variable, through a configuration profile, or by running on an EC2 instance.
`AWS_EC2_METADATA_SERVICE_ENDPOINT`	(Default `http://169.254.169.254`) Sets the base address of the instance metadata service.

`aws.EC2Meta`

Alias: ec2meta

Queries AWS EC2 Instance Metadata for information. This only retrieves data in the meta-data path – for data in the dynamic path use aws.EC2Dynamic.

For times when running outside EC2, or when the metadata API can’t be reached, a default value can be provided.

Added in gomplate v1.8.0

Usage

aws.EC2Meta key [default]

Arguments

name	description
`key`	(required) the metadata key to query
`default`	(optional) the default value

Examples

$ echo '{{aws.EC2Meta "instance-id"}}' | gomplate
i-12345678

`aws.EC2Dynamic`

Alias: ec2dynamic

Queries AWS EC2 Instance Dynamic Metadata for information. This only retrieves data in the dynamic path – for data in the meta-data path use aws.EC2Meta.

For times when running outside EC2, or when the metadata API can’t be reached, a default value can be provided.

Added in gomplate v1.8.0

Usage

aws.EC2Dynamic key [default]

Arguments

name	description
`key`	(required) the dynamic metadata key to query
`default`	(optional) the default value

Examples

$ echo '{{ (aws.EC2Dynamic "instance-identity/document" | json).region }}' | gomplate
us-east-1

`aws.EC2Region`

Alias: ec2region

Queries AWS to get the region. An optional default can be provided, or returns unknown if it can’t be determined for some reason.

Added in gomplate v1.8.0

Usage

aws.EC2Region [default]

Arguments

name	description
`default`	(optional) the default value

Examples

In EC2

$ echo '{{ aws.EC2Region }}' | ./gomplate
us-east-1

Not in EC2

$ echo '{{ aws.EC2Region }}' | ./gomplate
unknown
$ echo '{{ aws.EC2Region "foo" }}' | ./gomplate
foo

`aws.EC2Tag`

Alias: ec2tag

Queries the AWS EC2 API to find the value of the given user-defined tag. An optional default can be provided.

Added in gomplate v3.8.0

Usage

aws.EC2Tag tag [default]

Arguments

name	description
`tag`	(required) the tag to query
`default`	(optional) the default value

Examples

$ echo 'This server is in the {{ aws.EC2Tag "Account" }} account.' | ./gomplate
foo

$ echo 'I am a {{ aws.EC2Tag "classification" "meat popsicle" }}.' | ./gomplate
I am a meat popsicle.

`aws.EC2Tags`

Alias: ec2tags

Queries the AWS EC2 API to find all the tags/values user-defined tag.

Added in gomplate v3.8.0

Usage

aws.EC2Tags

Arguments

name	description

Examples

echo '{{ range $key, $value := aws.EC2Tags }}{{(printf "%s=%s\n" $key $value)}}{{ end }}' | ./gomplate
Description=foo
Name=bar
svc:name=foobar

`aws.KMSEncrypt`

Encrypt an input string with the AWS Key Management Service (KMS).

At most 4kb (4096 bytes) of data may be encrypted.

The resulting ciphertext will be base-64 encoded.

The keyID parameter is used to reference the Customer Master Key to use, and can be:

the key’s ID (e.g. 1234abcd-12ab-34cd-56ef-1234567890ab)
the key’s ARN (e.g. arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab)
the alias name (aliases must be prefixed with alias/, e.g. alias/ExampleAlias)
the alias ARN (e.g. arn:aws:kms:us-east-2:111122223333:alias/ExampleAlias)

For information on creating keys, see Creating Keys

See the AWS documentation for more details.

Usage

aws.KMSEncrypt keyID input

input | aws.KMSEncrypt keyID

Arguments

name	description
`keyID`	(required) the ID of the Customer Master Key (CMK) to use for encryption
`input`	(required) the string to encrypt

Examples

$ export CIPHER=$(gomplate -i '{{ aws.KMSEncrypt "alias/gomplate" "hello world" }}')
$ gomplate -i '{{ env.Getenv "CIPHER" | aws.KMSDecrypt }}'

`aws.KMSDecrypt`

Decrypt ciphertext that was encrypted with the AWS Key Management Service (KMS).

The ciphertext must be base-64 encoded.

See the AWS documentation for more details.

Usage

aws.KMSDecrypt input

input | aws.KMSDecrypt

Arguments

name	description
`input`	(required) the base-64 encoded ciphertext to decrypt

Examples

$ export CIPHER=$(gomplate -i '{{ aws.KMSEncrypt "alias/gomplate" "hello world" }}')
$ gomplate -i '{{ env.Getenv "CIPHER" | aws.KMSDecrypt }}'

`aws.Account`

Returns the currently-authenticated AWS account ID number.

Wraps the STS GetCallerIdentity API

Usage

aws.Account

Examples

$ gomplate -i 'My account is {{ aws.Account }}'
My account is 123456789012

`aws.ARN`

Returns the AWS ARN (Amazon Resource Name) associated with the current authentication credentials.

Wraps the STS GetCallerIdentity API

See also aws.UserID and aws.Account.

Added in gomplate v3.4.0

Usage

aws.ARN

Examples

$ gomplate -i 'Calling from {{ aws.ARN }}'
Calling from arn:aws:iam::123456789012:user/Alice

`aws.UserID`

Returns the unique identifier of the calling entity. The exact value depends on the type of entity making the call. The values returned are those listed in the aws:userid column in the Principal table found on the Policy Variables reference page in the IAM User Guide.

Wraps the STS GetCallerIdentity API

Usage

aws.UserID

Examples

$ gomplate -i 'I am {{ aws.UserID }}'
I am AIDACKCEVSQ6C2EXAMPLE