diff --git a/configsrc/vcluster/main/vcluster.schema.json b/configsrc/vcluster/main/vcluster.schema.json index 0e32b8024..68f690aab 100755 --- a/configsrc/vcluster/main/vcluster.schema.json +++ b/configsrc/vcluster/main/vcluster.schema.json @@ -209,7 +209,7 @@ }, "coredns": { "$ref": "#/$defs/CoreDNS", - "description": "CoreDNS defines everything related to the coredns that is deployed and used within the vCluster." + "description": "CoreDNS defines everything related to the coreDNS that is deployed and used within the vCluster." }, "proxy": { "$ref": "#/$defs/ControlPlaneProxy", @@ -703,7 +703,7 @@ }, "embedded": { "type": "boolean", - "description": "Embedded defines if vCluster will start the embedded coredns service within the control-plane and not as a separate deployment. This is a PRO feature." + "description": "Embedded defines if vCluster will start the embedded coredns service within the control-plane and not as a separate deployment. This is an Enterprise feature." }, "service": { "$ref": "#/$defs/CoreDNSService", @@ -2595,7 +2595,7 @@ "secret": { "type": "boolean" }, - "configmap": { + "configMap": { "type": "boolean" } }, diff --git a/platform/_partials/install/upgrade.mdx b/platform/_partials/install/upgrade.mdx index 552c35f76..0809f8b2d 100644 --- a/platform/_partials/install/upgrade.mdx +++ b/platform/_partials/install/upgrade.mdx @@ -14,7 +14,7 @@ Upgrade the platform via: defaultValue="cli" values={[ { label: 'CLI', value: 'cli', }, - { label: 'helm', value: 'helm', }, + { label: 'Helm', value: 'helm', }, ] }> diff --git a/platform/administer/projects/quotas.mdx b/platform/administer/projects/quotas.mdx index 3a8275410..e3343e02b 100644 --- a/platform/administer/projects/quotas.mdx +++ b/platform/administer/projects/quotas.mdx @@ -10,7 +10,7 @@ import Button from "@site/src/components/Button"; import Label from "@site/src/components/Label"; import Link from "@docusaurus/Link"; -Quotas allow you to set resource usage and count limits for the project. This works similiarly to Kubernetes `ResourcesQuotas`, but applies across multiple clusters. Quotas can be +Quotas allow you to set resource usage and count limits for the project. This works similarly to Kubernetes `ResourcesQuotas`, but applies across multiple clusters. Quotas can be defined across the whole project or on a per-user/per-team basis. :::info Project quotas with multiple virtual clusters diff --git a/platform/administer/upgrade-migrate/upgrade.mdx b/platform/administer/upgrade-migrate/upgrade.mdx deleted file mode 100644 index 20fa0c150..000000000 --- a/platform/administer/upgrade-migrate/upgrade.mdx +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: Upgrade vCluster Platform -sidebar_label: Upgrade -sidebar_position: 2 ---- - -import PartialAdminUpgrade from "../../_partials/install/upgrade.mdx"; - -Upgrading vCluster Platform is easy. vCluster Platform can be upgraded either via the vCluster CLI, or with Helm. - - - -:::info Versions and Values -The `$PLATFORM_VERSION` variable above is an environment variable set to your desired vCluster Platform version to -deploy. The `vcluster-platform.yaml` file is an optional YAML file that contains Helm values you would like -to use when upgrading your vCluster Platform deployment. -::: - diff --git a/platform/administer/upgrade-migrate/_category_.json b/platform/install/upgrade-migrate/_category_.json similarity index 61% rename from platform/administer/upgrade-migrate/_category_.json rename to platform/install/upgrade-migrate/_category_.json index c6bf617c5..36cf53422 100644 --- a/platform/administer/upgrade-migrate/_category_.json +++ b/platform/install/upgrade-migrate/_category_.json @@ -1,6 +1,6 @@ { "label": "Upgrade and Migrate", - "position": 10, + "position": 5, "collapsible": true, - "collapsed": true + "collapsed": false } diff --git a/platform/install/supported_versions.mdx b/platform/install/upgrade-migrate/lifecycle-policy.mdx similarity index 87% rename from platform/install/supported_versions.mdx rename to platform/install/upgrade-migrate/lifecycle-policy.mdx index aa38a4f77..bb3b5f683 100644 --- a/platform/install/supported_versions.mdx +++ b/platform/install/upgrade-migrate/lifecycle-policy.mdx @@ -1,9 +1,10 @@ --- -title: Lifecycle Policy -sidebar_label: Releases and Maintenance -sidebar_position: 5 +title: Lifecycle policy +sidebar_label: Lifecycle Policy +sidebar_position: 1 keywords: [support matrix, supported versions, lifecycle] --- + import SupportTerminology from '@site/docs/_partials/support_terminology.mdx'; @@ -26,6 +27,6 @@ Any previous versions which are not on this list are no longer in any support wi | v4.0 | October 15, 2024 | January 15, 2025 | April 15, 2025 | | v3.4| February 29, 2024 | April 1, 2025* | July 1, 2025 | -\* Due to the number of breaking changes from vCluster v0.19 to v0.20 and Platform v3.4 to v4.0, v3.4 has an extended active support end date. Review the [migration guide](../reference/migrations/4-0-migration.mdx) to upgrade your v3.4 to v4.0 Platform. +\* Due to the number of breaking changes from vCluster v0.19 to v0.20 and Platform v3.4 to v4.0, v3.4 has an extended active support end date. Review the [migration guide](../../reference/migrations/4-0-migration.mdx) to upgrade your v3.4 to v4.0 Platform. diff --git a/platform/administer/upgrade-migrate/migrate-to-hostcluster.mdx b/platform/install/upgrade-migrate/migrate-to-hostcluster.mdx similarity index 97% rename from platform/administer/upgrade-migrate/migrate-to-hostcluster.mdx rename to platform/install/upgrade-migrate/migrate-to-hostcluster.mdx index fd89c4844..48aafb835 100644 --- a/platform/administer/upgrade-migrate/migrate-to-hostcluster.mdx +++ b/platform/install/upgrade-migrate/migrate-to-hostcluster.mdx @@ -1,12 +1,12 @@ --- title: Migrate the platform to a different cluster -sidebar_label: Migrate Clusters -sidebar_position: 1 +sidebar_label: Migrate vCluster Platform +sidebar_position: 3 description: Learn how to migrate vCluster platform from one Kubernetes cluster to another. --- import Flow, { Step } from '@site/src/components/Flow' -import BasePrerequisites from '../../_partials/install/base-prerequisites.mdx'; +import BasePrerequisites from '@site/platform/_partials/install/base-prerequisites.mdx'; This guide explains how to migrate the platform to a different Kubernetes cluster, which might be necessary during cluster decommissioning or cloud platform migration. diff --git a/platform/install/upgrade-migrate/upgrade.mdx b/platform/install/upgrade-migrate/upgrade.mdx new file mode 100644 index 000000000..6199d00e4 --- /dev/null +++ b/platform/install/upgrade-migrate/upgrade.mdx @@ -0,0 +1,17 @@ +--- +title: Upgrade vCluster Platform +sidebar_label: Upgrade vCluster Platform +sidebar_position: 2 +--- + +import PartialAdminUpgrade from "@site/platform/_partials/install/upgrade.mdx"; + +You can upgrade vCluster Platform using either the vCluster CLI or Helm. + + + +:::info Versions and Values +The `$PLATFORM_VERSION` environment variable specifies the vCluster Platform version to deploy. +The `vcluster-platform.yaml` file is optional and defines Helm values to use when upgrading the vCluster Platform deployment. +::: + diff --git a/platform/reference/migrations/4-0-migration.mdx b/platform/reference/migrations/4-0-migration.mdx index a75a9e13f..9d8cb488a 100644 --- a/platform/reference/migrations/4-0-migration.mdx +++ b/platform/reference/migrations/4-0-migration.mdx @@ -1,5 +1,6 @@ --- -title: Upgrade Guide from pre-v4.0 to v4.0+ +title: Upgrade guide for pre-v4.0 to v4.0+ +sidebar_label: Upgrade Guide for pre-v4.0 to v4.0+ description: How to upgrade from pre-v4.0 to v4.0 release sidebar_position: 1 --- @@ -7,14 +8,14 @@ sidebar_position: 1 import Tabs from "@theme/Tabs"; import TabItem from "@theme/TabItem"; -These docs cover upgrading from pre v4.0 to v4.0. Once you upgrade to v4.0+, you need to follow the regular [upgrade docs](../../administer/upgrade-migrate/upgrade). +These docs cover upgrading from pre v4.0 to v4.0. After you upgrade to v4.0+, you must follow the upgrade docs. -## Upgrade to the latest Loft v3.x version +## Upgrade to the latest Loft version Before attempting to perform this major upgrade, upgrade to the latest v3.x version. Review the [older upgrade docs](https://loft.sh/docs/admin/upgrade-loft) on how to upgrade. It is recommended to upgrade using the CLI and not the UI as there are known issues to upgrade versions through the UI. -## Pre-Upgrade Recommendations +## Pre-upgrade recommendations ### Read through the v4.0 Release Notes @@ -26,15 +27,15 @@ One of the breaking changes in v4.0 is the requirement of a vCluster version def the vCluster would automatically upgrade these virtual clusters to the latest default vCluster version. Due to the [breaking changes introduced in v0.20](https://roadmap.vcluster.com/changelog/vcluster-v020-ga), automatic upgrades of vCluster version are no longer supported and a vCluster version must be set in the spec of a virtual cluster or virtual cluster template. -We recommend confirming that the versions of your virtual clusters and virtual cluster templates are in the resource yaml before upgrading. Otherwise, -your virtual clusters will have errors requiring you to define these versions post upgrade and since it will not know what version you upgraded from, it will not know what -version to set and manual steps will need to happen to determine the correct version and set it. +Confirm that the resource YAML includes the versions of your virtual clusters and virtual cluster templates before upgrading. +Otherwise, your virtual clusters might encounter errors that require you to define these versions after the upgrade. +Because it is not known which version you upgraded from, it cannot set the correct version automatically, and you must manually determine and set it. -#### How to define the vCluster version on Existing Virtual Clusters +#### Define the vCluster version on Existing Virtual Clusters -In the UI, for each virtual cluster, edit the configuration and type the version of the virtual cluster or virtual cluster template in the textbox and the resource yaml will automatically update the spec to include the version. +In the UI, for each virtual cluster, edit the configuration and type the version of the virtual cluster or virtual cluster template in the textbox and the resource YAML automatically updates the spec to include the version. -If the resource yaml of your virtual cluster or virtual cluster template has `spec.template.helmRelease.chart.version` set, then the virtual cluster version is defined. +If the resource YAML of your virtual cluster or virtual cluster template has `spec.template.helmRelease.chart.version` set, then the virtual cluster version is defined. `spec` Example: @@ -46,23 +47,23 @@ spec: version: 0.19.7 ``` -## Download the latest vCluster CLI (v0.20.0+) +## Download the latest vCluster CLI With the deprecation of the Loft CLI, review the [Loft CLI to vCluster CLI Migration docs](https://vcluster.com/docs/vcluster/reference/migrations/loft-cli-vcluster-cli-migration). -## Required Changes in your Platform Configuration before Upgrading +## Required changes in your platform configuration before upgrading A new feature has been added to support the ability to change the prefix of the namespace created for projects. In previous versions, the prefix was `loft-p`, but in v4.0.0, the new default is `p-`. Due to the change in defaults, the previous prefix needs to be set in the Platform configuration as part of the upgrade command. Since future upgrades reuse the values of the configuration, you only need to apply it once. -### Appending the project prefix to upgrade commands +### Append the project prefix to upgrade commands @@ -74,8 +75,8 @@ The following steps assume the existing installation is in the default namespace ::: ```bash -PLATFORM_NAMESPACE="loft" # update if the platform is installed to a different namespace -PLATFORM_VERSION="" # specify a version or it will upgrade to latest stable +PLATFORM_NAMESPACE="loft" # Update if the platform is installed to a different namespace +PLATFORM_VERSION="" # Specify a version or it upgrades to latest stable version vcluster platform start --upgrade --namespace $PLATFORM_NAMESPACE --version=$PLATFORM_VERSION --values=<(cat < Config` UI or through editing the `loft-manager-config` secret found in the namespace vCluster Platform is installed in. Editing this config causes loft to restart which should be unnecessary for adding OIDC platform clients. Therefore, managing vCluster Platform OIDC clients has been moved to its own UI and the clients their own objects. These new OIDC clients can be managed either through the OIDC Provider tab of the admin page or through Kubernetes Secrets, see [Adding OIDC Clients to vCluster Platform OIDC Using Secrets](/platform/how-to/oidc-provider#adding-oidc-clients-to-vcluster-platform-oidc-using-secrets). The `oidc.clients` field -is deprecated in vCluster Platform version 4.0 and will be removed in version 5.0. +is deprecated in vCluster Platform version 4.0 and is removed in version 5.0. -#### Migrating OIDC Clients from Admin Config to New OIDC Clients +#### Migrate OIDC clients from admin config to new OIDC clients 1. Navigate to `Admin > OIDC Provider`. 2. Select `Add Client`. @@ -137,14 +138,14 @@ is deprecated in vCluster Platform version 4.0 and will be removed in version 5. 6. Select "Save". 7. Repeat steps 1-6 for all clients. 8. Copy the `oidc.clients` to a safe location. These can be discard once all steps have been succesful. -9. Delete the `oidc.clients` field. This will cause vCluster Platform to restart. +9. Delete the `oidc.clients` field. This causes vCluster Platform to restart. 10. Validate OIDC clients function normally. -## Troubleshooting Tips +## Troubleshooting tips -### Forgot the Project Prefix +### Forgot the project prefix -If you accidentially performed the upgrade without setting the `projectNamespacePrefix`, then the pod of the platform will be in a `CrashLoopBackoff` with a log similiar to: +If you accidentially performed the upgrade without setting the `projectNamespacePrefix`, then the pod of the platform is in a `CrashLoopBackoff` with a log similar to: ```bash cmd/main.go:107 error executing root command {"component": "loft", "error": "init (4): set default project namespace prefix: seems like you have upgraded the platform from an earlier version that uses 'loft-p-' as a project namespace prefix. This has been changed to be 'p-' in the current version. Please set 'projectNamespacePrefix: loft-p-' in the platform config to get rid of this error"} diff --git a/platform_versioned_docs/version-4.2.0/administer/projects/quotas.mdx b/platform_versioned_docs/version-4.2.0/administer/projects/quotas.mdx index 3a8275410..e3343e02b 100644 --- a/platform_versioned_docs/version-4.2.0/administer/projects/quotas.mdx +++ b/platform_versioned_docs/version-4.2.0/administer/projects/quotas.mdx @@ -10,7 +10,7 @@ import Button from "@site/src/components/Button"; import Label from "@site/src/components/Label"; import Link from "@docusaurus/Link"; -Quotas allow you to set resource usage and count limits for the project. This works similiarly to Kubernetes `ResourcesQuotas`, but applies across multiple clusters. Quotas can be +Quotas allow you to set resource usage and count limits for the project. This works similarly to Kubernetes `ResourcesQuotas`, but applies across multiple clusters. Quotas can be defined across the whole project or on a per-user/per-team basis. :::info Project quotas with multiple virtual clusters diff --git a/platform_versioned_docs/version-4.2.0/administer/upgrade-migrate/migrate-to-hostcluster.mdx b/platform_versioned_docs/version-4.2.0/administer/upgrade-migrate/migrate-to-hostcluster.mdx deleted file mode 100644 index 7caf25ca5..000000000 --- a/platform_versioned_docs/version-4.2.0/administer/upgrade-migrate/migrate-to-hostcluster.mdx +++ /dev/null @@ -1,185 +0,0 @@ ---- -title: Migrate the platform to a different cluster -sidebar_label: Migrate Clusters -sidebar_position: 1 -description: Learn how to migrate vCluster platform from one Kubernetes cluster to another. ---- - -import Flow, { Step } from '@site/src/components/Flow' -import BasePrerequisites from '../../_partials/install/base-prerequisites.mdx'; - -This guide explains how to migrate the platform to a different Kubernetes cluster, which may be necessary during cluster decommissioning or cloud platform migration. - -## When to migrate - -Migrating a platform to a new Kubernetes cluster is necessary in certain cases, such as infrastructure upgrades, cluster decommissioning, or scaling needs. Migrate the platform in the following situations : - -- The existing cluster is being decommissioned. The platform must move to a new cluster. - -- The platform is migrating to a new cluster. The original cluster is going to be cleaned up. - -- The platform is migrating to a new cluster. The original cluster is going to be remain connected. - - -### Migration considerations - -:::warning -IMPORTANT: the platform must run on a dedicated Kubernetes cluster. It must have its own ingress and DNS record before migration. Ensure these conditions are met before proceeding. -::: - -Review the following factors before migrating. These scenarios require a different migration approach. - -- **Loft router configurations** - If the platform uses the Loft router (``), special DNS handling is required. The DNS records must be updated to reflect the new cluster. Failure to update DNS settings can cause routing issues and service downtime. - -- **Automated deployment tools** - If the platform is managed by an automated deployment tool such as `ArgoCD`, migration must be coordinated with GitOps workflows. Changes to cluster configuration must be reflected in the repository before deployment. Skipping this step can lead to drift between the declared and actual state of the platform. - -- **Virtual cluster dependencies** - If the platform has virtual cluster instances running on the same Kubernetes host cluster, these instances do not migrate automatically. They require a separate migration process after the platform has been moved. Migrating only the platform without considering virtual clusters can cause service disruptions and dependency issues. - -- **Virtual cluster agent on the destination cluster** - If the destination Kubernetes cluster has a virtual cluster agent, it must be decommissioned before migration. The agent can interfere with the new platform installation, potentially leading to scheduling conflicts and unexpected behavior. - -Not addressing these considerations before migration can lead to DNS misconfigurations, deployment failures, and conflicts with existing workloads. - -## Prerequisites - -### Base prerequisites - - - -### Platform specific prerequisites - -- Storage space for backup (approximately 1GB). -- Access to DNS management for the platform's domain -- Only one platform instance can exist per Kubernetes cluster. Do not install the platform twice in the same Kubernetes host cluster. -- The migration process requires 15-30 minutes of downtime. Communicate this downtime to end users. -- The source and destination installations must use the same platform version. Version changes during migration are not supported. - -## Migration steps - - - -### Install the platform in the new cluster - -Configuration - -- Use the Helm values from the original installation, making adjustments to values like `ingressClass` or `storageClass` as necessary -- If your project namespaces have the "loft-p-" prefix, set `projectNamespacePrefix: loft-p-` in your configuration - - - -Installation - -Install the platform in the new cluster following the [quick start guide](/platform/install/quick-start-guide). - -:::info Avoid DNS conflicts -When using cloud-managed ingress, use a temporary hostname to prevent conflicts with the running platform instance. -::: - - -### Prepare for migration - - -Send downtime communication to end users - - - -Optional: stop `ArgoCD` sync of any virtual clusters - - - -[Perform a backup of the source platform](/platform/administer/backup-restore/backup-restore-platform) - - -### Execute migration - - -Scale down the source platform: - -```bash title="Scale down the platform deployment" -kubectl scale deployment loft --replicas=0 -n vcluster-platform -``` - - - -[Restore the backup to the new installation](https://www.vcluster.com/docs/platform/administer/backup-restore/backup-restore-platform#restoring-vcluster-platform-from-backup) - - - -Apply the license certificate to the new cluster: - - ```bash title="Apply license certificate" - TARGET_NAMESPACE='vcluster-platform' - CA_CERT=$(kubectl get secret loft-cert -n vcluster-platform -o jsonpath="{.data.ca\.crt}") - TLS_CERT=$(kubectl get secret loft-cert -n vcluster-platform -o jsonpath="{.data.tls\.crt}") - PRIVATE_KEY=$(kubectl get secret loft-cert -n vcluster-platform -o jsonpath="{.data.tls\.key}") - - cat < loft-cert-clean.yaml - apiVersion: v1 - kind: Secret - metadata: - name: loft-cert - namespace: ${TARGET_NAMESPACE} - type: kubernetes.io/tls - data: - ca.crt: ${CA_CERT} - tls.crt: ${TLS_CERT} - tls.key: ${PRIVATE_KEY} - EOF - ``` - - ```bash title="Apply license certificate" - kubectl scale deployment loft --replicas=0 -n vcluster-platform - kubectl delete secret loft-cert -n ${TARGET_NAMESPACE} --ignore-not-found - kubectl create -f loft-cert-clean.yaml - ``` - - - -Update the hostname in the platform configuration as described in the [configuration guide](https://www.vcluster.com/docs/platform/configure/config#changing-the-lofthost-variable) - - -Update the DNS record to point to the new cluster if needed - - -If the original cluster is going to be used as a connected cluster: connect it to the new platform installation - - - - -## Post-migration validation - - -Log in to the platform UI and verify object presence: - - Check for all expected projects - - Verify user access and permissions - - Confirm virtual cluster listings - - -Verify license status in the platform UI: - - Navigate to Settings → License - - Confirm license is active and correct - - -Restart platform agents on connected clusters: - - ```bash title="Restart platform agents" - kubectl rollout restart deployment loft -n vcluster-platform - ``` - - -Validate the core capabilities of the platform: - - Single Sign-on: test login with all configured providers - - Log access: verify log retrieval from multiple virtual clusters - - Virtual cluster creation: create a test cluster - - Sleep mode: test sleep/wake feature - - -Optional: restart `ArgoCD` sync if previously stopped - - -Send end-of-downtime communication to end users - - diff --git a/platform_versioned_docs/version-4.2.0/administer/upgrade-migrate/upgrade.mdx b/platform_versioned_docs/version-4.2.0/administer/upgrade-migrate/upgrade.mdx deleted file mode 100644 index 20fa0c150..000000000 --- a/platform_versioned_docs/version-4.2.0/administer/upgrade-migrate/upgrade.mdx +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: Upgrade vCluster Platform -sidebar_label: Upgrade -sidebar_position: 2 ---- - -import PartialAdminUpgrade from "../../_partials/install/upgrade.mdx"; - -Upgrading vCluster Platform is easy. vCluster Platform can be upgraded either via the vCluster CLI, or with Helm. - - - -:::info Versions and Values -The `$PLATFORM_VERSION` variable above is an environment variable set to your desired vCluster Platform version to -deploy. The `vcluster-platform.yaml` file is an optional YAML file that contains Helm values you would like -to use when upgrading your vCluster Platform deployment. -::: - diff --git a/platform_versioned_docs/version-4.2.0/administer/upgrade-migrate/_category_.json b/platform_versioned_docs/version-4.2.0/install/upgrade-migrate/_category_.json similarity index 61% rename from platform_versioned_docs/version-4.2.0/administer/upgrade-migrate/_category_.json rename to platform_versioned_docs/version-4.2.0/install/upgrade-migrate/_category_.json index c6bf617c5..36cf53422 100644 --- a/platform_versioned_docs/version-4.2.0/administer/upgrade-migrate/_category_.json +++ b/platform_versioned_docs/version-4.2.0/install/upgrade-migrate/_category_.json @@ -1,6 +1,6 @@ { "label": "Upgrade and Migrate", - "position": 10, + "position": 5, "collapsible": true, - "collapsed": true + "collapsed": false } diff --git a/platform_versioned_docs/version-4.2.0/install/supported_versions.mdx b/platform_versioned_docs/version-4.2.0/install/upgrade-migrate/lifecycle-policy.mdx similarity index 88% rename from platform_versioned_docs/version-4.2.0/install/supported_versions.mdx rename to platform_versioned_docs/version-4.2.0/install/upgrade-migrate/lifecycle-policy.mdx index aa38a4f77..c38b21c01 100644 --- a/platform_versioned_docs/version-4.2.0/install/supported_versions.mdx +++ b/platform_versioned_docs/version-4.2.0/install/upgrade-migrate/lifecycle-policy.mdx @@ -1,7 +1,7 @@ --- title: Lifecycle Policy -sidebar_label: Releases and Maintenance -sidebar_position: 5 +sidebar_label: Lifecycle policy +sidebar_position: 1 keywords: [support matrix, supported versions, lifecycle] --- import SupportTerminology from '@site/docs/_partials/support_terminology.mdx'; @@ -26,6 +26,6 @@ Any previous versions which are not on this list are no longer in any support wi | v4.0 | October 15, 2024 | January 15, 2025 | April 15, 2025 | | v3.4| February 29, 2024 | April 1, 2025* | July 1, 2025 | -\* Due to the number of breaking changes from vCluster v0.19 to v0.20 and Platform v3.4 to v4.0, v3.4 has an extended active support end date. Review the [migration guide](../reference/migrations/4-0-migration.mdx) to upgrade your v3.4 to v4.0 Platform. +\* Due to the number of breaking changes from vCluster v0.19 to v0.20 and Platform v3.4 to v4.0, v3.4 has an extended active support end date. Review the [migration guide](../../reference/migrations/4-0-migration.mdx) to upgrade your v3.4 to v4.0 Platform. diff --git a/platform_versioned_docs/version-4.2.0/install/upgrade-migrate/migrate-to-hostcluster.mdx b/platform_versioned_docs/version-4.2.0/install/upgrade-migrate/migrate-to-hostcluster.mdx new file mode 100644 index 000000000..48aafb835 --- /dev/null +++ b/platform_versioned_docs/version-4.2.0/install/upgrade-migrate/migrate-to-hostcluster.mdx @@ -0,0 +1,187 @@ +--- +title: Migrate the platform to a different cluster +sidebar_label: Migrate vCluster Platform +sidebar_position: 3 +description: Learn how to migrate vCluster platform from one Kubernetes cluster to another. +--- + +import Flow, { Step } from '@site/src/components/Flow' +import BasePrerequisites from '@site/platform/_partials/install/base-prerequisites.mdx'; + +This guide explains how to migrate the platform to a different Kubernetes cluster, which might be necessary during cluster decommissioning or cloud platform migration. + +## When to migrate {#when-to-migrate} + +Migrating the platform to a new Kubernetes cluster is necessary in certain cases, such as infrastructure upgrades, cluster decommissioning, or scaling needs. Migrate the platform in the following situations: + +- The existing cluster is being decommissioned. The platform must move to a new cluster. + +- The platform is migrating to a new cluster. The original cluster is going to be cleaned up. + +- The platform is migrating to a new cluster. The original cluster is going to remain connected. + + +### Migration considerations {#migration-considerations} + +:::warning +The platform must run on a dedicated Kubernetes cluster. It must have its own external access (using ingress or LoadBalancer) and DNS record before migration. Ensure these conditions are met before proceeding. +::: + +Review the following factors before migrating. These scenarios require a different migration approach. + +- **Loft router configurations** + If the platform uses the Loft router (``), special DNS handling is required. The DNS records must be updated to reflect the new cluster. Failure to update DNS settings can cause routing issues and service downtime. + +- **Automated deployment tools** + If the platform is managed by an automated deployment tool such as `ArgoCD`, migration must be coordinated with GitOps workflows. Changes to cluster configuration must be reflected in the repository before deployment. Skipping this step can lead to drift between the declared and actual state of the platform. + +- **Virtual cluster dependencies** + If the platform has virtual cluster instances running on the same Kubernetes host cluster, these instances do not migrate automatically. They require a separate migration process after the platform has been moved. Migrating only the platform without considering virtual clusters can cause service disruptions and dependency issues. + +- **Virtual cluster agent on the destination cluster** + If the destination Kubernetes cluster has a virtual cluster agent, it must be decommissioned before migration. The agent can interfere with the new platform installation, potentially leading to scheduling conflicts and unexpected behavior. + +Not addressing these considerations before migration can lead to DNS misconfigurations, deployment failures, and conflicts with existing workloads. + +## Prerequisites {#prerequisites} + +### Base prerequisites {#base-prerequisites} + + + +### Platform specific prerequisites {#platform-specific-prerequisites} + +- Ensure at least 1 GB of available storage space for the backup. +- Confirm that you have access to DNS management for the platform's domain. +- Only one platform instance can run in a single Kubernetes cluster. Do not install the platform more than once in the same host cluster. +- Plan for 15–30 minutes of downtime during the migration process. Communicate this downtime to end users in advance. +- Use the same platform version for both the source and destination installations. Migration does not support version changes. + + +## Migration steps {#migration-steps} + + + +### Install the platform in the new cluster {#install-platform-new-cluster} + +Use the following configuration settings to complete the installation in the new cluster: + +- Use the Helm values from the original installation, making adjustments to values like `ingressClass` or `storageClass` as necessary. +- If your project namespaces use the `loft-p-` prefix, set `projectNamespacePrefix: loft-p-` in your configuration. + + + + +Install the platform in the new cluster by following the [quick start guide](/platform/install/quick-start-guide). + +:::info Using a temporary hostname during installation +When using cloud-managed ingress, use a temporary hostname to prevent conflicts with the running platform instance. +::: + + +### Prepare for migration {#prepare-for-migration} + + +Send downtime communication to end users. + + + +Optional: Stop `ArgoCD` sync of any virtual clusters. + + + +[Perform a backup of the source platform](/platform/administer/backup-restore/backup-restore-platform). + + +### Execute migration {#execute-migration} + + +Scale down the source platform: + +```bash title="Scale down the platform deployment" +kubectl scale deployment loft --replicas=0 -n vcluster-platform +``` + + + +[Restore the backup to the new installation](/platform/administer/backup-restore/backup-restore-platform#restoring-vcluster-platform-from-backup). + + + +Apply the license certificate to the new cluster: + +```bash title="Capture certificate data from the source cluster" +TARGET_NAMESPACE='vcluster-platform' +CA_CERT=$(kubectl get secret loft-cert -n vcluster-platform -o jsonpath="{.data.ca\.crt}") +TLS_CERT=$(kubectl get secret loft-cert -n vcluster-platform -o jsonpath="{.data.tls\.crt}") +PRIVATE_KEY=$(kubectl get secret loft-cert -n vcluster-platform -o jsonpath="{.data.tls\.key}") + +cat < loft-cert-clean.yaml +apiVersion: v1 +kind: Secret +metadata: + name: loft-cert + namespace: ${TARGET_NAMESPACE} +type: kubernetes.io/tls +data: + ca.crt: ${CA_CERT} + tls.crt: ${TLS_CERT} + tls.key: ${PRIVATE_KEY} +EOF +``` + +```bash title="Apply certificate to the target cluster" +kubectl scale deployment loft --replicas=0 -n vcluster-platform +kubectl delete secret loft-cert -n ${TARGET_NAMESPACE} --ignore-not-found +kubectl create -f loft-cert-clean.yaml +kubectl scale deployment loft --replicas=1 -n vcluster-platform +``` + + + +Update the hostname in the platform configuration as described in the [configuration guide](/platform/configure/config#setting-a-custom-domain). + + +Update the DNS record to point to the new cluster, if needed. + + +When using the original cluster as a connected cluster, connect it to the new platform installation. + + + + +## Post-migration validation {#post-migration-validation} + + +Log in to the platform UI and verify object presence: + - Check for all expected projects. + - Verify user access and permissions. + - Confirm virtual cluster listings. + + +Verify license status in the platform UI: + - Navigate to **Settings** → **License**. + - Confirm license is active and correct. + + +Restart platform agents on connected clusters: + +```bash title="Restart platform agent" +kubectl rollout restart deployment loft -n vcluster-platform +``` + + +Validate the core capabilities of the platform: + - Single sign-on: Test logging in with all configured providers. + - Log access: Verify log retrieval from multiple virtual clusters. + - Virtual cluster creation: Create a test cluster. + - Sleep mode: Test the sleep/wake feature. + + +Optional: Restart `ArgoCD` sync if previously stopped. + + +Send end-of-downtime communication to end users. + + + diff --git a/platform_versioned_docs/version-4.2.0/install/upgrade-migrate/upgrade.mdx b/platform_versioned_docs/version-4.2.0/install/upgrade-migrate/upgrade.mdx new file mode 100644 index 000000000..6199d00e4 --- /dev/null +++ b/platform_versioned_docs/version-4.2.0/install/upgrade-migrate/upgrade.mdx @@ -0,0 +1,17 @@ +--- +title: Upgrade vCluster Platform +sidebar_label: Upgrade vCluster Platform +sidebar_position: 2 +--- + +import PartialAdminUpgrade from "@site/platform/_partials/install/upgrade.mdx"; + +You can upgrade vCluster Platform using either the vCluster CLI or Helm. + + + +:::info Versions and Values +The `$PLATFORM_VERSION` environment variable specifies the vCluster Platform version to deploy. +The `vcluster-platform.yaml` file is optional and defines Helm values to use when upgrading the vCluster Platform deployment. +::: + diff --git a/platform_versioned_docs/version-4.2.0/reference/migrations/4-0-migration.mdx b/platform_versioned_docs/version-4.2.0/reference/migrations/4-0-migration.mdx index a75a9e13f..2317a1f16 100644 --- a/platform_versioned_docs/version-4.2.0/reference/migrations/4-0-migration.mdx +++ b/platform_versioned_docs/version-4.2.0/reference/migrations/4-0-migration.mdx @@ -7,7 +7,7 @@ sidebar_position: 1 import Tabs from "@theme/Tabs"; import TabItem from "@theme/TabItem"; -These docs cover upgrading from pre v4.0 to v4.0. Once you upgrade to v4.0+, you need to follow the regular [upgrade docs](../../administer/upgrade-migrate/upgrade). +These docs cover upgrading from pre v4.0 to v4.0. Once you upgrade to v4.0+, you need to follow the upgrade docs. ## Upgrade to the latest Loft v3.x version @@ -144,7 +144,7 @@ is deprecated in vCluster Platform version 4.0 and will be removed in version 5. ### Forgot the Project Prefix -If you accidentially performed the upgrade without setting the `projectNamespacePrefix`, then the pod of the platform will be in a `CrashLoopBackoff` with a log similiar to: +If you accidentially performed the upgrade without setting the `projectNamespacePrefix`, then the pod of the platform will be in a `CrashLoopBackoff` with a log similar to: ```bash cmd/main.go:107 error executing root command {"component": "loft", "error": "init (4): set default project namespace prefix: seems like you have upgraded the platform from an earlier version that uses 'loft-p-' as a project namespace prefix. This has been changed to be 'p-' in the current version. Please set 'projectNamespacePrefix: loft-p-' in the platform config to get rid of this error"} diff --git a/vcluster/_partials/config/controlPlane.mdx b/vcluster/_partials/config/controlPlane.mdx index 6dff330d3..02cea938d 100755 --- a/vcluster/_partials/config/controlPlane.mdx +++ b/vcluster/_partials/config/controlPlane.mdx @@ -2001,7 +2001,7 @@ Enabled defines if coredns is enabled #### `embedded` required boolean false pro {#controlPlane-coredns-embedded} -Embedded defines if vCluster will start the embedded coredns service within the control-plane and not as a separate deployment. This is a PRO feature. +Embedded defines if vCluster will start the embedded coredns service within the control-plane and not as a separate deployment. This is an Enterprise feature. diff --git a/vcluster/_partials/config/controlPlane/coredns.mdx b/vcluster/_partials/config/controlPlane/coredns.mdx index ef27737c0..0e8aecb88 100755 --- a/vcluster/_partials/config/controlPlane/coredns.mdx +++ b/vcluster/_partials/config/controlPlane/coredns.mdx @@ -31,7 +31,7 @@ Enabled defines if coredns is enabled ### `embedded` required boolean false pro {#coredns-embedded} -Embedded defines if vCluster will start the embedded coredns service within the control-plane and not as a separate deployment. This is a PRO feature. +Embedded defines if vCluster will start the embedded coredns service within the control-plane and not as a separate deployment. This is an Enterprise feature. diff --git a/vcluster/cli/_category_.json b/vcluster/cli/_category_.json index 25b6e2299..3f32dfb6e 100644 --- a/vcluster/cli/_category_.json +++ b/vcluster/cli/_category_.json @@ -1,5 +1,5 @@ { "label": "CLI", - "position": "7.5" + "position": "11" } diff --git a/vcluster/configure/vcluster-yaml/experimental/deny-proxy-requests.mdx b/vcluster/configure/vcluster-yaml/experimental/deny-proxy-requests.mdx index e2203d69a..811b1f518 100644 --- a/vcluster/configure/vcluster-yaml/experimental/deny-proxy-requests.mdx +++ b/vcluster/configure/vcluster-yaml/experimental/deny-proxy-requests.mdx @@ -3,7 +3,7 @@ title: Denying Proxy Requests sidebar_label: denyProxyRequests sidebar_position: 7 sidebar_class_name: pro -description: Configure vCluster to deny certain requests in the vCluster proxy. PRO feature. +description: Configure vCluster to deny certain requests in the vCluster proxy. --- import CodeBlock from '@theme/CodeBlock'; import DenyProxyRequestExample from '!!raw-loader!@site/vcluster/configure/vcluster-yaml/experimental/_code/deny-proxy-config.yaml' diff --git a/vcluster/contribute/_category_.json b/vcluster/contribute/_category_.json index 2cbf9ab43..36fc11c59 100644 --- a/vcluster/contribute/_category_.json +++ b/vcluster/contribute/_category_.json @@ -1,5 +1,5 @@ { "label": "Contribute", - "position": "9", + "position": "13", "collapsible": true } \ No newline at end of file diff --git a/vcluster/reference/_category_.json b/vcluster/reference/_category_.json index 247ef0514..913bcbc70 100644 --- a/vcluster/reference/_category_.json +++ b/vcluster/reference/_category_.json @@ -1,5 +1,5 @@ { "label": "Reference", - "position": "8", + "position": "12", "collapsible": true } diff --git a/vcluster/troubleshoot/_category_.json b/vcluster/troubleshoot/_category_.json index 1d636f64e..9cb2df279 100644 --- a/vcluster/troubleshoot/_category_.json +++ b/vcluster/troubleshoot/_category_.json @@ -1,5 +1,5 @@ { "label": "Troubleshoot", - "position": "8", + "position": "10", "collapsible": true } diff --git a/vcluster/understand/_category_.json b/vcluster/understand/_category_.json index 4000c200b..27dea0e19 100644 --- a/vcluster/understand/_category_.json +++ b/vcluster/understand/_category_.json @@ -1,5 +1,5 @@ { "label": "Understand", - "position": "8", + "position": "9", "collapsible": true } diff --git a/vcluster_versioned_docs/version-0.23.0/deploy/upgrade/supported_versions.mdx b/vcluster_versioned_docs/version-0.23.0/deploy/upgrade/supported_versions.mdx index bdba76a45..7349927db 100644 --- a/vcluster_versioned_docs/version-0.23.0/deploy/upgrade/supported_versions.mdx +++ b/vcluster_versioned_docs/version-0.23.0/deploy/upgrade/supported_versions.mdx @@ -1,5 +1,5 @@ --- -title: Lifecycle Policy +title: Lifecycle policy sidebar_label: Lifecycle Policy sidebar_position: 1 keywords: [support matrix, supported versions, lifecycle]