diff --git a/content/en/cloud/self-hosted/deployment/_index.md b/content/en/cloud/self-hosted/deployment/_index.md index edc0858b4..afcd860b9 100644 --- a/content/en/cloud/self-hosted/deployment/_index.md +++ b/content/en/cloud/self-hosted/deployment/_index.md @@ -8,6 +8,54 @@ weight: 2 ## High-level List of Deployment Tasks +## High-level List of Deployment Tasks + +### 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 +# example +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 + +
  1. Review the prequisites for installing Layer5 Cloud on Kubernetes. (docs)
    2. diff --git a/content/en/cloud/self-hosted/planning/_index.md b/content/en/cloud/self-hosted/planning/_index.md index fe8728f57..d89dca210 100644 --- a/content/en/cloud/self-hosted/planning/_index.md +++ b/content/en/cloud/self-hosted/planning/_index.md @@ -1,5 +1,136 @@ --- -title: Planning Layer5 Cloud Deployment +title: Planning +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 + +### 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: + +- **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 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. +{{< /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]