@intentius/chant-lexicon-k3s 0.46.0 → 0.49.0

package/src/describe-resources.ts

@@ -0,0 +1,258 @@
+/**
+ * Live observation for declared k3s Server/Agent entities (#1603).
+ *
+ * Mirrors the #1412 k3d answer for the k3s shape, and reuses the same
+ * `k8s.profiles.<env>.context` binding helm and the k8s lexicon read
+ * (`@intentius/chant/kubectl-context`, #1488): the kubectl context is a
+ * property of the cluster chant talks to, not of any one lexicon, so k3s
+ * does not invent a second binding namespace for the same thing.
+ *
+ * ## What this can honestly say
+ *
+ * A declared `K3s::Server` / `K3s::Agent` is chant's description of one node
+ * joining a cluster. From where chant runs — never the host itself — the
+ * only observables are ones the apiserver answers:
+ *
+ *   - the declared kubectl context exists and answers at all (`kubectl
+ *     version`), which also reports the live k3s build so a caller can see
+ *     it against the pin (`K3S_VERSION`);
+ *   - the node the entity names is registered and its `Ready` condition.
+ *
+ * Everything that would require reaching the host directly — whether the
+ * `k3s` systemd unit is up, what `/etc/rancher/k3s/config.yaml` currently
+ * holds on disk — is out of scope. That is the provisioning boundary #1598
+ * draws, and this reader never crosses it.
+ *
+ * `K3s::Registries` has no live counterpart at all: `registries.yaml` is
+ * consumed once at containerd startup and leaves no object an apiserver
+ * serves, so it reads `unsupported-kind` — honest, not a gap to close here.
+ *
+ * ## Node identity
+ *
+ * The only address chant can back up is a declared `node-name`. Unset, k3s
+ * registers the node under the host's own hostname — which chant, running
+ * off the host, cannot know or guess. An entity with no `node-name` is
+ * `read-failed`, never a guessed address and never `absent`.
+ *
+ * ## Ownership rides node-label (#1603)
+ *
+ * The serializer stamps chant's marker into `node-label` when a build carries
+ * ownership (`./serializer.ts`), which lands on the registered Node as
+ * ordinary Kubernetes labels — the durable channel a host config file has no
+ * other way to carry. Read back here the same way every label-based lexicon
+ * does (`LABEL_OWNERSHIP_KEYS`).
+ *
+ * ## Tri-state (#1089, and the #1488 lesson)
+ *
+ * An unreachable apiserver — context missing, connection refused, no
+ * credentials — is `read-failed`/`no-credentials`/`no-binding` for every
+ * declared entity, naming the context that was actually read, never
+ * `absent`. Only a genuine per-node `NotFound` is absence.
+ */
+
+import { exec } from "node:child_process";
+import { promisify } from "node:util";
+import type { DescribeResourcesResult } from "@intentius/chant/lexicon";
+import {
+  observeEntities,
+  type DeclaredEntity,
+  type EntityObservation,
+  type ObserverAdapter,
+} from "@intentius/chant/observation";
+import { classifyOwnership, LABEL_OWNERSHIP_KEYS } from "@intentius/chant/ownership";
+import { loadChantConfigUpward } from "@intentius/chant/config";
+import { resolveClusterTarget, classifyKubectlFailure } from "@intentius/chant/kubectl-context";
+import { SERVER_TYPE, AGENT_TYPE } from "./serializer";
+import { K3S_VERSION } from "./spec/fetch";
+
+/** Injectable command runner, so tests drive every branch without kubectl or a cluster. */
+export type ExecFn = (command: string) => Promise<{ stdout: string }>;
+
+const execAsync = promisify(exec);
+
+/** Shell-quote one argv element (same convention as helm's release-observe). */
+function q(arg: string): string {
+  return `'${arg.replace(/'/g, "'\\''")}'`;
+}
+
+/**
+ * The environment's kube context (#1488): the declared `k8s.profiles.<env>`
+ * binding when present, ambient otherwise. This is deliberately the SAME
+ * binding the k8s and helm lexicons read — a cluster is one target however
+ * many lexicons observe it — not a `k3s.profiles` of its own.
+ */
+export async function resolveK3sContext(environment: string): Promise<string | undefined> {
+  try {
+    const { config } = await loadChantConfigUpward(process.cwd());
+    return (await resolveClusterTarget(config as Record<string, unknown>, environment, "k3s")).context;
+  } catch {
+    return undefined;
+  }
+}
+
+/** The declared node identity: the `node-name` flag, chant's only honest
+ * source. Absent means k3s will name the node after the host's own hostname
+ * — unknowable from here, so there is nothing to query by. */
+export function declaredNodeName(entity: DeclaredEntity): string | undefined {
+  const name = (entity.props as Record<string, unknown> | undefined)?.["node-name"];
+  return typeof name === "string" && name.length > 0 ? name : undefined;
+}
+
+interface K3sNodeCondition {
+  type?: string;
+  status?: string;
+  reason?: string;
+}
+
+interface K3sNode {
+  metadata?: {
+    uid?: string;
+    labels?: Record<string, string>;
+    creationTimestamp?: string;
+  };
+  status?: {
+    nodeInfo?: { kubeletVersion?: string };
+    conditions?: K3sNodeCondition[];
+  };
+}
+
+/** The node's `Ready` condition as a status word: no condition at all reads
+ * `unknown` (asked, and the object said nothing) rather than a guess. */
+function nodeReadyStatus(node: K3sNode): string {
+  const ready = node.status?.conditions?.find((c) => c.type === "Ready");
+  if (!ready) return "unknown";
+  if (ready.status === "True") return "Ready";
+  return ready.reason && ready.reason.length > 0 ? ready.reason : "NotReady";
+}
+
+function pruneUndefined<T extends Record<string, unknown>>(obj: T): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(obj)) {
+    if (v !== undefined) out[k] = v;
+  }
+  return out;
+}
+
+interface K3sClient {
+  exec: ExecFn;
+  ctxFlag: string;
+  /** `kubectl version`'s serverVersion.gitVersion — the live k3s build. */
+  k3sVersion?: string;
+}
+
+function adapter(execFn: ExecFn, environment: string): ObserverAdapter<K3sClient> {
+  // Captured so a bind() failure can name the exact context it tried,
+  // per the #1488 lesson — a bare kubectl error rarely does.
+  let contextTried: string | undefined;
+
+  return {
+    async bind() {
+      const context = await resolveK3sContext(environment);
+      contextTried = context;
+      const ctxFlag = context ? ` --context ${q(context)}` : "";
+
+      const { stdout } = await execFn(`kubectl version -o json${ctxFlag}`);
+      const parsed = JSON.parse(stdout) as { serverVersion?: { gitVersion?: string } };
+      return { exec: execFn, ctxFlag, k3sVersion: parsed.serverVersion?.gitVersion };
+    },
+
+    classifyBindFailure(err) {
+      const outcome = classifyKubectlFailure(err);
+      const named = contextTried
+        ? `context "${contextTried}" (from k8s.profiles.${environment}.context)`
+        : "the ambient kubectl context (no k8s.profiles binding declared)";
+      const raw = outcome.kind === "unobserved" ? outcome.detail : err instanceof Error ? err.message.split("\n")[0] : String(err);
+      const reason = outcome.kind === "unobserved" ? outcome.reason : "read-failed";
+      return { reason, detail: `${named}: ${raw}` };
+    },
+
+    async read(client, entity): Promise<EntityObservation> {
+      if (entity.type !== SERVER_TYPE && entity.type !== AGENT_TYPE) {
+        return { unobserved: { reason: "unsupported-kind", detail: entity.type } };
+      }
+
+      const name = declaredNodeName(entity);
+      if (!name) {
+        return {
+          unobserved: {
+            reason: "read-failed",
+            detail:
+              "no `node-name` declared — unset, k3s names the node after the host's own hostname, which chant cannot know from here",
+          },
+        };
+      }
+
+      const command = `kubectl get node ${q(name)} -o json${client.ctxFlag}`;
+      try {
+        const { stdout } = await client.exec(command);
+        const node = JSON.parse(stdout) as K3sNode;
+        const ownership = classifyOwnership(node.metadata?.labels, LABEL_OWNERSHIP_KEYS);
+
+        return {
+          present: {
+            type: entity.type,
+            physicalId: node.metadata?.uid ?? name,
+            status: nodeReadyStatus(node),
+            lastUpdated: node.metadata?.creationTimestamp,
+            ownership,
+            attributes: pruneUndefined({
+              nodeName: name,
+              kubeletVersion: node.status?.nodeInfo?.kubeletVersion,
+              k3sVersion: client.k3sVersion,
+              versionMatchesPin: client.k3sVersion ? client.k3sVersion === K3S_VERSION : undefined,
+              labels: node.metadata?.labels,
+            }),
+          },
+          queried: command,
+        };
+      } catch (err) {
+        const outcome = classifyKubectlFailure(err);
+        if (outcome.kind === "absent") return { absent: true, queried: command };
+        return { unobserved: { reason: outcome.reason, detail: outcome.detail }, queried: command };
+      }
+    },
+  };
+}
+
+export interface DescribeResourcesOptions {
+  environment: string;
+  buildOutput: string;
+  entityNames: string[];
+  entities: Map<string, { entityType: string; props: Record<string, unknown> }>;
+  /** Restrict to chant-owned nodes (#1348). Withheld foreign nodes are
+   * `filtered`, never a silent drop into `absent`. */
+  owned?: boolean;
+}
+
+export async function describeResources(
+  options: DescribeResourcesOptions,
+  execFn: ExecFn = execAsync,
+): Promise<DescribeResourcesResult> {
+  const declared: DeclaredEntity[] = options.entityNames.map((name) => {
+    const entity = options.entities.get(name);
+    return {
+      name,
+      type: entity?.entityType ?? "",
+      props: entity?.props ?? {},
+    };
+  });
+
+  const result = await observeEntities(declared, adapter(execFn, options.environment));
+  if (!options.owned) return result;
+
+  // `--owned`: withhold a node that is present but carries no chant marker.
+  // Withheld is `filtered`, never absent — a foreign node still exists.
+  const resources = { ...result.resources };
+  const unobserved = { ...result.unobserved };
+  for (const [name, meta] of Object.entries(result.resources)) {
+    if (meta.ownership === "owned") continue;
+    delete resources[name];
+    unobserved[name] = {
+      type: meta.type,
+      reason: "filtered",
+      detail: "live node carries no chant ownership marker and --owned was requested",
+      ...(result.queried?.[name] ? { queried: result.queried[name] } : {}),
+    };
+  }
+  return { ...result, resources, unobserved };
+}

package/src/lint/audit-catalog.ts

@@ -4,7 +4,7 @@
  * post-synth check has an entry, or the check contributes nothing to
  * `chant audit`, silently.
  *
- * All five checks read the chant model (`ctx.entities`) rather than the
+ * All checks read the chant model (`ctx.entities`) rather than the
  * emitted YAML — an emitted config.yaml carries no marker naming its own
  * role — so every entry is constructed directly with `yamlBased: false`.
  */
@@ -50,4 +50,16 @@ export const k3sAuditCatalog: Record<string, RuleMeta> = {
     "Registry TLS verification disabled",
     "Remove `insecure_skip_verify`; pin the registry CA via `ca_file`.",
   ),
+  K3S106: entityRule(
+    "K3S106",
+    "correctness",
+    "tls-san missing for a declared bind/advertise address",
+    "Add the bind-address / advertise-address value to `tls-san`.",
+  ),
+  K3S107: entityRule(
+    "K3S107",
+    "correctness",
+    "Disabled component still configured",
+    "Remove the component's config key, or drop it from `disable`.",
+  ),
 };

package/src/lint/post-synth/index.ts

@@ -5,6 +5,8 @@ import { k3s102 } from "./k3s102";
 import { k3s103 } from "./k3s103";
 import { k3s104 } from "./k3s104";
 import { k3s105 } from "./k3s105";
+import { k3s106 } from "./k3s106";
+import { k3s107 } from "./k3s107";
 
 export const postSynthChecks: PostSynthCheck[] = [
   k3s101,
@@ -12,4 +14,6 @@ export const postSynthChecks: PostSynthCheck[] = [
   k3s103,
   k3s104,
   k3s105,
+  k3s106,
+  k3s107,
 ];

package/src/lint/post-synth/k3s106.ts

@@ -0,0 +1,57 @@
+/**
+ * K3S106: tls-san missing when the server is reachable at a declared
+ * address beyond the implicit default.
+ *
+ * The kube-apiserver certificate is only valid for the addresses baked
+ * into it. `bind-address` and `advertise-address` both say "clients reach
+ * this server somewhere other than its bare node-ip" — a fixed bind
+ * address, or a front-door address for an HA load balancer / VIP. Either
+ * one without a matching `tls-san` entry means the first connection
+ * through that address hits a certificate mismatch.
+ */
+
+import type {
+  PostSynthCheck,
+  PostSynthContext,
+  PostSynthDiagnostic,
+} from "@intentius/chant/lint/post-synth";
+import { entitiesOfType } from "./k3s-helpers";
+
+function isNonEmptyString(value: unknown): value is string {
+  return typeof value === "string" && value.length > 0;
+}
+
+export const k3s106: PostSynthCheck = {
+  id: "K3S106",
+  description: "tls-san is missing while bind-address or advertise-address is declared",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+    for (const entity of entitiesOfType(ctx, "K3s::Server")) {
+      const tlsSan = entity.props["tls-san"];
+      const hasTlsSan = isNonEmptyString(tlsSan) || (Array.isArray(tlsSan) && tlsSan.length > 0);
+      if (hasTlsSan) continue;
+
+      const bindAddress = entity.props["bind-address"];
+      const advertiseAddress = entity.props["advertise-address"];
+      const declaredField = isNonEmptyString(bindAddress)
+        ? "bind-address"
+        : isNonEmptyString(advertiseAddress)
+          ? "advertise-address"
+          : undefined;
+      if (!declaredField) continue;
+
+      diagnostics.push({
+        checkId: "K3S106",
+        severity: "warning",
+        message:
+          `"${entity.name}" sets \`${declaredField}\` but declares no \`tls-san\` — ` +
+          "the apiserver certificate won't cover that address, and the first client to reach " +
+          "it there hits a TLS mismatch. Add it to `tls-san`.",
+        entity: entity.name,
+        lexicon: "k3s",
+      });
+    }
+    return diagnostics;
+  },
+};

package/src/lint/post-synth/k3s107.ts

@@ -0,0 +1,66 @@
+/**
+ * K3S107: a packaged component is disabled but also configured.
+ *
+ * `disable` removes a packaged component entirely — the flags that
+ * configure it (`cluster-dns` for coredns, `servicelb-namespace` for
+ * servicelb, `default-local-storage-path` for local-storage) then land in
+ * config.yaml for a component that never starts. Dead config, and a
+ * signal the `disable` and the config drifted out of sync rather than
+ * being written together.
+ */
+
+import type {
+  PostSynthCheck,
+  PostSynthContext,
+  PostSynthDiagnostic,
+} from "@intentius/chant/lint/post-synth";
+import { entitiesOfType } from "./k3s-helpers";
+
+/**
+ * Packaged component name (as it appears in `disable`) to the config keys
+ * that only make sense while that component runs. Limited to the
+ * components the k3s server flag surface actually has dedicated
+ * configuration for — traefik and metrics-server are configured via Helm
+ * chart manifests, not server flags, so there is nothing here to conflict.
+ */
+const COMPONENT_CONFIG_KEYS: Record<string, string[]> = {
+  coredns: ["cluster-dns"],
+  servicelb: ["servicelb-namespace"],
+  "local-storage": ["default-local-storage-path"],
+};
+
+export const k3s107: PostSynthCheck = {
+  id: "K3S107",
+  description: "disable names a component the config also configures",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+    for (const entity of entitiesOfType(ctx, "K3s::Server")) {
+      const raw = entity.props.disable;
+      const disabled = typeof raw === "string" ? [raw] : Array.isArray(raw) ? raw : [];
+      for (const component of disabled) {
+        if (typeof component !== "string") continue;
+        const configKeys = COMPONENT_CONFIG_KEYS[component];
+        if (!configKeys) continue;
+        for (const key of configKeys) {
+          const value = entity.props[key];
+          const isSet =
+            (typeof value === "string" && value.length > 0) ||
+            (Array.isArray(value) && value.length > 0);
+          if (!isSet) continue;
+          diagnostics.push({
+            checkId: "K3S107",
+            severity: "warning",
+            message:
+              `"${entity.name}" disables \`${component}\` but also sets \`${key}\` — ` +
+              `that config has no effect on a component that never starts. Remove \`${key}\`, ` +
+              `or drop \`${component}\` from \`disable\`.`,
+            entity: entity.name,
+            lexicon: "k3s",
+          });
+        }
+      }
+    }
+    return diagnostics;
+  },
+};

package/src/lint/post-synth/post-synth.test.ts

@@ -5,6 +5,8 @@ import { k3s102 } from "./k3s102";
 import { k3s103 } from "./k3s103";
 import { k3s104 } from "./k3s104";
 import { k3s105 } from "./k3s105";
+import { k3s106 } from "./k3s106";
+import { k3s107 } from "./k3s107";
 
 function makeCtx(entities: Record<string, { entityType: string; props: Record<string, unknown> }>): PostSynthContext {
   return {
@@ -135,3 +137,87 @@ describe("K3S105: TLS verification disabled for a registry", () => {
     expect(diags).toHaveLength(0);
   });
 });
+
+describe("K3S106: tls-san missing for a declared bind/advertise address", () => {
+  test("flags bind-address with no tls-san", () => {
+    const diags = k3s106.check(
+      makeCtx({ cp: { entityType: "K3s::Server", props: { "bind-address": "10.0.0.10" } } }),
+    );
+    expect(diags).toHaveLength(1);
+    expect(diags[0].checkId).toBe("K3S106");
+    expect(diags[0].severity).toBe("warning");
+  });
+
+  test("flags advertise-address with no tls-san", () => {
+    const diags = k3s106.check(
+      makeCtx({ cp: { entityType: "K3s::Server", props: { "advertise-address": "10.0.0.20" } } }),
+    );
+    expect(diags).toHaveLength(1);
+  });
+
+  test("passes bind-address with tls-san set, and neither address declared", () => {
+    const diags = k3s106.check(
+      makeCtx({
+        a: {
+          entityType: "K3s::Server",
+          props: { "bind-address": "10.0.0.10", "tls-san": ["10.0.0.10"] },
+        },
+        b: { entityType: "K3s::Server", props: {} },
+      }),
+    );
+    expect(diags).toHaveLength(0);
+  });
+});
+
+describe("K3S107: disabled component still configured", () => {
+  test("flags servicelb-namespace with servicelb disabled", () => {
+    const diags = k3s107.check(
+      makeCtx({
+        cp: {
+          entityType: "K3s::Server",
+          props: { disable: ["servicelb"], "servicelb-namespace": "kube-system" },
+        },
+      }),
+    );
+    expect(diags).toHaveLength(1);
+    expect(diags[0].checkId).toBe("K3S107");
+    expect(diags[0].severity).toBe("warning");
+  });
+
+  test("flags cluster-dns with coredns disabled, and default-local-storage-path with local-storage disabled", () => {
+    const diags = k3s107.check(
+      makeCtx({
+        cp: {
+          entityType: "K3s::Server",
+          props: {
+            disable: ["coredns", "local-storage"],
+            "cluster-dns": "10.43.0.10",
+            "default-local-storage-path": "/data",
+          },
+        },
+      }),
+    );
+    expect(diags).toHaveLength(2);
+  });
+
+  test("passes disabling traefik (no server flag configures it) and unrelated config", () => {
+    const diags = k3s107.check(
+      makeCtx({
+        cp: {
+          entityType: "K3s::Server",
+          props: { disable: ["traefik"], "tls-san": ["10.0.0.10"] },
+        },
+      }),
+    );
+    expect(diags).toHaveLength(0);
+  });
+
+  test("passes servicelb-namespace with nothing disabled", () => {
+    const diags = k3s107.check(
+      makeCtx({
+        cp: { entityType: "K3s::Server", props: { "servicelb-namespace": "kube-system" } },
+      }),
+    );
+    expect(diags).toHaveLength(0);
+  });
+});

package/src/op/activities/index.ts

@@ -0,0 +1,30 @@
+/**
+ * k3s Op activities — resolved by the core activity registry when a project's
+ * `chant.config.ts` lists the `k3s` lexicon. Lifecycle activities for the
+ * reachable-host case (chant#1601, epic #1598):
+ *   - k3sInstall — run the pinned installer (`INSTALL_K3S_VERSION`), idempotent
+ *     on an already-installed matching version.
+ *   - k3sUninstall — the uninstall script, gated the way k3dDown is.
+ *
+ * Bounded exactly as k3dUp/k3dDown were (chant#1410): no SSH orchestration,
+ * no host provisioning. The join token never travels through these activities
+ * as a value — only `tokenFile`, a path — see the token-boundary note on
+ * {@link k3sInstall} in ./k3s.
+ *
+ * The step builders (k3sInstall, k3sUninstall) live in core, re-exported from
+ * the temporal Op-authoring barrel like k3dUp/k3dDown. The activities here are
+ * dependency-light — they shell out to the k3s installer/uninstall scripts and
+ * only pull in the lexicon's version pin, not its declarable surface — so a
+ * Temporal worker loads them cheaply.
+ */
+export {
+  k3sInstall,
+  k3sUninstall,
+  k3sInstallCommand,
+  k3sInstallEnv,
+  k3sUninstallCommand,
+  k3sUninstallScript,
+  k3sVersionCommand,
+  parseK3sVersion,
+} from "./k3s";
+export type { K3sRole, K3sInstallArgs, K3sUninstallArgs, K3sInstallResult } from "./k3s";