MachineImage

class aws_cdk.aws_ec2.MachineImage

Bases: object

Factory functions for standard Amazon Machine Image objects.

ExampleMetadata:

infused

Example:

# vpc: ec2.Vpc


template = ec2.LaunchTemplate(self, "LaunchTemplate",
    machine_image=ec2.MachineImage.latest_amazon_linux(),
    security_group=ec2.SecurityGroup(self, "LaunchTemplateSG",
        vpc=vpc
    )
)

Static Methods

classmethod from_ssm_parameter(parameter_name, *, cached_in_context=None, os=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

  • 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)

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.

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

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