feat(cli): add export command to generate desired-state YAML from current state by rohilsurana · Pull Request #1731 · raystack/frontier

rohilsurana · 2026-07-03T02:41:54Z

What

Adds frontier export <kind>, a top-level sibling of frontier reconcile. It reads the current state of one kind from the server through the admin API and prints it as a desired-state YAML document, the same format reconcile reads. Output goes to stdout only — redirect it to save a file. YAML is the only format.

$ frontier export platformuser --host <host> -H "Authorization:Basic <base64>" > platform-users.yaml
kind: PlatformUser
spec:
    - type: user
      ref: alice@example.org
      relation: admin

The reconcile command is unchanged. The kind argument is case-insensitive and accepts a plural, so platformusers finds PlatformUser. An unknown kind lists the available ones.

Both reconcile and export are now documented in the CLI reference (reconcile was missing from it).

Why

When an environment adopts the reconcile flow, its first desired-state file must match what already exists on the server. If it does not, the first apply makes unwanted changes. Writing that file by hand from list APIs is slow and easy to get wrong.

How

Export is part of the Reconciler contract in internal/reconcile: every kind must implement it, enforced at compile time. This follows rule 9 of RFC docs: RFC 0001 for declarative management of platform resources #1751.
PlatformUser implements it: one entry per principal and relation — a user or service user holding both admin and member exports as two entries. Users are referenced by email when they have one, service users by id. The bootstrap service account is skipped, the same as in reconcile.
Output is sorted, so re-running the export gives the same file and git diffs stay clean.
An empty platform exports spec: [], which reconcile accepts as an intentional empty list.
The kind registry moved to a shared helper, so new kinds register once for both reconcile and export.

Guarantees covered by tests

Feeding the export output straight back into reconcile --dry-run reports no changes, including principals that hold both relations.
Export of an empty platform round-trips the same way.
Unknown kinds fail with a clear error listing the available ones.

vercel · 2026-07-03T02:42:00Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
frontier	Ready	Preview, Comment	Jul 14, 2026 6:14am

coderabbitai · 2026-07-03T02:43:06Z

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

@coderabbitai resume to resume automatic reviews.
@coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

▶️ Resume reviews
🔍 Trigger review

📝 Walkthrough

Walkthrough

Adds export support to the reconcile framework, implements platform user export, and wires a new frontier export <kind> command with matching CLI help and reference docs.

Changes

Reconcile export feature

Layer / File(s)	Summary
Exporter interface and YAML export `internal/reconcile/reconcile.go`, `internal/reconcile/reconcile_test.go`	Adds the `Exporter` interface and the `Export(ctx, registry, kind)` function that emits a `{kind, spec}` YAML document, with error-path tests for unknown kinds and non-exporting reconcilers.
PlatformUser export implementation `internal/reconcile/platformuser_reconciler.go`, `internal/reconcile/platformuser_reconciler_test.go`	Adds `PlatformUserReconciler.Export`, which builds sorted `PlatformUserSpec` entries from fetched principals and is covered by export and dry-run reconciliation tests.
CLI export command and kind resolution `cmd/export.go`, `cmd/root.go`, `cmd/export_test.go`	Adds `frontier export <kind>`, kind resolution, stdout YAML printing, root registration, and resolve-kind tests.
Reconcile command wiring and help `cmd/reconcile.go`	Centralizes reconcile registry construction, updates the help text to mention export, and switches report output to `cmd.OutOrStdout()`.
CLI reference updates `docs/content/docs/reference/cli.mdx`	Adds reference sections for `frontier export <kind>` and `frontier reconcile [flags]` with examples and flags.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Possibly related PRs

raystack/frontier#1720: Extends the same reconcile framework with Exporter/Export support and the frontier export CLI path.

Suggested reviewers: AmanGIT07, rsbh, whoAbhishekSah

🚥 Pre-merge checks | ✅ 2

✅ Passed checks (2 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

coderabbitai

Actionable comments posted: 1

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 75607dba-a629-489d-b90a-5de555cb5f68

📥 Commits

Reviewing files that changed from the base of the PR and between 4a8d725 and 2ca9edd.

📒 Files selected for processing (5)

cmd/reconcile.go
internal/reconcile/platformuser_reconciler.go
internal/reconcile/platformuser_reconciler_test.go
internal/reconcile/reconcile.go
internal/reconcile/reconcile_test.go

coveralls · 2026-07-03T02:48:23Z

Coverage Report for CI Build 29316383996

Warning

Build has drifted: This PR's base is out of sync with its target branch, so coverage data may include unrelated changes.
Quick fix: rebase this PR. Learn more →

Coverage increased (+0.1%) to 44.984%

Details

Coverage increased (+0.1%) from the base build.
Patch coverage: 37 uncovered changes across 4 files (92 of 129 lines covered, 71.32%).
230 coverage regressions across 8 files.

Uncovered Changes

File	Changed	Covered	%
cmd/export.go	48	33	68.75%
cmd/reconcile.go	16	2	12.5%
internal/reconcile/reconcile.go	39	33	84.62%
internal/reconcile/platformuser_reconciler.go	25	23	92.0%
Total (5 files)	129	92	71.32%

Coverage Regressions

230 previously-covered lines in 8 files lost coverage.

File	Lines Losing Coverage	Coverage
core/invitation/service.go	66	50.54%
cmd/serve.go	42	0.0%
internal/api/v1beta1connect/group.go	42	83.05%
internal/store/postgres/group_repository.go	32	76.03%
core/group/service.go	22	54.78%
internal/store/postgres/org_users_repository.go	11	73.24%
cmd/group.go	8	43.8%
internal/store/postgres/invitation_repository.go	7	79.51%

Coverage Stats


Relevant Lines:	37756
Covered Lines:	16984
Line Coverage:	44.98%
Coverage Strength:	12.64 hits per line

💛 - Coveralls

coderabbitai

Actionable comments posted: 1

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 025c0faa-f5bc-4b12-bf33-7bcc3ee2fbaa

📥 Commits

Reviewing files that changed from the base of the PR and between 2ca9edd and d553b7f.

📒 Files selected for processing (7)

cmd/apply.go
cmd/get.go
cmd/root.go
internal/reconcile/platformuser_reconciler.go
internal/reconcile/platformuser_reconciler_test.go
internal/reconcile/reconcile.go
internal/reconcile/reconcile_test.go

✅ Files skipped from review due to trivial changes (1)

internal/reconcile/reconcile.go

🚧 Files skipped from review as they are similar to previous changes (3)

internal/reconcile/platformuser_reconciler.go
internal/reconcile/platformuser_reconciler_test.go
internal/reconcile/reconcile_test.go

coderabbitai

♻️ Duplicate comments (1)

cmd/export.go (1)
51-56: 🔒 Security & Privacy | 🟡 Minor | ⚡ Quick win

Narrow output file permissions for exported PII.

The exported document contains per-principal emails; writing with 0o644 leaves it world-readable. Matches an already-flagged concern on a prior commit of this file.
🔒 Proposed fix
-			return os.WriteFile(output, out, 0o644)
+			return os.WriteFile(output, out, 0o600)

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 4ef1ccea-dab3-45ac-8fb9-8f03784960e8

📥 Commits

Reviewing files that changed from the base of the PR and between d553b7f and 987ae62.

📒 Files selected for processing (7)

cmd/export.go
cmd/reconcile.go
cmd/root.go
internal/reconcile/platformuser_reconciler.go
internal/reconcile/platformuser_reconciler_test.go
internal/reconcile/reconcile.go
internal/reconcile/reconcile_test.go

🚧 Files skipped from review as they are similar to previous changes (4)

internal/reconcile/reconcile_test.go
internal/reconcile/reconcile.go
internal/reconcile/platformuser_reconciler.go
internal/reconcile/platformuser_reconciler_test.go

…rent state

…xport in CLI reference

…tderr

coderabbitai

🧹 Nitpick comments (1)

cmd/export.go (1)
47-50: 🚀 Performance & Scalability | 🔵 Trivial | 💤 Low value

Skip the byte→string conversion.

string(out) allocates a copy just to hand it back to Fprint. Writing the bytes directly avoids the extra allocation.
♻️ Proposed simplification
-			// cobra's cmd.Print falls back to stderr; the document must go to
-			// stdout so redirecting to a file works.
-			_, err = fmt.Fprint(cmd.OutOrStdout(), string(out))
-			return err
+			// cobra's cmd.Print falls back to stderr; the document must go to
+			// stdout so redirecting to a file works.
+			_, err = cmd.OutOrStdout().Write(out)
+			return err

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: a3d55fcb-3ab0-46c1-9eb0-a4adceb02a73

📥 Commits

Reviewing files that changed from the base of the PR and between 987ae62 and 62bea17.

📒 Files selected for processing (9)

cmd/export.go
cmd/export_test.go
cmd/reconcile.go
cmd/root.go
docs/content/docs/reference/cli.mdx
internal/reconcile/platformuser_reconciler.go
internal/reconcile/platformuser_reconciler_test.go
internal/reconcile/reconcile.go
internal/reconcile/reconcile_test.go

🚧 Files skipped from review as they are similar to previous changes (4)

internal/reconcile/reconcile_test.go
internal/reconcile/platformuser_reconciler_test.go
internal/reconcile/platformuser_reconciler.go
internal/reconcile/reconcile.go

whoAbhishekSah

Future Improvement suggestion: CLI filter for type supporting user and serviceuser.

rohilsurana · 2026-07-14T04:36:39Z

From the RFC review (#1751): export must be required for every kind, per rule 9 there. This PR describes Exporter as "the optional reverse of Reconciler", and a kind without it just lacks the command. Suggest making it part of the contract: every registered kind must implement Export, and registering one that does not should fail (or the interface should be folded into Reconciler so it cannot compile without it). The RFC text is being updated to match.

rohilsurana · 2026-07-14T04:47:05Z

Done — Export is folded into the Reconciler interface, so a kind cannot compile without it (commit e1c67b4, merged up to #1737 as well). The separate Exporter interface and the "does not support export" runtime error are gone, and the RFC's framework section no longer says "(optional)" (#1751).

… applying

rohilsurana · 2026-07-14T06:18:40Z

Two more changes landed here from the RFC review (#1751): documents now carry apiVersion: v1 (absent means v1 so existing files keep working; unknown versions are rejected; export emits the field), and Run parses and checks the whole file before dispatching anything, so a malformed later document stops the run before any change applies (b92eeda). Both are merged up to #1737.

rohilsurana · 2026-07-15T11:10:53Z

Review note

An independent pass flagged docs/content/docs/reconcile.mdx as only covering
PlatformUser. That is correct for this PR on its own, and it stays consistent here: the
CLI reference on this branch also lists only PlatformUser. The guide grows to cover the
Permission and Role kinds in the stacked PR #1737, alongside the code that adds them.
No change needed here.

vercel Bot deployed to Preview July 3, 2026 02:42 View deployment

coderabbitai Bot reviewed Jul 3, 2026

View reviewed changes

Comment thread cmd/reconcile.go Outdated

rohilsurana force-pushed the feat/reconcile-export branch from 2ca9edd to d553b7f Compare July 3, 2026 09:29

rohilsurana changed the title ~~feat(reconcile): add export command to generate desired-state YAML from current state~~ feat(cli): add 'get' command to export desired-state YAML and rename 'reconcile' to 'apply' Jul 3, 2026

vercel Bot deployed to Preview July 3, 2026 09:30 View deployment

coderabbitai Bot reviewed Jul 3, 2026

View reviewed changes

Comment thread cmd/get.go Outdated

rohilsurana force-pushed the feat/reconcile-export branch from d553b7f to 987ae62 Compare July 3, 2026 09:38

rohilsurana changed the title ~~feat(cli): add 'get' command to export desired-state YAML and rename 'reconcile' to 'apply'~~ feat(cli): add export command to generate desired-state YAML from current state Jul 3, 2026

vercel Bot deployed to Preview July 3, 2026 09:38 View deployment

coderabbitai Bot reviewed Jul 3, 2026

View reviewed changes

feat(cli): add export command to generate desired-state YAML from cur…

12fc9a5

…rent state

rohilsurana force-pushed the feat/reconcile-export branch from 987ae62 to 12fc9a5 Compare July 3, 2026 10:12

vercel Bot deployed to Preview July 3, 2026 10:12 View deployment

refactor(cli): export prints to stdout only, document reconcile and e…

5502e7c

…xport in CLI reference

vercel Bot deployed to Preview July 3, 2026 10:26 View deployment

rohilsurana mentioned this pull request Jul 3, 2026

feat(reconcile): add Permission and Role kinds, bootstrap only creates missing roles #1737

Merged

fix(cli): write export document and reconcile report to stdout, not s…

62bea17

…tderr

vercel Bot deployed to Preview July 3, 2026 14:40 View deployment

fix(cli): skip the empty report a failed reconcile document produces

4c606c0

coderabbitai Bot reviewed Jul 3, 2026

View reviewed changes

vercel Bot deployed to Preview July 3, 2026 14:44 View deployment

rohilsurana requested a review from whoAbhishekSah July 4, 2026 14:20

whoAbhishekSah approved these changes Jul 6, 2026

View reviewed changes

rohilsurana mentioned this pull request Jul 13, 2026

docs: RFC 0001 for declarative management of platform resources #1751

Open

refactor(reconcile): make Export part of the Reconciler contract

e1c67b4

vercel Bot deployed to Preview July 14, 2026 04:45 View deployment

feat(reconcile): add apiVersion to documents, parse whole file before…

b92eeda

… applying

vercel Bot deployed to Preview July 14, 2026 06:14 View deployment

docs: add reconcile and export guide

f852e60

rohilsurana mentioned this pull request Jul 15, 2026

feat(reconcile): add a Preference kind #1762

Merged

rohilsurana merged commit 45b45db into main Jul 16, 2026
6 checks passed

rohilsurana deleted the feat/reconcile-export branch July 16, 2026 05:41

Uh oh!

Conversation

rohilsurana commented Jul 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What

Why

How

Guarantees covered by tests

Uh oh!

vercel Bot commented Jul 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coderabbitai Bot commented Jul 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Reviews paused

Walkthrough

Changes

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

coveralls commented Jul 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Coverage Report for CI Build 29316383996

Coverage increased (+0.1%) to 44.984%

Details

Uncovered Changes

Coverage Regressions

Coverage Stats

💛 - Coveralls

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

whoAbhishekSah left a comment

Choose a reason for hiding this comment

Uh oh!

rohilsurana commented Jul 14, 2026

Uh oh!

rohilsurana commented Jul 14, 2026

Uh oh!

rohilsurana commented Jul 14, 2026

Uh oh!

rohilsurana commented Jul 15, 2026

Review note

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

rohilsurana commented Jul 3, 2026 •

edited

Loading

vercel Bot commented Jul 3, 2026 •

edited

Loading

coderabbitai Bot commented Jul 3, 2026 •

edited

Loading

coveralls commented Jul 3, 2026 •

edited

Loading