diff --git a/docs/CRANE_COMPATIBILITY_MATRIX.md b/docs/CRANE_COMPATIBILITY_MATRIX.md index e9933574..26028955 100644 --- a/docs/CRANE_COMPATIBILITY_MATRIX.md +++ b/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. --- diff --git a/docs/commands/transform.md b/docs/commands/transform.md index 990807f8..4a3dfa18 100644 --- a/docs/commands/transform.md +++ b/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 diff --git a/docs/kustomize-multistage.md b/docs/kustomize-multistage.md index 68656e28..5184308e 100644 --- a/docs/kustomize-multistage.md +++ b/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 diff --git a/docs/multistage-pipeline.md b/docs/multistage-pipeline.md index 2f767d4c..775fead8 100644 --- a/docs/multistage-pipeline.md +++ b/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 diff --git a/docs/plugins.md b/docs/plugins.md index db8d4c43..d4455082 100644 --- a/docs/plugins.md +++ b/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"}' ``` diff --git a/docs/pre-apply-validation-guide.md b/docs/pre-apply-validation-guide.md index 3cf39ecf..4cad766c 100644 --- a/docs/pre-apply-validation-guide.md +++ b/docs/pre-apply-validation-guide.md @@ -89,6 +89,8 @@ kubectl get storageclass 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 diff --git a/docs/resource-compatibility.md b/docs/resource-compatibility.md index 78dbf06e..1f6f3fd5 100644 --- a/docs/resource-compatibility.md +++ b/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. --- diff --git a/docs/stateless-migration-quickstart.md b/docs/stateless-migration-quickstart.md index 86d2d272..7d9a66dc 100644 --- a/docs/stateless-migration-quickstart.md +++ b/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