doc: DOC-1178 (#4473) (#4478)

* doc: DOC-1178 * ci: auto-formatting prettier issues * docs: vale suggestions * doc: addressing comments * ci: auto-formatting prettier issues * doc: addressing final comment * doc: prettier formatting --------- Co-authored-by: benradstone <[email protected]> (cherry picked from commit edbee4d) Co-authored-by: Ben Radstone <[email protected]>
spectrocloud · Oct 25, 2024 · acbfab3 · acbfab3
1 parent 7123ada
commit acbfab3
Showing 1 changed file with 43 additions and 3 deletions.
diff --git a/docs/docs-content/profiles/profile-customization.md b/docs/docs-content/profiles/profile-customization.md
@@ -8,11 +8,11 @@ hide_table_of_contents: false
 tags: ["profiles", "cluster profiles", "app profiles", "system profiles"]
 ---
 
-Namespace labels and annotations are used to customize packs. The section below explains how to apply them in a pack
-YAML configuration.
-
 ## Pack Labels and Annotations
 
+Namespace labels and annotations are used to customize packs. This section explains how to apply them in a pack YAML
+configuration.
+
 You can specify namespace labels and annotations to add-on packs, and packs for Container Storage Interfaces (CSI) and
 Container Network Interfaces (CNI) drivers. These labels and annotations are applied to the namespace the pack is
 deployed to or to a specific namespace if specified. You can apply labels and annotations to the pack's YAML file.
@@ -46,3 +46,43 @@ pack:
     "monitoring": "monitoring.io/enable=true"
     "wordpress-storage": "storage.metrics.io/format=json"
 ```
+
+## Namespace Considerations
+
+When deploying Helm charts or other manifests to your cluster outside of the context of Palette, it is important you
+understand the expected behavior of how Palette manages namespaces and its resources.
+
+If a Palette-managed cluster profile is removed, Palette will destroy the associated namespace and all resources within
+that namespace. This includes resources that were not deployed by Palette.
+
+Here is an example scenario.
+
+A cluster has the following two packs and Helm chart installed in the `hello-universe` namespace:
+
+- Hello Universe (Palette-managed pack)
+- Kubecost (Palette-managed pack)
+- kubernetes-dashboard (helm chart added outside of Palette)
+
+Initial state of the namespace.
+
+```bash
+kubectl get pods --namespace hello-universe
+NAME                                                             READY   STATUS    RESTARTS   AGE
+hello-universe-deployment-5b4ffc8f97-r5nhb                       1/1     Running   0          3m50s
+cost-analyzer-cost-analyzer-59bf7cc86-tzdgs                      2/2     Running   0          7m47s
+cost-analyzer-cost-analyzer-kube-state-metrics-8b6dbd76b-scjbj   1/1     Running   0          7m47s
+cost-analyzer-cost-analyzer-prometheus-server-7b4c66596f-fb5f2   1/1     Running   0          7m47s
+kubernetes-dashboard-7b544877d5-j8r4x                            1/1     Running   0          10m13s
+dashboard-metrics-scraper-7bc864c59-n2j4m                        1/1     Running   0          10m13s
+```
+
+If you remove the Kubecost pack through Palette, all resources in the `hello-universe` namespace will be destroyed,
+including the namespace.
+
+```bash
+kubectl get pods --namespace hello-universe
+No resources found in hello-universe namespace.
+```
+
+We recommend using separate namespaces for all cluster profile layers, including resources manually deployed outside
+Palette. Separating resources into namespaces prevents unintended deletions.