Custom Function

Shaun edited this page May 10, 2017 · 1 revision

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 Template 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.

Gen-Time functions in Action

asciicast

--

Deploy-Time Template Functions

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

asciicast

--

Deploy/Gen-Time Function - Lambda Invoke

asciicast

--

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.