Skip to content

docs: Correct chart name validation rules to match helm lint (DNS-1123 subdomain) #2161

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: Correct chart name validation rules to match helm lint (DNS-1123 subdomain) #2161

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
15 changes: 10 additions & 5 deletions docs/chart_best_practices/conventions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,25 +8,30 @@ This part of the Best Practices Guide explains general conventions.

## Chart Names

Chart names must follow DNS-1123 label conventions: only lowercase letters,
numbers, and dashes are allowed, names must start and end with a lowercase
letter or number, and names cannot exceed 63 characters:
Chart names are used as a prefix for the resources a chart creates, so they must

@promptless-for-oss promptless-for-oss Jun 30, 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.

PR #32278 makes helm lint call chartutil.ValidateMetadataName on the chart name. Its error message ("use lowercase letters, digits, hyphens, and dots only (e.g. my-chart, my.chart)") and added test cases (valid: my.chart; invalid: MyInvalidChart, my_chart, -my-chart, my-chart-, my chart, ../badchartname) confirmed that dots are now valid, which is why I changed the doc from "Names with dots ... invalid" to listing spaces and path separators as the invalid cases.

Source: helm/helm#32278

be valid Kubernetes resource names. Names must follow DNS-1123 subdomain
conventions: only lowercase letters, numbers, dashes, and dots are allowed;

@promptless-for-oss promptless-for-oss Jun 30, 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.

ValidateMetadataName in validate_name.go enforces the regex ^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$ with maxMetadataNameLen = 253. This is the source of the corrected "DNS-1123 subdomain" wording, the per-dot-segment start/end rule, and the 253-character limit replacing the previous 63-character claim.

Source: https://github.com/helm/helm/blob/main/pkg/chart/v2/util/validate_name.go

names must start and end with a lowercase letter or number; each dot-separated
segment must also start and end with a lowercase letter or number; and names
cannot exceed 253 characters:

Examples:

```
drupal
nginx-lego
aws-cluster-autoscaler
my.chart
```

Invalid chart names include:
- Names with uppercase letters (e.g., `MyChart`)
- Names with underscores (e.g., `my_chart`)
- Names with dots (e.g., `my.chart`)
- Names with spaces (e.g., `my chart`)
- Names starting with a dash (e.g., `-mychart`)
- Names ending with a dash (e.g., `mychart-`)
- Names longer than 63 characters
- Names containing path separators (e.g., `../mychart`)
- Names longer than 253 characters

The `helm lint` command validates chart names against these rules.

Expand Down
15 changes: 10 additions & 5 deletions versioned_docs/version-3/chart_best_practices/conventions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,25 +8,30 @@ This part of the Best Practices Guide explains general conventions.

## Chart Names

Chart names must follow DNS-1123 label conventions: only lowercase letters,
numbers, and dashes are allowed, names must start and end with a lowercase
letter or number, and names cannot exceed 63 characters:
Chart names are used as a prefix for the resources a chart creates, so they must
be valid Kubernetes resource names. Names must follow DNS-1123 subdomain
conventions: only lowercase letters, numbers, dashes, and dots are allowed;
names must start and end with a lowercase letter or number; each dot-separated
segment must also start and end with a lowercase letter or number; and names
cannot exceed 253 characters:

Examples:

```
drupal
nginx-lego
aws-cluster-autoscaler
my.chart
```

Invalid chart names include:
- Names with uppercase letters (e.g., `MyChart`)
- Names with underscores (e.g., `my_chart`)
- Names with dots (e.g., `my.chart`)
- Names with spaces (e.g., `my chart`)
- Names starting with a dash (e.g., `-mychart`)
- Names ending with a dash (e.g., `mychart-`)
- Names longer than 63 characters
- Names containing path separators (e.g., `../mychart`)
- Names longer than 253 characters

The `helm lint` command validates chart names against these rules.

Expand Down
Loading