empeira 0.1.0.pre.alpha.4 → 0.1.0.pre.alpha.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4e4e7094658b9e3d8f4ee0edbafa3e4e45be28921900cce8eb4af7d66096cee6
-  data.tar.gz: 7f062dc35a9cef14ad52f55362beba6c4a5a0ab1b57225ce27a191123dc01fc9
+  metadata.gz: 3f0b0c2558d0799e27a8985ab84de156e8de49741ec078965338d0c1638ab0d3
+  data.tar.gz: 5607b7c52a5fb130b7a8534318aecb89c0093709ea7d9b65fcccef86da745fab
 SHA512:
-  metadata.gz: 8410139aeffa1ccaab90f3ddac57a809a86420e385f1354f801f8181c936ecf5653762cc4dbade0178d6df99b2dad1cc8b68cb8d537013132ec09e2ed65aefa1
-  data.tar.gz: 52ba2b37546bc90263d9834193b5080440e2a66425c9f9403b19800e791bf5f26b895d4c4e1af4bc218951b3a0e433437c07c550f493f4577e4e8dfd156a06bb
+  metadata.gz: 5a0eaa2c61a33c12d49632cfa4690f9e369bbae26a1d4cf4f9b1c5ae0d3178d6aed0f14f28721d1a83e1332319b02cf5a899f8f31287b88816b2e2e7ba3e8366
+  data.tar.gz: ed8ab5306f5948ed1f81c8e1b00121cb6360490e35daf915b95c441a42174552320b08fcc37a193eb2e1011b694eb1f85932739df3ee0d2274b182fded0b6957

data/config/defaults.yaml

@@ -50,12 +50,19 @@ puppetdb:
       bootstrap_config: /etc/puppetlabs/puppetdb/bootstrap.cfg
       data: /opt/puppetlabs/server/data/puppetdb
 network:
-  egress: []
+  egress:
+    nodes: []
+    infrastructure: []
   redirects: []
 proxy:
-  enabled: false
-  global: []
-  rules: []
+  memory: 512
+  nodes:
+    enabled: false
+    global: []
+    rules: []
+  infrastructure:
+    enabled: false
+    allow: []
 vm:
   disk: 30
   interfaces: []

data/docs/addons.md

@@ -208,8 +208,12 @@ Array elements can be mappings, arrays or scalars. For example:
 
 ```yaml
 proxy:
-  enabled: true
-  global: [forge.puppet.com, github.com]
+  nodes:
+    enabled: true
+    global: [forge.puppet.com, github.com]
+  infrastructure:
+    enabled: false
+    allow: []
 server:
   mounts:
     - source: /home/user/data
@@ -217,10 +221,10 @@ server:
       readonly: true
 ```
 
-produces `EMPEIRA_CONFIG_PROXY_ENABLED=true`,
-`EMPEIRA_CONFIG_PROXY_GLOBAL_COUNT=2`,
-`EMPEIRA_CONFIG_PROXY_GLOBAL_0=forge.puppet.com`,
-`EMPEIRA_CONFIG_PROXY_GLOBAL_1=github.com`,
+produces `EMPEIRA_CONFIG_PROXY_NODES_ENABLED=true`,
+`EMPEIRA_CONFIG_PROXY_NODES_GLOBAL_COUNT=2`,
+`EMPEIRA_CONFIG_PROXY_NODES_GLOBAL_0=forge.puppet.com`,
+`EMPEIRA_CONFIG_PROXY_NODES_GLOBAL_1=github.com`,
 `EMPEIRA_CONFIG_SERVER_MOUNTS_COUNT=1`, and the variables
 `EMPEIRA_CONFIG_SERVER_MOUNTS_0_SOURCE`, `_TARGET`, `_READONLY`.
 

data/docs/architecture.md

@@ -93,6 +93,24 @@ system SSH. Guest commands use argument arrays and owned process groups; stdout
 and stderr stream in bounded frames without truncation. Timeouts, interrupts and
 host disconnects terminate those groups. Binary uploads are SHA-256 verified,
 staged privately and atomically installed in the real guest filesystem.
+The management supervisor and workers retain `umask 077`, private 0700 staging and
+explicit upload modes. Only executed commands (including Puppet and its children)
+and PTY shells start with `umask 022`. Previously the worker's private mask leaked
+into these children, causing ordinary file/directory creation to yield 0600/0700;
+APT could not read public keys created by commands that omitted an explicit mode.
+Commands still run as numeric root, and explicit private modes remain private.
+Empeira's native APT acquisition already copies its own signing key with mode 0644
+under `/var/tmp`; it does not create project repository keys under
+`/usr/share/keyrings` or `/etc/apt/keyrings`.
+
+This correction applies to newly seeded VMs. Recreate disposable existing VMs to
+receive the updated adapter; `up` does not replace seeded management code or repair
+existing files. No directory-wide chmod or post-Puppet keyring rewrite is performed.
+A catalog explicitly setting mode 0600, or a tool using private temporary files,
+still needs correction at its owning resource. Project-managed public APT keys
+should specify root:root and 0644, with searchable parent directories. The reported
+Docker/Elastic/project key names are absent from Empeira's source; their exact
+catalog resources require inspection in the affected project.
 
 The QEMU monitor verifies workspace/node/instance identity before management.
 A 0700 host directory and 0600 Unix socket restrict access; recorded device/inode

data/docs/configuration.md

@@ -107,9 +107,15 @@ runtime:
 server:
   environment: production
 network:
-  egress: []
+  egress:
+    nodes: []
+    infrastructure: []
 proxy:
-  enabled: false
+  nodes:
+    enabled: false
+  infrastructure:
+    enabled: false
+    allow: []
 node_defaults:
   os: ubuntu
   version: "24.04"
@@ -150,11 +156,15 @@ release version. A partial project mapping may omit it and inherit the default.
 | `server.timeout` | Positive readiness timeout in seconds per component, `240` |
 | `server.mounts` | Additional server-only host bind mounts, `[]`; `source`, `target`, optional boolean `readonly` (default `true`) |
 | `puppetdb.memory` | Positive integer MiB, `768` |
-| `network.egress` | Direct TCP proxy-bypass host/port entries, `[]`; a project array replaces the default array |
+| `network.egress.nodes` | Node-only direct TCP host/port grants, `[]`; arrays replace |
+| `network.egress.infrastructure` | Infrastructure-only direct TCP host/port grants, `[]`; arrays replace |
 | `network.redirects` | Exact IPv4/protocol/port endpoints redirected to enabled internal services, `[]` |
-| `proxy.enabled` | Boolean, `false`; creates the normal HTTP/HTTPS policy proxy |
-| `proxy.global` | DNS destination array, `[]` |
-| `proxy.rules` | Additive hostname-glob rules with `hosts` and `allow` arrays, `[]` |
+| `proxy.memory` | Positive integer MiB, `512` per Squid container; shared regular proxy and separate temporary bootstrap proxy each use this limit; does not enable either proxy |
+| `proxy.nodes.enabled` | Boolean, `false`; enables normal node HTTP/HTTPS proxy access |
+| `proxy.nodes.global` | DNS destination array, `[]` |
+| `proxy.nodes.rules` | Additive node hostname-glob rules with `hosts` and `allow` arrays, `[]` |
+| `proxy.infrastructure.enabled` | Boolean, `false`; enables infrastructure HTTP/HTTPS proxy access |
+| `proxy.infrastructure.allow` | Independent infrastructure DNS destination array, `[]` |
 | `vm.disk` | New VM virtual disk capacity in GiB, integer `1`–`2048`, default `30`; must accommodate the base image |
 | `vm.interfaces` | VM-only hostname rules defining dummy/VLAN devices with explicit IPv4 CIDR host addresses, `[]` |
 | `vm.console.root_password` | Initial console password, `empeira`; a string overrides it and `null` disables it |
@@ -488,14 +498,20 @@ The numeric gem packaging fallback is never used to bypass this check.
 ```yaml
 network:
   egress:
-    - host: api.example.com
-      ports: [443]
+    nodes:
+      - host: api.example.com
+        ports: [443]
+    infrastructure: []
 proxy:
-  enabled: true
-  global: [forgeapi.puppet.com]
-  rules:
-    - hosts: ["*-web-*"]
-      allow: [github.com, "*.github.com"]
+  nodes:
+    enabled: true
+    global: [forgeapi.puppet.com]
+    rules:
+      - hosts: ["*-web-*"]
+        allow: [github.com, "*.github.com"]
+  infrastructure:
+    enabled: false
+    allow: []
 hiera:
   mounts:
     - source: ../hieradata
@@ -507,7 +523,12 @@ vm:
     root_password: null
 ```
 
-When `proxy.enabled` is true, every node may use its matching destination policy.
+When `proxy.nodes.enabled` is true, every node may use its matching destination policy.
+Infrastructure access is separately controlled by `proxy.infrastructure.enabled`
+and `proxy.infrastructure.allow`; both scopes default to disabled. Disabled
+infrastructure has no configured proxy endpoint even when nodes use the proxy.
+Keep its direct-egress list empty for internal-only infrastructure. See the
+[migration instructions](proxy.md#migrating-shared-settings) for former shared keys.
 After bootstrap cleanup, Empeira reconciles normal proxy settings on running,
 provisioned nodes during `up` and `node start`. Repeated Puppet runs use the
 existing guest configuration. No
@@ -719,21 +740,24 @@ desired state; Puppet owns package state after the first catalog.
 
 ## Direct egress
 
-`network.egress` contains destination TCP grants, independent of HTTP/HTTPS proxy
-policy. Entries have exactly one `host` or IPv4 `ip` and a nonempty unique `ports`
+`network.egress.nodes` and `network.egress.infrastructure` contain separate
+destination TCP grants, independent of HTTP/HTTPS proxy policy. A node grant never
+applies to infrastructure or conversely. Entries have exactly one `host` or IPv4 `ip` and a nonempty unique `ports`
 array (1–65535). `up` resolves all A records and replaces the complete policy;
 resolution/apply failure blocks egress. IPv6 and external UDP grants are unsupported.
 
 ```yaml
 network:
   egress:
-    - host: repository.example.net
-      ports: [443]
-    - ip: 203.0.113.10
-      ports: [443, 8443]
+    nodes:
+      - host: repository.example.net
+        ports: [443]
+      - ip: 203.0.113.10
+        ports: [443, 8443]
+    infrastructure: []
 ```
 
-Named direct destinations enter generated `NO_PROXY`; applications choose DIRECT
+Direct destinations enter only their own scope's generated `NO_PROXY`; applications choose DIRECT
 or proxy themselves. See [networking](networking.md#one-gateway-one-direct-egress-policy)
 for routing, revocation and privilege boundaries.
 
@@ -765,7 +789,7 @@ vm:
           network: 192.0.2.20/32
 ```
 
-Patterns use the same `*`/`?` glob matcher as `proxy.rules`, against the full stored
+Patterns use the same `*`/`?` glob matcher as `proxy.nodes.rules`, against the full stored
 node hostname, case-insensitively. Patterns within a rule are alternatives. All
 matching rules contribute devices; identical definitions merge once. A conflicting
 definition names the hostname, device and both configuration paths. No match creates
@@ -947,7 +971,10 @@ The default control plane has six containers, or seven with the proxy, plus the
 runtime's peer-network adapter. Requested limits
 are 1536 MiB for the server (768 MiB JVM heap), 768 MiB for PuppetDB (256 MiB heap),
 256 MiB for PostgreSQL, 64 MiB for DNS, 96 MiB for the database relay, 64 MiB
-for the gateway and 128 MiB for Squid. The control-plane memory ceiling is about
+for the gateway and 512 MiB for the regular Squid proxy (`proxy.memory`). A temporary
+bootstrap Squid container has its own additional limit of the same size while
+running. These are per-container limits, not reservations or measured peaks.
+The control-plane memory ceiling is about
 2.7 GiB without the proxy, excluding the peer adapter and nodes. The server gets two CPUs and each
 other service one. Actual idle use is lower and varies by provider and platform.
 `up` automatically pulls missing remote images and builds missing recipe images.

data/docs/hiera-and-eyaml.md

@@ -207,8 +207,8 @@ The obsolete `images.modules` key is rejected.
 The disposable installer belongs to the update plane. It uses the selected
 runtime's normal bridge network (`bridge` on Docker, `podman` on Podman), with
 normal runtime DNS and external connectivity. It never joins an Empeira workspace
-network and needs neither CoreDNS nor Squid. Workspace `network.egress`, `proxy.enabled`,
-`proxy.global` and `proxy.rules` do not affect
+network and needs neither CoreDNS nor Squid. Workspace `network.egress`, `proxy.nodes.enabled`,
+`proxy.nodes.global` and `proxy.nodes.rules` do not affect
 Forge or Git acquisition. Supplied `HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY` and their
 lowercase equivalents are inherited unchanged; Empeira generates no proxy URL.
 The host/runtime's normal network and corporate-proxy configuration must permit

data/docs/networking.md

@@ -102,17 +102,26 @@ Every peer uses the owned gateway as its IPv4 default route. Only the gateway ha
 an external uplink; DNS, proxies, server, database and nodes stay isolated.
 The fixed browser UI relay has a separate loopback access path with forwarding off.
 
-`network.egress` grants destination IPv4/TCP-port pairs:
+`network.egress.nodes` and `network.egress.infrastructure` grant destination
+IPv4/TCP-port pairs independently:
 
 ```yaml
 network:
   egress:
-    - host: repository.example.net
-      ports: [443]
-    - ip: 203.0.113.10
-      ports: [443, 8443]
+    nodes:
+      - host: repository.example.net
+        ports: [443]
+      - ip: 203.0.113.10
+        ports: [443, 8443]
+    infrastructure: []
 ```
 
+The gateway restricts node grants to the reserved VM/container node address ranges
+and infrastructure grants to its separate runtime allocation pool. Both directions
+of direct connections are source-bound. The shared workspace subnet is never used
+as a blanket source for direct grants. Custom gateway images must advertise
+`scoped-egress-v1`; an older image fails closed before receiving external access.
+
 Entries have exactly one `host` or `ip`. Hostnames match exactly, without wildcards;
 `up` resolves every current A record and replaces the complete policy. IP selectors
 bypass DNS and may intentionally permit private LAN/VPN destinations. A different
@@ -128,9 +137,9 @@ CoreDNS alone receives TCP/UDP 53 to its selected resolvers. Proxies alone recei
 TCP 80/443 and enforce their destination allowlists. Normal proxy allow rules apply
 regardless of target IP range; the temporary authenticated bootstrap proxy retains
 its separate private/reserved-address restrictions.
-`proxy.global` does not grant direct egress. Applications choose DIRECT/proxy using
+`proxy.nodes.global` does not grant direct egress. Applications choose DIRECT/proxy using
 their own settings and `NO_PROXY`; direct/proxy selection has no automatic fallback.
-Both explicit hostnames and IPv4 selectors from `network.egress` are included in
+Both explicit hostnames and IPv4 selectors are included only in their own scope's
 normal proxy bypass settings. The gateway still permits only their configured TCP ports.
 See [proxy policy](proxy.md) for hostname rules and bootstrap destinations.
 

data/docs/nodes.md

@@ -296,12 +296,18 @@ Empeira uses the private privileged VirtIO channel internally to install the VM
 enroll certificates and run Puppet. User-facing SSH opens an ordinary interactive
 login without the internal provisioning command or automatic sudo.
 
-VM exec, shell, SSH and serial sessions release the workspace mutation lock after ownership and
-running-state checks. Parallel sessions and read-only status remain available. A
+Container SSH and VM exec, shell, SSH and serial sessions release the workspace
+mutation lock after ownership and running-state checks. Parallel sessions and read-only status remain available. A
 shared instance guard prevents `node stop`, `node destroy` or restart from replacing
-the VM while a session is attached; detach first and retry the conflicting operation.
+that node instance while a session is attached; detach first and retry the conflicting operation.
 Other nodes and workspace commands can proceed. Instance lock files stay stable;
 their open descriptors are released on detach, disconnect, errors and signals.
+Container SSH preparation remains inside the workspace transaction and pins the
+observed container ID before releasing that lock. Concurrent SSH sessions to the
+same or different nodes are allowed. Container `exec` and `shell` retain their
+existing workspace transaction. Mutations still use the exclusive workspace lock;
+`down` continues to require node removal, and destroy retains attached instances
+for a retry after sessions detach.
 
 ## Root diagnostic commands and interactive shell
 

data/docs/proxy.md

@@ -1,19 +1,24 @@
 # Proxy policy
 
-Normal external HTTP/HTTPS access stays behind Squid. Enabling the workspace proxy
-makes it available to every node; global and hostname rules remain the destination
-allowlist:
+Normal external HTTP/HTTPS access stays behind Squid. Nodes and infrastructure
+have independent switches and destination lists, both disabled by default. Enabling
+the node scope makes its global and hostname rules available to nodes:
 
 ```yaml
 proxy:
-  enabled: true
-  global:
-    - forgeapi.puppet.com
-  rules:
-    - hosts: ["lab-*"]
-      allow: ["*.github.com"]
-    - hosts: ["*-web-*"]
-      allow: [github.com, nginx.org]
+  memory: 512 # MiB per regular or temporary bootstrap Squid container
+  nodes:
+    enabled: true
+    global:
+      - forgeapi.puppet.com
+    rules:
+      - hosts: ["lab-*"]
+        allow: ["*.github.com"]
+      - hosts: ["*-web-*"]
+        allow: [github.com, nginx.org]
+  infrastructure:
+    enabled: false
+    allow: []
 ```
 
 ```console
@@ -44,9 +49,60 @@ The diagnostic resolves desired policy even for a hostname that does not exist.
 It reports when the normal proxy is disabled and does not claim that live
 infrastructure has already been reconciled.
 
+## Memory budget and startup diagnostics
+
+`proxy.memory` is a positive integer MiB limit per managed Squid container,
+defaulting to 512. Node access and infrastructure access share one regular proxy;
+the same limit applies when either or both scopes are enabled. The temporary,
+authenticated bootstrap proxy inherits this value as its own container limit.
+If both containers run simultaneously, each has a separate 512 MiB limit by
+default (1024 MiB combined), not one shared 512 MiB budget. These limits are
+neither memory reservations nor measured peak consumption.
+
+Existing configurations inherit the default. Setting `proxy.memory` alone does
+not enable a regular proxy or start a bootstrap proxy. Node and infrastructure
+access keep independent activation switches and destination grants. Bootstrap
+keeps its separate temporary activation, authentication and destination grants.
+Docker and Podman use the same native
+`--memory` argument, including rootless Podman. The engine host (or its Linux VM on
+macOS) still needs enough available memory and working cgroup memory controls.
+
+The former fixed 128 MiB limit was below the reported killed process's approximately
+139 MiB resident footprint (anonymous plus file RSS), before accounting for other
+cgroup charges. The 512 MiB default provides headroom for startup, concurrent
+requests, DNS and allocator overhead. It is a conservative budget, not a measured
+maximum or a guarantee for arbitrary workloads. Validate actual peak usage with
+native container stats and host cgroup/OOM diagnostics in the affected environment.
+
+Generated policy keeps `cache deny all`, sets `cache_mem 16 MB`, and explicitly uses
+`workers 1` together with `-N` for one foreground main process. An explicit
+`workers 0` causes Squid 7.7 to exit during startup with
+`FATAL: check failed: theProcessCount > 0`; `-N` already selects foreground mode.
+No disk cache is configured. Squid's [cache_mem documentation](https://www.squid-cache.org/Doc/config/cache_mem/)
+describes an object-memory target, not a cap on process RSS; in-flight requests can
+exceed it. The [workers setting](https://www.squid-cache.org/Doc/config/workers/)
+avoids multiplying main-process memory. These settings preserve DNS, source-bound
+client rules and the HTTP/HTTPS destination policy.
+
+If the regular proxy exits during startup or its readiness check, diagnostics
+include the native exit code, `OOMKilled` observation and actual inspected memory
+limit in bytes/MiB when available. Only `OOMKilled=true` confirms an OOM kill. Exit 137 alone does not:
+external SIGKILL can produce the same exit. Missing observations are explicitly
+reported as unavailable, and a runtime-reported zero limit is shown as unlimited.
+For confirmed proxy OOM, increase `proxy.memory`, check engine-host capacity, and
+run `empeira up`. Native logs remain available via the displayed runtime command.
+The temporary bootstrap proxy uses its own endpoint verification and readiness
+probe; the new regular-proxy OOM diagnostics do not apply to that separate path.
+
+A memory change replaces only the regular proxy on the next `up`; CA/database
+storage, nodes and unrelated services retain their identities. Unchanged runs
+reuse the proxy. Generated policy changes use the existing readiness/reload checkpoint.
+Replacing or reloading the proxy may interrupt active proxy connections.
+The next temporary bootstrap proxy receives the configured limit when created.
+
 ## Matching and destinations
 
-Defaults are `proxy.global: []` and `proxy.rules: []`. Every node receives
+Defaults are `proxy.nodes.global: []` and `proxy.nodes.rules: []`. Every node receives
 all global destinations plus `allow` from **every** matching rule. Duplicate entries
 are removed while preserving configuration order. A rule matches when any of its
 `hosts` patterns matches the complete lowercase hostname. Patterns must be lowercase.
@@ -66,14 +122,14 @@ Destination rules are separate from hostname globs:
 Only HTTP port 80 and HTTPS CONNECT port 443 are allowed. Allowed DNS destinations
 are reachable regardless of their target IP range, including private, loopback,
 link-local and reserved addresses. Domains without a matching allow rule remain
-denied. There is no TLS interception. Server-side outbound traffic gets
-`proxy.global` only; node hostname rules do not expand server access.
+denied. There is no TLS interception. Node destinations never grant infrastructure
+access, and infrastructure destinations never grant node access.
 
 ## Node policy and reconciliation
 
-When `proxy.enabled` is true, all nodes are authorized as proxy clients. Nodes get
+When `proxy.nodes.enabled` is true, all nodes are authorized as proxy clients. Nodes get
 upper/lowercase proxy variables and internal `NO_PROXY` entries, including explicitly
-configured `network.egress` hosts. Those named hosts use the common workspace
+configured `network.egress.nodes` hosts. Those named hosts use the common workspace
 gateway for their configured ports. VM access uses the same destination policy bound
 directly to the VM instance's reserved peer address. The proxy is reached at
 `proxy.empeira.internal:3128` on the isolated network. A request without a matching
@@ -90,17 +146,56 @@ Container and VM nodes consume the new policy without a restart; open proxy
 connections can end during reconciliation. Enabling/disabling proxy mode is a
 separate topology change and may require explicit node cleanup as reported by `up`.
 
-Changing direct-egress destinations also changes the server's `NO_PROXY`
-environment. `up` replaces a server whose environment definition changes while
+Changing `network.egress.infrastructure` destinations also changes infrastructure
+`NO_PROXY`. Changing node destinations does not change the server environment. `up` replaces a server whose environment definition changes while
 retaining CA storage and node identities. Changing only destination ports or
 transparent redirect rules preserves the server when its definition is unchanged.
 
+## Infrastructure policy
+
+`proxy.infrastructure.enabled` controls the Puppet/OpenVox server, PostgreSQL,
+PuppetDB backend/relay and `containers.additional` services. Its independent
+`allow` list uses the same exact-domain and domain-family syntax as node grants.
+The browser, DNS, Squid and gateway transports do not receive these application
+proxy settings.
+
+```yaml
+proxy:
+  infrastructure:
+    enabled: true
+    allow: [api.example.net]
+```
+
+When disabled, infrastructure definitions contain empty proxy values, overriding
+any image defaults. They contain no configured proxy endpoint and receive no Squid
+client grants, even if the node proxy is enabled. No startup wrapper removes an
+otherwise configured proxy. Internal names and mocks remain directly reachable.
+When enabled, only infrastructure's own direct destinations enter its `NO_PROXY`.
+Explicit environment settings in additional-service definitions remain application
+configuration; they do not add Squid permissions.
+
+`up` creates the shared normal proxy when either scope is enabled and removes it
+when both are disabled. Changing infrastructure's switch updates affected service
+definitions while retaining storage and node identities. Allowlist-only edits reload
+Squid without replacing unrelated services. Direct grants remain independent of
+both proxy switches; keep `network.egress.infrastructure: []` for internal-only
+infrastructure.
+
+## Migrating shared settings
+
+The former `proxy.enabled`, `proxy.global` and `proxy.rules` keys are rejected with
+a migration diagnostic. Move them under `proxy.nodes`; configure infrastructure
+explicitly with its own switch and `allow` list. Old shared `network.egress` arrays
+and legacy `mode` values are also rejected. Move grants to `network.egress.nodes`
+or `network.egress.infrastructure` according to the intended clients. No existing
+grant is silently copied to infrastructure.
+
 ## Managed bootstrap
 
 Managed bootstrap destinations are separate from normal user policy. Reviewed
 agent and distribution endpoints in `agent.install` and `bootstrap.guests` allow
 Puppet/OpenVox and required guest packages to be installed without duplicating them
-in `proxy.global`. The temporary authenticated bootstrap proxy uses workspace DNS
+in `proxy.nodes.global`. The temporary authenticated bootstrap proxy uses workspace DNS
 and retains its private, loopback, link-local and reserved destination-address
 restrictions independently of normal proxy policy. Its credential is not stored in
 the guest seed, JSON inventory or logs. A /32 source ACL admits only the provisioning

data/docs/troubleshooting.md

@@ -132,7 +132,7 @@ or restart of that same VM conflicts with the shared instance guard: detach with
 ## Proxy destination denied
 
 Run `empeira proxy show HOSTNAME` and check every matching rule. Verify the node
-exists in the workspace, `proxy.enabled` is true, and `up` has reconciled the
+exists in the workspace, `proxy.nodes.enabled` is true, and `up` has reconciled the
 configuration and current node addresses. Allowed DNS destinations may resolve to
 private or reserved IP addresses; only HTTP port 80 and HTTPS CONNECT port 443 are
 permitted. After updating Empeira, run `empeira up` to replace a proxy still using
@@ -367,6 +367,6 @@ external runtime network as a workaround. Docker workspace bridge attachment
 errors require an accessible Linux-engine host namespace and an identifiable
 iptables backend. The helper changes only owned bridge rules. Do not disable the
 host firewall globally. Check Docker Desktop host-network restrictions separately.
-Proxy errors require checking Squid source bindings and `proxy.global`/`proxy.rules`,
+Proxy errors require checking Squid source bindings and `proxy.nodes.global`/`proxy.nodes.rules`,
 not adding unrelated direct grants. Corporate DNS still follows host discovery;
 IPv6-only upstreams must be replaced with reachable IPv4 resolvers for this backend.

data/lib/empeira/build.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.1.0-alpha.4",
-  "revision": "b073c6a15db14c4dace4a732703240f4289cbb48",
-  "build_time": "2026-10-21T11:41:02Z"
+  "version": "0.1.0-alpha.7",
+  "revision": "16b913976904b1abadca0ba55d571039e762b997",
+  "build_time": "2026-11-13T14:35:59Z"
 }

data/lib/empeira/cli/proxy.rb

@@ -5,7 +5,7 @@ module Empeira
     class Proxy < Base
       desc 'show HOSTNAME', 'Explain the normal proxy destination policy for a hostname'
       def show(hostname)
-        config = application.context.configuration.fetch('proxy')
+        config = application.context.configuration.dig('proxy', 'nodes')
         resolver = Network::HostPolicy.new(config)
         say "Effective proxy policy for #{hostname.downcase}"
         say access_message(config)
@@ -19,7 +19,7 @@ module Empeira
           return "All workspace nodes may use this policy after 'empeira up' reconciles the proxy." if
             config.fetch('enabled')
 
-          'The normal workspace proxy is disabled.'
+          'The normal node proxy is disabled.'
         end
 
         def display_matches(rules)

data/lib/empeira/configuration/schema.rb

@@ -20,8 +20,11 @@ module Empeira
                       'environment' => :environment,
                       'memory' => :positive_integer, 'cpus' => :positive_integer, 'timeout' => :positive_integer },
         'puppetdb' => { 'enabled' => :boolean, 'memory' => :positive_integer, 'runtime' => :puppetdb_runtime },
-        'network' => { 'egress' => :network_egress, 'redirects' => :network_redirects },
-        'proxy' => { 'enabled' => :boolean, 'global' => :allowlist, 'rules' => :proxy_rules },
+        'network' => { 'egress' => { 'nodes' => :network_egress, 'infrastructure' => :network_egress },
+                       'redirects' => :network_redirects },
+        'proxy' => { 'memory' => :positive_integer,
+                     'nodes' => { 'enabled' => :boolean, 'global' => :allowlist, 'rules' => :proxy_rules },
+                     'infrastructure' => { 'enabled' => :boolean, 'allow' => :allowlist } },
         'vm' => { 'disk' => :vm_disk, 'interfaces' => :vm_interfaces,
                   'console' => { 'root_password' => :optional_string } },
         'dns' => { 'upstream' => { 'mode' => :dns_mode, 'servers' => :dns_servers },
@@ -116,12 +119,35 @@ module Empeira
       end
 
       def validate_fragment!(data)
+        validate_scope_migration!(data)
         validate_mapping!(data, RULES, [])
         data
       end
 
       private
 
+      def validate_scope_migration!(data)
+        return unless data.is_a?(Hash)
+
+        validate_proxy_scope_migration!(data['proxy'])
+        network = data['network']
+        validate_egress_scope_migration!(network['egress']) if network.is_a?(Hash)
+      end
+
+      def validate_proxy_scope_migration!(proxy)
+        return unless proxy.is_a?(Hash) && proxy.keys.intersect?(%w[enabled global rules])
+
+        raise ConfigurationError, 'Shared proxy settings have moved to proxy.nodes; configure ' \
+                                  'proxy.infrastructure separately'
+      end
+
+      def validate_egress_scope_migration!(egress)
+        return unless egress.is_a?(Array) || (egress.is_a?(Hash) && egress.key?('mode'))
+
+        raise ConfigurationError, 'Shared network.egress grants must be moved explicitly to ' \
+                                  'network.egress.nodes or network.egress.infrastructure'
+      end
+
       def validate_operational!(data)
         validate_images!(data.fetch('images'))
         NodeImages.effective!(data.fetch('images'))

data/lib/empeira/control_plane/controller.rb

@@ -254,8 +254,10 @@ module Empeira
       end
 
       def resolve_direct_egress
-        config = @plan.config.dig('network', 'egress')
-        @direct_resolver.resolve(config)
+        entries = @plan.config.dig('network', 'egress').flat_map do |scope, grants|
+          @direct_resolver.resolve(grants).entries.map { |entry| entry.merge('scope' => scope) }
+        end
+        Network::DirectEgress::Resolved.new(entries)
       end
 
       def bootstrap_dns?(upstreams:, routes:)
@@ -526,8 +528,7 @@ module Empeira
       def require_started!(key, resource)
         return if resource.fetch('state') == 'running'
 
-        raise Error, "Managed service #{key} is #{resource.fetch('state')} after start; " \
-                     "inspect #{@context.container_engine} logs #{resource.fetch('id')}"
+        raise StartupFailure.new(key: key, resource: resource, engine: @context.container_engine)
       end
 
       def update_hosts(reload_proxy: false)
@@ -636,6 +637,7 @@ module Empeira
         end
         reconcile('gateway')
         lockdown_gateway(@observed.fetch('gateway'))
+        require_scoped_egress_capability
         require_redirect_capability
         attach_gateway('gateway')
         apply_gateway_policy
@@ -668,6 +670,16 @@ module Empeira
                      'images.direct_egress image'
       end
 
+      def require_scoped_egress_capability
+        return if @gateway_plan.fetch('entries').empty?
+
+        result = @runtime.service_exec(@observed.fetch('gateway'),
+                                       [Network::Gateway::EXECUTABLE, 'scoped-egress-capability'])
+        return if result.success? && result.stdout.strip == 'scoped-egress-v1'
+
+        raise Error, 'Gateway does not support scoped direct egress; configure a compatible images.direct_egress image'
+      end
+
       def apply_gateway_policy
         # An uncertain apply must force fresh lockdown during failure recovery.
         @gateway_locked_id = nil