K3s

Author: cristianrgreco

docs/modules/k3s.md

@@ -1,6 +1,7 @@
-# K3s Module
+# K3s
 
-[K3s](https://k3s.io/) is a highly available, certified Kubernetes distribution designed for production workloads in unattended, resource-constrained, remote locations or inside IoT appliances.
+!!! warning
+    This container runs privileged, as it spawns its own containers. For this reason, this container will not work in certain rootless Docker, Docker-in-Docker, or other environments that disallow privileged containers.
 
 ## Install
 
@@ -10,17 +11,28 @@ npm install @testcontainers/k3s --save-dev
 
 ## Examples
 
+These examples use the following libraries:
+
+- [@kubernetes/client-node](https://www.npmjs.com/package/@kubernetes/client-node)
+
+        npm install @kubernetes/client-node
+
+Choose an image from the [container registry](https://hub.docker.com/r/rancher/k3s) and substitute `IMAGE`.
+
+### List nodes
+
 <!--codeinclude-->
-[Starting a K3s server:](../../packages/modules/k3s/src/k3s-container.test.ts) inside_block:starting_k3s
+[](../../packages/modules/k3s/src/k3s-container.test.ts) inside_block:k3sListNodes
 <!--/codeinclude-->
+ 
+### Start a pod
 
 <!--codeinclude-->
-[Connecting to the server using the Kubernetes JavaScript client:](../../packages/modules/k3s/src/k3s-container.test.ts) inside_block:connecting_with_client
+[](../../packages/modules/k3s/src/k3s-container.test.ts) inside_block:k3sStartPod
 <!--/codeinclude-->
 
-## Known limitations
+### Aliased kubeconfig
 
-!!! warning
-    * K3sContainer runs as a privileged container and needs to be able to spawn its own containers. For these reasons,
-    K3sContainer will not work in certain rootless Docker, Docker-in-Docker, or other environments where privileged
-    containers are disallowed.
+<!--codeinclude-->
+[](../../packages/modules/k3s/src/k3s-container.test.ts) inside_block:k3sAliasedKubeConfig
+<!--/codeinclude-->

packages/modules/k3s/src/k3s-container.test.ts

@@ -1,65 +1,33 @@
 import * as k8s from "@kubernetes/client-node";
-import { setTimeout } from "node:timers/promises";
 import { GenericContainer, Network, Wait } from "testcontainers";
+import { getImage } from "../../../testcontainers/src/utils/test-helper";
 import { K3sContainer } from "./k3s-container";
 
-describe("K3s", { timeout: 120_000 }, () => {
-  it("should construct", () => {
-    new K3sContainer("rancher/k3s:v1.31.2-k3s1");
-  });
+const IMAGE = getImage(__dirname);
 
+describe("K3s", { timeout: 120_000 }, () => {
   // K3sContainer runs as a privileged container
   if (!process.env["CI_ROOTLESS"]) {
     it("should start and have listable node", async () => {
-      // starting_k3s {
-      await using container = await new K3sContainer("rancher/k3s:v1.31.2-k3s1").start();
-      // }
-
-      // connecting_with_client {
-      // obtain a kubeconfig file that allows us to connect to k3s
-      const kubeConfig = container.getKubeConfig();
-
-      const kc = new k8s.KubeConfig();
-      kc.loadFromString(kubeConfig);
+      // k3sListNodes {
+      await using container = await new K3sContainer(IMAGE).start();
 
-      const client = kc.makeApiClient(k8s.CoreV1Api);
+      const kubeConfig = new k8s.KubeConfig();
+      kubeConfig.loadFromString(container.getKubeConfig());
 
-      // interact with the running K3s server, e.g.:
+      const client = kubeConfig.makeApiClient(k8s.CoreV1Api);
       const nodeList = await client.listNode();
-      // }
 
       expect(nodeList.items).toHaveLength(1);
-    });
-
-    it("should expose kubeconfig for a network alias", async () => {
-      await using network = await new Network().start();
-      await using container = await new K3sContainer("rancher/k3s:v1.31.2-k3s1")
-        .withNetwork(network)
-        .withNetworkAliases("k3s")
-        .start();
-
-      // obtain a kubeconfig that allows us to connect on the custom network
-      const kubeConfig = container.getAliasedKubeConfig("k3s");
-
-      await using kubectlContainer = await new GenericContainer("rancher/kubectl:v1.31.2")
-        .withNetwork(network)
-        .withCopyContentToContainer([{ content: kubeConfig, target: "/home/kubectl/.kube/config" }])
-        .withCommand(["get", "namespaces"])
-        .withWaitStrategy(Wait.forOneShotStartup())
-        .withStartupTimeout(30_000)
-        .start();
-
-      const chunks = [];
-      for await (const chunk of await kubectlContainer.logs()) {
-        chunks.push(chunk);
-      }
-      expect(chunks).toEqual(expect.arrayContaining([expect.stringContaining("kube-system")]));
+      // }
     });
 
     it("should start a pod", async () => {
-      await using container = await new K3sContainer("rancher/k3s:v1.31.2-k3s1").start();
-      const kc = new k8s.KubeConfig();
-      kc.loadFromString(container.getKubeConfig());
+      // k3sStartPod {
+      await using container = await new K3sContainer(IMAGE).start();
+
+      const kubeConfig = new k8s.KubeConfig();
+      kubeConfig.loadFromString(container.getKubeConfig());
 
       const pod = {
         metadata: {
@@ -85,23 +53,37 @@ describe("K3s", { timeout: 120_000 }, () => {
         },
       };
 
-      const client = kc.makeApiClient(k8s.CoreV1Api);
+      const client = kubeConfig.makeApiClient(k8s.CoreV1Api);
       await client.createNamespacedPod({ namespace: "default", body: pod });
 
-      // wait for pod to be ready
-      expect(await podIsReady(client, "default", "helloworld", 60_000)).toBe(true);
+      await vi.waitFor(async () => {
+        const { status } = await client.readNamespacedPodStatus({ namespace: "default", name: "helloworld" });
+
+        return (
+          status?.phase === "Running" &&
+          status?.conditions?.some((cond) => cond.type === "Ready" && cond.status === "True")
+        );
+      }, 60_000);
+      // }
     });
   }
-});
 
-async function podIsReady(client: k8s.CoreV1Api, namespace: string, name: string, timeout: number): Promise<boolean> {
-  for (const startTime = Date.now(); Date.now() - startTime < timeout; ) {
-    const res = await client.readNamespacedPodStatus({ namespace, name });
-    const ready =
-      res.status?.phase === "Running" &&
-      !!res.status?.conditions?.some((cond) => cond.type === "Ready" && cond.status === "True");
-    if (ready) return true;
-    await setTimeout(3_000);
-  }
-  return false;
-}
+  it("should expose kubeconfig for a network alias", async () => {
+    // k3sAliasedKubeConfig {
+    await using network = await new Network().start();
+    await using container = await new K3sContainer(IMAGE).withNetwork(network).withNetworkAliases("k3s").start();
+
+    const kubeConfig = container.getAliasedKubeConfig("k3s");
+
+    await using kubectlContainer = await new GenericContainer("rancher/kubectl:v1.31.2")
+      .withNetwork(network)
+      .withCopyContentToContainer([{ content: kubeConfig, target: "/home/kubectl/.kube/config" }])
+      .withCommand(["get", "namespaces"])
+      .withWaitStrategy(Wait.forOneShotStartup())
+      .start();
+
+    const chunks = await (await kubectlContainer.logs()).toArray();
+    expect(chunks).toEqual(expect.arrayContaining([expect.stringContaining("kube-system")]));
+    // }
+  });
+});