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_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, or a configuration profile.

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.

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.

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.

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.

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.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.

See also aws.KMSDecrypt.

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.

See also aws.KMSEncrypt.

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 }}'