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

package/src/Manifest.ts

@@ -0,0 +1,301 @@
+import { isResolved } from "alchemy/Diff";
+import * as Provider from "alchemy/Provider";
+import { Resource } from "alchemy/Resource";
+import { isPlainObject } from "alchemy/Util/data";
+import * as Data from "effect/Data";
+import * as Effect from "effect/Effect";
+import {
+  applyObject,
+  connectCluster,
+  deleteObject,
+  ifClusterExists,
+  readObject,
+} from "./Client.ts";
+import { toConnection, type ClusterLike, type Connection } from "./Connection.ts";
+import { driftMask, hashDriftSelection } from "./internal/declared.ts";
+import { connectionIdentity, connectionOfOutput, tryConnectionOf } from "./internal/workload.ts";
+import type { KubernetesObjectDefinition, KubernetesObjectRef } from "./Objects.ts";
+import type { Providers } from "./Providers.ts";
+
+export class ManifestInvalidProps extends Data.TaggedError("ManifestInvalidProps")<{
+  readonly message: string;
+  readonly cause?: unknown;
+}> {}
+
+/**
+ * A literal Kubernetes object: `apiVersion` + `kind` + `metadata`, with the
+ * rest of the object's fields (`spec`, `data`, …) carried as-is. Any kind is
+ * accepted — built-in objects and CRDs alike; the API server validates the
+ * shape on apply.
+ */
+export interface KubernetesManifest {
+  apiVersion: string;
+  kind: string;
+  metadata?: {
+    name?: string;
+    namespace?: string;
+    labels?: Record<string, string>;
+    annotations?: Record<string, string>;
+    [key: string]: unknown;
+  };
+  [key: string]: unknown;
+}
+
+export interface ManifestProps {
+  /**
+   * Target cluster the manifest is applied onto. Pass a managed cluster
+   * resource (e.g. `AWS.EKS.Cluster`), a `Kubernetes.KubeConfig(...)`, or
+   * a raw `Kubernetes.Connection`.
+   */
+  cluster: ClusterLike;
+  /**
+   * The Kubernetes object to apply (server-side apply, field manager
+   * `alchemy`) — a literal object with `apiVersion`, `kind`, `metadata`, and
+   * the kind's own fields. Arbitrary CRDs are supported via API discovery.
+   */
+  manifest: KubernetesManifest;
+}
+
+export interface Manifest extends Resource<
+  "Kubernetes.Manifest",
+  ManifestProps,
+  {
+    /** The connection of the cluster the object is applied to. */
+    connection: Connection;
+    /** The Kubernetes API version of the applied object. */
+    apiVersion: string;
+    /** The Kubernetes kind of the applied object. */
+    kind: string;
+    /** The name of the applied object. */
+    name: string;
+    /** The namespace of the applied object (`undefined` for cluster-scoped kinds). */
+    namespace: string | undefined;
+    /** Reference to the applied Kubernetes object. */
+    ref: KubernetesObjectRef;
+    /** The server-assigned UID of the applied object, when returned. */
+    uid: string | undefined;
+    /**
+     * Fingerprint of the declared fields last applied. `read` compares a GET
+     * projected through {@link driftMask} to this.
+     */
+    baselineHash?: string;
+    /**
+     * Declared-field mask from the last apply. Older state omits it and is
+     * compared with the same selection against the stored manifest.
+     */
+    driftMask?: unknown;
+    /**
+     * Set by `read` when the live object diverges. Reconcile does not persist
+     * it; the extra field is what `alchemy drift` compares.
+     */
+    observedHash?: string;
+  },
+  {},
+  Providers
+> {}
+
+/**
+ * Applies a raw Kubernetes manifest onto any cluster via server-side
+ * apply.
+ *
+ * Any literal object is accepted — built-in kinds and custom resources
+ * alike; unknown kinds are resolved through the Kubernetes API discovery
+ * endpoint, so CRDs work without any registration. The target `cluster`
+ * can be a managed cluster resource (e.g. `AWS.EKS.Cluster`) or any
+ * cluster your kubeconfig can reach (`Kubernetes.KubeConfig(...)`).
+ * ### Applying Manifests
+ * **Example:** StatefulSet
+ * ```typescript
+ * const sts = yield* Kubernetes.Manifest("Cache", {
+ *   cluster,
+ *   manifest: {
+ *     apiVersion: "apps/v1",
+ *     kind: "StatefulSet",
+ *     metadata: { name: "cache", namespace: "apps" },
+ *     spec: {
+ *       serviceName: "cache",
+ *       replicas: 3,
+ *       selector: { matchLabels: { app: "cache" } },
+ *       template: {
+ *         metadata: { labels: { app: "cache" } },
+ *         spec: { containers: [{ name: "redis", image: "redis:7" }] },
+ *       },
+ *     },
+ *   },
+ * });
+ * ```
+ *
+ * **Example:** Custom resource (CRD)
+ * ```typescript
+ * const widget = yield* Kubernetes.Manifest("Widget", {
+ *   cluster,
+ *   manifest: {
+ *     apiVersion: "acme.io/v1",
+ *     kind: "Widget",
+ *     metadata: { name: "w", namespace: "default" },
+ *     spec: { size: 3 },
+ *   },
+ * });
+ * ```
+ *
+ * ### Namespaces
+ * **Example:** Create a Namespace
+ * ```typescript
+ * const ns = yield* Kubernetes.Manifest("AppsNamespace", {
+ *   cluster,
+ *   manifest: {
+ *     apiVersion: "v1",
+ *     kind: "Namespace",
+ *     metadata: { name: "apps" },
+ *   },
+ * });
+ * ```
+ *
+ * ### Any Cluster
+ * **Example:** Apply onto a kubeconfig context
+ * ```typescript
+ * const local = Kubernetes.KubeConfig({ context: "kind-dev" });
+ *
+ * const config = yield* Kubernetes.Manifest("AppConfig", {
+ *   cluster: local,
+ *   manifest: {
+ *     apiVersion: "v1",
+ *     kind: "ConfigMap",
+ *     metadata: { name: "app-config", namespace: "default" },
+ *     data: { LOG_LEVEL: "info" },
+ *   },
+ * });
+ * ```
+ *
+ * @resource
+ * @product Manifest
+ */
+export const Manifest = Resource<Manifest>("Kubernetes.Manifest", {
+  aliases: ["AWS.EKS.Manifest"],
+});
+
+const toObjectDefinition = (
+  manifest: KubernetesManifest,
+): Effect.Effect<KubernetesObjectDefinition, Error> => {
+  const name = manifest.metadata?.name;
+  if (!name) {
+    return Effect.fail(
+      new ManifestInvalidProps({
+        message: `Kubernetes.Manifest requires manifest.metadata.name (got ${manifest.apiVersion}/${manifest.kind})`,
+      }),
+    );
+  }
+  return Effect.succeed(manifest as KubernetesObjectDefinition);
+};
+
+export const ManifestProvider = () =>
+  Provider.effect(
+    Manifest,
+    Effect.gen(function* () {
+      return {
+        stables: ["connection", "apiVersion", "kind", "name", "namespace"],
+        // In-cluster objects have no cloud-side enumeration that attributes
+        // them to alchemy; refresh happens per-instance through `read`.
+        list: () => Effect.succeed([] as Manifest["Attributes"][]),
+        diff: Effect.fn(function* ({ olds = {} as ManifestProps, news }) {
+          if (!isResolved(news)) return;
+          const oldManifest = olds.manifest as KubernetesManifest | undefined;
+          const newManifest = news.manifest as KubernetesManifest;
+          const oldCluster = connectionIdentity(tryConnectionOf(olds.cluster));
+          const newCluster = connectionIdentity(tryConnectionOf(news.cluster));
+          // Object identity (cluster, group/version/kind, name, namespace) is
+          // immutable — changing any of it is a replacement.
+          if (
+            oldManifest &&
+            ((oldCluster !== undefined && newCluster !== undefined && oldCluster !== newCluster) ||
+              oldManifest.apiVersion !== newManifest.apiVersion ||
+              oldManifest.kind !== newManifest.kind ||
+              oldManifest.metadata?.name !== newManifest.metadata?.name ||
+              oldManifest.metadata?.namespace !== newManifest.metadata?.namespace)
+          ) {
+            return { action: "replace" } as const;
+          }
+        }),
+        read: Effect.fn(function* ({ output, olds }) {
+          if (!output) return undefined;
+          const connection = connectionOfOutput(output);
+          if (!connection) return undefined;
+          // ClusterNotFound fails the drift row. undefined means this object is gone.
+          const transport = yield* connectCluster(connection);
+          const observed = yield* readObject({
+            transport,
+            object: output.ref,
+          }).pipe(Effect.catchTag("KubernetesNotFound", () => Effect.undefined));
+          if (!observed) return undefined;
+          const uid = (observed as { metadata?: { uid?: string } }).metadata?.uid;
+          const attrs = { ...output, uid };
+          const manifest = olds?.manifest;
+          // A stored mask is the apply-time selection. Older rows have the
+          // manifest and no mask; they use that same selection, not the
+          // previous whole-object hash.
+          const desired =
+            output.driftMask === undefined && manifest !== undefined
+              ? yield* toObjectDefinition(manifest)
+              : undefined;
+          const mask = output.driftMask ?? (desired === undefined ? undefined : driftMask(desired));
+          if (mask === undefined) return attrs;
+          const liveHash = yield* hashDriftSelection(mask, observed);
+          const baseline =
+            output.driftMask !== undefined && output.baselineHash !== undefined
+              ? output.baselineHash
+              : desired === undefined
+                ? undefined
+                : yield* hashDriftSelection(mask, desired);
+          if (baseline !== undefined && liveHash !== baseline) {
+            return { ...attrs, observedHash: liveHash };
+          }
+          return attrs;
+        }),
+        reconcile: Effect.fn(function* ({ news, output, session }) {
+          const connection = toConnection(news.cluster);
+          const transport = yield* connectCluster(connection);
+          const object = yield* toObjectDefinition(news.manifest);
+          const ref: KubernetesObjectRef = {
+            apiVersion: object.apiVersion,
+            kind: object.kind,
+            name: object.metadata.name,
+            namespace: object.metadata.namespace,
+          };
+
+          // Server-side apply is a true upsert: create-if-missing and
+          // converge-if-present in one call, `force: true` so alchemy owns
+          // the fields it manages regardless of prior managers.
+          const applied = yield* applyObject({ transport, object });
+          const witnessed = isPlainObject(applied) ? applied : undefined;
+          const baselineHash = yield* hashDriftSelection(object, witnessed ?? object);
+
+          yield* session.note(
+            `Applied ${ref.apiVersion}/${ref.kind} ${ref.namespace ? `${ref.namespace}/` : ""}${ref.name}`,
+          );
+
+          const uid = (applied as { metadata?: { uid?: string } })?.metadata?.uid ?? output?.uid;
+
+          return {
+            connection,
+            apiVersion: ref.apiVersion,
+            kind: ref.kind,
+            name: ref.name,
+            namespace: ref.namespace,
+            ref,
+            uid,
+            baselineHash,
+            driftMask: driftMask(object, witnessed),
+          };
+        }),
+        delete: Effect.fn(function* ({ output }) {
+          const connection = connectionOfOutput(output);
+          if (!connection) return;
+          const transport = yield* ifClusterExists(connectCluster(connection));
+          if (!transport) return;
+          // 404 (including a removed CRD's discovery 404) is already success.
+          // 403/5xx must surface: the object is still there.
+          yield* deleteObject({ transport, object: output.ref });
+        }),
+      };
+    }),
+  );

package/src/Objects.ts

@@ -0,0 +1,213 @@
+/**
+ * Internal Kubernetes object model + ordering/path helpers powering
+ * `Kubernetes.Manifest` and the workload platforms (`Deployment`, `Job`).
+ * Not part of the public surface — the public manifest shape is the literal
+ * `KubernetesManifest` on `Kubernetes.Manifest`.
+ */
+
+export interface KubernetesObjectMetadata {
+  name: string;
+  namespace?: string;
+  labels?: Record<string, string>;
+  annotations?: Record<string, string>;
+}
+
+export type KubernetesObjectDefinition = {
+  apiVersion: string;
+  kind: string;
+  metadata: KubernetesObjectMetadata;
+} & Record<string, unknown>;
+
+export interface KubernetesObjectRef {
+  apiVersion: string;
+  kind: string;
+  name: string;
+  namespace?: string;
+  /**
+   * Fingerprint of the declared fields last applied. Reads compare a GET
+   * projected through {@link driftMask} to this.
+   */
+  baselineHash?: string;
+  /**
+   * Declared-field mask from the last apply. Absent on state written before
+   * selections existed; those rows still detect a deleted object.
+   */
+  driftMask?: unknown;
+}
+
+export interface KubernetesObjectBinding {
+  type: "kubernetes-object";
+  object: KubernetesObjectDefinition;
+}
+
+export type KubernetesObjectScope = "Cluster" | "Namespaced";
+
+export interface KubernetesObjectKindSpec {
+  plural: string;
+  scope: KubernetesObjectScope;
+  applyRank: number;
+}
+
+/** Apply rank for kinds not in the static table (applied last, deleted first). */
+export const DEFAULT_APPLY_RANK = 100;
+
+const supportedKinds: Record<string, KubernetesObjectKindSpec> = {
+  "v1/Namespace": {
+    plural: "namespaces",
+    scope: "Cluster",
+    applyRank: 10,
+  },
+  // CRDs apply right after namespaces so a chart's custom resources
+  // (default rank 100) always find their definition registered.
+  "apiextensions.k8s.io/v1/CustomResourceDefinition": {
+    plural: "customresourcedefinitions",
+    scope: "Cluster",
+    applyRank: 15,
+  },
+  "v1/ServiceAccount": {
+    plural: "serviceaccounts",
+    scope: "Namespaced",
+    applyRank: 20,
+  },
+  "v1/ConfigMap": {
+    plural: "configmaps",
+    scope: "Namespaced",
+    applyRank: 30,
+  },
+  "v1/Secret": {
+    plural: "secrets",
+    scope: "Namespaced",
+    applyRank: 30,
+  },
+  "v1/Service": {
+    plural: "services",
+    scope: "Namespaced",
+    applyRank: 40,
+  },
+  "apps/v1/Deployment": {
+    plural: "deployments",
+    scope: "Namespaced",
+    applyRank: 50,
+  },
+  "apps/v1/StatefulSet": {
+    plural: "statefulsets",
+    scope: "Namespaced",
+    applyRank: 50,
+  },
+  "apps/v1/DaemonSet": {
+    plural: "daemonsets",
+    scope: "Namespaced",
+    applyRank: 50,
+  },
+  "batch/v1/Job": {
+    plural: "jobs",
+    scope: "Namespaced",
+    applyRank: 60,
+  },
+  "batch/v1/CronJob": {
+    plural: "cronjobs",
+    scope: "Namespaced",
+    applyRank: 60,
+  },
+  "v1/Pod": {
+    plural: "pods",
+    scope: "Namespaced",
+    applyRank: 60,
+  },
+};
+
+const objectTypeKey = (input: Pick<KubernetesObjectRef, "apiVersion" | "kind">) =>
+  `${input.apiVersion}/${input.kind}`;
+
+/** Look up the static kind table; `undefined` for kinds needing discovery. */
+export const lookupKubernetesKindSpec = (
+  input: Pick<KubernetesObjectRef, "apiVersion" | "kind">,
+): KubernetesObjectKindSpec | undefined => supportedKinds[objectTypeKey(input)];
+
+export const getKubernetesKindSpec = (input: Pick<KubernetesObjectRef, "apiVersion" | "kind">) => {
+  const spec = lookupKubernetesKindSpec(input);
+  if (!spec) {
+    throw new Error(`Unsupported Kubernetes object ${input.apiVersion}/${input.kind}`);
+  }
+  return spec;
+};
+
+const applyRankOf = (input: Pick<KubernetesObjectRef, "apiVersion" | "kind">) =>
+  lookupKubernetesKindSpec(input)?.applyRank ?? DEFAULT_APPLY_RANK;
+
+export const toKubernetesObjectRef = (object: KubernetesObjectDefinition): KubernetesObjectRef => ({
+  apiVersion: object.apiVersion,
+  kind: object.kind,
+  name: object.metadata.name,
+  namespace: object.metadata.namespace,
+});
+
+export const kubernetesObjectKey = (
+  input: Pick<KubernetesObjectRef, "apiVersion" | "kind" | "name" | "namespace">,
+) => [input.apiVersion, input.kind, input.namespace ?? "_cluster", input.name].join("/");
+
+const compareRefs = (a: KubernetesObjectRef, b: KubernetesObjectRef) =>
+  kubernetesObjectKey(a).localeCompare(kubernetesObjectKey(b));
+
+export const sortObjectsForApply = (objects: ReadonlyArray<KubernetesObjectDefinition>) =>
+  [...objects].sort(
+    (a, b) =>
+      applyRankOf(a) - applyRankOf(b) ||
+      compareRefs(toKubernetesObjectRef(a), toKubernetesObjectRef(b)),
+  );
+
+export const sortRefsForDelete = (objects: ReadonlyArray<KubernetesObjectRef>) =>
+  [...objects].sort((a, b) => applyRankOf(b) - applyRankOf(a) || compareRefs(a, b));
+
+export const chunkByApplyRank = (objects: ReadonlyArray<KubernetesObjectDefinition>) => {
+  const chunks: KubernetesObjectDefinition[][] = [];
+
+  for (const object of sortObjectsForApply(objects)) {
+    const rank = applyRankOf(object);
+    const current = chunks[chunks.length - 1];
+    if (!current) {
+      chunks.push([object]);
+      continue;
+    }
+
+    const currentRank = applyRankOf(current[0]);
+    if (currentRank === rank) {
+      current.push(object);
+    } else {
+      chunks.push([object]);
+    }
+  }
+
+  return chunks;
+};
+
+/**
+ * Build the REST path for an object given its (statically-known or
+ * discovered) kind spec.
+ */
+export const buildKubernetesObjectPathWithSpec = (
+  input: Pick<KubernetesObjectRef, "apiVersion" | "kind" | "name" | "namespace">,
+  spec: KubernetesObjectKindSpec,
+) => {
+  const [group, version] = input.apiVersion.includes("/")
+    ? input.apiVersion.split("/", 2)
+    : [undefined, input.apiVersion];
+
+  const base = group ? `/apis/${group}/${version}` : `/api/${version}`;
+
+  if (spec.scope === "Namespaced") {
+    if (!input.namespace) {
+      throw new Error(
+        `Kubernetes object ${input.apiVersion}/${input.kind}/${input.name} requires a namespace`,
+      );
+    }
+
+    return `${base}/namespaces/${input.namespace}/${spec.plural}/${input.name}`;
+  }
+
+  return `${base}/${spec.plural}/${input.name}`;
+};
+
+export const buildKubernetesObjectPath = (
+  input: Pick<KubernetesObjectRef, "apiVersion" | "kind" | "name" | "namespace">,
+) => buildKubernetesObjectPathWithSpec(input, getKubernetesKindSpec(input));

package/src/Providers.ts

@@ -0,0 +1,52 @@
+import { DockerLive } from "@alchemy.run/docker/Docker";
+import * as Provider from "alchemy/Provider";
+import * as Layer from "effect/Layer";
+import { builtinAdapters } from "./BuiltinAdapters.ts";
+import { Deployment, DeploymentProvider } from "./Deployment.ts";
+import { HelmChart, HelmChartProvider } from "./HelmChart.ts";
+import { Job, JobProvider } from "./Job.ts";
+import { LocalCluster, LocalClusterProvider } from "./LocalCluster.ts";
+import { Manifest, ManifestProvider } from "./Manifest.ts";
+
+export class Providers extends Provider.ProviderCollection<Providers>()("Kubernetes") {}
+
+/**
+ * The Kubernetes provider layer: the cluster-agnostic workload providers
+ * (`Deployment`, `Job`, `Manifest`, `HelmChart`), `LocalCluster`, and the
+ * built-in cluster adapters (`kubeconfig`, `token`, `client-cert`, `exec`).
+ *
+ * Managed-cloud clusters need their platform's adapter alongside — e.g.
+ * targeting an `AWS.EKS.Cluster` requires `AWS.providers()` in the same
+ * stack:
+ *
+ * ```ts
+ * const stack = Alchemy.Stack("app", {
+ *   providers: Layer.mergeAll(AWS.providers(), Kubernetes.providers()),
+ *   state: AWS.state(),
+ * });
+ * ```
+ */
+export const providers = () =>
+  Layer.effect(
+    Providers,
+    Provider.collection([Deployment, HelmChart, Job, LocalCluster, Manifest]),
+  ).pipe(
+    Layer.provide(
+      Layer.mergeAll(
+        DeploymentProvider(),
+        HelmChartProvider(),
+        JobProvider(),
+        LocalClusterProvider(),
+        ManifestProvider(),
+      ).pipe(
+        // Workloads build `main` / `context` images with the Docker CLI for
+        // connections that declare a `registry`.
+        Layer.provide(DockerLive),
+      ),
+    ),
+    // The built-in adapters are provideMerged (not just provided) so the
+    // workloads' dynamic `findClusterAdapter` lookups see them in the
+    // ambient stack context.
+    Layer.provideMerge(builtinAdapters()),
+    Layer.orDie,
+  );

package/src/globals.d.ts

@@ -0,0 +1,2 @@
+// `globalThis.__ALCHEMY_RUNTIME__`, declared by alchemy's Phase module.
+import type {} from "alchemy/Phase";

package/src/index.ts

@@ -0,0 +1,9 @@
+export * from "./BuiltinAdapters.ts";
+export * from "./ClusterAdapter.ts";
+export * from "./Connection.ts";
+export * from "./Deployment.ts";
+export * from "./HelmChart.ts";
+export * from "./Job.ts";
+export * from "./LocalCluster.ts";
+export * from "./Manifest.ts";
+export * from "./Providers.ts";