Skip to content
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

Add notes about edge cluster update limitations #1904

Merged
merged 4 commits into from
Dec 16, 2023
Merged

Add notes about edge cluster update limitations #1904

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
831d87c
docs: add IP requirement
lennessyy Dec 15, 2023
31c2bbe
docs: add note about edge cluster CNI pack
lennessyy Dec 15, 2023
d577ad9
docs: typo
lennessyy Dec 15, 2023
432bc73
Apply suggestions from code review
lennessyy Dec 15, 2023
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
126 changes: 81 additions & 45 deletions docs/docs-content/clusters/cluster-management/cluster-updates.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,73 +8,109 @@ tags: ["clusters", "cluster management"]
---


Palette supports various kinds of updates to running clusters, such as upgrade of Kubernetes version, upgrade of add-on versions, the addition of new add-ons, removing existing ones, etc. Based on the nature of the change, one of the following two mechanisms can be used to apply cluster updates to the cluster.
Palette allows you to update active clusters. You can update any layer of a cluster, including all infrastructure layers and add-on layers. Depending on the nature of the update, a cluster update could trigger different cluster repave operations. For more information, refer to [Repave Behaviors and Configurations](./node-pool.md#repave-behavior-and-configuration).

## Cluster Profile Updates
## Limitations

Fundamental changes to the cluster’s definition, such as upgrading Kubernetes versions, installing new packs, uninstalling previously installed packs, and updating default pack configuration, are initiated through the cluster profile. These changes result in update notifications on all the clusters that are instantiated from the cluster profile. Update notifications consist of detailed information about all the changes applied to the profile since the initial installation or the previous update. In addition, users can update the clusters individually at an appropriate time.
- You cannot update a cluster while its status is still **Provisioning**.

:::info
- You cannot change the Container Network Interface (CNI) of an Edge cluster. You must delete and re-create the cluster instead. For more information about creating an Edge cluster, refer to [Create Cluster Definition](../edge/site-deployment/site-installation/cluster-deployment.md).

Cluster Profile Changes will not be displayed or allowed on clusters when the cluster is provisioning and all worker node additions are completed. This is done to prevent the Kubernetes clusters from becoming unstable and transitioning into an unrecoverable state due to the changes in core components.
:::
## Prerequisites

- An active Kubernetes cluster in Palette.

## Enablement

<Tabs groupId="update-method">
<TabItem value="profile-version" label="Use a new cluster profile version">

This is the recommended best practice for updating a cluster in Palette.

1. Log in to [Palette](https://console.spectrocloud.com).

2. Navigate to the left **Main Menu** and select **Profiles**.

![Cluster Notification - Update Available](/cluster_list_update_available.png)
3. Create a new version of the profile you want to update. For more information, refer to [Version a Cluster Profile](../../profiles/cluster-profiles/modify-cluster-profiles/version-cluster-profile.md).

Updates to pack configuration might result in a conflict if the configuration was previously overridden within the cluster. These conflicts are presented to the user and need to be resolved before changes can be applied to the cluster.
4. Navigate to the left **Main Menu** and select **Cluster**.

5. Select the cluster you want to update, and navigate to the **Profile** tab of the cluster.

![Cluster Update Details](/cluster_update_available_detail.png)
6. Next to the name of the profile, click on the version number and select the new version you just published.

7. Click **Save**. Depending on the changes you made to the profile, doing so might trigger a cluster repave warning. Click **Continue** to confirm updating the cluster.

</TabItem>

## Instructions
<TabItem value="update-cluster-profile" label="Update cluster profile">

* Navigate to the cluster profiles page and choose the profile to be updated.
* Make the desired changes. These include add/delete layers, change pack version, change pack values, etc. Save your changes.
* On the Clusters page, observe the ‘Updates Available’ tag on every previously launched cluster using the updated cluster profile.
* Click on one of the clusters to be updated to invoke the cluster details page.
* An update notification in the form of a button called ‘Updates Available’ can be seen on the right top of the screen. Click the button to open the update notifications dialog.
* A notification is created for each change made to the profile. Review all notifications. Depending on the nature of the change, additional action might be required for certain notifications. There are typical scenarios where the settings or attached manifests for a pack are directly updated on the cluster, resulting in a conflict with the new incoming changes from the profile. The updated profile settings and modified cluster settings are shown side by side for such cases, with the differences highlighted. Resolve all of the conflicts. When there has been no update to the pack settings or manifests, the incoming changes from the profile are automatically merged. A side-by-side comparison between the original and merged cluster settings is still displayed in such cases for review purposes. However, users may choose to customize settings from this dialog further.
* Once all the notifications are reviewed and conflicts, if any, are resolved, confirm updates to apply changes to the cluster.
* The system starts the update process in a few seconds. Depending upon the nature of the change, a rolling update nodes of the clusters may take place. The detailed status of the upgrade is made available at UI.
* Repeat this process for other clusters to be upgraded.
You can make updates to a profile that is in-use by one or more active clusters, and doing so will trigger an update to all clusters that are using the cluster profile. For more information, refer to [Update a Cluster Profile](../../profiles/cluster-profiles/modify-cluster-profiles/update-cluster-profile.md).
lennessyy marked this conversation as resolved.
Show resolved Hide resolved

:::caution
We do not recommend updating a currently deployed cluster profile version to push out changes. Instead, we recommend creating a new profile version, and then upgrade active clusters to the new version.
lennessyy marked this conversation as resolved.
Show resolved Hide resolved
:::

</TabItem>

### Examples - Update Notifications
<TabItem value="override-profile-config" label="Override cluster profile configurations">

|**Update Type** |**Description**|**Notification Example** |
|:---------------|:---------|:-----------------------|
Pack Version Upgrade |The existing pack version is upgraded to a different version in the cluster profile |Kubernetes version is updated 1.18.16 > 1.20.0|
|Pack Values Update |The existing pack values are updated in the cluster profile |Kubernetes 1.20.0 values are updated|
|Add Pack|Add a new pack to the cluster profile |New Kibana 7.2.4 layer is added|
|Delete Pack|Delete the existing pack from the cluster profile |Kibana 7.2.4 layer is deleted|
|Attach Pack Manifest|Delete the existing pack from the cluster profile |Manifest security is attached to the pack Kubernetes|
|Update Pack Manifest|The attached pack manifest content is updated in the cluster profile|manifest security is updated in the pack Kubernetes|
|Delete Pack Manifest |The attached pack manifest is deleted from the cluster profile|manifest security is deleted in the pack Kubernetes|

:::info
You can modify the configuration of a deployed cluster without changing the cluster profile itself to update a cluster.

Prior to applying the notifications resulting from a profile update, the notification is automatically cleared if the corresponding changes are reverted.

:::caution
We do not recommend updating a currently deployed cluster's profile configurations without updating the profile itself. Instead, we recommend creating a new profile version, and then upgrade active clusters to the new version.
lennessyy marked this conversation as resolved.
Show resolved Hide resolved
:::

1. Log in to [Palette](https://console.spectrocloud.com).

2. Navigate to the left **Main Menu** and select **Clusters**.

3. Select the cluster you want to update, and navigate to the **Profile** tab of the cluster.

4. In the profile tab, make changes to the different layers as appropriate. The changes you make here are specific to this cluster only and do not propagate to the cluster profile or other clusters using the same profile.

5. Click **Save** to confirm your changes. Acknowledge the cluster repave warning if necessary.

</TabItem>
</Tabs>

## Validation

<Tabs groupId="update-method">
<TabItem value="profile-version" label="Use a new cluster profile version">

1. Log in to [Palette](https://console.spectrocloud.com).

2. Navigate to the left **Main Menu** and select **Clusters**.

3. Select the cluster you updated, and navigate to the **Profile** tab of the cluster.

4. Confirm that the cluster is now using an updated profile.

</TabItem>

<TabItem value="update-cluster-profile" label="Update cluster profile">

1. Log in to [Palette](https://console.spectrocloud.com).

2. Navigate to the left **Main Menu** and select **Clusters**.

3. Select the cluster you updated, and navigate to the **Profile** tab of the cluster.

4. Confirm that the cluster is now using an updated profile.

</TabItem>

### Examples - Notification settings
<TabItem value="override-profile-config" label="Override cluster profile configurations">

As described above, notifications originate from changes to pack settings or manifest. They are accompanied by a settings dialog with a split pane showing differences in values. Following are a few examples of such scenarios:
1. Log in to [Palette](https://console.spectrocloud.com).

|Values Updated |Values overridden in Clusters |Settings displayed (LHS) |Settings displayed (RHS) |Auto Merged | Action |
|:---------------|:---------|:--------------------|:--------|:-------|:--------|
|Pack Values|No|Original pack settings| Updated pack settings| Yes| Review and/or modify if desired|
|Attached Manifests|No|Original Manifests| Updated Manifests| Yes| Review and/or modify if desired|
|Pack Values|Yes|Updated settings from Cluster Profile| Current settings from cluster| No| Resolve all conflicts|
|Attached Manifests|Yes|Updated settings from Cluster Profile| Current settings from cluster| No| Resolve all conflicts|
|Pack Version Changed|No|Original pack settings| Updated pack settings| Yes| Review and/or modify if desired|
|Pack Version Changed|Yes|Updated settings from Cluster Profile| Current settings from cluster| No| Resolve all conflicts|
2. Navigate to the left **Main Menu** and select **Clusters**.

## Configuration overrides
3. Select the cluster you updated, and navigate to the **Profile** tab of the cluster.

Every pack installed via cluster profile provides a set of out-of-the-box default settings. These can be overridden at the time of launching a new cluster or any time afterward for a running cluster. Besides basic defaults, Palette also provides useful presets. Presets are preconfigured configuration blocks logically grouped. Can leverage these to turn a feature on/off quickly. For example, enabling ingress for a Prometheus/Grafana pack requires many settings to be added. However, the Ingres preset for the Prometheus pack makes it easy to make this change.
4. Confirm that the cluster is now using an updated profile.

![Cluster Update Details](/cluster_config_override.png)
</TabItem>
</Tabs>
5 changes: 3 additions & 2 deletions ...s-content/clusters/edge/site-deployment/site-installation/cluster-deployment.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,9 +8,9 @@ tags: ["edge"]
---



To complete the Edge Installation process, an Edge host must become a member of a host cluster. You can add an Edge host to an existing host cluster of type Edge Native, or you can create a new host cluster for Edge hosts and make the Edge host a member.


Select the workflow that best fits your needs.

- [Create an Edge Native Host Cluster](#create-an-edge-native-host-cluster)
Expand Down Expand Up @@ -46,8 +46,9 @@ Use the following steps to create a new host cluster so that you can add Edge ho
7. Review your cluster profile values and make changes as needed. Click on **Next**.


8. Provide the host cluster with the Virtual IP (VIP) address used by the physical site. You can also select any SSH keys in case you need to remote into the host cluster. You can also provide a list of Network Time Protocol (NTP) servers. Click on **Next**.
8. Provide the host cluster with the Virtual IP (VIP) address used by the physical site. Ensure that this VIP is not in a CIDR range that cannot routed through a proxy. In addition, ensure that this VIP does not overlap with any IP address already used by other hosts in your network, including your Edge hosts.

You can also select any SSH keys in case you need to remote into the host cluster. You can also provide a list of Network Time Protocol (NTP) servers. Click on **Next**.

9. The node configuration page is where you can specify what Edge hosts make up the host cluster. Assign Edge hosts to the **master-pool** and the **worker-pool**. When you have completed configuring the node pools, click on **Next**.

Expand Down