docs: PEM-6276 updated DNS and certificate prereqs (#5377)

* docs: PEM-6276 updated DNS and certificate prereqs

* docs: update guidance

docs/docs-content/enterprise-version/system-management/ssl-certificate-management.md

@@ -15,16 +15,17 @@ Palette uses SSL certificates to secure external communication. Internal compone
 and use HTTPS. External communication with Palette, such as the system console, gRPC endpoint, and API endpoint,
 requires you to upload an SSL certificate to enable HTTPS.
 
-:::info
+Palette validates the combination of system address, certificate, key, and Certificate Authority (CA). Ensure that the
+certificate is not expired, as well as that it is valid for the CA and the system address. Additionally, the system
+address must be accessible from the system console.
 
-Enabling HTTPS is a non-disruptive operation. You can enable HTTPS at any time without affecting the system's
-functionality.
+:::warning
 
-:::
-
-## Upload an SSL Certificate
+You can swap out the external endpoint certificate at any time without affecting the system functionality. However,
+updating the system address may require manual reconciliation on deployed clusters. Review the
+[prerequisites](#prerequisites) before you proceed to ensure you have all met all requirements.
 
-You can upload an SSL certificate in Palette by using the following steps.
+:::
 
 ### Prerequisites
 
@@ -37,6 +38,15 @@ You can upload an SSL certificate in Palette by using the following steps.
   not specify a custom domain name, the certificate must be created for the Palette system console's IP address. You can
   also specify a load balancer's IP address if you are using a load balancer to access Palette .
 
+- The new SSL certificate must also include the previous DNS name or IP address in the Subject Alternative Name (SAN)
+  field. This ensures that existing connections are not interrupted.
+
+- If you are changing the DNS endpoint, ensure both the new and old DNS endpoints are accessible for some time, ideally
+  sufficient time to ensure all existing Palette clusters have been updated to use the new endpoint and that no existing
+  connections are interrupted. Refer to the
+  [Reconcile System Address on Deployed Clusters](#reconcile-system-address-on-deployed-clusters) section for more
+  information on updating deployed clusters.
+
 ### Enablement
 
 1. Log in to the Palette system console.
@@ -73,3 +83,56 @@ You can validate that your certificate is uploaded correctly by using the follow
 
 Palette is now using your uploaded certificate to create a secure HTTPS connection with external clients. Users can now
 securely access the system console, gRPC endpoint, and API endpoint.
+
+### Prerequisites
+
+- Palette access with a configured cloud account.
+
+- A cluster deployed prior to the system address update. Refer to the [Clusters](../../clusters/clusters.md) section for
+  further guidance.
+
+- `kubectl` installed. Use the Kubernetes [Install Tools](https://kubernetes.io/docs/tasks/tools/) page for further
+  guidance.
+
+### Enablement
+
+1. Log into Palette using the configured system address.
+
+2. Navigate to the left **Main Menu** and select **Clusters**. Palette displays your deployed clusters. The clusters
+   that have the **Unknown** status need to be manually updated.
+
+3. Select your cluster from the **Clusters** list. The cluster **Overview** tab displays.
+
+4. Download the kubeconfig file. This file allows you to connect to your deployed cluster. Check out the
+   [Kubeconfig](../../clusters/cluster-management/kubeconfig.md) page to learn more.
+5. Open a terminal window and set the environment variable `KUBECONFIG` to point to the file you downloaded.
+
+   ```shell
+   export KUBECONFIG=<path-to-downloaded-kubeconfig-file>
+   ```
+
+6. Execute the following command in your terminal to view the cluster namespaces. Make a note of the cluster namespace
+   that Palette has created. Its name follows the pattern **cluster-id**.
+
+   ```shell
+   kubectl get namespaces
+   ```
+
+7. Palette uses ConfigMaps to save its configuration and environment variables. Update the `apiEndpoint` value in the
+   `hubble-info` ConfigMap to use the newly configured system address.
+
+   ```shell
+   kubectl edit configmap hubble-info --namespace <cluster-id>
+   ```
+
+8. Save your changes and exit the editor.
+
+Repeat these steps for each cluster that has the **Unknown** status.
+
+### Validate
+
+1. Log into Palette using the configured system address.
+
+2. Navigate to the left **Main Menu** and select **Clusters**.
+
+3. Palette successfully displays the status of your clusters. None of your clusters has the **Unknown** status.

docs/docs-content/vertex/system-management/ssl-certificate-management.md

@@ -15,16 +15,15 @@ Palette VerteX uses SSL certificates to secure external communication. The inter
 default secured and use HTTPS. External communication with Palette VerteX, such as the system console, gRPC endpoint,
 and API endpoint, requires you to upload an SSL certificate to enable HTTPS.
 
-:::info
+Palette VerteX validates the combination of system address, certificate, key, and Certificate Authority (CA). Ensure
+that the certificate is not expired, as well as that it is valid for the CA and the system address. Additionally, the
+system address must be accessible from the system console.
 
-Enabling HTTPS is a non-disruptive operation. You can enable HTTPS at any time without affecting the system's
-functionality.
+:::warning
 
-:::
-
-## Upload an SSL Certificate
-
-You can upload an SSL certificate in Palette VerteX by using the following steps.
+You can swap out the external endpoint certificate at any time without affecting the system functionality. However,
+updating the system address may require manual reconciliation on deployed clusters. Review the
+[prerequisites](#prerequisites) before you proceed to ensure you have all met all requirements.
 
 ## Prerequisites
 
@@ -37,7 +36,18 @@ You can upload an SSL certificate in Palette VerteX by using the following steps
   you did not specify a custom domain name, the certificate must be created for the Palette VerteX system console's IP
   address. You can also specify a load balancer's IP address if you are using a load balancer to access Palette VerteX.
 
-## Enablement
+- The new SSL certificate must also include the previous DNS name or IP address in the Subject Alternative Name (SAN)
+  field. This ensures that existing connections are not interrupted.
+
+- If you are changing the DNS endpoint, ensure both the new and old DNS endpoints are accessible for some time, ideally
+  sufficient time to ensure all existing Palette clusters have been updated to use the new endpoint and that no existing
+  connections are interrupted. Refer to the
+  [Reconcile System Address on Deployed Clusters](#reconcile-system-address-on-deployed-clusters) section for more
+  information on updating deployed clusters.
+
+### Enablement
+
+You can update your Palette system address and SSL certificates by using the following steps.
 
 1. Log in to the Palette VerteX system console.
 
@@ -73,3 +83,63 @@ You can validate that your certificate is uploaded correctly by using the follow
 
 Palette VerteX is now using your uploaded certificate to create a secure HTTPS connection with external clients. Users
 can now securely access the system console, gRPC endpoint, and API endpoint.
+
+## Reconcile System Address on Deployed Clusters
+
+Once you have updated your system address, the clusters that were deployed before the update will not be able to
+automatically reconnect to Palette if the old system address is no longer available. You will need to manually update
+the API endpoint on each cluster if this is the case. This enables the Palette agent to reconnect to the API at the
+newly configured system address.
+
+### Prerequisites
+
+- Palette VerteX access with a configured cloud account.
+
+- A cluster deployed prior to the system address update. Refer to the [Clusters](../../clusters/clusters.md) section for
+  further guidance.
+
+- `kubectl` installed. Use the Kubernetes [Install Tools](https://kubernetes.io/docs/tasks/tools/) page for further
+  guidance.
+
+### Enablement
+
+1. Log into Palette VerteX using the configured system address.
+
+2. Navigate to the left **Main Menu** and select **Clusters**. Palette displays your deployed clusters. The clusters
+   that have the **Unknown** status need to be manually updated.
+
+3. Select your cluster from the **Clusters** list. The cluster **Overview** tab displays.
+
+4. Download the kubeconfig file. This file allows you to connect to your deployed cluster. Check out the
+   [Kubeconfig](../../clusters/cluster-management/kubeconfig.md) page to learn more.
+5. Open a terminal window and set the environment variable `KUBECONFIG` to point to the file you downloaded.
+
+   ```shell
+   export KUBECONFIG=<path-to-downloaded-kubeconfig-file>
+   ```
+
+6. Execute the following command in your terminal to view the cluster namespaces. Make a note of the cluster namespace
+   that Palette has created. Its name follows the pattern **cluster-id**.
+
+   ```shell
+   kubectl get namespaces
+   ```
+
+7. Palette uses ConfigMaps to save its configuration and environment variables. Update the `apiEndpoint` value in the
+   `hubble-info` ConfigMap to use the newly configured system address.
+
+   ```shell
+   kubectl edit configmap hubble-info --namespace <cluster-id>
+   ```
+
+8. Save your changes and exit the editor.
+
+Repeat these steps for each cluster that has the **Unknown** status.
+
+### Validate
+
+1. Log into Palette VerteX using the configured system address.
+
+2. Navigate to the left **Main Menu** and select **Clusters**.
+
+3. Palette VerteX successfully displays the status of your clusters. None of your clusters has the **Unknown** status.