From 414724ec0b34131511f30ffbc6d06069f6cc02af Mon Sep 17 00:00:00 2001 From: Amber Alston Date: Wed, 27 May 2026 15:31:53 -0600 Subject: [PATCH 1/4] Add wizard config screen and branding docs for EC v3 Add two new sections to the EC v3 "Configure Embedded Cluster" page: - "Set up the wizard's Configure screen" - explains how the Config CR maps to the wizard UI, with a worked example showing groups, conditional fields, and key concepts - "Customize the wizard branding" - explains how the Application CR title and icon fields appear in the wizard These sections ensure EC v3 users can set up and brand the wizard without visiting the KOTS docs. Part of KOTS de-emphasis Phase 2 (epic 137934): - Addresses sc-137943 (config screen setup) - Addresses sc-137945 (wizard branding) Co-Authored-By: Claude Opus 4.6 (1M context) --- embedded-cluster/embedded-using.mdx | 85 +++++++++++++++++++++++++++++ 1 file changed, 85 insertions(+) diff --git a/embedded-cluster/embedded-using.mdx b/embedded-cluster/embedded-using.mdx index b42a2c960c..c63c0f0d7b 100644 --- a/embedded-cluster/embedded-using.mdx +++ b/embedded-cluster/embedded-using.mdx @@ -51,6 +51,91 @@ To create an application release that supports installation with Embedded Cluste 1. Install with Embedded Cluster in a development environment to test. See [Online installation with Embedded Cluster](installing-embedded) or [Air gap installation with Embedded Cluster](installing-embedded-air-gap). +## Set up the wizard's Configure screen {#configure-screen} + +During installation and upgrades, the Embedded Cluster wizard includes a **Configure** step where end customers provide configuration values for your application. This screen is defined by the [Config custom resource](/reference/custom-resource-config) in your release. + +The Config custom resource lets you define groups of configuration fields that appear in the wizard. Each group becomes a section in the sidebar, and customers navigate between groups to complete the configuration. + +### How it works + +The Config custom resource defines one or more groups, each containing one or more items. During installation, the wizard renders these as form fields. The values that customers provide are available to your Helm chart through [Replicated template functions](/reference/template-functions-about). + +For example, the following Config custom resource defines two groups: + +```yaml +apiVersion: kots.io/v1beta1 +kind: Config +metadata: + name: config-sample +spec: + groups: + - name: database + title: Database Configuration + description: Choose 'Embedded' to deploy PostgreSQL within the cluster, or 'External' to connect to your own PostgreSQL instance. + items: + - name: database_type + title: PostgreSQL Type + type: select_one + default: embedded + items: + - name: embedded + title: Embedded PostgreSQL + - name: external + title: External PostgreSQL + - name: external_host + title: PostgreSQL Host + type: text + when: '{{repl ConfigOptionEquals "database_type" "external"}}' + - name: features + title: Features + items: + - name: enable_feature_x + title: Enable Feature X + type: bool + default: "0" +``` + +In the wizard, this renders as two groups in the sidebar ("Database Configuration" and "Features"). Customers select their database type, and if they choose "External PostgreSQL", additional fields appear for the database connection details. + +### Key concepts + +- **Groups** define the sidebar sections. Each group has a `title` that appears in the sidebar and a list of `items`. +- **Items** define individual form fields. Supported types include `text`, `password`, `bool`, `select_one`, `textarea`, and more. See the [Config custom resource reference](/reference/custom-resource-config) for all available types. +- **Conditional fields** use the `when` property with template functions to show or hide fields based on other values. This lets you create dynamic forms that adapt to customer choices. +- **Default values** and **generated values** (such as auto-generated passwords) reduce the number of fields customers need to fill in manually. +- **Validation** can be added using the `validation` property to check field values against regex patterns before the customer proceeds. + +During upgrades, the wizard pre-populates the Configure screen with the customer's existing values, allowing them to review and update their configuration before proceeding. + +For the complete field reference, see [Config custom resource](/reference/custom-resource-config). + +## Customize the wizard branding {#branding} + +You can customize the appearance of the Embedded Cluster install and upgrade wizard using the [Application custom resource](/reference/custom-resource-application) in your release. The Application custom resource lets you set a custom title and icon that appear throughout the wizard. + +### Set the title and icon + +Add an Application custom resource to your release with the `title` and `icon` fields: + +```yaml +apiVersion: kots.io/v1beta1 +kind: Application +metadata: + name: my-app +spec: + title: My Application + icon: https://example.com/icon.png +``` + +The `title` appears in the wizard header on every screen, along with "Installation Wizard" or "Upgrade Wizard" as the subtitle. The `icon` appears next to the title. If no icon is provided, a default letter avatar is generated from the first character of the title. + +:::note +For air gap installations, use a Base64 encoded image for the `icon` field because remote URLs are not accessible in air gap environments. +::: + +For more information about the Application custom resource fields, see [Application custom resource](/reference/custom-resource-application). + ## Add support for air gap installations {#local-image-registry} This section describes how to support air gap installations with Embedded Cluster v3. It includes information about how to configure your release and lists the limitations and known issues of air gap installations with Embedded Cluster v3. From 1534fdb70e0148ff27d05e03967a68608b144662 Mon Sep 17 00:00:00 2001 From: Amber Alston Date: Thu, 28 May 2026 12:43:20 -0600 Subject: [PATCH 2/4] Update embedded-cluster/embedded-using.mdx Co-authored-by: Evans Mungai --- embedded-cluster/embedded-using.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/embedded-cluster/embedded-using.mdx b/embedded-cluster/embedded-using.mdx index c63c0f0d7b..b3b51e8ecc 100644 --- a/embedded-cluster/embedded-using.mdx +++ b/embedded-cluster/embedded-using.mdx @@ -124,7 +124,7 @@ kind: Application metadata: name: my-app spec: - title: My Application + title: Acme Application icon: https://example.com/icon.png ``` From 77a023cb462e157727f455b2a271e6abf61f120a Mon Sep 17 00:00:00 2001 From: Amber Alston Date: Thu, 28 May 2026 12:43:32 -0600 Subject: [PATCH 3/4] Update embedded-cluster/embedded-using.mdx Co-authored-by: Evans Mungai --- embedded-cluster/embedded-using.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/embedded-cluster/embedded-using.mdx b/embedded-cluster/embedded-using.mdx index b3b51e8ecc..04218c6f38 100644 --- a/embedded-cluster/embedded-using.mdx +++ b/embedded-cluster/embedded-using.mdx @@ -122,7 +122,7 @@ Add an Application custom resource to your release with the `title` and `icon` f apiVersion: kots.io/v1beta1 kind: Application metadata: - name: my-app + name: acme-app spec: title: Acme Application icon: https://example.com/icon.png From f1026634f7ecd910e448e9f80112b73f3442c084 Mon Sep 17 00:00:00 2001 From: Amber Alston Date: Thu, 28 May 2026 12:43:44 -0600 Subject: [PATCH 4/4] Update embedded-cluster/embedded-using.mdx Co-authored-by: Evans Mungai --- embedded-cluster/embedded-using.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/embedded-cluster/embedded-using.mdx b/embedded-cluster/embedded-using.mdx index 04218c6f38..00d58b04dc 100644 --- a/embedded-cluster/embedded-using.mdx +++ b/embedded-cluster/embedded-using.mdx @@ -125,7 +125,7 @@ metadata: name: acme-app spec: title: Acme Application - icon: https://example.com/icon.png + icon: https://acme.com/icon.png ``` The `title` appears in the wizard header on every screen, along with "Installation Wizard" or "Upgrade Wizard" as the subtitle. The `icon` appears next to the title. If no icon is provided, a default letter avatar is generated from the first character of the title.