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

aws.Account

Returns the currently-authenticated AWS account ID number.

Wraps the STS GetCallerIdentity API

See also aws.UserID and aws.ARN.

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.

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

See also aws.ARN and aws.Account.

Usage

aws.UserID

Examples

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