From 5bd33473c7949a7406e4d566ba9569e74a61338e Mon Sep 17 00:00:00 2001 From: Lenny Chen <55669665+lennessyy@users.noreply.github.com> Date: Fri, 20 Sep 2024 15:54:09 -0700 Subject: [PATCH] docs: clarify agent upgrade documentation (#4031) * docs: add table * docs: incorporate feedback * docs: virtual box tutorial gitleaks --------- Co-authored-by: Lenny Chen --- .../pause-platform-upgrades.md | 119 +++++++++++++++++- .../edge/deploy-cluster-virtualbox.md | 2 +- 2 files changed, 115 insertions(+), 6 deletions(-) diff --git a/docs/docs-content/clusters/cluster-management/platform-settings/pause-platform-upgrades.md b/docs/docs-content/clusters/cluster-management/platform-settings/pause-platform-upgrades.md index 01ed4ec891..eaa2015bbc 100644 --- a/docs/docs-content/clusters/cluster-management/platform-settings/pause-platform-upgrades.md +++ b/docs/docs-content/clusters/cluster-management/platform-settings/pause-platform-upgrades.md @@ -7,12 +7,81 @@ sidebar_position: 0 tags: ["clusters", "cluster management"] --- -Palette supports the **Pause Agent Upgrades** feature to exclude a cluster or a group of clusters from getting -automatically upgraded when Palette is upgraded. The three ways to activate this feature are: +Palette supports the **Pause Agent Upgrades** feature to exclude a cluster or a group of clusters from having their +Palette agent automatically upgraded when Palette is upgraded. -- Pause Upgrades for a Single Cluster -- Pause Upgrades for all Clusters within Project Scope -- Pause Upgrades for all Clusters within Tenant Scope +:::info + +This feature only pauses upgrades for Palette agents, not updates to the clusters themselves. + +::: + +## Pause Agent Upgrade Scopes + +Agent upgrades can be paused and resumed in the following scopes: + +- Pause agent upgrades for a single cluster +- Pause agent upgrades for all clusters within a project +- Pause agent upgrades for all clusters within a tenant + +When determining if the agent upgrades for one cluster is paused or not, you only need to look at the setting for the +cluster itself. Agent upgrade settings are always applied based on individual cluster settings. Project and tenant agent +upgrade settings are not inherited - instead cluster level settings are set to match _each time_ project and tenant +level settings are changed. + +Pausing or resuming agent upgrades at a higher-level scope will automatically pause or resume agent upgrades in the +lower-level scopes. For example, if you pause agent upgrades at the tenant level, then agent upgrades will be paused for +all projects within that tenant, and all clusters within those projects. Similarly, if you resume upgrades at the +project level, then all clusters within that project will have their agent upgrades resumed. + +This is a one-time change that happens at the moment when you pause or resume upgrades in the project or tenant scope, +and it does not mandate that the same setting be kept at the lower scopes. If you pause or resume agent upgrades in a +lower-level scope, it will override the setting from the higher-level scope. For example, even if all agent upgrades are +paused at the tenant level, you can override the tenant-level pause by resuming upgrades in a specific project or a +specific cluster. + +:::warning + +Overrides of agent upgrade settings are not permanent. When the pause agent settings at the project or tenant scope +change, the agent upgrade setting in the cluster or project scopes will always be set to match the higher-level scope +setting regardless. If you want to override the project or tenant level agent upgrade setting, you must change the agent +upgrade setting in the lower scope _after_ the change in the higher scope. + +::: + +The following table lists some example upgrade configurations and whether the Palette agent will be upgrades in those +settings. Note that only the settings at the cluster level determines whether the Palette agent will be upgraded. + +| Tenant | Project | Cluster | Outcome | +| ---------------- | ---------------- | ---------------- | ----------------------------------------- | +| Upgrades paused | Upgrades paused | Upgrades enabled | Palette agent will upgrade automatically. | +| Upgrades enabled | Upgrades enabled | Upgrade paused | Palette agent upgrades are paused. | + +## Agent Upgrades for PCG and Edge Hosts + +Aside from clusters, you can also pause the agent upgrades on Private Cloud Gateways (PCG) and Edge hosts that are +registered with Palette but are not part of a cluster. + +Since PCGs are scoped to tenants, you can pause the agent upgrades on a PCG by pausing agent upgrades on the tenant to +which the PCG is associated. You can also pause or resume upgrades for a PCG in the PCG details page through **Cluster +Settings**. Similar to clusters, pausing and resuming upgrades at the tenant level will pause or resume agent upgrades +for all PCGs in the tenant. Pausing and resuming upgrades for a PCG individually will override the tenant-level setting. + +Edge hosts that are part of a cluster have their agent upgrades managed by the settings of their cluster. Edge hosts +that are not part of a cluster have their agent upgrades managed at the project and tenant level. Similar to clusters, +pausing or resuming agent upgrades at the tenant level will automatically pause or resume agent upgrades for all +projects within that tenant. However, you can override the tenant level setting by manually changing the upgrade setting +at the project level. + +The following is a table showing the scopes at which you can pause agent upgrades for different objects. The same +relationship between the scopes applies: Changing the setting in a higher scope will trigger a one-time change to the +lower scopes, and changing the setting at the lower scope will override the setting in the higher scope. + +| | Individual Cluster/PCG | Project | Tenant | +| --------------- | ---------------------- | ------- | ------ | +| Cluster | ✅ | ✅ | ✅ | +| PCG | ✅ | ❌ | ✅ | +| Idle Edge hosts | ❌ | ✅ | ✅ | ## Prerequisites @@ -71,6 +140,24 @@ clusters within the project scope, or all within the tenant scope. + + +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. Click on the PCG you want to pause or resume upgrades for. + +5. From the PCG details page, click **Settings** > **Cluster Settings**. + +6. Toggle the **Pause Agent Upgrades** button to pause upgrades for the PCG. + +7. A pop-up box will ask you to confirm the action. Click **OK**. + + + ## Validate @@ -93,6 +180,9 @@ clusters within the project scope, or all within the tenant scope. +Pausing upgrades in a project also pauses agent upgrades for all Edge hosts in the project that are not part of a +cluster. + 1. Log in to [Palette](https://console.spectrocloud.com). 2. Navigate to the left **Main Menu** and click on **Project Settings**. @@ -105,6 +195,9 @@ clusters within the project scope, or all within the tenant scope. +Pausing upgrades in a Tenant also pauses agent upgrades for all Edge hosts in the tenant that are not part of a cluster, +as well as PCGs in the tenant. + 1. Log in to [Palette](https://console.spectrocloud.com). 2. Navigate to the left **Main Menu** and click on **Tenant Settings**. @@ -115,4 +208,20 @@ clusters within the project scope, or all within the tenant scope. + + +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. Click on the PCG you want to pause or resume upgrades for. + +5. From the PCG details page, click **Settings** > **Cluster Settings**. + +6. The **Pause Agent Upgrades** toggle button is checked. + + + diff --git a/docs/docs-content/tutorials/edge/deploy-cluster-virtualbox.md b/docs/docs-content/tutorials/edge/deploy-cluster-virtualbox.md index cbae83d752..b971d06b15 100644 --- a/docs/docs-content/tutorials/edge/deploy-cluster-virtualbox.md +++ b/docs/docs-content/tutorials/edge/deploy-cluster-virtualbox.md @@ -196,7 +196,7 @@ displayed in the example output below. stylus: site: paletteEndpoint: api.spectrocloud.com - edgeHostToken: 62ElvdMeX5MdOESgTleBjjKAB123456 + edgeHostToken: **************** users: - name: kairos