Browse the documentation

Early preview

Containers and Kubernetes

An Executor binary is a static executable that runs inside FROM scratch, distroless and Alpine images, operates cleanly as the container's PID 1, and needs no privileged container flags for its sandbox.

A minimal image

FROM gcr.io/distroless/static-debian12
COPY dist/order-service-oee /app/order-service-oee
ENTRYPOINT ["/app/order-service-oee"]

Build the binary in CI first:

oee build -f oee.yaml --target linux-x86_64 --sign-key ./certs/oee.key -o dist/order-service-oee

Executor as PID 1

As the container's init process, oee-stub:

  • forwards the container's stop signals to the guest process group;
  • reaps zombie processes, so no defunct process accumulates;
  • applies the configured seccomp and Landlock sandbox rules;
  • launches the wrapped application and supervises its whole process tree;
  • stops the tree through the state-preserving pipeline and exits with a deterministic code, so the container stops cleanly with its logs and mounted volume data intact.

Sandboxing in unprivileged containers

Default Docker and Kubernetes seccomp profiles often refuse nested CLONE_NEWUSER or mount calls with EPERM. At startup, the Executor probes the kernel's capabilities (CapEff in /proc/self/status and the Landlock ABI version) and applies sandbox.container_fallback:

ValueInside an unprivileged container
"auto" (default)Layers every unprivileged primitive the container permits: Landlock filesystem path restrictions, seccomp-BPF syscall filtering, PR_SET_CHILD_SUBREAPER process containment and setrlimit quotas. No --privileged and no --cap-add=SYS_ADMIN on docker run.
"strict"Halts before launching the guest if any requested namespace primitive is unavailable, with exit code 69.

Caps inside a container

  • Percentages follow the container. The capacity base is the smaller of the host's capacity and the enclosing container's limit, read from the container's cgroup. A "10%" cap in a container limited to 4 cores resolves against 4 cores, not the host's 64.
  • The container's cgroup. Inside a container, the supervisor uses the container's cgroup for strict caps when it is writable.
  • Strict never weakens. If no kernel hard limit is available, a strict cap refuses to start with exit code 69 instead of becoming advisory.

Secrets from Kubernetes and Docker Swarm

Exit-event credentials can come from a mounted secret file, such as from_file: "/run/secrets/oee_api_token", or from an environment variable with from_env, which the Executor strips from the guest's environment by default.

Exit codes for restart policies and Jobs

The Executor's exit codes are explicit and configurable, so Docker restart policies (--restart=on-failure), Kubernetes Jobs and CI/CD pipelines can tell a planned stop from a failure:

CodeMeaning
0A checkpoint completed the work.
124A time-based exit event: duration, cron, timestamp or idle.
143An external or message exit event, or oee stop.
76A utilization exit event.
75The exit-event lease was lost under FAIL_CLOSED.
78The pre-launch gate blocked startup.
69Required enforcement is unavailable on this host.
70A quota or policy violation.

Scaling inside one Pod

The built-in auto-scaler runs replicas within one container on one host, behind its own load balancer, each held to its own cap and the optional total_limits ceiling. Spreading replicas across nodes remains the job of Kubernetes.