underpost 3.2.21 → 3.2.28

package/src/cli/fs.js

@@ -95,6 +95,17 @@ class UnderpostFileStorage {
     ) {
       const { storage, storageConf } = Underpost.fs.getStorageConf(options);
 
+      // ── Single-file handling: when path is a file (not a directory), use parent dir
+      //    as the git working directory and process just that one file. ──────────────
+      let isSingleFile = false;
+      let parentDir = path;
+      let singleFileName = '';
+      if (fs.existsSync(path) && !fs.statSync(path).isDirectory()) {
+        isSingleFile = true;
+        parentDir = dir.dirname(path);
+        singleFileName = path.split('/').pop();
+      }
+
       // 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) {
@@ -137,10 +148,15 @@ class UnderpostFileStorage {
         return;
       }
 
-      const deleteFiles = options.pull === true ? [] : Underpost.repo.getDeleteFiles(path);
+      // For single files, run getDeleteFiles against the parent directory to avoid
+      // trying to `cd` into a file.
+      const gitContextPath = isSingleFile ? parentDir : path;
+      const deleteFiles = options.pull === true ? [] : Underpost.repo.getDeleteFiles(gitContextPath);
+
+      // When processing a single file, only consider it for deletion
       for (const relativePath of deleteFiles) {
-        const _path = path + '/' + relativePath;
-        if (_path in storage) {
+        const _path = isSingleFile ? (relativePath === singleFileName ? path : null) : path + '/' + relativePath;
+        if (_path && _path in storage) {
           await Underpost.fs.delete(_path);
           delete storage[_path];
         }
@@ -157,17 +173,25 @@ class UnderpostFileStorage {
         // 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"`, {
+          Underpost.repo.initLocalRepo({ path: gitContextPath });
+          shellExec(`cd ${gitContextPath} && git add . && git commit -m "Base pull state"`, {
             silentOnError: true,
           });
         }
       } else {
-        const files =
-          options.git === true ? Underpost.repo.getChangedFiles(path) : await fs.readdir(path, { recursive: true });
+        let files;
+        if (isSingleFile) {
+          // Single file: treat the file itself as the sole item to process
+          files = [singleFileName];
+        } else {
+          files =
+            options.git === true
+              ? Underpost.repo.getChangedFiles(gitContextPath)
+              : await fs.readdir(path, { recursive: true });
+        }
         for (const relativePath of files) {
-          const _path = path + '/' + relativePath;
-          if (fs.statSync(_path).isDirectory()) {
+          const _path = isSingleFile ? path : path + '/' + relativePath;
+          if (fs.existsSync(_path) && fs.statSync(_path).isDirectory()) {
             if (options.pull === true && !fs.existsSync(_path)) fs.mkdirSync(_path, { recursive: true });
             continue;
           } else if (!(_path in storage) || options.force === true) {
@@ -178,8 +202,8 @@ class UnderpostFileStorage {
       }
       Underpost.fs.writeStorageConf(storage, storageConf);
       if (options.git === true) {
-        shellExec(`cd ${path} && git add .`);
-        shellExec(`underpost cmt ${path} feat`, {
+        shellExec(`cd ${gitContextPath} && git add .`);
+        shellExec(`underpost cmt ${gitContextPath} feat`, {
           silentOnError: true,
           silent: true,
           disableLog: true,

package/src/cli/index.js

@@ -70,6 +70,10 @@ program
     '--pull-bundle',
     'Downloads the pre-built client bundle from Cloudinary via pull-bundle before starting. Use together with --skip-full-build to skip the local build entirely.',
   )
+  .option(
+    '--private-test-repo',
+    'During --build, clone the private test source repo (engine-test-<id>) instead of the production engine-<id> repo.',
+  )
   .action(Underpost.start.callback)
   .description('Initiates application servers, build pipelines, or other defined services based on the deployment ID.');
 
@@ -727,9 +731,44 @@ program
     'Explicitly download the pre-built client bundle from Cloudinary inside the container (supported by: sync, template-deploy). Use together with --skip-full-build.',
   )
   .option('--remove', 'Remove/teardown resources')
+  .option(
+    '--test',
+    'Enables test/generic-purpose mode for the runner (e.g. use self-signed TLS instead of cert-manager).',
+  )
   .description('Runs specified scripts using various runners.')
   .action(Underpost.run.callback);
 
+program
+  .command('docker-compose')
+  .argument('[target]', 'Optional service name for --logs, --shell, --restart, or --build.')
+  .option('--install', 'Install Docker Engine and the Compose v2 plugin on RHEL/Rocky hosts.')
+  .option(
+    '--reset',
+    'Comprehensive teardown (equivalent to cluster --reset): removes all stack containers, the network, named volumes (destroys data), orphans, and generated artifacts.',
+  )
+  .option('--force', 'Force reinstall (--install), remove volumes (--down), or also drop the env-file (--reset).')
+  .option(
+    '--deploy-id <deploy-id>',
+    "Deployment to run as the app container (default: dd-default). 'dd-default' self-bootstraps a fresh engine; any other id runs the standard 'underpost start' command (mirrors src/cli/deploy.js).",
+  )
+  .option('--env <env>', 'Deployment environment for non-default deploy ids (default: development).')
+  .option('--generate', 'Render dynamic supporting files (nginx router config, env-file, app-command override).')
+  .option('--up', 'Start the full stack detached (regenerates config first).')
+  .option('--down', 'Stop and remove containers (and orphans).')
+  .option('--volumes', 'With --down, also remove named volumes (destroys persisted data).')
+  .option('--restart', 'Restart services (optionally a single [target]).')
+  .option('--build', 'With --up rebuild images; alone, rebuilds images with --no-cache.')
+  .option('--pull', 'Pull upstream images for all services.')
+  .option('--logs', 'Follow logs for all services (optionally a single [target]).')
+  .option('--status', 'Show a formatted status table of services.')
+  .option('--shell', 'Open an interactive shell in [target] (default: app).')
+  .option('--exec <subcommand>', 'General-purpose passthrough docker compose subcommand.')
+  .option('--compose-file <path>', 'Path to the compose file (default: docker-compose.yml).')
+  .option('--env-file <path>', 'Path to the compose env-file (default: docker/compose.env).')
+  .option('--nginx-conf <path>', 'Path to the generated nginx config (default: docker/nginx/default.conf).')
+  .description('General-purpose Docker Compose development pipeline (mirrors the Kubernetes dev stack).')
+  .action(Underpost.dockerCompose.callback);
+
 program
   .command('lxd')
   .argument(
@@ -848,6 +887,42 @@ program
   .option('--remove-machines <system-ids>', 'Removes baremetal machines by comma-separated system IDs, or use "all"')
   .option('--clear-discovered', 'Clears all discovered baremetal machines from the database.')
   .option('--commission', 'Init workflow for commissioning a physical machine.')
+  .option(
+    '--install-disk [device]',
+    'Explicit target install disk for Rocky deployment (e.g. /dev/nvme0n1). Omit or leave empty to auto-detect the internal disk.',
+  )
+  .option(
+    '--no-auto-install',
+    'Disables the ephemeral runtime AUTO_INSTALL fallback (controller must trigger install).',
+  )
+  .option('--no-remote-install', 'Skips the controller-side remote install orchestration over SSH.')
+  .option(
+    '--worker',
+    'Post-install infra role: join the deployed node as a Kubernetes worker (requires --control <ip>). Without this flag the node is set up as a control-plane.',
+  )
+  .option('--control <ip>', 'Control-plane IP the worker node joins (used with --worker for kubeadm infra setup).')
+  .option(
+    '--ssh-key-dir <dir>',
+    'Directory holding the SSH key pair used for commissioning/orchestration (expects <dir>/id_rsa and <dir>/id_rsa.pub). Overrides the workflow "sshKeyDir"; defaults to engine-private/deploy. Supports a leading ~.',
+  )
+  .option(
+    '--deploy-id <deploy-id>',
+    'Deployment ID whose user key pair is used for SSH (key from engine-private/conf/<deploy-id>/users/<user>/id_rsa). Same user↔deployId↔key convention as the ssh command.',
+  )
+  .option(
+    '--user <user>',
+    'SSH user paired with --deploy-id for key resolution and the login user on an existing control-plane (defaults to root). Mirrors the ssh command --user.',
+  )
+  .option(
+    '--engine-repo <url>',
+    'Custom engine repo cloned + normalized to /home/dd/engine on the node (default: <GITHUB_USERNAME>/engine).',
+  )
+  .option('--engine-branch <branch>', 'Branch of the engine repo to clone on the node.')
+  .option(
+    '--engine-private-repo <url>',
+    'Custom private repo cloned + normalized to /home/dd/engine/engine-private on the node (default: <GITHUB_USERNAME>/engine-<id>-private).',
+  )
+  .option('--engine-private-branch <branch>', 'Branch of the engine-private repo to clone on the node.')
   .option(
     '--bootstrap-http-server-run',
     'Runs a temporary bootstrap HTTP server for generic purposes such as serving iPXE scripts or ISO images during commissioning.',
@@ -888,6 +963,14 @@ program
   )
   .option('--dev', 'Sets the development context environment for baremetal operations.')
   .option('--ls', 'Lists available boot resources and machines.')
+  .option(
+    '--resume-infra-setup',
+    'Skip commissioning, OS install, and all bootstrapping; resume only the SSH-based infra setup (kubeadm join/init) on a node that already has the OS installed and is reachable via SSH.',
+  )
+  .option(
+    '--resume-join',
+    'Skip everything except the kubeadm join command. Assumes engine, Node.js, CRI-O, kubelet, and kubeadm are already installed. Only retrieves a fresh join token from the control-plane and runs kubeadm join.',
+  )
   .description(
     'Manages baremetal server operations, including installation, database setup, commissioning, and user management.',
   )

package/src/cli/kickstart.js

@@ -43,46 +43,168 @@ class UnderpostKickStart {
 
     /**
      * @method kickstartPreVariables
-     * @description Generates the variable assignments block for the %pre script.
-     * @param {object} options
-     * @param {string} [options.rootPassword]
-     * @param {string} [options.authorizedKeys]
-     * @param {string} [options.adminUsername]
+     * @description Generates the shell variable-assignment block injected at the top of the
+     * kickstart `%pre` script. These variables drive both the ephemeral commissioning runtime
+     * and the unattended disk installer in `scripts/rocky-kickstart.sh`. Passwords are emitted
+     * base64-encoded (`*_B64`) and decoded by an in-script `ks_b64d` helper; all other values
+     * are single-quote escaped so arbitrary content survives the shell/heredoc layers.
+     * @param {object} options - Variable values to bake into the `%pre` block.
+     * @param {string} [options.rootPassword=''] - root console password (base64-encoded).
+     * @param {string} [options.authorizedKeys=''] - SSH public key(s) installed as authorized_keys.
+     * @param {string} [options.adminUsername=''] - Primary (MAAS) admin user (defaults to MAAS_ADMIN_USERNAME).
+     * @param {string} [options.adminPassword=''] - Primary admin console password (defaults to rootPassword).
+     * @param {string} [options.deployUsername=''] - Optional second (deploy) admin user (e.g. admin).
+     * @param {string} [options.deployPassword=''] - Deploy user console password (defaults to rootPassword).
+     * @param {string} [options.netIp=''] - Static IPv4 for the deployed OS; empty = DHCP.
+     * @param {number} [options.netPrefix=24] - IPv4 prefix length for the static address.
+     * @param {string} [options.netGateway=''] - Default gateway for the deployed OS.
+     * @param {string} [options.netDns=''] - DNS server for the deployed OS.
+     * @param {string} [options.timezone=''] - IANA timezone configured in the deployed OS (e.g. America/Santiago).
+     * @param {string} [options.keyboardLayout=''] - Console/X11 keyboard layout for the deployed OS (e.g. es).
+     * @param {string} [options.chronyConfPath='/etc/chrony.conf'] - chrony config path written in the deployed OS.
+     * @param {string} [options.bootstrapUrl=''] - Base URL of the bootstrap HTTP server for this host (status POSTs).
+     * @param {string} [options.workflowId=''] - Workflow identifier reported in status metadata.
+     * @param {string} [options.systemId=''] - MAAS system id reported in status metadata (if known).
+     * @param {string} [options.targetHostname=''] - Hostname reported in status metadata and set on the deployed OS.
+     * @param {number} [options.sshPort=22] - SSH port the ephemeral runtime listens on.
+     * @param {string} [options.installDiskHint=''] - Optional explicit target disk (e.g. /dev/nvme0n1); empty = auto-detect.
+     * @param {boolean} [options.autoInstall=true] - When true, the ephemeral runtime self-installs after a fallback timeout if no remote trigger arrives.
      * @memberof UnderpostKickStart
-     * @returns {string}
+     * @returns {string} Newline-joined bash variable assignments.
      */
-    kickstartPreVariables: ({ rootPassword = '', authorizedKeys = '', adminUsername = '' }) => {
+    kickstartPreVariables: ({
+      rootPassword = '',
+      authorizedKeys = '',
+      adminUsername = '',
+      adminPassword = '',
+      deployUsername = '',
+      deployPassword = '',
+      netIp = '',
+      netPrefix = 24,
+      netGateway = '',
+      netDns = '',
+      timezone = '',
+      keyboardLayout = '',
+      chronyConfPath = '/etc/chrony.conf',
+      bootstrapUrl = '',
+      workflowId = '',
+      systemId = '',
+      targetHostname = '',
+      sshPort = 22,
+      installDiskHint = '',
+      autoInstall = true,
+    }) => {
       const sanitizedKeys = (authorizedKeys || '').trim();
+      // Passwords are passed base64-encoded so arbitrary characters (quotes,
+      // spaces, $, etc.) survive every shell/heredoc layer intact. base64 output
+      // never contains single quotes. Decoding tries `base64` then falls back to
+      // python3 so a minimal Anaconda environment can never yield empty passwords.
+      const b64 = (v) => Buffer.from(String(v || ''), 'utf8').toString('base64');
+      const sq = (v) => `'${String(v || '').replace(/'/g, "'\\''")}'`;
       return [
-        `ROOT_PASS='${rootPassword || ''}'`,
-        `AUTHORIZED_KEYS='${sanitizedKeys}'`,
-        `ADMIN_USER='${adminUsername || process.env.MAAS_ADMIN_USERNAME || 'maas'}'`,
+        `ks_b64d() { printf %s "$1" | base64 -d 2>/dev/null || printf %s "$1" | python3 -c 'import sys,base64;sys.stdout.buffer.write(base64.b64decode(sys.stdin.read().strip()))' 2>/dev/null; }`,
+        `ROOT_PASS_B64='${b64(rootPassword)}'`,
+        `ADMIN_PASS_B64='${b64(adminPassword || rootPassword)}'`,
+        `DEPLOY_PASS_B64='${b64(deployPassword)}'`,
+        `ROOT_PASS="$(ks_b64d "$ROOT_PASS_B64")"`,
+        `ADMIN_PASS="$(ks_b64d "$ADMIN_PASS_B64")"`,
+        `DEPLOY_PASS="$(ks_b64d "$DEPLOY_PASS_B64")"`,
+        `AUTHORIZED_KEYS=${sq(sanitizedKeys)}`,
+        `ADMIN_USER=${sq(adminUsername || process.env.MAAS_ADMIN_USERNAME || 'maas')}`,
+        `DEPLOY_USER=${sq(deployUsername)}`,
+        `NET_IP=${sq(netIp)}`,
+        `NET_PREFIX='${parseInt(netPrefix, 10) || 24}'`,
+        `NET_GATEWAY=${sq(netGateway)}`,
+        `NET_DNS=${sq(netDns)}`,
+        `TIMEZONE=${sq(timezone)}`,
+        `KEYBOARD_LAYOUT=${sq(keyboardLayout)}`,
+        `CHRONY_CONF_PATH=${sq(chronyConfPath || '/etc/chrony.conf')}`,
+        `BOOTSTRAP_URL=${sq(bootstrapUrl)}`,
+        `WORKFLOW_ID=${sq(workflowId)}`,
+        `SYSTEM_ID=${sq(systemId)}`,
+        `TARGET_HOSTNAME=${sq(targetHostname)}`,
+        `SSH_PORT='${sshPort || 22}'`,
+        `INSTALL_DISK_HINT=${sq(installDiskHint)}`,
+        `AUTO_INSTALL='${autoInstall ? '1' : '0'}'`,
       ].join('\n');
     },
 
     /**
      * @method kickstartFactory
      * @description Generates a complete kickstart configuration by combining the header,
-     * variable assignments, and the rocky-kickstart.sh script body.
-     * @param {object} options
-     * @param {string} [options.lang='en_US.UTF-8']
-     * @param {string} [options.keyboard='us']
-     * @param {string} [options.timezone='America/New_York']
-     * @param {string} [options.rootPassword]
-     * @param {string} [options.authorizedKeys]
+     * the `%pre` variable-assignment block, and the `scripts/rocky-kickstart.sh` body.
+     * @param {object} options - Kickstart generation options.
+     * @param {string} [options.lang='en_US.UTF-8'] - System language for the ephemeral runtime.
+     * @param {string} [options.keyboard='us'] - Keyboard layout for the ephemeral runtime AND the deployed OS.
+     * @param {string} [options.timezone='America/New_York'] - Timezone for the ephemeral runtime AND the deployed OS.
+     * @param {string} [options.chronyConfPath='/etc/chrony.conf'] - chrony config path written in the deployed OS.
+     * @param {string} [options.rootPassword=process.env.MAAS_ADMIN_PASS] - root console password.
+     * @param {string} [options.adminUsername=''] - Primary (MAAS) admin user created in the deployed OS.
+     * @param {string} [options.adminPassword=''] - Primary admin console password (defaults to rootPassword).
+     * @param {string} [options.deployUsername=''] - Optional second (deploy) admin user (e.g. admin).
+     * @param {string} [options.deployPassword=''] - Deploy user console password (defaults to rootPassword).
+     * @param {string} [options.netIp=''] - Static IPv4 for the deployed OS; empty = DHCP.
+     * @param {number} [options.netPrefix=24] - IPv4 prefix length for the static address.
+     * @param {string} [options.netGateway=''] - Default gateway for the deployed OS.
+     * @param {string} [options.netDns=''] - DNS server for the deployed OS.
+     * @param {string} [options.authorizedKeys=''] - SSH public key(s) installed as authorized_keys.
+     * @param {string} [options.bootstrapUrl=''] - Base URL of the bootstrap HTTP server (status POSTs).
+     * @param {string} [options.workflowId=''] - Workflow identifier reported in status metadata.
+     * @param {string} [options.systemId=''] - MAAS system id reported in status metadata (if known).
+     * @param {string} [options.targetHostname=''] - Hostname reported in status metadata and set on the deployed OS.
+     * @param {number} [options.sshPort=22] - SSH port the ephemeral runtime listens on.
+     * @param {string} [options.installDiskHint=''] - Optional explicit target disk; empty = auto-detect.
+     * @param {boolean} [options.autoInstall=true] - When true, the runtime self-installs after a fallback timeout.
      * @memberof UnderpostKickStart
-     * @returns {string}
+     * @returns {string} The full kickstart (ks.cfg) source.
      */
     kickstartFactory: ({
       lang = 'en_US.UTF-8',
       keyboard = 'us',
       timezone = 'America/New_York',
+      chronyConfPath = '/etc/chrony.conf',
       rootPassword = process.env.MAAS_ADMIN_PASS,
+      adminUsername = '',
+      adminPassword = '',
+      deployUsername = '',
+      deployPassword = '',
+      netIp = '',
+      netPrefix = 24,
+      netGateway = '',
+      netDns = '',
       authorizedKeys = '',
+      bootstrapUrl = '',
+      workflowId = '',
+      systemId = '',
+      targetHostname = '',
+      sshPort = 22,
+      installDiskHint = '',
+      autoInstall = true,
     }) => {
-      const adminUsername = process.env.MAAS_ADMIN_USERNAME || 'maas';
+      const resolvedAdminUsername = adminUsername || process.env.MAAS_ADMIN_USERNAME || 'maas';
       const header = UnderpostKickStart.API.kickstartHeader({ lang, keyboard, timezone, rootPassword });
-      const variables = UnderpostKickStart.API.kickstartPreVariables({ rootPassword, authorizedKeys, adminUsername });
+      const variables = UnderpostKickStart.API.kickstartPreVariables({
+        rootPassword,
+        authorizedKeys,
+        adminUsername: resolvedAdminUsername,
+        adminPassword,
+        deployUsername,
+        deployPassword,
+        netIp,
+        netPrefix,
+        netGateway,
+        netDns,
+        timezone,
+        keyboardLayout: keyboard,
+        chronyConfPath,
+        bootstrapUrl,
+        workflowId,
+        systemId,
+        targetHostname,
+        sshPort,
+        installDiskHint,
+        autoInstall,
+      });
 
       const scriptPath = path.resolve(__dirname, '../../scripts/rocky-kickstart.sh');
       const scriptBody = fs.readFileSync(scriptPath, 'utf8');

package/src/cli/monitor.js

@@ -378,34 +378,77 @@ class UnderpostMonitor {
       return deployStatusPort(deployId, env) ?? 3000;
     },
     /**
-     * Reads Phase-2 runtime readiness from a single pod over HTTP, tunneling
-     * through `kubectl port-forward` to the in-pod internal status endpoint.
+     * Reads Phase-2 runtime status from a single pod using the selected transport.
      *
-     * Transport failures (port-forward down, connection refused, HTTP error)
-     * are reported as `{ ok: false }` and must never be interpreted as success
-     * by callers — they are retried, not promoted. A reachable endpoint returns
-     * `{ ok: true, status }` with the normalized runtime contract value.
+     *   - `exec` (default): `kubectl exec … underpost config get container-status`
+     *     reads the env-file value. Synchronous, no background process — required
+     *     for custom instances (cyberia-server/client) and the safe choice for
+     *     CI/SSH. See `Deploy custom instance to K8S.md`.
+     *   - `http`: port-forward to the in-pod `/_internal/status` endpoint served
+     *     by the `underpost start` launcher (dd-* runtime deploys). Opt-in.
+     *
+     * Transport failures are reported as `{ ok: false }` and must never be read
+     * as success — they are retried, not promoted.
      *
      * @param {string} podName
      * @param {string} namespace
      * @param {number} internalPort
+     * @param {('http'|'exec')} [transport='exec']
      * @returns {Promise<{ok: boolean, status?: (string|null), transportError?: string}>}
      * @memberof UnderpostMonitor
      */
-    async readRuntimeStatus(podName, namespace, internalPort) {
-      // The local side of the tunnel MUST be an ephemeral free port: pinning it
-      // to internalPort collides with any host-local service on that number
-      // (e.g. a dev runtime on the same machine as the cluster), which makes
-      // port-forward fail to bind and every read return a false transport error.
+    async readRuntimeStatus(podName, namespace, internalPort, transport = 'exec') {
+      return transport === 'exec'
+        ? Underpost.monitor.readRuntimeStatusViaExec(podName, namespace)
+        : Underpost.monitor.readRuntimeStatusViaHttp(podName, namespace, internalPort);
+    },
+    /**
+     * Phase-2 read over `kubectl exec` (env-file transport). Works for any pod
+     * whose image bakes the underpost CLI — notably custom instances that stamp
+     * `container-status` from `lifecycle.postStart`/`preStop` hooks.
+     * @param {string} podName
+     * @param {string} namespace
+     * @returns {{ok: boolean, status?: (string|null), transportError?: string}}
+     * @memberof UnderpostMonitor
+     */
+    readRuntimeStatusViaExec(podName, namespace) {
+      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 },
+        );
+        const status = normalizeContainerStatus(raw ? raw.toString().trim() : '');
+        return status === undefined ? { ok: false, transportError: 'empty_status' } : { ok: true, status };
+      } catch (error) {
+        return { ok: false, transportError: error?.code || error?.message || 'exec_failed' };
+      }
+    },
+    /**
+     * Phase-2 read over `kubectl port-forward` + HTTP `/_internal/status`.
+     *
+     * The local side of the tunnel MUST be an ephemeral free port: pinning it to
+     * internalPort collides with any host-local service on that number (e.g. a
+     * dev runtime on the same machine as the cluster), making port-forward fail
+     * to bind and every read return a false transport error.
+     *
+     * @param {string} podName
+     * @param {string} namespace
+     * @param {number} internalPort
+     * @returns {Promise<{ok: boolean, status?: (string|null), transportError?: string}>}
+     * @memberof UnderpostMonitor
+     */
+    async readRuntimeStatusViaHttp(podName, namespace, internalPort) {
       const override = parseInt(process.env.UNDERPOST_PF_LOCAL_PORT);
       const localPort = Number.isNaN(override) ? await Underpost.monitor.findFreePort() : override;
       const url = `http://127.0.0.1:${localPort}${INTERNAL_STATUS_PATH}`;
       let portForward;
       try {
-        // `exec` collapses the shell so the tracked child PID is the
-        // sudo/kubectl process, letting the SIGTERM teardown reach the tunnel.
+        // `exec` makes the tracked child the sudo/kubectl process (so kill
+        // reaches it); stdio is redirected to /dev/null so the tunnel never
+        // inherits — and therefore never holds open — a CI/SSH session's pipes,
+        // which would hang the job after a successful deploy.
         portForward = shellExec(
-          `exec sudo kubectl port-forward pod/${podName} ${localPort}:${internalPort} -n ${namespace}`,
+          `exec sudo kubectl port-forward pod/${podName} ${localPort}:${internalPort} -n ${namespace} </dev/null >/dev/null 2>&1`,
           { async: true, silent: true, disableLog: true, silentOnError: true },
         );
       } catch (_) {
@@ -440,12 +483,26 @@ class UnderpostMonitor {
      * two-phase state machine.
      *
      *   Phase 1 (Kubernetes): pod `Ready` condition via `checkDeploymentReadyStatus`.
-     *   Phase 2 (Runtime):    `running-deployment` from the in-pod internal
-     *                         status endpoint, read over HTTP (`readRuntimeStatus`).
+     *   Phase 2 (Runtime):    `container-status`, read via the selected transport.
+     *
+     * Two deployment shapes are supported via `options`:
+     *   - `runtime` gate (default, dd-* deploys): the `underpost start` launcher
+     *     stamps `running-deployment`. Success requires K8S Ready AND every pod
+     *     reporting `running-deployment`.
+     *   - `kubernetes` gate (custom instances, e.g. cyberia): the runtime is a
+     *     bare binary; K8S `readinessProbe` (TCP) IS the running signal and
+     *     `container-status` is stamped to `initializing`/`stopping` by lifecycle
+     *     hooks. Success requires K8S Ready; the status read is used only for
+     *     fast `error` detection and display.
+     *
+     * Phase-2 transport defaults to `exec` (`kubectl exec`, no background
+     * process). The `http` transport (`kubectl port-forward` → `/_internal/status`)
+     * is opt-in via `options.statusTransport='http'` or
+     * `UNDERPOST_STATUS_TRANSPORT=http`; it must not be used in CI/SSH sessions
+     * where a stray tunnel can hang the job.
      *
-     * Contract:
-     *   - Success requires BOTH phases; runtime readiness is never declared
-     *     before Kubernetes readiness.
+     * Contract (both shapes):
+     *   - Runtime readiness is never declared before Kubernetes readiness.
      *   - An explicit runtime `error` (or a fatal pod status) transitions
      *     immediately to `failed` (throw → CD exit 1).
      *   - Transport failures never count as success and never advance state.
@@ -457,16 +514,27 @@ class UnderpostMonitor {
      * @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 {object} [options] - Monitoring shape.
+     * @param {('runtime'|'kubernetes')} [options.readyGate='runtime'] - Running-signal owner.
+     * @param {('http'|'exec')} [options.statusTransport='http'] - Phase-2 read transport.
      * @returns {object} - Object containing the ready status of the deployment.
      * @memberof UnderpostMonitor
      */
-    async monitorReadyRunner(deployId, env, targetTraffic, ignorePods = [], namespace = 'default') {
+    async monitorReadyRunner(deployId, env, targetTraffic, ignorePods = [], namespace = 'default', options = {}) {
       const delayMs = parseInt(process.env.UNDERPOST_MONITOR_DELAY_MS) || 1000;
       const maxIterations = parseInt(process.env.UNDERPOST_MONITOR_MAX_ITERATIONS) || 3000;
       const deploymentId = `${deployId}-${env}-${targetTraffic}`;
       const tag = `[${deploymentId}]`;
       const expectedStatus = RUNTIME_STATUS.RUNNING;
-      const internalPort = await Underpost.monitor.deployInternalPort(deployId, env);
+      const readyGate = options.readyGate === 'kubernetes' ? 'kubernetes' : 'runtime';
+      // Default to `exec`: a single synchronous `kubectl exec` read leaves no
+      // background process behind. The `http` transport spawns `kubectl
+      // port-forward` children that, if orphaned, inherit a CI/SSH session's
+      // stdio and hang the job after a successful deploy — opt in explicitly.
+      const statusTransport =
+        (options.statusTransport || process.env.UNDERPOST_STATUS_TRANSPORT) === 'http' ? 'http' : 'exec';
+      const internalPort =
+        statusTransport === 'http' ? await Underpost.monitor.deployInternalPort(deployId, env) : null;
       const podErrorStates = ['error', 'crashloopbackoff', 'oomkilled', 'imagepullbackoff', 'errimagepull'];
 
       const emit = (state, status) =>
@@ -478,7 +546,15 @@ class UnderpostMonitor {
           timestamp: new Date().toISOString(),
         });
 
-      logger.info('Deployment init', { deployId, env, targetTraffic, namespace, internalPort });
+      logger.info('Deployment init', {
+        deployId,
+        env,
+        targetTraffic,
+        namespace,
+        internalPort,
+        readyGate,
+        statusTransport,
+      });
       emit('pending');
 
       const runtimeStatusCache = new Map();
@@ -513,12 +589,12 @@ class UnderpostMonitor {
         const allPodsK8sReady = result.notReadyPods.length === 0;
         if (allPodsK8sReady) emit('pod_ready');
 
-        // Phase 2: runtime readiness over HTTP. Transport failures neither
-        // advance state nor count as success; explicit `error` is terminal.
+        // Phase 2: runtime status via the selected transport. Transport failures
+        // neither advance state nor count as success; explicit `error` is terminal.
         let allRuntimeRead = true;
         for (const pod of allPods) {
           if (!pod?.NAME) continue;
-          const read = await Underpost.monitor.readRuntimeStatus(pod.NAME, namespace, internalPort);
+          const read = await Underpost.monitor.readRuntimeStatus(pod.NAME, namespace, internalPort, statusTransport);
           if (!read.ok) {
             allRuntimeRead = false;
             emit('runtime_booting', `transport:${read.transportError}`);
@@ -526,6 +602,9 @@ class UnderpostMonitor {
           }
           const status = read.status;
           if (status === RUNTIME_STATUS.ERROR) throw new Error(`Pod ${pod.NAME} reported runtime status=error`);
+          // Regression (advanced → empty/build) means a pod restarted. Under the
+          // kubernetes gate the runtime never advances past `initializing`, so
+          // only treat a drop to empty/build as a regression there.
           if (advancedPods.has(pod.NAME) && (!status || status === RUNTIME_STATUS.BUILD))
             throw new Error(`Pod ${pod.NAME} runtime status regressed (${status ?? 'empty'}) — pod likely restarted`);
           if (status && status !== RUNTIME_STATUS.BUILD) advancedPods.add(pod.NAME);
@@ -533,8 +612,13 @@ class UnderpostMonitor {
           emit('runtime_booting', status);
         }
 
+        // Under the kubernetes gate the readinessProbe is the running signal, so
+        // K8S Ready alone confirms Phase 2; the status read above is kept only
+        // for `error` fast-fail and display.
         const allRuntimeReady =
-          allRuntimeRead && allPods.every((pod) => runtimeStatusCache.get(pod.NAME) === expectedStatus);
+          readyGate === 'kubernetes'
+            ? true
+            : allRuntimeRead && allPods.every((pod) => runtimeStatusCache.get(pod.NAME) === expectedStatus);
 
         for (const pod of allPods) {
           const status = runtimeStatusCache.get(pod.NAME) || 'waiting for status';
@@ -550,11 +634,12 @@ class UnderpostMonitor {
           );
         }
 
-        // Terminal success requires BOTH phases. runtime_ready cannot precede
+        // Terminal success requires both phases. runtime_ready cannot precede
         // Kubernetes readiness.
         if (allPodsK8sReady && allRuntimeReady) {
-          emit('runtime_ready', expectedStatus);
-          logger.info(`${tag} | Deployment ready (K8S Ready + runtime ${expectedStatus})`);
+          const readySignal = readyGate === 'kubernetes' ? 'K8S readinessProbe' : `runtime ${expectedStatus}`;
+          emit('runtime_ready', readyGate === 'kubernetes' ? 'k8s-ready' : expectedStatus);
+          logger.info(`${tag} | Deployment ready (K8S Ready + ${readySignal})`);
           return result;
         }