Skip to content

CONCEPT Cited by 1 source

Container-entrypoint compatibility layer

A container-entrypoint compatibility layer is code that runs inside a Docker container's entrypoint script (before the user's command), and whose job is to re-synthesise platform primitives that the target execution substrate doesn't natively provide but that the source substrate did. It is the implementation technique for environmental parity under a zero-code-change migration.

Why entrypoint (and not a sidecar, init container, or runtime SDK)

  • Sidecar — not all target platforms support sidecars. SageMaker notably does not; Kubernetes does. A migration toward a sidecar-less platform can't rely on them.
  • Init container — Kubernetes primitive; not universal. SageMaker Jobs have no equivalent.
  • Runtime SDK patching — forces user code changes (an SDK call to fetch credentials or redirect metrics), violating the zero-code-change constraint.
  • Entrypoint — runs in the same container, in every environment that runs containers, with full access to the container's env vars, filesystem, and network. Universal, invisible to user code.

What goes in the layer

On Lyft's LyftLearn 2.0 migration (Kubernetes → SageMaker), the entrypoint layer absorbed every Kubernetes primitive SageMaker lacked:

  1. Credentials — fetches from Confidant at startup and writes them into the container's environment in the shape K8s webhooks produced. See patterns/runtime-fetched-credentials-and-config.
  2. Environment variables — SageMaker caps the number of env vars passable via its API, so the entrypoint fetches additional config at runtime.
  3. Metrics — reconfigures StatsD networking to connect directly to the metrics aggregation gateway instead of a K8s sidecar.
  4. Hyperparameters — SageMaker's API cap on direct parameter passing is too small for Lyft's use cases, so the layer uploads hyperparameters to S3 pre-job and has SageMaker download them into its standard input path automatically.
  5. Runtime context detection — the same image runs in SageMaker Jobs, SageMaker Studio notebooks, and K8s serving; the entrypoint detects which and sets up Spark config, user account, env vars, and permissions accordingly. See concepts/runtime-environment-detection and patterns/cross-platform-base-image.

Trade-offs

  • + Invisible to user code. The compatibility cost is paid once per container start, not per user call.
  • − Startup latency. Every additional fetch at entrypoint adds cold-start time. This has to be weighed against concepts/cold-start budgets and may motivate warm pools or lazy image loading.
  • − Debuggability. A failure in the compatibility layer manifests as "user code saw a different environment than expected" — which requires tracing back through the entrypoint to locate.

Seen in

Last updated · 517 distilled / 1,221 read