ns: aws preamble: | 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](https://docs.aws.amazon.com/sdk-for-go/v1/developer-guide/configuring-sdk.html) 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](https://docs.aws.amazon.com/general/latest/gr/rande.html). 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_META_ENDPOINT` _(Deprecated)_ | _(Default `http://169.254.169.254`)_ Sets the base address of the instance metadata service. Use `AWS_EC2_METADATA_SERVICE_ENDPOINT` instead. | funcs: - name: aws.EC2Meta alias: ec2meta released: v1.8.0 description: | Queries AWS [EC2 Instance Metadata](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html) 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. pipeline: false arguments: - name: key required: true description: the metadata key to query - name: default required: false description: the default value examples: - | $ echo '{{aws.EC2Meta "instance-id"}}' | gomplate i-12345678 - name: aws.EC2Dynamic alias: ec2dynamic released: v1.8.0 description: | Queries AWS [EC2 Instance Dynamic Metadata](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html) 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. pipeline: false arguments: - name: key required: true description: the dynamic metadata key to query - name: default required: false description: the default value examples: - | $ echo '{{ (aws.EC2Dynamic "instance-identity/document" | json).region }}' | gomplate us-east-1 - name: aws.EC2Region alias: ec2region released: v1.8.0 description: | Queries AWS to get the region. An optional default can be provided, or returns `unknown` if it can't be determined for some reason. pipeline: false arguments: - name: default required: false description: the default value rawExamples: - | _In EC2_ ```console $ echo '{{ aws.EC2Region }}' | ./gomplate us-east-1 ``` _Not in EC2_ ```console $ echo '{{ aws.EC2Region }}' | ./gomplate unknown $ echo '{{ aws.EC2Region "foo" }}' | ./gomplate foo ``` - name: aws.EC2Tag alias: ec2tag released: v3.8.0 description: | Queries the AWS EC2 API to find the value of the given [user-defined tag](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/Using_Tags.html). An optional default can be provided. pipeline: false arguments: - name: tag required: true description: the tag to query - name: default required: false description: 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. - name: aws.EC2Tags alias: ec2tags released: v3.8.0 description: | Queries the AWS EC2 API to find all the tags/values [user-defined tag](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/Using_Tags.html). pipeline: false arguments: examples: - | echo '{{ range $key, $value := aws.EC2Tags }}{{(printf "%s=%s\n" $key $value)}}{{ end }}' | ./gomplate Description=foo Name=bar svc:name=foobar - name: aws.KMSEncrypt released: v4.0.0 description: | 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_](https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html) See [the AWS documentation](https://docs.aws.amazon.com/kms/latest/developerguide/overview.html) for more details. See also [`aws.KMSDecrypt`](#awskmsdecrypt). pipeline: true arguments: - name: keyID required: true description: the ID of the Customer Master Key (CMK) to use for encryption - name: input required: true description: the string to encrypt examples: - | $ export CIPHER=$(gomplate -i '{{ aws.KMSEncrypt "alias/gomplate" "hello world" }}') $ gomplate -i '{{ env.Getenv "CIPHER" | aws.KMSDecrypt }}' - name: aws.KMSDecrypt released: v3.4.0 description: | Decrypt ciphertext that was encrypted with the AWS Key Management Service (KMS). The ciphertext must be base-64 encoded. See [the AWS documentation](https://docs.aws.amazon.com/kms/latest/developerguide/overview.html) for more details. See also [`aws.KMSEncrypt`](#awskmsencrypt). pipeline: true arguments: - name: input required: true description: 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 }}' - name: aws.Account released: v3.4.0 description: | Returns the currently-authenticated AWS account ID number. Wraps the [STS GetCallerIdentity API](https://docs.aws.amazon.com/STS/latest/APIReference/API_GetCallerIdentity.html) See also [`aws.UserID`](#awsuserid) and [`aws.ARN`](#awsarn). pipeline: false examples: - | $ gomplate -i 'My account is {{ aws.Account }}' My account is 123456789012 - name: aws.ARN released: v3.4.0 description: | Returns the AWS ARN (Amazon Resource Name) associated with the current authentication credentials. Wraps the [STS GetCallerIdentity API](https://docs.aws.amazon.com/STS/latest/APIReference/API_GetCallerIdentity.html) See also [`aws.UserID`](#awsuserid) and [`aws.Account`](#awsaccount). pipeline: false examples: - | $ gomplate -i 'Calling from {{ aws.ARN }}' Calling from arn:aws:iam::123456789012:user/Alice - name: aws.UserID released: v3.4.0 description: | 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](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_variables.html#principaltable) found on the Policy Variables reference page in the IAM User Guide. Wraps the [STS GetCallerIdentity API](https://docs.aws.amazon.com/STS/latest/APIReference/API_GetCallerIdentity.html) See also [`aws.ARN`](#awsarn) and [`aws.Account`](#awsaccount). pipeline: false examples: - | $ gomplate -i 'I am {{ aws.UserID }}' I am AIDACKCEVSQ6C2EXAMPLE