Skip to content

docs: Clarify how alias interacts with dependency conditions and tags #2183

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

Draft
promptless-for-oss wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

docs: Clarify how alias interacts with dependency conditions and tags #2183

Show file tree
Hide file tree
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
22 changes: 22 additions & 0 deletions docs/topics/charts.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -339,6 +339,25 @@ new-subchart-2
The manual way of achieving this is by copy/pasting the same chart in the
`charts/` directory multiple times with different names.

When a dependency uses an `alias`, the alias becomes the dependency's name for

@promptless-for-oss promptless-for-oss Jul 18, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Verifies that an alias becomes the dependency's name for condition evaluation. In processDependencyEnabled, if req.Alias != "" { req.Name = req.Alias } (lines 165-166) runs before processDependencyConditions (defined line 40), which resolves cvals.PathValue(cpath + c) (line 47) against the user-defined condition path. Confirmed by testdata/subpop/Chart.yaml where the dependency name=subchart2, alias=subchart2alias uses condition: subchart2alias.enabled.

Source: https://github.com/helm/helm/blob/main/pkg/chart/v2/util/dependencies.go#L165-L166

the purposes of `condition` evaluation. The `condition` path and any enabling
values in the top parent's values must therefore be keyed by the alias name
rather than the original chart name. For example, with the `new-subchart-1`
alias above you would use `condition: new-subchart-1.enabled` in `Chart.yaml`
and set the value in the top parent's values:

```yaml
# parentchart/values.yaml
new-subchart-1:
enabled: true
```

For a chart reached through an aliased dependency chain, the values path

@promptless-for-oss promptless-for-oss Jul 18, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Verifies that the values path accumulates the alias name at each level of an aliased dependency chain. Recursion builds subpath := path + t.Metadata.Name + "." (line 205); getAliasDependency sets the copied chart's out.Metadata.Name = dep.Alias, so the metadata name equals the alias, producing paths like outer-alias.inner-alias.enabled.

Source: https://github.com/helm/helm/blob/main/pkg/chart/v2/util/dependencies.go#L205

accumulates the alias name at each level (for example,
`outer-alias.inner-alias.enabled`). Tags are not affected by an alias: they are

@promptless-for-oss promptless-for-oss Jul 18, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Verifies that tags are not affected by an alias. processDependencyTags (defined line 64) reads the "tags" values table via cvals.Table("tags") (line 69) and matches each dependency's r.Tags labels against vt[k]; the dependency name (r.Name) is used only in a non-bool warning log message, never for tag matching.

Source: https://github.com/helm/helm/blob/main/pkg/chart/v2/util/dependencies.go#L64-L69

matched by the labels listed in the dependency's `tags` field, not by the chart
or alias name.

#### Tags and Condition fields in dependencies

In addition to the other fields above, each requirements entry may contain the
Expand Down Expand Up @@ -414,6 +433,9 @@ helm install --set tags.front-end=true --set subchart2.enabled=false
- Tags and conditions values must be set in the top parent's values.
- The `tags:` key in values must be a top level key. Globals and nested `tags:`
tables are not currently supported.
- When a dependency uses an `alias`, its `condition` path is keyed by the alias

@promptless-for-oss promptless-for-oss Jul 18, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Verifies the Tags and Condition Resolution bullet: an aliased dependency's condition path is keyed by the alias (req.Name = req.Alias at lines 165-166 before processDependencyConditions), and tags are matched by r.Tags labels against the "tags" table (processDependencyTags, lines 64-69), not by chart/alias name.

Source: https://github.com/helm/helm/blob/main/pkg/chart/v2/util/dependencies.go#L165-L166

name rather than the original chart name. Tags are not affected by aliasing;
they are matched by the labels in the dependency's `tags` field.

#### Importing Child Values via dependencies

Expand Down
22 changes: 22 additions & 0 deletions versioned_docs/version-3/topics/charts.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -335,6 +335,25 @@ new-subchart-2
The manual way of achieving this is by copy/pasting the same chart in the
`charts/` directory multiple times with different names.

When a dependency uses an `alias`, the alias becomes the dependency's name for

@promptless-for-oss promptless-for-oss Jul 18, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Mirror of docs/topics/charts.mdx alias-condition note. Verifies alias becomes the dependency's name for condition evaluation: if req.Alias != "" { req.Name = req.Alias } (lines 165-166) runs before processDependencyConditions (line 40); condition path resolved via cvals.PathValue(cpath + c) (line 47). Confirmed by testdata/subpop/Chart.yaml (name=subchart2, alias=subchart2alias, condition: subchart2alias.enabled).

Source: https://github.com/helm/helm/blob/main/pkg/chart/v2/util/dependencies.go#L165-L166

the purposes of `condition` evaluation. The `condition` path and any enabling
values in the top parent's values must therefore be keyed by the alias name
rather than the original chart name. For example, with the `new-subchart-1`
alias above you would use `condition: new-subchart-1.enabled` in `Chart.yaml`
and set the value in the top parent's values:

```yaml
# parentchart/values.yaml
new-subchart-1:
enabled: true
```

For a chart reached through an aliased dependency chain, the values path

@promptless-for-oss promptless-for-oss Jul 18, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Mirror of docs/topics/charts.mdx. Verifies values path accumulates the alias at each level: recursion builds subpath := path + t.Metadata.Name + "." (line 205) and getAliasDependency sets out.Metadata.Name = dep.Alias. Also verifies tags unaffected by alias via processDependencyTags reading cvals.Table("tags").

Source: https://github.com/helm/helm/blob/main/pkg/chart/v2/util/dependencies.go#L205

accumulates the alias name at each level (for example,
`outer-alias.inner-alias.enabled`). Tags are not affected by an alias: they are
matched by the labels listed in the dependency's `tags` field, not by the chart
or alias name.

#### Tags and Condition fields in dependencies

In addition to the other fields above, each requirements entry may contain the
Expand Down Expand Up @@ -410,6 +429,9 @@ helm install --set tags.front-end=true --set subchart2.enabled=false
- Tags and conditions values must be set in the top parent's values.
- The `tags:` key in values must be a top level key. Globals and nested `tags:`
tables are not currently supported.
- When a dependency uses an `alias`, its `condition` path is keyed by the alias

@promptless-for-oss promptless-for-oss Jul 18, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Mirror of docs/topics/charts.mdx Tags and Condition Resolution bullet. Verifies aliased dependency's condition path is keyed by the alias (req.Name = req.Alias, lines 165-166, before processDependencyConditions) and tags are matched by r.Tags labels against the "tags" table (processDependencyTags, lines 64-69), not by chart/alias name.

Source: https://github.com/helm/helm/blob/main/pkg/chart/v2/util/dependencies.go#L165-L166

name rather than the original chart name. Tags are not affected by aliasing;
they are matched by the labels in the dependency's `tags` field.

#### Importing Child Values via dependencies

Expand Down
Loading