Class MachineImage

Factory functions for standard Amazon Machine Image objects.

Inheritance

object

MachineImage

Namespace: Amazon.CDK.AWS.EC2

Assembly: Amazon.CDK.Lib.dll

Syntax (csharp)

public abstract class MachineImage : DeputyBase

Syntax (vb)

Public MustInherit Class MachineImage Inherits DeputyBase

Remarks

ExampleMetadata: infused

Examples

Vpc vpc;


            var mySecurityGroup = new SecurityGroup(this, "SecurityGroup", new SecurityGroupProps { Vpc = vpc });
            new AutoScalingGroup(this, "ASG", new AutoScalingGroupProps {
                Vpc = vpc,
                InstanceType = InstanceType.Of(InstanceClass.BURSTABLE2, InstanceSize.MICRO),
                MachineImage = MachineImage.LatestAmazonLinux2(),
                SecurityGroup = mySecurityGroup
            });

Synopsis

Constructors

MachineImage()

Factory functions for standard Amazon Machine Image objects.

Methods

FromSsmParameter(string, ISsmParameterImageOptions?)	An image specified in SSM parameter store.
GenericLinux(IDictionary<string, string>, IGenericLinuxImageProps?)	A Linux image where you specify the AMI ID for every region.
GenericWindows(IDictionary<string, string>, IGenericWindowsImageProps?)	A Windows image where you specify the AMI ID for every region.
LatestAmazonLinux(IAmazonLinuxImageProps?)	(deprecated) An Amazon Linux image that is automatically kept up-to-date.
LatestAmazonLinux2(IAmazonLinux2ImageSsmParameterProps?)	An Amazon Linux 2 image that is automatically kept up-to-date.
LatestAmazonLinux2022(IAmazonLinux2022ImageSsmParameterProps?)	(deprecated) An Amazon Linux 2022 image that is automatically kept up-to-date.
LatestAmazonLinux2023(IAmazonLinux2023ImageSsmParameterProps?)	An Amazon Linux 2023 image that is automatically kept up-to-date.
LatestWindows(WindowsVersion, IWindowsImageProps?)	A Windows image that is automatically kept up-to-date.
Lookup(ILookupMachineImageProps)	Look up a shared Machine Image using DescribeImages.
ResolveSsmParameterAtLaunch(string, ISsmParameterImageOptions?)	An image specified in SSM parameter store that will be resolved at instance launch time.

Constructors

MachineImage()

Factory functions for standard Amazon Machine Image objects.

protected MachineImage()

Remarks

ExampleMetadata: infused

Examples

Vpc vpc;


            var mySecurityGroup = new SecurityGroup(this, "SecurityGroup", new SecurityGroupProps { Vpc = vpc });
            new AutoScalingGroup(this, "ASG", new AutoScalingGroupProps {
                Vpc = vpc,
                InstanceType = InstanceType.Of(InstanceClass.BURSTABLE2, InstanceSize.MICRO),
                MachineImage = MachineImage.LatestAmazonLinux2(),
                SecurityGroup = mySecurityGroup
            });

Methods

FromSsmParameter(string, ISsmParameterImageOptions?)

An image specified in SSM parameter store.

public static IMachineImage FromSsmParameter(string parameterName, ISsmParameterImageOptions? options = null)

Parameters

parameterName string

options ISsmParameterImageOptions

Returns

IMachineImage

Remarks

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.

GenericLinux(IDictionary<string, string>, IGenericLinuxImageProps?)

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

public static IMachineImage GenericLinux(IDictionary<string, string> amiMap, IGenericLinuxImageProps? props = null)

Parameters

amiMap IDictionary<string, string>

For every region where you are deploying the stack, specify the AMI ID for that region.

props IGenericLinuxImageProps

Customize the image by supplying additional props.

Returns

IMachineImage

Remarks

ExampleMetadata: infused

GenericWindows(IDictionary<string, string>, IGenericWindowsImageProps?)

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

public static IMachineImage GenericWindows(IDictionary<string, string> amiMap, IGenericWindowsImageProps? props = null)

Parameters

amiMap IDictionary<string, string>

For every region where you are deploying the stack, specify the AMI ID for that region.

props IGenericWindowsImageProps

Customize the image by supplying additional props.

Returns

IMachineImage

Remarks

ExampleMetadata: infused

LatestAmazonLinux(IAmazonLinuxImageProps?)

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

[Obsolete("use MachineImage.latestAmazonLinux2 instead")]
public static IMachineImage LatestAmazonLinux(IAmazonLinuxImageProps? props = null)

Parameters

props IAmazonLinuxImageProps

Returns

IMachineImage

Remarks

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:

MachineImage.LatestAmazonLinux(new AmazonLinuxImageProps {
    // Use Amazon Linux 2
    Generation = AmazonLinuxGeneration.AMAZON_LINUX_2
});

Stability: Deprecated

LatestAmazonLinux2(IAmazonLinux2ImageSsmParameterProps?)

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

public static IMachineImage LatestAmazonLinux2(IAmazonLinux2ImageSsmParameterProps? props = null)

Parameters

props IAmazonLinux2ImageSsmParameterProps

Returns

IMachineImage

Remarks

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.

LatestAmazonLinux2022(IAmazonLinux2022ImageSsmParameterProps?)

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

[Obsolete("- use latestAmazonLinux2023() instead")]
public static IMachineImage LatestAmazonLinux2022(IAmazonLinux2022ImageSsmParameterProps? props = null)

Parameters

props IAmazonLinux2022ImageSsmParameterProps

Returns

IMachineImage

Remarks

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.

Stability: Deprecated

LatestAmazonLinux2023(IAmazonLinux2023ImageSsmParameterProps?)

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

public static IMachineImage LatestAmazonLinux2023(IAmazonLinux2023ImageSsmParameterProps? props = null)

Parameters

props IAmazonLinux2023ImageSsmParameterProps

Returns

IMachineImage

Remarks

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.

LatestWindows(WindowsVersion, IWindowsImageProps?)

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

public static IMachineImage LatestWindows(WindowsVersion version, IWindowsImageProps? props = null)

Parameters

version WindowsVersion

props IWindowsImageProps

Returns

IMachineImage

Remarks

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.

Lookup(ILookupMachineImageProps)

Look up a shared Machine Image using DescribeImages.

public static IMachineImage Lookup(ILookupMachineImageProps props)

Parameters

props ILookupMachineImageProps

Returns

IMachineImage

Remarks

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.

ResolveSsmParameterAtLaunch(string, ISsmParameterImageOptions?)

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

public static IMachineImage ResolveSsmParameterAtLaunch(string parameterName, ISsmParameterImageOptions? options = null)

Parameters

parameterName string

The name of SSM parameter containing the AMI ID.

options ISsmParameterImageOptions

The parameter image options.

Returns

IMachineImage

Remarks

The AMI ID will be resolved at instance launch time.

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