Use variables in your custom component document

Variables provide a way to label data with meaningful names that can be used throughout an application. You can define custom variables with simple and readable formats for complex workflows, and reference them in the YAML application component document for an AWSTOE component.

This section provides information to help you define variables for your AWSTOE component in the YAML application component document, including syntax, name constraints, and examples.

Constants

Constants are immutable variables that cannot be modified or overridden once defined. Constants can be defined using values in the constants section of an AWSTOE document.

Syntax

constants:
  - <name>:
      type: <constant type>
      value: <constant value>

Reference constant values in a document

You can reference constants in step or loop inputs inside of your YAML document, as follows:

Examples

Constant referenced in step inputs

name: Download AWS CLI version 2
schemaVersion: 1.0
constants:
  - Source:
      type: string
      value: https://awscli.amazonaws.com/AWSCLIV2.msi
phases:
  - name: build
    steps:
      - name: Download
        action: WebDownload
        inputs:
          - source: '{{ Source }}'
            destination: 'C:\Windows\Temp\AWSCLIV2.msi'

Constant referenced in loop inputs

name: PingHosts
schemaVersion: 1.0
constants:
  - Hosts:
      type: string
      value: 127.0.0.1,amazon.com
phases:
  - name: build
    steps:
      - name: Ping
        action: ExecuteBash
        loop:
          forEach:
            list: '{{ Hosts }}'
            delimiter: ','
        inputs:
          commands:
            - ping -c 4 {{ loop.value }}

Parameters

Parameters are mutable variables, with settings that the calling application can provide at runtime. You can define parameters in the Parameters section of the YAML document.

Syntax

parameters:
  - <name>:
      type: <parameter type>
      default: <parameter value>
      description: <parameter description>

Reference parameter values in a document

You can reference parameters in step or loop inputs inside of your YAML document, as follows:

Examples

The following examples show how to use parameters in your YAML document:

Override parameters at runtime

You can use the --parameters option from the AWS CLI with a key-value pair to set a parameter value at runtime.

Syntax

--parameters name1=value1,name2=value2...

Examples

The following examples show how to use parameters in your YAML document:

Use Systems Manager Parameter Store parameters

You can reference AWS Systems Manager Parameter Store parameters (SSM parameters) in your component documents by prefixing variables with aws:ssm. For example,

{{ aws:ssm:/my/param }} resolves to the value of the SSM parameter /my/param.

This feature supports the following SSM parameter types:

For more information about the Parameter Store see AWS Systems Manager Parameter Store in the AWS Systems Manager User Guide.

You can also reference AWS Secrets Manager secrets using an SSM parameter SecureString. For example: {{ aws:ssm:/aws/reference/secretsmanager/test/test-secret }}. For more information, see Referencing AWS Secrets Manager secrets from Parameter Store parameters.

Required IAM permissions

To use Systems Manager parameters in your components, your instance role must have the ssm:GetParameter permission for the parameter resource ARN. For example:

JSON

{
	"Version":"2012-10-17",
	"Statement": [
		{
			"Effect": "Allow",
			"Action": "ssm:GetParameter",
			"Resource": "arn:aws:ssm:*:111122223333:parameter/ImageBuilder-*"
		}
	]
}

To access encrypted values, you'll also need the following permissions:

Reference an SSM parameter in a component document

The following example shows how to reference an Systems Manager Parameter Store parameter of Systems Manager parameters in a component:

name: UseSSMParameterVariable
description: This is a sample component document that prints out the value of an SSM Parameter. Never do this for a SecureString parameter.
schemaVersion: 1.0

phases:
  - name: verify
    steps:
      - name: EchoParameterValue
        action: ExecuteBash
        inputs:
          commands:
            - echo "Log SSM parameter name: /my/test/param, value {{ aws:ssm:/my/test/param }}."

Dynamic runtime variable resolution for SSM parameters

AWSTOE provides the following built-in function that you can use within variable references to manipulate or transform values at runtime.

resolve function

The resolve function resolves a variable reference inside of another variable reference, allowing for dynamic variable name referencing. This is useful when working with SSM parameters where part of the parameter path may be variable and passed in as a document parameter.

The resolve function only supports dynamic resolution of the name portion of an SSM parameter.

Syntax

The dynamic_variable in the following example represents the name of an SSM parameter, and must be one of the following:

{{ aws:ssm:resolve(dynamic_variable) }}

Example: Resolve an SSM parameter at runtime

The following example shows how to use the resolve function in a YAML component document:

name: SsmParameterTest
description: This component verifies an SSM parameter variable reference with the echo command.
schemaVersion: 1.0

parameters:
  - parameter-name:
      type: string
      description: "test"

phases:
  - name: validate
    steps:
      - name: PrintDynamicVariable
        action: ExecuteBash
        inputs:
          commands:
            - echo "{{ aws:ssm:resolve(parameter-name) }}"

Use environment variables

AWSTOE can resolve operating system environment variables that are set on the build or test instance. To reference an environment variable, prefix the variable name with env:. For example, {{ env:MY_VAR }} resolves to the value of the MY_VAR environment variable on the instance.

AWSTOE matches environment variable names exactly. A name can contain any characters that are valid for the operating system, including dots, spaces, and parentheses. For example, {{ env:ProgramFiles(x86) }} is a valid reference on Windows.

The following example shows how to reference an environment variable in a component:

name: UseEnvironmentVariable
description: This sample component prints out the value of an environment variable.
schemaVersion: 1.0

phases:
  - name: build
    steps:
      - name: EchoEnvironmentVariable
        action: ExecuteBash
        inputs:
          commands:
            - echo "The value of SOME_VAR is {{ env:SOME_VAR }}."

Environment variables that Image Builder provides

When Image Builder runs a component on a build or test instance, it sets environment variables that describe the current image build. Your components read these values with the AWSTOE env: variable prefix described earlier in this topic.

Image Builder provides the following environment variables.

The following example shows how to read Image Builder environment variables in a component:

name: UseImageBuilderEnvironmentVariables
description: This sample component prints out Image Builder environment variable values.
schemaVersion: 1.0

phases:
  - name: build
    steps:
      - name: EchoImageBuildValues
        action: ExecuteBash
        inputs:
          commands:
            - echo "Image phase: {{ env:IMAGE_PHASE }}."
            - echo "Image build version ARN: {{ env:IMAGE_BUILD_VERSION_ARN }}."

Use instance metadata (IMDS) variables

AWSTOE can resolve values from the Amazon EC2 Instance Metadata Service (IMDS) on the build or test instance. To reference a metadata value, prefix the metadata path with aws:imds:. The path is relative to the instance metadata meta-data/ category. For example, {{ aws:imds:instance-id }} resolves to the instance ID. The reference {{ aws:imds:placement/region }} resolves to the AWS Region.

For more information about instance metadata, see Use instance metadata to manage your EC2 instance in the Amazon EC2 User Guide.

The following example shows how to reference an IMDS value in a component:

name: UseInstanceMetadataVariable
description: This sample component prints out the instance ID from IMDS.
schemaVersion: 1.0

phases:
  - name: build
    steps:
      - name: EchoInstanceId
        action: ExecuteBash
        inputs:
          commands:
            - echo "The instance ID is {{ aws:imds:instance-id }}."

Use context variables

AWSTOE provides context variables that describe the current execution and instance. To reference a context variable, prefix the key with context:. For example, {{ context:accountId }} resolves to the AWS account ID.

AWSTOE provides the following context variables.

The following example shows how to reference context variables in a component:

name: UseContextVariables
description: This sample component prints out context variable values.
schemaVersion: 1.0

phases:
  - name: build
    steps:
      - name: EchoContextValues
        action: ExecuteBash
        inputs:
          commands:
            - echo "Account: {{ context:accountId }}, OS: {{ context:osName }}."