github.com/hairyhenderson/gomplate/v4@v4.0.0-pre-2.0.20240520121557-362f058f0c93/docs-src/content/functions/aws.yml

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](http://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](http://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](http://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](http://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`](#aws-kmsdecrypt).
    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`](#aws-kmsencrypt).
    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`](#aws-userid) and [`aws.ARN`](#aws-arn).
    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`](#aws-userid) and [`aws.Account`](#aws-account).
    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](http://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`](#aws-arn) and [`aws.Account`](#aws-account).
    pipeline: false
    examples:
      - |
        $ gomplate -i 'I am {{ aws.UserID }}'
        I am AIDACKCEVSQ6C2EXAMPLE