Custom Function
Custom Template Functions expand the functionality of Go's Templating library by allowing you to execute external functions to retrieve additional information for building your template.
Qaz supports all the Go Template functions as well as some custom ones.
Qaz has two levels of custom template functions, these are Gen-Time functions and Deploy-Time functions.
--
Gen-Time functions are functions that are executed when a template is being generated. These are handy for reading files into a template or making API calls to fetch values.
Here are some of the Gen-Time functions available... more to come:
cat
A template function for reading values from an external file into a template.
Example:
{{ "path/to/myfile.txt" | cat }} or {{ cat "path/to/myfile.txt" }}
Returns the value of myfile.txt under the files directory
s3_read
As the name suggests, this function reads the content of a given s3 key and writes it to the template.
Example:
{{ "s3://mybucket/key" | s3_read }} or {{ s3_read "s3://mybucket/key" }}
Writes the contents of the object to the template
GET
GET implements http GET requests on a given url, and writes the response to the template.
Example
{{ "http://localhost" | GET }} or {{ GET "http://localhost" }}
invoke
Invokes a Lambda function and stores the returned value with the template.
Example
{{ invoke "function_name" `{"some_json":"some_value"}` }}
Note: JSON passed inside a template function needs to be wrapped in back-ticks.
kms_encrypt
Generates an encrypted Cipher Text blob using AWS KMS
Example
{{ kms_encrypt kms.keyid "Text to Encrypt!" }}
kms_decrypt
Decrypts a given Cipher Text blob using AWS KMS
Example
{{ kms_decrypt "CipherTextBlob" }}
Note: The encryption functionality does require some understanding of AWS KMS. The kms_encrypt creates a Cipher Text Blob from the given text. The Cipher holds metadata that allows it to be decrypted without giving the Key ID. It can however, only be decrypted using an AWS profile with access to the Key ID used to encrypt.
See Here for more information on KMS CipherTextBlob and Encryption terminology.
mod @thorstenhuhn
Gen-Time function for Modulus Division within templates. I.e Returns the remainder of an uneven division.
Example:
{{ mod 7 3 }} returns --> 1
seq @thorstenhuhn
Gen-Time function for sequence iteration. I.e Iteration over a given range.
Example:
{{ range $i, $seq := seq 1 5 }}
MyInstance{{ $seq }}:
Type: AWS::EC2::Instance
...
{{ end }}Gen-Time functions in Action
Deploy-Time functions are run just before the template is pushed to AWS Cloudformation. These are handy for:
- Fetching values from dependency stacks
- Making API calls to pull values from resources built by preceding stacks
- Triggering events via an API call and adjusting the template based on the response
- Updating Values in a decrypted template
Here are some of the Deploy-Time functions available... more to come:
stack_output
stack_output fetches the output value of a given stack and stores the value in your template. This function uses the stack name as defined in your project configuration
Example
# internal-stackname::output
<< stack_output "vpc::vpcid" >>
stack_output_ext
stack_output_ext fetches the output value of a given stack that exists outside of your project/configuration and stores the value in your template. This function requires the full name of the stack as it appears on the AWS Console.
Example
# external-stackname::output
<< stack_output_ext "external-vpc::vpcid" >>
Important!: When using Deploy-Time functions the Template delimiters are different: << >> Qaz identifies items wrapped in these as Deploy-Time functions and only executes them just for before deploying to AWS.
The following are also accessible as Deploy-Time functions:
- s3_read
- invoke
- GET
- kms_decrypt
- kms_encrypt
Deploy-Time Functions in action
Deploy/Gen-Time Function - Lambda Invoke
--