Skip to content

PER-14389: Migrate from Permit Cloud — on-prem import guide#647

Open
EliMoshkovich wants to merge 5 commits into
masterfrom
PER-14389-migrate-from-cloud-import-guide
Open

PER-14389: Migrate from Permit Cloud — on-prem import guide#647
EliMoshkovich wants to merge 5 commits into
masterfrom
PER-14389-migrate-from-cloud-import-guide

Conversation

@EliMoshkovich

@EliMoshkovich EliMoshkovich commented Jul 8, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Summary

  • Adds a customer-facing guide to the On-Premises Deployment section for importing a Permit-delivered migration data package (SaaS → on-prem migration, import side only).
  • The export side is deliberately out of scope: it is performed by Permit and delivered as a secure download link, so the page documents how to request the migration (window, optional 90-day audit history, version alignment) rather than any internal tooling.

Linear Issue

PER-14389

Changes

  • New page: docs/how-to/deploy/on-prem/migrate-from-cloud.mdx (picked up automatically by the autogenerated on-prem sidebar)
  • Content: package request + checksum verification, pre-import DB backup, write-freeze (verified chart deployment names), ordered table import with fail-fast loops, the same-session FK-disable form for v2_api_key/v2_pdp_config, dangling-member cleanup, cloud-specific config cleanup (SSO/webhooks/PDP review), admin superuser grant, org-filtered row-count verification against manifest.json, Keycloak email-linking for member access (verified-email requirement), SDK cutover snippet, troubleshooting
  • One-line companion fix in management.mdx: backend health check /api/v2/health → /v2/healthy (same /api routing hole as the review finding below; the backend route is /healthy under the /v2 prefix)

Review round (2026-07-13)

  • api_url fixed (Zeev): dropped the /api suffix from the SDK cutover snippet. On-prem, the ingress routes everything to the frontend and its nginx proxies only location /v2/ to the backend — with /api every management call fell into the SPA fallback and returned HTML. Verified against the platform chart ingress, the frontend nginx config, and APP_PREFIX = "/v2" in permit-backend.
  • kubectl scale portability (Copilot): scale-down now uses the explicit deployment/<name> resource form with flags first.
  • Independent re-verification pass: chart deployment names (permit-backend-v2, celery-general, permit-dl-enricher-v2), postgres pod label / -U permit -d permit convention (matches sibling on-prem docs), initdb --username makes the app user the bootstrap superuser (so session_replication_role works), v2_member.is_superuser and v2_user_invite.member_id columns exist, manifest jq paths match the real manifest schema, delivery-package layout matches the internal plan (permit-migration-<org>-<ts>/ with policy-repo/ + README.md), all anchors/relative links valid.

Test plan

  • npm run build passes: 0 bad links, 0 bad anchors (review-round edits touch fenced code blocks only)
  • Every command verified against the validated internal migration runbook and the on-prem Helm chart (deployment names, postgres pod label, DB name/user, namespace)
  • Independent deep review with a customer-facing lens; all findings fixed (incl. a critical kubectl cp path mismatch that would have broken every import command, unfiltered verification counts, missing backup step, and policy-repo coverage)
  • Review-round findings fixed and re-verified against the platform chart + backend source (see above)
  • No references to unreleased internal tooling (export endpoint, installer import flag)

🤖 Generated with Claude Code

@EliMoshkovich @claude
PER-14389: add "Migrate from Permit Cloud" on-prem import guide
c5a226c 
Customer-facing guide for importing a Permit-delivered migration data
package into an on-prem deployment: package request/verification, DB
backup, write-freeze, ordered table import (with the same-session
FK-disable form for api_key/pdp_config), post-import cleanup and
superuser grant, org-filtered verification against the manifest,
Keycloak email-linking for member access, and troubleshooting.

Import side only — the export is performed by Permit and delivered as a
secure download link; no internal tooling is referenced.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Copilot AI review requested due to automatic review settings July 8, 2026 19:44
@linear-code

linear-code Bot commented Jul 8, 2026

Copy link
Copy Markdown

PER-14389

@netlify

netlify Bot commented Jul 8, 2026 •
edited
Loading

Copy link
Copy Markdown

✅ Deploy Preview for permitio-docs ready!

Name Link
🔨 Latest commit c3f3ff7
🔍 Latest deploy log https://app.netlify.com/projects/permitio-docs/deploys/6a5546b819bf7c0008175aee
😎 Deploy Preview https://deploy-preview-647--permitio-docs.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

Copilot AI reviewed Jul 8, 2026
View reviewed changes

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Adds a new customer-facing, enterprise-only on-prem guide that walks users through importing a Permit-provided SaaS → on-prem migration package (requesting the package, integrity verification, safe/ordered DB import, post-import cleanup, verification, and app cutover guidance).

Changes:

  • Introduces a new on-prem migration guide page covering package request/process and detailed import steps.
  • Documents operational safety steps (write-freeze, pre-import DB backup, fail-fast import loops) and post-import cleanup/verification.
  • Adds team-member re-access guidance (Keycloak email linking + verified-email requirement) and an SDK endpoint cutover snippet.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comment thread docs/how-to/deploy/on-prem/migrate-from-cloud.mdx Outdated
Comment thread docs/how-to/deploy/on-prem/migrate-from-cloud.mdx Outdated
EliMoshkovich and others added 3 commits July 8, 2026 14:55
@EliMoshkovich @claude
PER-14389: round-2 review fixes — disclosure + customer-friendliness
dc345be 
Critical: the SDK cutover snippet omitted the api_url override, so a
migrated app's management calls would silently keep writing to the old
Permit Cloud workspace; it also pointed pdp= at the platform domain
instead of an on-prem PDP deployment. Now shows both endpoints with a
do-not-skip caution and links PDP Deployment.

Over-disclosure removed:
- 41-table schema list replaced with a manifest-driven loop
  (manifest.import.tables_in_order / fk_disabled_tables — contract added
  to the export in the backend PR), so public docs carry no schema dump
  and can't drift per installer version
- avp_policy_store_id cleanup SQL (cloud-provider internals) moved to
  the package README; docs keep only the customer-relevant review bullets
- unilateral commitments softened: audit retention period, download-link
  expiry, "without code changes"/"automatically regain access" guarantees

Friendliness: "At a glance" orientation (phases, downtime window, done
criteria, Permit assistance), pg_restore rollback snippet, jq/tar/sha256
prerequisites, replica-count note before scale-down, FK-bypass scoping
caution, platform-wide superuser caution, dependency-order gloss, and
the standard Support footer.

Build: 0 bad links, 0 bad anchors.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@EliMoshkovich @claude
PER-14389: single-transaction import (FK-graph analysis fix)
702f53d 
FK-graph verification against the schema found the documented ordered
import cannot work for all customers: v2_project <-> v2_policy_repo
reference each other (a genuine FK cycle, hit by any GitOps org), plus
two more order violations masked in the original validation by empty
tables. The import now runs as one FK-deferred transaction
(--single-transaction + ON_ERROR_STOP): all-or-nothing, safe because the
package is a single consistent snapshot, and simpler for customers -
any failure rolls back cleanly and the step is just rerun.

Troubleshooting updated accordingly (partial-import scenario no longer
exists; added a guard entry for packages predating manifest.import).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@EliMoshkovich @claude
PER-14389: final proofread fixes — version-safe atomicity + clarity
2c8ac07 
- Replace --single-transaction with explicit BEGIN/COMMIT: on psql <= 14 a
  client-side \COPY failure under --single-transaction COMMITs the
  already-loaded tables (rollback-on-client-error landed in psql 15),
  breaking the all-or-nothing promise; explicit BEGIN/COMMIT is atomic on
  every version (verified empirically on psql 14 and 16).
- Admonition: "turned off" not "deferred" (no DEFERRABLE semantics), and
  forward-reference the step-6 member cleanup as the one known exception
  to snapshot consistency.
- Step 8: log out/in only works after the step-9 restart.
- Step 9: per-deployment scale commands (one --replicas flag can't express
  three different counts).
- Troubleshooting: "prints no COPY lines" (psql still prints SET/BEGIN).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
zeevmoney
zeevmoney previously requested changes Jul 13, 2026
View reviewed changes

@zeevmoney zeevmoney left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is an automated review. See comments.

Comment thread docs/how-to/deploy/on-prem/migrate-from-cloud.mdx Outdated
@EliMoshkovich @claude
PER-14389: review fixes — drop /api prefix, portable kubectl scale form
c3f3ff7 
- api_url must not carry an /api suffix: on-prem routes only /v2/ through
  the frontend nginx to the backend (verified against the platform chart
  ingress and permit-backend APP_PREFIX); with /api every SDK management
  call lands on the SPA fallback and returns HTML (Zeev's finding)
- scale-down command uses the explicit deployment/<name> resource form
  with flags first (portable across kubectl versions; Copilot's finding)
- management.mdx backend health check: /api/v2/health -> /v2/healthy
  (the actual backend route; same /api routing hole as above)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@EliMoshkovich
EliMoshkovich requested a review from zeevmoney July 13, 2026 20:13
zeevmoney
zeevmoney reviewed Jul 13, 2026
View reviewed changes

@zeevmoney zeevmoney left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Automated Review - the PR looks clean, found nothing.

@EliMoshkovich
EliMoshkovich requested a review from zeevmoney July 13, 2026 22:15
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot Copilot left review comments
@zeevmoney zeevmoney zeevmoney approved these changes

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@EliMoshkovich @zeevmoney