@alchemy.run/kubernetes 0.0.0 → 2.0.0-beta.84

package/lib/Deployment.d.ts

@@ -0,0 +1,382 @@
+import type { Input } from "alchemy/Input";
+import { Platform, type Main, type PlatformProps } from "alchemy/Platform";
+import * as Provider from "alchemy/Provider";
+import { Resource } from "alchemy/Resource";
+import { type HostRuntimeContext, type ServerHost as ServerHostService } from "alchemy/Runtime/Process";
+import { Stack } from "alchemy/Stack";
+import * as Effect from "effect/Effect";
+import { type IdentityState, type RegistryState, type WorkloadBindingContract, type WorkloadIdentityOptions, type WorkloadImageSource, type WorkloadServices } from "./ClusterAdapter.ts";
+import { type ClusterLike, type Connection } from "./Connection.ts";
+import { type KubernetesObjectRef } from "./Objects.ts";
+import type { Providers } from "./Providers.ts";
+export declare const isDeployment: (value: any) => value is Deployment;
+/**
+ * The image-source props shared by the workload platforms. Exactly one of
+ * `main` (bundle an inline Effect program), `context`/`dockerfile` (build
+ * the user's own Dockerfile), or `image` (a pre-built registry reference).
+ */
+export interface DeploymentPropsBase extends PlatformProps {
+    /**
+     * Target cluster the workload is deployed onto: a cluster resource
+     * (`Kubernetes.LocalCluster`, `AWS.EKS.Cluster`), a
+     * `Kubernetes.KubeConfig(...)`, or a raw `Kubernetes.Connection`. The
+     * connection supplies authentication and the registry `main` / `context`
+     * images are pushed to. Also accepts an Effect that produces any of
+     * these, so `{ cluster: Cluster }` and `{ cluster: yield* Cluster }`
+     * both type-check.
+     */
+    cluster: ClusterLike | Effect.Effect<Input<ClusterLike>, never, any>;
+    /**
+     * Base name for the generated Deployment / Service / ServiceAccount. If
+     * omitted, a deterministic name is derived from the stack, stage, and
+     * logical id.
+     */
+    name?: string;
+    /**
+     * Kubernetes namespace to deploy into. The namespace must already exist.
+     * @default "default"
+     */
+    namespace?: string;
+    /**
+     * HTTP port exposed by the container and the Service.
+     * @default 3000
+     */
+    port?: number;
+    /**
+     * Replica count for the Deployment.
+     * @default 1
+     */
+    replicas?: number;
+    /**
+     * Kubernetes Service type. `LoadBalancer` provisions the platform's
+     * cloud load balancer and exposes its hostname as the Deployment `url`.
+     * @default "LoadBalancer"
+     */
+    serviceType?: "ClusterIP" | "NodePort" | "LoadBalancer";
+    /**
+     * Annotations applied to the Service (e.g. load-balancer scheme /
+     * target-type hints).
+     */
+    serviceAnnotations?: Record<string, string>;
+    /**
+     * Container entrypoint override (Kubernetes `command`). Mostly useful with
+     * `image` / `context` sources.
+     */
+    command?: string[];
+    /**
+     * Container arguments (Kubernetes `args`).
+     */
+    args?: string[];
+    /**
+     * Container CPU/memory requests + limits (Kubernetes resource quantities).
+     */
+    resources?: {
+        requests?: {
+            cpu?: string;
+            memory?: string;
+        };
+        limits?: {
+            cpu?: string;
+            memory?: string;
+        };
+    };
+    /**
+     * Additional environment variables for the container.
+     */
+    env?: Record<string, any>;
+    /**
+     * Container image build architecture.
+     * @default the connection's `architecture`, else "amd64"
+     */
+    architecture?: "amd64" | "arm64";
+    /**
+     * Deep-partial Kubernetes Pod template merged into the synthesized
+     * template (objects merge recursively; arrays and primitives replace) —
+     * a literal object in the shape of `PodTemplateSpec`, e.g.
+     * `{ spec: { tolerations: [...], nodeSelector: {...} } }`.
+     */
+    podTemplate?: Record<string, unknown>;
+    /**
+     * Cloud-specific workload-identity options, consumed by the cluster
+     * platform's identity adapter (on EKS: `{ managedPolicyArns: [...] }`
+     * attaches extra managed policies to the generated pod-identity role; on
+     * GKE: `{ gcpServiceAccount }` runs the pods as an existing Google
+     * service account instead of the ServiceAccount's own principal).
+     */
+    identity?: WorkloadIdentityOptions;
+    /**
+     * Deployment / pod labels, merged over the generated
+     * `app.kubernetes.io/name` label. Also used as the Service selector.
+     */
+    labels?: Record<string, string>;
+    /**
+     * User-defined tags applied to workload-owned cloud resources (identity
+     * roles, image repositories).
+     */
+    tags?: Record<string, string>;
+}
+/** Bundle an inline Effect program (`main`) into a generated image. */
+export interface BundledDeploymentProps extends DeploymentPropsBase {
+    /**
+     * Module entrypoint for the bundled program. This should typically be
+     * `import.meta.url` from an inline Effect program.
+     */
+    main: string;
+    /**
+     * Environment image used as the generated Dockerfile's `FROM`; must be
+     * able to run the bun runtime.
+     * @default "oven/bun:1"
+     */
+    image?: string;
+    /** Named export to load from `main`. @default "default" */
+    handler?: string;
+    /** Bundler configuration for the entrypoint. */
+    build?: WorkloadImageSource["build"];
+    /** Environment Dockerfile (path or inline content). */
+    dockerfile?: WorkloadImageSource["dockerfile"];
+    /** Build context for a path {@link dockerfile} environment. */
+    context?: string;
+}
+/** Build the user's own Dockerfile (`context` + optional `dockerfile` path). */
+export interface DockerfileDeploymentProps extends DeploymentPropsBase {
+    /** Docker build context directory. */
+    context?: string;
+    /**
+     * Path to the Dockerfile (relative to the cwd), or inline content.
+     * @default `${context}/Dockerfile`
+     */
+    dockerfile?: WorkloadImageSource["dockerfile"];
+}
+/** Run a pre-built registry image. */
+export interface ImageDeploymentProps extends DeploymentPropsBase {
+    /**
+     * A pre-built image reference, e.g. `nginx:1.27`, pulled by the nodes as
+     * written. EKS clusters mirror it into ECR first.
+     */
+    image: string;
+}
+export type DeploymentProps = BundledDeploymentProps | DockerfileDeploymentProps | ImageDeploymentProps;
+export interface Deployment extends Resource<"Kubernetes.Deployment", DeploymentProps, {
+    /** The connection of the cluster the deployment runs on. */
+    connection: Connection;
+    /** The Kubernetes namespace the deployment's objects live in. */
+    namespace: string;
+    /** The name of the Kubernetes Deployment. */
+    deploymentName: string;
+    /** The name of the Kubernetes Service exposing the deployment. */
+    serviceName: string;
+    /** The name of the service account the pods run as. */
+    serviceAccountName: string;
+    /** The container port the server listens on. */
+    port: number;
+    /** The URI of the container image the deployment runs. */
+    imageUri: string;
+    /**
+     * Workload-identity state provisioned by the cluster platform's
+     * adapter (on EKS: the pod-identity role + association; on GKE: the
+     * Workload Identity principal and the IAM grants applied to it).
+     */
+    identity: IdentityState | undefined;
+    /**
+     * Image-registry state provisioned by the cluster platform's adapter
+     * (on EKS: the ECR repository).
+     */
+    registry: RegistryState | undefined;
+    /**
+     * The LoadBalancer URL (`http://<hostname>[:port]` — the cloud load
+     * balancer listens on the Service `port`, so a non-80 port is part of
+     * the URL) when `serviceType` is `LoadBalancer`, otherwise
+     * `undefined`. May be `undefined` immediately after a create while
+     * the cloud load balancer is still provisioning.
+     */
+    url: string | undefined;
+    /** References to the Kubernetes objects created for the deployment. */
+    kubernetesObjects: KubernetesObjectRef[];
+    /** The content hash of the container image source. */
+    code: {
+        hash: string;
+    };
+}, WorkloadBindingContract, Providers> {
+}
+export type DeploymentServices = ServerHostService | WorkloadServices;
+export type DeploymentShape = Main<DeploymentServices>;
+export interface DeploymentRuntimeContext extends HostRuntimeContext {
+    readonly Type: "Kubernetes.Deployment";
+}
+/**
+ * A replicated Kubernetes server on any cluster, running a container image
+ * or an HTTP server written in Effect.
+ *
+ * `Deployment` provisions a Kubernetes `Deployment` + `Service` (+
+ * `ServiceAccount`) via server-side apply, with the container image from
+ * exactly one of three sources flat on props: `main` (bundle an inline
+ * Effect program), `context` (build your own Dockerfile), or `image` (a
+ * pre-built registry reference). `main` and `context` images are built on
+ * the deploying machine and pushed to the connection's registry
+ * (`Kubernetes.LocalCluster` includes one; EKS uses ECR; GKE uses
+ * Artifact Registry). Bindings attach environment variables on any
+ * cluster; cloud credential grants need a platform with workload identity.
+ * On `AWS.EKS.Cluster` targets it accepts the `{ env, policyStatements }`
+ * contract of `AWS.Lambda.Function`: IAM policy statements go to a
+ * generated pod-identity role. On `GCP.Container.Cluster` targets it
+ * accepts the `{ env, iam }` contract of `GCP.Run.Service`: IAM roles are
+ * granted to the Kubernetes ServiceAccount's Workload Identity Federation
+ * principal.
+ * ### Creating a Deployment
+ * **Example:** Run an image on a local cluster
+ * ```typescript
+ * const cluster = yield* Kubernetes.LocalCluster("Cluster", {
+ *   name: "alchemy",
+ * });
+ *
+ * const web = yield* Kubernetes.Deployment("Web", {
+ *   cluster,
+ *   image: "ghcr.io/stefanprodan/podinfo:6.15.0",
+ *   replicas: 2,
+ *   port: 9898,
+ *   serviceType: "ClusterIP",
+ * });
+ * web.serviceName; // K8s-native attrs
+ * ```
+ *
+ * **Example:** Any cluster via kubeconfig
+ * ```typescript
+ * const cluster = Kubernetes.KubeConfig({ context: "prod-east" });
+ *
+ * const nginx = yield* Kubernetes.Deployment("Nginx", {
+ *   cluster,
+ *   image: "nginx:1.27",
+ *   replicas: 3,
+ *   port: 80,
+ *   serviceType: "LoadBalancer",
+ * });
+ * nginx.url; // the load balancer's address
+ * ```
+ *
+ * **Example:** Build your own Dockerfile
+ * ```typescript
+ * const legacy = yield* Kubernetes.Deployment("LegacyApp", {
+ *   cluster,
+ *   context: "./legacy",
+ *   replicas: 2,
+ *   port: 8080,
+ * });
+ * ```
+ *
+ * ### Effect Servers
+ * **Example:** Inline Effect server
+ * ```typescript
+ * const api = yield* Kubernetes.Deployment(
+ *   "Api",
+ *   { cluster, main: import.meta.url, port: 3000, replicas: 2 },
+ *   Effect.gen(function* () {
+ *     return {
+ *       fetch: Effect.succeed(HttpServerResponse.text("ok")),
+ *     };
+ *   }),
+ * );
+ * ```
+ *
+ * **Example:** Push to your own registry
+ * ```typescript
+ * const cluster = Kubernetes.KubeConfig({
+ *   context: "prod-east",
+ *   registry: { server: "ghcr.io/acme" },
+ * });
+ *
+ * const api = yield* Kubernetes.Deployment(
+ *   "Api",
+ *   { cluster, main: import.meta.url, port: 3000 },
+ *   Effect.gen(function* () {
+ *     return {
+ *       fetch: Effect.succeed(HttpServerResponse.text("ok")),
+ *     };
+ *   }),
+ * );
+ * ```
+ *
+ * **Example:** DynamoDB binding on EKS
+ * ```typescript
+ * const cluster = yield* AWS.EKS.Cluster("Cluster", { compute: "auto" });
+ *
+ * const api = yield* Kubernetes.Deployment(
+ *   "Api",
+ *   { cluster, main: import.meta.url, port: 3000 },
+ *   Effect.gen(function* () {
+ *     const putItem = yield* AWS.DynamoDB.PutItem(table);
+ *     return {
+ *       fetch: Effect.gen(function* () {
+ *         yield* putItem({ Item: { id: { S: "1" } } });
+ *         return HttpServerResponse.text("ok");
+ *       }),
+ *     };
+ *   }).pipe(Effect.provide(AWS.DynamoDB.PutItemHttp)),
+ * );
+ * ```
+ *
+ * **Example:** Tagged Effect server
+ * ```typescript
+ * export class Api extends Kubernetes.Deployment<Api, {
+ *   health: () => Effect.Effect<string>;
+ * }>()("Api") {}
+ *
+ * export default Api.make(
+ *   { cluster, main: import.meta.url, port: 3000 },
+ *   Effect.gen(function* () {
+ *     return {
+ *       fetch: Effect.gen(function* () {
+ *         return HttpServerResponse.text("ok");
+ *       }),
+ *       health: () => Effect.succeed("ok"),
+ *     };
+ *   }),
+ * );
+ * ```
+ *
+ * ### Bundling & Tree-shaking
+ * `main` is bundled with rolldown at deploy time. Unused code is
+ * tree-shaken. `effect`, alchemy, and `@distilled.cloud` are marked
+ * pure so unused parts prune more aggressively. Your app is not
+ * marked pure.
+ *
+ * **Example:** Mark additional packages as pure
+ * Only list packages with no top-level side effects.
+ * ```typescript
+ * {
+ *   main: import.meta.url,
+ *   build: {
+ *     pure: { packages: ["my-lib", "@my-scope/*"] },
+ *   },
+ * }
+ * ```
+ *
+ * **Example:** Turn it off
+ * ```typescript
+ * {
+ *   main: import.meta.url,
+ *   build: { pure: false },
+ * }
+ * ```
+ *
+ * ### Kubernetes Escape Hatch
+ * **Example:** Tune the synthesized pod template
+ * ```typescript
+ * const tuned = yield* Kubernetes.Deployment("Api", {
+ *   cluster,
+ *   main: import.meta.url,
+ *   port: 3000,
+ *   podTemplate: {
+ *     spec: {
+ *       tolerations: [{ key: "gpu", operator: "Exists" }],
+ *       nodeSelector: { pool: "arm" },
+ *     },
+ *   },
+ * });
+ * ```
+ *
+ * @resource
+ * @product Workloads
+ */
+export declare const Deployment: Platform<Deployment, DeploymentServices, DeploymentShape, DeploymentRuntimeContext>;
+export declare const DeploymentProvider: () => import("effect/Layer").Layer<Provider.Provider<Deployment>, never, import("alchemy/AlchemyContext").AlchemyContext | import("@alchemy.run/docker/Docker").Docker | import("effect/FileSystem").FileSystem | import("effect/Path").Path | Stack | import("alchemy/Stage").Stage>;
+//# sourceMappingURL=Deployment.d.ts.map

package/lib/Deployment.d.ts.map

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