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

package/lib/Job.d.ts

@@ -0,0 +1,314 @@
+import { Platform, type PlatformProps, type PlatformServices } from "alchemy/Platform";
+import * as Provider from "alchemy/Provider";
+import { Resource } from "alchemy/Resource";
+import type { HostRuntimeContext } from "alchemy/Runtime/Process";
+import { RuntimeContext } from "alchemy/RuntimeContext";
+import { Stack } from "alchemy/Stack";
+import * as Effect from "effect/Effect";
+import type { Scope } from "effect/Scope";
+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 isJob: (value: any) => value is Job;
+export interface JobPropsBase extends PlatformProps {
+    /**
+     * Target cluster the job runs on: 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.
+     */
+    cluster: ClusterLike;
+    /**
+     * Base name for the generated Job / ServiceAccount. If omitted, a
+     * deterministic name is derived from the stack, stage, and logical id.
+     */
+    name?: string;
+    /**
+     * Kubernetes namespace to run in. The namespace must already exist.
+     * @default "default"
+     */
+    namespace?: string;
+    /**
+     * Number of retries before the Job is marked failed (Kubernetes
+     * `backoffLimit`).
+     */
+    backoffLimit?: number;
+    /**
+     * Cron schedule (standard 5-field cron, e.g. `"0 3 * * *"`). When set, a
+     * Kubernetes `CronJob` is synthesized instead of a plain `Job`.
+     */
+    schedule?: string;
+    /**
+     * Restart policy for the job's pods.
+     * @default "Never"
+     */
+    restartPolicy?: "Never" | "OnFailure";
+    /**
+     * Seconds after completion before the finished Job is garbage-collected
+     * (Kubernetes `ttlSecondsAfterFinished`).
+     */
+    ttlSecondsAfterFinished?: number;
+    /**
+     * 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;
+    /**
+     * Job / pod labels, merged over the generated `app.kubernetes.io/name`
+     * label.
+     */
+    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 BundledJobProps extends JobPropsBase {
+    /**
+     * 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 DockerfileJobProps extends JobPropsBase {
+    /** 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 ImageJobProps extends JobPropsBase {
+    /**
+     * A pre-built image reference, e.g. `ghcr.io/acme/migrator:v3`, pulled
+     * by the nodes as written. EKS clusters mirror it into ECR first.
+     */
+    image: string;
+}
+export type JobProps = BundledJobProps | DockerfileJobProps | ImageJobProps;
+export interface Job extends Resource<"Kubernetes.Job", JobProps, {
+    /** The connection of the cluster the job runs on. */
+    connection: Connection;
+    /** The Kubernetes namespace the job's objects live in. */
+    namespace: string;
+    /** The Kubernetes kind synthesized for the workload (`Job`, or `CronJob` when `schedule` is set). */
+    kind: "Job" | "CronJob";
+    /** The name of the Kubernetes Job/CronJob object. */
+    jobName: string;
+    /** The cron schedule, when the workload is a CronJob. */
+    schedule: string | undefined;
+    /** The name of the service account the pods run as. */
+    serviceAccountName: string;
+    /** The URI of the container image the job 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;
+    /** References to the Kubernetes objects created for the job. */
+    kubernetesObjects: KubernetesObjectRef[];
+    /** The content hash of the container image source. */
+    code: {
+        hash: string;
+    };
+}, WorkloadBindingContract, Providers> {
+}
+export type JobServices = WorkloadServices;
+/**
+ * The impl shape: `{ run, ...rpc }`. `run` executes to completion inside
+ * the pod; the process exits when it returns.
+ */
+export type JobMain<InitServices = never> = void | {
+    run?: Effect.Effect<void, never, InitServices | PlatformServices | RuntimeContext | Scope>;
+};
+export type JobShape = JobMain<JobServices>;
+export interface JobRuntimeContext extends HostRuntimeContext {
+    readonly Type: "Kubernetes.Job";
+}
+/**
+ * Run-to-completion work on any Kubernetes cluster, as a container image
+ * or an Effect program.
+ *
+ * `Job` provisions a Kubernetes `Job` (or `CronJob` when `schedule` is
+ * set) via server-side apply and a ServiceAccount, plus — through the
+ * target cluster's platform adapter — workload identity and a container
+ * image from exactly one of three sources flat on props: `main` (bundle an
+ * inline Effect program whose impl returns `{ run }`), `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). On `AWS.EKS.Cluster`
+ * targets, bindings attach IAM policy statements to a generated
+ * pod-identity role; on `GCP.Container.Cluster` targets, GCP bindings grant
+ * their IAM roles to the Kubernetes ServiceAccount's Workload Identity
+ * Federation principal — exactly like `Kubernetes.Deployment`.
+ * ### Creating a Job
+ * **Example:** Remote image (external — no Effect runtime in the container)
+ * ```typescript
+ * const migrate = yield* Kubernetes.Job("DbMigrate", {
+ *   cluster,
+ *   image: "ghcr.io/acme/migrator:v3",
+ *   backoffLimit: 2,
+ * });
+ * ```
+ *
+ * **Example:** Inline Effect program
+ * ```typescript
+ * const cluster = yield* Kubernetes.LocalCluster("Cluster", {
+ *   name: "alchemy",
+ * });
+ *
+ * const hello = yield* Kubernetes.Job(
+ *   "Hello",
+ *   { cluster, main: import.meta.url, backoffLimit: 2 },
+ *   Effect.gen(function* () {
+ *     return {
+ *       run: Effect.log("hello from a Job"),
+ *     };
+ *   }),
+ * );
+ * ```
+ *
+ * **Example:** Inline Effect program with a DynamoDB binding (EKS)
+ * ```typescript
+ * const seed = yield* Kubernetes.Job(
+ *   "SeedData",
+ *   { cluster, main: import.meta.url },
+ *   Effect.gen(function* () {
+ *     const putItem = yield* AWS.DynamoDB.PutItem(table);
+ *     return {
+ *       run: Effect.gen(function* () {
+ *         yield* putItem({ Item: { id: { S: "seed" } } });
+ *       }),
+ *     };
+ *   }).pipe(Effect.provide(AWS.DynamoDB.PutItemHttp)),
+ * );
+ * ```
+ *
+ * **Example:** Tagged Effect program
+ * ```typescript
+ * export class Backfill extends Kubernetes.Job<Backfill, {
+ *   progress: () => Effect.Effect<number>;
+ * }>()("Backfill") {}
+ *
+ * export default Backfill.make(
+ *   { cluster, main: import.meta.url, backoffLimit: 1 },
+ *   Effect.gen(function* () {
+ *     return {
+ *       run: Effect.gen(function* () { }),
+ *       progress: () => Effect.succeed(0),
+ *     };
+ *   }),
+ * );
+ * ```
+ *
+ * ### 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 },
+ * }
+ * ```
+ *
+ * ### Scheduling
+ * **Example:** Nightly CronJob
+ * ```typescript
+ * const nightly = yield* Kubernetes.Job("NightlyBackfill", {
+ *   cluster,
+ *   main: import.meta.url,
+ *   schedule: "0 3 * * *",
+ * });
+ * ```
+ *
+ * @resource
+ * @product Workloads
+ */
+export declare const Job: Platform<Job, JobServices, JobShape, JobRuntimeContext>;
+export declare const JobProvider: () => import("effect/Layer").Layer<Provider.Provider<Job>, 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=Job.d.ts.map

package/lib/Job.d.ts.map

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