Skip to content

Commit 93a76e4

Browse files
tarunb12tarunb12
authored
feat(imagebuilder-alpha): add support for Component Construct (#36107)
### Reason for this change Reapplying #36006, following revert in #36104. Adds JSDoc examples in the places that it was causing issues ### Describe any new or updated permissions being added N/A ### Description of how you validated changes Built locally, tests are passing ### Checklist - [x] My code adheres to the [CONTRIBUTING GUIDE](https://github.com/aws/aws-cdk/blob/main/CONTRIBUTING.md) and [DESIGN GUIDELINES](https://github.com/aws/aws-cdk/blob/main/docs/DESIGN_GUIDELINES.md) ---- *By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license*
1 parent 6051039 commit 93a76e4

File tree

45 files changed

+6068
-0
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

45 files changed

+6068
-0
lines changed

‎packages/@aws-cdk/aws-imagebuilder-alpha/README.md‎

Lines changed: 244 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,250 @@ EC2 Image Builder supports AWS-managed components for common tasks, AWS Marketpl
3636
that you create. Components run during specific workflow phases: build and validate phases during the build stage, and
3737
test phase during the test stage.
3838

39+
### Component
40+
41+
A component defines the sequence of steps required to customize an instance during image creation (build component) or
42+
test an instance launched from the created image (test component). Components are created from declarative YAML or JSON
43+
documents that describe runtime configuration for building, validating, or testing instances. Components are included
44+
when added to the image recipe or container recipe for an image build.
45+
46+
EC2 Image Builder supports AWS-managed components for common tasks, AWS Marketplace components, and custom components
47+
that you create. Components run during specific workflow phases: build and validate phases during the build stage, and
48+
test phase during the test stage.
49+
50+
#### Basic Usage
51+
52+
Create a component with the required properties: platform and component data.
53+
54+
```ts
55+
const component = new imagebuilder.Component(this, 'MyComponent', {
56+
platform: imagebuilder.Platform.LINUX,
57+
data: imagebuilder.ComponentData.fromJsonObject({
58+
schemaVersion: imagebuilder.ComponentSchemaVersion.V1_0,
59+
phases: [
60+
{
61+
name: imagebuilder.ComponentPhaseName.BUILD,
62+
steps: [
63+
{
64+
name: 'install-app',
65+
action: imagebuilder.ComponentAction.EXECUTE_BASH,
66+
inputs: {
67+
commands: ['echo "Installing my application..."', 'yum update -y'],
68+
},
69+
},
70+
],
71+
},
72+
],
73+
}),
74+
});
75+
```
76+
77+
#### Component Data Sources
78+
79+
##### Inline Component Data
80+
81+
Use `ComponentData.fromInline()` for existing YAML/JSON definitions:
82+
83+
```ts
84+
const component = new imagebuilder.Component(this, 'InlineComponent', {
85+
platform: imagebuilder.Platform.LINUX,
86+
data: imagebuilder.ComponentData.fromInline(`
87+
name: my-component
88+
schemaVersion: 1.0
89+
phases:
90+
- name: build
91+
steps:
92+
- name: update-os
93+
action: ExecuteBash
94+
inputs:
95+
commands: ['yum update -y']
96+
`)
97+
});
98+
```
99+
100+
##### JSON Object Component Data
101+
102+
Most developer-friendly approach using objects:
103+
104+
```ts
105+
106+
const component = new imagebuilder.Component(this, 'JsonComponent', {
107+
platform: imagebuilder.Platform.LINUX,
108+
data: imagebuilder.ComponentData.fromJsonObject({
109+
schemaVersion: imagebuilder.ComponentSchemaVersion.V1_0,
110+
phases: [
111+
{
112+
name: imagebuilder.ComponentPhaseName.BUILD,
113+
steps: [
114+
{
115+
name: 'configure-app',
116+
action: imagebuilder.ComponentAction.CREATE_FILE,
117+
inputs: {
118+
path: '/etc/myapp/config.json',
119+
content: '{"env": "production"}'
120+
}
121+
}
122+
]
123+
}
124+
]
125+
})
126+
});
127+
```
128+
129+
##### Structured Component Document
130+
131+
For type-safe, CDK-native definitions with enhanced properties like `timeout` and `onFailure`.
132+
133+
###### Defining a component step
134+
135+
You can define steps in the component which will be executed in order when the component is applied:
136+
137+
```ts
138+
const step: imagebuilder.ComponentDocumentStep = {
139+
name: 'configure-app',
140+
action: imagebuilder.ComponentAction.CREATE_FILE,
141+
inputs: imagebuilder.ComponentStepInputs.fromObject({
142+
path: '/etc/myapp/config.json',
143+
content: '{"env": "production"}'
144+
})
145+
};
146+
```
147+
148+
###### Defining a component phase
149+
150+
Phases group steps together, which run in sequence when building, validating or testing in the component:
151+
152+
```ts
153+
const phase: imagebuilder.ComponentDocumentPhase = {
154+
name: imagebuilder.ComponentPhaseName.BUILD,
155+
steps: [
156+
{
157+
name: 'configure-app',
158+
action: imagebuilder.ComponentAction.CREATE_FILE,
159+
inputs: imagebuilder.ComponentStepInputs.fromObject({
160+
path: '/etc/myapp/config.json',
161+
content: '{"env": "production"}'
162+
})
163+
}
164+
]
165+
};
166+
```
167+
168+
###### Defining a component
169+
170+
The component data defines all steps across the provided phases to execute during the build:
171+
172+
```ts
173+
const component = new imagebuilder.Component(this, 'StructuredComponent', {
174+
platform: imagebuilder.Platform.LINUX,
175+
data: imagebuilder.ComponentData.fromComponentDocumentJsonObject({
176+
schemaVersion: imagebuilder.ComponentSchemaVersion.V1_0,
177+
phases: [
178+
{
179+
name: imagebuilder.ComponentPhaseName.BUILD,
180+
steps: [
181+
{
182+
name: 'install-with-timeout',
183+
action: imagebuilder.ComponentAction.EXECUTE_BASH,
184+
timeout: Duration.minutes(10),
185+
onFailure: imagebuilder.ComponentOnFailure.CONTINUE,
186+
inputs: imagebuilder.ComponentStepInputs.fromObject({
187+
commands: ['./install-script.sh']
188+
})
189+
}
190+
]
191+
}
192+
]
193+
})
194+
});
195+
```
196+
197+
##### S3 Component Data
198+
199+
For those components you want to upload or have uploaded to S3:
200+
201+
```ts
202+
// Upload a local file
203+
const componentFromAsset = new imagebuilder.Component(this, 'AssetComponent', {
204+
platform: imagebuilder.Platform.LINUX,
205+
data: imagebuilder.ComponentData.fromAsset(this, 'ComponentAsset', './my-component.yml'),
206+
});
207+
208+
// Reference an existing S3 object
209+
const bucket = s3.Bucket.fromBucketName(this, 'ComponentBucket', 'my-components-bucket');
210+
const componentFromS3 = new imagebuilder.Component(this, 'S3Component', {
211+
platform: imagebuilder.Platform.LINUX,
212+
data: imagebuilder.ComponentData.fromS3(bucket, 'components/my-component.yml'),
213+
});
214+
```
215+
216+
#### Encrypt component data with a KMS key
217+
218+
You can encrypt component data with a KMS key, so that only principals with access to decrypt with the key are able to
219+
access the component data.
220+
221+
```ts
222+
const component = new imagebuilder.Component(this, 'EncryptedComponent', {
223+
platform: imagebuilder.Platform.LINUX,
224+
kmsKey: new kms.Key(this, 'ComponentKey'),
225+
data: imagebuilder.ComponentData.fromJsonObject({
226+
schemaVersion: imagebuilder.ComponentSchemaVersion.V1_0,
227+
phases: [
228+
{
229+
name: imagebuilder.ComponentPhaseName.BUILD,
230+
steps: [
231+
{
232+
name: 'secure-setup',
233+
action: imagebuilder.ComponentAction.EXECUTE_BASH,
234+
inputs: {
235+
commands: ['echo "This component data is encrypted with KMS"'],
236+
},
237+
},
238+
],
239+
},
240+
],
241+
}),
242+
});
243+
```
244+
245+
#### AWS-Managed Components
246+
247+
AWS provides a collection of managed components for common tasks:
248+
249+
```ts
250+
// Install AWS CLI v2
251+
const awsCliComponent = imagebuilder.AwsManagedComponent.awsCliV2(this, 'AwsCli', {
252+
platform: imagebuilder.Platform.LINUX
253+
});
254+
255+
// Update the operating system
256+
const updateComponent = imagebuilder.AwsManagedComponent.updateOS(this, 'UpdateOS', {
257+
platform: imagebuilder.Platform.LINUX
258+
});
259+
260+
// Reference any AWS-managed component by name
261+
const customAwsComponent = imagebuilder.AwsManagedComponent.fromAwsManagedComponentName(
262+
this,
263+
'CloudWatchAgent',
264+
'amazon-cloudwatch-agent-linux'
265+
);
266+
```
267+
268+
#### AWS Marketplace Components
269+
270+
You can reference AWS Marketplace components using the marketplace component name and its product ID:
271+
272+
```ts
273+
const marketplaceComponent = imagebuilder.AwsMarketplaceComponent.fromAwsMarketplaceComponentAttributes(
274+
this,
275+
'MarketplaceComponent',
276+
{
277+
componentName: 'my-marketplace-component',
278+
marketplaceProductId: 'prod-1234567890abcdef0',
279+
}
280+
);
281+
```
282+
39283
### Infrastructure Configuration
40284

41285
Infrastructure configuration defines the compute resources and environment settings used during the image building

0 commit comments

Comments
 (0)