Skip to content

docs(lakefs): add the Alauda support for lakeFS installation guide - #823

Merged
SuJinpei merged 2 commits into
mainfrom
docs/lakefs-v1.84.1-install-guide
Jul 31, 2026
Merged

docs(lakefs): add the Alauda support for lakeFS installation guide#823
SuJinpei merged 2 commits into
mainfrom
docs/lakefs-v1.84.1-install-guide

Conversation

@SuJinpei

Copy link
Copy Markdown
Contributor

Installation guide for the S2 ecosystem plugin Alauda support for lakeFS (lakeFS 1.84.1, upstream
chart 1.12.18), packaged by the oss-operator-factory and published to the Alauda Cloud marketplace
(cn app 967 / io app 837).

Follows the convention already used by the knative / nacos / debezium / konveyor guides:
hand-authored prose with factory:auto fenced slots for supported-versions and known-limitations, so
later releases regenerate those without touching the prose. No id: field, so CI assigns a real KB
id on merge.

What the guide leads with, and why

The storage decision, before installation — because that is where a lakeFS install actually goes
wrong. The shipped defaults are an embedded metadata store on the container filesystem, which is
single-replica and not durable, and it is easy to mistake "it installed" for "it is ready to use".
The guide gives all three shapes explicitly — out-of-the-box, evaluation-with-a-PVC, production with
PostgreSQL + S3 — and the one-volume-at-/home/lakefs rule that makes the middle one work.

Everything here was executed, not transcribed from upstream docs

Commands come from the validated e2e path: lakectl invoked from inside the image against the
Service, the exact convergence checks the release gate uses, and the uninstall ordering (delete the
LakeFS resource before the Operator, or the namespace hangs in Terminating) — which is the
failure this release actually hit during onboarding.

The second commit is a correction worth reading

The first version documented lakeFS's unattended installation.* setup with no qualification. While
running the production-shape e2e leg (PostgreSQL + S3) I found that it does not apply when the
metadata store is PostgreSQL
: the server starts normally, connects to PostgreSQL — it creates its
partitioned kv tables and writes to them — initialises the S3 adapter, and then stays
{"state":"not_initialized"}, rejecting every API call with credentials not found.

Established rather than assumed:

  • not a race — still uninitialised minutes after boot, on a freshly created database, reproduced
    twice;
  • isolated with a control — two deployments identical except database.type: the embedded one
    comes up initialized and the configured key works, the PostgreSQL one does not.

A reader following the original text for a production deployment would have got something that
starts cleanly and then refuses to work. It is now scoped to evaluation, with the caveat, the
/app/lakefs setup escape hatch (which mints its own key pair and ignores any configured one), a
pointer from the production section, and a Known Limitation entry.

Once set up, the production shape is fully functional — verified end to end: repository on
s3://<bucket>/<repo>, upload → commit → branch → merge → read back, objects physically present in
the object store, and the S3-compatible gateway serving them.

Validation

Frontmatter parses; no id: on the new file; relative anchors resolve. yarn build does not run
locally (it dies in SSG on localStorage.getItem is not a function inside @alauda/doom, a
module-load failure independent of page content) — CI builds fine.

SuJinpei added 2 commits July 31, 2026 03:08
Installation guide for the S2 ecosystem plugin "Alauda support for lakeFS"
(lakeFS 1.84.1, upstream chart 1.12.18), packaged by the oss-operator-factory and
published to the Alauda Cloud marketplace.

Follows the per-component convention already used by the knative / nacos /
debezium / konveyor guides: hand-authored prose with factory:auto fenced slots
for supported-versions and known-limitations, so later releases can regenerate
those from component.yaml without touching the prose. No id field, so CI assigns
a real KB id on merge.

The guide leads with the storage decision because that is where a lakeFS install
actually goes wrong: the shipped defaults are an embedded metadata store on the
container filesystem, which is single-replica and not durable. It gives all three
shapes explicitly (out-of-the-box, evaluation-with-a-PVC, production with
PostgreSQL + S3) and the one-volume-at-/home/lakefs rule that makes the middle
one work.

Every command was taken from the validated e2e path rather than written from the
upstream docs — lakectl invoked from inside the image against the Service, and
the uninstall ordering (delete the LakeFS resource before the Operator, or the
namespace hangs Terminating) is the failure this release actually hit.
…a store

Measured on ACP 4.2 while running the production-shape e2e leg: with
database.type postgres, lakeFS starts normally, connects to PostgreSQL and
initialises its S3 adapter, then stays uninitialized and rejects every request
with 'credentials not found'. Isolated with a control - two deployments
identical except the metadata store type; the embedded one comes up initialised,
the PostgreSQL one does not.

The guide previously presented the installation block with no qualification, so
a reader following it for a production deployment would get something that
starts cleanly and then refuses to work. It is now scoped to evaluation, with
the caveat, the '/app/lakefs setup' escape hatch (which mints its own key pair
and ignores any configured one), a pointer from the production section, and a
Known Limitation entry.
@SuJinpei
SuJinpei merged commit b84d895 into main Jul 31, 2026
1 check passed
@SuJinpei
SuJinpei deleted the docs/lakefs-v1.84.1-install-guide branch July 31, 2026 07:09
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant