📖 Docs/namespace renaming known limitation

docs/CRANE_COMPATIBILITY_MATRIX.md

@@ -39,7 +39,8 @@ Cluster_Scope_Conditional -.->|Migrated if Related & Permitted| Target
 ### 3.1 Namespace-Scoped Resources (Fully Supported)
 These resources are the core of any migration and are moved automatically.
 * **Workloads:** Deployment, DeploymentConfig, StatefulSet, DaemonSet, Job, CronJob.
-* **Networking:** Service, Route, Ingress, Endpoints.
+* **Networking:** Service, Route, Ingress, Endpoints, NetworkPolicy.
+  > **Warning — Namespace renaming:** If the namespace is renamed during migration, NetworkPolicy `namespaceSelector` entries that match the old namespace by label (e.g., `kubernetes.io/metadata.name: old-ns`) are not updated automatically. Manually update them before applying.
 * **Config & Secrets:** ConfigMap, Secret, ServiceAccount.
 * **Storage:** PersistentVolumeClaim (PVC).
 
@@ -48,6 +49,7 @@ These resources are migrated **only if they are linked to the namespace workload
 
 * **Definitions (CRDs):** Migrated if the namespace contains Custom Resources (CRs) that depend on these definitions.
 * **Global Security (ClusterRole/Binding):** Migrated if specifically referenced by a ServiceAccount within the migrating namespace.
+  > **Warning — Namespace renaming:** If the namespace is renamed during migration, ClusterRoleBinding `subjects` that reference the old namespace name are not updated automatically. Manually update them before applying.
 * **Security Context Constraints (SCCs):** Migrated if the application requires specific localized SCCs to run (common in OpenShift environments).
 * **Quota & Limits:** ResourceQuotas and LimitRanges are migrated if they are defined specifically for the source namespace.
 
@@ -71,5 +73,6 @@ For "Conditionally Supported" resources to migrate successfully, the following m
 * [ ] **Storage Mapping:** Confirm that destination StorageClasses are ready to receive moved PVCs.
 * [ ] **Operator Readiness:** All required Operators are installed via OperatorHub on the target cluster.
 * [ ] **CRD Check:** Verify if any global CRDs need to be manually applied to the target to avoid "orphan" resources.
+* [ ] **Namespace Renaming:** If renaming the namespace, manually update any ClusterRoleBinding subjects and NetworkPolicy namespaceSelector entries matching the old namespace by label before applying.
 
 ---

docs/commands/transform.md

@@ -262,6 +262,12 @@ crane transform --force
 
 **Important**: Custom stages (not ending with `Plugin`) are protected from accidental overwrites. You must use `--force` to regenerate them.
 
+> **Warning — Namespace renaming:** If you rename the namespace — whether by editing resource files directly or by using a `namespace:` directive in `kustomization.yaml` — Crane does not automatically update references to the old namespace name in:
+> - **ClusterRoleBinding `subjects`** — entries that reference a ServiceAccount in the old namespace will still point to the old name.
+> - **NetworkPolicy `namespaceSelector`** — entries matching the old namespace by label (e.g., `kubernetes.io/metadata.name: old-ns`) will not be updated automatically.
+>
+> Both will silently break after migration. Manually update these resources as well.
+
 **Best Practice**: Always add custom stages as the **last stage** in your pipeline. This ensures that:
 - The `input/` directory contains the most up-to-date output from all previous stages
 - You're editing the final state of resources after all plugin transformations

docs/kustomize-multistage.md

@@ -479,6 +479,8 @@ Stages don't have to correspond to a plugin. If a stage directory name doesn't m
 
 **Use case**: Manual transformation stages where you want to hand-edit resources.
 
+> **Warning — Namespace renaming:** If you manually rename the namespace in resource files within a custom stage (for example, changing `namespace: old-ns` to `namespace: new-ns`), Crane does not automatically update **ClusterRoleBinding subjects** referencing the old namespace name, or **NetworkPolicy `namespaceSelector`** entries matching the old namespace by label (e.g., `kubernetes.io/metadata.name: old-ns`). These will silently break after migration. Manually update them as well.
+
 ### Example
 
 ```bash

docs/multistage-pipeline.md

@@ -470,6 +470,8 @@ Stages don't have to correspond to a plugin. If a stage directory name doesn't m
 
 **Use case**: Manual transformation stages where you want to hand-edit resources.
 
+> **Warning — Namespace renaming:** If you manually rename the namespace in resource files within a custom stage (for example, changing `namespace: old-ns` to `namespace: new-ns`), Crane does not automatically update **ClusterRoleBinding subjects** referencing the old namespace name, or **NetworkPolicy `namespaceSelector`** entries matching the old namespace by label (e.g., `kubernetes.io/metadata.name: old-ns`). These will silently break after migration. Manually update them as well.
+
 ### Example
 
 ```bash

docs/plugins.md

@@ -75,6 +75,8 @@ crane transform --skip-plugins OpenshiftPlugin
 
 Pass configuration to plugins:
 
+> **Warning — Namespace renaming:** If you use `new-namespace` (or any namespace-rename flag) to rename the namespace during migration, Crane does not automatically update **ClusterRoleBinding subjects** referencing the old namespace name, or **NetworkPolicy `namespaceSelector`** entries matching the old namespace by label (e.g., `kubernetes.io/metadata.name: old-ns`). These will silently break after migration. Manually update them before applying.
+
 ```bash
 crane transform --optional-flags '{"new-namespace": "production"}'
 ```

docs/pre-apply-validation-guide.md

@@ -89,6 +89,8 @@ kubectl get storageclass <name>
 
 If everything was exported together, references are usually satisfied; gaps often come from excluded resources or cluster-only dependencies.
 
+> **Warning — Namespace renaming:** If you renamed a namespace during migration, Crane does not automatically update **ClusterRoleBinding subjects** referencing the old namespace name, or **NetworkPolicy `namespaceSelector`** entries matching the old namespace by label (e.g., `kubernetes.io/metadata.name: old-ns`). These will silently point to a namespace that no longer exists. Manually update them before applying.
+
 ---
 
 ## 5. Namespaces

docs/resource-compatibility.md

@@ -39,7 +39,8 @@ Cluster_Scope_Conditional -.->|Migrated if Related & Permitted| Target
 ### 3.1 Namespace-Scoped Resources (Fully Supported)
 These resources are the core of any migration and are moved automatically.
 * **Workloads:** Deployment, DeploymentConfig, StatefulSet, DaemonSet, Job, CronJob.
-* **Networking:** Service, Route, Ingress, Endpoints.
+* **Networking:** Service, Route, Ingress, Endpoints, NetworkPolicy.
+  > **Warning — Namespace renaming:** If the namespace is renamed during migration, NetworkPolicy `namespaceSelector` entries that match the old namespace by label (e.g., `kubernetes.io/metadata.name: old-ns`) are not updated automatically. Manually update them before applying.
 * **Config & Secrets:** ConfigMap, Secret, ServiceAccount.
 * **Storage:** PersistentVolumeClaim (PVC).
 
@@ -48,6 +49,7 @@ These resources are migrated **only if they are linked to the namespace workload
 
 * **Definitions (CRDs):** Migrated if the namespace contains Custom Resources (CRs) that depend on these definitions.
 * **Global Security (ClusterRole/Binding):** Migrated if specifically referenced by a ServiceAccount within the migrating namespace.
+  > **Warning — Namespace renaming:** If the namespace is renamed during migration, ClusterRoleBinding `subjects` that reference the old namespace name are not updated automatically. Manually update them before applying.
 * **Security Context Constraints (SCCs):** Migrated if the application requires specific localized SCCs to run (common in OpenShift environments).
 * **Quota & Limits:** ResourceQuotas and LimitRanges are migrated if they are defined specifically for the source namespace.
 
@@ -71,5 +73,6 @@ For "Conditionally Supported" resources to migrate successfully, the following m
 * [ ] **Storage Mapping:** Confirm that destination StorageClasses are ready to receive moved PVCs.
 * [ ] **Operator Readiness:** All required Operators are installed via OperatorHub on the target cluster.
 * [ ] **CRD Check:** Verify if any global CRDs need to be manually applied to the target to avoid "orphan" resources.
+* [ ] **Namespace Renaming:** If renaming the namespace, manually update any ClusterRoleBinding subjects and NetworkPolicy namespaceSelector entries matching the old namespace by label before applying.
 
 ---

docs/stateless-migration-quickstart.md

@@ -293,12 +293,14 @@ What you should see (example):
 
 After validation passes and you are satisfied with the cleaned manifests, apply them to the target cluster:
 
+> **Warning — Namespace renaming:** If you renamed the namespace during migration, Crane does not automatically update **ClusterRoleBinding subjects** referencing the old namespace name, or **NetworkPolicy `namespaceSelector`** entries matching the old namespace by label (e.g., `kubernetes.io/metadata.name: old-ns`). These will silently point to a namespace that no longer exists. Manually update them before applying.
+
+Make sure the target namespace already exists before applying manifests, so namespace-scoped resources do not fail during apply.
+
 ```bash
 kubectl --context "${TARGET_CONTEXT}" apply -f output/output.yaml
 ```
 
-Make sure the target namespace already exists before applying manifests, so namespace-scoped resources do not fail during apply.
-
 ## Troubleshooting
 
 ### Export directory already exists