alchemy-docker-k3s 0.1.3 → 0.1.5

package/dist/index.d.mts

@@ -42,6 +42,29 @@ interface K3sDefinition {
   };
   /** K3s' built-in Flannel data plane. @default "vxlan" */
   flannelBackend?: "vxlan" | "wireguard-native";
+  /**
+   * Kubelet settings applied to every node. Changing them re-runs the K3s installer
+   * on each existing node in place, one node at a time; running containers keep running.
+   */
+  kubelet?: KubeletSettings;
+}
+interface KubeletSettings {
+  /**
+   * Image garbage collection. The kubelet starts deleting unused images when the
+   * image filesystem is `highThresholdPercent` full and stops at `lowThresholdPercent`.
+   * Unset keeps the kubelet defaults (85 % and 80 %).
+   */
+  imageGc?: {
+    /** Integer percentage, 1–100, above `lowThresholdPercent`. */
+    highThresholdPercent: number;
+    /** Integer percentage, 0–99, below `highThresholdPercent`. */
+    lowThresholdPercent: number;
+  };
+  /**
+   * Further kubelet flags as `name=value`, passed as `--kubelet-arg`. Flags the package
+   * manages itself (`cloud-provider`, `provider-id`, `image-gc-*`) are rejected.
+   */
+  extraArgs?: string[];
 }
 interface NormalizedK3sDefinition {
   channel: `v1.${number}`;
@@ -55,6 +78,8 @@ interface NormalizedK3sDefinition {
     traefikValues: Record<string, unknown>;
   };
   flannelBackend: "vxlan" | "wireguard-native";
+  /** Validated kubelet flags as `name=value`, without the `--kubelet-arg` prefix. */
+  kubeletArgs: string[];
 }
 interface ClusterVersion {
   node: string;
@@ -108,4 +133,4 @@ declare const Cluster: (id: string, props: ClusterProps) => Effect.Effect<Cluste
 //#region src/cluster-state.d.ts
 declare const ClusterState: import("alchemy").ResourceClass<ClusterResource>;
 //#endregion
-export { Cluster, type ClusterAttributes, type Cluster$1 as ClusterInstance, type ClusterProps, ClusterState, type K3sDefinition, type PortMapping, Providers, providers };
+export { Cluster, type ClusterAttributes, type Cluster$1 as ClusterInstance, type ClusterProps, ClusterState, type K3sDefinition, type KubeletSettings, type PortMapping, Providers, providers };

package/dist/index.mjs

@@ -5,7 +5,7 @@ import * as Provider from "alchemy/Provider";
 import * as Redacted from "effect/Redacted";
 import { parse } from "yaml";
 import { chmod, mkdir, writeFile } from "node:fs/promises";
-import { dirname, join, resolve } from "node:path";
+import { dirname, join } from "node:path";
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import * as Layer from "effect/Layer";
@@ -51,6 +51,24 @@ const validateUpdateWindow = (window) => {
 	}
 	return window;
 };
+const MANAGED_KUBELET_FLAGS = /^(cloud-provider|provider-id|image-gc-[a-z-]+)=/;
+const KUBELET_FLAG = /^[a-z][a-z0-9-]*=\S*$/;
+/** Validates kubelet settings and renders them as `name=value` kubelet flags. */
+const kubeletArguments = (settings = {}) => {
+	const args = [];
+	if (settings.imageGc !== void 0) {
+		const { highThresholdPercent: high, lowThresholdPercent: low } = settings.imageGc;
+		const percent = (value) => Number.isInteger(value) && value >= 0 && value <= 100;
+		if (!percent(high) || !percent(low) || low >= high) throw new Error(`kubelet.imageGc thresholds must be integer percentages with lowThresholdPercent < highThresholdPercent; received ${JSON.stringify(settings.imageGc)}`);
+		args.push(`image-gc-high-threshold=${high}`, `image-gc-low-threshold=${low}`);
+	}
+	for (const arg of settings.extraArgs ?? []) {
+		if (!KUBELET_FLAG.test(arg)) throw new Error(`kubelet.extraArgs entries must be name=value without a leading --; received ${JSON.stringify(arg)}`);
+		if (MANAGED_KUBELET_FLAGS.test(arg)) throw new Error(`kubelet.extraArgs must not set ${JSON.stringify(arg.split("=")[0])}, which the package manages`);
+		args.push(arg);
+	}
+	return args;
+};
 const normalizeK3sDefinition = (definition) => {
 	const normalized = {
 		channel: validateChannel(definition.channel),
@@ -63,7 +81,8 @@ const normalizeK3sDefinition = (definition) => {
 			metricsServer: definition.addons?.metricsServer ?? true,
 			traefikValues: definition.addons?.traefikValues ?? {}
 		},
-		flannelBackend: definition.flannelBackend ?? "vxlan"
+		flannelBackend: definition.flannelBackend ?? "vxlan",
+		kubeletArgs: kubeletArguments(definition.kubelet)
 	};
 	if (normalized.flannelBackend !== "vxlan" && normalized.flannelBackend !== "wireguard-native") throw new Error(`flannelBackend must be "vxlan" or "wireguard-native"; received ${JSON.stringify(normalized.flannelBackend)}`);
 	const traefikValues = normalized.addons.traefikValues;
@@ -131,9 +150,16 @@ const resolveChannelVersion = async (channel, fetcher = fetch) => {
 };
 //#endregion
 //#region ../shared/src/kubeconfig.ts
+/**
+* Relative to the directory Alchemy runs from. Alchemy identifies a cluster by
+* its connection's auth, which contains this path, so an absolute path would
+* make every checkout or workspace look like a different cluster and replace
+* everything deployed to it. Reading the cluster rewrites the file wherever
+* Alchemy runs.
+*/
 const kubeconfigPath = (provider, fqn) => {
 	const safe = fqn.replace(/[^a-zA-Z0-9_.-]+/g, "-").replace(/^-|-$/g, "");
-	return resolve(join(".alchemy", "kubeconfigs", provider, `${safe}.yaml`));
+	return join(".alchemy", "kubeconfigs", provider, `${safe}.yaml`);
 };
 const writeKubeconfig = async (path, contents) => {
 	await mkdir(dirname(path), {
@@ -234,7 +260,8 @@ const buildCreateArgs = (props, version, token) => {
 		`--cluster-cidr=${props.k3s.clusterCidr}`,
 		`--service-cidr=${props.k3s.serviceCidr}`,
 		`--cluster-dns=${props.k3s.clusterDns}`,
-		`--flannel-backend=${props.k3s.flannelBackend}`
+		`--flannel-backend=${props.k3s.flannelBackend}`,
+		...props.k3s.kubeletArgs.map((arg) => `--kubelet-arg=${arg}`)
 	]) args.push("--k3s-arg", `${value}@server:0`);
 	if (!props.k3s.addons.traefik) args.push("--k3s-arg", "--disable=traefik@server:0");
 	if (!props.k3s.addons.metricsServer) args.push("--k3s-arg", "--disable=metrics-server@server:0");
@@ -418,7 +445,8 @@ const Cluster = (id, props) => Effect.gen(function* () {
 			clusterCidr: k3s.clusterCidr,
 			serviceCidr: k3s.serviceCidr,
 			clusterDns: k3s.clusterDns,
-			addons: k3s.addons
+			addons: k3s.addons,
+			kubeletArgs: k3s.kubeletArgs
 		})
 	});
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "alchemy-docker-k3s",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Persistent local k3d clusters for Alchemy",
   "license": "Apache-2.0",
   "type": "module",