Label management of VPA resources

[mrballcb]

Is your feature request related to a problem? Please describe.
When VPAs are created, the only labels on them are hardcoded labels (defined in goldilocks at build time). In order to see what app this VPA belongs to, we have to parse the spec section to extract the deployment/ss/ds, then go look it up and get the labels from there, or apply institutional knowledge to know where or what to look at.

Describe the solution you'd like
I'd like to have the VPAs have the (mostly) same labels that the resources have. I'd like options to enable copy-through of labels and to control which labels get copied. Ideally it would be cli options. I expect it to automatically exclude "owner" type labels so that the respective tools don't think they own these resources. Examples are app.kubernetes.io/managed-by or helm.sh/*, but I'm sure there are lots more.

Describe alternatives you've considered

• A python script that runs at $interval to do the above parse/extract/label process. In my local tests, goldilocks does not see VPA label changes as a change marker, so it does not want to revert the additional labels. EDIT: goldilocks eventually reconciles the VPA and removes any added labels.

Additional context
I would happily accept any suggestions of preferred approach that might differ from my description. Locally I've already set Claude loose on putting something together. It has 3 new cli options (a boolean enable with a modest default, an explicit include list, and an explicit exclude list). It has a full suite of tests and documentation. It compiles and passes tests locally, but I have not tested it in a real cluster yet. I'm going to poke at it a bit more before creating a PR. (I have to make sure I don't run afoul of my own employer's rules with regard to open source contributions as well. I have not submitted the required contributors information yet.)

Generic questions:

1. Does Fairwinds have any AI specific advisement or limitations on use?
2. Does this project have any AI specific advisement or limitations on use?

[mrballcb]

Our specific use case: we have team owner labels and backstage refs on applications that we would like to persist through to the VPA to simplify notification methods for drawing attention to changes. It also eases the cognitive load for humans observing these labels.

[mrballcb]

My local IMPLEMENTATION_PLAN follows. Please let me know if it seems reasonable:

==========

Label Propagation Implementation Summary

Overview

Implemented label propagation from Kubernetes controller resources (Deployment, StatefulSet, DaemonSet) to their corresponding VPA (VerticalPodAutoscaler) resources. This allows users to maintain consistent labeling across resources for monitoring, cost allocation, and organizational purposes.

Implementation Date

February 26, 2026

Files Modified

1. Core Utilities (pkg/utils/utils.go)

Added:

• DefaultExcludedLabelPatterns - constant defining default label patterns to exclude
• FilterLabelsForPropagation() - main filtering function with include/exclude logic
• shouldPropagateLabel() - pattern matching for exact and prefix label exclusions
• MergeLabels() - merge multiple label maps with precedence

Key Logic:

1. If includeList is provided: start with ONLY those specific labels (override mode)
2. Otherwise: start with all controller labels (default mode)
3. Apply exclusions:
   • If includeList was NOT provided: apply default exclusion patterns
   • Always apply additional exclusions from additionalExclusions parameter
4. Merge propagated labels with VPALabels (VPALabels always take precedence)

2. Unit Tests (pkg/utils/utils_test.go)

Added 24 test cases:

• 11 tests for FilterLabelsForPropagation()
• 7 tests for shouldPropagateLabel()
• 6 tests for MergeLabels()

All tests pass ✅

3. VPA Reconciler (pkg/vpa/vpa.go)

Modified Reconciler struct:

• Added PropagateLabels bool
• Added FilterIncludeLabels []string
• Added FilterExcludeLabels []string

Modified reconcileControllerAndVPA():

• Extract controller labels when PropagateLabels is enabled
• Pass controller labels to getVPAObject()

Modified getVPAObject() signature:

• Added controllerLabels map[string]string parameter
• Integrated label filtering and merging logic

4. Integration Tests (pkg/vpa/vpa_test.go)

Added 5 comprehensive integration tests:

• Test_LabelPropagation_DefaultExclusions - Verify default exclusion patterns work
• Test_LabelPropagation_IncludeList - Verify include-only mode overrides defaults
• Test_LabelPropagation_AdditionalExclusions - Verify additional exclusions are applied
• Test_LabelPropagation_CombinedIncludeAndExclude - Verify combined filters work correctly
• Test_LabelPropagation_Disabled - Verify no propagation when disabled

All tests pass ✅

5. CLI Flags (cmd/controller.go)

Added flags:

• --propagate-labels (boolean, default: false)
• --filter-include-labels (string slice)
• --filter-exclude-labels (string slice)

Added hidden misspelled variants:

• --propogate-labels (hidden)
• --filter-includ-labels (hidden)
• --filter-exlude-labels (hidden)

Added validation:

• Warning emitted if filter flags are used without --propagate-labels

6. Documentation (docs/advanced.md)

Added comprehensive section: "Label Propagation"

• Overview and use cases
• Flag descriptions
• Default exclusion patterns
• 4 detailed usage examples with expected outcomes
• Important notes and gotchas

Features

Default Exclusion Patterns

When --propagate-labels is enabled without --filter-include-labels:

• app.kubernetes.io/managed-by (exact match)
• helm.sh/* (prefix match - excludes all helm.sh labels)
• wiz.io/* (prefix match - excludes all wiz.io labels)

Usage Modes

Mode 1: Default Propagation with Exclusions

goldilocks controller --propagate-labels=true

Propagates all labels except default exclusion patterns.

Mode 2: Include-Only Mode

goldilocks controller --propagate-labels=true --filter-include-labels=app,env,team

Propagates ONLY specified labels, ignoring default exclusions.

Mode 3: Additional Exclusions

goldilocks controller --propagate-labels=true --filter-exclude-labels=team

Adds custom exclusions to the default exclusion list.

Mode 4: Combined Include and Exclude

goldilocks controller --propagate-labels=true \
  --filter-include-labels=app,env,team \
  --filter-exclude-labels=team

Start with include list, then apply additional exclusions.

Test Results

Unit Tests

=== RUN   TestFilterLabelsForPropagation
--- PASS: TestFilterLabelsForPropagation (0.00s)
=== RUN   TestShouldPropagateLabel
--- PASS: TestShouldPropagateLabel (0.00s)
=== RUN   TestMergeLabels
--- PASS: TestMergeLabels (0.00s)
PASS
ok  	github.com/fairwindsops/goldilocks/pkg/utils	0.492s

Integration Tests

=== RUN   Test_LabelPropagation_DefaultExclusions
--- PASS: Test_LabelPropagation_DefaultExclusions (0.00s)
=== RUN   Test_LabelPropagation_IncludeList
--- PASS: Test_LabelPropagation_IncludeList (0.00s)
=== RUN   Test_LabelPropagation_AdditionalExclusions
--- PASS: Test_LabelPropagation_AdditionalExclusions (0.00s)
=== RUN   Test_LabelPropagation_CombinedIncludeAndExclude
--- PASS: Test_LabelPropagation_CombinedIncludeAndExclude (0.00s)
=== RUN   Test_LabelPropagation_Disabled
--- PASS: Test_LabelPropagation_Disabled (0.00s)
PASS
ok  	github.com/fairwindsops/goldilocks/pkg/vpa	0.602s

Full Test Suite

All project tests pass ✅

Build

Application builds successfully ✅

Verification

• CLI help shows correct flags ✅
• Misspelled flags are hidden ✅
• No vet errors ✅

Backward Compatibility

✅ Fully backward compatible

• Default behavior unchanged (no label propagation unless explicitly enabled)
• Existing VPAs continue to work with only creator and source labels
• When --propagate-labels is enabled, existing VPAs will be updated on next reconciliation

Key Design Decisions

1. VPALabels Always Present: creator: Fairwinds and source: goldilocks are always preserved and cannot be overridden by propagated labels

2. Include List Overrides Defaults: When --filter-include-labels is specified, default exclusions are bypassed, giving users full control

3. Pattern Matching: Labels ending with / are treated as prefix matches (e.g., helm.sh/ matches all helm.sh/* labels)

4. Warning on Misconfiguration: Using filter flags without --propagate-labels emits a warning to prevent user confusion

5. Misspelling Support: Accept common misspellings (propogate) via hidden flags for better UX

Example Scenarios

Scenario 1: Basic Usage

goldilocks controller --propagate-labels=true

Controller labels:

• app=myapp
• env=prod
• team=backend
• helm.sh/chart=v1.0
• wiz.io/scan=true

VPA labels:

• app=myapp ✅
• env=prod ✅
• team=backend ✅
• creator=Fairwinds ✅
• source=goldilocks ✅

Scenario 2: Include-Only Mode

goldilocks controller --propagate-labels=true --filter-include-labels=app,env,helm.sh/chart

VPA labels:

• app=myapp ✅
• env=prod ✅
• helm.sh/chart=v1.0 ✅ (allowed by include list)
• creator=Fairwinds ✅
• source=goldilocks ✅

Scenario 3: Additional Exclusions

goldilocks controller --propagate-labels=true --filter-exclude-labels=team

VPA labels:

• app=myapp ✅
• env=prod ✅
• creator=Fairwinds ✅
• source=goldilocks ✅

Future Enhancements (Not Implemented)

Potential future improvements could include:

• Per-namespace label propagation configuration via annotations
• Per-controller label propagation via annotations
• Label transformation rules (rename, prefix, etc.)
• Support for label value filtering/transformation

References

• Documentation: docs/advanced.md
• Unit Tests: pkg/utils/utils_test.go
• Integration Tests: pkg/vpa/vpa_test.go