# MachineImage

Factory functions for standard Amazon Machine Image objects.

- Source: [`aws-ec2/lib/machine-image/machine-image.ts`](https://github.com/aws/aws-cdk/blob/v2.273.0/packages/aws-cdk-lib/aws-ec2/lib/machine-image/machine-image.ts#L22)
- Type last changed: v2.89.0 · 28 Jul 2023

## Example

```ts
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

```ts
new MachineImage()
```

## Methods

- `fromSsmParameter(parameterName: string, options?: SsmParameterImageOptions): IMachineImage` (static) — 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.

- `genericLinux(amiMap: { [key: string]: string }, props?: GenericLinuxImageProps): IMachineImage` (static) — A Linux image where you specify the AMI ID for every region.

  **Parameters**

  - `amiMap` — For every region where you are deploying the stack, specify the AMI ID for that region.
  - `props` — Customize the image by supplying additional props.

- `genericWindows(amiMap: { [key: string]: string }, props?: GenericWindowsImageProps): IMachineImage` (static) — A Windows image where you specify the AMI ID for every region.

  **Parameters**

  - `amiMap` — For every region where you are deploying the stack, specify the AMI ID for that region.
  - `props` — Customize the image by supplying additional props.

- `latestAmazonLinux(props?: AmazonLinuxImageProps): IMachineImage` (static) — use MachineImage.latestAmazonLinux2 instead

  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:

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

- `latestAmazonLinux2(props?: AmazonLinux2ImageSsmParameterProps): IMachineImage` (static) — 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.

- `latestAmazonLinux2022(props?: AmazonLinux2022ImageSsmParameterProps): IMachineImage` (static) — - use latestAmazonLinux2023() instead

  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.

- `latestAmazonLinux2023(props?: AmazonLinux2023ImageSsmParameterProps): IMachineImage` (static) — 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.

- `latestWindows(version: WindowsVersion, props?: WindowsImageProps): IMachineImage` (static) — 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.

- `lookup(props: LookupMachineImageProps): IMachineImage` (static) — 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.

- `resolveSsmParameterAtLaunch(parameterName: string, options?: SsmParameterImageOptions): IMachineImage` (static) — 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**

  - `parameterName` — The name of SSM parameter containing the AMI ID.
  - `options` — The parameter image options.