underpost 2.99.7 → 3.0.0

package/src/cli/cluster.js

@@ -36,6 +36,7 @@ class UnderpostCluster {
      * @param {boolean} [options.mysql=false] - Deploy MySQL.
      * @param {boolean} [options.postgresql=false] - Deploy PostgreSQL.
      * @param {boolean} [options.valkey=false] - Deploy Valkey.
+     * @param {boolean} [options.ipfs=false] - Deploy ipfs-cluster statefulset.
      * @param {boolean} [options.full=false] - Deploy a full set of common components.
      * @param {boolean} [options.info=false] - Display extensive Kubernetes cluster information.
      * @param {boolean} [options.certManager=false] - Deploy Cert-Manager for certificate management.
@@ -57,10 +58,10 @@ class UnderpostCluster {
      * @param {string} [options.prom=''] - Initialize the cluster with a Prometheus Operator deployment and monitor scrap for specified hosts.
      * @param {boolean} [options.uninstallHost=false] - Uninstall all host components.
      * @param {boolean} [options.config=false] - Apply general host configuration (SELinux, containerd, sysctl, firewalld).
-     * @param {boolean} [options.worker=false] - Configure as a worker node (for Kubeadm or K3s join).
      * @param {boolean} [options.chown=false] - Set up kubectl configuration for the current user.
      * @param {boolean} [options.removeVolumeHostPaths=false] - Remove data from host paths used by Persistent Volumes.
      * @param {string} [options.hosts] - Set custom hosts entries.
+     * @param {string} [options.replicas] - Set the number of replicas for certain deployments.
      * @memberof UnderpostCluster
      */
     async init(
@@ -73,6 +74,7 @@ class UnderpostCluster {
         mysql: false,
         postgresql: false,
         valkey: false,
+        ipfs: false,
         full: false,
         info: false,
         certManager: false,
@@ -94,10 +96,10 @@ class UnderpostCluster {
         prom: '',
         uninstallHost: false,
         config: false,
-        worker: false,
         chown: false,
         removeVolumeHostPaths: false,
         hosts: '',
+        replicas: '',
       },
     ) {
       // Handles initial host setup (installing docker, podman, kind, kubeadm, helm)
@@ -140,11 +142,14 @@ class UnderpostCluster {
       }
 
       // Reset Kubernetes cluster components (Kind/Kubeadm/K3s) and container runtimes
-      if (options.reset === true)
+      if (options.reset === true) {
+        const clusterType = options.k3s === true ? 'k3s' : options.kubeadm === true ? 'kubeadm' : 'kind';
         return await Underpost.cluster.safeReset({
           underpostRoot,
           removeVolumeHostPaths: options.removeVolumeHostPaths,
+          clusterType,
         });
+      }
 
       // Check if a cluster (Kind, Kubeadm, or K3s) is already initialized
       const alreadyKubeadmCluster = Underpost.deploy.get('calico-kube-controllers')[0];
@@ -153,66 +158,20 @@ class UnderpostCluster {
       const alreadyK3sCluster = Underpost.deploy.get('svclb-traefik')[0];
 
       // --- Kubeadm/Kind/K3s Cluster Initialization ---
-      // This block handles the initial setup of the Kubernetes cluster (control plane or worker).
-      // It prevents re-initialization if a cluster is already detected.
-      if (!options.worker && !alreadyKubeadmCluster && !alreadyKindCluster && !alreadyK3sCluster) {
+      if (!alreadyKubeadmCluster && !alreadyKindCluster && !alreadyK3sCluster) {
         Underpost.cluster.config();
         if (options.k3s === true) {
           logger.info('Initializing K3s control plane...');
           // Install K3s
-          console.log('Installing K3s...');
+          logger.info('Installing K3s...');
           shellExec(`curl -sfL https://get.k3s.io | sh -`);
-          console.log('K3s installation completed.');
-
-          // Move k3s binary to /bin/k3s and make it executable
-          shellExec(`sudo mv /usr/local/bin/k3s /bin/k3s`);
-          shellExec(`sudo chmod +x /bin/k3s`);
-          console.log('K3s binary moved to /bin/k3s and made executable.');
+          logger.info('K3s installation completed.');
 
-          // Configure kubectl for the current user for K3s *before* checking readiness
-          // This ensures kubectl can find the K3s kubeconfig immediately after K3s installation.
           Underpost.cluster.chown('k3s');
 
-          // Wait for K3s to be ready
           logger.info('Waiting for K3s to be ready...');
-          let k3sReady = false;
-          let retries = 0;
-          const maxRetries = 20; // Increased retries for K3s startup
-          const delayMs = 5000; // 5 seconds
-
-          while (!k3sReady && retries < maxRetries) {
-            try {
-              // Explicitly use KUBECONFIG for kubectl commands to ensure it points to K3s config
-              const nodes = shellExec(`KUBECONFIG=/etc/rancher/k3s/k3s.yaml kubectl get nodes -o json`, {
-                stdout: true,
-                silent: true,
-              });
-              const parsedNodes = JSON.parse(nodes);
-              if (
-                parsedNodes.items.some((node) =>
-                  node.status.conditions.some((cond) => cond.type === 'Ready' && cond.status === 'True'),
-                )
-              ) {
-                k3sReady = true;
-                logger.info('K3s cluster is ready.');
-              } else {
-                logger.info(`K3s not yet ready. Retrying in ${delayMs / 1000} seconds...`);
-                await new Promise((resolve) => setTimeout(resolve, delayMs));
-              }
-            } catch (error) {
-              logger.info(`Error checking K3s status: ${error.message}. Retrying in ${delayMs / 1000} seconds...`);
-              await new Promise((resolve) => setTimeout(resolve, delayMs));
-            }
-            retries++;
-          }
-
-          if (!k3sReady) {
-            logger.error('K3s cluster did not become ready in time. Please check the K3s logs.');
-            return;
-          }
-
-          // K3s includes local-path-provisioner by default, so no need to install explicitly.
-          logger.info('K3s comes with local-path-provisioner by default. Skipping explicit installation.');
+          shellExec(`sudo systemctl is-active --wait k3s || sudo systemctl wait --for=active k3s.service`);
+          logger.info('K3s service is active.');
         } else if (options.kubeadm === true) {
           logger.info('Initializing Kubeadm control plane...');
           // Set default values if not provided
@@ -254,14 +213,6 @@ class UnderpostCluster {
           );
           Underpost.cluster.chown('kind'); // Pass 'kind' to chown
         }
-      } else if (options.worker === true) {
-        // Worker node specific configuration (kubeadm join command needs to be executed separately)
-        logger.info('Worker node configuration applied. Awaiting join command...');
-        // No direct cluster initialization here for workers. The `kubeadm join` or `k3s agent` command
-        // needs to be run on the worker after the control plane is up and a token is created.
-        // This part of the script is for general worker setup, not the join itself.
-      } else {
-        logger.warn('Cluster already initialized or worker flag not set for worker node.');
       }
 
       // --- Optional Component Deployments (Databases, Ingress, Cert-Manager) ---
@@ -307,36 +258,21 @@ EOF
       }
 
       if (options.full === true || options.valkey === true) {
-        if (options.pullImage === true) {
-          // shellExec(`sudo podman pull valkey/valkey:latest`);
-          if (!options.kubeadm && !options.k3s) {
-            // Only load if not kubeadm/k3s (Kind needs it)
-            shellExec(`docker pull valkey/valkey:latest`);
-            shellExec(`sudo kind load docker-image valkey/valkey:latest`);
-          } else if (options.kubeadm || options.k3s)
-            // For kubeadm/k3s, ensure it's available for containerd
-            shellExec(`sudo crictl pull valkey/valkey:latest`);
-        }
+        if (options.pullImage === true) Underpost.cluster.pullImage('valkey/valkey:latest', options);
         shellExec(`kubectl delete statefulset valkey-service -n ${options.namespace} --ignore-not-found`);
         shellExec(`kubectl apply -k ${underpostRoot}/manifests/valkey -n ${options.namespace}`);
         await Underpost.test.statusMonitor('valkey-service', 'Running', 'pods', 1000, 60 * 10);
       }
+      if (options.ipfs) {
+        await Underpost.ipfs.deploy(options, underpostRoot);
+      }
       if (options.full === true || options.mariadb === true) {
         shellExec(
           `sudo kubectl create secret generic mariadb-secret --from-file=username=/home/dd/engine/engine-private/mariadb-username --from-file=password=/home/dd/engine/engine-private/mariadb-password --dry-run=client -o yaml | kubectl apply -f - -n ${options.namespace}`,
         );
         shellExec(`kubectl delete statefulset mariadb-statefulset -n ${options.namespace} --ignore-not-found`);
 
-        if (options.pullImage === true) {
-          // shellExec(`sudo podman pull mariadb:latest`);
-          if (!options.kubeadm && !options.k3s) {
-            // Only load if not kubeadm/k3s (Kind needs it)
-            shellExec(`docker pull mariadb:latest`);
-            shellExec(`sudo kind load docker-image mariadb:latest`);
-          } else if (options.kubeadm || options.k3s)
-            // For kubeadm/k3s, ensure it's available for containerd
-            shellExec(`sudo crictl pull mariadb:latest`);
-        }
+        if (options.pullImage === true) Underpost.cluster.pullImage('mariadb:latest', options);
         shellExec(`kubectl apply -f ${underpostRoot}/manifests/mariadb/storage-class.yaml -n ${options.namespace}`);
         shellExec(`kubectl apply -k ${underpostRoot}/manifests/mariadb -n ${options.namespace}`);
       }
@@ -350,30 +286,14 @@ EOF
         shellExec(`kubectl apply -k ${underpostRoot}/manifests/mysql -n ${options.namespace}`);
       }
       if (options.full === true || options.postgresql === true) {
-        if (options.pullImage === true) {
-          if (!options.kubeadm && !options.k3s) {
-            // Only load if not kubeadm/k3s (Kind needs it)
-            shellExec(`docker pull postgres:latest`);
-            shellExec(`sudo kind load docker-image postgres:latest`);
-          } else if (options.kubeadm || options.k3s)
-            // For kubeadm/k3s, ensure it's available for containerd
-            shellExec(`sudo crictl pull postgres:latest`);
-        }
+        if (options.pullImage === true) Underpost.cluster.pullImage('postgres:latest', options);
         shellExec(
           `sudo kubectl create secret generic postgres-secret --from-file=password=/home/dd/engine/engine-private/postgresql-password --dry-run=client -o yaml | kubectl apply -f - -n ${options.namespace}`,
         );
         shellExec(`kubectl apply -k ${underpostRoot}/manifests/postgresql -n ${options.namespace}`);
       }
       if (options.mongodb4 === true) {
-        if (options.pullImage === true) {
-          if (!options.kubeadm && !options.k3s) {
-            // Only load if not kubeadm/k3s (Kind needs it)
-            shellExec(`docker pull mongo:4.4`);
-            shellExec(`sudo kind load docker-image mongo:4.4`);
-          } else if (options.kubeadm || options.k3s)
-            // For kubeadm/k3s, ensure it's available for containerd
-            shellExec(`sudo crictl pull mongo:4.4`);
-        }
+        if (options.pullImage === true) Underpost.cluster.pullImage('mongo:4.4', options);
         shellExec(`kubectl apply -k ${underpostRoot}/manifests/mongodb-4.4 -n ${options.namespace}`);
 
         const deploymentName = 'mongodb-deployment';
@@ -395,15 +315,7 @@ EOF
           );
         }
       } else if (options.full === true || options.mongodb === true) {
-        if (options.pullImage === true) {
-          if (!options.kubeadm && !options.k3s) {
-            // Only load if not kubeadm/k3s (Kind needs it)
-            shellExec(`docker pull mongo:latest`);
-            shellExec(`sudo kind load docker-image mongo:latest`);
-          } else if (options.kubeadm || options.k3s)
-            // For kubeadm/k3s, ensure it's available for containerd
-            shellExec(`sudo crictl pull mongo:latest`);
-        }
+        if (options.pullImage === true) Underpost.cluster.pullImage('mongo:latest', options);
         shellExec(
           `sudo kubectl create secret generic mongodb-keyfile --from-file=/home/dd/engine/engine-private/mongodb-keyfile --dry-run=client -o yaml | kubectl apply -f - -n ${options.namespace}`,
         );
@@ -464,6 +376,32 @@ EOF
       }
     },
 
+    /**
+     * @method pullImage
+     * @description Pulls a container image using the appropriate runtime based on the cluster type.
+     * - For Kind clusters: pulls via Docker and loads the image into the Kind cluster.
+     * - For Kubeadm/K3s clusters: pulls via crictl (containerd).
+     * @param {string} image - The fully-qualified container image reference (e.g. 'mongo:latest').
+     * @param {object} options - The cluster options object from `init`.
+     * @param {boolean} [options.kubeadm=false] - Whether the cluster is Kubeadm-based.
+     * @param {boolean} [options.k3s=false] - Whether the cluster is K3s-based.
+     * @memberof UnderpostCluster
+     */
+    pullImage(image, options = { kubeadm: false, k3s: false }) {
+      if (!options.kubeadm && !options.k3s) {
+        const tarPath = `/tmp/kind-image-${image.replace(/[\/:]/g, '-')}.tar`;
+        shellExec(`docker pull ${image}`);
+        shellExec(`docker save ${image} -o ${tarPath}`);
+        shellExec(
+          `for node in $(kind get nodes); do cat ${tarPath} | docker exec -i $node ctr --namespace=k8s.io images import -; done`,
+        );
+        shellExec(`rm -f ${tarPath}`);
+      } else if (options.kubeadm || options.k3s) {
+        // Kubeadm / K3s: use crictl to pull directly into containerd
+        shellExec(`sudo crictl pull ${image}`);
+      }
+    },
+
     /**
      * @method config
      * @description Configures host-level settings required for Kubernetes.
@@ -570,12 +508,15 @@ net.ipv4.ip_forward = 1' | sudo tee ${iptableConfPath}`,
      * @description Performs a complete reset of the Kubernetes cluster and its container environments.
      * This version focuses on correcting persistent permission errors (such as 'permission denied'
      * in coredns) by restoring SELinux security contexts and safely cleaning up cluster artifacts.
+     * Only the uninstall/delete commands specific to the given clusterType are executed; all other
+     * cleanup steps (log truncation, filesystem, network) are always run as generic k8s resets.
      * @param {object} [options] - Configuration options for the reset.
      * @param {string} [options.underpostRoot] - The root path of the underpost project.
      * @param {boolean} [options.removeVolumeHostPaths=false] - Whether to remove data from host paths used by Persistent Volumes.
+     * @param {string} [options.clusterType='kind'] - The type of cluster to reset: 'kind', 'kubeadm', or 'k3s'.
      * @memberof UnderpostCluster
      */
-    async safeReset(options = { underpostRoot: '.', removeVolumeHostPaths: false }) {
+    async safeReset(options = { underpostRoot: '.', removeVolumeHostPaths: false, clusterType: 'kind' }) {
       logger.info('Starting a safe and comprehensive reset of Kubernetes and container environments...');
 
       try {
@@ -645,14 +586,22 @@ net.ipv4.ip_forward = 1' | sudo tee ${iptableConfPath}`,
         // Safely unmount pod filesystems to avoid errors.
         shellExec('sudo umount -f /var/lib/kubelet/pods/*/*');
 
-        // Phase 3: Execute official uninstallation commands
-        logger.info('Phase 3/7: Executing official reset and uninstallation commands...');
-        logger.info('  -> Executing kubeadm reset...');
-        shellExec('sudo kubeadm reset --force');
-        logger.info('  -> Executing K3s uninstallation script if it exists...');
-        shellExec('sudo /usr/local/bin/k3s-uninstall.sh');
-        logger.info('  -> Deleting Kind clusters...');
-        shellExec('kind get clusters | xargs -r -t -n1 kind delete cluster');
+        // Phase 3: Execute official uninstallation commands (type-specific)
+        const clusterType = options.clusterType || 'kind';
+        logger.info(
+          `Phase 3/7: Executing official reset/uninstallation commands for cluster type: '${clusterType}'...`,
+        );
+        if (clusterType === 'kubeadm') {
+          logger.info('  -> Executing kubeadm reset...');
+          shellExec('sudo kubeadm reset --force');
+        } else if (clusterType === 'k3s') {
+          logger.info('  -> Executing K3s uninstallation script if it exists...');
+          shellExec('sudo /usr/local/bin/k3s-uninstall.sh');
+        } else {
+          // Default: kind
+          logger.info('  -> Deleting Kind clusters...');
+          shellExec('kind get clusters | xargs -r -t -n1 kind delete cluster');
+        }
 
         // Phase 4: File system cleanup
         logger.info('Phase 4/7: Cleaning up remaining file system artifacts...');
@@ -672,9 +621,6 @@ net.ipv4.ip_forward = 1' | sudo tee ${iptableConfPath}`,
         // Remove iptables rules and CNI network interfaces.
         shellExec('sudo iptables -F');
         shellExec('sudo iptables -t nat -F');
-        // Restore iptables rules
-        shellExec(`chmod +x ${options.underpostRoot}/scripts/nat-iptables.sh`);
-        shellExec(`${options.underpostRoot}/scripts/nat-iptables.sh`, { silent: true });
         shellExec('sudo ip link del cni0');
         shellExec('sudo ip link del flannel.1');
 
@@ -772,6 +718,11 @@ EOF`);
       shellExec(`chmod +x /usr/local/bin/helm`);
       shellExec(`sudo mv /usr/local/bin/helm /bin/helm`);
       shellExec(`sudo rm -rf get_helm.sh`);
+
+      // Install snap
+      shellExec(`sudo yum install -y snapd`);
+      shellExec(`sudo systemctl enable --now snapd.socket`);
+
       console.log('Host prerequisites installed successfully.');
     },
 

package/src/cli/deploy.js

@@ -491,6 +491,7 @@ spec:
         retryPerTryTimeout: '',
         kindType: '',
         port: 0,
+        exposePort: 0,
         cmd: '',
       },
     ) {
@@ -573,11 +574,13 @@ EOF`);
         if (options.expose === true) {
           const kindType = options.kindType ? options.kindType : 'svc';
           const svc = Underpost.deploy.get(deployId, kindType)[0];
-          const port = options.port
-            ? options.port
-            : kindType !== 'svc'
-              ? 80
-              : parseInt(svc[`PORT(S)`].split('/TCP')[0]);
+          const port = options.exposePort
+            ? parseInt(options.exposePort)
+            : options.port
+              ? parseInt(options.port)
+              : kindType !== 'svc'
+                ? 80
+                : parseInt(svc[`PORT(S)`].split('/TCP')[0]);
           logger.info(deployId, {
             svc,
             port,

package/src/cli/index.js

@@ -214,6 +214,7 @@ program
   .option('--postgresql', 'Initializes the cluster with a PostgreSQL statefulset.')
   .option('--mongodb4', 'Initializes the cluster with a MongoDB 4.4 service.')
   .option('--valkey', 'Initializes the cluster with a Valkey service.')
+  .option('--ipfs', 'Initializes the cluster with an ipfs-cluster statefulset.')
   .option('--contour', 'Initializes the cluster with Project Contour base HTTPProxy and Envoy.')
   .option('--cert-manager', "Initializes the cluster with a Let's Encrypt production ClusterIssuer.")
   .option('--dedicated-gpu', 'Initializes the cluster with dedicated GPU base resources and environment settings.')
@@ -242,12 +243,12 @@ program
   .option('--init-host', 'Installs necessary Kubernetes node CLI tools (e.g., kind, kubeadm, docker, podman, helm).')
   .option('--uninstall-host', 'Uninstalls all host components installed by init-host.')
   .option('--config', 'Sets the base Kubernetes node configuration.')
-  .option('--worker', 'Sets the context for a worker node.')
   .option('--chown', 'Sets the appropriate ownership for Kubernetes kubeconfig files.')
   .option('--k3s', 'Initializes the cluster using K3s (Lightweight Kubernetes).')
   .option('--hosts <hosts>', 'A comma-separated list of cluster hostnames or IP addresses.')
   .option('--remove-volume-host-paths', 'Removes specified volume host paths after execution.')
   .option('--namespace <namespace>', 'Kubernetes namespace for cluster operations (defaults to "default").')
+  .option('--replicas <replicas>', 'Sets a custom number of replicas for statefulset deployments.')
   .action(Underpost.cluster.init)
   .description('Manages Kubernetes clusters, defaulting to Kind cluster initialization.');
 
@@ -295,6 +296,10 @@ program
   .option('--namespace <namespace>', 'Kubernetes namespace for deployment operations (defaults to "default").')
   .option('--kind-type <kind-type>', 'Specifies the Kind cluster type for deployment operations.')
   .option('--port <port>', 'Sets up port forwarding from local to remote ports.')
+  .option(
+    '--expose-port <port>',
+    'Sets the local:remote port to expose when --expose is active (overrides auto-detected service port).',
+  )
   .option('--cmd <cmd>', 'Custom initialization command for deployment (comma-separated commands).')
   .description('Manages application deployments, defaulting to deploying development pods.')
   .action(Underpost.deploy.callback);
@@ -613,37 +618,33 @@ program
 
 program
   .command('lxd')
-  .option('--init', 'Initializes LXD on the current machine.')
-  .option('--reset', 'Resets LXD on the current machine, deleting all configurations.')
-  .option('--install', 'Installs LXD on the current machine.')
-  .option('--dev', 'Sets the development context environment for LXD.')
-  .option('--create-virtual-network', 'Creates an LXD virtual network bridge.')
-  .option('--create-admin-profile', 'Creates an admin profile for LXD management.')
-  .option('--control', 'Sets the context for a control node VM.')
-  .option('--worker', 'Sets the context for a worker node VM.')
-  .option('--create-vm <vm-id>', 'Creates default virtual machines with the specified ID.')
-  .option('--init-vm <vm-id>', 'Retrieves the Underpost initialization script for the specified VM.')
-  .option('--info-vm <vm-id>', 'Retrieves all information about the specified VM.')
-  .option('--test <vm-id>', 'Tests the health, status, and network connectivity for a VM.')
-  .option('--root-size <gb-size>', 'Sets the root partition size (in GB) for the VM.')
-  .option('--k3s', 'Flag to indicate that the VM initialization is for a K3s cluster type.')
+  .option('--init', 'Initializes LXD on the current machine via preseed.')
+  .option('--reset', 'Removes the LXD snap and purges all data.')
+  .option('--install', 'Installs the LXD snap.')
+  .option('--dev', 'Use local paths instead of the global npm installation.')
+  .option('--create-virtual-network', 'Creates the lxdbr0 bridge network.')
+  .option('--ipv4-address <cidr>', 'IPv4 address/CIDR for the lxdbr0 bridge network (default: "10.250.250.1/24").')
+  .option('--create-admin-profile', 'Creates the admin-profile for VM management.')
+  .option('--control', 'Initialize the target VM as a K3s control plane node.')
+  .option('--worker', 'Initialize the target VM as a K3s worker node.')
+  .option('--create-vm <vm-name>', 'Copy the LXC launch command for a new K3s VM to the clipboard.')
+  .option('--delete-vm <vm-name>', 'Stop and delete the specified VM.')
+  .option('--init-vm <vm-name>', 'Run k3s-node-setup.sh on the specified VM (use with --control or --worker).')
+  .option('--info-vm <vm-name>', 'Display full configuration and status for the specified VM.')
+  .option('--test <vm-name>', 'Run connectivity and health checks on the specified VM.')
+  .option('--root-size <gb-size>', 'Root disk size in GiB for --create-vm (default: 32).')
   .option(
     '--join-node <nodes>',
-    'A comma-separated list of worker and control nodes to join (e.g., "k8s-worker-1,k8s-control").',
-  )
-  .option(
-    '--expose <vm-name-ports>',
-    'Exposes specified ports on a VM (e.g., "k8s-control:80,443"). Multiple VM-port pairs can be comma-separated.',
-  )
-  .option(
-    '--delete-expose <vm-name-ports>',
-    'Removes exposed ports on a VM (e.g., "k8s-control:80,443"). Multiple VM-port pairs can be comma-separated.',
-  )
-  .option('--workflow-id <workflow-id>', 'Sets the workflow ID context for LXD operations.')
-  .option('--vm-id <vm-id>', 'Sets the VM ID context for LXD operations.')
-  .option('--deploy-id <deploy-id>', 'Sets the deployment ID context for LXD operations.')
-  .option('--namespace <namespace>', 'Kubernetes namespace for LXD operations (defaults to "default").')
-  .description('Manages LXD containers and virtual machines.')
+    'Join a K3s worker to a control plane. Standalone format: "workerName,controlName". ' +
+      'When used with --init-vm --worker, provide just the control node name for auto-join.',
+  )
+  .option('--expose <vm-name:ports>', 'Proxy host ports to a VM (e.g., "k3s-control:80,443").')
+  .option('--delete-expose <vm-name:ports>', 'Remove proxied ports from a VM (e.g., "k3s-control:80,443").')
+  .option('--workflow-id <workflow-id>', 'Workflow ID to execute via runWorkflow.')
+  .option('--vm-id <vm-name>', 'Target VM name for workflow execution.')
+  .option('--deploy-id <deploy-id>', 'Deployment ID context for workflow execution.')
+  .option('--namespace <namespace>', 'Kubernetes namespace context (defaults to "default").')
+  .description('Manages LXD virtual machines as K3s nodes (control plane or workers).')
   .action(Underpost.lxd.callback);
 
 program

package/src/cli/ipfs.js

@@ -0,0 +1,184 @@
+/**
+ * IPFS Cluster module for managing ipfs-cluster StatefulSet deployment on Kubernetes.
+ * @module src/cli/ipfs.js
+ * @namespace UnderpostIPFS
+ */
+
+import { loggerFactory } from '../server/logger.js';
+import { shellExec } from '../server/process.js';
+import fs from 'fs-extra';
+import Underpost from '../index.js';
+
+const logger = loggerFactory(import.meta);
+
+/**
+ * @class UnderpostIPFS
+ * @description Manages deployment of an ipfs-cluster StatefulSet on Kubernetes.
+ * Credentials (cluster secret + peer identity) are generated once and persisted
+ * to engine-private/ so the cluster identity survives redeployments.
+ * @memberof UnderpostIPFS
+ */
+class UnderpostIPFS {
+  static API = {
+    /**
+     * @method resolveCredentials
+     * @description Resolves the IPFS cluster credentials from engine-private/ if they
+     * already exist, otherwise generates new ones (hex cluster secret + peer identity
+     * via ipfs-cluster-service init) and persists them with mode 0o600.
+     * @param {string} privateDir - Absolute path to the engine-private directory.
+     * @returns {{ CLUSTER_SECRET: string, IDENTITY_JSON: { id: string, private_key: string } }}
+     * @memberof UnderpostIPFS
+     */
+    resolveCredentials(privateDir) {
+      const secretPath = `${privateDir}/ipfs-cluster-secret`;
+      const identityPath = `${privateDir}/ipfs-cluster-identity.json`;
+
+      if (fs.existsSync(secretPath) && fs.existsSync(identityPath)) {
+        logger.info('Reusing existing IPFS cluster credentials from engine-private/');
+        return {
+          CLUSTER_SECRET: fs.readFileSync(secretPath, 'utf8').trim(),
+          IDENTITY_JSON: JSON.parse(fs.readFileSync(identityPath, 'utf8')),
+        };
+      }
+
+      logger.info('Generating new IPFS cluster credentials and persisting to engine-private/');
+
+      // ipfs-cluster-service requires CLUSTER_SECRET as a 64-char hex string.
+      // base64 (openssl rand -base64 32) contains '/', '+', '=' which are invalid hex bytes.
+      const CLUSTER_SECRET = shellExec("od -vN 32 -An -tx1 /dev/urandom | tr -d ' \\n'", {
+        stdout: true,
+      }).trim();
+
+      const tmpDir = '/tmp/ipfs-cluster-identity';
+      shellExec(`rm -rf ${tmpDir} && mkdir -p ${tmpDir}`);
+      shellExec(`docker run --rm -v ${tmpDir}:/data/ipfs-cluster ipfs/ipfs-cluster init -f`);
+      const IDENTITY_JSON = JSON.parse(shellExec(`cat ${tmpDir}/identity.json`, { stdout: true }).trim());
+      shellExec(`rm -rf ${tmpDir}`);
+
+      fs.ensureDirSync(privateDir);
+      fs.writeFileSync(secretPath, CLUSTER_SECRET, { mode: 0o600 });
+      fs.writeFileSync(identityPath, JSON.stringify(IDENTITY_JSON, null, 2), { mode: 0o600 });
+
+      logger.info(`IPFS cluster credentials saved (peer ID: ${IDENTITY_JSON.id})`);
+
+      return { CLUSTER_SECRET, IDENTITY_JSON };
+    },
+
+    /**
+     * @method teardown
+     * @description Deletes the existing ipfs-cluster StatefulSet, its Kubernetes Secret,
+     * env ConfigMap, and all PVCs so the next deployment initialises a clean data volume
+     * (ensuring the correct datastore profile is applied by the init container).
+     * @param {object} options
+     * @param {string} options.namespace - Kubernetes namespace.
+     * @param {number} ipfsReplicas - Number of replicas whose PVCs must be removed.
+     * @memberof UnderpostIPFS
+     */
+    teardown(options, ipfsReplicas) {
+      logger.info(`Tearing down existing ipfs-cluster deployment in namespace '${options.namespace}'`);
+      shellExec(`kubectl delete statefulset ipfs-cluster -n ${options.namespace} --ignore-not-found`);
+      shellExec(`kubectl delete secret ipfs-cluster-secret -n ${options.namespace} --ignore-not-found`);
+      shellExec(`kubectl delete configmap env-config -n ${options.namespace} --ignore-not-found`);
+      for (let i = 0; i < ipfsReplicas; i++) {
+        shellExec(
+          `kubectl delete pvc cluster-storage-ipfs-cluster-${i} ipfs-storage-ipfs-cluster-${i} -n ${options.namespace} --ignore-not-found`,
+        );
+      }
+    },
+
+    /**
+     * @method applySecrets
+     * @description Creates (or idempotently updates) the Kubernetes Secret and env ConfigMap
+     * that the StatefulSet pods read at startup.
+     * - Secret `ipfs-cluster-secret`: cluster-secret + bootstrap-peer-priv-key
+     * - ConfigMap `env-config`: bootstrap-peer-id + CLUSTER_SVC_NAME
+     * @param {{ CLUSTER_SECRET: string, IDENTITY_JSON: { id: string, private_key: string } }} credentials
+     * @param {object} options
+     * @param {string} options.namespace - Kubernetes namespace.
+     * @memberof UnderpostIPFS
+     */
+    applySecrets({ CLUSTER_SECRET, IDENTITY_JSON }, options) {
+      logger.info('Applying IPFS cluster Kubernetes Secret and env ConfigMap');
+
+      shellExec(
+        `kubectl create secret generic ipfs-cluster-secret \
+--from-literal=cluster-secret=${CLUSTER_SECRET} \
+--from-literal=bootstrap-peer-priv-key=${IDENTITY_JSON.private_key} \
+--dry-run=client -o yaml | kubectl apply -f - -n ${options.namespace}`,
+      );
+
+      shellExec(
+        `kubectl create configmap env-config \
+--from-literal=bootstrap-peer-id=${IDENTITY_JSON.id} \
+--from-literal=CLUSTER_SVC_NAME=ipfs-cluster \
+--dry-run=client -o yaml | kubectl apply -f - -n ${options.namespace}`,
+      );
+    },
+
+    /**
+     * @method applyManifests
+     * @description Applies host-level sysctl tuning (Kind clusters only), the storage class,
+     * the kustomize manifests, and scales the StatefulSet to the requested replica count.
+     * @param {object} options
+     * @param {string} options.namespace - Kubernetes namespace.
+     * @param {boolean} [options.kubeadm] - Whether the cluster is Kubeadm-based.
+     * @param {boolean} [options.k3s] - Whether the cluster is K3s-based.
+     * @param {string} underpostRoot - Absolute path to the underpost project root.
+     * @param {number} ipfsReplicas - Desired replica count.
+     * @memberof UnderpostIPFS
+     */
+    applyManifests(options, underpostRoot, ipfsReplicas) {
+      // Apply UDP buffer sysctl on every Kind node so QUIC (used by IPFS) can reach the
+      // recommended 7.5 MB buffer size. Kind nodes are containers and do NOT inherit the
+      // host sysctl values, so this must be set via docker exec on each node directly.
+      if (!options.kubeadm && !options.k3s) {
+        logger.info('Applying UDP buffer sysctl on Kind nodes');
+        shellExec(
+          `for node in $(kind get nodes); do docker exec $node sysctl -w net.core.rmem_max=7500000 net.core.wmem_max=7500000; done`,
+        );
+      }
+
+      shellExec(`kubectl apply -f ${underpostRoot}/manifests/ipfs/storage-class.yaml`);
+      shellExec(`kubectl apply -k ${underpostRoot}/manifests/ipfs -n ${options.namespace}`);
+
+      // statefulset.yaml hardcodes replicas: 3 as the ceiling; scale down here if needed.
+      shellExec(`kubectl scale statefulset ipfs-cluster --replicas=${ipfsReplicas} -n ${options.namespace}`);
+    },
+
+    /**
+     * @method deploy
+     * @description Full orchestration of the ipfs-cluster StatefulSet deployment:
+     * optionally pulls images, resolves or generates credentials, tears down any existing
+     * deployment, applies secrets, applies manifests, and waits for all pods to be Running.
+     * @param {object} options - Cluster init options forwarded from UnderpostCluster.API.init.
+     * @param {string} options.namespace - Kubernetes namespace.
+     * @param {boolean} [options.pullImage] - Whether to pull container images first.
+     * @param {boolean} [options.kubeadm] - Whether the cluster is Kubeadm-based.
+     * @param {boolean} [options.k3s] - Whether the cluster is K3s-based.
+     * @param {string|number} [options.replicas] - Override replica count (defaults to 3).
+     * @param {string} underpostRoot - Absolute path to the underpost project root.
+     * @memberof UnderpostIPFS
+     */
+    async deploy(options, underpostRoot) {
+      if (options.pullImage === true) {
+        Underpost.cluster.pullImage('ipfs/kubo:latest', options);
+        Underpost.cluster.pullImage('ipfs/ipfs-cluster:latest', options);
+      }
+
+      const credentials = Underpost.ipfs.resolveCredentials(`${underpostRoot}/engine-private`);
+
+      const ipfsReplicas = options.replicas ? parseInt(options.replicas) : 3;
+
+      Underpost.ipfs.teardown(options, ipfsReplicas);
+      Underpost.ipfs.applySecrets(credentials, options);
+      Underpost.ipfs.applyManifests(options, underpostRoot, ipfsReplicas);
+
+      logger.info(`Waiting for ${ipfsReplicas} ipfs-cluster pod(s) to reach Running state`);
+      for (let i = 0; i < ipfsReplicas; i++) {
+        await Underpost.test.statusMonitor(`ipfs-cluster-${i}`, 'Running', 'pods', 1000, 60 * 15);
+      }
+    },
+  };
+}
+
+export default UnderpostIPFS;