Skip to content

docs: egret's own engine policies converge from bound engines and admins (platform #836) - #62

Merged
viethqb merged 37 commits into
mainfrom
docs/gov-sp2a-infra-convergence
Nov 4, 2026
Merged

viethqb merged 37 commits into
mainfrom
docs/gov-sp2a-infra-convergence

Conversation

@viethqb

@viethqb viethqb commented Nov 4, 2026

Copy link
Copy Markdown
Member

Summary

These are the docs for egret-data/platform#836 (governance SP2a). Egret's own engine policies now follow the engines bound to each profile and the active platform admins.

  • Engines and Ranger, "Platform admins on the engines": rewritten. Convergence now owns the egret-admin - … policies and the four fixed Trino policies. It runs on every change and at every start.
  • Upgrade, new section "Egret's own engine policies are kept in line (governance SP2a)":
    • what the first start deletes, with the D5 cases;
    • one policy-version bump for each profile that changes;
    • a start that finds nothing to change no longer bumps the version, where before it added +3 on every start;
    • the all - … defaults are not touched;
    • a hand-written policy that uses one of these names is treated as egret's own;
    • recompile with POST /api/control-plane/perm/compile/{service_id} before migrating.

The branch is rebased on #61 and keeps both upgrade sections.

🤖 Generated with Claude Code

viethqb and others added 30 commits October 22, 2026 07:50
* docs: Wave 1 fixes (KI-059 to KI-207, KI-236 to KI-246)

Describe the product as it is on platform main after #711, #712, #715,
#716, #718 and #719: dashboard typing and filter values, redacted
connection listing for non-admins, closed storage prefixes and Key
prefix scoping, System secrets, concurrent workflow runs and the
worker-off notice, unknown-key warnings and catalog.public_url default,
SECRET input masking, egret init output and the Helm oidc.devRealm gate.

Close 16 known-issue rows and add KI-236 to KI-246.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* docs(reference): regenerate the REST reference from platform main

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Sonnet 5.5 <noreply@anthropic.com>
* docs(reference): regenerate the REST reference from platform main

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs: Wave 2 fixes (KI-004 to KI-211, KI-247 to KI-259)

Describe the product as it is on platform main after #720, #721, #724
and #725: SQL Lab row limit that keeps ORDER BY and marks cut results,
rounded floats, cancel and pre-start error panels, the timeout message,
Cmd K in the editor; chart export (.png only for chart images, 10,000
rows), Progress goal, row chart order, map unmatched-region note, Change
keeping cartesian config; dataset delete refused while charts use it,
typed confirmation, Trash notice, metric rename rewrite, Dimension and
Filter switches, display names, Duplicate for both kinds; Data API live
route and Pending publish, honest revoke note, constraint labels.

Close 38 known-issue rows (KI-101 partly) and add KI-247 to KI-259.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
…-260 onwards) (#30)

* docs: Wave 2b fixes in the pages and known issues (B4, B6, B7; KI-260 to KI-266)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs: regenerate the REST reference from platform main (#726, #727)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs: re-shoot the engine, run-log and SQL Lab screenshots for Wave 2b

The cp-engine-* shots take DOCS_ENGINE and alerts/run-log takes
RUN_LOG_ALERT, so a pass can point them at its own objects.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs: REST reference for the engines and monitor changes of platform #728

Generated from the openapi.json of #728's branch head (2021bff8), which
is platform main plus #728.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
)

Re-shoot the B7, Wave 2, B4 and B6 screenshots that went stale, on the
demo stack built from platform main 4755bdcf. The Explore shots run in the
Docs sandbox workspace (DOCS_WS knob); the harness now resets the viewport
to 1440x900 before each shot so a tall shot no longer leaks into the next.
Three captions and the quoted roles banner follow the new images.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Close KI-214, KI-215, KI-216, KI-222, KI-223 and KI-224 (fixed in
platform #734) and add KI-267 to KI-270. Update pages whose text no
longer matches: status words in sentence case, the back links of the
chart editor and the app editor, the user header without an avatar,
and the visible SQL Lab title.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
…wards) (#33)

* docs(known-issues): close Wave 3 U2/U3 and KI-236/KI-263 rows; add KI-271 to KI-279

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(reference): regenerate the REST reference from platform main

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs: storage downloads, engine saves, date picker, filter settings, refusal page, sidebar and small screens after U2/U3

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(screenshots): re-shoot after U1-U3 on a stack built from main

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Document that a deleted user's engine username is retired for good and
that egret-admin follows the active platform admins:

- Users: Disable/Enable in the row menu, the new disable and delete
  dialog copy with Disable instead, what a retired username means, the
  last-active-admin guard.
- People & groups: the Reused names tab, its verdicts and what to do.
- Governance overview: the reused-username finding; user deletes in
  Recent changes for user:read holders. Audit log: user:delete.
- Engines and Ranger, Engine permissions: egret-admin follows active
  platform admins in the same transaction, plus a boot repair.
- Upgrade note for migration 0209 (release note) and the username
  ledger restore runbook.
- KI-284, KI-285; glossary entry; REST reference regenerated from
  platform main's openapi.json; shot entries for the new screens.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
* docs: Wave 3 U4 SQL Lab and U5 dashboards (KI-280 onwards)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(reference): regenerate the REST reference from platform main

Adds DELETE /api/ws/{workspace}/queries (platform #740).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs: measured side-panel breakpoint (KI-282) and images for the new dialogs

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(screenshots): re-shoot SQL Lab and dashboards after U4 and U5

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
…to KI-289) (#36)

Document the per-person answer of Who can read? and Check access: one
sentence per person and engine (mask, exemption with rule and group,
StarRocks clearance replay and refusal, rows, ties, Not enforced), the
folded evidence, the members table and its 200-member limit. State the
engine gaps (StarRocks table-level clearance and row filter, Trino
column-level row filter) on the explain, rule, tagging and clearance
pages and as KI-286 to KI-288; record KI-289. Regenerate the REST API
reference and add shot entries for a re-shoot.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Close KI-008, KI-050, KI-053 to KI-056 and KI-058 (platform #743) and
KI-038, KI-039, KI-171 and KI-219 to KI-221 (platform #742). Add KI-290
to KI-295, found by those packages, and correct KI-234's reference to
KI-171. Update the chart editor, chart type, column formatting, dataset
Trash, dashboard card and alerts and reports pages to match.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
…I-296 onwards) (#38)

Close KI-295 (#745), the nine U8 rows (#746), the U9 rows (#747, KI-120
as not reproducing) and the nine U10 rows (#748). Add KI-296 to KI-299.
Document the flows trash, the new editor warnings, the Connections
wording at the workspace level, the 204 of the notification settings
and regenerate the REST reference.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Close the thirteen rows platform #751 fixed (KI-251, KI-280 to KI-282,
KI-290 to KI-294, KI-296 to KI-299); KI-283 stays open. Add KI-300 (+ App
in the Apps Trash), KI-301 (reports draw charts without dataset display
names) and KI-302 (alert editor's database/Engines warning). Document the
operator labels, the trash and folder confirmations on Charts, Apps and
Alerts, the edit panel layout rule, dataset names on dashboard cards and
the drill menu, and the connection wording; regenerate the REST reference.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
PDF reports print on A4 at the sheet's width and ignore the custom image
size (PNG keeps it); report cards use dataset display names and formats;
the alert editor's no-connection warning and two Data API texts say
connection and Connections.

Co-authored-by: Claude Sonnet 5.5 <noreply@anthropic.com>
…lt from main (#41)

* docs: captions, demo-stack examples and shot scripts follow the re-shoot

Captions and the demo-stack examples now describe what the stack built
from platform main shows: Governance's classification vocabulary (Add
classification, Rules, Views, Manual policies), one overview finding now
that view lineage is computed, the Connections page, five reports, the
Data API activity numbers, the run log of Pending orders above 100. The
user delete dialog gets its screenshot (platform #741).

Shot scripts: the rule dialog switches Applies to by its button, the
classification tabs are Rules and Views, the Data API pickers are
Connection, the alert condition and report editor pick demo objects,
the save-chart dialog is shot on a new chart, and the dataset create
dialog picks trino-demo.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* docs(screenshots): re-shoot after the KI fix programme on a stack built from main

205 screenshots re-shot on the demo stack built from platform main
2363d90f (egret, frontend and renderer), with the admin-demo-data.md
step 3 data rebuilt: Governance, engine detail, Control Plane and
Workspace settings data shots, Workflows, Apps, the get-started
tutorial, chart editors, alerts, Data API and dataset shots.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Sonnet 5.5 <noreply@anthropic.com>
…42)

Close KI-286 and KI-288: on StarRocks a whole-table clearance now refuses
an uncleared reader on direct reads and nulls every column through a view,
and a row filter by classification filters tables classified as a whole.
Document the table-commit recompile, the ceiling refusal (409
expansion_ceiling), the new Who can read? lines and the upgrade note, and
remove the old StarRocks gap statements. Add KI-303 to KI-307 for the
follow-ups. Regenerate the perm REST reference.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Close KI-303 and document the rename hold, its refusals, drops and
recursive namespace purges, the four new Governance overview findings,
the Where used badges and the tag:move/tag:purge feed entries. Add
KI-308 to KI-310 for path grants and policies, catalog grants and the
cost of the hold. Regenerate the REST reference.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
…latform #758) (#44)

Document what a Catalog Client's grants must cover for a rename, a
single- and multi-table commit, a recursive namespace drop and remote
signing; case-insensitive grant matching; Iceberg JSON refusals and the
413 body caps. Add an upgrade note and KI-311 to KI-314.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
A read grant now vends read-only storage credentials, and write or
manage read-write-delete. Document the rule on the catalog detail page,
the behaviour change for engines and clients with only read grants, the
access-denied symptom of a read-only write, and an upgrade note. Close
KI-311 and add KI-315 (credential lifetime and shared keys) and KI-316
(cross-warehouse register on overlapping storage).

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
KI-304 is fixed in platform #766: a StarRocks table with a mask refuses the
hidden _file and _pos columns to a reader who does not see the real value in
every masked column, so that reader's SELECT * is refused (error 5204 on _file).
Document the behaviour change in the masks page and the upgrade notes, the
wildcard-selector gap that stays open, and the compile that applies the deny.

Co-authored-by: Claude Haiku 5.5 <noreply@anthropic.com>
KI-289 is fixed in platform #768: the preview refusal of a second row filter
names the rule being created as plain text. Close the known issue and drop the
limit that described the dead link.

Co-authored-by: Claude Haiku 5.5 <noreply@anthropic.com>
Platform change: a role granted to a group now reaches the group's members on
the engines (the compile expands it). Update the clearance, People and groups
pages that said such a role was not applied on engines. Workspace memberships
held through a group are still not applied, and the pages say so.

Co-authored-by: Claude Haiku 5.5 <noreply@anthropic.com>
…#49)

Synced groups drop after 7 days without a sign-in (platform #778). A role or
workspace held through a group is applied on engines (platform #769, #782), so
the egret-only wording and the warning that said otherwise go. A mask rule
refused for a whole-table classification lists the other tables (platform #773).
An engine is bound only to a profile of its own type (platform #776).

Co-authored-by: Claude Haiku 5.5 <noreply@anthropic.com>
… hour (#50)

KI-304 is fixed in platform #798: masks selected by a wildcard or an exclusion
get the hidden-column deny. Drop the masks-page limit that said otherwise.
Expired role and workspace grants are recompiled hourly (platform #796).

Co-authored-by: Claude Haiku 5.5 <noreply@anthropic.com>
)

Groups holding a role or workspace reach their members on the engines (platform
#769, #782, #799), so the reference no longer says egret only. Only perm.md
changes; the other generated pages are not part of this change.

Co-authored-by: Claude Haiku 5.5 <noreply@anthropic.com>
…rm #764) (#52)

Close KI-308 and KI-309: a rename through egret's Iceberg catalog copies
deny grants, path masks and path row filters to the new name before the
commit and keeps them on the old name, moves allow grants and catalog
grants after it, and refuses restrictive patterns and hand-written
policies that name the table. Document the hold, the refusals, the
recursive namespace drop, the five new Overview findings and the new
Recent changes sentences. Update KI-310 and add KI-317 to KI-321.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
* docs: DG debt wave 2 (P1–P4) known issues and pages

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(api): regenerate the policy administration reference (platform #805)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(reference): regenerate REST reference for platform #807

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
…5) (#54)

Close KI-322 and KI-323 (platform #810), record KI-329 to KI-331, document
the Manual policies tab's Wider than its pattern rows and how Ranger picks
tag policies (platform #809), the retried boot recompile of role-referencing
profiles, and upgrade notes for #809 and #810.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
…als, grant leftovers (#55)

Platform #811-#815:
- close KI-319, KI-320, KI-324, KI-329, KI-330, KI-331; narrow KI-315
  (vended credentials live 15 minutes); add KI-332 (engine rebind
  through PUT bumps two profiles in no fixed order)
- document catalog.sts_token_validity_seconds, the retryable 409
  profile_set_changed, view renames and pattern hand-written policy
  checks, group delete removing its grants, and the live-allow rule
  for workspace membership and the last ws_admin
- upgrade notes for #811-#815; regenerate the affected REST pages

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
…e (KI-287, KI-307) (#56)

Platform #818:
- close KI-287 (Trino filters tables where the classification is only on
  columns) and KI-307 (attach answers a clearance_masks_pending_table
  notice, shown as a warning toast); add KI-333 (open-mode Trino engine
  has no per-user baseline) and KI-334 (Data page shows a running engine
  as provisioning)
- masks and row filters, tagging, clearance, explain access, check access
  and provision pages; upgrade notes for #818
- regenerate the resource-tags and rule-effect REST pages

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
…g known issues (#57)

* docs: final DG-debt screenshots, view attach notice, StarRocks/Iceberg known issues

- document the clearance_on_view attach notice of platform #820 (tagging,
  clearance, upgrade notes) and refine KI-307
- re-shoot gov-overview, gov-profile, gov-engine-advanced, cp-users,
  cp-users-bulk and cp-user-detail; new shots of the Manual policies tab
  (Wider than its pattern), New profile, Trino config, the Clearance 409
  alert, both attach warning toasts and the rule dialog's Kind hint, with
  their shot entries and a staged-race script for the 409
- add KI-335 to KI-344: StarRocks CN crash loop, StarRocks engine without
  a profile, _file/_pos under a StarRocks row filter, SQL Lab explorer on
  StarRocks, empty switcher on the deny-only 403 page, StarRocks Iceberg
  metadata tables bypass Ranger (open S1), Trino metadata tables (fix in
  review), grants naming a user with no username, leftover profile after a
  failed Add engine, unknown-table columns error; note on KI-304

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs: Trino metadata tables fixed (#821), StarRocks metadata-table warning (#822)

- KI-341 fixed by platform #821; masks and row filters page and upgrade notes
- describe the StarRocks warning on the Governance engine page, Control plane
  engine detail and Register external engine; KI-340 workaround; four new
  screenshots from platform main ed059897

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs: new users get an engine username at creation (#823)

- KI-342 fixed by platform #823; Users, People and groups, grants, check
  access, concepts, glossary and upgrade notes: No username yet and Allocate
  username and add now only for service accounts and people the boot pass
  could not name

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
viethqb and others added 7 commits November 2, 2026 18:34
…26) (#58)

* docs: StarRocks engines default to egret's patched image (platform #826)

KI-340 is fixed on egret's patched StarRocks FE and KI-345 (masks and row
filters skipped for prepared statements, which Data API endpoints with
parameters use) is added. Engines and Ranger describes the patched image and
how to move an engine onto it; upgrade notes, the engine pages, masks and
filters, and the local stack follow.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs: re-shoot the StarRocks warning screenshots for the patched image (#826)

- re-shoot gov-engine-starrocks-warning, cp-engine-ext-sr-overview,
  cp-engine-ext-sr-settings and cp-register-sr-warning with the new warning
  text (official images, prepared statements, egret-starrocks-fe)
- the shot entries wait for the new wording; alt texts follow it

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
…platform #827) (#59)

* docs: StarRocks engines default to egret-starrocks-fe 4.1.7-egret.3 (platform #827)

- KI-337 fixed in the patched image, KI-304 note; KI-340 and KI-345 point to
  egret.3
- new KI-346 (HTTP SQL API and Arrow Flight SQL skip masks and row filters),
  KI-347 (FILES() has no privilege), KI-348 (materialized views stored past
  the creator's policy), KI-349 (SHOW CREATE CATALOG needs no privilege)
- engines-and-ranger: image table, every hole, egret.3 pin; local stack
  image; upgrade notes; the widened warning on the engine pages

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs: re-shoot the StarRocks warning screenshots for egret.3 (platform #827)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
- Kubernetes: NetworkPolicy/egret-engine-isolation in the object table, the
  engineNetworkPolicy values, an "Engine network policy" section with the
  measured result
- security hardening: keep the engines reachable from Egret only
- upgrade notes: behaviour change, ingressFrom for an engine Ingress

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
…platform #832) (#61)

- KI-350 (EXPLAIN COSTS shows the statistics of hidden rows) and KI-351
  (loads, exports and INTO OUTFILE with the nodes' cloud identity), both
  fixed in 4.1.7-egret.4
- the StarRocks warning names them and is hidden only from egret.4:
  engine detail, register external, engines and policy, masks and filters
- engines-and-ranger: egret.4 row, holes, refusals (5213, 5214), move
  procedure; local stack allin1; upgrade note
- the four warning screenshots re-shot from the #832 frontend

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
…dmins (governance SP2a)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…iffer

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@viethqb
viethqb merged commit 196a4f2 into main Nov 4, 2026
2 checks passed
@viethqb
viethqb deleted the docs/gov-sp2a-infra-convergence branch November 4, 2026 15:36
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