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

package/src/internal/helm.ts

@@ -0,0 +1,245 @@
+import { unwrapRedacted } from "alchemy/Util/data";
+import { collectRedactedSecrets, redactJson } from "alchemy/Util/Redaction";
+/**
+ * Internal Helm rendering for `Kubernetes.HelmChart`.
+ *
+ * Renders a chart to plain Kubernetes objects with the local `helm` CLI
+ * (`helm template` — pure local templating, no cluster connection, no
+ * in-cluster release records), so the rendered objects flow through the same
+ * server-side-apply machinery as `Kubernetes.Manifest` and the workload platforms.
+ * Mirrors the `Docker` service's local-CLI dependency: the `helm` binary
+ * must be installed on the deploying machine (`HELM_BIN` overrides the
+ * binary path).
+ */
+import * as Config from "effect/Config";
+import * as Data from "effect/Data";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import * as ChildProcess from "effect/process/ChildProcess";
+import * as ChildProcessSpawner from "effect/process/ChildProcessSpawner";
+import * as Stream from "effect/Stream";
+import * as YAML from "yaml";
+import type { KubernetesObjectDefinition } from "../Objects.ts";
+
+/** A Helm invocation or render failure (bad chart ref, template error, …). */
+export class HelmError extends Data.TaggedError("HelmError")<{
+  readonly message: string;
+}> {}
+
+const HelmBin = Config.String("HELM_BIN").pipe(Effect.orElseSucceed(() => "helm"));
+
+export interface RenderHelmChartOptions {
+  /**
+   * Chart reference: a repository chart name (with `repo`), an
+   * `oci://` reference, or a local chart directory path.
+   */
+  chart: string;
+  /** Classic chart repository URL (`--repo`). */
+  repo?: string | undefined;
+  /** Chart version (`--version`). */
+  version?: string | undefined;
+  /** Release name the chart's templates render with (`.Release.Name`). */
+  releaseName: string;
+  /** Namespace the chart renders into (`.Release.Namespace`). */
+  namespace: string;
+  /** Values passed to the chart (written to a temp values file). */
+  values?: Record<string, unknown> | undefined;
+  /**
+   * Render objects from the chart's `crds/` directory too
+   * (`--include-crds`).
+   * @default true
+   */
+  includeCrds?: boolean | undefined;
+}
+
+/**
+ * Render a chart with `helm template --no-hooks` and parse the
+ * multi-document YAML output into object definitions. Every rendered object
+ * must carry `apiVersion`, `kind`, and `metadata.name` (server-side apply
+ * needs a name; `generateName`-only objects are rejected with a clear
+ * error). Helm lifecycle hooks are excluded from the result (see
+ * {@link isHelmHook}).
+ */
+export const renderHelmChart = Effect.fn(function* (options: RenderHelmChartOptions) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+  const bin = yield* HelmBin;
+  const secrets = yield* Effect.sync(() =>
+    options.values === undefined ? [] : collectRedactedSecrets(options.values),
+  );
+
+  // The values file holds unwrapped credentials. Close this scope when the
+  // render finishes, including on helm or parse failure, so the file is removed.
+  return yield* Effect.scoped(
+    Effect.gen(function* () {
+      const args = [
+        "template",
+        options.releaseName,
+        options.chart,
+        "--namespace",
+        options.namespace,
+        // Helm lifecycle hooks (`helm.sh/hook`) only make sense under Helm's own
+        // release events; HelmChart server-side applies the render and does not
+        // implement hook timing/weights/delete policies, so a hook (e.g. a
+        // pre-delete uninstall Job) must never enter the managed-object graph.
+        "--no-hooks",
+      ];
+      if (options.repo !== undefined) {
+        args.push("--repo", options.repo);
+      }
+      if (options.version !== undefined) {
+        args.push("--version", options.version);
+      }
+      if (options.includeCrds ?? true) {
+        args.push("--include-crds");
+      }
+      if (options.values !== undefined && Object.keys(options.values).length > 0) {
+        // JSON is valid YAML, so the literal values object round-trips through
+        // a temp values file without a YAML serializer.
+        const dir = yield* fs.makeTempDirectoryScoped({
+          prefix: "alchemy-helm-",
+        });
+        const valuesFile = path.join(dir, "values.json");
+        // JSON.stringify(Redacted) emits the display placeholder. Unwrap at the
+        // values file; the chart props stay wrapped for plan and state.
+        const valuesJson = yield* Effect.sync(() => JSON.stringify(unwrapRedacted(options.values)));
+        yield* fs.writeFileString(valuesFile, valuesJson);
+        args.push("--values", valuesFile);
+      }
+
+      const result = yield* ChildProcess.make(bin, args, {
+        stdin: "ignore",
+        stdout: "pipe",
+        stderr: "pipe",
+        detached: false,
+        extendEnv: true,
+      }).pipe(
+        (command) => spawner.spawn(command),
+        Effect.flatMap((child) =>
+          Effect.all(
+            {
+              exitCode: child.exitCode,
+              stdout: child.stdout.pipe(Stream.decodeText, Stream.mkString),
+              stderr: child.stderr.pipe(Stream.decodeText, Stream.mkString),
+            },
+            { concurrency: "unbounded" },
+          ),
+        ),
+        // Scope the child to this render so it isn't tied to (and killed by)
+        // an enclosing scope that closes before helm exits.
+        Effect.scoped,
+        // A spawn failure (almost always ENOENT) means the helm CLI itself is
+        // missing — a machine-setup problem, not a resource error.
+        Effect.catchCause((cause) =>
+          Effect.die(
+            new Error(
+              `Failed to run '${bin}': ${String(cause)}. Kubernetes.HelmChart renders charts with the local helm CLI; if it isn't installed, install it (https://helm.sh/docs/intro/install/) or point HELM_BIN at the binary.`,
+            ),
+          ),
+        ),
+      );
+
+      if (result.exitCode !== 0) {
+        const detail =
+          `helm ${args.join(" ")} exited with code ${String(result.exitCode)}: ` +
+          result.stderr.trim();
+        return yield* Effect.failSync(
+          () => new HelmError({ message: redactJson(detail, secrets) }),
+        );
+      }
+
+      return yield* parseRenderedManifests(options.chart, result.stdout, secrets);
+    }),
+  );
+});
+
+/**
+ * Whether a rendered object is a Helm lifecycle hook (`helm.sh/hook`
+ * annotation). Hooks are executed by Helm at release events (pre-install,
+ * pre-delete, test, …); HelmChart has no release and no hook lifecycle, so
+ * they are filtered out rather than applied as ordinary objects.
+ */
+export const isHelmHook = (object: KubernetesObjectDefinition): boolean =>
+  typeof object.metadata.annotations?.["helm.sh/hook"] === "string";
+
+const causeText = (cause: unknown): string =>
+  cause instanceof Error ? cause.message : String(cause);
+
+/**
+ * Parse `helm template` output (multi-document YAML) into definitions.
+ * Hook-annotated objects are dropped — `renderHelmChart` already passes
+ * `--no-hooks`, but the parser enforces the invariant independently of the
+ * helm CLI's behavior.
+ *
+ * `secrets` scrubs credentials out of parser and validation diagnostics.
+ * Parsed objects stay plain; callers pass the same list to the request
+ * scrubber.
+ */
+export const parseRenderedManifests = (
+  chart: string,
+  rendered: string,
+  secrets: readonly string[] = [],
+): Effect.Effect<Array<KubernetesObjectDefinition>, HelmError> =>
+  Effect.try({
+    try: () => parseRenderedManifestsSync(chart, rendered, secrets),
+    catch: (cause) =>
+      cause instanceof HelmError
+        ? cause
+        : new HelmError({
+            message: redactJson(
+              `Failed to parse rendered manifests from chart '${chart}': ${causeText(cause)}`,
+              secrets,
+            ),
+          }),
+  });
+
+const parseRenderedManifestsSync = (
+  chart: string,
+  rendered: string,
+  secrets: readonly string[],
+): Array<KubernetesObjectDefinition> => {
+  const fail = (message: string): never => {
+    throw new HelmError({ message: redactJson(message, secrets) });
+  };
+  // Helm 4 writes OCI pull metadata to stdout before the rendered YAML.
+  // Strip only that exact leading preamble; chart output remains subject to
+  // the same strict Kubernetes object validation below.
+  const manifests = chart.startsWith("oci://")
+    ? rendered.replace(/^Pulled: [^\r\n]+\r?\nDigest: [^\r\n]+\r?\n(?=---(?:\r?\n|$))/, "")
+    : rendered;
+  const documents = YAML.parseAllDocuments(manifests);
+  const objects: Array<KubernetesObjectDefinition> = [];
+  for (const document of documents) {
+    // parseAllDocuments records syntax errors on the document instead of
+    // throwing. toJS() can still throw (unresolved aliases, alias cycles).
+    if (document.errors.length > 0) {
+      const detail = document.errors.map((error) => error.message).join("\n");
+      fail(`Failed to parse rendered manifests from chart '${chart}': ${detail}`);
+    }
+    const value: unknown = document.toJS();
+    // helm renders empty documents for templates that produce no output
+    // (conditionals, whitespace) — skip them.
+    if (value === null || value === undefined) continue;
+    if (typeof value !== "object" || Array.isArray(value)) {
+      fail(`Chart '${chart}' rendered a non-object YAML document: ${JSON.stringify(value)}`);
+    }
+    const object = value as Partial<KubernetesObjectDefinition>;
+    if (typeof object.apiVersion !== "string" || typeof object.kind !== "string") {
+      // Scrub the full JSON before truncating so a secret that crosses the
+      // 200-character boundary is removed entirely.
+      const snippet = redactJson(JSON.stringify(value), secrets).slice(0, 200);
+      fail(`Chart '${chart}' rendered an object without apiVersion/kind: ${snippet}`);
+    }
+    if (typeof object.metadata?.name !== "string") {
+      fail(
+        `Chart '${chart}' rendered a ${object.apiVersion}/${object.kind} without metadata.name — server-side apply requires a concrete name (generateName is not supported)`,
+      );
+    }
+    const definition = object as KubernetesObjectDefinition;
+    if (isHelmHook(definition)) continue;
+    objects.push(definition);
+  }
+  return objects;
+};

package/src/internal/kind.ts

@@ -0,0 +1,43 @@
+import type { KindClusterConfig, LocalClusterProps } from "../LocalCluster.ts";
+
+/**
+ * containerd patch enabling the per-registry `hosts.toml` directory that
+ * points `localhost:<registryPort>` at the local registry container. The
+ * default on kind v0.27+ node images; kept for older ones
+ * (https://kind.sigs.k8s.io/docs/user/local-registry/).
+ */
+export const REGISTRY_CONTAINERD_PATCH = `[plugins."io.containerd.grpc.v1.cri".registry]
+  config_path = "/etc/containerd/certs.d"`;
+
+/** The kind config fields of a `LocalCluster`'s props. */
+export const kindConfigOf = ({
+  nodes,
+  networking,
+  featureGates,
+  runtimeConfig,
+  kubeadmConfigPatches,
+  kubeadmConfigPatchesJSON6902,
+  containerdConfigPatches,
+  containerdConfigPatchesJSON6902,
+}: Partial<LocalClusterProps>): KindClusterConfig => ({
+  nodes,
+  networking,
+  featureGates,
+  runtimeConfig,
+  kubeadmConfigPatches,
+  kubeadmConfigPatchesJSON6902,
+  containerdConfigPatches,
+  containerdConfigPatchesJSON6902,
+});
+
+/**
+ * The kind cluster config `LocalCluster` passes to `kind create cluster`:
+ * the kind fields with the kind/apiVersion header and the registry
+ * containerd patch added. kind reads YAML, and JSON is valid YAML.
+ */
+export const kindClusterConfig = (config: KindClusterConfig) => ({
+  kind: "Cluster",
+  apiVersion: "kind.x-k8s.io/v1alpha4",
+  ...JSON.parse(JSON.stringify(config)),
+  containerdConfigPatches: [...(config.containerdConfigPatches ?? []), REGISTRY_CONTAINERD_PATCH],
+});

package/src/internal/kubeconfig.ts

@@ -0,0 +1,364 @@
+/**
+ * Internal kubeconfig resolution for the built-in cluster adapters: parse a
+ * kubeconfig file, resolve a context to (cluster, user), and turn its auth
+ * stanza — static token, client certificate, or `exec` credential plugin —
+ * into a {@link ClusterTransport}. This is the "anything kubectl can reach"
+ * path: AKS/GKE/EKS CLI-managed contexts work through their exec plugins
+ * (`kubelogin`, `gke-gcloud-auth-plugin`, `aws eks get-token`).
+ */
+import * as Config from "effect/Config";
+import * as Data from "effect/Data";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import * as ChildProcess from "effect/process/ChildProcess";
+import * as ChildProcessSpawner from "effect/process/ChildProcessSpawner";
+import * as Stream from "effect/Stream";
+import * as YAML from "yaml";
+
+/** A kubeconfig file could not be read, parsed, or resolved. */
+export class KubeConfigError extends Data.TaggedError("Kubernetes.KubeConfigError")<{
+  readonly message: string;
+  readonly cause?: unknown;
+}> {}
+
+/** An exec credential plugin invocation failed or answered malformed. */
+export class ExecCredentialError extends Data.TaggedError("Kubernetes.ExecCredentialError")<{
+  readonly message: string;
+  readonly cause?: unknown;
+}> {}
+
+interface KubeConfigFile {
+  "current-context"?: string;
+  clusters?: {
+    name?: string;
+    cluster?: {
+      server?: string;
+      "certificate-authority"?: string;
+      "certificate-authority-data"?: string;
+      "insecure-skip-tls-verify"?: boolean;
+    };
+  }[];
+  users?: {
+    name?: string;
+    user?: KubeConfigUser;
+  }[];
+  contexts?: {
+    name?: string;
+    context?: { cluster?: string; user?: string };
+  }[];
+}
+
+interface KubeConfigUser {
+  token?: string;
+  tokenFile?: string;
+  "client-certificate"?: string;
+  "client-certificate-data"?: string;
+  "client-key"?: string;
+  "client-key-data"?: string;
+  exec?: {
+    command?: string;
+    args?: string[];
+    env?: { name?: string; value?: string }[];
+    apiVersion?: string;
+  };
+}
+
+/** The resolved connection material for one kubeconfig context. */
+export interface ResolvedKubeContext {
+  endpoint: string;
+  certificateAuthorityData?: string;
+  insecureSkipTlsVerify?: boolean;
+  user: KubeConfigUser;
+}
+
+const decodeBase64 = (value: string) => Buffer.from(value, "base64").toString("utf8");
+
+const expandHome = Effect.fn(function* (input: string) {
+  if (!input.startsWith("~")) return input;
+  const home = yield* Effect.sync(() => process.env.HOME ?? process.env.USERPROFILE);
+  if (!home) {
+    return yield* new KubeConfigError({
+      message: `Cannot expand '${input}': no HOME environment variable`,
+    });
+  }
+  const path = yield* Path.Path;
+  return path.join(home, input.slice(1));
+});
+
+/** Resolve the kubeconfig file path: explicit → `$KUBECONFIG` → default. */
+export const resolveKubeConfigPath = Effect.fn(function* (explicit: string | undefined) {
+  if (explicit) return yield* expandHome(explicit);
+  const fromEnv = yield* Config.String("KUBECONFIG").pipe(Effect.orElseSucceed(() => undefined));
+  // $KUBECONFIG may be a path list; use the first entry like kubectl's
+  // effective-config merge order.
+  const candidate = fromEnv?.split(":")[0];
+  if (candidate) return yield* expandHome(candidate);
+  return yield* expandHome("~/.kube/config");
+});
+
+/** Load a kubeconfig file and resolve one context to its cluster + user. */
+export const resolveKubeContext = Effect.fn(function* (options: {
+  path?: string;
+  context?: string;
+}) {
+  const fs = yield* FileSystem.FileSystem;
+  const configPath = yield* resolveKubeConfigPath(options.path);
+
+  const raw = yield* fs.readFileString(configPath).pipe(
+    Effect.mapError(
+      (cause) =>
+        new KubeConfigError({
+          message: `Failed to read kubeconfig at '${configPath}'`,
+          cause,
+        }),
+    ),
+  );
+
+  const parsed = yield* Effect.try({
+    try: () => YAML.parse(raw) as KubeConfigFile,
+    catch: (cause) =>
+      new KubeConfigError({
+        message: `Failed to parse kubeconfig at '${configPath}'`,
+        cause,
+      }),
+  });
+
+  const contextName = options.context ?? parsed["current-context"];
+  if (!contextName) {
+    return yield* new KubeConfigError({
+      message: `Kubeconfig '${configPath}' has no current-context — pass an explicit context`,
+    });
+  }
+
+  const context = parsed.contexts?.find((entry) => entry.name === contextName)?.context;
+  if (!context?.cluster) {
+    return yield* new KubeConfigError({
+      message: `Context '${contextName}' not found in kubeconfig '${configPath}'`,
+    });
+  }
+
+  const cluster = parsed.clusters?.find((entry) => entry.name === context.cluster)?.cluster;
+  if (!cluster?.server) {
+    return yield* new KubeConfigError({
+      message: `Cluster '${context.cluster}' (context '${contextName}') has no server in kubeconfig '${configPath}'`,
+    });
+  }
+
+  const user = parsed.users?.find((entry) => entry.name === context.user)?.user ?? {};
+
+  let certificateAuthorityData = cluster["certificate-authority-data"];
+  if (!certificateAuthorityData && cluster["certificate-authority"]) {
+    const caPath = yield* expandHome(cluster["certificate-authority"]);
+    const pem = yield* fs.readFileString(caPath).pipe(
+      Effect.mapError(
+        (cause) =>
+          new KubeConfigError({
+            message: `Failed to read certificate authority file '${caPath}'`,
+            cause,
+          }),
+      ),
+    );
+    certificateAuthorityData = Buffer.from(pem, "utf8").toString("base64");
+  }
+
+  return {
+    endpoint: cluster.server,
+    certificateAuthorityData,
+    insecureSkipTlsVerify: cluster["insecure-skip-tls-verify"],
+    user,
+  } satisfies ResolvedKubeContext;
+});
+
+interface ExecCredentialStatus {
+  token?: string;
+  clientCertificateData?: string;
+  clientKeyData?: string;
+  expirationTimestamp?: string;
+}
+
+/** Credentials minted by a user's auth stanza for one request. */
+export interface MintedCredentials {
+  token?: string;
+  clientCert?: { certificate: string; key: string };
+}
+
+// Exec plugin invocations are cached per (command, args) until their
+// expirationTimestamp (or briefly, when the plugin doesn't declare one).
+// Plain cached values, no finalizers — module scope is safe.
+const execCache = new Map<string, { credentials: MintedCredentials; expiresAt: number }>();
+
+/**
+ * Run a kubeconfig-style exec credential plugin and parse its
+ * ExecCredential response.
+ */
+export const runExecCredential = Effect.fn(function* (options: {
+  command: string;
+  args?: string[] | undefined;
+  env?: Record<string, string> | undefined;
+}) {
+  const cacheKey = JSON.stringify([options.command, options.args ?? [], options.env ?? {}]);
+  const cached = execCache.get(cacheKey);
+  const now = yield* Effect.sync(() => Date.now());
+  if (cached && cached.expiresAt > now) {
+    return cached.credentials;
+  }
+
+  const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+  // The child process is scoped to this invocation: spawn, drain stdio,
+  // and close the scope when the plugin exits.
+  const result = yield* ChildProcess.make(options.command, options.args ?? [], {
+    stdin: "ignore",
+    stdout: "pipe",
+    stderr: "pipe",
+    detached: false,
+    extendEnv: true,
+    env: options.env,
+  }).pipe(
+    (command) => spawner.spawn(command),
+    Effect.flatMap((child) =>
+      Effect.all(
+        {
+          exitCode: child.exitCode,
+          stdout: child.stdout.pipe(Stream.decodeText, Stream.mkString),
+          stderr: child.stderr.pipe(Stream.decodeText, Stream.mkString),
+        },
+        { concurrency: "unbounded" },
+      ),
+    ),
+    Effect.scoped,
+    Effect.catchCause((cause) =>
+      Effect.fail(
+        new ExecCredentialError({
+          message: `Failed to run exec credential plugin '${options.command}': ${String(cause)}`,
+        }),
+      ),
+    ),
+  );
+
+  if (result.exitCode !== 0) {
+    return yield* new ExecCredentialError({
+      message:
+        `Exec credential plugin '${options.command} ${(options.args ?? []).join(" ")}' ` +
+        `exited with code ${String(result.exitCode)}: ${result.stderr.trim()}`,
+    });
+  }
+
+  const status = yield* Effect.try({
+    try: () => (JSON.parse(result.stdout) as { status?: ExecCredentialStatus }).status,
+    catch: (cause) =>
+      new ExecCredentialError({
+        message: `Exec credential plugin '${options.command}' answered malformed JSON`,
+        cause,
+      }),
+  });
+
+  if (!status || (!status.token && !(status.clientCertificateData && status.clientKeyData))) {
+    return yield* new ExecCredentialError({
+      message: `Exec credential plugin '${options.command}' returned no token or client certificate`,
+    });
+  }
+
+  const credentials: MintedCredentials = {
+    token: status.token,
+    clientCert:
+      status.clientCertificateData && status.clientKeyData
+        ? {
+            certificate: status.clientCertificateData,
+            key: status.clientKeyData,
+          }
+        : undefined,
+  };
+
+  const expiresAt = status.expirationTimestamp
+    ? // Re-mint 30s before the declared expiry.
+      new Date(status.expirationTimestamp).getTime() - 30_000
+    : // No declared expiry: cache briefly so bursts of requests share one
+      // plugin invocation without holding a stale credential for long.
+      now + 60_000;
+  execCache.set(cacheKey, { credentials, expiresAt });
+
+  return credentials;
+});
+
+/** Mint request credentials from a kubeconfig user's auth stanza. */
+export const mintUserCredentials = Effect.fn(function* (user: KubeConfigUser) {
+  if (user.exec?.command) {
+    return yield* runExecCredential({
+      command: user.exec.command,
+      args: user.exec.args,
+      env: user.exec.env
+        ? Object.fromEntries(
+            user.exec.env
+              .filter(
+                (entry): entry is { name: string; value: string } =>
+                  typeof entry.name === "string" && typeof entry.value === "string",
+              )
+              .map((entry) => [entry.name, entry.value]),
+          )
+        : undefined,
+    });
+  }
+
+  if (user.token) {
+    return { token: user.token } satisfies MintedCredentials;
+  }
+
+  if (user.tokenFile) {
+    const fs = yield* FileSystem.FileSystem;
+    const tokenPath = yield* expandHome(user.tokenFile);
+    const token = yield* fs.readFileString(tokenPath).pipe(
+      Effect.mapError(
+        (cause) =>
+          new KubeConfigError({
+            message: `Failed to read token file '${tokenPath}'`,
+            cause,
+          }),
+      ),
+    );
+    return { token: token.trim() } satisfies MintedCredentials;
+  }
+
+  const certData = user["client-certificate-data"];
+  const keyData = user["client-key-data"];
+  if (certData && keyData) {
+    return {
+      clientCert: {
+        certificate: decodeBase64(certData),
+        key: decodeBase64(keyData),
+      },
+    } satisfies MintedCredentials;
+  }
+
+  const certPath = user["client-certificate"];
+  const keyPath = user["client-key"];
+  if (certPath && keyPath) {
+    const fs = yield* FileSystem.FileSystem;
+    const readPem = (file: string) =>
+      expandHome(file).pipe(
+        Effect.flatMap((resolved) =>
+          fs.readFileString(resolved).pipe(
+            Effect.mapError(
+              (cause) =>
+                new KubeConfigError({
+                  message: `Failed to read credential file '${resolved}'`,
+                  cause,
+                }),
+            ),
+          ),
+        ),
+      );
+    return {
+      clientCert: {
+        certificate: yield* readPem(certPath),
+        key: yield* readPem(keyPath),
+      },
+    } satisfies MintedCredentials;
+  }
+
+  return yield* new KubeConfigError({
+    message:
+      "Kubeconfig user has no supported auth stanza (token, tokenFile, " +
+      "client certificate, or exec credential plugin)",
+  });
+});