Document KOTS/kURL adoption for the new Enterprise Portal

[seanoseanohay]

Summary

Documents how vendors can move KOTS/kURL customers onto the new Enterprise Portal (EP v2), scoped to what's currently merged rather than the full planned feature set.

• How to enable EP v2 for a single KOTS/kURL customer (per-customer Portal Version toggle, plus its Vendor API equivalent for scripting many at once)
• Why there's no single app-level switch that moves an existing customer base at once, and what happens to KOTS/kURL customers when they are moved
• Pairing the Portal Version toggle with the separate Security Center toggle for a customer
• How Download Portal, Classic Enterprise Portal, and the new Enterprise Portal coexist (intentional, ongoing, not just a migration step)
• What KOTS/kURL customers see today: instance visibility/labels, no in-console install/upgrade instructions, Security Center gating (hidden if a customer's only instances are KOTS/kURL), correct license labeling, and manual/support-bundle air gap instance record creation

Scope vs. Shortcut tracking

Content is scoped to match story status as of this PR:

Story	Status	Reflected in docs
sc-135427 — Backend asset URL resolution	Completed	Yes
sc-135421 — MDX download components	Completed	Yes
sc-138598 — Instance visibility	Completed	Yes
sc-138600 — Air gap instance creation	Completed	Yes
sc-138487 — Default KOTS/kURL template pages	In Development	Not yet — intentionally left out until merged
sc-138833 — Version-filtered release browsing + downloads	In Development (no code yet)	Not yet — intentionally left out until built

This is the docs deliverable for sc-138819. It links out to a spot the sc-138820 (VP portal access messaging) update can point to once that ships.

Test plan

• Vale style pass clean on all new/changed lines
• Docs review

🤖 Generated with Claude Code

Co-Authored-By: Claude Sonnet 5 noreply@anthropic.com

###Images to help give confidence:

Portal Type Toggle:

### Enterprise Portal Per Customer: ### Enterprise Portal for all customers: ### EP With Change All Customers Toggled ### Kots And Kurl Create Airgap Instance: ### Kots And Kurl Instances Shown without Drop Down: ### Security Center without helm or EC entitlments: ### Security Center Tab: ### Security Center Tab, SBOM portion:

Image

[netlify]

✅ Deploy Preview for replicated-docs ready!

Name	Link
🔨 Latest commit	e14007f
🔍 Latest deploy log	https://app.netlify.com/projects/replicated-docs/deploys/6a627684e49db20009a4d9d9
😎 Deploy Preview	https://deploy-preview-4284--replicated-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

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

[netlify]

✅ Deploy Preview for replicated-docs-upgrade ready!

Name	Link
🔨 Latest commit	e14007f
🔍 Latest deploy log	https://app.netlify.com/projects/replicated-docs-upgrade/deploys/6a6276848e1479000845223c
😎 Deploy Preview	https://deploy-preview-4284--replicated-docs-upgrade.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

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

[AmberAlston]

Review: KOTS/kURL adoption docs for the new Enterprise Portal

Thanks for getting this started. The descriptive content (what KOTS/kURL customers see in the portal) is mostly accurate and worth keeping. The procedural content (how a vendor moves customers over) is built around the wrong control and contains a few claims that don't match how the product behaves. Flagging everything below so we can correct it in one pass.

Heads up on sequencing. This doc is one item in the EP v2 Beta close-out, and it landed ahead of the other pieces it depends on:

• In-product messaging (sc-138820) will reword the app-level Portal Access description, add "KOTS/kURL is EP v2 only" notes next to the relevant toggles, and link into this page. This doc and that messaging should be reviewed and merged together so the labels, notes, and deep links line up. A couple of the corrections below exist because the doc got ahead of that work.
• Relabeling PR is a separate close-out item. If it renames any of the toggles this doc references, the labels here need to be re-checked against the shipped UI before publish. Please confirm final labels against that PR rather than against current main.
• Entitlement model (sc-138828). Visibility is moving from an internal feature flag to the EP v2 entitlement (with a per-vendor kill-switch), so please frame this doc around the entitlement and the vendor-controlled per-customer opt-in, not around any internal flag or "mode." A good durable anchor to state explicitly: EP v2 access for end customers remains per-customer opt-in, controlled by the vendor.

Because "Docs are restructured and live" is on the gate for the Beta entitlement flip, it is worth getting this one right rather than fast.

Accuracy (behavior does not match the doc)

1. "Move a KOTS or kURL customer" skips the step that actually moves them.
   The section tells vendors to switch Portal Version to the new Enterprise Portal. In the current build, the Portal Version control only appears once Enterprise Portal access is already enabled for that customer. A KOTS/kURL customer sits on the Download Portal with access off, so the move is really two steps: turn on Enable Enterprise Portal for this customer on the Enterprise Portal access tab, then set Portal Version to the new portal (Classic does not support KOTS/kURL). The doc should cover enabling access first, then Portal Version. If the Beta flow is meant to collapse this into a single Portal Version toggle for KOTS/kURL-entitled customers, let's confirm the intended UX and document that instead. Either way, the current single-step instruction leaves the customer on the Download Portal.

2. "There is no single switch that moves your entire existing customer base to the new Enterprise Portal at once" is wrong.
   There is one. The app-level Enable Enterprise Portal for all customers setting (Enterprise Portal > Customer Access) moves every customer, including KOTS/kURL, off the Download Portal and onto the Enterprise Portal at once. This line should be replaced with instructions for that toggle plus the per-customer option for selective moves.

3. "New customers ... default to the new Enterprise Portal, regardless of install type" is backwards for this audience.
   When both portals are enabled (the transitioning-vendor case this doc targets), a new customer with no explicit setting defaults to the Classic portal, not the new one. New customers default to the new portal only for teams that are on the new portal exclusively. Recommend dropping this sentence rather than trying to caveat it, since it depends on the vendor's portal configuration.

4. "Portal coexistence" overstates what one customer can have at once.
   Coexistence is real across different customers (some on the Download Portal, some on the new Enterprise Portal). It is not true for a single customer. Enabling Enterprise Portal access for a customer moves them off the Download Portal; the two are alternatives for the same customer, not concurrent. The claim that a moved customer can "keep sharing that link" and that "this works even after you move them" should come out.

5. License install-type label list does not match the UI.
   The parenthetical "(Helm, Linux (Embedded Cluster), KOTS, or kURL)" is not what the License Details page renders. It shows an Install Options list using different strings (for example "Replicated KOTS", "Embedded Cluster", "Helm Airgap"), and it is a multi-value capability list rather than a single install-type label. Drop the parenthetical and keep the plain statement that license details render regardless of install type.

6. "Do not see Security Center at all" is inaccurate (three places).
   Customers whose only instances are KOTS/kURL still see the Security Center area; it shows an explanatory message instead of security data. Reword to "see an explanatory message instead of security data." The surrounding scoping claims (mixed customers see data for their Helm/EC instances, KOTS/kURL do not contribute CVE data or counts) are correct and can stay.

Terminology and language

7. Remove "mixed mode" everywhere.
   It is an internal engineering term. It is never shown in the UI, and it is ambiguous in this doc (a reader can't tell whether it means Classic-vs-new EP or Download-Portal-vs-EP). Describe the actual state instead ("if your team runs both the Classic and the new Enterprise Portal") and use the real button labels: Enable Enterprise Portal for this customer, Enable Enterprise Portal for all customers, Portal Version, and the switch Use new Enterprise Portal for this customer. Note that "mixed mode" also appears in the existing "For vendors already using the Classic Enterprise Portal" section, so this cleanup should extend to the rest of the page, not just the new content.

8. Drop "never supported," "historically used," and "yet" style phrasing.
   For example, "The Classic Enterprise Portal never supported KOTS or kURL installations. Customers using these install types have historically used the Download Portal." State it in the present: the Classic Enterprise Portal does not support KOTS or kURL, and those customers use the Download Portal. (The related "not included ... yet" phrasing in the in-product Security Center message is being handled in sc-138820, not here.)

Readability and structure

9. Reframe the "all customers" section around the toggle that exists.
   Once corrected per item 2, the heading is accurate. The body should describe the app-level toggle for the bulk move and the per-customer path for selective moves.

10. The general adoption mechanics overlap the existing Classic-adoption section.
    The bulk-enable and coexistence content is general EP v2 adoption guidance, not KOTS/kURL-specific, and it duplicates the existing "For vendors already using the Classic Enterprise Portal" section. Consider consolidating the general mechanics there and keeping this section focused on what is KOTS/kURL-specific (instance visibility, no in-console instructions, Security Center scoping, air gap).

11. Simplify "structured install-step customization" in the limitations bullet.
    The phrase is undefined jargon. The original wording was clearer.

12. Install-type naming drift (minor, pre-existing).
    The page uses "Linux", "Linux/Embedded Cluster", "Embedded Cluster (Linux)", and "Linux (Embedded Cluster)" in different spots. The new "Linux (Embedded Cluster)" is the right direction; worth normalizing the page over time.

Please validate this by running the workflow

This is the most important ask. The corrections above come from reading the code, which is good for catching contradictions but does not confirm real behavior. These docs describe a click-path and a customer-side experience that should be exercised end to end against a real portal before we publish, on a team with both the EP v1 and EP v2 feature flags on and KOTS/kURL entitlements (the early-adopter configuration this targets). Suggested run:

1. Identify or create a KOTS or kURL customer currently on the Download Portal (Enterprise Portal access off). Note which controls appear on their Enterprise Portal access tab before you change anything (in particular, whether Portal Version is visible yet).
2. Turn on Enable Enterprise Portal for this customer. Confirm whether the Portal Version control now appears and what it defaults to.
3. Set Portal Version to the new Enterprise Portal. Log in as that customer (or use Login as customer) and confirm they land on EP v2 and the Download Portal no longer serves them.
4. As that customer, confirm each claim in the doc: KOTS/kURL instances labeled with version and status, no in-console install/upgrade instructions and no card expansion, license Install Options rendering, air gap record creation (manual and support-bundle), and Security Center showing the explanatory message when their only instances are KOTS/kURL (or data when they also have Helm/EC).
5. Separately exercise the app-level Enable Enterprise Portal for all customers path to confirm the bulk move.
6. Confirm the session-invalidation behavior by changing a logged-in customer's portal version and watching what happens on their next request.

Capturing the actual click-path and screenshots from this run will also settle the open question in item 1 (whether the move is one step or two in the Beta build).

Accurate, keep as-is

• KOTS/kURL instances appearing on Instances & Updates, labeled, with version and status.
• No in-console install/upgrade instructions for KOTS/kURL, and those cards not expanding.
• Air gap instance record creation for KOTS/kURL, gated on license install type and air gap option. (This is actually ahead of the sc-138819 draft, which still listed air gap creation as unavailable. Worth a quick confirm that it is enabled in the Beta build being documented, but the code supports it.)
• Session invalidation on a portal change.
• Fleet-level coexistence across different customers.

[AmberAlston]

see prior comment

[seanoseanohay]

Accuracy fixes:

1. Two-step move flow corrected: Enable Enterprise Portal for this customer must be on before Portal Version appears, then set it to Use new Enterprise Portal for this customer. Confirmed against AccessComponent.tsx gating logic (customerId && effectiveEnterprisePortalEnabled && epCustomizationEnabled && isHybrid && isTeamAdmin).
2. Replaced the wrong "no single switch" claim with the real Enable Enterprise Portal for all customers toggle (Enterprise Portal > Customer Access), and noted it overrides rather than overwrites each customer's individual setting.
3. Dropped the "new customers default to v2" sentence rather than caveat it.
4. Fixed per-customer coexistence: enabling access moves a customer off the Download Portal (alternative, not concurrent). Fleet-level coexistence across different customers is unchanged and still called out as intended/ongoing.
5. Dropped the license install-type label parenthetical.
6. Reworded all three "do not see Security Center at all" spots to "see an explanatory message instead of security data."

Terminology:
7. Removed "mixed mode" everywhere on the page (including the pre-existing Classic-adoption section) in favor of the real labels: Enable Enterprise Portal for this customer, Enable Enterprise Portal for all customers, Portal Version, Use new Enterprise Portal for this customer.
8. Present-tensed the Classic EP / Download Portal relationship.

Structure:
9/10. Consolidated the general bulk-enable and coexistence guidance into the existing "For vendors already using the Classic Enterprise Portal" section, and trimmed the new KOTS/kURL section down to what's actually KOTS/kURL-specific (it now just points back to that section plus the one real wrinkle: most KOTS/kURL customers start with access off).
11. Simplified "structured install-step customization" back to plain language.
12. Left the Linux/Embedded Cluster naming drift alone per your "over time" note.

[seanoseanohay]

Did manual walk through with local version via repldev.