Skip to content

fix: accept legacy custom_resource_config_file as deprecated alias#2926

Merged
k8s-ci-robot merged 2 commits intokubernetes:mainfrom
nmn3m:fix/custom-resource-config-file-alias
Apr 17, 2026
Merged

fix: accept legacy custom_resource_config_file as deprecated alias#2926
k8s-ci-robot merged 2 commits intokubernetes:mainfrom
nmn3m:fix/custom-resource-config-file-alias

Conversation

@nmn3m
Copy link
Copy Markdown
Member

@nmn3m nmn3m commented Apr 15, 2026

What this PR does / why we need it:

The custom_resource_config_file config-file key was renamed to custom_resource_state_config_file in #2703 so it would match the CLI flag --custom-resource-state-config-file. Because YAML unmarshalling silently ignores unknown keys, users upgrading from v2.16 to v2.17+ saw their custom resource state config silently stop loading, with no error or warning.

This PR restores backward compatibility by honoring the legacy custom_resource_config_file key as a deprecated alias:

  • When only the legacy key is set, its value is copied into CustomResourceConfigFile so the CRS file loads as it did pre-v2.17.
  • When both keys are set, the canonical custom_resource_state_config_file takes precedence.
  • A deprecation warning is logged at startup whenever the legacy key is present, prompting users to migrate.
  • The CRS metrics guide (docs/metrics/extend/customresourcestate-metrics.md) now documents both keys and notes the alias is scheduled for removal.

Coverage was added in pkg/options/options_test.go for the unmarshal contract (alias populates the deprecated field; canonical wins when both are set).

How does this change affect the cardinality of KSM: does not change cardinality

Which issue(s) this PR fixes:
Fixes #2803

@k8s-ci-robot k8s-ci-robot added the needs-triage Indicates an issue or PR lacks a `triage/foo` label and requires one. label Apr 15, 2026
@k8s-ci-robot
Copy link
Copy Markdown
Contributor

This issue is currently awaiting triage.

If kube-state-metrics contributors determine this is a relevant issue, they will accept it by applying the triage/accepted label and provide further guidance.

The triage/accepted label can be added by org members by writing /triage accepted in a comment.

Details

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

@github-project-automation github-project-automation bot moved this to Needs Triage in SIG Instrumentation Apr 15, 2026
@k8s-ci-robot k8s-ci-robot added size/M Denotes a PR that changes 30-99 lines, ignoring generated files. cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. labels Apr 15, 2026
@nmn3m
Copy link
Copy Markdown
Member Author

nmn3m commented Apr 15, 2026

cc @bhope

@bhope
Copy link
Copy Markdown
Member

bhope commented Apr 15, 2026

Thanks for the PR!

/lgtm

@k8s-ci-robot k8s-ci-robot added the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Apr 15, 2026
Comment thread internal/wrapper.go Outdated
}

yaml.Unmarshal(configFile, opts)

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Can you add a todo comment to remove it in ksm 2.21?

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Can also be in the larger comment below just use the TODO as a keyword

Copy link
Copy Markdown

Copilot AI left a comment

Choose a reason for hiding this comment

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

Pull request overview

Restores backward compatibility for kube-state-metrics option YAML parsing by accepting the legacy custom_resource_config_file key (deprecated) as an alias for custom_resource_state_config_file, addressing silent CRS config breakage for upgrades from v2.16 → v2.17+.

Changes:

  • Add a deprecated custom_resource_config_file YAML key alias and log a deprecation notice when it’s used.
  • Copy legacy key into the canonical CRS config file option when the canonical key is unset.
  • Add unit tests for YAML unmarshal precedence and update CRS docs to mention the deprecated alias.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 3 comments.

File Description
pkg/options/options.go Adds a deprecated Options field to accept the legacy YAML key.
internal/wrapper.go Logs deprecation + applies aliasing during config merge at startup.
pkg/options/options_test.go Adds tests validating YAML unmarshal behavior for legacy vs canonical keys.
docs/metrics/extend/customresourcestate-metrics.md Documents canonical YAML key and legacy deprecated alias.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comment thread internal/wrapper.go Outdated
Comment on lines +86 to +87
if opts.CustomResourceConfigFileDeprecated != "" {
klog.InfoS("The 'custom_resource_config_file' config key is deprecated and will be removed in a future release; use 'custom_resource_state_config_file' instead")
Copy link

Copilot AI Apr 15, 2026

Choose a reason for hiding this comment

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

The deprecation notice is logged with InfoS, but the struct/docs describe it as a warning; consider using a warning-level log (e.g., klog.Warningf/WarningS) so it’s visible in typical production log filters. Also, gating on opts.CustomResourceConfigFileDeprecated != "" won’t warn (or alias) if the legacy key is explicitly present but empty; if the intent is “warn whenever the key is present”, detect key presence via Viper (cfgViper.IsSet("custom_resource_config_file")) or a YAML node-based unmarshal.

Suggested change
if opts.CustomResourceConfigFileDeprecated != "" {
klog.InfoS("The 'custom_resource_config_file' config key is deprecated and will be removed in a future release; use 'custom_resource_state_config_file' instead")
if cfgViper.IsSet("custom_resource_config_file") {
klog.Warning("The 'custom_resource_config_file' config key is deprecated and will be removed in a future release; use 'custom_resource_state_config_file' instead")

Copilot uses AI. Check for mistakes.
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

@nmn3m can you include this change as well? Thanks

Comment thread pkg/options/options.go
Comment on lines +58 to 59
CustomResourceConfigFileDeprecated string `yaml:"custom_resource_config_file"`
ContinueWithoutCustomResourceConfigFile bool `yaml:"continue_without_custom_resource_state_config_file"`
Copy link

Copilot AI Apr 15, 2026

Choose a reason for hiding this comment

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

This struct field formatting looks like it hasn’t been gofmt’d (extra spaces between name/type/tag). Please run gofmt so the struct remains consistently formatted with the rest of the file.

Copilot uses AI. Check for mistakes.
Comment thread internal/wrapper.go Outdated
Comment on lines +82 to +90
}

yaml.Unmarshal(configFile, opts)

if opts.CustomResourceConfigFileDeprecated != "" {
klog.InfoS("The 'custom_resource_config_file' config key is deprecated and will be removed in a future release; use 'custom_resource_state_config_file' instead")
if opts.CustomResourceConfigFile == "" {
opts.CustomResourceConfigFile = opts.CustomResourceConfigFileDeprecated
}
Copy link

Copilot AI Apr 15, 2026

Choose a reason for hiding this comment

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

os.ReadFile / yaml.Unmarshal errors are ignored here. If reading the file fails, configFile can be nil/empty and opts will silently remain unchanged; if YAML is invalid, unmarshalling failure will also be silent. Consider returning/exiting (honoring ContinueWithoutConfig) on read failure and handling the yaml.Unmarshal error explicitly so configuration issues aren’t silently ignored.

Suggested change
}
yaml.Unmarshal(configFile, opts)
if opts.CustomResourceConfigFileDeprecated != "" {
klog.InfoS("The 'custom_resource_config_file' config key is deprecated and will be removed in a future release; use 'custom_resource_state_config_file' instead")
if opts.CustomResourceConfigFile == "" {
opts.CustomResourceConfigFile = opts.CustomResourceConfigFileDeprecated
}
if !opts.ContinueWithoutConfig {
klog.FlushAndExit(klog.ExitFlushTimeout, 1)
}
} else {
if err := yaml.Unmarshal(configFile, opts); err != nil {
klog.ErrorS(err, "failed to unmarshal options configuration file", "file", file)
if !opts.ContinueWithoutConfig {
klog.FlushAndExit(klog.ExitFlushTimeout, 1)
}
} else if opts.CustomResourceConfigFileDeprecated != "" {
klog.InfoS("The 'custom_resource_config_file' config key is deprecated and will be removed in a future release; use 'custom_resource_state_config_file' instead")
if opts.CustomResourceConfigFile == "" {
opts.CustomResourceConfigFile = opts.CustomResourceConfigFileDeprecated
}
}

Copilot uses AI. Check for mistakes.
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Can you errcheck on the yaml. Unmarshal call? Thanks

@nmn3m nmn3m force-pushed the fix/custom-resource-config-file-alias branch from 73aec31 to 9f66f83 Compare April 16, 2026 10:31
@k8s-ci-robot k8s-ci-robot removed the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Apr 16, 2026
@nmn3m nmn3m requested a review from mrueg April 16, 2026 10:32
@bhope
Copy link
Copy Markdown
Member

bhope commented Apr 17, 2026

/lgtm

@k8s-ci-robot k8s-ci-robot added the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Apr 17, 2026
…ml.Unmarshal

Signed-off-by: Nour <nurmn3m@gmail.com>
@k8s-ci-robot k8s-ci-robot removed the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Apr 17, 2026
@mrueg
Copy link
Copy Markdown
Member

mrueg commented Apr 17, 2026

/lgtm

Thanks!

@k8s-ci-robot k8s-ci-robot added the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Apr 17, 2026
@k8s-ci-robot
Copy link
Copy Markdown
Contributor

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: bhope, mrueg, nmn3m

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Details Needs approval from an approver in each of these files:

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

@k8s-ci-robot k8s-ci-robot added the approved Indicates a PR has been approved by an approver from all required OWNERS files. label Apr 17, 2026
@k8s-ci-robot k8s-ci-robot merged commit 70c80b4 into kubernetes:main Apr 17, 2026
13 checks passed
@github-project-automation github-project-automation bot moved this from Needs Triage to Done in SIG Instrumentation Apr 17, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

approved Indicates a PR has been approved by an approver from all required OWNERS files. cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. lgtm "Looks good to me", indicates that a PR is ready to be merged. needs-triage Indicates an issue or PR lacks a `triage/foo` label and requires one. size/M Denotes a PR that changes 30-99 lines, ignoring generated files.

Projects

Development

Successfully merging this pull request may close these issues.

v2.17.0 breaks custom_resource_config_file config option

5 participants