@celilo/e2e 0.13.1 → 0.14.1

package/docker/Dockerfile.proxmox-sim

@@ -0,0 +1,48 @@
+FROM oven/bun:1
+
+WORKDIR /app
+
+# The Docker CLI is the whole point of this image: creating an LXC means
+# starting a real container on the host daemon, via the socket mounted at run
+# time (D2). `docker-cli` alone — no daemon, nothing to run in here.
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    docker.io \
+    openssl \
+    ca-certificates \
+    && rm -rf /var/lib/apt/lists/*
+
+# The fake comes from THIS checkout, bundled next to us at build-infra time
+# (src/registry-bundle.ts), not from npm.
+#
+# Installing `@celilo/terraform-fake` here instead would mean the simulator runs
+# whatever npm last published, so a PR that changes the fake would be tested
+# against code it does not touch — the "modules run their bundled copy" trap
+# (celilo#173) in a new place, and silent. Before the first release it cannot
+# work at all: `bun install` resolved `@celilo/terraform-fake@*` against
+# registry.npmjs.org and got a 404.
+# Placed AS the package name, so the entrypoint's import specifier is the same
+# one that resolves against the workspace at typecheck time. A relative path
+# into the bundle would work at runtime and drag a dependency-less copy into
+# `tsc`, which then cannot resolve msw.
+COPY terraform-fake/package.json ./node_modules/@celilo/terraform-fake/package.json
+COPY terraform-fake/src ./node_modules/@celilo/terraform-fake/src
+
+# Only the fake's own third-party deps (msw, express, @mswjs/http-middleware),
+# which are ordinary public packages.
+RUN cd node_modules/@celilo/terraform-fake && bun install --production
+
+# The rig's half: the provisioner and the zone plan it resolves against.
+COPY src/proxmox-provisioner.ts ./src/proxmox-provisioner.ts
+COPY src/types.ts ./src/types.ts
+COPY simulators/proxmox/entrypoint.ts ./simulators/proxmox/entrypoint.ts
+
+# Proxmox is HTTPS-only on 8006 and every consumer skips verification
+# (`pm_tls_insecure`), so a self-signed pair generated at build time is exactly
+# as good as a real one here and needs no fixture to keep in sync.
+RUN mkdir -p /certs && openssl req -x509 -newkey rsa:2048 \
+    -keyout /certs/proxmox-sim.key -out /certs/proxmox-sim.crt \
+    -days 3650 -nodes -subj "/CN=proxmox.sim" 2>/dev/null
+
+EXPOSE 8006
+
+ENTRYPOINT ["bun", "run", "simulators/proxmox/entrypoint.ts"]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celilo/e2e",
-  "version": "0.13.1",
+  "version": "0.14.1",
   "description": "E2E test infrastructure for Celilo-deployed applications. Provides a simulated internet with DNS hierarchy, ACME server, firewalls, and target machines in Docker.",
   "type": "module",
   "main": "./src/index.ts",
@@ -39,7 +39,8 @@
   "dependencies": {
     "@celilo/capabilities": "^1.2.0",
     "@celilo/cli-display": "^0.2.0",
-    "@celilo/event-bus": "^0.5.0",
+    "@celilo/event-bus": "^0.6.0",
+    "@celilo/terraform-fake": "^0.2.0",
     "yaml": "^2.8.0",
     "zod": "^3.24.1"
   },

package/simulators/proxmox/entrypoint.ts

@@ -0,0 +1,51 @@
+/**
+ * The Proxmox simulator, as the rig runs it.
+ *
+ * Everything here is the join between two halves that are deliberately kept
+ * apart: `@celilo/terraform-fake` knows the Proxmox API and nothing about this
+ * rig, and `proxmox-provisioner` knows this rig and nothing about Proxmox. This
+ * file is the only place that holds both, and it is also the only place that
+ * holds the host Docker socket (D2) — which is why it is an image in the rig
+ * rather than anything the published package ships.
+ */
+// In the image this specifier resolves to the BUNDLED copy from this checkout
+// (Dockerfile.proxmox-sim places it at node_modules/@celilo/terraform-fake),
+// never to whatever npm last published — a PR that changes the fake must be
+// tested against the fake it changed.
+import { createProxmoxFake } from '@celilo/terraform-fake';
+import { createDockerProvisioner } from '../../src/proxmox-provisioner';
+
+const port = Number(process.env.PROXMOX_SIM_PORT ?? 8006);
+
+/**
+ * The compose project name, which prefixes the networks and volumes the
+ * provisioner attaches containers to.
+ *
+ * Required rather than defaulted: a wrong guess here does not fail, it starts
+ * containers on a network no test is looking at, and the deploy failure that
+ * follows points at DNS or the firewall instead.
+ */
+const project = process.env.CELILO_E2E_PROJECT;
+if (!project) {
+  throw new Error('CELILO_E2E_PROJECT is required — it names the compose project to attach to');
+}
+
+const fake = createProxmoxFake({
+  tls: {
+    key: await Bun.file('/certs/proxmox-sim.key').text(),
+    cert: await Bun.file('/certs/proxmox-sim.crt').text(),
+  },
+  // One node, named to match what a test sets as `target_node`.
+  nodes: [
+    {
+      name: process.env.PROXMOX_SIM_NODE ?? 'pve1',
+      cores: 8,
+      memoryBytes: 16 * 1024 ** 3,
+      diskBytes: 500 * 1024 ** 3,
+    },
+  ],
+  provisioner: createDockerProvisioner({ project }),
+});
+
+await fake.listen(port);
+console.log(`[proxmox-sim] listening on https://0.0.0.0:${port}/api2/json (project ${project})`);

package/src/cli/build.ts

@@ -25,7 +25,7 @@ import { gunzipSync } from 'node:zlib';
 import { stageAptRepo } from '../../scripts/stage-apt-repo';
 import { stageLibsignal } from '../../scripts/stage-libsignal';
 import { explainBuildFailure } from '../doctor';
-import { ensureRegistryServerBundle } from '../registry-bundle';
+import { ensureRegistryServerBundle, ensureTerraformFakeBundle } from '../registry-bundle';
 
 /**
  * Ceiling on a single `docker build`. The slowest image here is a few minutes
@@ -213,6 +213,7 @@ export const PUBLISHED_CELILO_PACKAGES = [
   '@celilo/cli-display',
   '@celilo/core',
   '@celilo/event-bus',
+  '@celilo/terraform-fake',
   '@celilo/e2e',
   '@celilo/cli',
 ] as const;
@@ -501,6 +502,7 @@ function buildDockerImages(pkgDir: string): void {
   // Dockerfile.registry copies from <pkgDir>/registry-server, which is
   // .gitignored and recreated from the canonical source each build.
   ensureRegistryServerBundle(pkgDir);
+  ensureTerraformFakeBundle(pkgDir);
 
   const dockerDir = join(pkgDir, 'docker');
   if (!existsSync(dockerDir)) {

package/src/container-manager.ts

@@ -637,17 +637,12 @@ function buildNetworkHandle(
       // remember, and removes a hand-maintained copy of a list the compose
       // generator already owns.
       //
-      // `external` is excluded from provided_networks: it is the residual, has
-      // no subnet, and is not a zone modules are placed in.
+      // `external` is excluded: it is the residual, has no subnet, and is not a
+      // zone modules are placed in.
       const declaredZones = firewallZoneLegs(topology);
       const providedZones = declaredZones.filter((zone) => zone !== 'external');
       const firewallIp = ZONE_GATEWAYS.internal; // fw-main on internal
       const natIp = opts.natIp ?? internalNatIp();
-      const providedNetworks = providedZones.map((zone) => ({
-        zone,
-        subnet: ZONE_SUBNETS[zone],
-        gateway: ZONE_GATEWAYS[zone],
-      }));
 
       // fw-main is a firewall container, not a target machine, so the
       // network readiness wait (target-setup) does NOT cover its sshd. Poll
@@ -670,9 +665,24 @@ function buildNetworkHandle(
         `firewall ${firewallIp} sshd`,
       );
 
-      // fw-main is registered as an internal-zone machine; iptables
-      // deploys to it and (Phase 2) writes the provided zones to system
-      // config from its on_install hook.
+      // The addressing of each segmented zone, supplied the way an operator
+      // supplies it — `system config set`, celilo's own surface.
+      //
+      // This used to ride in on `module config set iptables provided_networks`,
+      // and the module wrote it to system config from its install hook. Modules
+      // no longer define networks
+      // (openspec/changes/networks-are-declared-not-written/specs/network-declaration/spec.md);
+      // the manifest REQUIRES them, and celilo asks whoever is attached for any
+      // it does not already hold. The harness answers in advance rather than
+      // through the interview, because these values are the simulator's own
+      // address plan (ZONE_SUBNETS) — it is not a stand-in for an operator's
+      // judgement, it is the topology this rig physically wired.
+      for (const zone of providedZones) {
+        await handle.celilo(`system config set network.${zone}.subnet ${ZONE_SUBNETS[zone]}`);
+        await handle.celilo(`system config set network.${zone}.gateway ${ZONE_GATEWAYS[zone]}`);
+      }
+
+      // fw-main is registered as an internal-zone machine; iptables deploys to it.
       await handle.celilo(
         `machine add ${firewallIp} --ssh-user root --ssh-key-file /root/.ssh/id_ed25519 --zone internal`,
       );
@@ -680,9 +690,6 @@ function buildNetworkHandle(
       await handle.celilo(`module config set iptables firewall_ip ${firewallIp}`);
       await handle.celilo(`module config set iptables nat_ip ${natIp}`);
       await handle.celilo(`module config set iptables zones '${JSON.stringify(declaredZones)}'`);
-      await handle.celilo(
-        `module config set iptables provided_networks '${JSON.stringify(providedNetworks)}'`,
-      );
       // `check: false` returns the failed deploy instead of throwing, so a test
       // can assert on WHAT the refusal said. Interface classification refuses
       // by design (D12 onboarding), and a refusal is only useful if it names

package/src/docker-compose-generator.ts

@@ -2,7 +2,7 @@ import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { stringify } from 'yaml';
 import { normalizeObservers, observerEnv, observerPlacement } from './observer';
-import { SIMULATOR_IPS } from './simulator-ips';
+import { PROXMOX_SIM_IP, SIMULATOR_IPS } from './simulator-ips';
 import type { MachineSpec, NetworkConfig, TopologyPreset, Zone } from './types';
 import {
   ZONE_GATEWAYS,
@@ -462,6 +462,31 @@ export function generateSharedInfraYaml(): string {
 // Per-test compose generation
 // ---------------------------------------------------------------------------
 
+/**
+ * The Proxmox API simulator, on `secure-mgmt` with celilo-mgr (D6).
+ *
+ * Defined once and emitted from BOTH compose blocks. Adding a simulator to
+ * only one of them is the standard way to end up with something that works in
+ * exactly half the suites, and the half it fails in is whichever one nobody
+ * ran first.
+ *
+ * It holds the host Docker socket because creating an LXC has to produce a
+ * real container (D2). The containment for that is in the provisioner: every
+ * container it creates carries the `celilo-e2e-` prefix and it refuses to
+ * touch one that does not.
+ */
+function proxmoxSimService() {
+  return baseService({
+    build: { context: '.', dockerfile: 'docker/Dockerfile.proxmox-sim' },
+    networks: { 'secure-mgmt': { ipv4_address: PROXMOX_SIM_IP } },
+    volumes: ['/var/run/docker.sock:/var/run/docker.sock'],
+    // Compose substitutes this at up-time from `-p`, so the generator does not
+    // have to know the project name (it is not a property of the YAML).
+    environment: { CELILO_E2E_PROJECT: '${COMPOSE_PROJECT_NAME}' },
+    cap_add: ['NET_ADMIN'],
+  });
+}
+
 /**
  * Generate the compose YAML for a single test's containers.
  * References the shared infrastructure's isp-external network as external.
@@ -472,7 +497,10 @@ export function generateTestComposeYaml(config: NetworkConfig, celiloRoot?: stri
   // The control-plane network exists if celilo-mgr lives there OR if any
   // machine does — a module declaring `zone: secure-mgmt` needs somewhere to
   // land whether or not the management box shares the network (#436).
-  const needsSecureMgmt = mgmtOnOwnNetwork || (config.secureMgmtMachines ?? []).length > 0;
+  // The proxmox simulator lives here too, so enabling it must bring the network
+  // up even in a topology where celilo-mgr sits on the internal LAN.
+  const needsSecureMgmt =
+    mgmtOnOwnNetwork || (config.secureMgmtMachines ?? []).length > 0 || config.proxmoxSim === true;
   const networks: Record<string, unknown> = {
     internal: zoneNetworkDef('internal'),
     dmz: zoneNetworkDef('dmz'),
@@ -635,6 +663,10 @@ export function generateTestComposeYaml(config: NetworkConfig, celiloRoot?: stri
   });
 
   // --- Dynamic test machines ---
+  if (config.proxmoxSim) {
+    services['proxmox-sim'] = proxmoxSimService();
+  }
+
   const allMachines = getAllMachines(config);
 
   for (const machine of allMachines) {
@@ -749,6 +781,10 @@ export function generateComposeYaml(config: NetworkConfig, celiloRoot = '..'): s
     dmz: zoneNetworkDef('dmz'),
     app: zoneNetworkDef('app'),
     secure: zoneNetworkDef('secure'),
+    // The proxmox simulator lives on secure-mgmt, so enabling it has to bring
+    // the network with it — a service on a network the file never declares is
+    // a compose error at `up`, not a missing feature at deploy.
+    ...(config.proxmoxSim ? { 'secure-mgmt': zoneNetworkDef('secure-mgmt') } : {}),
     'isp-external': networkDef('203.0.113.0/24', '203.0.113.250'),
     'internet-external': networkDef('100.64.0.0/24', '100.64.0.250'),
     'real-internet': {
@@ -895,6 +931,10 @@ export function generateComposeYaml(config: NetworkConfig, celiloRoot = '..'): s
     volumes: getRegistryVolumes(),
   });
 
+  if (config.proxmoxSim) {
+    services['proxmox-sim'] = proxmoxSimService();
+  }
+
   const allMachines = getAllMachines(config);
 
   for (const machine of allMachines) {

package/src/index.ts

@@ -88,7 +88,7 @@ export {
 
 // Simulator addresses on `internet-external` — canonical for code, so a test
 // asserting against the authoritative DNS server never hardcodes its IP.
-export { SIMULATOR_IPS, SIMULATOR_IP_ENTRIES } from './simulator-ips';
+export { PROXMOX_SIM_IP, SIMULATOR_IPS, SIMULATOR_IP_ENTRIES } from './simulator-ips';
 export type { SimulatorIpName } from './simulator-ips';
 
 // Shared infrastructure management (for test runners)

package/src/network-builder.ts

@@ -140,6 +140,20 @@ export class NetworkBuilder {
     return this;
   }
 
+  /**
+   * Add the Proxmox API simulator on `secure-mgmt`.
+   *
+   * Turns on the only path in the suite that deploys a module through a
+   * `container_service` rather than the machine pool: IPAM allocation, the
+   * deployed-system recording, the infrastructure-variable resolver and the
+   * DNS-ingress reservation. Creating an LXC against it starts a real
+   * container, so what Ansible then configures is a genuinely reachable host.
+   */
+  withProxmoxSim(): this {
+    this.config.proxmoxSim = true;
+    return this;
+  }
+
   /**
    * Add a real, UNLINKED signal-cli daemon on the internal network.
    *

package/src/proxmox-provisioner.test.ts

@@ -0,0 +1,196 @@
+import { describe, expect, test } from 'bun:test';
+/**
+ * The provisioner's logic, with `docker` stubbed — no daemon involved.
+ *
+ * What is worth testing here is everything BEFORE the shell-out: which zone
+ * network a guest lands on, that the container is named so the cleanup sweep
+ * can find it, and that readiness is waited on rather than assumed.
+ */
+import type { GuestRecord } from '@celilo/terraform-fake';
+import {
+  CONTAINER_PREFIX,
+  containerNameFor,
+  createDockerProvisioner,
+  parseNet,
+  zoneForGateway,
+} from './proxmox-provisioner';
+import { ZONE_GATEWAYS, zoneIp } from './types';
+
+/**
+ * Addresses are DERIVED from the zone plan, never written out. A literal here
+ * pins an address to a zone role, and the two drift the moment the plan moves:
+ * an earlier draft of this file paired dmz's gateway with an address from the
+ * app range, and every assertion still passed because they were only ever
+ * compared against each other.
+ */
+const DMZ_ADDRESS = zoneIp('dmz', 13);
+const NET0 = `name=eth0,bridge=vmbr0,gw=${ZONE_GATEWAYS.dmz},ip=${DMZ_ADDRESS}/24,tag=20`;
+
+const guest = (overrides: Record<string, string> = {}): GuestRecord => ({
+  vmid: 203,
+  node: 'pve1',
+  kind: 'lxc',
+  hostname: 'test-host',
+  status: 'running',
+  config: { net0: NET0, ...overrides },
+});
+
+/** Records argv instead of running docker; replies `active` to the readiness poll. */
+function stubDocker() {
+  const calls: string[][] = [];
+  const runner = (args: string[]): string => {
+    calls.push(args);
+    return args.includes('is-active') ? 'active\n' : '';
+  };
+  return { calls, runner, find: (verb: string) => calls.find((c) => c[0] === verb) };
+}
+
+const provisionerWith = (docker: (args: string[]) => string) =>
+  createDockerProvisioner({ project: 'celilo-e2e-test', docker, sleep: async () => {} });
+
+describe('createGuest', () => {
+  test('runs the container on the zone network at the address terraform was given', async () => {
+    const { runner, find } = stubDocker();
+    await provisionerWith(runner).createGuest(guest());
+
+    const run = find('run') ?? [];
+    expect(run).toContain('celilo-e2e-test_dmz');
+    expect(run[run.indexOf('--ip') + 1]).toBe(DMZ_ADDRESS);
+    expect(run.at(-1)).toBe('celilo-e2e/target-machine');
+  });
+
+  test('names the container so the debris sweep can find it', async () => {
+    // cele2e doctor and the by-name cleanup both key off this prefix; an
+    // unprefixed container leaks silently between runs.
+    const { runner, find } = stubDocker();
+    await provisionerWith(runner).createGuest(guest());
+
+    const name = (find('run') ?? [])[(find('run') ?? []).indexOf('--name') + 1];
+    expect(name).toStartWith(CONTAINER_PREFIX);
+    expect(name).toBe('celilo-e2e-lxc-203');
+  });
+
+  test('passes the gateway through, since target-setup routes from it', async () => {
+    const { runner, find } = stubDocker();
+    await provisionerWith(runner).createGuest(guest());
+
+    expect(find('run')).toContain(`GATEWAY=${ZONE_GATEWAYS.dmz}`);
+  });
+
+  test('mounts the ssh-keys volume the machine pool already uses', async () => {
+    const { runner, find } = stubDocker();
+    await provisionerWith(runner).createGuest(guest());
+
+    expect(find('run')).toContain('celilo-e2e-test_ssh-keys:/ssh-keys:ro');
+  });
+
+  test('the app zone gets the dockerd-capable image', async () => {
+    const { runner, find } = stubDocker();
+    const net0 = `name=eth0,gw=${ZONE_GATEWAYS.app},ip=${zoneIp('app', 13)}/24`;
+    await provisionerWith(runner).createGuest(guest({ net0 }));
+
+    expect((find('run') ?? []).at(-1)).toBe('celilo-e2e/target-machine-docker');
+  });
+
+  test('waits for target-setup before returning', async () => {
+    // Returning early lets Ansible race sshd, which surfaces as an
+    // intermittent connection failure several steps later.
+    let ready = false;
+    const calls: string[][] = [];
+    const runner = (args: string[]): string => {
+      calls.push(args);
+      if (!args.includes('is-active')) return '';
+      const answer = ready ? 'active\n' : 'activating\n';
+      ready = true;
+      return answer;
+    };
+    await provisionerWith(runner).createGuest(guest());
+
+    expect(calls.filter((c) => c.includes('is-active')).length).toBe(2);
+  });
+
+  test('gives up rather than hanging when the container never boots', async () => {
+    const runner = (args: string[]): string => {
+      if (args.includes('is-active')) throw new Error('container not running');
+      return '';
+    };
+    const provisioner = createDockerProvisioner({
+      project: 'p',
+      docker: runner,
+      readyTimeoutMs: 0,
+      sleep: async () => {},
+    });
+
+    expect(provisioner.createGuest(guest())).rejects.toThrow('did not go active');
+  });
+
+  test('appends ssh_public_keys AFTER boot, since target-setup overwrites the file', async () => {
+    const { runner, calls } = stubDocker();
+    await provisionerWith(runner).createGuest(
+      guest({ ssh_public_keys: 'ssh-ed25519 AAAAC3 test' }),
+    );
+
+    const append = calls.findIndex((c) => c.join(' ').includes('authorized_keys'));
+    const ready = calls.findIndex((c) => c.includes('is-active'));
+    expect(append).toBeGreaterThan(ready);
+  });
+
+  test('refuses a gateway belonging to no zone rather than guessing one', async () => {
+    const { runner } = stubDocker();
+    const net0 = 'name=eth0,gw=192.0.2.1,ip=192.0.2.10/24';
+
+    expect(provisionerWith(runner).createGuest(guest({ net0 }))).rejects.toThrow('no rig zone');
+  });
+
+  test('refuses a net0 with no address rather than starting an unreachable box', async () => {
+    const { runner } = stubDocker();
+
+    expect(provisionerWith(runner).createGuest(guest({ net0: 'name=eth0' }))).rejects.toThrow(
+      'no gw/ip',
+    );
+  });
+});
+
+describe('destroyGuest', () => {
+  test('removes the container', () => {
+    const { runner, find } = stubDocker();
+    provisionerWith(runner).destroyGuest(guest());
+
+    expect(find('rm')).toEqual(['rm', '-f', 'celilo-e2e-lxc-203']);
+  });
+});
+
+describe('the containment that makes the mounted Docker socket acceptable', () => {
+  test('nothing without the prefix is ever touched', () => {
+    // The simulator can reach every container on the developer's machine. This
+    // is the guard that keeps it to its own (D2).
+    expect(containerNameFor(203)).toStartWith(CONTAINER_PREFIX);
+  });
+});
+
+describe('parseNet', () => {
+  test('unpacks the comma-packed net0 Proxmox uses', () => {
+    expect(parseNet(NET0)).toMatchObject({
+      name: 'eth0',
+      bridge: 'vmbr0',
+      ip: `${DMZ_ADDRESS}/24`,
+      tag: '20',
+    });
+  });
+
+  test('an empty net0 yields nothing rather than throwing', () => {
+    expect(parseNet('')).toEqual({});
+  });
+});
+
+describe('zoneForGateway', () => {
+  test('every rig zone resolves from its own gateway', () => {
+    for (const zone of Object.keys(ZONE_GATEWAYS) as Array<keyof typeof ZONE_GATEWAYS>) {
+      expect(zoneForGateway(ZONE_GATEWAYS[zone])).toBe(zone);
+    }
+  });
+
+  test('an unknown gateway resolves to nothing', () => {
+    expect(zoneForGateway('192.0.2.1')).toBeUndefined();
+  });
+});

package/src/proxmox-provisioner.ts

@@ -0,0 +1,173 @@
+/**
+ * Makes a fake Proxmox LXC into a real, SSH-able Docker container.
+ *
+ * This is the callback `@celilo/terraform-fake` calls on create and destroy.
+ * It lives here rather than in the package because everything it knows —
+ * zone networks, the `target-machine` image, the compose project name — is
+ * rig-specific (D9).
+ *
+ * The container is the SAME image and the SAME boot contract the machine pool
+ * already uses, so a container-service deploy and a machine-pool deploy differ
+ * only in how the host came to exist. `target-setup.service` inside the image
+ * already installs the fleet key from the mounted `ssh-keys` volume, sets the
+ * default route from `GATEWAY`, and points DNS at the resolver — so this
+ * reuses that rather than reimplementing any of it, and readiness is the same
+ * `systemctl is-active target-setup` the harness waits on for machines.
+ */
+import { execFileSync } from 'node:child_process';
+import type { GuestRecord } from '@celilo/terraform-fake';
+import { ZONE_GATEWAYS, type Zone } from './types';
+
+/**
+ * Every container this creates carries the prefix, and it refuses to touch one
+ * that does not.
+ *
+ * Both halves matter. The prefix is what `cele2e doctor` and the by-name
+ * cleanup sweep use to find debris, so an unprefixed container leaks silently
+ * between runs. The refusal is the containment that made mounting the host
+ * Docker socket acceptable (D2): the simulator can reach every container on
+ * the developer's machine, and must only ever act on its own.
+ */
+export const CONTAINER_PREFIX = 'celilo-e2e-';
+
+/** Shells out to `docker`. Injected so the logic is testable without a daemon. */
+export type DockerRunner = (args: string[]) => string;
+
+export const realDocker: DockerRunner = (args) =>
+  execFileSync('docker', args, { encoding: 'utf-8', timeout: 60_000 });
+
+export interface DockerProvisionerOptions {
+  /** Compose project name — networks and volumes are prefixed with it. */
+  project: string;
+  docker?: DockerRunner;
+  /** Poll budget for `target-setup` to go active. Matches the machine-pool wait. */
+  readyTimeoutMs?: number;
+  sleep?: (ms: number) => Promise<void>;
+}
+
+export const containerNameFor = (vmid: number): string => `${CONTAINER_PREFIX}lxc-${vmid}`;
+
+/** Parse Proxmox's comma-packed `net0` into its parts. */
+export function parseNet(net0: string): Record<string, string> {
+  const parts: Record<string, string> = {};
+  for (const pair of net0.split(',')) {
+    const [key, ...rest] = pair.split('=');
+    if (key && rest.length > 0) parts[key] = rest.join('=');
+  }
+  return parts;
+}
+
+/**
+ * Which rig zone a guest belongs to, from the gateway Terraform was given.
+ *
+ * Deliberately keyed off the gateway rather than the VLAN tag: `ZONE_GATEWAYS`
+ * is already the rig's source of truth for zone addressing, so this cannot
+ * drift from it the way a second tag→zone table would.
+ */
+export function zoneForGateway(gateway: string): Zone | undefined {
+  return (Object.keys(ZONE_GATEWAYS) as Zone[]).find((zone) => ZONE_GATEWAYS[zone] === gateway);
+}
+
+export function createDockerProvisioner(options: DockerProvisionerOptions) {
+  const docker = options.docker ?? realDocker;
+  const readyTimeoutMs = options.readyTimeoutMs ?? 60_000;
+  const sleep = options.sleep ?? ((ms: number) => new Promise((r) => setTimeout(r, ms)));
+
+  const assertOurs = (name: string): void => {
+    if (!name.startsWith(CONTAINER_PREFIX)) {
+      throw new Error(`refusing to act on ${name}: not a ${CONTAINER_PREFIX} container`);
+    }
+  };
+
+  return {
+    async createGuest(guest: GuestRecord): Promise<void> {
+      const net = parseNet(guest.config.net0 ?? '');
+      const gateway = net.gw;
+      const cidr = net.ip;
+      if (!gateway || !cidr) {
+        throw new Error(`guest ${guest.vmid} has no gw/ip in net0: ${guest.config.net0}`);
+      }
+
+      const zone = zoneForGateway(gateway);
+      if (!zone) {
+        throw new Error(`no rig zone has gateway ${gateway} (guest ${guest.vmid})`);
+      }
+
+      const name = containerNameFor(guest.vmid);
+      assertOurs(name);
+
+      // Same image selection rule the compose generator uses for machines: the
+      // app zone needs a dockerd-capable box.
+      const image =
+        zone === 'app' ? 'celilo-e2e/target-machine-docker' : 'celilo-e2e/target-machine';
+
+      docker([
+        'run',
+        '-d',
+        '--name',
+        name,
+        '--hostname',
+        guest.hostname,
+        '--network',
+        `${options.project}_${zone}`,
+        '--ip',
+        cidr.split('/')[0] ?? '',
+        '--privileged',
+        '--tmpfs',
+        '/run',
+        '--tmpfs',
+        '/run/lock',
+        '--tmpfs',
+        '/tmp',
+        '-v',
+        `${options.project}_ssh-keys:/ssh-keys:ro`,
+        '-e',
+        `GATEWAY=${gateway}`,
+        image,
+      ]);
+
+      await this.waitUntilReady(name);
+
+      // Proxmox really does honour `ssh_public_keys`, and a module may pass a
+      // key that is not the fleet key in the mounted volume. Appended AFTER
+      // target-setup has run, because that script *copies* authorized_keys
+      // over and would otherwise clobber this.
+      const key = guest.config.ssh_public_keys?.trim();
+      if (key) {
+        docker([
+          'exec',
+          name,
+          'bash',
+          '-c',
+          `mkdir -p /root/.ssh && printf '%s\\n' ${JSON.stringify(key)} >> /root/.ssh/authorized_keys && chmod 600 /root/.ssh/authorized_keys`,
+        ]);
+      }
+    },
+
+    /**
+     * Block until the container's own boot contract says it is ready.
+     *
+     * Reporting the create task OK before this would let Ansible race sshd,
+     * which surfaces as an intermittent connection failure several steps later.
+     */
+    async waitUntilReady(name: string): Promise<void> {
+      const deadline = Date.now() + readyTimeoutMs;
+      while (Date.now() < deadline) {
+        try {
+          const out = docker(['exec', name, 'systemctl', 'is-active', 'target-setup']);
+          if (out.trim() === 'active') return;
+        } catch {
+          // Still booting: `docker exec` fails until systemd is up.
+        }
+        await sleep(500);
+      }
+      throw new Error(`${name} target-setup did not go active within ${readyTimeoutMs}ms`);
+    },
+
+    destroyGuest(guest: GuestRecord): void {
+      const name = containerNameFor(guest.vmid);
+      assertOurs(name);
+      docker(['rm', '-f', name]);
+    },
+  };
+}

package/src/proxmox-sim-compose.test.ts

@@ -0,0 +1,75 @@
+/**
+ * The simulator reaches BOTH generated compose files, or neither.
+ *
+ * Wiring a simulator into one generator and not the other is the standard way
+ * to produce something that works in exactly half the suites — and the half it
+ * fails in is whichever one nobody ran first. These tests are cheap precisely
+ * because that failure is expensive.
+ */
+import { describe, expect, test } from 'bun:test';
+import { generateComposeYaml, generateTestComposeYaml } from './docker-compose-generator';
+import { PROXMOX_SIM_IP } from './simulator-ips';
+import type { NetworkConfig } from './types';
+
+const config = (overrides: Partial<NetworkConfig> = {}): NetworkConfig => ({
+  topology: 'default',
+  dmzMachines: [],
+  appMachines: [],
+  secureMachines: [],
+  internalMachines: [],
+  secureMgmtMachines: [],
+  domain: 'iamtheinternet.org',
+  ddnsPassword: 'test123',
+  verifyRouting: false,
+  managementVolumes: [],
+  dhcpClient: false,
+  signalCli: false,
+  signalSim: false,
+  signalRelease: false,
+  ...overrides,
+});
+
+const GENERATORS: Array<[string, (c: NetworkConfig) => string]> = [
+  ['generateTestComposeYaml', (c) => generateTestComposeYaml(c)],
+  ['generateComposeYaml', (c) => generateComposeYaml(c)],
+];
+
+describe.each(GENERATORS)('%s', (_name, generate) => {
+  test('omits the simulator entirely when it is not asked for', () => {
+    // Every existing suite deploys onto the machine pool. None of them should
+    // pay for a container they do not use.
+    expect(generate(config())).not.toContain('proxmox-sim');
+  });
+
+  test('emits the simulator when enabled', () => {
+    expect(generate(config({ proxmoxSim: true }))).toContain('proxmox-sim');
+  });
+
+  test('puts it on secure-mgmt at the address celilo will be pointed at', () => {
+    // secure-mgmt with celilo-mgr, not a data-plane tier: Proxmox creates the
+    // fleet rather than being consumed by it (D6).
+    const yaml = generate(config({ proxmoxSim: true }));
+
+    expect(yaml).toContain(PROXMOX_SIM_IP);
+    expect(yaml).toContain('secure-mgmt');
+  });
+
+  test('declares the secure-mgmt network it puts the simulator on', () => {
+    // A service on a network the file never declares is a compose error at
+    // `up`, and it reads as a topology problem rather than a missing line.
+    const yaml = generate(config({ proxmoxSim: true }));
+    const networksBlock = yaml.slice(yaml.indexOf('networks:'), yaml.indexOf('services:'));
+
+    expect(networksBlock).toContain('secure-mgmt');
+  });
+
+  test('mounts the Docker socket, since creating an LXC must make a real box', () => {
+    expect(generate(config({ proxmoxSim: true }))).toContain('/var/run/docker.sock');
+  });
+
+  test('passes the compose project through, which names the networks to attach to', () => {
+    // Left to a default, the provisioner would start containers on a network
+    // no test is watching, and the deploy failure would point at DNS.
+    expect(generate(config({ proxmoxSim: true }))).toContain('CELILO_E2E_PROJECT');
+  });
+});

package/src/public-sim-routes.test.ts

@@ -54,6 +54,7 @@ const EVERYTHING: NetworkConfig = {
   signalCli: true,
   signalSim: true,
   signalRelease: true,
+  proxmoxSim: true,
 };
 
 function publicSimulators(yaml: string): Array<{ name: string; dockerfile: string }> {

package/src/registry-bundle.ts

@@ -1,5 +1,5 @@
 /**
- * Bundle helper for the @celilo/registry-server source.
+ * Bundle helpers for sibling-package sources a Dockerfile has to COPY.
  *
  * Why this exists: Dockerfile.registry COPYs from a `registry-server/`
  * directory in its build context. When cele2e runs from inside the
@@ -16,6 +16,15 @@
  *
  * The bundled directory is .gitignored — it's a build artifact, not
  * canonical source. The canonical source remains packages/registry-server.
+ *
+ * The same reasoning applies to @celilo/terraform-fake, which
+ * Dockerfile.proxmox-sim needs, with one addition that is not merely
+ * convenience: the simulator MUST run the workspace copy, not the published
+ * one. Installing it from npm inside the image would mean a PR that changes the
+ * fake is tested against whatever was last released — the "modules run their
+ * bundled copy" trap (celilo#173) in a new place, and silent. It also cannot
+ * work before the first release: `bun install` in the image resolved
+ * `@celilo/terraform-fake@*` against registry.npmjs.org and got a 404.
  */
 
 import { cpSync, existsSync, rmSync } from 'node:fs';
@@ -33,22 +42,40 @@ import { join } from 'node:path';
  *   published incorrectly.
  */
 export function ensureRegistryServerBundle(pkgDir: string): void {
-  const bundle = join(pkgDir, 'registry-server');
-  const upstream = join(pkgDir, '..', 'registry-server');
+  ensureSiblingBundle(pkgDir, 'registry-server', ['package.json', 'tsconfig.json', 'src']);
+}
+
+/**
+ * Ensure <pkgDir>/terraform-fake/ holds the source Dockerfile.proxmox-sim
+ * COPYs, so the simulator runs the fake from THIS checkout.
+ */
+export function ensureTerraformFakeBundle(pkgDir: string): void {
+  ensureSiblingBundle(pkgDir, 'terraform-fake', ['package.json', 'src']);
+}
+
+/**
+ * Copy `entries` from the sibling package `name` into `<pkgDir>/<name>`.
+ *
+ * In the monorepo the bundle is wiped and recopied every time — cheap, and it
+ * means the image can never build from a stale copy. When npm-installed there
+ * is no sibling and the bundle must already have shipped in the tarball; a
+ * missing one is a publish defect, not something to paper over.
+ */
+function ensureSiblingBundle(pkgDir: string, name: string, entries: string[]): void {
+  const bundle = join(pkgDir, name);
+  const upstream = join(pkgDir, '..', name);
 
   if (!existsSync(upstream)) {
     if (!existsSync(bundle)) {
       throw new Error(
-        `cele2e: ${bundle} is missing and ../registry-server doesn't exist either.\nThe @celilo/e2e package was published without its registry-server bundle. Re-publish from infra/scripts/publish.ts so the bundle is recreated.`,
+        `cele2e: ${bundle} is missing and ../${name} doesn't exist either.\nThe @celilo/e2e package was published without its ${name} bundle. Re-publish from infra/scripts/publish.ts so the bundle is recreated.`,
       );
     }
     return; // npm-installed; bundle ships in tarball
   }
 
-  // Monorepo: wipe + copy the canonical source so the bundle is always
-  // fresh. We only need three things — package.json, tsconfig.json, src/.
   rmSync(bundle, { recursive: true, force: true });
-  cpSync(join(upstream, 'package.json'), join(bundle, 'package.json'));
-  cpSync(join(upstream, 'tsconfig.json'), join(bundle, 'tsconfig.json'));
-  cpSync(join(upstream, 'src'), join(bundle, 'src'), { recursive: true });
+  for (const entry of entries) {
+    cpSync(join(upstream, entry), join(bundle, entry), { recursive: true });
+  }
 }

package/src/shared-infra.ts

@@ -18,7 +18,7 @@ import {
   SHARED_PROJECT_NAME,
   generateSharedInfraYaml,
 } from './docker-compose-generator';
-import { ensureRegistryServerBundle } from './registry-bundle';
+import { ensureRegistryServerBundle, ensureTerraformFakeBundle } from './registry-bundle';
 
 const SHARED_COMPOSE_FILE = 'docker-compose.shared.yml';
 const COMPOSE_TIMEOUT = 120_000;
@@ -153,6 +153,9 @@ export async function ensureSharedInfra(): Promise<void> {
   // COPY resolves whether we're in the monorepo (regenerated from the
   // sibling) or installed from npm (already bundled in the tarball).
   ensureRegistryServerBundle(e2eDir);
+  // Same reason, for Dockerfile.proxmox-sim: the simulator runs the fake from
+  // this checkout rather than whatever npm last published.
+  ensureTerraformFakeBundle(e2eDir);
 
   // Generate and write compose file
   const yaml = generateSharedInfraYaml();

package/src/simulator-ips.ts

@@ -1,3 +1,5 @@
+import { zoneIp } from './types';
+
 /**
  * Single source of truth for the IPs of e2e simulator containers on
  * the `internet-external` Docker network.
@@ -71,6 +73,22 @@ export const SIMULATOR_IPS = {
 
 export type SimulatorIpName = keyof typeof SIMULATOR_IPS;
 
+/**
+ * Proxmox API simulator — the one simulator NOT on `internet-external`, and so
+ * deliberately not a member of `SIMULATOR_IPS` above.
+ *
+ * It lives on `secure-mgmt` with celilo-mgr (D6): Proxmox *creates* the fleet
+ * rather than being consumed by it, which makes it control-plane, not a public
+ * internet service. Putting it in the map would also hand it to
+ * `check-simulator-ips.sh`, which scans for the internet-external address
+ * space and would be checking the wrong thing.
+ *
+ * Derived from `zoneIp` rather than written out, so it cannot drift from the
+ * zone plan. `.1` is the gateway and `.100` is celilo-mgr; `90` follows the
+ * convention the other zone-resident simulators use.
+ */
+export const PROXMOX_SIM_IP = zoneIp('secure-mgmt', 90);
+
 /**
  * Iterable list of `[name, ip]` pairs — useful for the sanity check
  * script and any future consumer that wants to enumerate the set.

package/src/types.ts

@@ -68,6 +68,19 @@ export interface NetworkConfig {
   managementVolumes: string[];
   /** Include a DHCP client container on the internal network */
   dhcpClient: boolean;
+  /**
+   * Include the Proxmox API simulator on `secure-mgmt`.
+   *
+   * Turns on the ONLY path in the suite that deploys a module through a
+   * `container_service` rather than the machine pool — IPAM allocation, the
+   * deployed-system recording, the infrastructure-variable resolver and the
+   * DNS-ingress reservation. Optional because it costs a container and a
+   * `service add`, and every existing suite deploys onto the machine pool.
+   *
+   * On `secure-mgmt` with celilo-mgr rather than a data-plane tier: Proxmox
+   * creates the fleet rather than being consumed by it (D6).
+   */
+  proxmoxSim?: boolean;
   /**
    * Include a REAL signal-cli daemon on the internal network.
    *
@@ -454,6 +467,17 @@ export interface ResponderValues {
    * silently approved). Passed straight through to `celilo events respond`.
    */
   aspects?: Record<string, boolean>;
+  /**
+   * Generic interview answers, keyed `<scope>.<key>` (ISS-0127).
+   *
+   * The value's shape follows the question: string for text/select, string[]
+   * for multiselect, boolean for confirm. This is how a command that is neither
+   * a deploy nor a module — `service add proxmox`, say — gets driven headlessly.
+   *
+   * The responder has supported this family since ISS-0127; only this type was
+   * missing it, which made the capability unreachable from a test.
+   */
+  interview?: Record<string, unknown>;
 }
 
 /**