Skip to content

docs: add migration note for default-httplistenerpolicy Helm ownership conflict #751

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
kavix wants to merge 1 commit into
base: main
Choose a base branch
from
+33 −0
Open

docs: add migration note for default-httplistenerpolicy Helm ownership conflict #751

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 33 additions & 0 deletions docs/platform-engineer-guide/upgrades.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -74,6 +74,39 @@ kubectl delete crd <crd-name>

Deleting a CRD also deletes every custom resource of that type, cluster-wide.

## Known Migration Issues

### `default-httplistenerpolicy` Ownership Conflict (Data Plane)

:::warning Applies to users who followed older README setup instructions
If you applied the Data Plane setup steps from an older version of the README, you may have a `HTTPListenerPolicy` resource named `default-httplistenerpolicy` that was created **outside of Helm**. Starting from [openchoreo#4080](https://github.com/openchoreo/openchoreo/pull/4080), this resource is now shipped as part of the `openchoreo-data-plane` Helm chart. Running `helm upgrade` without any preparation will fail with:

```
Error: UPGRADE FAILED: rendered manifests contain a resource that already exists.
Unable to continue with update: HTTPListenerPolicy "default-httplistenerpolicy" in namespace "..." exists and cannot be imported into the current release.
```

To resolve this, transfer ownership of the resource to Helm **before** running `helm upgrade` by applying the following annotation and label:

```bash
# Replace <release-name> and <release-namespace> with your actual values
kubectl annotate httplistenerpolicy default-httplistenerpolicy \
meta.helm.sh/release-name=<release-name> \
meta.helm.sh/release-namespace=<release-namespace> \
--overwrite

kubectl label httplistenerpolicy default-httplistenerpolicy \
app.kubernetes.io/managed-by=Helm \
--overwrite
Comment on lines +89 to +100

@coderabbitai coderabbitai Bot Jul 8, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

Add an explicit namespace to the ownership-transfer commands.

Right now kubectl annotate / kubectl label will run against whatever namespace is active in the current context, which makes these instructions easy to apply to the wrong object. Please include the Data Plane/release namespace in both commands so the Helm ownership metadata is written to the existing default-httplistenerpolicy resource.

Suggested fix 
-kubectl annotate httplistenerpolicy default-httplistenerpolicy \
+kubectl annotate -n <release-namespace> httplistenerpolicy default-httplistenerpolicy \
   meta.helm.sh/release-name=<release-name> \
   meta.helm.sh/release-namespace=<release-namespace> \
   --overwrite

-kubectl label httplistenerpolicy default-httplistenerpolicy \
+kubectl label -n <release-namespace> httplistenerpolicy default-httplistenerpolicy \
   app.kubernetes.io/managed-by=Helm \
   --overwrite
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
To resolve this, transfer ownership of the resource to Helm **before** running `helm upgrade` by applying the following annotation and label:
```bash
# Replace <release-name> and <release-namespace> with your actual values
kubectl annotate httplistenerpolicy default-httplistenerpolicy \
meta.helm.sh/release-name=<release-name> \
meta.helm.sh/release-namespace=<release-namespace> \
--overwrite
kubectl label httplistenerpolicy default-httplistenerpolicy \
app.kubernetes.io/managed-by=Helm \
--overwrite
To resolve this, transfer ownership of the resource to Helm **before** running `helm upgrade` by applying the following annotation and label:
🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/platform-engineer-guide/upgrades.mdx` around lines 89 - 100, The
ownership-transfer commands in the upgrades guide omit the target namespace, so
they can annotate/label the wrong httplistenerpolicy. Update the kubectl
annotate and kubectl label examples to include the Data Plane/release namespace
explicitly, while keeping the existing resource name default-httplistenerpolicy
and Helm metadata keys in the same upgrade instructions section.

```

:::tip Finding your release name and namespace
Run `helm list -A | grep openchoreo-data-plane` to find the release name and namespace for your Data Plane installation.
:::

Once the annotation and label are applied, proceed with the normal upgrade steps below.
:::

## Upgrade Process

### Single Cluster Deployment
Expand Down