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

     1  ---
     2  title: aws functions
     3  menu:
     4    main:
     5      parent: functions
     6  ---
     7  
     8  The functions in the `aws` namespace interface with various Amazon Web Services
     9  APIs to make it possible for a template to render differently based on the AWS
    10  environment and metadata.
    11  
    12  ### Configuring AWS
    13  
    14  A number of environment variables can be used to control how gomplate communicates
    15  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)
    16  for details.
    17  
    18  | Environment Variable | Description |
    19  | -------------------- | ----------- |
    20  | `AWS_TIMEOUT` | _(Default `500`)_ Adjusts timeout for API requests, in milliseconds. Not part of the AWS SDK. |
    21  | `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. |
    22  | `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. |
    23  
    24  ## `aws.EC2Meta`
    25  
    26  **Alias:** `ec2meta`
    27  
    28  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`.
    29  
    30  For times when running outside EC2, or when the metadata API can't be reached, a `default` value can be provided.
    31  
    32  ### Usage
    33  
    34  ```go
    35  aws.EC2Meta key [default]
    36  ```
    37  
    38  ### Arguments
    39  
    40  | name | description |
    41  |------|-------------|
    42  | `key` | _(required)_ the metadata key to query |
    43  | `default` | _(optional)_ the default value |
    44  
    45  ### Examples
    46  
    47  ```console
    48  $ echo '{{aws.EC2Meta "instance-id"}}' | gomplate
    49  i-12345678
    50  ```
    51  
    52  ## `aws.EC2Dynamic`
    53  
    54  **Alias:** `ec2dynamic`
    55  
    56  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`.
    57  
    58  For times when running outside EC2, or when the metadata API can't be reached, a `default` value can be provided.
    59  
    60  ### Usage
    61  
    62  ```go
    63  aws.EC2Dynamic key [default]
    64  ```
    65  
    66  ### Arguments
    67  
    68  | name | description |
    69  |------|-------------|
    70  | `key` | _(required)_ the dynamic metadata key to query |
    71  | `default` | _(optional)_ the default value |
    72  
    73  ### Examples
    74  
    75  ```console
    76  $ echo '{{ (aws.EC2Dynamic "instance-identity/document" | json).region }}' | gomplate
    77  us-east-1
    78  ```
    79  
    80  ## `aws.EC2Region`
    81  
    82  **Alias:** `ec2region`
    83  
    84  Queries AWS to get the region. An optional default can be provided, or returns
    85  `unknown` if it can't be determined for some reason.
    86  
    87  ### Usage
    88  
    89  ```go
    90  aws.EC2Region [default]
    91  ```
    92  
    93  ### Arguments
    94  
    95  | name | description |
    96  |------|-------------|
    97  | `default` | _(optional)_ the default value |
    98  
    99  ### Examples
   100  
   101  _In EC2_
   102  ```console
   103  $ echo '{{ aws.EC2Region }}' | ./gomplate
   104  us-east-1
   105  ```
   106  _Not in EC2_
   107  ```console
   108  $ echo '{{ aws.EC2Region }}' | ./gomplate
   109  unknown
   110  $ echo '{{ aws.EC2Region "foo" }}' | ./gomplate
   111  foo
   112  ```
   113  
   114  ## `aws.EC2Tag`
   115  
   116  **Alias:** `ec2tag`
   117  
   118  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
   119  can be provided.
   120  
   121  ### Usage
   122  
   123  ```go
   124  aws.EC2Tag tag [default]
   125  ```
   126  
   127  ### Arguments
   128  
   129  | name | description |
   130  |------|-------------|
   131  | `tag` | _(required)_ the tag to query |
   132  | `default` | _(optional)_ the default value |
   133  
   134  ### Examples
   135  
   136  ```console
   137  $ echo 'This server is in the {{ aws.EC2Tag "Account" }} account.' | ./gomplate
   138  foo
   139  ```
   140  ```console
   141  $ echo 'I am a {{ aws.EC2Tag "classification" "meat popsicle" }}.' | ./gomplate
   142  I am a meat popsicle.
   143  ```
   144  
   145  ## `aws.KMSEncrypt`
   146  
   147  Encrypt an input string with the AWS Key Management Service (KMS).
   148  
   149  At most 4kb (4096 bytes) of data may be encrypted.
   150  
   151  The resulting ciphertext will be base-64 encoded.
   152  
   153  The `keyID` parameter is used to reference the Customer Master Key to use,
   154  and can be:
   155  
   156  - the key's ID (e.g. `1234abcd-12ab-34cd-56ef-1234567890ab`)
   157  - the key's ARN (e.g. `arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab`)
   158  - the alias name (aliases must be prefixed with `alias/`, e.g. `alias/ExampleAlias`)
   159  - the alias ARN (e.g. `arn:aws:kms:us-east-2:111122223333:alias/ExampleAlias`)
   160  
   161  For information on creating keys, see [_Creating Keys_](https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html)
   162  
   163  See [the AWS documentation](https://docs.aws.amazon.com/kms/latest/developerguide/overview.html)
   164  for more details.
   165  
   166  See also [`aws.KMSDecrypt`](#aws-kmsdecrypt).
   167  
   168  ### Usage
   169  
   170  ```go
   171  aws.KMSEncrypt keyID input
   172  ```
   173  ```go
   174  input | aws.KMSEncrypt keyID
   175  ```
   176  
   177  ### Arguments
   178  
   179  | name | description |
   180  |------|-------------|
   181  | `keyID` | _(required)_ the ID of the Customer Master Key (CMK) to use for encryption |
   182  | `input` | _(required)_ the string to encrypt |
   183  
   184  ### Examples
   185  
   186  ```console
   187  $ export CIPHER=$(gomplate -i '{{ aws.KMSEncrypt "alias/gomplate" "hello world" }}')
   188  $ gomplate -i '{{ env.Getenv "CIPHER" | aws.KMSDecrypt }}'
   189  ```
   190  
   191  ## `aws.KMSDecrypt`
   192  
   193  Decrypt ciphertext that was encrypted with the AWS Key Management Service
   194  (KMS).
   195  
   196  The ciphertext must be base-64 encoded.
   197  
   198  See [the AWS documentation](https://docs.aws.amazon.com/kms/latest/developerguide/overview.html)
   199  for more details.
   200  
   201  See also [`aws.KMSEncrypt`](#aws-kmsencrypt).
   202  
   203  ### Usage
   204  
   205  ```go
   206  aws.KMSDecrypt input
   207  ```
   208  ```go
   209  input | aws.KMSDecrypt
   210  ```
   211  
   212  ### Arguments
   213  
   214  | name | description |
   215  |------|-------------|
   216  | `input` | _(required)_ the base-64 encoded ciphertext to decrypt |
   217  
   218  ### Examples
   219  
   220  ```console
   221  $ export CIPHER=$(gomplate -i '{{ aws.KMSEncrypt "alias/gomplate" "hello world" }}')
   222  $ gomplate -i '{{ env.Getenv "CIPHER" | aws.KMSDecrypt }}'
   223  ```
   224  
   225  ## `aws.Account`
   226  
   227  Returns the currently-authenticated AWS account ID number.
   228  
   229  Wraps the [STS GetCallerIdentity API](https://docs.aws.amazon.com/STS/latest/APIReference/API_GetCallerIdentity.html)
   230  
   231  See also [`aws.UserID`](#aws-userid) and [`aws.ARN`](#aws-arn).
   232  
   233  ### Usage
   234  
   235  ```go
   236  aws.Account
   237  ```
   238  
   239  
   240  ### Examples
   241  
   242  ```console
   243  $ gomplate -i 'My account is {{ aws.Account }}'
   244  My account is 123456789012
   245  ```
   246  
   247  ## `aws.ARN`
   248  
   249  Returns the AWS ARN (Amazon Resource Name) associated with the current authentication credentials.
   250  
   251  Wraps the [STS GetCallerIdentity API](https://docs.aws.amazon.com/STS/latest/APIReference/API_GetCallerIdentity.html)
   252  
   253  See also [`aws.UserID`](#aws-userid) and [`aws.Account`](#aws-account).
   254  
   255  ### Usage
   256  
   257  ```go
   258  aws.ARN
   259  ```
   260  
   261  
   262  ### Examples
   263  
   264  ```console
   265  $ gomplate -i 'Calling from {{ aws.ARN }}'
   266  Calling from arn:aws:iam::123456789012:user/Alice
   267  ```
   268  
   269  ## `aws.UserID`
   270  
   271  Returns the unique identifier of the calling entity. The exact value
   272  depends on the type of entity making the call. The values returned are those
   273  listed in the `aws:userid` column in the [Principal table](http://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_variables.html#principaltable)
   274  found on the Policy Variables reference page in the IAM User Guide.
   275  
   276  Wraps the [STS GetCallerIdentity API](https://docs.aws.amazon.com/STS/latest/APIReference/API_GetCallerIdentity.html)
   277  
   278  See also [`aws.ARN`](#aws-arn) and [`aws.Account`](#aws-account).
   279  
   280  ### Usage
   281  
   282  ```go
   283  aws.UserID
   284  ```
   285  
   286  
   287  ### Examples
   288  
   289  ```console
   290  $ gomplate -i 'I am {{ aws.UserID }}'
   291  I am AIDACKCEVSQ6C2EXAMPLE
   292  ```