Open History to see the last commit
1import type * as ec2 from "@distilled.cloud/aws/ec2";
2import * as Binding from "alchemy/Binding";
3import type { Input } from "alchemy/Input";
4import type * as Effect from "effect/Effect";
5import type { FindImageOptions } from "./Image.ts";
6
7/**
8 * The `DescribeImages`-backed AMI lookup (IAM action `ec2:DescribeImages`;
9 * `Describe*` actions do not support resource-level permissions, so the
10 * runtime grant is on `*`). Returns the newest available image matching the
11 * filters, or `undefined` when nothing matches.
12 *
13 * As a **data source**, invoke it at plan time via {@link getAmi} — the
14 * result is an `Output` resolved during plan/deploy and inert inside
15 * deployed bundles. As a **runtime binding**, bind it inside a Function to
16 * look images up at runtime with the IAM grant attached automatically.
17 * Provide the implementation with
18 * `Effect.provide(AWS.EC2.GetAmiHttp)` (already registered by
19 * `AWS.providers()` for plan-time use).
20 * ### Looking Up Images
21 * **Example:** Plan-time lookup (data source)
22 * ```typescript
23 * const instance = yield* AWS.EC2.Instance("web", {
24 * imageId: AWS.EC2.getAmi({
25 * owners: ["amazon"],
26 * name: ["al2023-ami-2023.*"],
27 * }).ImageId.as<string>(),
28 * instanceType: "t3.micro",
29 * subnetId: subnet.subnetId,
30 * });
31 * ```
32 * **Example:** Runtime lookup inside a Function
33 * ```typescript
34 * // init — bind the operation
35 * const getAmi = yield* AWS.EC2.GetAmi({
36 * owners: ["amazon"],
37 * name: ["al2023-ami-2023.*"],
38 * });
39 *
40 * // runtime — read the newest matching image
41 * const latest = yield* getAmi();
42 * console.log(latest?.ImageId, latest?.CreationDate);
43 * ```
44 *
45 * @binding
46 */
47export interface GetAmi extends Binding.Service<
48 GetAmi,
49 "AWS.EC2.GetAmi",
50 (
51 options: FindImageOptions,
52 ) => Effect.Effect<() => Effect.Effect<ec2.Image | undefined, ec2.DescribeImagesError>>
53> {}
54
55export const GetAmi = Binding.Service<GetAmi>("AWS.EC2.GetAmi");
56
57/**
58 * Plan-time AMI lookup — the data-source form of {@link GetAmi} (what
59 * Terraform calls a data source and Pulumi an invoke). Returns an
60 * `Output<ec2.Image | undefined>` resolved during plan/deploy; safe to call
61 * from composition code that is re-executed inside a deployed runtime
62 * bundle. Prefer {@link image} (or the distro presets) when you only need
63 * the AMI ID and want a missing image to fail the plan.
64 */
65export const getAmi = <Req = never>(
66 options: Input<FindImageOptions> | Effect.Effect<FindImageOptions, never, Req>,
67) => GetAmi.execute<Req>(options);