diff --git a/docs/docs-content/clusters/cluster-management/cluster-updates.md b/docs/docs-content/clusters/cluster-management/cluster-updates.md index ff65c9b123..16c9402531 100644 --- a/docs/docs-content/clusters/cluster-management/cluster-updates.md +++ b/docs/docs-content/clusters/cluster-management/cluster-updates.md @@ -1,80 +1,118 @@ --- -sidebar_label: "Cluster Updates" -title: "Cluster Updates" -description: "Events and Notifications on Cluster Updates" +sidebar_label: "Update a Cluster" +title: "Update a Cluster" +description: "Guide to updating a cluster in Palette." hide_table_of_contents: false sidebar_position: 20 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 +## Prerequisites -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. -::: +- An active Kubernetes cluster in Palette. + +## Enablement + + + + +This is the recommended best practice for updating a cluster in Palette. -![Cluster Notification - Update Available](/cluster_list_update_available.png) +1. Log in to [Palette](https://console.spectrocloud.com). -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. +2. Navigate to the left **Main Menu** and select **Profiles**. +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). -![Cluster Update Details](/cluster_update_available_detail.png) +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. +6. Next to the name of the profile, click on the version number and select the new version you just published. -## Instructions +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. -* 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). + +:::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. +::: + -### Examples - Update Notifications + -|**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. ::: +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. + + + + +## Validation + + + + +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. + + + + + +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. + + + + + +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. -### Examples - Notification settings +4. Confirm that the cluster is now using an updated profile. -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: + + -|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| -## Configuration overrides -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. -![Cluster Update Details](/cluster_config_override.png) \ No newline at end of file diff --git a/docs/docs-content/clusters/edge/edgeforge-workflow/palette-canvos.md b/docs/docs-content/clusters/edge/edgeforge-workflow/palette-canvos.md index 46a27ea18f..7424dd11e9 100644 --- a/docs/docs-content/clusters/edge/edgeforge-workflow/palette-canvos.md +++ b/docs/docs-content/clusters/edge/edgeforge-workflow/palette-canvos.md @@ -634,6 +634,10 @@ Using the `-y` option with the `sudo zypper install` command is critical to succ EOF ``` + :::info + If you need to pull images from a private image registry, you can supply the credentials for the registry in the user data file in the `registryCredentials` field or in the cluster profile. Credentials specified in **user-data** overwrites the credentials provided in the cluster profile. To learn how to provide credentials in cluster profiles, refer to [Deploy Cluster with a Private Registry](../site-deployment/deploy-private-registry.md). + ::: + View the newly created user data file to ensure the token is set correctly. ```bash diff --git a/docs/docs-content/clusters/edge/site-deployment/deploy-private-registry.md b/docs/docs-content/clusters/edge/site-deployment/deploy-private-registry.md new file mode 100644 index 0000000000..7fefbcf6bf --- /dev/null +++ b/docs/docs-content/clusters/edge/site-deployment/deploy-private-registry.md @@ -0,0 +1,98 @@ +--- +sidebar_label: "Deploy Cluster with a Private Registry" +title: "Deploy Cluster with a Private Registry" +description: "Instructions for creating an Edge Native Cluster Profile" +hide_table_of_contents: false +sidebar_position: 60 +tags: ["edge"] +--- + +Palette Edge supports authentication with private image registries, which allows your cluster to pull images from a private registry during deployment. You can configure your cluster to pull images from a private registry for both cluster creation and cluster updates. To configure a cluster to pull images from a private image registry, provide the registry URL and the credentials needed to authenticate with the registry in the cluster profile. + +:::caution +If you have specified registry credentials in the `registryCredentials` field in the user data file during the EdgeForge process, the credentials provided in the cluster profile will be ignored. For more information, refer to [EdgeForge - Build Artifacts](../edgeforge-workflow/palette-canvos.md) and [Installer Configuration](../edge-configuration/installer-reference.md#external-registry). +::: + +## Limitations + +- A cluster cannot pull images from more than one private registry. + +- If your private registry has TLS enabled, you can only configure a _new_ cluster to use a TLS certificate with a private registry. You cannot configure an existing cluster with a TLS certificate to communicate with your private registry. + +- Palette Edge supports basic username/password authentication. Token authentication schemes used by services such as AWS ECR and Google Artifact Registry are not supported. + +## Prerequisites + +- At least one Edge host with an x86_64 or AMD64 processor architecture. + +- A private image registry. + +- A provider image you created in the EdgeForge process stored in your private image registry. For more information, refer to [Build Artifacts](../edgeforge-workflow/palette-canvos.md). + +## Enablement + +1. Log in to [Palette](https://console.spectrocloud.com). + +2. Navigate to the left **Main Menu** and select **Profiles**. + +3. If you already have an Edge cluster profile you want to deploy the cluster with, select that profile and select **Create new version** to create a new version of the profile to save your changes. + + Otherwise, click **Add new profile** to create a new cluster profile. + +4. Select the OS layer of your cluster profile. If you are creating a new profile, you will get to configuring the OS layer after filling out **Basic Information** and **Cloud Type**. You should choose the Bring Your Own OS (BYOOS) pack for your OS layer. + +5. Update the `system.uri` parameter in the pack editor for your OS layer. Use the custom OS image you created in the EdgeForge process. Refer to the EdgeForge [Build Images](../edgeforge-workflow/palette-canvos.md) guide if you are missing a custom OS image. The following is an example configuration using the BYOOS pack with a custom OS image. + + ```yaml + pack: + content: + images: + - image: '{{.spectro.pack.edge-native-byoi.options.system.uri}}' + # - image: example.io/my-other-images/example:v1.0.0 + # - image: example.io/my-super-other-images/example:v1.0.0 + + options: + system.uri: example.io/my-images/example-custom-os:v1.4.5 + ``` + +6. At the root level of YAML for your OS layer, add the `providerCredentials` field to provide the credentials you need to authenticate with your registry. For more information about the `providerCredentials` field, refer to [Bring Your Own OS (BYOOS)](../../../integrations/byoos.md) pack page. The `providerCredentials.password` field will be masked when you provide it in the YAML file. You can also use a macro to store your credentials instead of providing it directly in the YAML file. For more information, refer to [Macros Support](../../cluster-management/macros.md): + + ```yaml {7-16} + pack: + content: + images: + - image: '{{.spectro.pack.edge-native-byoi.options.system.uri}}' + # - image: example.io/my-other-images/example:v1.0.0 + # - image: example.io/my-super-other-images/example:v1.0.0 + providerCredentials: + registry: domain/project + user: user + password: ****** + certificates: | + -----BEGIN CERTIFICATE----- + MIIDVzCCAj+gAwIBAgIRANtGPo/hFkZtYRNw0KaeW54wDQYJKoZIhvcNAQELBQAw + ---------------------------------------------------------------- + 7OicCaV35lje5FSl0owu74ghAlCgMyAdKsJf615g1kKO4V5E2BMErd9Ibw== + -----END CERTIFICATE----- + + options: + system.uri: example.io/my-images/example-custom-os:v1.4.5 + ``` + +7. If you are updating an existing profile, click **Confirm changes**, and then click **Save changes** to publish the new version of your cluster profile. If you are creating a new profile, click **Next layer** and finish configuring the remaining layers. + +8. If you already have an active cluster that is using the original version of the cluster profile, update the cluster so that it uses the new version of the cluster profile you just published. For more information about updating clusters, refer to [Update a Cluster](../../cluster-management/cluster-updates.md). This will trigger a full cluster repave since it includes an update to the OS layer of the cluster. To learn more about cluster repave behavior, refer to [Repave Behavior and Configuration](../../cluster-management/node-pool.md#repave-behavior-and-configuration). + + If you don't have an active cluster yet, deploy a new cluster with the profile you just created, and the cluster will pull images from the private registry you specified. + +## Validate + +1. Log in to [Palette](https://console.spectrocloud.com). + +2. Navigate to the left **Main Menu** and select **Clusters**. + +3. Select the cluster that is using the profile with the registry credentials. + +4. Navigate to the **Events** tab of the cluster to confirm if the cluster is instructed pull images from the private registry. + +5. If the cluster is successfully provisioned and enters the **Running** state, then you have successfully configured the cluster to authenticate with and pull images from the private registry. If the cluster does not enter the **Running** state, navigate to the **Events** table and observe if the cluster is emitting errors related to image pulls. \ No newline at end of file diff --git a/docs/docs-content/clusters/edge/site-deployment/model-profile.md b/docs/docs-content/clusters/edge/site-deployment/model-profile.md index 5d170fc9dd..c1ea5af800 100644 --- a/docs/docs-content/clusters/edge/site-deployment/model-profile.md +++ b/docs/docs-content/clusters/edge/site-deployment/model-profile.md @@ -57,7 +57,7 @@ The following steps will guide you on how to create a cluster profile for Edge. 6. Select **Edge Native** as the **Cloud Type** and click on **Next**. -7. Select **Public Repo** in the **Registry field**. +7. Select either **Public Repo** or **Palette Registry (OCI)** in the **Registry field**. 8. Select **BYOS Edge OS** in the **Pack Name** field and the pack version. diff --git a/docs/docs-content/integrations/byoos.md b/docs/docs-content/integrations/byoos.md index 412d42e435..598e90e93e 100644 --- a/docs/docs-content/integrations/byoos.md +++ b/docs/docs-content/integrations/byoos.md @@ -21,12 +21,13 @@ Using your custom OS provides several benefits, including the ability to control ## Versions Supported -**1.0.x** -
- + + + + ## Prerequisites @@ -51,8 +52,10 @@ The BYOS Edge OS pack supports the following parameters. | `pack.content.images` | Specifies a list of OS images to use with the pack. | list | | `pack.content.images.image` | An OS image to use with the pack. | string| | `system.uri` | The system URI specifies the location of BYOOS image. | string| - - +| `providerCredentials.registry` | Specifies the private registry for the cluster to pull images from | string | +| `providerCredentials.username` | Specifies the username used for authentication with a private registry. | string | +| `providerCredentials.password` | Specifies the password used for authentication with a private registry. | string | +| `providerCredentials.certificate` | Specifies the X509 certificate used for authentication and encryption with a private registry | string | ```yaml pack: @@ -61,6 +64,17 @@ The BYOS Edge OS pack supports the following parameters. - image: '{{.spectro.pack.edge-native-byoi.options.system.uri}}' # - image: example.io/my-other-images/example:v1.0.0 # - image: example.io/my-super-other-images/example:v1.0.0 + providerCredentials: + registry: domain/project + user: user + password: ****** + certificates: | + -----BEGIN CERTIFICATE----- + MIIDVzCCAj+gAwIBAgIRANtGPo/hFkZtYRNw0KaeW54wDQYJKoZIhvcNAQELBQAw + ---------------------------------------------------------------- + 7OicCaV35lje5FSl0owu74ghAlCgMyAdKsJf615g1kKO4V5E2BMErd9Ibw== + -----END CERTIFICATE----- + options: system.uri: example.io/my-images/example-custom-os:v1.4.5 @@ -83,6 +97,9 @@ Select the BYOOS pack and fill out the required parameters during the cluster pr + + + ## Prerequisites To use the non-Edge BYOOS pack, you must have the following: