cyberia 3.2.5 → 3.2.9

package/src/cli/cluster.js

@@ -172,9 +172,19 @@ class UnderpostCluster {
           const podNetworkCidr = options.podNetworkCidr || '192.168.0.0/16';
           const controlPlaneEndpoint = options.controlPlaneEndpoint || `${os.hostname()}:6443`;
 
-          // Initialize kubeadm control plane
+          // Initialize kubeadm control plane.
+          // Use CRI-O socket when available, otherwise fall back to containerd.
+          const crioSocket = 'unix:///var/run/crio/crio.sock';
+          const containerdSocket = 'unix:///run/containerd/containerd.sock';
+          const criSocket =
+            shellExec(`test -S /var/run/crio/crio.sock && echo crio || echo containerd`, {
+              stdout: true,
+              silent: true,
+            }).trim() === 'crio'
+              ? crioSocket
+              : containerdSocket;
           shellExec(
-            `sudo kubeadm init --pod-network-cidr=${podNetworkCidr} --control-plane-endpoint="${controlPlaneEndpoint}"`,
+            `sudo kubeadm init --pod-network-cidr=${podNetworkCidr} --control-plane-endpoint="${controlPlaneEndpoint}" --cri-socket=${criSocket}`,
           );
           // Configure kubectl for the current user
           Underpost.cluster.chown('kubeadm'); // Pass 'kubeadm' to chown
@@ -389,8 +399,17 @@ EOF
         );
         shellExec(`rm -f ${tarPath}`);
       } else if (options.kubeadm || options.k3s) {
-        // Kubeadm / K3s: use crictl to pull directly into containerd
-        shellExec(`sudo crictl pull ${image}`);
+        // Kubeadm / K3s: use crictl to pull directly into the active CRI runtime.
+        // crictl is not in sudo's secure_path; pass full PATH through env.
+        // Point crictl at CRI-O when the socket exists, otherwise fall back to containerd.
+        const criSock =
+          shellExec(`test -S /var/run/crio/crio.sock && echo crio || echo containerd`, {
+            stdout: true,
+            silent: true,
+          }).trim() === 'crio'
+            ? 'unix:///var/run/crio/crio.sock'
+            : 'unix:///run/containerd/containerd.sock';
+        shellExec(`sudo env PATH="$PATH:/usr/local/bin:/usr/bin" crictl --runtime-endpoint ${criSock} pull ${image}`);
       }
     },
 
@@ -453,12 +472,11 @@ net.ipv4.ip_forward = 1' | sudo tee ${iptableConfPath}`,
       shellExec(`sudo sysctl -w fs.inotify.max_queued_events=2099999999`);
 
       // shellExec(`sudo sysctl --system`); // Apply sysctl changes immediately
-      // Apply NAT iptables rules.
+      // Apply NAT iptables rules and configure firewalld for Kubernetes.
+      // nat-iptables.sh enables firewalld and opens all required ports; do NOT stop it
+      // afterwards — keeping firewalld running with these rules is required for
+      // multi-machine kubeadm inter-node communication.
       shellExec(`${underpostRoot}/scripts/nat-iptables.sh`, { silent: true });
-
-      // Disable firewalld (common cause of network issues in Kubernetes)
-      shellExec(`sudo systemctl stop firewalld`); // Stop if running
-      shellExec(`sudo systemctl disable firewalld`); // Disable from starting on boot
     },
 
     /**
@@ -575,8 +593,10 @@ net.ipv4.ip_forward = 1' | sudo tee ${iptableConfPath}`,
         shellExec('sudo systemctl stop kubelet');
         shellExec('sudo systemctl stop docker');
         shellExec('sudo systemctl stop podman');
-        // Safely unmount pod filesystems to avoid errors.
-        shellExec('sudo umount -f /var/lib/kubelet/pods/*/*');
+        // Lazy-unmount all kubelet pod mounts to avoid 'Device or resource busy' on rm.
+        shellExec(
+          `sudo sh -c 'findmnt --raw --noheadings -o TARGET | grep /var/lib/kubelet | sort -r | xargs -r umount -l' 2>/dev/null || true`,
+        );
 
         // Phase 3: Execute official uninstallation commands (type-specific)
         const clusterType = options.clusterType || 'kind';
@@ -584,6 +604,14 @@ net.ipv4.ip_forward = 1' | sudo tee ${iptableConfPath}`,
           `Phase 3/7: Executing official reset/uninstallation commands for cluster type: '${clusterType}'...`,
         );
         if (clusterType === 'kubeadm') {
+          // Kill control plane processes that hold ports (6443, 10257, 10259, 2379, 2380)
+          // so the next `kubeadm init` does not fail with [ERROR Port-xxxx].
+          logger.info('  -> Stopping and killing control plane containers and processes...');
+          shellExec('sudo crictl rm -a -f 2>/dev/null || true');
+          shellExec('sudo crictl rmp -a -f 2>/dev/null || true');
+          shellExec('sudo systemctl stop etcd 2>/dev/null || true');
+          for (const port of [6443, 10259, 10257, 2379, 2380])
+            shellExec(`sudo fuser -k ${port}/tcp 2>/dev/null || true`);
           logger.info('  -> Executing kubeadm reset...');
           shellExec('sudo kubeadm reset --force');
         } else if (clusterType === 'k3s') {
@@ -600,7 +628,12 @@ net.ipv4.ip_forward = 1' | sudo tee ${iptableConfPath}`,
         // Remove any leftover configurations and data.
         shellExec('sudo rm -rf /etc/kubernetes/*');
         shellExec('sudo rm -rf /etc/cni/net.d/*');
+        // Second-pass lazy umount before rm to clear any remaining busy mounts.
+        shellExec(
+          `sudo sh -c 'findmnt --raw --noheadings -o TARGET | grep /var/lib/kubelet | sort -r | xargs -r umount -l' 2>/dev/null || true`,
+        );
         shellExec('sudo rm -rf /var/lib/kubelet/*');
+        shellExec('sudo rm -rf /var/lib/etcd');
         shellExec('sudo rm -rf /var/lib/cni/*');
         shellExec('sudo rm -rf /var/lib/docker/*');
         shellExec('sudo rm -rf /var/lib/containerd/*');
@@ -613,11 +646,14 @@ 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');
-        shellExec('sudo ip link del cni0');
-        shellExec('sudo ip link del flannel.1');
+        shellExec('sudo ip link del cni0 2>/dev/null || true');
+        shellExec('sudo ip link del flannel.1 2>/dev/null || true');
+        shellExec('sudo ip link del vxlan.calico 2>/dev/null || true');
+        shellExec('sudo ip link del tunl0 2>/dev/null || true');
 
         logger.info('Phase 6/7: Clean up images');
-        shellExec(`podman rmi $(podman images -qa) --force`);
+        shellExec('sudo podman rmi --all --force 2>/dev/null || true');
+        shellExec('sudo crictl rmi --prune 2>/dev/null || true');
 
         // Phase 6: Reload daemon and finalize
         logger.info('Phase 7/7: Reloading the system daemon and finalizing...');
@@ -687,6 +723,9 @@ net.ipv4.ip_forward = 1' | sudo tee ${iptableConfPath}`,
       // Install Podman
       shellExec(`sudo dnf -y install podman`);
 
+      // Install CRI-O (required for kubeadm with CRI-O socket)
+      shellExec(`node bin run install-crio`);
+
       // Install Kind (Kubernetes in Docker)
       shellExec(`[ $(uname -m) = ${archData.name} ] && curl -Lo ./kind https://kind.sigs.k8s.io/dl/v0.29.0/kind-linux-${archData.alias}
 chmod +x ./kind
@@ -744,6 +783,14 @@ EOF`);
       console.log('Removing Podman...');
       shellExec(`sudo dnf -y remove podman`);
 
+      // Remove CRI-O
+      console.log('Removing CRI-O...');
+      shellExec(`sudo systemctl stop crio 2>/dev/null || true`);
+      shellExec(`sudo systemctl disable crio 2>/dev/null || true`);
+      shellExec(`sudo dnf -y remove cri-o`);
+      shellExec(`sudo rm -f /etc/yum.repos.d/cri-o.repo`);
+      shellExec(`sudo rm -f /etc/crictl.yaml`);
+
       // Remove Kubeadm, Kubelet, and Kubectl
       console.log('Removing Kubernetes tools...');
       shellExec(`sudo yum remove -y kubelet kubeadm kubectl`);

package/src/cli/db.js

@@ -839,6 +839,8 @@ class UnderpostDB {
                 pods: podsToProcess.map((p) => p.NAME),
               });
 
+              let exportSucceeded = false;
+
               // Process each pod
               for (const pod of podsToProcess) {
                 logger.info('Processing pod', { podName: pod.NAME, node: pod.NODE, status: pod.STATUS });
@@ -871,7 +873,7 @@ class UnderpostDB {
 
                     if (options.export === true) {
                       const outputPath = options.outPath || toNewSqlPath;
-                      await Underpost.db._exportMariaDB({
+                      const success = await Underpost.db._exportMariaDB({
                         pod,
                         namespace,
                         dbName,
@@ -879,6 +881,7 @@ class UnderpostDB {
                         password,
                         outputPath,
                       });
+                      exportSucceeded = exportSucceeded || success;
                     }
                     break;
                   }
@@ -909,13 +912,14 @@ class UnderpostDB {
 
                     if (options.export === true) {
                       const outputPath = options.outPath || toNewBsonPath;
-                      Underpost.db._exportMongoDB({
+                      const success = Underpost.db._exportMongoDB({
                         pod,
                         namespace,
                         dbName,
                         outputPath,
                         collections: options.collections,
                       });
+                      exportSucceeded = exportSucceeded || success;
                     }
                     break;
                   }
@@ -926,6 +930,10 @@ class UnderpostDB {
                 }
               }
 
+              if (options.export === true && exportSucceeded === true) {
+                Underpost.db._enforceBackupRetention(`../${repoName}/${hostFolder}`);
+              }
+
               // Mark this host+path combination as processed
               processedHostPaths.add(hostPathKey);
             }
@@ -948,6 +956,43 @@ class UnderpostDB {
         throw error;
       }
     },
+    /**
+     * Helper: Removes old timestamp backup folders and keeps only the newest ones.
+     * @method _enforceBackupRetention
+     * @memberof UnderpostDB
+     * @param {string} backupDir - Path to host-folder backup directory.
+     * @param {number} [maxRetention=MAX_BACKUP_RETENTION] - Maximum folders to keep.
+     * @return {number} Number of removed backup folders.
+     */
+    _enforceBackupRetention(backupDir, maxRetention = MAX_BACKUP_RETENTION) {
+      try {
+        if (!fs.existsSync(backupDir)) return 0;
+
+        const timestamps = fs
+          .readdirSync(backupDir)
+          .filter((entry) => /^\d+$/.test(entry))
+          .sort((a, b) => parseInt(b, 10) - parseInt(a, 10));
+
+        if (timestamps.length <= maxRetention) return 0;
+
+        const staleTimestamps = timestamps.slice(maxRetention);
+        staleTimestamps.forEach((timestamp) => {
+          fs.removeSync(`${backupDir}/${timestamp}`);
+        });
+
+        logger.info('Pruned old backup timestamp folders', {
+          backupDir,
+          kept: maxRetention,
+          removed: staleTimestamps.length,
+          removedTimestamps: staleTimestamps,
+        });
+
+        return staleTimestamps.length;
+      } catch (error) {
+        logger.error('Failed to enforce backup retention', { backupDir, maxRetention, error: error.message });
+        return 0;
+      }
+    },
 
     /**
      * Creates cluster metadata for the specified deployment.

package/src/cli/deploy.js

@@ -9,6 +9,7 @@ import {
   buildPortProxyRouter,
   buildProxyRouter,
   Config,
+  cronDeployIdResolve,
   deployRangePortFactory,
   getDataDeploy,
   loadConfServerJson,
@@ -124,24 +125,47 @@ class UnderpostDeploy {
      * @param {string} namespace - Kubernetes namespace for the deployment.
      * @param {Array<object>} volumes - Volume configurations for the deployment.
      * @param {Array<string>} cmd - Command to run in the deployment container.
+     * @param {boolean} skipFullBuild - Whether to skip the full client bundle build during deployment.
+     * @param {boolean} pullBundle - Whether to pull the pre-built client bundle from Cloudinary before starting. Use together with skipFullBuild to skip the local build entirely.
      * @returns {string} - YAML deployment configuration for the specified deployment.
      * @memberof UnderpostDeploy
      */
-    deploymentYamlPartsFactory({ deployId, env, suffix, resources, replicas, image, namespace, volumes, cmd }) {
+    deploymentYamlPartsFactory({
+      deployId,
+      env,
+      suffix,
+      resources,
+      replicas,
+      image,
+      namespace,
+      volumes,
+      cmd,
+      skipFullBuild,
+      pullBundle,
+    }) {
       if (!cmd)
-        cmd = [
-          `npm install -g npm@11.2.0`,
-          `npm install -g underpost`,
-          `underpost secret underpost --create-from-env`,
-          `underpost start --build --run ${deployId} ${env}`,
-        ];
+        cmd =
+          pullBundle || skipFullBuild
+            ? [
+                // When pullBundle (or skipFullBuild) is set the container pulls the pre-built client
+                // bundle from Cloudinary (push-bundle must have been run on the dev machine beforehand).
+                `underpost secret underpost --create-from-env`,
+                `underpost start --build --run --pull-bundle --skip-full-build ${deployId} ${env}`,
+              ]
+            : [
+                // `npm install -g npm@11.2.0`,
+                // `npm install -g underpost`,
+                `underpost secret underpost --create-from-env`,
+                `underpost start --build --run ${deployId} ${env}`,
+              ];
       const packageJson = JSON.parse(fs.readFileSync('./package.json', 'utf8'));
       if (!volumes) volumes = [];
       const confVolume = fs.existsSync(`./engine-private/conf/${deployId}/conf.volume.json`)
         ? JSON.parse(fs.readFileSync(`./engine-private/conf/${deployId}/conf.volume.json`, 'utf8'))
         : [];
       volumes = volumes.concat(confVolume);
-      const containerImage = image ? image : `localhost/rockylinux9-underpost:v${packageJson.version}`;
+      // const containerImage = image ? image : `localhost/rockylinux9-underpost:v${packageJson.version}`;
+      const containerImage = image ? image : `underpost/underpost-engine:v${packageJson.version}`;
       return `apiVersion: apps/v1
 kind: Deployment
 metadata:
@@ -164,6 +188,7 @@ spec:
       containers:
         - name: ${deployId}-${env}-${suffix}
           image: ${containerImage}
+          imagePullPolicy: ${containerImage.startsWith('localhost/') ? 'Never' : 'IfNotPresent'}
           envFrom:
             - secretRef:
                 name: underpost-config
@@ -221,6 +246,8 @@ spec:
      * @param {string} [options.retryPerTryTimeout] - Retry per-try timeout setting for the deployment.
      * @param {boolean} [options.disableDeploymentProxy] - Whether to disable deployment proxy.
      * @param {string} [options.traffic] - Traffic status for the deployment.
+     * @param {boolean} [options.skipFullBuild] - Whether to skip the full client bundle build; forwarded to deploymentYamlPartsFactory to generate a pull-bundle startup command.
+     * @param {boolean} [options.pullBundle] - Whether to pull the pre-built client bundle from Cloudinary; forwarded to deploymentYamlPartsFactory. Use together with skipFullBuild.
      * @returns {Promise<void>} - Promise that resolves when the manifest is built.
      * @memberof UnderpostDeploy
      */
@@ -257,6 +284,8 @@ ${Underpost.deploy
     image,
     namespace: options.namespace,
     cmd: options.cmd ? options.cmd.split(',').map((c) => c.trim()) : undefined,
+    skipFullBuild: options.skipFullBuild,
+    pullBundle: options.pullBundle,
   })
   .replace('{{ports}}', buildKindPorts(fromPort, toPort))}
 `;
@@ -550,10 +579,13 @@ spec:
      * @param {string} [options.kindType] - Type of Kubernetes resource to retrieve information for.
      * @param {number} [options.port] - Port number for exposing the deployment.
      * @param {string} [options.cmd] - Custom initialization command for deploymentYamlPartsFactory (comma-separated commands).
+     * @param {number} [options.exposePort] - Local:remote port override when --expose is active (overrides auto-detected service port).
      * @param {boolean} [options.k3s] - Whether to use k3s cluster context.
      * @param {boolean} [options.kubeadm] - Whether to use kubeadm cluster context.
      * @param {boolean} [options.kind] - Whether to use kind cluster context.
      * @param {boolean} [options.gitClean] - Whether to run git clean on volume mount paths before copying.
+     * @param {boolean} [options.skipFullBuild] - Whether to skip the full client bundle build; passed through to buildManifest/deploymentYamlPartsFactory.
+     * @param {boolean} [options.pullBundle] - Whether to pull the pre-built client bundle from Cloudinary; passed through to buildManifest/deploymentYamlPartsFactory. Use together with skipFullBuild.
      * @returns {Promise<void>} - Promise that resolves when the deployment process is complete.
      * @memberof UnderpostDeploy
      */
@@ -624,6 +656,8 @@ EOF`);
                 path: instance.path,
                 fromPort: instance.fromPort,
                 toPort: instance.toPort,
+                fromDebugPort: instance.fromDebugPort,
+                toDebugPort: instance.toDebugPort,
                 traffic: Underpost.deploy.getCurrentTraffic(_deployId, { namespace, hostTest: instance.host }),
               });
             }
@@ -801,9 +835,10 @@ EOF`);
      * @memberof UnderpostDeploy
      */
     configMap(env, namespace = 'default') {
+      const cronDeployId = cronDeployIdResolve() || 'dd-cron';
       shellExec(`kubectl delete secret underpost-config -n ${namespace} --ignore-not-found`);
       shellExec(
-        `kubectl create secret generic underpost-config --from-env-file=/home/dd/engine/engine-private/conf/dd-cron/.env.${env} --dry-run=client -o yaml | kubectl apply -f - -n ${namespace}`,
+        `kubectl create secret generic underpost-config --from-env-file=/home/dd/engine/engine-private/conf/${cronDeployId}/.env.${env} --dry-run=client -o yaml | kubectl apply -f - -n ${namespace}`,
       );
     },
     /**
@@ -1092,11 +1127,10 @@ ${renderHosts}`,
      * @param {string} targetTraffic - Target traffic status for the deployment.
      * @param {Array<string>} ignorePods - List of pod names to ignore.
      * @param {string} [namespace='default'] - Kubernetes namespace for the deployment.
-     * @param {string} [outLogType=''] - Type of log output.
      * @returns {object} - Object containing the ready status of the deployment.
      * @memberof UnderpostDeploy
      */
-    async monitorReadyRunner(deployId, env, targetTraffic, ignorePods = [], namespace = 'default', outLogType = '') {
+    async monitorReadyRunner(deployId, env, targetTraffic, ignorePods = [], namespace = 'default') {
       let checkStatusIteration = 0;
       const checkStatusIterationMsDelay = 1000;
       const maxIterations = 3000;
@@ -1134,32 +1168,30 @@ ${renderHosts}`,
           }
         }
 
-        switch (outLogType) {
-          case 'underpost': {
-            let indexOf = -1;
-            for (const pod of result.notReadyPods) {
-              indexOf++;
-              const { NAME, out } = pod;
+        {
+          let indexOf = -1;
+          for (const pod of result.notReadyPods) {
+            indexOf++;
+            const { NAME, out } = pod;
 
-              if (out.match('not') && out.match('found') && checkStatusIteration <= 20 && out.match(deploymentId))
-                lastMsg[NAME] = 'Starting deployment';
-              else if (out.match('not') && out.match('found') && checkStatusIteration <= 20 && out.match('underpost'))
-                lastMsg[NAME] = 'Installing underpost cli';
-              else if (out.match('not') && out.match('found') && checkStatusIteration <= 20 && out.match('task'))
-                lastMsg[NAME] = 'Initializing setup task';
-              else if (out.match('Empty environment variables')) lastMsg[NAME] = 'Setup environment';
-              else if (out.match(`${deployId}-${env}-build-deployment`)) lastMsg[NAME] = 'Building apps/services';
-              else if (out.match(`${deployId}-${env}-initializing-deployment`))
-                lastMsg[NAME] = 'Initializing apps/services';
-              else if (!lastMsg[NAME]) lastMsg[NAME] = `Waiting for status`;
+            if (out.match('not') && out.match('found') && checkStatusIteration <= 20 && out.match(deploymentId))
+              lastMsg[NAME] = 'Starting deployment';
+            // else if (out.match('not') && out.match('found') && checkStatusIteration <= 20 && out.match('underpost'))
+            //   lastMsg[NAME] = 'Installing underpost cli';
+            else if (out.match('not') && out.match('found') && checkStatusIteration <= 20 && out.match('task'))
+              lastMsg[NAME] = 'Initializing setup task';
+            else if (out.match('Empty environment variables')) lastMsg[NAME] = 'Setup environment';
+            else if (out.match(`${deployId}-${env}-build-deployment`)) lastMsg[NAME] = 'Building apps/services';
+            else if (out.match(`${deployId}-${env}-initializing-deployment`))
+              lastMsg[NAME] = 'Initializing apps/services';
+            else if (!lastMsg[NAME]) lastMsg[NAME] = `Waiting for status`;
 
-              console.log(
-                'Target pod:',
-                NAME[NAME.match('green') ? 'bgGreen' : 'bgBlue'].bold.black,
-                '| Status:',
-                lastMsg[NAME].bold.magenta,
-              );
-            }
+            console.log(
+              'Target pod:',
+              NAME[NAME.match('green') ? 'bgGreen' : 'bgBlue'].bold.black,
+              '| Status:',
+              lastMsg[NAME].bold.magenta,
+            );
           }
         }
         await timer(checkStatusIterationMsDelay);

package/src/cli/fs.js

@@ -75,6 +75,7 @@ class UnderpostFileStorage {
      * @param {boolean} [options.force=false] - Flag to force file operations.
      * @param {boolean} [options.pull=false] - Flag to pull files from storage.
      * @param {boolean} [options.git=false] - Flag to use Git for file operations.
+     * @param {boolean} [options.omitUnzip=false] - If true, do not extract zip and keep downloaded zip file.
      * @param {string} [options.storageFilePath=''] - The path to the storage configuration file.
      * @returns {Promise<void>} A promise that resolves when the recursive callback is complete.
      * @memberof UnderpostFileStorage
@@ -88,10 +89,50 @@ class UnderpostFileStorage {
         force: false,
         pull: false,
         git: false,
+        omitUnzip: false,
         storageFilePath: '',
       },
     ) {
       const { storage, storageConf } = Underpost.fs.getStorageConf(options);
+
+      // In recursive remove mode, delete every tracked storage key under the requested path,
+      // even when local files/directories are already missing.
+      if (options.rm === true) {
+        const normalizedPath = typeof path === 'string' ? path.trim() : '';
+        const basePath = normalizedPath.replace(/\/+$/, '');
+        const hasPathFilter = basePath.length > 0;
+
+        const associatedPaths = Object.keys(storage || {}).filter((storedPath) => {
+          if (!hasPathFilter) return true;
+          return storedPath === basePath || storedPath.startsWith(`${basePath}/`);
+        });
+
+        for (const associatedPath of associatedPaths) {
+          await Underpost.fs.delete(associatedPath);
+          if (storage) delete storage[associatedPath];
+        }
+
+        if (hasPathFilter && options.force === true && fs.existsSync(basePath)) fs.removeSync(basePath);
+
+        Underpost.fs.writeStorageConf(storage, storageConf);
+
+        if (associatedPaths.length === 0)
+          logger.warn('No associated tracked storage paths found', { path: hasPathFilter ? basePath : '*' });
+        else
+          logger.info('Removed associated tracked storage paths', {
+            path: hasPathFilter ? basePath : '*',
+            removed: associatedPaths.length,
+          });
+
+        if (options.git === true) {
+          const gitPath = hasPathFilter ? basePath : '.';
+          shellExec(`cd ${gitPath} && git add .`);
+          shellExec(`underpost cmt ${gitPath} feat`);
+        }
+
+        return;
+      }
+
       const deleteFiles = options.pull === true ? [] : Underpost.repo.getDeleteFiles(path);
       for (const relativePath of deleteFiles) {
         const _path = path + '/' + relativePath;
@@ -109,8 +150,12 @@ class UnderpostFileStorage {
           } else pullSkipCount++;
         }
         if (pullSkipCount > 0) logger.warn(`Pull skipped ${pullSkipCount} files that already exist`);
-        Underpost.repo.initLocalRepo({ path });
-        shellExec(`cd ${path} && git add . && git commit -m "Base pull state"`);
+        // Only run git init/commit when the caller explicitly requests git tracking (--git flag).
+        // For bundle pulls into ./build the git step is unwanted and would error on a non-repo path.
+        if (options.git === true) {
+          Underpost.repo.initLocalRepo({ path });
+          shellExec(`cd ${path} && git add . && git commit -m "Base pull state"`);
+        }
       } else {
         const files =
           options.git === true ? Underpost.repo.getChangedFiles(path) : await fs.readdir(path, { recursive: true });
@@ -143,12 +188,13 @@ class UnderpostFileStorage {
      * @param {boolean} [options.force=false] - Flag to force file operations.
      * @param {boolean} [options.pull=false] - Flag to pull files from storage.
      * @param {boolean} [options.git=false] - Flag to use Git for file operations.
+     * @param {boolean} [options.omitUnzip=false] - If true, do not extract zip and keep downloaded zip file.
      * @returns {Promise<void>} A promise that resolves when the callback is complete.
      * @memberof UnderpostFileStorage
      */
     async callback(
       path,
-      options = { rm: false, recursive: false, deployId: '', force: false, pull: false, git: false },
+      options = { rm: false, recursive: false, deployId: '', force: false, pull: false, git: false, omitUnzip: false },
     ) {
       if (options.recursive === true || options.git === true)
         return await Underpost.fs.recursiveCallback(path, options);
@@ -161,11 +207,13 @@ class UnderpostFileStorage {
      * @description Uploads a file to Cloudinary.
      * @param {string} path - The path to the file to upload.
      * @param {object} [options] - An object containing options for the upload.
-     * @param {boolean} [options.force=false] - Flag to force file operations.
+     * @param {string} [options.deployId=''] - The identifier for the deployment (used to locate the storage config file).
+     * @param {boolean} [options.force=false] - Flag to force file operations (overwrites existing remote asset).
      * @param {string} [options.storageFilePath=''] - The path to the storage configuration file.
      * @returns {Promise<object>} A promise that resolves to the upload result.
      * @memberof UnderpostFileStorage
      */
+
     async upload(
       path,
       options = { rm: false, recursive: false, deployId: '', force: false, pull: false, storageFilePath: '' },
@@ -191,22 +239,45 @@ class UnderpostFileStorage {
      * @method pull
      * @description Pulls a file from Cloudinary.
      * @param {string} path - The path to the file to pull.
+     * @param {object} [options] - Pull options.
+     * @param {boolean} [options.omitUnzip=false] - If true, do not extract zip and keep downloaded zip file.
+     * @param {boolean} [options.force=false] - If true, re-download even if the local zip already exists.
      * @returns {Promise<void>} A promise that resolves when the file is pulled.
      * @memberof UnderpostFileStorage
      */
-    async pull(path) {
+    async pull(path, options = { omitUnzip: false, force: false }) {
       Underpost.fs.cloudinaryConfig();
       const folder = dir.dirname(path);
       if (!fs.existsSync(folder)) fs.mkdirSync(folder, { recursive: true });
+      const zipPath = `${path}.zip`;
+
+      if (options.omitUnzip === true && options.force !== true && fs.existsSync(zipPath)) {
+        logger.warn('pull skipped, zip already exists and omit-unzip is enabled', { path, zipPath });
+        return;
+      }
+
       const downloadResult = await cloudinary.utils.download_archive_url({
         public_ids: [path],
         resource_type: 'raw',
       });
       logger.info('download result', downloadResult);
-      await Downloader.downloadFile(downloadResult, path + '.zip');
-      path = Underpost.fs.zip2File(path + '.zip');
-      fs.removeSync(path + '.zip');
+      await Downloader.downloadFile(downloadResult, zipPath);
+
+      if (options.omitUnzip === true) {
+        logger.warn('omit unzip enabled, keeping downloaded zip file', { path, zipPath });
+        return;
+      }
+
+      path = Underpost.fs.zip2File(zipPath);
+      fs.removeSync(`${path}.zip`);
     },
+    /**
+     * @method delete
+     * @description Deletes a file from Cloudinary by its public ID.
+     * @param {string} path - The path (public ID) of the file to delete.
+     * @returns {Promise<object>} A promise that resolves to the Cloudinary delete result.
+     * @memberof UnderpostFileStorage
+     */
     async delete(path) {
       Underpost.fs.cloudinaryConfig();
       const deleteResult = await cloudinary.api

package/src/cli/image.js

@@ -99,6 +99,7 @@ class UnderpostImage {
       if (!path) path = '.';
       if (!imageName) imageName = `rockylinux9-underpost:${Underpost.version}`;
       if (!imagePath) imagePath = '.';
+      if (imageName.match('/')) imageName = imageName.split('/')[1];
       if (!version) version = 'latest';
       version = imageName && imageName.match(':') ? '' : `:${version}`;
       const podManImg = `localhost/${imageName}${version}`;
@@ -178,6 +179,12 @@ class UnderpostImage {
      * @memberof UnderpostImage
      */
     pullDockerHubImage(options = { k3s: false, kubeadm: false, kind: false, dockerhubImage: '', version: '' }) {
+      if (options.dockerhubImage && options.dockerhubImage.startsWith('localhost')) {
+        logger.warn(`[image] pullDockerHubImage skipped — local image cannot be pulled from Docker Hub`, {
+          dockerhubImage: options.dockerhubImage,
+        });
+        return;
+      }
       if (options.dockerhubImage === 'underpost') {
         options.dockerhubImage = 'underpost/underpost-engine';
         if (!options.version) options.version = Underpost.version;
@@ -185,7 +192,42 @@ class UnderpostImage {
       if (!options.version) options.version = 'latest';
       const version = options.dockerhubImage && options.dockerhubImage.match(':') ? '' : `:${options.version}`;
       const image = `${options.dockerhubImage}${version}`;
-      if (options.kind === true) {
+      const targetKind = options.kind === true;
+      const targetK3s = options.k3s === true;
+      const targetKubeadm = options.kubeadm === true || (!targetKind && !targetK3s);
+
+      const requestedRepo = image.replace(/:[^/]+$/, '');
+      const requestedTag = image.match(/:([^/]+)$/)?.[1] || 'latest';
+      const normalizeRepo = (repo = '') =>
+        repo
+          .trim()
+          .replace(/^localhost\//, '')
+          .replace(/^docker\.io\//, '')
+          .replace(/^library\//, '');
+
+      const currentImages = UnderpostImage.API.list({
+        kind: targetKind,
+        kubeadm: targetKubeadm,
+        k3s: targetK3s,
+        log: false,
+      });
+
+      const existsInCluster = currentImages.some((row) => {
+        const rowImageRaw = String(row.IMAGE || row.image || '').trim();
+        if (!rowImageRaw) return false;
+        const rowImage = rowImageRaw.replace(/:[^/]+$/, '');
+        const rowTag = String(row.TAG || rowImageRaw.match(/:([^/]+)$/)?.[1] || '').trim();
+        return normalizeRepo(rowImage) === normalizeRepo(requestedRepo) && rowTag === requestedTag;
+      });
+
+      if (existsInCluster) {
+        logger.info(`[image] pull skipped. Image already loaded`, {
+          image,
+          clusterType: targetKind ? 'kind' : targetK3s ? 'k3s' : 'kubeadm',
+        });
+        return;
+      }
+      if (targetKind) {
         shellExec(`docker pull ${image}`);
         shellExec(`sudo kind load docker-image ${image}`);
       } else {