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 ```