cyberia 3.2.9 → 3.2.22

package/scripts/lxd-vm-setup.sh

@@ -1,23 +1,208 @@
+#!/bin/bash
+set -euo pipefail
 
-echo "Expanding /dev/sda2 and resizing filesystem..."
+# ---------------------------------------------------------------------------
+# LXD VM OS base setup. Runs inside the VM via `lxc exec`. Idempotent.
+# ---------------------------------------------------------------------------
 
-if ! command -v parted &>/dev/null; then
-  sudo dnf install -y parted
+# lxdbr0 is a plain L2 bridge: LXD runs no DHCP/DNS on it (MAAS owns
+# provisioning), so VMs configure their NIC statically and deterministically.
+# The host pins the gateway (10.250.250.1) on the bridge and provides NAT; no
+# resolver listens there, so DNS must use public/MAAS resolvers, not the gateway.
+# LXD_NET_MODE=dhcp opts back into DHCP-first for VMs on a MAAS-served segment.
+LXD_NET_MODE="${LXD_NET_MODE:-static}"
+LXD_FALLBACK_IPV4_CIDR="${LXD_FALLBACK_IPV4_CIDR:-10.250.250.100/24}"
+LXD_FALLBACK_GATEWAY="${LXD_FALLBACK_GATEWAY:-10.250.250.1}"
+LXD_FALLBACK_DNS="${LXD_FALLBACK_DNS:-1.1.1.1 8.8.8.8}"
+ROCKY_MIRROR_HOST="${ROCKY_MIRROR_HOST:-mirrors.rockylinux.org}"
+
+current_ipv4() {
+    ip -4 addr show "$IFACE" | awk '/inet /{print $2; exit}'
+}
+
+wait_for_ipv4() {
+    local current_ip=""
+    
+    for _ in $(seq 1 10); do
+        current_ip="$(current_ipv4)"
+        if [ -n "$current_ip" ]; then
+            echo "$current_ip"
+            return 0
+        fi
+        sleep 1
+    done
+    
+    return 1
+}
+
+refresh_resolver_state() {
+    if command -v resolvectl >/dev/null 2>&1; then
+        sudo resolvectl flush-caches || true
+    fi
+    
+    if [ -f /run/NetworkManager/resolv.conf ]; then
+        sudo ln -sf /run/NetworkManager/resolv.conf /etc/resolv.conf || true
+    fi
+}
+
+verify_name_resolution() {
+    getent ahostsv4 "$ROCKY_MIRROR_HOST" >/dev/null 2>&1
+}
+
+retry_dnf() {
+    local attempt=1
+    local max_attempts=3
+    
+    until "$@"; do
+        if [ "$attempt" -ge "$max_attempts" ]; then
+            return 1
+        fi
+        
+        echo "DNF command failed (attempt $attempt/$max_attempts): $*"
+        echo "Refreshing resolver state before retry..."
+        refresh_resolver_state
+        verify_name_resolution || true
+        attempt=$((attempt + 1))
+    done
+}
+
+# k3s derives the node name from the system hostname. The Rocky image keeps
+# "localhost.localdomain" for every VM, so without this every node would try to
+# register under the same name — the second one is rejected ("Node password
+# rejected, duplicate hostname"). Pin the hostname to the LXD instance name so
+# node names are unique and deterministic (control plane labeling relies on it).
+if [ -n "${LXD_NODE_NAME:-}" ] && [ "$(hostname)" != "$LXD_NODE_NAME" ]; then
+    echo "--- Hostname ---"
+    echo "Setting hostname to ${LXD_NODE_NAME} (k3s node name)..."
+    sudo hostnamectl set-hostname "$LXD_NODE_NAME" 2>/dev/null || sudo hostname "$LXD_NODE_NAME"
+fi
+
+echo "--- Network Configuration ---"
+
+# 1. Detect primary non-loopback interface
+IFACE=$(ip -o link show up | awk -F': ' '$2!="lo"{print $2; exit}')
+echo "Using network interface: ${IFACE:-none}"
+
+if [ -z "$IFACE" ]; then
+    echo "CRITICAL ERROR: No network interface detected."
+    exit 1
+fi
+
+# 2. Force NetworkManager initialization if interface lacks an IP address
+CURRENT_IP="$(current_ipv4 || true)"
+
+if command -v nmcli >/dev/null 2>&1 && [ -z "$CURRENT_IP" ]; then
+    echo "Inspecting NetworkManager profiles..."
+    
+    # Check if a profile is tracking this device
+    NM_CON=$(nmcli -t -f NAME,DEVICE connection show | awk -F: -v iface="$IFACE" '$2==iface{print $1; exit}')
+    
+    if [ -z "$NM_CON" ]; then
+        echo "No connection profile matches $IFACE. Forcing generation of profile 'k3s-net'..."
+        nmcli connection add type ethernet con-name k3s-net ifname "$IFACE"
+        NM_CON="k3s-net"
+    fi
+
+    apply_static_ipv4() {
+        echo "Applying static LXD bridge address ${LXD_FALLBACK_IPV4_CIDR} (gw ${LXD_FALLBACK_GATEWAY}, dns ${LXD_FALLBACK_DNS})..."
+        nmcli connection modify "$NM_CON" \
+        connection.autoconnect yes \
+        connection.interface-name "$IFACE" \
+        ipv4.method manual \
+        ipv4.addresses "$LXD_FALLBACK_IPV4_CIDR" \
+        ipv4.gateway "$LXD_FALLBACK_GATEWAY" \
+        ipv4.dns "$LXD_FALLBACK_DNS" \
+        ipv4.ignore-auto-dns yes \
+        ipv6.method ignore
+        nmcli connection up "$NM_CON"
+        CURRENT_IP="$(wait_for_ipv4 || true)"
+    }
+
+    # Static-first: lxdbr0 has no DHCP, so a DHCP attempt only adds a ~45s
+    # activation timeout per boot. DHCP is opt-in for VMs on a MAAS-served
+    # segment (LXD_NET_MODE=dhcp), with a static fallback if no lease appears.
+    if [ "$LXD_NET_MODE" = "dhcp" ]; then
+        echo "Configuring DHCP-first NetworkManager profile '$NM_CON'..."
+        nmcli connection modify "$NM_CON" \
+        connection.autoconnect yes \
+        connection.interface-name "$IFACE" \
+        ipv4.method auto \
+        ipv4.dhcp-client-id mac \
+        ipv4.ignore-auto-dns no \
+        ipv6.method ignore
+        echo "Bringing network interface up with DHCP..."
+        nmcli connection up "$NM_CON" || echo "DHCP activation failed; static fallback will be applied."
+        CURRENT_IP="$(wait_for_ipv4 || true)"
+        if [ -z "$CURRENT_IP" ]; then
+            echo "No DHCP lease on $IFACE."
+            apply_static_ipv4
+        fi
+    else
+        echo "Configuring static NetworkManager profile '$NM_CON' for the plain LXD bridge..."
+        apply_static_ipv4
+    fi
+fi
+
+# 3. Give the network interface a short window to settle and lease an IP address
+echo "Waiting for IP address allocation..."
+CURRENT_IP="${CURRENT_IP:-$(wait_for_ipv4 || true)}"
+if [ -n "$CURRENT_IP" ]; then
+    echo "Interface $IFACE successfully initialized with IP: $CURRENT_IP"
+fi
+
+# 4. Verify DNS and outbound connectivity before proceeding (Fail Closed)
+echo "Verifying internet and DNS connectivity..."
+refresh_resolver_state
+if ! verify_name_resolution; then
+    echo "CRITICAL ERROR: DNS lookup failed for $ROCKY_MIRROR_HOST. Diagnostic snapshot:"
+    echo "=== /etc/resolv.conf ==="
+    cat /etc/resolv.conf || true
+    echo "=== Interface State ==="
+    ip -4 addr show "$IFACE" || true
+    echo "=== Routing Table ==="
+    ip route show || true
+    echo "=== NetworkManager Status ==="
+    nmcli device status || true
+    exit 1
+fi
+
+if ! timeout 15 curl -fsSL --max-time 10 "https://${ROCKY_MIRROR_HOST}" -o /dev/null; then
+    echo "CRITICAL ERROR: Network/DNS remains unreachable. Diagnostic snapshot:"
+    echo "=== /etc/resolv.conf ==="
+    cat /etc/resolv.conf || true
+    echo "=== Interface State ==="
+    ip -4 addr show "$IFACE" || true
+    echo "=== Routing Table ==="
+    ip route show || true
+    echo "=== NetworkManager Status ==="
+    nmcli device status || true
+    exit 1
 fi
 
+echo "--- Disk Resizing ---"
+if ! command -v parted >/dev/null 2>&1; then
+    sudo dnf install -y parted
+fi
+
+set +e
 sudo parted /dev/sda ---pretend-input-tty <<EOF
 unit s
 resizepart 2 100%
 Yes
 quit
 EOF
+set -e
 
 sudo resize2fs /dev/sda2
-echo "Disk resized."
+echo "Disk partition and filesystem resized successfully."
 
-echo "Installing essential packages..."
-sudo dnf install -y tar bzip2 git curl jq epel-release
-sudo dnf -y update
+echo "--- Package Installation ---"
+retry_dnf sudo dnf install -y epel-release
+retry_dnf sudo dnf install -y tar bzip2 git curl jq
+retry_dnf sudo dnf -y update
 
-echo "Loading br_netfilter module..."
+echo "--- Kernel Modules for K3s ---"
 sudo modprobe br_netfilter
+echo "br_netfilter" | sudo tee /etc/modules-load.d/k3s-br_netfilter.conf > /dev/null
+
+echo "Setup complete. System is ready for k3s-node-setup.sh"

package/scripts/maas-nat-firewalld.sh

@@ -0,0 +1,145 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# MAAS NAT + firewall helper
+# - Enables IPv4 forwarding and masquerading for the MAAS/provisioning subnet
+# - Opens the MAAS API on the uplink zone when requested
+# - Opens provisioning and optional NFS services on the zone bound to MAAS_LAN_CIDR
+#
+# Usage examples:
+#   sudo MAAS_LAN_CIDR="192.168.1.0/24" PUBLIC_ZONE="public" ./maas-nat-firewalld.sh
+#   sudo NFS_MODE="v3" CONFIGURE_NFS_V3_PORTS="true" ./maas-nat-firewalld.sh
+
+MAAS_LAN_CIDR="${MAAS_LAN_CIDR:-192.168.1.0/24}"
+PUBLIC_ZONE="${PUBLIC_ZONE:-public}"
+TRUSTED_ZONE="${TRUSTED_ZONE:-trusted}"
+NFS_MODE="${NFS_MODE:-v4}"                    # v4 or v3
+CONFIGURE_NFS_V3_PORTS="${CONFIGURE_NFS_V3_PORTS:-false}"
+EXPOSE_MAAS_API_PUBLIC="${EXPOSE_MAAS_API_PUBLIC:-true}"
+
+# Fixed NFSv3 ports (only used when CONFIGURE_NFS_V3_PORTS=true)
+NFS_MOUNTD_PORT="${NFS_MOUNTD_PORT:-20048}"
+NFS_STATD_PORT="${NFS_STATD_PORT:-32765}"
+# Outgoing port must differ from the listen port; rpc.statd exits 255 if they match.
+NFS_STATD_OUTGOING_PORT="${NFS_STATD_OUTGOING_PORT:-32766}"
+NFS_LOCKD_PORT="${NFS_LOCKD_PORT:-32803}"
+NFS_LOCKD_UDP_PORT="${NFS_LOCKD_UDP_PORT:-${NFS_LOCKD_PORT}}"
+NFS_CONF_DROPIN="/etc/nfs.conf.d/99-maas-nfs-v3-ports.conf"
+
+case "${NFS_MODE}" in
+    v3|v4) ;;
+    *)
+        echo "[ERROR] NFS_MODE must be 'v3' or 'v4'." >&2
+        exit 1
+    ;;
+esac
+
+# Ensure the kernel NFS server is enabled and actually running. `exportfs -rav` only populates the
+# export table; it does not start nfsd, and `systemctl try-restart` is a no-op when the unit is
+# stopped. Without this, clients hang on mount because nothing listens on 2049/mountd.
+ensure_nfs_server_running() {
+    if [[ "${NFS_MODE}" == "v3" ]]; then
+        # NFSv3 depends on the portmapper and the status monitor.
+        sudo systemctl enable --now rpcbind 2>/dev/null || true
+        sudo systemctl enable --now rpc-statd 2>/dev/null || true
+    fi
+    
+    local unit=""
+    for candidate in nfs-server nfs-kernel-server; do
+        if systemctl cat "${candidate}.service" >/dev/null 2>&1; then
+            unit="${candidate}"
+            break
+        fi
+    done
+    if [[ -z "${unit}" ]]; then
+        echo "[ERROR] No NFS server unit found (nfs-server/nfs-kernel-server). Install nfs-utils or nfs-kernel-server." >&2
+        return 1
+    fi
+    
+    echo "[INFO] Enabling and (re)starting ${unit} to apply exports and fixed ports..."
+    sudo systemctl enable "${unit}" 2>/dev/null || true
+    sudo systemctl restart "${unit}"
+}
+
+echo "[INFO] Enabling firewalld..."
+sudo systemctl enable --now firewalld
+
+echo "[INFO] Enabling kernel forwarding..."
+sudo tee /etc/sysctl.d/99-maas-nat.conf >/dev/null <<'EOF'
+net.ipv4.ip_forward = 1
+EOF
+
+sudo sysctl --system >/dev/null
+
+echo "[INFO] Allowing NAT for the MAAS LAN..."
+sudo firewall-cmd --permanent --zone="${PUBLIC_ZONE}" --add-masquerade
+sudo firewall-cmd --permanent --zone="${TRUSTED_ZONE}" --add-source="${MAAS_LAN_CIDR}"
+
+echo "[INFO] Opening MAAS services on the MAAS LAN zone..."
+sudo firewall-cmd --permanent --zone="${TRUSTED_ZONE}" --add-port=5240/tcp
+for service in dns dhcp tftp; do
+    sudo firewall-cmd --permanent --zone="${TRUSTED_ZONE}" --add-service="${service}"
+done
+
+if [[ "${EXPOSE_MAAS_API_PUBLIC}" == "true" ]]; then
+    echo "[INFO] Opening MAAS API on the uplink zone..."
+    sudo firewall-cmd --permanent --zone="${PUBLIC_ZONE}" --add-port=5240/tcp
+fi
+
+echo "[INFO] Opening NFS ports on the MAAS LAN zone..."
+
+if [[ "${NFS_MODE}" == "v4" ]]; then
+    # NFSv4 normally needs only TCP 2049.
+    sudo firewall-cmd --permanent --zone="${TRUSTED_ZONE}" --add-port=2049/tcp
+else
+    # NFSv3 side-band daemons need fixed ports for deterministic firewall rules.
+    if [[ "${CONFIGURE_NFS_V3_PORTS}" != "true" ]]; then
+        echo "[ERROR] NFSv3 requires CONFIGURE_NFS_V3_PORTS=true for consistent firewalld rules." >&2
+        echo "[ERROR] Re-run with CONFIGURE_NFS_V3_PORTS=true or switch to NFS_MODE=v4." >&2
+        exit 1
+    fi
+    
+    echo "[INFO] Writing fixed NFSv3 port configuration..."
+    sudo install -d -m 0755 /etc/nfs.conf.d
+        sudo tee "${NFS_CONF_DROPIN}" >/dev/null <<EOF
+[nfsd]
+vers3=y
+
+[mountd]
+port=${NFS_MOUNTD_PORT}
+
+[statd]
+port=${NFS_STATD_PORT}
+outgoing-port=${NFS_STATD_OUTGOING_PORT}
+
+[lockd]
+port=${NFS_LOCKD_PORT}
+udp-port=${NFS_LOCKD_UDP_PORT}
+EOF
+    
+    sudo firewall-cmd --permanent --zone="${TRUSTED_ZONE}" --add-service=rpc-bind
+    sudo firewall-cmd --permanent --zone="${TRUSTED_ZONE}" --add-port=2049/tcp
+    for proto in tcp udp; do
+        sudo firewall-cmd --permanent --zone="${TRUSTED_ZONE}" --add-port="${NFS_MOUNTD_PORT}/${proto}"
+        sudo firewall-cmd --permanent --zone="${TRUSTED_ZONE}" --add-port="${NFS_STATD_PORT}/${proto}"
+        # Outgoing port is the fixed source for SM_NOTIFY; peers need to reach it.
+        sudo firewall-cmd --permanent --zone="${TRUSTED_ZONE}" --add-port="${NFS_STATD_OUTGOING_PORT}/${proto}"
+    done
+    sudo firewall-cmd --permanent --zone="${TRUSTED_ZONE}" --add-port="${NFS_LOCKD_PORT}/tcp"
+    sudo firewall-cmd --permanent --zone="${TRUSTED_ZONE}" --add-port="${NFS_LOCKD_UDP_PORT}/udp"
+fi
+
+ensure_nfs_server_running
+
+echo "[INFO] Reloading firewall..."
+sudo firewall-cmd --reload
+
+echo
+echo "[INFO] Firewall status:"
+sudo firewall-cmd --zone="${PUBLIC_ZONE}" --list-all
+echo
+echo "[INFO] MAAS LAN zone (${TRUSTED_ZONE}):"
+sudo firewall-cmd --zone="${TRUSTED_ZONE}" --list-all
+
+echo
+echo "[INFO] MAAS NAT + firewall configuration completed."

package/scripts/test-monitor.sh

@@ -0,0 +1,250 @@
+#!/usr/bin/env bash
+#
+# test-monitor.sh — end-to-end deploy + two-phase monitor smoke test.
+#
+# Two deployment shapes are supported (see
+# src/client/public/nexodev/docs/references/Deploy-Monitor-PRD.md and
+# 'Deploy custom instance to K8S.md'):
+#
+#   --mode runtime   `underpost start` deploy (e.g. dd-test). Monitored with the
+#                    HTTP gate: /_internal/ready probes + port-forward status.
+#   --mode instance  Custom instances from conf.instances.json (e.g. cyberia
+#                    mmo-server / mmo-client). Monitored with the kubernetes gate
+#                    (TCP readinessProbe) + exec status transport.
+#
+# Every variable in the DEFAULTS block below is overridable with a flag of the
+# same name (--env, --deploy-id, …). Run with --help for the full list.
+#
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ENGINE_DIR="$(cd "${SCRIPT_DIR}/.." && pwd)"
+cd "$ENGINE_DIR"
+
+# ─────────────────────────── DEFAULTS (all overridable) ───────────────────────────
+MODE=runtime                                  # runtime | instance
+ENV=development                               # development | production
+DEPLOY_ID=dd-test                             # deploy id (instance mode: parent of conf.instances.json)
+INSTANCE_IDS=                                 # instance mode: csv of ids (default: all in conf.instances.json)
+IMAGE=underpost/wp:v3.2.14                    # runtime mode image (instance mode reads image from conf)
+VERSIONS=green                                # csv of blue/green versions
+REPLICAS=1                                    # replicas per deployment
+NAMESPACE=default                             # k8s namespace
+CLUSTER=                                      # kind | kubeadm | k3s | "" (auto/none)
+TIMEOUT_RESPONSE=300000ms                     # HTTPProxy per-route response timeout
+TEMPLATE_REPO=underpostnet/pwa-microservices-template-private  # runtime mode link repo
+ENVOY_NAMESPACE=projectcontour                # ingress namespace (instance TLS exposure)
+ENVOY_SERVICE=envoy                           # ingress service (instance TLS exposure)
+HTTPS_PORT=443                                # local https port for instance TLS exposure
+
+USE_CERT=false                                # runtime: pass --cert to the proxy step
+USE_PULL_BUNDLE=false                         # runtime: include --pull-bundle in the start cmd
+USE_TLS=false                                 # generate self-signed certs + expose over HTTPS
+USE_TEST_REPO=false                           # runtime: publish src to engine-test-<id> + pod clones it (--private-test-repo)
+DO_BUILD_TEMPLATE=true                        # run `node bin/build.template --update-private`
+DO_CLUSTER_MANIFESTS=true                     # run `node bin run build-cluster-deployment-manifests`
+DO_EXPOSE=true                                # expose locally after deploy + monitor
+
+usage() {
+  cat <<'EOF'
+Usage: scripts/test-monitor.sh [flags]
+
+Modes:
+  --mode <runtime|instance>     Deployment shape to test (default: runtime)
+
+Common (every default is overridable):
+  --env <development|production>
+  --deploy-id <id>
+  --instance-ids <csv>          instance mode only; default = all ids in conf.instances.json
+  --image <image>               runtime mode only
+  --versions <csv>              e.g. green or blue,green
+  --replicas <n>
+  --namespace <ns>
+  --cluster <kind|kubeadm|k3s|none>
+  --timeout-response <dur>      e.g. 300000ms
+  --template-repo <owner/repo>  runtime mode link repo
+  --envoy-namespace <ns>        instance TLS exposure ingress namespace
+  --envoy-service <name>        instance TLS exposure ingress service
+  --https-port <port>           local https port for instance TLS exposure
+
+Toggles (use --x / --no-x):
+  --tls | --no-tls              self-signed certs + HTTPS exposure (default: off)
+  --cert | --no-cert            runtime proxy --cert (default: off)
+  --pull-bundle | --no-pull-bundle   runtime start --pull-bundle (default: off)
+  --test-repo | --no-test-repo  runtime: publish src to engine-test-<id> and have the
+                                pod clone it via --private-test-repo (default: off)
+  --expose | --no-expose        local exposure after monitor (default: on)
+  --build-template | --no-build-template       sync private template (default: on)
+  --cluster-manifests | --no-cluster-manifests  rebuild cluster manifests (default: on)
+
+  -h, --help
+
+Examples:
+  # Runtime deploy (default), no TLS
+  scripts/test-monitor.sh
+
+  # Runtime deploy over HTTPS
+  scripts/test-monitor.sh --tls
+
+  # Runtime deploy from a work-in-progress test source repo (engine-test-<id>)
+  scripts/test-monitor.sh --test-repo
+
+  # Cyberia instances (both), dev on kind, no TLS
+  scripts/test-monitor.sh --mode instance --deploy-id dd-cyberia --cluster kind
+
+  # Only the mmo-server instance, production, over HTTPS
+  scripts/test-monitor.sh --mode instance --deploy-id dd-cyberia \
+    --instance-ids mmo-server --env production --cluster kubeadm --tls
+EOF
+}
+
+# ─────────────────────────── flag parsing ───────────────────────────
+# Supports `--key value` and `--key=value` for value flags, plus --x/--no-x toggles.
+needval() { [[ $# -ge 2 ]] || { echo "Missing value for $1" >&2; exit 1; }; }
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --mode) needval "$@"; MODE="$2"; shift 2;;            --mode=*) MODE="${1#*=}"; shift;;
+    --env) needval "$@"; ENV="$2"; shift 2;;              --env=*) ENV="${1#*=}"; shift;;
+    --deploy-id) needval "$@"; DEPLOY_ID="$2"; shift 2;;  --deploy-id=*) DEPLOY_ID="${1#*=}"; shift;;
+    --instance-ids) needval "$@"; INSTANCE_IDS="$2"; shift 2;; --instance-ids=*) INSTANCE_IDS="${1#*=}"; shift;;
+    --image) needval "$@"; IMAGE="$2"; shift 2;;          --image=*) IMAGE="${1#*=}"; shift;;
+    --versions) needval "$@"; VERSIONS="$2"; shift 2;;    --versions=*) VERSIONS="${1#*=}"; shift;;
+    --replicas) needval "$@"; REPLICAS="$2"; shift 2;;    --replicas=*) REPLICAS="${1#*=}"; shift;;
+    --namespace) needval "$@"; NAMESPACE="$2"; shift 2;;  --namespace=*) NAMESPACE="${1#*=}"; shift;;
+    --cluster) needval "$@"; CLUSTER="$2"; shift 2;;      --cluster=*) CLUSTER="${1#*=}"; shift;;
+    --timeout-response) needval "$@"; TIMEOUT_RESPONSE="$2"; shift 2;; --timeout-response=*) TIMEOUT_RESPONSE="${1#*=}"; shift;;
+    --template-repo) needval "$@"; TEMPLATE_REPO="$2"; shift 2;; --template-repo=*) TEMPLATE_REPO="${1#*=}"; shift;;
+    --envoy-namespace) needval "$@"; ENVOY_NAMESPACE="$2"; shift 2;; --envoy-namespace=*) ENVOY_NAMESPACE="${1#*=}"; shift;;
+    --envoy-service) needval "$@"; ENVOY_SERVICE="$2"; shift 2;; --envoy-service=*) ENVOY_SERVICE="${1#*=}"; shift;;
+    --https-port) needval "$@"; HTTPS_PORT="$2"; shift 2;; --https-port=*) HTTPS_PORT="${1#*=}"; shift;;
+    --tls) USE_TLS=true; shift;;                          --no-tls) USE_TLS=false; shift;;
+    --cert) USE_CERT=true; shift;;                        --no-cert) USE_CERT=false; shift;;
+    --pull-bundle) USE_PULL_BUNDLE=true; shift;;          --no-pull-bundle) USE_PULL_BUNDLE=false; shift;;
+    --test-repo) USE_TEST_REPO=true; shift;;              --no-test-repo) USE_TEST_REPO=false; shift;;
+    --expose) DO_EXPOSE=true; shift;;                     --no-expose) DO_EXPOSE=false; shift;;
+    --build-template) DO_BUILD_TEMPLATE=true; shift;;     --no-build-template) DO_BUILD_TEMPLATE=false; shift;;
+    --cluster-manifests) DO_CLUSTER_MANIFESTS=true; shift;; --no-cluster-manifests) DO_CLUSTER_MANIFESTS=false; shift;;
+    -h|--help) usage; exit 0;;
+    *) echo "Unknown flag: $1" >&2; usage; exit 1;;
+  esac
+done
+
+# ─────────────────────────── derived flags ───────────────────────────
+CLUSTER_FLAG=""
+case "$CLUSTER" in
+  kind)    CLUSTER_FLAG="--kind";;
+  kubeadm) CLUSTER_FLAG="--kubeadm";;
+  k3s)     CLUSTER_FLAG="--k3s";;
+  ""|none) CLUSTER_FLAG="";;
+  *) echo "Unknown --cluster: $CLUSTER (expected kind|kubeadm|k3s|none)" >&2; exit 1;;
+esac
+DEV_FLAG=""; [ "$ENV" = development ] && DEV_FLAG="--dev"
+INSTANCES_CONF="./engine-private/conf/${DEPLOY_ID}/conf.instances.json"
+SERVER_CONF="./engine-private/conf/${DEPLOY_ID}/conf.server.json"
+
+echo "[test-monitor] mode=$MODE env=$ENV deploy=$DEPLOY_ID cluster=${CLUSTER:-none} tls=$USE_TLS test-repo=$USE_TEST_REPO expose=$DO_EXPOSE"
+
+# ─────────────────────────── shared helpers ───────────────────────────
+
+# setup_tls_secrets <host> [<host> …] — regenerate self-signed certs and create
+# the per-host k8s TLS secret the HTTPProxy references (name == host).
+setup_tls_secrets() {
+  local ssl_base="${ENGINE_DIR}/engine-private/ssl"
+  for host in "$@"; do
+    local cert_dir="${ssl_base}/${host}"
+    mkdir -p "$cert_dir"
+    bash "${SCRIPT_DIR}/ssl.sh" "$cert_dir" "$host"
+    local name_safe="${host//[^a-zA-Z0-9_.-]/_}"
+    kubectl delete secret "$host" -n "$NAMESPACE" --ignore-not-found
+    kubectl create secret tls "$host" \
+      --cert="${cert_dir}/${name_safe}.pem" \
+      --key="${cert_dir}/${name_safe}-key.pem" \
+      -n "$NAMESPACE"
+  done
+}
+
+# hosts_from <conf.json> — unique hosts declared in a conf.server.json or conf.instances.json.
+hosts_from() {
+  node -e "
+    const c = require('$1');
+    const hosts = Array.isArray(c) ? c.map(i => i.host) : Object.keys(c);
+    console.log([...new Set(hosts)].join(' '));
+  "
+}
+
+# ─────────────────────────── pre-steps ───────────────────────────
+[ "$DO_CLUSTER_MANIFESTS" = true ] && node bin run build-cluster-deployment-manifests
+[ "$DO_BUILD_TEMPLATE" = true ] && node bin/build.template --update-private
+
+# ─────────────────────────── runtime mode ───────────────────────────
+run_runtime_mode() {
+  local link_cmd="cd /home/dd,underpost clone ${TEMPLATE_REPO},cd /home/dd/${TEMPLATE_REPO##*/},npm install,npm link"
+  local deploy_cmd proxy_flag="" expose_flags="" start_flags=""
+
+  # Publish the local engine src to underpostnet/engine-test-<id> so the pod
+  # (started with --private-test-repo) clones this work-in-progress source.
+  [ "$USE_TEST_REPO" = true ] && node bin/build "$DEPLOY_ID" --update-private
+
+  [ "$USE_PULL_BUNDLE" = true ] && start_flags="${start_flags} --pull-bundle"
+  [ "$USE_TEST_REPO" = true ] && start_flags="${start_flags} --private-test-repo"
+  deploy_cmd="${link_cmd},underpost start --build --run${start_flags} ${DEPLOY_ID} ${ENV}"
+
+  [ "$USE_CERT" = true ] && proxy_flag="--cert"
+  [ "$USE_TLS" = true ] && proxy_flag="--self-signed"
+
+  node bin deploy "$DEPLOY_ID" "$ENV" $CLUSTER_FLAG --sync --build-manifest \
+    --image "$IMAGE" --timeout-response "$TIMEOUT_RESPONSE" --versions "$VERSIONS" --replicas "$REPLICAS" --cmd "$deploy_cmd"
+  node bin deploy "$DEPLOY_ID" "$ENV" $CLUSTER_FLAG --disable-update-proxy $proxy_flag
+  node bin monitor "$DEPLOY_ID" "$ENV" --ready-deployment --promote \
+    --timeout-response "$TIMEOUT_RESPONSE" --versions "$VERSIONS" --replicas "$REPLICAS"
+
+  node bin run etc-hosts --deploy-id "$DEPLOY_ID"
+
+  if [ "$USE_TLS" = true ]; then
+    setup_tls_secrets $(hosts_from "$SERVER_CONF")
+    expose_flags="--tls"
+  fi
+  [ "$DO_EXPOSE" = true ] && node bin deploy --expose --local-proxy "$DEPLOY_ID" "$ENV" $expose_flags
+}
+
+# ─────────────────────────── instance mode ───────────────────────────
+run_instance_mode() {
+  [ -f "$INSTANCES_CONF" ] || { echo "Missing $INSTANCES_CONF" >&2; exit 1; }
+  if [ -z "$INSTANCE_IDS" ]; then
+    INSTANCE_IDS=$(node -e "console.log(require('$INSTANCES_CONF').map(i=>i.id).join(','))")
+  fi
+  local tls_flag=""; [ "$USE_TLS" = true ] && tls_flag="--tls --test"
+
+  # `run instance` builds/pulls the image, applies the manifest, monitors with the
+  # kubernetes gate (TCP readinessProbe) + exec status, then promotes traffic.
+  IFS=',' read -ra ids <<< "$INSTANCE_IDS"
+  for id in "${ids[@]}"; do
+    [ -n "$id" ] || continue
+    echo "[test-monitor] deploying instance ${DEPLOY_ID},${id}"
+    node bin run instance "${DEPLOY_ID},${id},${REPLICAS}" \
+      $DEV_FLAG $CLUSTER_FLAG --namespace "$NAMESPACE" --etc-hosts $tls_flag \
+      ${IMAGE:+--image-name "$IMAGE"}
+  done
+
+  [ "$DO_EXPOSE" = true ] || return 0
+  if [ "$USE_TLS" = true ]; then
+    # Instances are routed by the Contour ingress; port-forward Envoy so the
+    # HTTPProxy host routing (server/client.cyberiaonline.com) works locally.
+    echo "[test-monitor] exposing HTTPS via ${ENVOY_NAMESPACE}/${ENVOY_SERVICE} on :${HTTPS_PORT}"
+    sudo kubectl port-forward -n "$ENVOY_NAMESPACE" "svc/${ENVOY_SERVICE}" "${HTTPS_PORT}:443" &
+  else
+    # Plain HTTP: port-forward each instance service port directly.
+    for id in "${ids[@]}"; do
+      [ -n "$id" ] || continue
+      node bin deploy --expose "${DEPLOY_ID}-${id}" "$ENV" --namespace "$NAMESPACE" || true
+    done
+  fi
+}
+
+case "$MODE" in
+  runtime)  run_runtime_mode;;
+  instance) run_instance_mode;;
+  *) echo "Unknown --mode: $MODE (expected runtime|instance)" >&2; exit 1;;
+esac
+
+echo "[test-monitor] done (mode=$MODE tls=$USE_TLS)"