From 40367378498f02ce8203ec23897d27803283fe7b Mon Sep 17 00:00:00 2001 From: Arnav Nagzirkar <113314200+arnavnagzirkar@users.noreply.github.com> Date: Mon, 8 Jun 2026 21:04:49 -0700 Subject: [PATCH 1/2] docs: document ownership annotations in install and upgrade help text 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 #12869 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: Arnav Nagzirkar <113314200+arnavnagzirkar@users.noreply.github.com> --- pkg/cmd/install.go | 14 ++++++++++++++ pkg/cmd/upgrade.go | 13 +++++++++++++ 2 files changed, 27 insertions(+) diff --git a/pkg/cmd/install.go b/pkg/cmd/install.go index 67e2a9fab..8c56f7ac2 100644 --- a/pkg/cmd/install.go +++ b/pkg/cmd/install.go @@ -127,6 +127,20 @@ supply a version number with the '--version' flag. To see the list of chart repositories, use 'helm repo list'. To search for charts in a repository, use 'helm search'. + +RESOURCE OWNERSHIP + +When Helm installs a chart, it adds the following metadata to every Kubernetes +resource it creates: + + - Label: app.kubernetes.io/managed-by=Helm + - Annotation: meta.helm.sh/release-name= + - Annotation: meta.helm.sh/release-namespace= + +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 +adopt pre-existing resources into the release, use '--take-ownership'. Helm will +then add the ownership metadata and manage those resources going forward. ` func newInstallCmd(cfg *action.Configuration, out io.Writer) *cobra.Command { diff --git a/pkg/cmd/upgrade.go b/pkg/cmd/upgrade.go index 43e19ab22..e41bcddaa 100644 --- a/pkg/cmd/upgrade.go +++ b/pkg/cmd/upgrade.go @@ -80,6 +80,19 @@ or '--set' flags. Priority is given to new values. The --dry-run flag will output all generated chart manifests, including Secrets which can contain sensitive values. To hide Kubernetes Secrets use the --hide-secret flag. Please carefully consider how and when these flags are used. + +RESOURCE OWNERSHIP + +Helm tracks ownership of Kubernetes resources using the following metadata: + + - Label: app.kubernetes.io/managed-by=Helm + - Annotation: meta.helm.sh/release-name= + - Annotation: meta.helm.sh/release-namespace= + +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. +To take ownership of such resources and have Helm manage them going forward, use +'--take-ownership'. ` func newUpgradeCmd(cfg *action.Configuration, out io.Writer) *cobra.Command { From ceb6bfd5165812ec2614ec9b1976cee846f401d1 Mon Sep 17 00:00:00 2001 From: Arnav Nagzirkar <113314200+arnavnagzirkar@users.noreply.github.com> Date: Mon, 8 Jun 2026 21:43:05 -0700 Subject: [PATCH 2/2] docs: clarify ownership metadata wording in install and upgrade help 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> --- pkg/cmd/install.go | 7 ++++--- pkg/cmd/upgrade.go | 8 ++++---- 2 files changed, 8 insertions(+), 7 deletions(-) diff --git a/pkg/cmd/install.go b/pkg/cmd/install.go index 8c56f7ac2..d6c43e05a 100644 --- a/pkg/cmd/install.go +++ b/pkg/cmd/install.go @@ -138,9 +138,10 @@ resource it creates: - Annotation: meta.helm.sh/release-namespace= 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 -adopt pre-existing resources into the release, use '--take-ownership'. Helm will -then add the ownership metadata and manage those resources going forward. +without this metadata, or with metadata pointing to a different release or +namespace, Helm will refuse to install and return an error. To adopt such +pre-existing resources into the release, use '--take-ownership'. Helm will then +add the ownership metadata and manage those resources going forward. ` func newInstallCmd(cfg *action.Configuration, out io.Writer) *cobra.Command { diff --git a/pkg/cmd/upgrade.go b/pkg/cmd/upgrade.go index e41bcddaa..113c1e703 100644 --- a/pkg/cmd/upgrade.go +++ b/pkg/cmd/upgrade.go @@ -89,10 +89,10 @@ Helm tracks ownership of Kubernetes resources using the following metadata: - Annotation: meta.helm.sh/release-name= - Annotation: meta.helm.sh/release-namespace= -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. -To take ownership of such resources and have Helm manage them going forward, use -'--take-ownership'. +During an upgrade, if a resource exists in the cluster without this metadata +(or with metadata pointing to a different release or namespace), Helm will +return an error. To take ownership of such resources and have Helm manage them +going forward, use '--take-ownership'. ` func newUpgradeCmd(cfg *action.Configuration, out io.Writer) *cobra.Command {