From c31227c2de3dc15cbf71beb74fbe5f6e5694312c Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 15 Dec 2025 21:47:49 +0000 Subject: [PATCH 1/7] Initial plan From fc66eaf8d5eec707570c39c76ac61436a76a5bca Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 15 Dec 2025 21:52:14 +0000 Subject: [PATCH 2/7] docs(cloud): add INIT_CONFIG environment variable documentation to deployment guide Co-authored-by: pontusringblom <170570911+pontusringblom@users.noreply.github.com> --- .../en/cloud/self-hosted/deployment/_index.md | 50 ++++++++++++++++++- 1 file changed, 49 insertions(+), 1 deletion(-) diff --git a/content/en/cloud/self-hosted/deployment/_index.md b/content/en/cloud/self-hosted/deployment/_index.md index edc0858b4..2e3fa3a7b 100644 --- a/content/en/cloud/self-hosted/deployment/_index.md +++ b/content/en/cloud/self-hosted/deployment/_index.md @@ -6,7 +6,55 @@ tags: [helm] weight: 2 --- -## High-level List of Deployment Tasks +## High-level List of Deployment + +## Environment Variables + +### INIT_CONFIG + +The `INIT_CONFIG` environment variable allows you to configure the initial setup of your self-hosted Layer5 Cloud provider. This variable accepts a JSON string that defines the provider initialization configuration. + +#### Purpose + +`INIT_CONFIG` enables you to: +- Pre-configure provider settings during deployment +- Automate initial setup for consistent deployments +- Define custom provider configurations without manual intervention + +#### Usage + +Set the `INIT_CONFIG` environment variable with a JSON configuration string: + +```bash +export INIT_CONFIG='{"provider": {"name": "my-provider", "settings": {...}}}' +``` + +For Docker deployments: + +```bash +docker run -e INIT_CONFIG='{"provider": {"name": "my-provider"}}' layer5/meshery-cloud +``` + +For Kubernetes deployments, add to your deployment manifest: + +```yaml +env: + - name: INIT_CONFIG + value: '{"provider": {"name": "my-provider", "settings": {...}}}' +``` + +{{< alert type="info" title="Note" >}} +The INIT_CONFIG variable is only processed during the initial startup. Subsequent restarts will not reprocess this configuration. +{{< /alert >}} + +#### Configuration Schema + +The `INIT_CONFIG` JSON structure supports the following fields: + +- `provider.name`: The name of your provider instance +- `provider.settings`: Custom provider settings specific to your deployment + +For detailed configuration options, refer to the [provider initialization documentation](https://github.com/layer5io/meshery-cloud/blob/master/docs/provider-init.md). Tasks
  1. Review the prequisites for installing Layer5 Cloud on Kubernetes. (docs)
    2. From 723d23a9e7feb589274b4b5756debe9b8bfa7986 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 15 Dec 2025 21:53:01 +0000 Subject: [PATCH 3/7] docs(cloud): add provider configuration planning guide for INIT_CONFIG Co-authored-by: pontusringblom <170570911+pontusringblom@users.noreply.github.com> --- .../en/cloud/self-hosted/planning/_index.md | 29 ++++++++++++++++++- 1 file changed, 28 insertions(+), 1 deletion(-) diff --git a/content/en/cloud/self-hosted/planning/_index.md b/content/en/cloud/self-hosted/planning/_index.md index fe8728f57..fd28ecbb0 100644 --- a/content/en/cloud/self-hosted/planning/_index.md +++ b/content/en/cloud/self-hosted/planning/_index.md @@ -1,5 +1,32 @@ --- -title: Planning Layer5 Cloud Deployment +title: Planning + +## Provider Configuration Planning + +When planning your self-hosted Layer5 Cloud deployment, consider how you will initialize and configure your provider instance. The `INIT_CONFIG` environment variable enables you to automate provider configuration during deployment. + +### Configuration Strategy + +Before deploying, plan your configuration approach: + +1. **Provider Identity**: Define your provider name and identification +2. **Initial Settings**: Determine which settings need to be configured at startup +3. **Configuration Management**: Decide how configuration will be managed (environment variables, secrets, config files) +4. **Update Strategy**: Plan for configuration updates and changes over time + +### Using INIT_CONFIG for Automated Setup + +The `INIT_CONFIG` environment variable allows you to pre-configure your provider during deployment, eliminating manual setup steps. This is particularly valuable for: + +- **Reproducible Deployments**: Ensure consistent configuration across environments +- **CI/CD Integration**: Automate deployments with predefined configurations +- **Infrastructure as Code**: Manage provider configuration alongside your infrastructure + +For detailed usage and examples, see the [Deployment Guide](/cloud/self-hosted/deployment/#init_config). + +{{< alert type="warning" title="Important" >}} +Plan your INIT_CONFIG carefully as it is only processed during initial startup. Changes require redeployment or manual configuration updates. +{{< /alert >}} Layer5 Cloud Deployment description: "Understand deployment prerequisites and prepare your environment for a secure and scalable Layer5 Cloud deployment." categories: [Self-Hosted] #tags: [helm] From 8f443c7aaf3f7618688c1c1852f9393c2b5074c7 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 15 Dec 2025 22:12:25 +0000 Subject: [PATCH 4/7] fix(cloud): correct frontmatter structure in planning guide Co-authored-by: pontusringblom <170570911+pontusringblom@users.noreply.github.com> --- content/en/cloud/self-hosted/planning/_index.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/content/en/cloud/self-hosted/planning/_index.md b/content/en/cloud/self-hosted/planning/_index.md index fd28ecbb0..677426317 100644 --- a/content/en/cloud/self-hosted/planning/_index.md +++ b/content/en/cloud/self-hosted/planning/_index.md @@ -1,5 +1,8 @@ --- title: Planning +description: Plan your self-hosted Layer5 Cloud deployment +weight: 2 +--- ## Provider Configuration Planning @@ -26,7 +29,8 @@ For detailed usage and examples, see the [Deployment Guide](/cloud/self-hosted/d {{< alert type="warning" title="Important" >}} Plan your INIT_CONFIG carefully as it is only processed during initial startup. Changes require redeployment or manual configuration updates. -{{< /alert >}} Layer5 Cloud Deployment +{{< /alert >}} + Layer5 Cloud Deployment description: "Understand deployment prerequisites and prepare your environment for a secure and scalable Layer5 Cloud deployment." categories: [Self-Hosted] #tags: [helm] From 24df97a1c06e9e522341246cef6a7a6d1f2f6656 Mon Sep 17 00:00:00 2001 From: Lee Calcote Date: Fri, 2 Jan 2026 11:06:51 -0600 Subject: [PATCH 5/7] Update content/en/cloud/self-hosted/deployment/_index.md Signed-off-by: Lee Calcote --- content/en/cloud/self-hosted/deployment/_index.md | 1 - 1 file changed, 1 deletion(-) diff --git a/content/en/cloud/self-hosted/deployment/_index.md b/content/en/cloud/self-hosted/deployment/_index.md index 2e3fa3a7b..c177a10d4 100644 --- a/content/en/cloud/self-hosted/deployment/_index.md +++ b/content/en/cloud/self-hosted/deployment/_index.md @@ -54,7 +54,6 @@ The `INIT_CONFIG` JSON structure supports the following fields: - `provider.name`: The name of your provider instance - `provider.settings`: Custom provider settings specific to your deployment -For detailed configuration options, refer to the [provider initialization documentation](https://github.com/layer5io/meshery-cloud/blob/master/docs/provider-init.md). Tasks
    1. Review the prequisites for installing Layer5 Cloud on Kubernetes. (docs)
      2. From 30615c4534b19bffcf7d625095788eab81106d3e Mon Sep 17 00:00:00 2001 From: pontus <170570911+pontusringblom@users.noreply.github.com> Date: Fri, 2 Jan 2026 11:50:47 -0600 Subject: [PATCH 6/7] Update content/en/cloud/self-hosted/deployment/_index.md Co-authored-by: Kishore B <85435355+kishore08-07@users.noreply.github.com> Signed-off-by: pontus <170570911+pontusringblom@users.noreply.github.com> --- content/en/cloud/self-hosted/deployment/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/cloud/self-hosted/deployment/_index.md b/content/en/cloud/self-hosted/deployment/_index.md index c177a10d4..1d7b7b655 100644 --- a/content/en/cloud/self-hosted/deployment/_index.md +++ b/content/en/cloud/self-hosted/deployment/_index.md @@ -6,7 +6,7 @@ tags: [helm] weight: 2 --- -## High-level List of Deployment +## High-level List of Deployment Tasks ## Environment Variables From b76bdfa6bc1bdd3937f77a138251540d1357df85 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 2 Jan 2026 17:55:44 +0000 Subject: [PATCH 7/7] docs(cloud): update deployment guide headings and add comprehensive YAML config details Co-authored-by: pontusringblom <170570911+pontusringblom@users.noreply.github.com> --- .../en/cloud/self-hosted/deployment/_index.md | 3 +- .../en/cloud/self-hosted/planning/_index.md | 102 +++++++++++++++++- 2 files changed, 103 insertions(+), 2 deletions(-) diff --git a/content/en/cloud/self-hosted/deployment/_index.md b/content/en/cloud/self-hosted/deployment/_index.md index 1d7b7b655..afcd860b9 100644 --- a/content/en/cloud/self-hosted/deployment/_index.md +++ b/content/en/cloud/self-hosted/deployment/_index.md @@ -8,7 +8,7 @@ weight: 2 ## High-level List of Deployment Tasks -## Environment Variables +## High-level List of Deployment Tasks ### INIT_CONFIG @@ -32,6 +32,7 @@ export INIT_CONFIG='{"provider": {"name": "my-provider", "settings": {...}}}' For Docker deployments: ```bash +# example docker run -e INIT_CONFIG='{"provider": {"name": "my-provider"}}' layer5/meshery-cloud ``` diff --git a/content/en/cloud/self-hosted/planning/_index.md b/content/en/cloud/self-hosted/planning/_index.md index 677426317..d89dca210 100644 --- a/content/en/cloud/self-hosted/planning/_index.md +++ b/content/en/cloud/self-hosted/planning/_index.md @@ -17,6 +17,106 @@ Before deploying, plan your configuration approach: 3. **Configuration Management**: Decide how configuration will be managed (environment variables, secrets, config files) 4. **Update Strategy**: Plan for configuration updates and changes over time +### Provider Admin Organization Initialization + +The Provider Admin organization is a special organization identified by the hardcoded UUID `11111111-1111-1111-1111-111111111111`. It represents the root administrative organization for the cloud platform. + +#### Configuration Format + +The `INIT_CONFIG` environment variable accepts a YAML configuration with the following structure: + +```yaml +organization: + name: "Layer5" + description: "The uber organization for all things Layer5." + country: "United States" + region: "North America" + +user: + first_name: "Admin" + last_name: "User" + email: "admin@layer5.io" + username: "admin@layer5.io" # Optional, defaults to email if not provided + password: "change-me-on-first-login" # Required +``` + +#### Setting the Environment Variable + +To enable Provider Admin organization initialization, set the `INIT_CONFIG` environment variable with the entire YAML configuration as its value: + +```bash +INIT_CONFIG='organization: + name: "Layer5" + description: "The uber organization for all things Layer5." + country: "United States" + region: "North America" + +user: + first_name: "Admin" + last_name: "User" + email: "admin@layer5.io" + username: "admin@layer5.io" + password: "change-me-on-first-login"' +``` + +#### Required and Optional Fields + +**Organization:** +- `name`: Name of the provider organization (required) +- `description`: Description of the organization (optional) +- `country`: Country where the organization is located (optional) +- `region`: Region where the organization is located (optional) + +**User:** +- `first_name`: First name of the provider admin user (required) +- `last_name`: Last name of the provider admin user (required) +- `email`: Email address of the provider admin user (required) +- `username`: Username for the provider admin user (optional, defaults to email) +- `password`: Password for the provider admin user (required) + +#### Initialization Process + +When the server starts and `INIT_CONFIG` is set: + +1. The YAML configuration is parsed and validated +2. The system checks if the provider organization already exists (by UUID `11111111-1111-1111-1111-111111111111`) +3. If the organization exists, initialization is skipped +4. If the organization does not exist: + - Kratos identity is created with password credentials for authentication + - Provider admin user is created + - Admin and MeshMap roles are assigned to the user + - Provider organization is created with the hardcoded UUID + - User is added to the provider organization with organization admin role + +#### Idempotency + +The initialization process is idempotent: +- Running the server multiple times with the same configuration will not create duplicate organizations +- If the provider organization already exists, the initialization is skipped +- No errors are thrown if the organization already exists + +#### Error Handling + +If initialization fails: +- Errors are logged using MeshKit logger +- The server continues to start (non-fatal error) +- All database operations are wrapped in a transaction for atomicity +- If any step fails, all changes are rolled back + +### Deployment Options + +You can set the `INIT_CONFIG` environment variable using several methods: + +**Option A (Helm with inline values)**: Include `initConfig` in the Helm `values.yaml` file with the YAML configuration as a multiline string + +**Option B (Helm with --set-file flag)**: Use `--set-file` to load configuration from a separate file: +```bash +helm install meshery-cloud ./install/kubernetes/helm/layer5-cloud \ + --set-file env.initConfig=./config/provider-init.yaml.example +``` + +**Option C (Direct environment variable)**: Set the `INIT_CONFIG` environment variable with the YAML content as a string + ### Using INIT_CONFIG for Automated Setup The `INIT_CONFIG` environment variable allows you to pre-configure your provider during deployment, eliminating manual setup steps. This is particularly valuable for: @@ -25,7 +125,7 @@ The `INIT_CONFIG` environment variable allows you to pre-configure your provider - **CI/CD Integration**: Automate deployments with predefined configurations - **Infrastructure as Code**: Manage provider configuration alongside your infrastructure -For detailed usage and examples, see the [Deployment Guide](/cloud/self-hosted/deployment/#init_config). +For detailed configuration options, see the configuration schema below. {{< alert type="warning" title="Important" >}} Plan your INIT_CONFIG carefully as it is only processed during initial startup. Changes require redeployment or manual configuration updates.