Skip to content

docs(cloud): add comprehensive INIT_CONFIG YAML configuration documentation for self-hosted deployments #879

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
leecalcote merged 7 commits into from
Jan 6, 2026
Merged

docs(cloud): add comprehensive INIT_CONFIG YAML configuration documentation for self-hosted deployments #879

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
c31227c
Initial plan
Copilot Dec 15, 2025
fc66eaf
docs(cloud): add INIT_CONFIG environment variable documentation to de…
Copilot Dec 15, 2025
723d23a
docs(cloud): add provider configuration planning guide for INIT_CONFIG
Copilot Dec 15, 2025
8f443c7
fix(cloud): correct frontmatter structure in planning guide
Copilot Dec 15, 2025
24df97a
Update content/en/cloud/self-hosted/deployment/_index.md
leecalcote Jan 2, 2026
30615c4
Update content/en/cloud/self-hosted/deployment/_index.md
pontusringblom Jan 2, 2026
b76bdfa
docs(cloud): update deployment guide headings and add comprehensive Y…
Copilot Jan 2, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 49 additions & 1 deletion content/en/cloud/self-hosted/deployment/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,55 @@ tags: [helm]
weight: 2
---

## High-level List of Deployment Tasks
## High-level List of Deployment
Copy link
Member

@leecalcote leecalcote Jan 2, 2026

Choose a reason for hiding this comment

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

Suggested change
## High-level List of Deployment
## High-level List of Deployment Tasks

Copy link
Contributor Author

Copilot AI Jan 2, 2026

Choose a reason for hiding this comment

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

Updated in commit b76bdfa. Changed the section heading to "High-level List of Deployment Tasks".


## 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
Copy link
Member

@leecalcote leecalcote Jan 2, 2026

Choose a reason for hiding this comment

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

Suggested change
docker run -e INIT_CONFIG='{"provider": {"name": "my-provider"}}' layer5/meshery-cloud
# example
docker run -e INIT_CONFIG='{"provider": {"name": "my-provider"}}' layer5/meshery-cloud

Copy link
Contributor Author

Copilot AI Jan 2, 2026

Choose a reason for hiding this comment

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

Added in commit b76bdfa. The Docker example now includes the "# example" comment.

```

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

<ol>
<li>Review the prequisites for installing Layer5 Cloud on Kubernetes. (<a href="#prerequisites">docs</a>)</li>
Expand Down
33 changes: 32 additions & 1 deletion content/en/cloud/self-hosted/planning/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,36 @@
---
title: Planning Layer5 Cloud Deployment
title: Planning
Copy link
Contributor

@pontusringblom pontusringblom Dec 15, 2025

Choose a reason for hiding this comment

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

@copilot don't change the title.

Copy link
Contributor Author

Copilot AI Dec 15, 2025

Choose a reason for hiding this comment

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

Fixed in commit 8f443c7. The title is now preserved as "Planning" and the frontmatter structure is correct.

description: Plan your self-hosted Layer5 Cloud deployment
weight: 2
---

## 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).
Copy link
Contributor

@pontusringblom pontusringblom Jan 2, 2026

Choose a reason for hiding this comment

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

@copilot, the other Deployment Guide referenced here is not publicly available for reference. Delete this reference and instead, incorporate the following information into a revision of your proposed "Provider Configuration Planning" page:

# Provider Admin Organization Initialization

This directory contains the configuration for initializing the Provider Admin organization and user during server boot-time.

## Overview

The Provider Admin organization is a special organization identified by the hardcoded UUID `11111111-1111-1111-1111-111111111111`. It represents the uber organization for all things Layer5 and serves as the root administrative organization for the cloud platform.

## Configuration

To enable Provider Admin organization initialization, set the `INIT_CONFIG` environment variable with the entire YAML configuration as its value. An example configuration is provided in `provider-init.yaml.example`.

### Environment Variable

```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"'

Configuration File Format

The configuration file is a YAML file with the following structure:

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

Required 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)

Behavior

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

Testing

To test the initialization:

  1. Create a YAML configuration based on provider-init.yaml.example

  2. Set the INIT_CONFIG environment variable with the entire YAML content:

    • 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: 
      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

  3. Start the server

  4. Check logs for initialization messages:

    INFO Initializing Provider Admin organization from config: organization:...
INFO Provider user created with ID: user ID: <uuid>
INFO Provider organization created with ID: 11111111-1111-1111-1111-111111111111
INFO Provider user added to organization with admin role

  5. Verify in the database:

    SELECT * FROM organizations WHERE id = '11111111-1111-1111-1111-111111111111';
SELECT * FROM users WHERE email = 'admin@layer5.io';

Production Deployment

For production deployments:

  1. Create a secure YAML configuration with production values
  2. Store the configuration in a secure secrets management system (e.g., Kubernetes Secrets, HashiCorp Vault, AWS Secrets Manager)
  3. Set INIT_CONFIG environment variable in your deployment configuration:
    • Helm (inline values): Use initConfig value in values.yaml with the YAML configuration as a multiline string
    • Helm (--set-file): Use --set-file flag to load from a secure file: 
      helm install meshery-cloud ./install/kubernetes/helm/layer5-cloud \
  --set-file env.initConfig=/path/to/secure/provider-init.yaml
    • Kubernetes: Create a Secret containing the YAML configuration and mount as environment variable
    • Docker Compose: Use secrets or environment file with the YAML content
  4. Use strong, unique credentials for the provider admin user
  5. Consider rotating admin credentials regularly after initial setup

Skipping Initialization

To skip provider organization initialization:

  • Do not set the INIT_CONFIG environment variable, or
  • Set INIT_CONFIG to an empty string

The server will log: INIT_CONFIG not set, skipping provider organization initialization

Troubleshooting

Invalid YAML Configuration

ERROR Failed to initialize Provider Admin organization: Failed to load provider initialization configuration

Solution: Verify that the INIT_CONFIG environment variable contains valid YAML syntax. Check for proper indentation and quotes.

Invalid Configuration

ERROR Failed to initialize Provider Admin organization: Provider initialization configuration is invalid

Solution: Check that all required fields are present in the YAML configuration:

  • organization.name (required)
  • user.email (required)
  • user.first_name (required)
  • user.last_name (required)
  • user.password (required)

Database Errors

ERROR Failed to create Provider Admin organization
ERROR Failed to create Provider Admin user

Solution: Check database connectivity and logs for detailed error messages. Ensure migrations have run successfully.

Security Considerations

  • Store the INIT_CONFIG value securely using secrets management systems
  • Never commit the INIT_CONFIG value with real credentials to version control
  • Use strong, unique credentials for the provider admin user
  • Rotate admin credentials regularly after initial setup
  • Audit provider admin user activity
  • Consider using environment-specific configurations for different deployment stages

Copy link
Contributor Author

Copilot AI Jan 2, 2026

Choose a reason for hiding this comment

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

Updated in commit b76bdfa. I've removed the reference to the non-public Deployment Guide and incorporated the comprehensive YAML configuration documentation into the Provider Configuration Planning section, including:

  • Provider Admin Organization Initialization details
  • Complete YAML configuration format with organization and user fields
  • Required and optional fields documentation
  • Initialization process, idempotency, and error handling
  • Deployment options (Helm inline, --set-file, direct env variable)


{{< 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]
Expand Down