AWS imagebuilder medium security documentation change
Summary
Restructured documentation to separate constants and SSM parameters, added detailed guidance for using Systems Manager Parameter Store parameters including SecureString/Secrets Manager integration, IAM permissions, and dynamic resolution with resolve()
Security assessment
Added documentation for SecureString parameter handling with explicit warning about logging risks, references to Secrets Manager integration, and required IAM permissions for parameter access. These changes directly relate to secure credential management practices.
Diff
diff --git a/imagebuilder/latest/userguide/toe-user-defined-variables.md b/imagebuilder/latest/userguide/toe-user-defined-variables.md index da7f41dd7..fa056547e 100644 --- a//imagebuilder/latest/userguide/toe-user-defined-variables.md +++ b//imagebuilder/latest/userguide/toe-user-defined-variables.md @@ -5 +5 @@ -ParametersConstants +ConstantsParametersUse Systems Manager Parameter Store parameters @@ -12,0 +13,94 @@ This section provides information to help you define variables for your AWSTOE c +## 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. + +###### Rules for constant names + + * The name must be between 3 and 128 characters in length. + + * The name can only contain alphanumeric characters (a-z, A-Z, 0-9), dashes (-), or underscores (_). + + * The name must be unique within the document. + + * The name must be specified as a YAML string. + + + + +**Syntax** + + + constants: + - <name>: + type: <constant type> + value: <constant value> + +Key name | Required | Description +---|---|--- +`name` | Yes | Name of the constant. Must be unique for the document (it must not be the same as any other parameter names or constants). +`value` | Yes | Value of the constant. +`type` | Yes | Type of the constant. Supported type is `string`. + +###### Reference constant values in a document + +You can reference constants in step or loop inputs inside of your YAML document, as follows: + + * Constant references are case-sensitive, and the name must match exactly. + + * The name must be enclosed within double curly braces `{{` `MyConstant` `}}`. + + * Spaces are allowed within the curly braces, and are automatically trimmed. For example, all of the following references are valid: + +`{{ `MyConstant` }}`, `{{ `MyConstant`}}`, `{{`MyConstant` }}`, `{{`MyConstant`}}` + + * The reference in the YAML document must be specified as a string (enclosed in single or double quotes). + +For example: `- {{ `MyConstant` }}` is not valid, as it is not identified as a string. + +However, the following references are both valid: `- '{{ `MyConstant` }}'` and `- "{{ `MyConstant` }}"`. + + + + +###### 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 }} + @@ -162 +256 @@ The following examples show how to use parameters in your YAML document: -## Constants +## Use Systems Manager Parameter Store parameters @@ -164 +258 @@ The following examples show how to use parameters in your YAML document: -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. +You can reference AWS Systems Manager Parameter Store parameters (SSM parameters) in your component documents by prefixing variables with `aws:ssm`. For example, @@ -166 +260 @@ Constants are immutable variables that cannot be modified or overridden once def -###### Rules for constant names +`{{ aws:ssm:/my/param }}` resolves to the value of the SSM parameter `/my/param`. @@ -168 +262 @@ Constants are immutable variables that cannot be modified or overridden once def - * The name must be between 3 and 128 characters in length. +This feature supports the following SSM parameter types: @@ -170 +264 @@ Constants are immutable variables that cannot be modified or overridden once def - * The name can only contain alphanumeric characters (a-z, A-Z, 0-9), dashes (-), or underscores (_). + * String – Maps to the AWSTOE string type. @@ -172 +266 @@ Constants are immutable variables that cannot be modified or overridden once def - * The name must be unique within the document. + * StringList – Maps to the AWSTOE `stringList` type. @@ -174 +268 @@ Constants are immutable variables that cannot be modified or overridden once def - * The name must be specified as a YAML string. + * SecureString – Maps to the AWSTOE string type. @@ -179 +273 @@ Constants are immutable variables that cannot be modified or overridden once def -**Syntax** +For more information about the Parameter Store see [AWS Systems Manager Parameter Store](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.html) in the _AWS Systems Manager User Guide_. @@ -180,0 +275 @@ Constants are immutable variables that cannot be modified or overridden once def +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](https://docs.aws.amazon.com/systems-manager/latest/userguide/integration-ps-secretsmanager.html). @@ -182,4 +277 @@ Constants are immutable variables that cannot be modified or overridden once def - constants: - - <name>: - type: <constant type> - value: <constant value> +###### Important @@ -187,5 +279 @@ Constants are immutable variables that cannot be modified or overridden once def -Key name | Required | Description ----|---|--- -`name` | Yes | Name of the constant. Must be unique for the document (it must not be the same as any other parameter names or constants). -`value` | Yes | Value of the constant. -`type` | Yes | Type of the constant. Supported type is `string`. +Image Builder excludes `SecureString` parameter resolution from its logs. However, you are also responsible for ensuring that sensitive information is not logged through commands issued in the component document. For example, if you use the `echo` command with a secure string, the command writes a plaintext value to the log. @@ -193 +281 @@ Key name | Required | Description -###### Reference constant values in a document +### Required IAM permissions @@ -195 +283 @@ Key name | Required | Description -You can reference constants in step or loop inputs inside of your YAML document, as follows: +To use Systems Manager parameters in your components, your instance role must have the `ssm:GetParameter` permission for the parameter resource ARN. For example: @@ -197 +284,0 @@ You can reference constants in step or loop inputs inside of your YAML document, - * Constant references are case-sensitive, and the name must match exactly. @@ -199 +286,10 @@ You can reference constants in step or loop inputs inside of your YAML document, - * The name must be enclosed within double curly braces `{{` `MyConstant` `}}`. + { + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": "ssm:GetParameter", + "Resource": "arn:aws:ssm:*:111122223333:parameter/ImageBuilder-*" + } + ] + } @@ -201 +297 @@ You can reference constants in step or loop inputs inside of your YAML document, - * Spaces are allowed within the curly braces, and are automatically trimmed. For example, all of the following references are valid: +### Reference an SSM parameter in a component document @@ -203 +299 @@ You can reference constants in step or loop inputs inside of your YAML document, -`{{ `MyConstant` }}`, `{{ `MyConstant`}}`, `{{`MyConstant` }}`, `{{`MyConstant`}}` +The following example shows how to reference an Systems Manager Parameter Store parameter of Systems Manager parameters in a component: @@ -205 +300,0 @@ You can reference constants in step or loop inputs inside of your YAML document, - * The reference in the YAML document must be specified as a string (enclosed in single or double quotes). @@ -207 +302,3 @@ You can reference constants in step or loop inputs inside of your YAML document, -For example: `- {{ `MyConstant` }}` is not valid, as it is not identified as a string. + 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 @@ -209 +306,8 @@ For example: `- {{ `MyConstant` }}` is not valid, as it is not identified as a s -However, the following references are both valid: `- '{{ `MyConstant` }}'` and `- "{{ `MyConstant` }}"`. + phases: + - name: verify + steps: + - name: EchoParameterValue + action: ExecuteBash + inputs: + commands: + - echo "Log SSM parameter name: /my/test/param, value {{ aws:ssm:/my/test/param }}." @@ -210,0 +315 @@ However, the following references are both valid: `- '{{ `MyConstant` }}'` and ` +### Dynamic runtime variable resolution for SSM parameters @@ -211,0 +317 @@ However, the following references are both valid: `- '{{ `MyConstant` }}'` and ` +AWSTOE provides the following built-in function that you can use within variable references to manipulate or transform values at runtime. @@ -212,0 +319 @@ However, the following references are both valid: `- '{{ `MyConstant` }}'` and ` +#### resolve function @@ -214 +321 @@ However, the following references are both valid: `- '{{ `MyConstant` }}'` and ` -###### Examples +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. @@ -216 +323 @@ However, the following references are both valid: `- '{{ `MyConstant` }}'` and ` -Constant referenced in step inputs +The `resolve` function only supports dynamic resolution of the name portion of an SSM parameter. @@ -217,0 +325 @@ Constant referenced in step inputs +##### Syntax @@ -219,14 +327 @@ Constant referenced in step inputs - name: Download AWS CLI version 2