<#1071 docs: clarify base image USER/WORKDIR requi...
# flyte-github
a
#1071 docs: clarify base image USER/WORKDIR requirements on Image.from_base() Pull request opened by mhotan Summary
Image.from_base()
is unique among the
Image.from_*
factories in that it does not create a runtime user or chown the working directory — the resulting container runs as whatever
USER
and with whatever
WORKDIR
the base image declares. When that
USER
is non-root (UBI
nonroot
uid
65532
, distroless
nonroot
, chainguard
nonroot
) and the
WORKDIR
is owned by root with restrictive perms, tasks fail at start with:
Copy code
PermissionError: [Errno 13] Permission denied
inside
flyte._internal.runtime.entrypoints.download_code_bundle
. The container starts fine because the runtime does
chdir
as
root
before dropping to the configured
USER
, but the unprivileged
USER
cannot then traverse
WORKDIR
to read or write the code bundle file. This PR is docstring-only — it extends the
Image.from_base()
docstring to call out the constraint and link the BYOI guide section that documents the
.with_commands()
workaround. Auto-flows into the API reference page. The companion build-time fix lives in
unionai/cloud
(PR #15929): the v2 image builder no longer overrides the base image's declared
WORKDIR
, and emits a
WARN
at build time when the resulting `USER`+`WORKDIR` combination is known to be broken. Customers are expected to fix the misconfiguration in their base image; the build warning + this docstring point them at the correct pattern. This PR previously also contained a runtime fallback that rerouted the code bundle to
/tmp/flyte-bundle/<version>
when the resolved
WORKDIR
turned out to be unwritable. After review (see commits c3058d2 / 6822569) we removed it: a silent reroute contradicts the BYOI principle the cloud PR establishes ("honor what the base declared, don't override silently, surface the problem"). The build-time
WARN
plus the clear
PermissionError
traceback at runtime are the right surfaces; a silent runtime reroute would hide misconfigured base images and let them propagate. Tracking issue (Union internal): FAB-352. Test plan •
pydoc flyte.Image.from_base
renders the new docstring cleanly. • No code paths changed — existing tests pass unchanged. flyteorg/flyte-sdk