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