AWS::ImageBuilder::Component - AWS CloudFormation
SyntaxPropertiesReturn valuesExamples

AWS::ImageBuilder::Component

Creates a new component that can be used to build, validate, test, and assess your image. The component is based on a YAML document that you specify using exactly one of the following methods:

  • Inline, using the data property in the request body.

  • A URL that points to a YAML document file stored in Amazon S3, using the uri property in the request body.

Syntax

To declare this entity in your AWS CloudFormation template, use the following syntax:

JSON

{
  "Type" : "AWS::ImageBuilder::Component",
  "Properties" : {
      "ChangeDescription" : String,
      "Data" : String,
      "Description" : String,
      "KmsKeyId" : String,
      "Name" : String,
      "Platform" : String,
      "SupportedOsVersions" : [ String, ... ],
      "Tags" : {Key: Value, ...},
      "Uri" : String,
      "Version" : String
    }
}

YAML

Type: AWS::ImageBuilder::Component
Properties:
  ChangeDescription: String
  Data: String
  Description: String
  KmsKeyId: String
  Name: String
  Platform: String
  SupportedOsVersions: 
    - String
  Tags: 
    Key: Value
  Uri: String
  Version: String

Properties

ChangeDescription

The change description of the component. Describes what change has been made in this version, or what makes this version different from other versions of the component.

Required: No

Type: String

Minimum: 1

Maximum: 1024

Update requires: Replacement

Data

Component data contains inline YAML document content for the component. Alternatively, you can specify the uri of a YAML document file stored in Amazon S3. However, you cannot specify both properties.

Required: No

Type: String

Minimum: 1

Maximum: 16000

Update requires: Replacement

Description

Describes the contents of the component.

Required: No

Type: String

Minimum: 1

Maximum: 1024

Update requires: Replacement

KmsKeyId

The ID of the KMS key that is used to encrypt this component.

Required: No

Type: String

Minimum: 1

Maximum: 1024

Update requires: Replacement

Name

The name of the component.

Required: Yes

Type: String

Pattern: ^[-_A-Za-z-0-9][-_A-Za-z0-9 ]{1,126}[-_A-Za-z-0-9]$

Update requires: Replacement

Platform

The operating system platform of the component.

Required: Yes

Type: String

Allowed values: Windows | Linux | macOS

Update requires: Replacement

SupportedOsVersions

The operating system (OS) version supported by the component. If the OS information is available, a prefix match is performed against the base image OS version during image recipe creation.

Required: No

Type: Array of String

Minimum: 1

Maximum: 25

Update requires: Replacement

Tags

The tags that apply to the component.

Required: No

Type: Object of String

Pattern: .{1,}

Update requires: Replacement

Uri

The uri of a YAML component document file. This must be an S3 URL (s3://bucket/key), and the requester must have permission to access the S3 bucket it points to. If you use Amazon S3, you can specify component content up to your service quota.

Alternatively, you can specify the YAML document inline, using the component data property. You cannot specify both properties.

Required: No

Type: String

Update requires: Replacement

Version

The component version. For example, 1.0.0.

Required: Yes

Type: String

Update requires: Replacement

Return values

Ref

When you pass the logical ID of this resource to the intrinsic Ref function, Ref returns the resource ARN, such as arn:aws:imagebuilder:us-west-2:123456789012:component/examplecomponent/2019.12.02/1.

For more information about using the Ref function, see Ref.

Fn::GetAtt

The Fn::GetAtt intrinsic function returns a value for a specified attribute of this type. The following are the available attributes and sample return values.

For more information about using the Fn::GetAtt intrinsic function, see Fn::GetAtt.

Arn

Returns the Amazon Resource Name (ARN) of the component. The following pattern is applied: ^arn:aws[^:]*:imagebuilder:[^:]+:(?:\d{12}|aws):(?:image-recipe|infrastructure-configuration|distribution-configuration|component|image|image-pipeline)/[a-z0-9-_]+(?:/(?:(?:x|\d+)\.(?:x|\d+)\.(?:x|\d+))(?:/\d+)?)?$.

Encrypted

Returns the encryption status of the component. For example true or false.

Name

Returns the name of the component.

Type

Image Builder determines the component type based on the phases that are defined in the component document. If there is only one phase, and its name is "test", then the type is TEST. For all other components, the type is BUILD.

Examples

Create a component using Data

The following example shows the schema for the Component resource document in both JSON and YAML format. This example includes details for the Data field . You can use either the Data or Uri fields to reference the component document.

JSON

{
	"Resources": {
		"ComponentAllParameters": {
			"Type": "AWS::ImageBuilder::Component",
			"Properties": {
				"Name": "component-name",
				"Platform": "Linux",
				"Version": "1.0.0",
				"Description": "description",
				"ChangeDescription": "change-description",
				"KmsKeyId": "customer-kms-key-id",
				"SupportedOsVersions": ["Amazon Linux 2"],
				"Tags": {
					"CustomerComponentTagKey1": "CustomerComponentTagValue1",
					"CustomerComponentTagKey2": "CustomerComponentTagValue2"
				},
				"Data": "name: HelloWorldTestingLinuxDoc - InlineData\ndescription: This is hello world testing doc\nschemaVersion: 1.0\n\nphases:\n  - name: build\n    steps:\n      - name: HelloWorldStep\n        action: ExecuteBash\n        inputs:\n          commands:\n            - echo \"Hello World! Build.\"\n  - name: validate\n    steps:\n      - name: HelloWorldStep\n        action: ExecuteBash\n        inputs:\n          commands:\n            - echo \"Hello World! Validate.\"\n  - name: test\n    steps:\n      - name: HelloWorldStep\n        action: ExecuteBash\n        inputs:\n          commands:\n            - echo \"Hello World! Test.\"\n"
			}
		}
	}
}

YAML

Resources:
  ComponentAllParameters:
    Type: 'AWS::ImageBuilder::Component'
    Properties:
      Name: 'component-name'
      Platform: 'Linux'
      Version: '1.0.0'
      Description: 'description'
      ChangeDescription: 'change-description'
      KmsKeyId: 'customer-kms-key-id'
      SupportedOsVersions: 
        - 'Amazon Linux 2'
      Tags:
        CustomerComponentTagKey1: 'CustomerComponentTagValue1'
        CustomerComponentTagKey2: 'CustomerComponentTagValue2'
      # Require one of 'Data' or 'Uri' for Component template
      Data: |
        name: HelloWorldTestingLinuxDoc - InlineData
        description: This is hello world testing doc
        schemaVersion: 1.0

        phases:
          - name: build
            steps:
              - name: HelloWorldStep
                action: ExecuteBash
                inputs:
                  commands:
                    - echo "Hello World! Build."
          - name: validate
            steps:
              - name: HelloWorldStep
                action: ExecuteBash
                inputs:
                  commands:
                    - echo "Hello World! Validate."
          - name: test
            steps:
              - name: HelloWorldStep
                action: ExecuteBash
                inputs:
                  commands:
                    - echo "Hello World! Test."

Create a component using a Uri

The following example shows the schema for the Component resource document in both YAML and JSON format. This example includes details for the Uri field . You can use either the Data or Uri fields to reference the component document.

YAML

Resources:
  ComponentAllParameters:
    Type: 'AWS::ImageBuilder::Component'
    Properties:
      Name: 'component-name'
      Platform: 'Linux'
      Version: '1.0.0'
      # Require one of 'Data' or 'Uri' for Component template
      Uri: 's3://imagebuilder/component_document.yml'
      Description: 'description'
      ChangeDescription: 'change-description'
      KmsKeyId: 'customer-kms-key-id'
      SupportedOsVersions: 
      - 'CentOS'
      - 'Red Hat Enterprise Linux'
      Tags:
        CustomerComponentTagKey1: 'CustomerComponentTagValue1'
        CustomerComponentTagKey2: 'CustomerComponentTagValue2'

JSON

{
    "Resources": {
        "ComponentAllParameters": {
            "Type": "AWS::ImageBuilder::Component",
            "Properties": {
                "Name": "component-name",
                "Platform": "Linux",
                "Version": "1.0.0",
                "Uri": "s3://imagebuilder/component_document.yml",
                "Description": "description",
                "ChangeDescription": "change-description",
                "KmsKeyId": "customer-kms-key-id",
                "SupportedOsVersions": ["CentOS", "Red Hat Enterprise Linux"],
                "Tags": {
                    "CustomerComponentTagKey1": "CustomerComponentTagValue1",
                    "CustomerComponentTagKey2": "CustomerComponentTagValue2"
                }
            }
        }
    }
}