github.com/wuhuizuo/gomplate@v3.5.0+incompatible/docs-src/content/functions/aws.yml (about)

     1  ns: aws
     2  preamble: |
     3    The functions in the `aws` namespace interface with various Amazon Web Services
     4    APIs to make it possible for a template to render differently based on the AWS
     5    environment and metadata.
     6  
     7    ### Configuring AWS
     8  
     9    A number of environment variables can be used to control how gomplate communicates
    10    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)
    11    for details.
    12  
    13    | Environment Variable | Description |
    14    | -------------------- | ----------- |
    15    | `AWS_TIMEOUT` | _(Default `500`)_ Adjusts timeout for API requests, in milliseconds. Not part of the AWS SDK. |
    16    | `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. |
    17    | `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, or a configuration profile. |
    18  funcs:
    19    - name: aws.EC2Meta
    20      alias: ec2meta
    21      description: |
    22        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`.
    23  
    24        For times when running outside EC2, or when the metadata API can't be reached, a `default` value can be provided.
    25      pipeline: false
    26      arguments:
    27        - name: key
    28          required: true
    29          description: the metadata key to query
    30        - name: default
    31          required: false
    32          description: the default value
    33      examples:
    34        - |
    35          $ echo '{{aws.EC2Meta "instance-id"}}' | gomplate
    36          i-12345678
    37    - name: aws.EC2Dynamic
    38      alias: ec2dynamic
    39      description: |
    40        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`.
    41  
    42        For times when running outside EC2, or when the metadata API can't be reached, a `default` value can be provided.
    43      pipeline: false
    44      arguments:
    45        - name: key
    46          required: true
    47          description: the dynamic metadata key to query
    48        - name: default
    49          required: false
    50          description: the default value
    51      examples:
    52        - |
    53          $ echo '{{ (aws.EC2Dynamic "instance-identity/document" | json).region }}' | gomplate
    54          us-east-1
    55    - name: aws.EC2Region
    56      alias: ec2region
    57      description: |
    58        Queries AWS to get the region. An optional default can be provided, or returns
    59        `unknown` if it can't be determined for some reason.
    60      pipeline: false
    61      arguments:
    62        - name: default
    63          required: false
    64          description: the default value
    65      rawExamples:
    66        - |
    67          _In EC2_
    68          ```console
    69          $ echo '{{ aws.EC2Region }}' | ./gomplate
    70          us-east-1
    71          ```
    72          _Not in EC2_
    73          ```console
    74          $ echo '{{ aws.EC2Region }}' | ./gomplate
    75          unknown
    76          $ echo '{{ aws.EC2Region "foo" }}' | ./gomplate
    77          foo
    78          ```
    79    - name: aws.EC2Tag
    80      alias: ec2tag
    81      description: |
    82        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
    83        can be provided.
    84      pipeline: false
    85      arguments:
    86        - name: tag
    87          required: true
    88          description: the tag to query
    89        - name: default
    90          required: false
    91          description: the default value
    92      examples:
    93        - |
    94          $ echo 'This server is in the {{ aws.EC2Tag "Account" }} account.' | ./gomplate
    95          foo
    96        - |
    97          $ echo 'I am a {{ aws.EC2Tag "classification" "meat popsicle" }}.' | ./gomplate
    98          I am a meat popsicle.
    99    - name: aws.KMSEncrypt
   100      description: |
   101        Encrypt an input string with the AWS Key Management Service (KMS).
   102  
   103        At most 4kb (4096 bytes) of data may be encrypted.
   104  
   105        The resulting ciphertext will be base-64 encoded.
   106  
   107        The `keyID` parameter is used to reference the Customer Master Key to use,
   108        and can be:
   109  
   110        - the key's ID (e.g. `1234abcd-12ab-34cd-56ef-1234567890ab`)
   111        - the key's ARN (e.g. `arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab`)
   112        - the alias name (aliases must be prefixed with `alias/`, e.g. `alias/ExampleAlias`)
   113        - the alias ARN (e.g. `arn:aws:kms:us-east-2:111122223333:alias/ExampleAlias`)
   114  
   115        For information on creating keys, see [_Creating Keys_](https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html)
   116  
   117        See [the AWS documentation](https://docs.aws.amazon.com/kms/latest/developerguide/overview.html)
   118        for more details.
   119  
   120        See also [`aws.KMSDecrypt`](#aws-kmsdecrypt).
   121      pipeline: true
   122      arguments:
   123        - name: keyID
   124          required: true
   125          description: the ID of the Customer Master Key (CMK) to use for encryption
   126        - name: input
   127          required: true
   128          description: the string to encrypt
   129      examples:
   130        - |
   131          $ export CIPHER=$(gomplate -i '{{ aws.KMSEncrypt "alias/gomplate" "hello world" }}')
   132          $ gomplate -i '{{ env.Getenv "CIPHER" | aws.KMSDecrypt }}'
   133    - name: aws.KMSDecrypt
   134      description: |
   135        Decrypt ciphertext that was encrypted with the AWS Key Management Service
   136        (KMS).
   137  
   138        The ciphertext must be base-64 encoded.
   139  
   140        See [the AWS documentation](https://docs.aws.amazon.com/kms/latest/developerguide/overview.html)
   141        for more details.
   142  
   143        See also [`aws.KMSEncrypt`](#aws-kmsencrypt).
   144      pipeline: true
   145      arguments:
   146        - name: input
   147          required: true
   148          description: the base-64 encoded ciphertext to decrypt
   149      examples:
   150        - |
   151          $ export CIPHER=$(gomplate -i '{{ aws.KMSEncrypt "alias/gomplate" "hello world" }}')
   152          $ gomplate -i '{{ env.Getenv "CIPHER" | aws.KMSDecrypt }}'
   153    - name: aws.Account
   154      description: |
   155        Returns the currently-authenticated AWS account ID number.
   156  
   157        Wraps the [STS GetCallerIdentity API](https://docs.aws.amazon.com/STS/latest/APIReference/API_GetCallerIdentity.html)
   158  
   159        See also [`aws.UserID`](#aws-userid) and [`aws.ARN`](#aws-arn).
   160      pipeline: false
   161      examples:
   162        - |
   163          $ gomplate -i 'My account is {{ aws.Account }}'
   164          My account is 123456789012
   165    - name: aws.ARN
   166      description: |
   167        Returns the AWS ARN (Amazon Resource Name) associated with the current authentication credentials.
   168  
   169        Wraps the [STS GetCallerIdentity API](https://docs.aws.amazon.com/STS/latest/APIReference/API_GetCallerIdentity.html)
   170  
   171        See also [`aws.UserID`](#aws-userid) and [`aws.Account`](#aws-account).
   172      pipeline: false
   173      examples:
   174        - |
   175          $ gomplate -i 'Calling from {{ aws.ARN }}'
   176          Calling from arn:aws:iam::123456789012:user/Alice
   177    - name: aws.UserID
   178      description: |
   179        Returns the unique identifier of the calling entity. The exact value
   180        depends on the type of entity making the call. The values returned are those
   181        listed in the `aws:userid` column in the [Principal table](http://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_variables.html#principaltable)
   182        found on the Policy Variables reference page in the IAM User Guide.
   183  
   184        Wraps the [STS GetCallerIdentity API](https://docs.aws.amazon.com/STS/latest/APIReference/API_GetCallerIdentity.html)
   185  
   186        See also [`aws.ARN`](#aws-arn) and [`aws.Account`](#aws-account).
   187      pipeline: false
   188      examples:
   189        - |
   190          $ gomplate -i 'I am {{ aws.UserID }}'
   191          I am AIDACKCEVSQ6C2EXAMPLE