Skip to content

Commit aef71d7

Browse files
author
Tarun Belani
committed
feat(imagebuilder-alpha): add support for Image Recipe Construct
1 parent 183ec35 commit aef71d7

34 files changed

+3785
-0
lines changed

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

Lines changed: 196 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,202 @@ 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+
### Image Recipe
40+
41+
#### Image Recipe Basic Usage
42+
43+
Create an image recipe with the required base image:
44+
45+
```ts
46+
const imageRecipe = new imagebuilder.ImageRecipe(this, 'MyImageRecipe', {
47+
baseImage: imagebuilder.BaseImage.fromSsmParameterName(
48+
'/aws/service/ami-amazon-linux-latest/al2023-ami-minimal-kernel-default-x86_64'
49+
)
50+
});
51+
```
52+
53+
#### Image Recipe Base Images
54+
55+
To create a recipe, you have to select a base image to build and customize from. This base image can be referenced from
56+
various sources, such as from SSM parameters, AWS Marketplace products, and AMI IDs directly.
57+
58+
##### SSM Parameters
59+
60+
Using SSM parameter references:
61+
62+
```ts
63+
const imageRecipe = new imagebuilder.ImageRecipe(this, 'SsmImageRecipe', {
64+
baseImage: imagebuilder.BaseImage.fromSsmParameterName(
65+
'/aws/service/ami-amazon-linux-latest/al2023-ami-minimal-kernel-default-x86_64'
66+
)
67+
});
68+
69+
// Using an SSM parameter construct
70+
const parameter = ssm.StringParameter.fromStringParameterName(
71+
this,
72+
'BaseImageParameter',
73+
'/aws/service/ami-windows-latest/Windows_Server-2022-English-Full-Base'
74+
);
75+
const windowsRecipe = new imagebuilder.ImageRecipe(this, 'WindowsImageRecipe', {
76+
baseImage: imagebuilder.BaseImage.fromSsmParameter(parameter)
77+
});
78+
```
79+
80+
##### AMI IDs
81+
82+
When you have a specific AMI to use:
83+
84+
```ts
85+
const imageRecipe = new imagebuilder.ImageRecipe(this, 'AmiImageRecipe', {
86+
baseImage: imagebuilder.BaseImage.fromAmiId('ami-12345678')
87+
});
88+
```
89+
90+
##### Marketplace Images
91+
92+
For marketplace base images:
93+
94+
```ts
95+
const imageRecipe = new imagebuilder.ImageRecipe(this, 'MarketplaceImageRecipe', {
96+
baseImage: imagebuilder.BaseImage.fromMarketplaceProductId('prod-1234567890abcdef0')
97+
});
98+
```
99+
100+
#### Image Recipe Components
101+
102+
Components from various sources, such as custom-owned, AWS-owned, or AWS Marketplace-owned, can optionally be included
103+
in recipes. For parameterized components, you are able to provide the parameters to use in the recipe, which will be
104+
applied during the image build when executing components.
105+
106+
##### Custom Components in Image Recipes
107+
108+
Add your own components to the recipe:
109+
110+
```ts
111+
const customComponent = new imagebuilder.Component(this, 'MyComponent', {
112+
platform: imagebuilder.Platform.LINUX,
113+
data: imagebuilder.ComponentData.fromJsonObject({
114+
schemaVersion: imagebuilder.ComponentSchemaVersion.V1_0,
115+
phases: [
116+
{
117+
name: imagebuilder.ComponentPhaseName.BUILD,
118+
steps: [
119+
{
120+
name: 'install-app',
121+
action: imagebuilder.ComponentAction.EXECUTE_BASH,
122+
inputs: {
123+
commands: ['yum install -y my-application']
124+
}
125+
}
126+
]
127+
}
128+
]
129+
})
130+
});
131+
132+
const imageRecipe = new imagebuilder.ImageRecipe(this, 'ComponentImageRecipe', {
133+
baseImage: imagebuilder.BaseImage.fromSsmParameterName(
134+
'/aws/service/ami-amazon-linux-latest/al2023-ami-minimal-kernel-default-x86_64'
135+
),
136+
components: [
137+
{
138+
component: customComponent
139+
}
140+
]
141+
});
142+
```
143+
144+
##### AWS-Managed Components in Image Recipes
145+
146+
Use pre-built AWS components:
147+
148+
```ts
149+
const imageRecipe = new imagebuilder.ImageRecipe(this, 'AwsManagedImageRecipe', {
150+
baseImage: imagebuilder.BaseImage.fromSsmParameterName(
151+
'/aws/service/ami-amazon-linux-latest/al2023-ami-minimal-kernel-default-x86_64'
152+
),
153+
components: [
154+
{
155+
component: imagebuilder.AwsManagedComponent.updateOS(this, 'UpdateOS', {
156+
platform: imagebuilder.Platform.LINUX
157+
})
158+
},
159+
{
160+
component: imagebuilder.AwsManagedComponent.awsCliV2(this, 'AwsCli', {
161+
platform: imagebuilder.Platform.LINUX
162+
})
163+
}
164+
]
165+
});
166+
```
167+
168+
##### Component Parameters in Image Recipes
169+
170+
Pass parameters to components that accept them:
171+
172+
```ts
173+
const parameterizedComponent = imagebuilder.Component.fromComponentName(
174+
this,
175+
'ParameterizedComponent',
176+
'my-parameterized-component'
177+
);
178+
179+
const imageRecipe = new imagebuilder.ImageRecipe(this, 'ParameterizedImageRecipe', {
180+
baseImage: imagebuilder.BaseImage.fromSsmParameterName(
181+
'/aws/service/ami-amazon-linux-latest/al2023-ami-minimal-kernel-default-x86_64'
182+
),
183+
components: [
184+
{
185+
component: parameterizedComponent,
186+
parameters: {
187+
environment: imagebuilder.ComponentParameterValue.fromString('production'),
188+
version: imagebuilder.ComponentParameterValue.fromString('1.0.0')
189+
}
190+
}
191+
]
192+
});
193+
```
194+
195+
#### Image Recipe Configuration
196+
197+
##### Block Device Configuration
198+
199+
Configure storage for the build instance:
200+
201+
```ts
202+
const imageRecipe = new imagebuilder.ImageRecipe(this, 'BlockDeviceImageRecipe', {
203+
baseImage: imagebuilder.BaseImage.fromSsmParameterName(
204+
'/aws/service/ami-amazon-linux-latest/al2023-ami-minimal-kernel-default-x86_64'
205+
),
206+
blockDevices: [
207+
{
208+
deviceName: '/dev/sda1',
209+
volume: ec2.BlockDeviceVolume.ebs(100, {
210+
encrypted: true,
211+
volumeType: ec2.EbsDeviceVolumeType.GENERAL_PURPOSE_SSD_GP3
212+
})
213+
}
214+
]
215+
});
216+
```
217+
218+
##### AMI Tagging
219+
220+
Tag the output AMI:
221+
222+
```ts
223+
const imageRecipe = new imagebuilder.ImageRecipe(this, 'TaggedImageRecipe', {
224+
baseImage: imagebuilder.BaseImage.fromSsmParameterName(
225+
'/aws/service/ami-amazon-linux-latest/al2023-ami-minimal-kernel-default-x86_64'
226+
),
227+
amiTags: {
228+
Environment: 'Production',
229+
Application: 'WebServer',
230+
Owner: 'DevOps Team'
231+
}
232+
});
233+
```
234+
39235
### Component
40236

41237
A component defines the sequence of steps required to customize an instance during image creation (build component) or

‎packages/@aws-cdk/aws-imagebuilder-alpha/lib/base-image.ts‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
import * as ssm from 'aws-cdk-lib/aws-ssm';
2+
3+
/**
4+
* Represents a base image that is used to start from in EC2 Image Builder image builds
5+
*/
6+
export class BaseImage {
7+
/**
8+
* The AMI ID to use as a base image in an image recipe
9+
*
10+
* @param amiId The AMI ID to use as the base image
11+
*/
12+
public static fromAmiId(amiId: string): BaseImage {
13+
return new BaseImage(amiId);
14+
}
15+
16+
/**
17+
* The marketplace product ID for an AMI product to use as the base image in an image recipe
18+
*
19+
* @param productId The Marketplace AMI product ID to use as the base image
20+
*/
21+
public static fromMarketplaceProductId(productId: string): BaseImage {
22+
return new BaseImage(productId);
23+
}
24+
25+
/**
26+
* The SSM parameter to use as the base image in an image recipe
27+
*
28+
* @param parameter The SSM parameter to use as the base image
29+
*/
30+
public static fromSsmParameter(parameter: ssm.IParameter): BaseImage {
31+
return this.fromSsmParameterName(parameter.parameterArn);
32+
}
33+
34+
/**
35+
* The parameter name for the SSM parameter to use as the base image in an image recipe
36+
*
37+
* @param parameterName The name of the SSM parameter to use as the base image
38+
*/
39+
public static fromSsmParameterName(parameterName: string): BaseImage {
40+
return new BaseImage(`ssm:${parameterName}`);
41+
}
42+
43+
/**
44+
* The direct string value of the base image to use in an image recipe. This can be an EC2 Image Builder image ARN,
45+
* an SSM parameter, an AWS Marketplace product ID, or an AMI ID.
46+
*
47+
* @param baseImageString The base image as a direct string value
48+
*/
49+
public static fromString(baseImageString: string): BaseImage {
50+
return new BaseImage(baseImageString);
51+
}
52+
53+
/**
54+
* The rendered base image to use
55+
**/
56+
public readonly image: string;
57+
58+
protected constructor(image: string) {
59+
this.image = image;
60+
}
61+
}

0 commit comments

Comments
 (0)