Using Écluse: the operator manual

This is the operator manual for deploying and running Écluse: how to configure it, connect clients, and fence its network egress. It's the companion to the internal architecture documents, which carry the why.

Status: pre-launch. Écluse is under active development. This manual is the configuration and operational contract: the env vars, the config schema, the client setup, and the security responsibilities. Features still landing are marked (planned).

Contents

• What Écluse does
• Deployment model
• The two-variable start (serve-only gate)
• The Golden Path
• Deviating from the Golden Path
• Configuration
  • Environment variables
  • The configuration document
  • Secrets
• Connecting your clients
• Securing network egress (required)
• Locking down CI egress (recommended)
• Rule policy
• Operating Écluse
• Planned controls
• Appendix: runtime-sizing arithmetic
• Learn more

What Écluse does

Écluse sits between your build (developer machine or CI) and the upstream registry and applies a deny-by-default policy before any package reaches a build. It reads through a private upstream first, falls back to the gated public registry, and mirrors approved packages asynchronously. It's a policy gate, not a registry, and hosts nothing itself. npm is the first supported ecosystem; the engine is ecosystem-agnostic, with PyPI on the roadmap. The design is in docs/architecture.md.

Deployment model

Écluse ships as one reproducible container image, a multicall executable selected by the container command:

• ecluse proxy (default): the HTTP proxy on ECLUSE_SERVER__PORT (default 8080) plus the mirror worker.
• ecluse pilot: the OSV advisory ingestion pipeline.
• ecluse dredger: the registry cleanup (reaper) worker.
• ecluse check-config: validates the shared configuration exactly as a boot would and prints the whole resolved posture without starting anything (exit 0 valid, 2 refused). Run it in CI or before a rollout.

All roles share one config file and rule set. The proxy scales horizontally behind a load balancer, but Pilot and Dredger must run as singletons: multiple instances race, duplicate API calls, and overlap registry deletions.

ecluse pilot compile --out DIR runs one OSV compilation and exits: it fetches an ecosystem's advisory export (--ecosystem, default npm; --source URL overrides the configured advisories.osvExportBaseUrl) and writes <ecosystem>-osv-schema<N>.db (e.g. npm-osv-schema3.db) into DIR, exiting non-zero on failure. --upload also publishes the artifact to the advisory bucket, a full sync cycle in one invocation, and aborts immediately without a configured bucket. A systemically corrupt or truncated export aborts the compile without publishing, so a running proxy keeps its last-good database rather than adopt one that silently omits advisories.

Point your package manager at the proxy as a registry (see Connecting your clients). Before running a published image, verify its provenance and SBOM attestations; the recipe is in the README.

The two-variable start (serve-only gate)

The fastest way to put the gate in front of real installs is a serve-only deployment: no mirror, no queue, no cloud account, just the gated public leg.

ECLUSE_MOUNTS__NPM__ENABLED=true \
ECLUSE_SERVER__PUBLIC_URL=http://127.0.0.1:8080 \
ecluse proxy

Every rule, advisory gate, integrity floor, and egress control applies exactly as on a mirrored deployment; the only thing missing is the mirror write. The trade: the public leg is permanent, availability stays coupled to the public registry, and no mirrored copy survives an upstream yank. Use it to evaluate the gate, then graduate to the Golden Path by declaring a mirrorTarget.

The Golden Path

This is the recommended, most resilient way to run Écluse, and the posture the threat model treats as canonical. Aim for it unless you have a specific reason to diverge.

1. Run three registries, not one. Give the three internal roles distinct backends: a first-party store (publication target), a public-derived mirror store (mirror target), and a pull-through read endpoint that unions both (ECLUSE_MOUNTS__NPM__PRIVATE_UPSTREAM). Separating provenance keeps the mirror auditable. The one hard rule: the aggregating endpoint must union trusted stores only, never a direct public upstream, or raw ungated packages reach clients as trusted and bypass the gate. See registry-level composition.
2. Let callers use their own identity. The default forwards each caller's credential to the private upstream and publication target, so access matches your registry IAM exactly and Écluse holds no standing read credential. Nothing to set. See access model.
3. Mint the mirror-write token from the container role. Point ECLUSE_MOUNTS__NPM__MIRROR_TARGET at a CodeArtifact endpoint so the worker mints a short-lived token under the task/instance role instead of carrying a static secret. Scope that role write-only to the mirror store and keep ECLUSE_MOUNTS__NPM__MIRROR_CODE_ARTIFACT_TOKEN_DURATION short: it's Écluse's only standing credential and it writes the trusted store. Scope the mirror queue the same way, granting only the serve role SendMessage and only the worker ReceiveMessage/DeleteMessage/ChangeMessageVisibility, because anyone who can write the queue can force a write to the trusted store. ChangeMessageVisibility is load-bearing, not optional: the worker uses it both to hold a long publish and to back a dead-lettered poison message off so it rides your redrive policy to the DLQ; without the grant an over-cap artifact silently churns on the ordinary visibility cadence instead.
4. Let the edge own access; leave ECLUSE_SERVER__AUTH_TOKEN off. Écluse is not your access boundary. Front it with a gateway, mesh, or IAP, and restrict reachability both north-south and east-west (pod-to-pod): an ingress-only allow-list that leaves the pod reachable inside the cluster is a common vulnerability. See Connecting your clients.
5. Fence egress, keep metadata reachable. Default-deny outbound, allowing only your upstreams, the mirror target, the advisory bucket when ECLUSE_ADVISORIES__BUCKET is set (the proxy needs s3:GetObject to sync it), and the metadata endpoint; require IMDSv2 with hop limit 1. Don't block the metadata endpoint: Écluse needs it to mint credentials. See Securing network egress.
6. Make the proxy unbypassable. Deny CI runners (and, where practical, workstations) outbound access to the public registries. See Locking down CI egress.
7. Verify what you run. Pin the image by digest and verify its provenance and SBOM attestations (see Verifying the image).

The reasoning behind each choice, and the residual risks it accepts, is in the threat model and Security invariants.

Deviating from the Golden Path

Écluse still runs if you diverge, but each deviation trades away a protection, and one is silent (Écluse can't detect it, so nothing warns you):

• Collapsing the registries onto one store (declaring ECLUSE_MOUNTS__NPM__MIRROR_TARGET equal to the private upstream, or ECLUSE_MOUNTS__NPM__PUBLICATION_TARGET onto either). The perimeter holds, but first-party and public-derived packages share one store, so you lose provenance separation and clean post-incident scoping. The proxy logs a boot warning for each pair of a mount's endpoints that resolve to the same registry, and Écluse Dredger refuses to boot if MIRROR_TARGET equals PUBLICATION_TARGET, since automated pruning on a shared store risks first-party data loss.
• Pointing the private upstream at a registry that itself draws from public (say a CodeArtifact repo with the stock npm-store upstream to npmjs). This is the dangerous one, and Écluse can't detect it: raw ungated packages reach clients through the trusted read path, behind the gate instead of through it, nullifying the rules, integrity floor, and freshness quarantine. Aggregate trusted stores only into the private upstream, and let the gated mirror be the only way public content enters.

The threat model records both. The other deviations self-announce: an open edge leans on your network boundary, a static publish credential fails closed at boot without that edge, and a static mirror-write secret forgoes the minted token.

Configuration

Configuration has two layers: environment variables for process and secret values, and an optional config document (YAML) for the two things too expressive for flat env vars, the rule policy and the mount map. A single-mount npm deployment on the default policy needs no document.

A mount serves only when you declare it: any ECLUSE_MOUNTS__<ECOSYSTEM>__* variable (or any key under mounts.<ecosystem> in the document) activates that mount, and a mount you never mention stays off. Whether an active mount mirrors is derived from its endpoints: declaring mirrorTarget makes it mirrored (its private upstream is then required, so the mirror reads back), and omitting it makes the mount serve-only. Each boot logs one posture line per mount and warns on any pair of a mount's endpoints that resolve to the same registry. The design rationale is in Configuration and authentication.

A value resolves as defaults < config document < environment variable, so the environment wins, and the boot log carries one config: line per resolved key naming the layer that supplied it (secrets redacted), the same dump ecluse check-config prints.

Environment variables

One spelling rule. Environment variables are the mechanical transliteration of the document schema: __ descends into an object and _ joins a camelCase word, so ECLUSE_CACHE__MAX_BYTES spells cache.maxBytes and ECLUSE_MOUNTS__NPM__MIRROR_TARGET spells mounts.npm.mirrorTarget.

The secret-typed variables also accept the container-secret file pattern: set the _FILE form (ECLUSE_SERVER__AUTH_TOKEN_FILE, ECLUSE_MOUNTS__NPM__MIRROR_TARGET_TOKEN_FILE, ECLUSE_MOUNTS__NPM__PUBLICATION_TARGET_TOKEN_FILE) to a file path and the file's contents (trailing newlines stripped) become the value, so the token never enters the environment. Setting both a variable and its _FILE form, or naming an unreadable file, is a fail-loud boot error.

Process

Server (server.*)

Mounts (mounts.npm.*)

Mirror queue (queue.*) and the ambient AWS environment

Limits (limits.*)

Cache (cache.*)

Integrity (integrity.*)

Egress (egress.*)

Advisories (advisories.*)

Runtime (runtime.*)

Observability (observability.*)

Configuration is validated in full at startup and the process refuses to start on any problem (an unknown rule type, a bad URL, an unresolved policy reference), so a misconfiguration is a loud, immediate failure rather than a quietly mis-enforced policy. The validation model is in Validation: fail fast, reject the unknown.

⚠️ The first-party publish surface authorises names, not callers. With publishing enabled (ECLUSE_MOUNTS__NPM__PUBLICATION_TARGET), ECLUSE_MOUNTS__NPM__PUBLISH_ALLOW limits which package names may be published; it is not authentication. So a static ECLUSE_MOUNTS__NPM__PUBLICATION_TARGET_TOKEN (used only when a publisher forwards none) is fail-closed: set it without ECLUSE_SERVER__AUTH_TOKEN and Écluse refuses to start (PublishStaticCredentialNeedsEdge), so "static publish credential + open edge" is unrepresentable. ECLUSE_SERVER__AUTH_TOKEN is the edge Écluse can verify itself; an external layer is good defence-in-depth but does not satisfy this. Pure passthrough (the default) needs none of it. See Access model → Publishing.

The configuration document

A YAML file mounted at /etc/ecluse/config.yaml (relocate it with ECLUSE_CONFIG; a non-existent explicit path is a boot error). It carries the rule policy (see Rule policy) and, for multi-mount deployments, the mount map. Single-mount deployments desugar from the env vars above and need no document. Schema and examples: Configuration and authentication. Deployments derive their initial policy from the default baseline configuration.

Secrets

Secrets never live in the config document. Client and registry tokens are always env vars, and cloud-managed registries (CodeArtifact, Artifact Registry) derive short-lived tokens from ambient cloud credentials. A mirrored mount holds a mirror-target write credential; a serve-only mount never writes and holds none. Reads use the default passthrough strategy: the caller's own credential is forwarded to the private upstream and stripped before the public one. The credential model, including the planned per-mount strategies, is in access model and Outbound registry credentials.

Connecting your clients

Point your package manager at the proxy as its registry. With ECLUSE_SERVER__AUTH_TOKEN set, supply it the standard npm way:

# .npmrc
registry=https://ecluse.example.internal/
//ecluse.example.internal/:_authToken=${ECLUSE_TOKEN}

Edge authentication to the proxy has two shipped modes:

1. Open: ECLUSE_SERVER__AUTH_TOKEN unset; access control is delegated to the network layer (VPC, service mesh). Appropriate only on a closed network.
2. Static token: ECLUSE_SERVER__AUTH_TOKEN set; clients send it as Authorization: Bearer <token> or .npmrc _authToken.

A third mode, a trusted edge identity honoured over a verifiable binding to a fronting gateway/IAP/mesh, is planned; see access model → edge authentication.

Securing network egress (required)

Écluse fetches from the registries you point it at, and some URLs it follows (a version's dist.tarball) come from upstream responses. Apply least-privilege egress in two layers. Écluse provides the first in the application, with an origin-aware trust model:

• Untrusted origins (the public upstream and every dist.tarball) are gated by a host+port allowlist, fetched HTTPS-only with TLS certificate validation, and bounded by response-size limits. An upstream URL with no explicit port authorises port 443 alone; a nonstandard port must be written (https://repo.internal:8443) and authorises exactly that host:port. A non-HTTPS upstream, or a port outside 1..65535, fails closed at boot. Certificate validation is the guarantor against the resolve-to-internal and DNS-rebinding SSRF class: an address a name is steered to can't present a CA-trusted certificate for the host. As defence-in-depth, a literal internal-range block (loopback, link-local including the 169.254.169.254 metadata endpoint, RFC1918, CGNAT, IPv6 ULA) refuses a dist.tarball whose host is an internal-address literal; extend it with ECLUSE_EGRESS__ADDITIONAL_BLOCKED_RANGES.
• The trusted private origin (ECLUSE_MOUNTS__NPM__PRIVATE_UPSTREAM) is deliberately not subject to the internal-range block: a private registry legitimately lives on your internal network.

The dist.tarball host gate. dist.tarball is upstream-chosen, so Écluse fetches a tarball only from the same allowlisted host that served the packument, host and port compared as a pair. A plaintext dist.tarball is upgraded to https on its own host; on any other host it is dropped (the version is skipped). There is no widening knob.

Provide the second layer at the platform, default-denying egress and allowing only your registries, mirror target, and the metadata endpoint:

• AWS: security-group egress rules / network ACLs to the upstream and mirror CIDRs; reach CodeArtifact and S3 over VPC endpoints; require IMDSv2 with hop limit 1 (httpPutResponseHopLimit: 1).
• GCP: VPC firewall egress rules and, where applicable, VPC Service Controls.
• Kubernetes: a default-deny NetworkPolicy with an explicit egress allowlist; allow your private upstream's internal range.
• Service mesh (Istio/Linkerd): sidecar outbound policy REGISTRY_ONLY, each upstream a ServiceEntry, constrained by a Sidecar egress listener and an egress AuthorizationPolicy.

Don't block the metadata endpoint or internal ranges for the proxy itself. Écluse's own metadata access goes through the AWS SDK to mint its instance-role credentials; denying it breaks those credentials. IMDSv2 hop limit 1 keeps the minting working while stopping a neighbour or forwarded request from reaching metadata through extra hops. Grant the proxy only the cloud permissions it needs: the mirror-write credential and the advisory-bucket read (s3:GetObject) when ECLUSE_ADVISORIES__BUCKET is set, nothing more. The invariants and their rationale are in Network egress is a shared responsibility.

Securing Écluse Pilot and Dredger

Both auxiliary services need distinct, tightly scoped egress, and both must run as singletons:

• Écluse Pilot: no public ingress. Egress to the OSV export host in ECLUSE_ADVISORIES__OSV_EXPORT_BASE_URL (default osv-vulnerabilities.storage.googleapis.com), the metadata endpoint, and your object store (s3:PutObject to upload the advisory database). The object is named <ecosystem>-osv-schema<N>.db (e.g. npm-osv-schema3.db); the key is stable per ecosystem, so bucket policies and the proxy's ETag polling can target it. On an export-host 5xx/408/429, Pilot retries with capped, jittered backoff, so a transient outage can't get your NAT address rate-limited.
• Écluse Dredger: no public ingress. Egress only to your private mirror for delete requests and to the metadata endpoint for credentials. It holds a standing high-privilege delete capability, so isolate it from all untrusted networks.

To avoid an idling Pilot pod, schedule the one-shot instead: run ecluse pilot compile --out /tmp/osv --upload as a Kubernetes CronJob with concurrencyPolicy: Forbid (which preserves the singleton by never overlapping a run). Give the pod s3:PutObject via IRSA or workload identity rather than mounted keys, and align its schedule with the proxy's polling (the proxy polls more often than Pilot publishes).

Locking down CI egress (recommended)

The controls above secure Écluse's own egress. This one secures your consumers'. If you control CI, deny runners outbound access to the public registries (registry.npmjs.org and the equivalents for other ecosystems) and let them reach only Écluse and your internal services. Now a misconfigured job (a stray --registry flag, a committed .npmrc, a tool that ignores your settings) can't reach the public registry, so it fails instead of pulling an unvetted package. This makes the policy unbypassable rather than merely default: a per-project package-manager setup can override what you ship to a machine, but none can route around a network that only reaches Écluse. See MOTIVATION → The bar. The same idea extends to developer workstations, a softer control than CI.

Rule policy

Écluse evaluates a named map of rules over a built-in deny-by-default policy: a package is admitted only if a rule allows it, and every deny type outranks every allow type by default. The policy lives in the config document's rules object; it also has an environment spelling (ECLUSE_RULES carrying the JSON object), which suits a one-rule tweak while the document stays the reviewable home for a real policy. The shipped default is small and biased toward resilience:

• min-age (AllowIfOlderThan): admit public versions older than a quarantine window (7 days by default), the core defence against race-to-publish typosquatting and dependency confusion.
• remediation-fast-track (AllowIfRemediatesCve): admit a release a synced advisory names as its exact fixed version ahead of the quarantine, provided no other advisory still affects it. It abstains until an advisory database has been synced (set ECLUSE_ADVISORIES__BUCKET and run Pilot), so without one only the quarantine governs.

Every other built-in rule is off by default and opts in by name:

• AllowByIdentity: admit a specific package or package@version past the quarantine, at the top of the allow band but still below every deny.
• DenyByIdentity (the revoke shape): a hard-deny for a specific package or package@version.
• DenyInstallTimeExecution: deny install-time code execution (off because many legitimate packages ship install scripts).
• DenyIfCve: block a version a synced advisory records as affected at or above a CVSS minSeverity (0-10). The npm malware feed carries no score and counts as above every threshold, so enabling it also blocks known-malicious packages. It sits just below AllowByIdentity, so an identity pin overrides it; its onUnavailable knob (deny by default, or skip) decides what happens when the advisory database can't answer. Read Onboarding DenyIfCve before enabling.

Override a value, add a rule, or suppress a default by name in the document:

{
  "rules": {
    "min-age": { "ageSeconds": 1209600 },
    "deny-scripts": { "type": "DenyInstallTimeExecution", "precedence": 200 },
    "revoke-bad": { "type": "DenyByIdentity", "identity": "bad-package" },
    "cve-fast-lane": { "type": "AllowIfRemediatesCve" },
    "deny-known-cves": { "type": "DenyIfCve", "minSeverity": 8 },
    "pin-fix": { "type": "AllowByIdentity", "identity": "left-pad@1.3.0" }
  }
}

The precedence values, the patch/add/suppress merge model, and the strict validation are in Rule policy and Rules engine.

Independent of the rules, a public version is served only if it carries a digest meeting the public integrity floor (ECLUSE_INTEGRITY__MIN_PUBLIC, default sha256; see the table above). Gotcha: a custom or off-spec public upstream serving versions without a floor-meeting digest will have those versions silently disappear and their tarballs 403. To serve such a source, point it at the private upstream slot and loosen ECLUSE_INTEGRITY__MIN_TRUSTED below sha256. The mechanics are in Public integrity floor.

Onboarding DenyIfCve

DenyIfCve can break a cold deployment: on a freshly-stood-up mirror it can deny historical versions your existing builds still depend on that an advisory has since covered. Enable it after your private mirror is warmed:

1. Leave DenyIfCve out of your policy and run Écluse normally, so your CI and developers pull the versions you depend on. Each is mirrored into the trusted store, which the rules never re-gate once it is there.
2. Once your must-have builds are mirrored, add DenyIfCve with a minSeverity you are comfortable with (8 blocks high and critical CVEs; malware blocks regardless of the threshold).
3. If a specific version you must keep is then denied (a false positive, or a risk you accept), pin it with an AllowByIdentity rule, which outranks DenyIfCve.

Set onUnavailable: skip if you would rather the gate fail open (skip itself, logging loudly) than refuse traffic when the advisory database is briefly unavailable; the default deny fails closed.

Operating Écluse

• Pre-warming the cache. A cold npm install against an empty cache hits the proxy with dozens of heavy requests at once, causing latency spikes or 503 backpressure. Run an npm install after starting Écluse, before production traffic; once warm, request coalescing absorbs spikes.

• Health probes. GET /livez reports process liveness (on a mirroring deployment a stalled mirror worker fails it; a serve-only deployment's liveness is the listener alone). GET /readyz reports config loaded and the listener serving; it is deliberately lenient about public-upstream reachability, so a transient blip doesn't pull a healthy pod from rotation. With an advisory bucket configured, readiness also waits for each ecosystem's first advisory sync (a one-way flip, so it never flaps), so mounting an ecosystem whose artifact Pilot never publishes leaves the pod never ready. The npm liveness probe GET /npm/-/ping answers locally with 200 {}, and GET /npm/-/v1/search returns 501 by design (search is a discovery convenience, not an install path). Pilot and Dredger export the same /livez and /readyz on ECLUSE_SERVER__PORT.

• Graceful shutdown and pod drain. On SIGTERM/SIGINT Écluse drains in-flight work rather than dropping it. GET /readyz flips to 503 (the signal a load balancer or mesh watches to stop routing new traffic here) while GET /livez stays 200, so an orchestrator does not kill a still-draining instance early. Every response then carries Connection: close, so a keep-alive pool reconnects to a ready instance, and the process finishes in-flight requests and in-progress artifact streams (a half-delivered tarball runs to completion) before exiting, bounded by ECLUSE_SERVER__SHUTDOWN_DRAIN_TIMEOUT (default 30 seconds). Set the platform's termination grace period above ECLUSE_SERVER__SHUTDOWN_DRAIN_TIMEOUT so the orchestrator does not SIGKILL mid-drain: on Kubernetes, set terminationGracePeriodSeconds comfortably above it. When Écluse is attached to an interactive terminal, a second Ctrl+C (or Ctrl+D) forces an immediate halt that bypasses the drain; this is gated on standard input being a TTY, so production has no such bypass.

• Process exit codes. The exit status states how a run ended, so an orchestrator can branch without parsing logs:

  Code	Meaning
  0	Graceful shutdown: the drain completed and the services returned.
  1	A service exited abnormally; the detail is the last ecluse: service exited: line on standard error.
  2	The boot aborted: configuration or wiring was rejected, every problem already reported. A restart without changes fails identically.
  3	The run was cancelled from outside (a kill that bypassed the graceful path).
  130	The local-development halt (Ctrl-D on an interactive terminal).

• Logs. One JSON object per line by default (ECLUSE_OBSERVABILITY__LOG_FORMAT=json), or console for local development. Bearer tokens render as a redacted placeholder, so token material never reaches a log field.

• Telemetry (opt-in). Set ECLUSE_OBSERVABILITY__TELEMETRY=on, then DD_* (DD_SERVICE, DD_ENV, DD_VERSION, DD_AGENT_HOST) for Datadog or the standard OTEL_* for any other backend; DD_* wins where both are set, and the resolved identity stamps both traces and the dd object on every log line. DD_API_KEY/DD_SITE are ignored: Écluse exports only to a node-local collector or Agent, at http://localhost:4318 by default or wherever DD_AGENT_HOST/OTEL_EXPORTER_OTLP_ENDPOINT points (authenticate a remote collector out of band with OTEL_EXPORTER_OTLP_HEADERS). Export is async and batched, off the request path, so an unreachable collector never slows a request.

• The memory plan. Every byte-valued bound (cache, response cap, publish aggregate, in-memory queue) is a named tenant of the effective heap ceiling, not an independent multiplier, and each is boot-logged as a memory plan: line. A pod too small for the tenants' floors degrades gracefully instead of refusing: it sheds (cache first, to zero, serving uncached), each step a loud warning, and always boots. Only an explicit override that breaks the plan refuses (exit 2). The model is in Runtime sizing.

• Runtime sizing. Cores and the heap ceiling resolve at boot (config, else cgroup, else the runtime's own posture) and every decision is logged with its provenance. The whole-cores guidance and per-pod memory arithmetic are in the runtime-sizing appendix.

• Revoking a mirrored version (internal yank). The mirror store deliberately resists upstream yanks, so a benign yank doesn't break your installs, but a version later found malicious isn't removed automatically (Écluse never re-gates trusted content). Usually this resolves itself: once the public registry yanks the bad version, re-mirroring can't reproduce its bytes and you purge the stale copy at leisure. When your own scanning is ahead of the public yank, revoke in order: (1) deny the identity (a DenyByIdentity rule), so the serve path stops admitting it and the worker stops re-mirroring, then (2) purge that version from the mirror. Order matters: purge alone is a treadmill, since while the version is live upstream the next install re-admits and re-mirrors it.

Datadog on Kubernetes

Deploy via the Datadog Operator: a DatadogAgent custom resource (datadoghq.com/v2alpha1) manages the node Agent, traces and metrics go OTLP over TCP to the node-local Agent, and logs are scraped from stdout with no extra wiring.

1. Enable the Agent's OTLP receiver in the CR. Sampling lives Agent-side (the probabilistic sampler needs Agent v7.70+):

   apiVersion: datadoghq.com/v2alpha1
   kind: DatadogAgent
   spec:
     features:
       otlp:
         receiver:
           protocols:
             http: { enabled: true }   # :4318
     override:
       nodeAgent:
         env:
           - { name: DD_APM_PROBABILISTIC_SAMPLER_ENABLED, value: "true" }
           - { name: DD_APM_PROBABILISTIC_SAMPLER_SAMPLING_PERCENTAGE, value: "20" }

2. Point Écluse at the node-local Agent with the Downward API, one OTLP endpoint for traces and metrics both:

   env:
     - name: HOST_IP
       valueFrom: { fieldRef: { fieldPath: status.hostIP } }
     - name: OTEL_EXPORTER_OTLP_ENDPOINT
       value: "http://$(HOST_IP):4318"
     - name: OTEL_EXPORTER_OTLP_PROTOCOL
       value: "http/protobuf"

3. Logs need no extra wiring: Écluse writes JSONL to stdout and the Agent's container log collection picks it up.

Planned controls

Documented ahead of implementation so the configuration surface is known.

• GCP backends (planned): the Pub/Sub MirrorQueue and ADC credential leaf. The AWS equivalents (SQS MirrorQueue, CodeArtifact credential leaf, mirror worker, composition root) are built and wired.
• Per-mount credential strategies and trusted-edge identity (planned): today reads are passthrough (the caller's credential is forwarded) and the edge is open or static-token. The target model (a service read strategy, a trusted-edge identity mode) is in access model.

The full deployment runbook ships with the launch.

Appendix: runtime-sizing arithmetic

Give Écluse whole cores. A fractional CPU limit (say 3.5) has no good option: claiming 4 capabilities overruns the CFS quota during stop-the-world GC and freezes the process mid-pause; flooring to 3 strands the fraction. Écluse floors the derived count, so pair an integer limit with requests = limits (and exclusive cores where offered) to remove throttling structurally. A CPU limit doesn't shrink the processor count the runtime sees, so without ECLUSE_RUNTIME__CORES a 2-CPU pod on a 32-core node would claim 32 capabilities and 32 nurseries.

Memory arithmetic (proxy pod). The binary ships -A64m -n4m (a 64 MiB per-core allocation area in 4 MiB chunks), trading bounded extra memory for far fewer GCs under load. Budget roughly cores x 64 MiB of nursery, plus the live heap (dominated by the metadata cache), plus up to one live-heap of copying headroom during a major GC. Worked shapes:

• a 2-CPU / 512 MiB pod runs as-is;
• a 2-CPU / 256 MiB pod also needs GHCRTS="-A16m";
• a 4-CPU pod wants ~750 MiB on defaults, or 512 MiB with -A32m.

Taller pods amortise the cache and coalescing better, so prefer 4-CPU-ish shapes. Tune the allocation area with GHCRTS; the boot log prints the effective value. Pilot and Dredger run different workloads, so tune their allocation area separately, though the core/heap resolution above applies to every role.

Learn more

The internal design, for when you need the why:

• Architecture overview
• Configuration and authentication
• Security invariants and network egress
• Threat model, the STRIDE register, generated from the OWASP Threat Dragon model (threat-modelling/ecluse.json)
• Rules engine
• Multi-ecosystem hosting and URL rewriting
• Release and supply-chain operations