underpost 3.2.8 → 3.2.10

package/src/cli/deploy.js

@@ -78,8 +78,7 @@ class UnderpostDeploy {
       return `
     - conditions:
         - prefix: ${path}
-      ${
-        pathRewritePolicy
+      ${pathRewritePolicy
           ? `pathRewritePolicy:
           replacePrefix:
           ${pathRewritePolicy.map(
@@ -89,30 +88,26 @@ class UnderpostDeploy {
           ).join(`
 `)}`
           : ''
-      }${
-        timeoutPolicy
-          ? `\n      timeoutPolicy:\n${timeoutPolicy.response ? `        response: ${timeoutPolicy.response}\n` : ''}${
-              timeoutPolicy.idle ? `        idle: ${timeoutPolicy.idle}\n` : ''
-            }`
+        }${timeoutPolicy
+          ? `\n      timeoutPolicy:\n${timeoutPolicy.response ? `        response: ${timeoutPolicy.response}\n` : ''}${timeoutPolicy.idle ? `        idle: ${timeoutPolicy.idle}\n` : ''
+          }`
           : ''
-      }${
-        retryPolicy
-          ? `\n      retryPolicy:\n${retryPolicy.count !== undefined ? `        count: ${retryPolicy.count}\n` : ''}${
-              retryPolicy.perTryTimeout ? `        perTryTimeout: ${retryPolicy.perTryTimeout}\n` : ''
-            }`
+        }${retryPolicy
+          ? `\n      retryPolicy:\n${retryPolicy.count !== undefined ? `        count: ${retryPolicy.count}\n` : ''}${retryPolicy.perTryTimeout ? `        perTryTimeout: ${retryPolicy.perTryTimeout}\n` : ''
+          }`
           : ''
-      }
+        }
       enableWebsockets: true
       services:
     ${deploymentVersions
-      .map(
-        (version, i) =>
-          `    - name: ${serviceId ? serviceId : `${deployId}-${env}-${version}-service`}
+          .map(
+            (version, i) =>
+              `    - name: ${serviceId ? serviceId : `${deployId}-${env}-${version}-service`}
           port: ${port}
           weight: ${i === 0 ? 100 : 0}
     `,
-      )
-      .join('')}`;
+          )
+          .join('')}`;
     },
     /**
      * Creates a YAML deployment configuration for a deployment.
@@ -125,17 +120,51 @@ 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.
+     * @param {string} [imagePullPolicy] - Container imagePullPolicy override (`Always`, `IfNotPresent`, `Never`). When omitted, defaults to `Never` for `localhost/` images and `IfNotPresent` otherwise.
      * @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,
+      imagePullPolicy,
+      // K8S lifecycle + probe wiring. Pass-through structures shaped like the
+      // upstream Kubernetes API, spliced verbatim into the container spec.
+      //   lifecycle:        { postStart: { exec: { command: [...] } }, preStop: { exec: { command: [...] } } }
+      //   readinessProbe:   { tcpSocket: { port: 8081 }, ... }
+      //   livenessProbe:    { tcpSocket: { port: 8081 }, ... }
+      //   containerPort:    integer; rendered as ports[0].containerPort. Optional.
+      lifecycle,
+      readinessProbe,
+      livenessProbe,
+      containerPort,
+    }) {
       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`)
@@ -166,36 +195,64 @@ spec:
       containers:
         - name: ${deployId}-${env}-${suffix}
           image: ${containerImage}
-          imagePullPolicy: ${containerImage.startsWith('localhost/') ? 'Never' : 'IfNotPresent'}
+          imagePullPolicy: ${imagePullPolicy ? imagePullPolicy : containerImage.startsWith('localhost/') ? 'Never' : 'IfNotPresent'}
           envFrom:
             - secretRef:
                 name: underpost-config
-${
-  resources
-    ? `          resources:
+${containerPort
+          ? `          ports:
+            - containerPort: ${containerPort}
+`
+          : ''
+        }${resources
+          ? `          resources:
             requests:
               memory: "${resources.requests.memory}"
               cpu: "${resources.requests.cpu}"
             limits:
               memory: "${resources.limits.memory}"
               cpu: "${resources.limits.cpu}"`
-    : ''
-}
+          : ''
+        }
           command:
             - /bin/sh
             - -c
             - >
               ${cmd.join(' &&\n              ')}
+${readinessProbe
+          ? `          readinessProbe:
+${JSON.stringify(readinessProbe, null, 2)
+            .split('\n')
+            .map((l) => '            ' + l)
+            .join('\n')}
+`
+          : ''
+        }${livenessProbe
+          ? `          livenessProbe:
+${JSON.stringify(livenessProbe, null, 2)
+            .split('\n')
+            .map((l) => '            ' + l)
+            .join('\n')}
+`
+          : ''
+        }${lifecycle
+          ? `          lifecycle:
+${JSON.stringify(lifecycle, null, 2)
+            .split('\n')
+            .map((l) => '            ' + l)
+            .join('\n')}
+`
+          : ''
+        }
 
-${
-  volumes.length > 0
-    ? Underpost.deploy
-        .volumeFactory(volumes.map((v) => ((v.version = `${deployId}-${env}-${suffix}`), v)))
-        .render.split(`\n`)
-        .map((l) => '    ' + l)
-        .join(`\n`)
-    : ''
-}
+${volumes.length > 0
+          ? Underpost.deploy
+            .volumeFactory(volumes.map((v) => ((v.version = `${deployId}-${env}-${suffix}`), v)))
+            .render.split(`\n`)
+            .map((l) => '    ' + l)
+            .join(`\n`)
+          : ''
+        }
 ---
 apiVersion: v1
 kind: Service
@@ -224,6 +281,9 @@ 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.
+     * @param {string} [options.imagePullPolicy] - Container imagePullPolicy override (`Always`, `IfNotPresent`, `Never`); forwarded to deploymentYamlPartsFactory. When omitted, the builder defaults to `Never` for `localhost/` images and `IfNotPresent` otherwise.
      * @returns {Promise<void>} - Promise that resolves when the manifest is built.
      * @memberof UnderpostDeploy
      */
@@ -252,16 +312,19 @@ spec:
         for (const deploymentVersion of deploymentVersions) {
           deploymentYamlParts += `---
 ${Underpost.deploy
-  .deploymentYamlPartsFactory({
-    deployId,
-    env,
-    suffix: deploymentVersion,
-    replicas,
-    image,
-    namespace: options.namespace,
-    cmd: options.cmd ? options.cmd.split(',').map((c) => c.trim()) : undefined,
-  })
-  .replace('{{ports}}', buildKindPorts(fromPort, toPort))}
+              .deploymentYamlPartsFactory({
+                deployId,
+                env,
+                suffix: deploymentVersion,
+                replicas,
+                image,
+                namespace: options.namespace,
+                cmd: options.cmd ? options.cmd.split(',').map((c) => c.trim()) : undefined,
+                skipFullBuild: options.skipFullBuild,
+                pullBundle: options.pullBundle,
+                imagePullPolicy: options.imagePullPolicy,
+              })
+              .replace('{{ports}}', buildKindPorts(fromPort, toPort))}
 `;
         }
         fs.writeFileSync(`./engine-private/conf/${deployId}/build/${env}/deployment.yaml`, deploymentYamlParts, 'utf8');
@@ -313,20 +376,20 @@ ${Underpost.deploy
           let proxyRoutes = '';
           const globalTimeoutPolicy =
             (options.timeoutResponse && options.timeoutResponse !== '') ||
-            (options.timeoutIdle && options.timeoutIdle !== '')
+              (options.timeoutIdle && options.timeoutIdle !== '')
               ? {
-                  response: options.timeoutResponse,
-                  idle: options.timeoutIdle,
-                }
+                response: options.timeoutResponse,
+                idle: options.timeoutIdle,
+              }
               : undefined;
           const globalRetryPolicy =
             options.retryCount ||
-            options.retryCount === 0 ||
-            (options.retryPerTryTimeout && options.retryPerTryTimeout !== '')
+              options.retryCount === 0 ||
+              (options.retryPerTryTimeout && options.retryPerTryTimeout !== '')
               ? {
-                  count: options.retryCount,
-                  perTryTimeout: options.retryPerTryTimeout,
-                }
+                count: options.retryCount,
+                perTryTimeout: options.retryPerTryTimeout,
+              }
               : undefined;
           if (!options.disableDeploymentProxy)
             for (const conditionObj of pathPortAssignment) {
@@ -483,10 +546,15 @@ spec:
       const hostTest = options?.hostTest
         ? options.hostTest
         : Object.keys(loadConfServerJson(`./engine-private/conf/${deployId}/conf.server.json`))[0];
+      // Missing HTTPProxy is the canonical "no traffic colour set yet" state
+      // for blue/green rollouts. silentOnError swallows kubectl's NotFound
+      // exit so the function can return null cleanly.
       const info = shellExec(`sudo kubectl get HTTPProxy/${hostTest} -n ${options.namespace} -o yaml`, {
         silent: true,
         stdout: true,
+        silentOnError: true,
       });
+      if (!info) return null;
       return info.match('blue') ? 'blue' : info.match('green') ? 'green' : null;
     },
 
@@ -509,13 +577,12 @@ metadata:
   namespace: ${options.namespace}
 spec:
   virtualhost:
-    fqdn: ${host}${
-      env === 'development'
-        ? ''
-        : `
+    fqdn: ${host}${env === 'development'
+          ? ''
+          : `
     tls:
       secretName: ${host}`
-    }
+        }
   routes:`;
     },
 
@@ -553,10 +620,14 @@ 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.
+     * @param {string} [options.imagePullPolicy] - Container imagePullPolicy override (`Always`, `IfNotPresent`, `Never`); passed through to buildManifest/deploymentYamlPartsFactory. When omitted, the builder defaults to `Never` for `localhost/` images and `IfNotPresent` otherwise.
      * @returns {Promise<void>} - Promise that resolves when the deployment process is complete.
      * @memberof UnderpostDeploy
      */
@@ -598,6 +669,7 @@ spec:
         kubeadm: false,
         kind: false,
         gitClean: false,
+        imagePullPolicy: '',
       },
     ) {
       const namespace = options.namespace ? options.namespace : 'default';
@@ -772,25 +844,41 @@ EOF`);
      * @memberof UnderpostDeploy
      */
     async checkDeploymentReadyStatus(deployId, env, traffic, ignoresNames = [], namespace = 'default') {
-      const cmd = `underpost config get container-status`;
       const pods = Underpost.kubectl.get(`${deployId}-${env}-${traffic}`, 'pods', namespace);
       const readyPods = [];
       const notReadyPods = [];
+
+      // Readiness signal: the pod's Kubernetes `Ready` condition driven by the
+      // container's readinessProbe (TCP socket, HTTP get, or exec). Set by kubelet
+      // when the probe passes. A failed or crashing runtime never becomes Ready —
+      // kubelet surfaces CrashLoopBackOff and this gate stays closed.
       for (const pod of pods) {
         const { NAME } = pod;
         if (ignoresNames && ignoresNames.find((t) => NAME.trim().toLowerCase().match(t.trim().toLowerCase()))) continue;
-        const out = await new Promise((resolve) => {
-          shellExec(`sudo kubectl exec -i ${NAME} -n ${namespace} -- sh -c "${cmd}"`, {
+
+        let podJson = null;
+        try {
+          // Pod may not exist yet (between deployment apply and pod
+          // scheduling). silentOnError lets the monitor loop continue
+          // instead of aborting on the transient NotFound exit.
+          const raw = shellExec(`sudo kubectl get pod ${NAME} -n ${namespace} -o json`, {
             silent: true,
             disableLog: true,
-            callback: function (code, stdout, stderr) {
-              return resolve(JSON.stringify({ code, stdout, stderr }));
-            },
+            stdout: true,
+            silentOnError: true,
           });
-        });
-        pod.out = out;
-        const ready = out.match(`${deployId}-${env}-running-deployment`);
-        ready ? readyPods.push(pod) : notReadyPods.push(pod);
+          podJson = raw ? JSON.parse(raw) : null;
+        } catch (_) {
+          podJson = null;
+        }
+        const conditions = podJson?.status?.conditions || [];
+        const readyCondition = conditions.find((c) => c.type === 'Ready');
+        const k8sReady = readyCondition?.status === 'True';
+
+        pod.out = JSON.stringify({ k8sReady, condition: readyCondition ?? null });
+
+        if (k8sReady) readyPods.push(pod);
+        else notReadyPods.push(pod);
       }
       return {
         ready: pods.length > 0 && notReadyPods.length === 0,
@@ -824,6 +912,7 @@ EOF`);
      * @param {string} options.timeoutIdle - Timeout idle setting for the deployment.
      * @param {string} options.retryCount - Retry count setting for the deployment.
      * @param {string} options.retryPerTryTimeout - Retry per-try timeout setting for the deployment.
+     * @param {string} [options.imagePullPolicy] - Container imagePullPolicy override; forwarded to the manifest rebuild triggered here.
      * @memberof UnderpostDeploy
      */
     switchTraffic(
@@ -837,12 +926,14 @@ EOF`);
         timeoutIdle: '',
         retryCount: '',
         retryPerTryTimeout: '',
+        imagePullPolicy: '',
       },
     ) {
       const timeoutFlags = Underpost.deploy.timeoutFlagsFactory(options);
+      const imagePullPolicyFlag = options.imagePullPolicy ? ` --image-pull-policy ${options.imagePullPolicy}` : '';
 
       shellExec(
-        `node bin deploy --info-router --build-manifest --traffic ${targetTraffic} --replicas ${replicas} --namespace ${namespace}${timeoutFlags} ${deployId} ${env}`,
+        `node bin deploy --info-router --build-manifest --traffic ${targetTraffic} --replicas ${replicas} --namespace ${namespace}${timeoutFlags}${imagePullPolicyFlag} ${deployId} ${env}`,
       );
 
       shellExec(`sudo kubectl apply -f ./engine-private/conf/${deployId}/build/${env}/proxy.yaml -n ${namespace}`);
@@ -911,10 +1002,10 @@ EOF`);
       shellExec(`kubectl delete pv ${pvId} --ignore-not-found`);
       shellExec(`kubectl apply -f - -n ${namespace} <<EOF
 ${Underpost.deploy.persistentVolumeFactory({
-  hostPath: rootVolumeHostPath,
-  pvcId,
-  namespace,
-})}
+        hostPath: rootVolumeHostPath,
+        pvcId,
+        namespace,
+      })}
 EOF
 `);
     },
@@ -973,23 +1064,22 @@ ${secret ? `          readOnly: true\n` : ''}`;
 
         _volumes += `
     - name: ${volumeName}
- ${
-   emptyDir
-     ? `     emptyDir: {}`
-     : secret
-       ? `     secret:
+ ${emptyDir
+            ? `     emptyDir: {}`
+            : secret
+              ? `     secret:
         secretName: ${secret}`
-       : configMap
-         ? `     configMap:
+              : configMap
+                ? `     configMap:
         name: ${configMap}`
-         : claimName
-           ? `     persistentVolumeClaim:
+                : claimName
+                  ? `     persistentVolumeClaim:
         claimName: ${claimName}`
-           : `     hostPath:
+                  : `     hostPath:
         path: ${volumeHostPath}
         type: ${volumeType}
 `
- }
+          }
 
   `;
       });
@@ -1070,7 +1160,7 @@ spec:
         fs.writeFileSync(
           `/etc/hosts`,
           fs.readFileSync(`/etc/hosts`, 'utf8') +
-            `
+          `
 ${renderHosts}`,
           'utf8',
         );
@@ -1090,9 +1180,25 @@ ${renderHosts}`,
       env === 'production' &&
       options.cert === true &&
       (!options.certHosts || options.certHosts.split(',').includes(host)),
-
     /**
      * Monitors the ready status of a deployment.
+     *
+     * Ready signal:
+     *   The orchestrator gate is the Kubernetes pod Ready condition. When the
+     *   container's `readinessProbe` succeeds, kubelet flips
+     *   `status.conditions[Ready]` to True and `checkDeploymentReadyStatus`
+     *   returns the pod in `readyPods`. This is the only required signal — see
+     *   `src/client/public/nexodev/docs/references/Deploy custom instance to K8S.md`.
+     *
+     * Container-status:
+     *   `underpost config get container-status` is still read from each pod for
+     *   the display column and for early-abort on `error`, but it is no longer
+     *   required to equal `<deploy>-running-deployment` to finish the monitor.
+     *   Older implementations gated on it; that produced false timeouts for
+     *   runtimes (e.g. cyberia-server's Go binary, cyberia-client's server.py)
+     *   whose startup sequence didn't reliably overwrite the
+     *   `initializing-deployment` stamp set by the postStart lifecycle hook.
+     *
      * @param {string} deployId - Deployment ID for which the ready status is being monitored.
      * @param {string} env - Environment for which the ready status is being monitored.
      * @param {string} targetTraffic - Target traffic status for the deployment.
@@ -1102,79 +1208,88 @@ ${renderHosts}`,
      * @memberof UnderpostDeploy
      */
     async monitorReadyRunner(deployId, env, targetTraffic, ignorePods = [], namespace = 'default') {
-      let checkStatusIteration = 0;
-      const checkStatusIterationMsDelay = 1000;
+      const delayMs = 1000;
       const maxIterations = 3000;
       const deploymentId = `${deployId}-${env}-${targetTraffic}`;
-      const iteratorTag = `[${deploymentId}]`;
-      logger.info('Deployment init', { deployId, env, targetTraffic, checkStatusIterationMsDelay, namespace });
-      const minReadyOk = 3;
-      let readyOk = 0;
-      let result = {
-        ready: false,
-        notReadyPods: [],
-        readyPods: [],
-      };
-      let lastMsg = {};
-      while (readyOk < minReadyOk) {
-        if (checkStatusIteration >= maxIterations) {
-          logger.error(
-            `${iteratorTag} | Deployment check ready status timeout. Max iterations reached: ${maxIterations}`,
+      const expectedContainerStatus = `${deployId}-${env}-running-deployment`;
+      const tag = `[${deploymentId}]`;
+      const containerStatusDefault = 'waiting for status';
+
+      logger.info('Deployment init', { deployId, env, targetTraffic, namespace });
+
+      // Per-pod cache of last-known container-status (persists across retries)
+      const podStatusCache = new Map();
+
+      const readContainerStatus = (podName) => {
+        try {
+          const raw = shellExec(
+            `sudo kubectl exec ${podName} -n ${namespace} -- sh -c 'underpost config get container-status --plain'`,
+            { silent: true, disableLog: true, stdout: true, silentOnError: true },
           );
-          break;
+          const val = raw ? raw.toString().trim() : '';
+          return val && val !== 'undefined' ? val : containerStatusDefault;
+        } catch (_) {
+          // exec failed (e.g. pod not yet running) — preserve last known value
+          return podStatusCache.get(podName) || containerStatusDefault;
         }
-        result = await Underpost.deploy.checkDeploymentReadyStatus(deployId, env, targetTraffic, ignorePods, namespace);
-        if (result.ready === true) {
-          readyOk++;
-          logger.info(`${iteratorTag} | Deployment ready. Verification number: ${readyOk}`);
-          for (const pod of result.readyPods) {
-            const { NAME } = pod;
-            lastMsg[NAME] = 'Deployment ready';
-            console.log(
-              'Target pod:',
-              NAME[NAME.match('green') ? 'bgGreen' : 'bgBlue'].bold.black,
-              '| Status:',
-              lastMsg[NAME].bold.magenta,
-            );
-          }
+      };
+
+
+      for (let i = 0; i < maxIterations; i++) {
+        const result = await Underpost.deploy.checkDeploymentReadyStatus(
+          deployId, env, targetTraffic, ignorePods, namespace,
+        );
+
+        const allPods = [...result.readyPods, ...result.notReadyPods];
+
+        // Update cache with latest status for each pod (informational + error gate)
+        for (const pod of allPods) {
+          if (!pod?.NAME) continue;
+          const status = readContainerStatus(pod.NAME);
+          if (status === 'error')
+            throw new Error(`Pod ${pod.NAME} has error status`);
+          podStatusCache.set(pod.NAME, status);
         }
 
-        {
-          let indexOf = -1;
-          for (const pod of result.notReadyPods) {
-            indexOf++;
-            const { NAME, out } = pod;
+        const allPodsK8sReady = allPods.length > 0 && result.notReadyPods.length === 0;
 
-            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`;
+        // Print snapshot for every pod — annotate when container-status hasn't caught
+        // up to the K8S Ready condition (informational only; no longer gates exit).
+        for (const pod of allPods) {
+          const status = podStatusCache.get(pod.NAME) || containerStatusDefault;
+          const podStatus = pod.STATUS || 'Unknown';
+          const statusMatchesExpected = status === expectedContainerStatus;
+          const statusDisplay = statusMatchesExpected ? status : `${status} (advisory)`;
 
-            console.log(
-              'Target pod:',
-              NAME[NAME.match('green') ? 'bgGreen' : 'bgBlue'].bold.black,
-              '| Status:',
-              lastMsg[NAME].bold.magenta,
-            );
-          }
+          console.log(
+            'Target pod:',
+            pod.NAME[pod.NAME.includes('green') ? 'bgGreen' : 'bgBlue'].bold.black,
+            '| Pod status:',
+            podStatus.bold.yellow,
+            '| Runtime status:',
+            statusDisplay.bold.cyan,
+          );
+        }
+
+        // Finish as soon as every pod is K8S-Ready. The readinessProbe (TCP
+        // socket on the listening port) is the source of truth — a runtime
+        // that can't bind never reaches Ready and the monitor will time out.
+        if (allPodsK8sReady) {
+          logger.info(`${tag} | All pods Ready (K8S readinessProbe satisfied)`);
+          return result;
+        }
+
+        await timer(delayMs);
+
+        if ((i + 1) % 10 === 0) {
+          logger.info(`${tag} | In progress... iteration ${i + 1}`);
         }
-        await timer(checkStatusIterationMsDelay);
-        checkStatusIteration++;
-        logger.info(
-          `${iteratorTag} | Deployment in progress... | Delay number monitor iterations: ${checkStatusIteration}`,
-        );
       }
-      logger.info(
-        `${iteratorTag} | Deployment ready. | Total delay number monitor iterations: ${checkStatusIteration}`,
+
+      logger.error(`${tag} | Deployment timeout after ${maxIterations} iterations`);
+      throw new Error(
+        `monitorReadyRunner timeout: ${deploymentId} did not become Ready within ${maxIterations}*${delayMs}ms`,
       );
-      return result;
     },
 
     /**
@@ -1334,6 +1449,34 @@ ${renderHosts}`,
       return undefined;
     },
 
+    /**
+     * Extracts a non-standard `imagePullPolicy` key from an env-resolved
+     * instance lifecycle block (the convention used in `conf.instances.json`,
+     * where `imagePullPolicy` sits alongside `postStart`/`preStop` for
+     * per-instance ergonomics) and returns a clean lifecycle hash that is
+     * safe to splice into the K8S container spec.
+     *
+     * Returns `{ lifecycle, imagePullPolicy }`:
+     *   - `lifecycle` — the input minus `imagePullPolicy`, or `undefined` when
+     *     the resulting block is empty.
+     *   - `imagePullPolicy` — the extracted value, or `undefined` if absent.
+     *
+     * @param {object|undefined} lifecycle - Env-resolved lifecycle block
+     *   (already passed through pickEnv). May be `undefined`.
+     * @returns {{ lifecycle: (object|undefined), imagePullPolicy: (string|undefined) }}
+     * @memberof UnderpostDeploy
+     */
+    extractInstanceImagePullPolicy(lifecycle) {
+      if (!lifecycle || typeof lifecycle !== 'object' || !('imagePullPolicy' in lifecycle)) {
+        return { lifecycle, imagePullPolicy: undefined };
+      }
+      const { imagePullPolicy, ...rest } = lifecycle;
+      return {
+        lifecycle: Object.keys(rest).length > 0 ? rest : undefined,
+        imagePullPolicy,
+      };
+    },
+
     /**
      * Generates timeout flags string for deployment commands.
      * @param {object} options - Options containing timeout settings.