From c9d5826a0e047f57c27171d45738f47d2dfc2c4e Mon Sep 17 00:00:00 2001 From: Karl Cardenas <29551334+karl-cardenas-coding@users.noreply.github.com> Date: Wed, 13 Nov 2024 13:48:01 -0700 Subject: [PATCH] docs: DOC-1098 PCG Migrate (#4689) * docs: DOC-1098 * docs: content update * save * docs: content update * docs: feedback from Ravi * docs: updated content * docs: apply suggestions from code review Co-authored-by: caroldelwing * ci: auto-formatting prettier issues --------- Co-authored-by: caroldelwing Co-authored-by: karl-cardenas-coding --- .../docs-content/clusters/pcg/architecture.md | 11 +- .../clusters/pcg/manage-pcg/migrate_pcg.md | 156 ++++++++++++++++++ 2 files changed, 166 insertions(+), 1 deletion(-) create mode 100644 docs/docs-content/clusters/pcg/manage-pcg/migrate_pcg.md diff --git a/docs/docs-content/clusters/pcg/architecture.md b/docs/docs-content/clusters/pcg/architecture.md index 316a607583..d6fe847801 100644 --- a/docs/docs-content/clusters/pcg/architecture.md +++ b/docs/docs-content/clusters/pcg/architecture.md @@ -73,6 +73,14 @@ cluster deployment process. Once a cluster is deployed, the PCG is no longer inv Palette and the deployed cluster. The cluster will communicate with Palette directly through local network gateways or a proxy server. The workload cluster is self-sustaining and does not require the PCG to be operational. +For every workload cluster that a PCG facilitates deployment, the workload cluster will maintain a reference point back +to that PCG. This reference point is used to identify the PCG used in the event of a cluster deletion. The mapping +between a workload cluster and a PCG is stored in the Palette management plane. + +A PCG can be migrated. Migrated means that all clusters deployed by the original PCG will be updated to reference a +different PCG. This action is internal to the Palette management plane. The migration process is necessary when you want +to remove an existing PCG. Refer to the [Migrate a PCG](./manage-pcg/migrate_pcg.md) for guidance on migrating a PCG. +
Cluster API State Management with PCG @@ -82,7 +90,8 @@ workload cluster as a dedicated service. The workload cluster, through the Palet managing its own lifecycle operations. The PCG is not involved in managing the workloads of the deployed cluster. In the event of a cluster deletion, the CAPI state management is pivoted back to the PCG, and CAPI begins the cluster -deletion process to release the resources used by the workload cluster. +deletion process to release the resources used by the workload cluster. The pivot process uses the PCG reference point +to correctly identify which PCG to move the CAPI state management back to.
diff --git a/docs/docs-content/clusters/pcg/manage-pcg/migrate_pcg.md b/docs/docs-content/clusters/pcg/manage-pcg/migrate_pcg.md new file mode 100644 index 0000000000..bd447c6fae --- /dev/null +++ b/docs/docs-content/clusters/pcg/manage-pcg/migrate_pcg.md @@ -0,0 +1,156 @@ +--- +sidebar_label: "Migrate a PCG" +title: "Migrate a PCG" +description: "Learn why, when, and how to migrate an existing Private Cloud Gateway (PCG) to a differnt PCG." +hide_table_of_contents: false +sidebar_position: 50 +tags: ["pcg"] +--- + +Clusters deployed through a Private Cloud Gateway (PCG) maintain a reference point to the PCG that deployed them. This +reference point is required for Palette to know which PCG to use when the cluster needs to be removed. A Cluster API +pivot occurs between the PCG and the cluster during a cluster deployment and removal. In a cluster creation, the pivot +occurs from the PCG to the cluster. In a cluster removal, the Cluster API pivot occurs from the cluster to the PCG. +Check out the [Order of Operations](../../../architecture/orchestration-spectrocloud.md) page to learn more about the +Cluster API pivot. + +The cluster's PCG reference point is stored in the Palette management plane's internal database. You can retrieve a +cluster's PCG reference point by using the Palette API endpoint `GET /v1/spectroclusters/:uid`. The response payload's +`metadata.annotations.overlordUid` field contains the ID of the PCG that deployed the cluster. + +```json hideClipboard {5} +{ + "metadata": { + "annotations": { + "jetUid": "***********************", + "overlordUid": "6732677ce46389af646d517a", + "ownerUid": "***********************", + "palette.spectrocloud.com/disablenodeautoremidiation": "false", + "permissions": "cluster.create,cluster.delete,cluster.get,cluster.import,cluster.list,cluster.update,tag.update", + "projectUid": "***********************", + "rootDomain": "console.spectrocloud.com", + "scope": "project", + "scopeVisibility": "16", + "spectroComponentsUpgradeForbidden": "true", + "tenantUid": "***********************" + }, +``` + +
+How do I get my PCG's `overlordUid`? + +The `overlordUid` is a unique identifier of the PCG that deployed the cluster. However, this value is different from the +actual cluster ID of the PCG. To retrieve a PCG cluster's `overlordUid`, use the following kubectl command on the PCG +cluster. + +```shell +kubectl get configmap overlord-config --namespace=jet-system --output=jsonpath='{.data.overlord-config\.yaml}' | grep 'overlordUid:' | sed 's/overlordUid: //' +``` + +You will get the `overlordUid` of the PCG cluster. + +```text hideClipboard +6732677ce46389af646d517a +``` + +
+ +## What is a PCG migration? + +A PCG migration is an action that updates the PCG reference point mapping in Palette for clusters deployed by a specific +PCG. All clusters deployed by the original PCG will be updated to reference a new PCG. This action is internal to the +Palette management plane. The migration process is necessary when you want to remove the existing PCG. The ability to +migrate a PCG is helpful in scenarios such as: + +- Decommissioning an existing PCG. + +- PCG upgrade errors. + +:::warning + +A PCG migration is an irreversible action. Once a PCG is migrated, the original PCG is no longer associated with the +clusters that it deployed. + +::: + +Use the following steps to update the PCG reference point mapping to a different PCG. + +## Prerequisites + +- Tenant admin access to Palette. + +- At least two healthy PCGs with network connectivity to the Palette management plane. + +- The new PCG must target the same infrastructure provider as the existing PCG. + +## Migrate PCG + +1. Log in to [Palette](https://console.spectrocloud.com) as a tenant administrator. + +2. Navigate to the left **Main Menu** and select **Tenant Settings**. + +3. Select **Private Cloud Gateways** from the **Tenant Settings Menu**. + +4. In the list of PCGs, identify the PCG that you want to migrate and click on the **three-dot Menu** at the end of the + PCG row. + +5. Select **Migrate** from the **drop-down Menu**. + +6. In the **Migrate Cloud Gateway** dialog box, select the PCG from the **PCG** drop-down list that you want to migrate + to. + +7. Click **Migrate**. + +We recommend you remove the cloud account created by the PCG that you migrated. This will prevent any future cluster +deployments from using the cloud account associated with the migrated PCG. During a cluster deployment, if you +accidentally select the cloud account mapped to the former PCG, Palette will automatically ensure the newly specified +PCG is used as the PCG reference point instead of the former PCG that belongs to the cloud account selected. + +## Validate + +After the migration is complete, you can validate it by checking that a cluster deployed with the migrated PCG no longer +references the old PCG. Use the Palette API endpoint `GET /v1/spectroclusters/:uid` and verify the +`metadata.annotations.overlordUid` field to ensure that the cluster now references the new PCG. + +1. Log in to [Palette](https://console.spectrocloud.com). + +2. Navigate to the left **Main Menu** and click **Clusters**. + +3. Click on a cluster that was deployed by the PCG that you migrated. Take note of the cluster ID. You can find the ID + in the URL of the browser. It is the last part of the URL, located after `/clusters/`. + + ```text hideClipboard + https://console.spectrocloud.com/clusters/11111111111111111111 + ``` + +4. Retrieve a deployed cluster's `overlordUid` using the Palette API endpoint `GET /v1/spectroclusters/:uid`. You can + use the `curl` command below. Make sure you replace the `:uid` path parameter with the cluster ID, and the `apiKey` + and `ProjectUid` headers with your own values. + + ```shell hideClipboard + curl --location 'https://api.spectrocloud.com/v1/spectroclusters/:uid' \ + --header 'ProjectUid: XXXXXXXXXXXX' \ + --header 'Accept: application/json' \ + --header 'apiKey: XXXXXXXXXXX' + ``` + +5. Verify that the `metadata.annotations.overlordUid` field in the response payload matches the new PCG's `overlordUid`. + Refer to the intro section of this guide for guidance on how to get the `overlordUid` of a PCG cluster. + + ```json hideClipboard {5} + { + "metadata": { + "annotations": { + "jetUid": "*********************************", + "overlordUid": "672fa7ad6e7f4d26fd91d81b", + "ownerUid": "********************************", + "palette.spectrocloud.com/disablenodeautoremidiation": "false", + "permissions": "cluster.create,cluster.delete,cluster.get,cluster.import,cluster.list,cluster.update,tag.update", + "projectUid": "**********************", + "rootDomain": "console.spectrocloud.com", + "scope": "project", + "scopeVisibility": "16", + "spectroComponentsUpgradeForbidden": "true", + "tenantUid": "************************" + }, + ```