docs: Missing docs on ownership annotations#32199
Open
arnavnagzirkar wants to merge 2 commits into
Open
Conversation
Add a RESOURCE OWNERSHIP section to the helm install and helm upgrade command descriptions explaining the meta.helm.sh/release-name and meta.helm.sh/release-namespace annotations (and app.kubernetes.io/managed-by label) that Helm uses to track resource ownership, and document the --take-ownership flag for adopting pre-existing resources. Fixes helm#12869 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: Arnav Nagzirkar <113314200+arnavnagzirkar@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Note
Copilot was unable to run its full agentic suite in this review.
Adds CLI help text explaining Helm’s resource ownership metadata and how --take-ownership affects install/upgrade behavior.
Changes:
- Documented the label/annotations Helm uses to track resource ownership in
helm installhelp output. - Documented upgrade-time ownership checks and the purpose of
--take-ownershipinhelm upgradehelp output.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| pkg/cmd/upgrade.go | Adds help text describing ownership metadata and --take-ownership during upgrades. |
| pkg/cmd/install.go | Adds help text describing ownership metadata and adopting existing resources with --take-ownership. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+92
to
+93
| During an upgrade, if a resource exists in the cluster without these annotations | ||
| (or with annotations pointing to a different release), Helm will return an error. |
Comment on lines
+140
to
+141
| These are used to track ownership. If a resource already exists in the cluster | ||
| without these annotations, Helm will refuse to install and return an error. To |
|
Promptless prepared a documentation update related to this change. Triggered by PR #32199 Added a troubleshooting FAQ entry explaining resource ownership errors and how to resolve them using |
The refusal condition referred to 'these annotations', but Helm tracks ownership with both the app.kubernetes.io/managed-by label and the meta.helm.sh release-name/release-namespace annotations. checkOwnership also errors when that metadata points to a different release or namespace, not only when it is absent. Reword both help texts to say 'this metadata' and to cover the mismatched release or namespace case. Signed-off-by: Arnav Nagzirkar <113314200+arnavnagzirkar@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
The
meta.helm.sh/release-nameandmeta.helm.sh/release-namespaceannotations (along with theapp.kubernetes.io/managed-by=Helmlabel) are used by Helm to track ownership of Kubernetes resources.Root cause
The
meta.helm.sh/release-nameandmeta.helm.sh/release-namespaceannotations(along with the
app.kubernetes.io/managed-by=Helmlabel) are used by Helm to trackownership of Kubernetes resources. These are defined in
pkg/action/validate.goashelmReleaseNameAnnotationandhelmReleaseNamespaceAnnotation. However, neither thehelm installnorhelm upgradecommand help text explained these annotations or the--take-ownershipflag that lets users adopt pre-existing resources. Users had noin-tool documentation to discover or understand the ownership mechanism.
What changed
Added a "RESOURCE OWNERSHIP" section to the
installDescconstant inpkg/cmd/install.go(newInstallCmd) and theupgradeDescconstant inpkg/cmd/upgrade.go(newUpgradeCmd). Each section lists the three ownershipmetadata items Helm applies:
app.kubernetes.io/managed-by=Helm(label)meta.helm.sh/release-name=<release-name>(annotation)meta.helm.sh/release-namespace=<release-namespace>(annotation)And explains how the
--take-ownershipflag allows adopting resources that alreadyexist in the cluster without this ownership metadata.
Issue
Fixes #12869
Issue: #12869
Diffstat
Testing
Ran the relevant tests and linter for the changed files while developing.
Kept the change minimal and focused on this one issue.
AI assistance
I used GitHub Copilot to help write parts of this change. I've reviewed and tested it myself, I understand what it does, and I'll follow up on any review feedback.