@sst-community/sst 4.19.0 → 5.0.0-alpha.1

package/platform/types/components/aws/microvm.d.ts

@@ -0,0 +1,439 @@
+import { ComponentResourceOptions, Output } from "@pulumi/pulumi";
+import { cloudwatch, iam, lambda, lambdamicrovms } from "@pulumi/aws";
+import { Component, Transform } from "../component";
+import { Link } from "../link";
+import { Input } from "../input";
+import { DurationHours } from "../duration";
+import { RETENTION } from "./logging";
+import { FunctionArgs } from "./function";
+import { Vpc } from "./vpc";
+export interface MicroVmArgs {
+    /**
+     * The image to run. Lambda builds it from your `Dockerfile`, on top of its Amazon Linux
+     * 2023 base image.
+     *
+     * SST zips the `context` directory, puts the `dockerfile` at the root of the zip, and
+     * uploads it. Lambda builds the image from the zip, starts your app, and takes a snapshot
+     * that every MicroVM starts from. So your app starts once, at build time: anything it
+     * does on startup, like reading the time or generating an ID, is the same in every
+     * MicroVM.
+     *
+     * A build takes a few minutes, and runs again whenever the code, the `environment` or a
+     * link's values change. If it fails, the deploy fails, and the build's logs are in the
+     * log group. MicroVMs keep starting from the last version that built.
+     *
+     * Each build adds a version to the image, and Lambda allows 50. After a build, SST
+     * deletes the old ones. It keeps the newest 5 that built, and any that MicroVMs still
+     * run from.
+     *
+     * Lambda runs the `Dockerfile` itself, so Docker build args, targets, secrets and caches
+     * don't apply. Files matched by a `.dockerignore` in the `context` aren't uploaded, and
+     * neither are the `sst-env.d.ts` files SST generates, so writing them doesn't rebuild
+     * the image.
+     *
+     * @default `{ context: ".", dockerfile: "Dockerfile" }`
+     * @example
+     * ```js
+     * {
+     *   image: {
+     *     context: "./sandbox",
+     *     dockerfile: "Dockerfile"
+     *   }
+     * }
+     * ```
+     */
+    image?: Input<{
+        /**
+         * The path to the directory that's zipped and uploaded, relative to your project root.
+         * @default `"."`
+         */
+        context?: Input<string>;
+        /**
+         * The path to the `Dockerfile`, relative to the `context`.
+         * @default `"Dockerfile"`
+         */
+        dockerfile?: Input<string>;
+    }>;
+    /**
+     * The port your app listens on. The SDK sends requests to this port.
+     * @default `8080`
+     */
+    port?: Input<number>;
+    /**
+     * Key-value pairs set as environment variables in the image.
+     *
+     * They're part of the image, so changing them rebuilds it. Lambda allows up to 50.
+     */
+    environment?: FunctionArgs["environment"];
+    /**
+     * [Link resources](/docs/linking/) to your MicroVMs. This grants the execution role the
+     * permissions of the linked resources, and sets them as environment variables in the
+     * image, so your app can read them through the SDK.
+     *
+     * Changing a linked resource's values rebuilds the image.
+     *
+     * To read them with `Resource`, add `sst` to your app's dependencies. It comes with the
+     * SST CLI, about 75 MB, as an optional dependency that your app doesn't need. To leave it
+     * out of the image, install with `npm install --omit=optional`.
+     *
+     * :::caution
+     * The links' values, `Secret` values included, are stored in the image. Anyone allowed
+     * to call `lambda:GetMicrovmImageVersion` on it can read them.
+     * :::
+     *
+     * @example
+     * ```js
+     * {
+     *   link: [bucket]
+     * }
+     * ```
+     */
+    link?: FunctionArgs["link"];
+    /**
+     * Permissions and the resources that your MicroVMs need to access. They're added to the
+     * execution role.
+     *
+     * @example
+     * ```js
+     * {
+     *   permissions: [
+     *     {
+     *       actions: ["bedrock:InvokeModel"],
+     *       resources: ["*"]
+     *     }
+     *   ]
+     * }
+     * ```
+     */
+    permissions?: FunctionArgs["permissions"];
+    /**
+     * The longest a MicroVM can exist, running and suspended. Lambda terminates it after
+     * this, up to 8 hours.
+     *
+     * This is the default for `microvm.run()` in the SDK, which can override it.
+     *
+     * @default `"1 hour"`
+     */
+    duration?: Input<DurationHours>;
+    /**
+     * When a MicroVM gets no requests for a while, Lambda suspends it, and you stop paying
+     * for compute. Its memory and disk are kept. Then, if it stays suspended for too long,
+     * Lambda terminates it.
+     *
+     * Pass `false` to keep MicroVMs running until `duration` is up.
+     *
+     * This is the default for `microvm.run()` in the SDK, which can override it.
+     *
+     * @default `{ suspendAfter: "15 minutes", terminateAfter: "15 minutes", autoResume: true }`
+     */
+    idle?: Input<false | {
+        /**
+         * How long a MicroVM can go without a request before it's suspended. At least
+         * 1 minute.
+         * @default `"15 minutes"`
+         */
+        suspendAfter?: Input<DurationHours>;
+        /**
+         * How long a MicroVM can stay suspended before it's terminated.
+         * @default `"15 minutes"`
+         */
+        terminateAfter?: Input<DurationHours>;
+        /**
+         * Resume a suspended MicroVM when a request arrives for it.
+         * @default `true`
+         */
+        autoResume?: Input<boolean>;
+    }>;
+    /**
+     * Configure the log group for your MicroVMs' logs.
+     * @default `{ retention: "1 month" }`
+     */
+    logging?: Input<{
+        /**
+         * How long to keep the logs.
+         * @default `"1 month"`
+         */
+        retention?: Input<keyof typeof RETENTION>;
+    }>;
+    /**
+     * Send your MicroVMs' outbound traffic through the private subnets of a VPC, so they can
+     * reach private resources, like a database.
+     *
+     * Requests to a MicroVM still come in through its HTTPS endpoint. Only its outbound
+     * traffic goes through the VPC, and it reaches the internet only through the VPC's NAT.
+     *
+     * This creates a Lambda network connector that every MicroVM is run with. Creating it
+     * takes about 5 minutes. Lambda's docs say to terminate the MicroVMs that use it before
+     * it's changed or removed.
+     *
+     * @example
+     * Create a `Vpc` component, with a NAT if your MicroVMs need the internet.
+     *
+     * ```js title="sst.config.ts"
+     * const myVpc = new sst.aws.Vpc("MyVpc", { nat: "ec2" });
+     * ```
+     *
+     * And pass it in.
+     *
+     * ```js
+     * {
+     *   vpc: myVpc
+     * }
+     * ```
+     *
+     * Or pass in the subnets and security groups of an existing VPC.
+     *
+     * ```js
+     * {
+     *   vpc: {
+     *     privateSubnets: ["subnet-0b6a2b73896dc8c4c", "subnet-021389ebee680c2f0"],
+     *     securityGroups: ["sg-0399348378a4c256c"]
+     *   }
+     * }
+     * ```
+     */
+    vpc?: Vpc | Input<{
+        /**
+         * A list of VPC security group IDs.
+         */
+        securityGroups: Input<Input<string>[]>;
+        /**
+         * A list of VPC subnet IDs.
+         */
+        privateSubnets: Input<Input<string>[]>;
+    }>;
+    /**
+     * Configure how this component works in `sst dev`.
+     *
+     * By default, the image isn't built in `sst dev`. Instead, `dev.command` runs your app on
+     * your machine, in a tab of the `sst dev` multiplexer, with the links and the execution
+     * role's permissions.
+     *
+     * In `sst dev`, the SDK sends the requests of every MicroVM you run to `dev.url`. So the
+     * MicroVMs aren't isolated from each other the way they are once deployed.
+     *
+     * So that the CLI can assume it, the execution role trusts your AWS account in `sst dev`,
+     * as `Service`'s and `Task`'s roles do. Any IAM user or role in the account whose
+     * policies allow `sts:AssumeRole` on it can then assume it too.
+     *
+     * To build the image and run real MicroVMs in `sst dev`, pass in `false`.
+     */
+    dev?: false | {
+        /**
+         * The command that `sst dev` runs to start your app.
+         */
+        command?: Input<string>;
+        /**
+         * The directory the `command` runs in.
+         * @default The `image.context`
+         */
+        directory?: Input<string>;
+        /**
+         * The URL your app listens on in `sst dev`.
+         * @default `"http://localhost:8080"`, with your `port`
+         */
+        url?: Input<string>;
+    };
+    /**
+     * [Transform](/docs/components#transform) how this component creates its underlying
+     * resources.
+     */
+    transform?: {
+        /**
+         * Transform the MicroVM image resource.
+         */
+        image?: Transform<lambdamicrovms.ImageArgs>;
+        /**
+         * Transform the IAM role Lambda uses to build the image.
+         */
+        buildRole?: Transform<iam.RoleArgs>;
+        /**
+         * Transform the IAM role your MicroVMs run with.
+         */
+        executionRole?: Transform<iam.RoleArgs>;
+        /**
+         * Transform the CloudWatch log group.
+         */
+        logGroup?: Transform<cloudwatch.LogGroupArgs>;
+        /**
+         * Transform the Lambda network connector, created when `vpc` is set.
+         */
+        networkConnector?: Transform<lambda.CoreNetworkConnectorArgs>;
+        /**
+         * Transform the IAM role Lambda uses to create the network connector's network
+         * interfaces in the VPC.
+         */
+        operatorRole?: Transform<iam.RoleArgs>;
+    };
+}
+/**
+ * The `MicroVm` component lets you run your code in
+ * [AWS Lambda MicroVMs](https://docs.aws.amazon.com/lambda/latest/dg/lambda-microvms-guide.html):
+ * isolated, stateful sandboxes, each with its own HTTPS endpoint, that live for up to
+ * 8 hours. For example, to run code that an AI agent wrote.
+ *
+ * The component creates the image. Your app then starts MicroVMs from it, and sends them
+ * requests, with the [SDK](/docs/component/aws/microvm#sdk).
+ *
+ * :::note
+ * Lambda MicroVMs run on ARM64 only, and are available in `us-east-1`, `us-east-2`,
+ * `us-west-2`, `eu-west-1` and `ap-northeast-1`.
+ * :::
+ *
+ * @example
+ *
+ * #### Create a MicroVM image
+ *
+ * ```ts title="sst.config.ts"
+ * const sandbox = new sst.aws.MicroVm("Sandbox", {
+ *   image: { context: "./sandbox" },
+ *   dev: { command: "node app.js" }
+ * });
+ * ```
+ *
+ * Here `./sandbox` has a `Dockerfile` that starts an app listening on port 8080.
+ *
+ * #### Link it and run MicroVMs
+ *
+ * ```ts title="sst.config.ts"
+ * new sst.aws.Function("MyFunction", {
+ *   handler: "src/lambda.handler",
+ *   link: [sandbox]
+ * });
+ * ```
+ *
+ * ```ts title="src/lambda.ts"
+ * import { Resource } from "sst";
+ * import { microvm } from "sst/aws/microvm";
+ *
+ * const vm = await microvm.run(Resource.Sandbox);
+ * const res = await vm.fetch("/exec", {
+ *   method: "POST",
+ *   body: JSON.stringify({ code: "print(1 + 1)" })
+ * });
+ * await vm.terminate();
+ * ```
+ *
+ * #### Reach private resources in a VPC
+ *
+ * ```ts title="sst.config.ts"
+ * const vpc = new sst.aws.Vpc("MyVpc", { nat: "ec2" });
+ *
+ * new sst.aws.MicroVm("Sandbox", {
+ *   image: { context: "./sandbox" },
+ *   vpc
+ * });
+ * ```
+ *
+ * #### Limit how long MicroVMs live
+ *
+ * A MicroVM you don't terminate keeps running until it's idle, or until its `duration` is
+ * up. These defaults keep that short; change them for long sessions.
+ *
+ * ```ts title="sst.config.ts"
+ * new sst.aws.MicroVm("Sandbox", {
+ *   image: { context: "./sandbox" },
+ *   duration: "4 hours",
+ *   idle: { suspendAfter: "10 minutes", terminateAfter: "1 hour" }
+ * });
+ * ```
+ *
+ * Your account has a quota for the memory of all its MicroVMs in a region, running and
+ * suspended, and each MicroVM has 2 GB. Once it's reached, `microvm.run()` fails until
+ * some are terminated. You can ask for more in the Service Quotas console.
+ *
+ * :::caution
+ * Lambda can't delete an image while MicroVMs from it are running. So `sst remove`, and
+ * starting `sst dev` on a deployed stage, fail until they're terminated, idle, or their
+ * `duration` is up.
+ * :::
+ */
+export declare class MicroVm extends Component implements Link.Linkable {
+    private readonly image?;
+    private readonly buildRole?;
+    private readonly executionRole;
+    private readonly logGroup;
+    private readonly networkConnector?;
+    private readonly region;
+    private readonly partition;
+    private readonly runDefaults;
+    private readonly devUrl?;
+    constructor(name: string, args?: MicroVmArgs, opts?: ComponentResourceOptions);
+    /**
+     * The ARN of the MicroVM image. Not created in `sst dev`, unless `dev` is `false`.
+     */
+    get arn(): Output<string> | undefined;
+    /**
+     * The underlying [resources](/docs/components/#nodes) this component creates.
+     */
+    get nodes(): {
+        /**
+         * The MicroVM image. Not created in `sst dev`, unless `dev` is `false`.
+         */
+        image: import("@pulumi/aws/lambdamicrovms/image").Image | undefined;
+        /**
+         * The IAM role Lambda uses to build the image.
+         */
+        buildRole: import("@pulumi/aws/iam/role").Role | undefined;
+        /**
+         * The IAM role your MicroVMs run with.
+         */
+        executionRole: import("@pulumi/aws/iam/role").Role;
+        /**
+         * The CloudWatch log group.
+         */
+        logGroup: import("@pulumi/aws/cloudwatch/logGroup").LogGroup;
+        /**
+         * The Lambda network connector. Only created when `vpc` is set, and not in
+         * `sst dev`.
+         */
+        networkConnector: import("@pulumi/aws/lambda/coreNetworkConnector").CoreNetworkConnector | undefined;
+    };
+    /** @internal */
+    getSSTLink(): {
+        properties: {
+            dev: {
+                url: Output<string>;
+            };
+            port: import("@pulumi/pulumi").OutputInstance<number>;
+            imageArn?: undefined;
+            imageVersion?: undefined;
+            executionRoleArn?: undefined;
+            logGroup?: undefined;
+            ingressNetworkConnectors?: undefined;
+            egressNetworkConnectors?: undefined;
+            duration?: undefined;
+            idle?: undefined;
+        };
+        include?: undefined;
+    } | {
+        properties: {
+            imageArn: Output<string>;
+            imageVersion: Output<string>;
+            executionRoleArn: Output<string>;
+            logGroup: Output<string>;
+            ingressNetworkConnectors: Output<string>[];
+            egressNetworkConnectors: Output<string>[];
+            port: import("@pulumi/pulumi").OutputInstance<number>;
+            duration: import("@pulumi/pulumi").OutputInstance<number>;
+            idle: Output<{
+                autoResumeEnabled: boolean;
+                maxIdleDurationSeconds: number;
+                suspendedDurationSeconds: number;
+            } | undefined> | undefined;
+            dev?: undefined;
+        };
+        include: {
+            effect?: "allow" | "deny" | undefined;
+            actions: string[];
+            resources: Input<Input<string>[]>;
+            conditions?: Input<Input<{
+                test: Input<string>;
+                variable: Input<string>;
+                values: Input<Input<string>[]>;
+            }>[]> | undefined;
+            type: "aws.permission";
+        }[];
+    };
+}
+//# sourceMappingURL=microvm.d.ts.map

package/platform/types/components/aws/microvm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"microvm.d.ts","sourceRoot":"","sources":["../../../../src/components/aws/microvm.ts"],"names":[],"mappings":"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"}