1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
|
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
|
