class MachineImage

Language	Type name
.NET	Amazon.CDK.AWS.EC2.MachineImage
Go	github.com/aws/aws-cdk-go/awscdk/v2/awsec2#MachineImage
Java	software.amazon.awscdk.services.ec2.MachineImage
Python	aws_cdk.aws_ec2.MachineImage
TypeScript (source)	aws-cdk-lib » aws_ec2 » MachineImage

Factory functions for standard Amazon Machine Image objects.

Example

declare const vpc: ec2.Vpc;

const mySecurityGroup = new ec2.SecurityGroup(this, 'SecurityGroup', { vpc });
new autoscaling.AutoScalingGroup(this, 'ASG', {
  vpc,
  instanceType: ec2.InstanceType.of(ec2.InstanceClass.BURSTABLE2, ec2.InstanceSize.MICRO),
  machineImage: ec2.MachineImage.latestAmazonLinux2(),
  securityGroup: mySecurityGroup,
});

Initializer

new MachineImage()

Methods

Name	Description
static fromSsmParameter(parameterName, options?)	An image specified in SSM parameter store.
static genericLinux(amiMap, props?)	A Linux image where you specify the AMI ID for every region.
static genericWindows(amiMap, props?)	A Windows image where you specify the AMI ID for every region.
static latestAmazonLinux(props?)⚠️	An Amazon Linux image that is automatically kept up-to-date.
static latestAmazonLinux2(props?)	An Amazon Linux 2 image that is automatically kept up-to-date.
static latestAmazonLinux2022(props?)⚠️	An Amazon Linux 2022 image that is automatically kept up-to-date.
static latestAmazonLinux2023(props?)	An Amazon Linux 2023 image that is automatically kept up-to-date.
static latestWindows(version, props?)	A Windows image that is automatically kept up-to-date.
static lookup(props)	Look up a shared Machine Image using DescribeImages.
static resolveSsmParameterAtLaunch(parameterName, options?)	An image specified in SSM parameter store that will be resolved at instance launch time.

---

static fromSsmParameter(parameterName, options?)

public static fromSsmParameter(parameterName: string, options?: SsmParameterImageOptions): IMachineImage

Parameters

• parameterName string
• options SsmParameterImageOptions

Returns

• IMachineImage

An image specified in SSM parameter store.

By default, the SSM parameter is refreshed at every deployment, causing your instances to be replaced whenever a new version of the AMI is released.

Pass { cachedInContext: true } to keep the AMI ID stable. If you do, you will have to remember to periodically invalidate the context to refresh to the newest AMI ID.

---

static genericLinux(amiMap, props?)

public static genericLinux(amiMap: { [string]: string }, props?: GenericLinuxImageProps): IMachineImage

Parameters

• amiMap { [string]: string } — For every region where you are deploying the stack, specify the AMI ID for that region.
• props GenericLinuxImageProps — Customize the image by supplying additional props.

Returns

• IMachineImage

A Linux image where you specify the AMI ID for every region.

---

static genericWindows(amiMap, props?)

public static genericWindows(amiMap: { [string]: string }, props?: GenericWindowsImageProps): IMachineImage

Parameters

• amiMap { [string]: string } — For every region where you are deploying the stack, specify the AMI ID for that region.
• props GenericWindowsImageProps — Customize the image by supplying additional props.

Returns

• IMachineImage

A Windows image where you specify the AMI ID for every region.

---

static latestAmazonLinux(props?)⚠️

public static latestAmazonLinux(props?: AmazonLinuxImageProps): IMachineImage

⚠️ Deprecated: use MachineImage.latestAmazonLinux2 instead

Parameters

• props AmazonLinuxImageProps

Returns

• IMachineImage

An Amazon Linux image that is automatically kept up-to-date.

This Machine Image automatically updates to the latest version on every deployment. Be aware this will cause your instances to be replaced when a new version of the image becomes available. Do not store stateful information on the instance if you are using this image.

N.B.: "latest" in the name of this function indicates that it always uses the most recent image of a particular generation of Amazon Linux, not that it uses the "latest generation". For backwards compatibility, this function uses Amazon Linux 1 if no generation is specified.

Specify the desired generation using the generation property:

ec2.MachineImage.latestAmazonLinux({
  // Use Amazon Linux 2
  generation: ec2.AmazonLinuxGeneration.AMAZON_LINUX_2,
})

---

static latestAmazonLinux2(props?)

public static latestAmazonLinux2(props?: AmazonLinux2ImageSsmParameterProps): IMachineImage

Parameters

• props AmazonLinux2ImageSsmParameterProps

Returns

• IMachineImage

An Amazon Linux 2 image that is automatically kept up-to-date.

This Machine Image automatically updates to the latest version on every deployment. Be aware this will cause your instances to be replaced when a new version of the image becomes available. Do not store stateful information on the instance if you are using this image.

---

static latestAmazonLinux2022(props?)⚠️

public static latestAmazonLinux2022(props?: AmazonLinux2022ImageSsmParameterProps): IMachineImage

⚠️ Deprecated: - use latestAmazonLinux2023() instead

Parameters

• props AmazonLinux2022ImageSsmParameterProps

Returns

• IMachineImage

An Amazon Linux 2022 image that is automatically kept up-to-date.

This Machine Image automatically updates to the latest version on every deployment. Be aware this will cause your instances to be replaced when a new version of the image becomes available. Do not store stateful information on the instance if you are using this image.

---

static latestAmazonLinux2023(props?)

public static latestAmazonLinux2023(props?: AmazonLinux2023ImageSsmParameterProps): IMachineImage

Parameters

• props AmazonLinux2023ImageSsmParameterProps

Returns

• IMachineImage

An Amazon Linux 2023 image that is automatically kept up-to-date.

This Machine Image automatically updates to the latest version on every deployment. Be aware this will cause your instances to be replaced when a new version of the image becomes available. Do not store stateful information on the instance if you are using this image.

---

static latestWindows(version, props?)

public static latestWindows(version: WindowsVersion, props?: WindowsImageProps): IMachineImage

Parameters

• version WindowsVersion
• props WindowsImageProps

Returns

• IMachineImage

A Windows image that is automatically kept up-to-date.

This Machine Image automatically updates to the latest version on every deployment. Be aware this will cause your instances to be replaced when a new version of the image becomes available. Do not store stateful information on the instance if you are using this image.

---

static lookup(props)

public static lookup(props: LookupMachineImageProps): IMachineImage

Parameters

• props LookupMachineImageProps

Returns

• IMachineImage

Look up a shared Machine Image using DescribeImages.

The most recent, available, launchable image matching the given filter criteria will be used. Looking up AMIs may take a long time; specify as many filter criteria as possible to narrow down the search.

The AMI selected will be cached in cdk.context.json and the same value will be used on future runs. To refresh the AMI lookup, you will have to evict the value from the cache using the cdk context command. See https://docs.aws.amazon.com/cdk/latest/guide/context.html for more information.

This function can not be used in environment-agnostic stacks.

---

static resolveSsmParameterAtLaunch(parameterName, options?)

public static resolveSsmParameterAtLaunch(parameterName: string, options?: SsmParameterImageOptions): IMachineImage

Parameters

• parameterName string — The name of SSM parameter containing the AMI ID.
• options SsmParameterImageOptions — The parameter image options.

Returns

• IMachineImage

An image specified in SSM parameter store that will be resolved at instance launch time.

The AMI ID will be resolved at instance launch time.

See also: https://docs.aws.amazon.com/autoscaling/ec2/userguide/using-systems-manager-parameters.html