MachineImage

class aws_cdk.aws_ec2.MachineImage

Bases: object

Factory functions for standard Amazon Machine Image objects.

ExampleMetadata:

infused

Example:

# vpc: ec2.Vpc


my_security_group = ec2.SecurityGroup(self, "SecurityGroup", vpc=vpc)
autoscaling.AutoScalingGroup(self, "ASG",
    vpc=vpc,
    instance_type=ec2.InstanceType.of(ec2.InstanceClass.BURSTABLE2, ec2.InstanceSize.MICRO),
    machine_image=ec2.MachineImage.latest_amazon_linux2(),
    security_group=my_security_group
)

Static Methods

classmethod from_ssm_parameter(parameter_name, *, cached_in_context=None, os=None, parameter_version=None, user_data=None)

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.

Parameters:

  • parameter_name (str) –

  • cached_in_context (Optional[bool]) – Whether the AMI ID is cached to be stable between deployments. By default, the newest image is used on each deployment. This will cause instances to be replaced whenever a new version is released, and may cause downtime if there aren’t enough running instances in the AutoScalingGroup to reschedule the tasks on. If set to true, the AMI ID will be cached in cdk.context.json and the same value will be used on future runs. Your instances will not be replaced but your AMI version will grow old over time. 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. Can not be set to true in environment-agnostic stacks. Default: false

  • os (Optional[OperatingSystemType]) – Operating system. Default: OperatingSystemType.LINUX

  • parameter_version (Optional[str]) – The version of the SSM parameter. Default: no version specified.

  • user_data (Optional[UserData]) – Custom UserData. Default: - UserData appropriate for the OS

Return type:

IMachineImage

classmethod generic_linux(ami_map, *, user_data=None)

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

Parameters:

  • ami_map (Mapping[str, str]) – For every region where you are deploying the stack, specify the AMI ID for that region.

  • user_data (Optional[UserData]) – Initial user data. Default: - Empty UserData for Linux machines

Return type:

IMachineImage

classmethod generic_windows(ami_map, *, user_data=None)

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

Parameters:

  • ami_map (Mapping[str, str]) – For every region where you are deploying the stack, specify the AMI ID for that region.

  • user_data (Optional[UserData]) – Initial user data. Default: - Empty UserData for Windows machines

Return type:

IMachineImage

classmethod latest_amazon_linux(*, cached_in_context=None, cpu_type=None, edition=None, generation=None, kernel=None, storage=None, user_data=None, virtualization=None)

(deprecated) 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.latest_amazon_linux(
    # Use Amazon Linux 2
    generation=ec2.AmazonLinuxGeneration.AMAZON_LINUX_2
)
Parameters:

  • cached_in_context (Optional[bool]) – Whether the AMI ID is cached to be stable between deployments. By default, the newest image is used on each deployment. This will cause instances to be replaced whenever a new version is released, and may cause downtime if there aren’t enough running instances in the AutoScalingGroup to reschedule the tasks on. If set to true, the AMI ID will be cached in cdk.context.json and the same value will be used on future runs. Your instances will not be replaced but your AMI version will grow old over time. 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. Can not be set to true in environment-agnostic stacks. Default: false

  • cpu_type (Optional[AmazonLinuxCpuType]) – CPU Type. Default: X86_64

  • edition (Optional[AmazonLinuxEdition]) – What edition of Amazon Linux to use. Default: Standard

  • generation (Optional[AmazonLinuxGeneration]) – What generation of Amazon Linux to use. Default: AmazonLinux

  • kernel (Optional[AmazonLinuxKernel]) – What kernel version of Amazon Linux to use. Default: -

  • storage (Optional[AmazonLinuxStorage]) – What storage backed image to use. Default: GeneralPurpose

  • user_data (Optional[UserData]) – Initial user data. Default: - Empty UserData for Linux machines

  • virtualization (Optional[AmazonLinuxVirt]) – Virtualization type. Default: HVM

Deprecated:

use MachineImage.latestAmazonLinux2 instead

Stability:

deprecated

Return type:

IMachineImage

classmethod latest_amazon_linux2(*, kernel=None, storage=None, virtualization=None, cpu_type=None, edition=None, cached_in_context=None, user_data=None)

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.

Parameters:

  • kernel (Optional[AmazonLinux2Kernel]) – What kernel version of Amazon Linux to use. Default: -

  • storage (Optional[AmazonLinuxStorage]) – What storage backed image to use. Default: GeneralPurpose

  • virtualization (Optional[AmazonLinuxVirt]) – Virtualization type. Default: HVM

  • cpu_type (Optional[AmazonLinuxCpuType]) – CPU Type. Default: AmazonLinuxCpuType.X86_64

  • edition (Optional[AmazonLinuxEdition]) – What edition of Amazon Linux to use. Default: AmazonLinuxEdition.Standard

  • cached_in_context (Optional[bool]) – Whether the AMI ID is cached to be stable between deployments. By default, the newest image is used on each deployment. This will cause instances to be replaced whenever a new version is released, and may cause downtime if there aren’t enough running instances in the AutoScalingGroup to reschedule the tasks on. If set to true, the AMI ID will be cached in cdk.context.json and the same value will be used on future runs. Your instances will not be replaced but your AMI version will grow old over time. 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. Can not be set to true in environment-agnostic stacks. Default: false

  • user_data (Optional[UserData]) – Initial user data. Default: - Empty UserData for Linux machines

Return type:

IMachineImage

classmethod latest_amazon_linux2022(*, kernel=None, cpu_type=None, edition=None, cached_in_context=None, user_data=None)

(deprecated) 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.

Parameters:

  • kernel (Optional[AmazonLinux2022Kernel]) – What kernel version of Amazon Linux to use. Default: AmazonLinux2022Kernel.DEFAULT

  • cpu_type (Optional[AmazonLinuxCpuType]) – CPU Type. Default: AmazonLinuxCpuType.X86_64

  • edition (Optional[AmazonLinuxEdition]) – What edition of Amazon Linux to use. Default: AmazonLinuxEdition.Standard

  • cached_in_context (Optional[bool]) – Whether the AMI ID is cached to be stable between deployments. By default, the newest image is used on each deployment. This will cause instances to be replaced whenever a new version is released, and may cause downtime if there aren’t enough running instances in the AutoScalingGroup to reschedule the tasks on. If set to true, the AMI ID will be cached in cdk.context.json and the same value will be used on future runs. Your instances will not be replaced but your AMI version will grow old over time. 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. Can not be set to true in environment-agnostic stacks. Default: false

  • user_data (Optional[UserData]) – Initial user data. Default: - Empty UserData for Linux machines

Deprecated:

  • use latestAmazonLinux2023() instead

Stability:

deprecated

Return type:

IMachineImage

classmethod latest_amazon_linux2023(*, kernel=None, cpu_type=None, edition=None, cached_in_context=None, user_data=None)

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.

Parameters:

  • kernel (Optional[AmazonLinux2023Kernel]) – What kernel version of Amazon Linux to use. Default: AmazonLinux2023Kernel.DEFAULT

  • cpu_type (Optional[AmazonLinuxCpuType]) – CPU Type. Default: AmazonLinuxCpuType.X86_64

  • edition (Optional[AmazonLinuxEdition]) – What edition of Amazon Linux to use. Default: AmazonLinuxEdition.Standard

  • cached_in_context (Optional[bool]) – Whether the AMI ID is cached to be stable between deployments. By default, the newest image is used on each deployment. This will cause instances to be replaced whenever a new version is released, and may cause downtime if there aren’t enough running instances in the AutoScalingGroup to reschedule the tasks on. If set to true, the AMI ID will be cached in cdk.context.json and the same value will be used on future runs. Your instances will not be replaced but your AMI version will grow old over time. 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. Can not be set to true in environment-agnostic stacks. Default: false

  • user_data (Optional[UserData]) – Initial user data. Default: - Empty UserData for Linux machines

Return type:

IMachineImage

classmethod latest_windows(version, *, user_data=None)

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.

Parameters:

  • version (WindowsVersion) –

  • user_data (Optional[UserData]) – Initial user data. Default: - Empty UserData for Windows machines

Return type:

IMachineImage

classmethod lookup(*, name, filters=None, owners=None, user_data=None, windows=None)

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.

Parameters:

  • name (str) – Name of the image (may contain wildcards).

  • filters (Optional[Mapping[str, Sequence[str]]]) – Additional filters on the AMI. Default: - No additional filters

  • owners (Optional[Sequence[str]]) – Owner account IDs or aliases. Default: - All owners

  • user_data (Optional[UserData]) – Custom userdata for this image. Default: - Empty user data appropriate for the platform type

  • windows (Optional[bool]) – Look for Windows images. Default: false

Return type:

IMachineImage

classmethod resolve_ssm_parameter_at_launch(parameter_name, *, cached_in_context=None, os=None, parameter_version=None, user_data=None)

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.

Parameters:

  • parameter_name (str) – The name of SSM parameter containing the AMI ID.

  • cached_in_context (Optional[bool]) – Whether the AMI ID is cached to be stable between deployments. By default, the newest image is used on each deployment. This will cause instances to be replaced whenever a new version is released, and may cause downtime if there aren’t enough running instances in the AutoScalingGroup to reschedule the tasks on. If set to true, the AMI ID will be cached in cdk.context.json and the same value will be used on future runs. Your instances will not be replaced but your AMI version will grow old over time. 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. Can not be set to true in environment-agnostic stacks. Default: false

  • os (Optional[OperatingSystemType]) – Operating system. Default: OperatingSystemType.LINUX

  • parameter_version (Optional[str]) – The version of the SSM parameter. Default: no version specified.

  • user_data (Optional[UserData]) – Custom UserData. Default: - UserData appropriate for the OS

See:

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

Return type:

IMachineImage