HIP: Chart values/v1 plugin type

Proposes a new chart-defined plugin type `values/v1` that enables plugins
to transform chart values before they are coalesced and distributed to
subchart dependencies.

Use cases:
- Map simple user values to complex subchart structures
- Apply conditional logic (switch/case) to derive values
- Compute values from inputs

Execution point in values pipeline:
1-3. Load & merge values
4.   values/v1 plugins
5.   CoalesceValues()
6.   ValidateAgainstSchema()
7.   Template rendering

Addresses long-standing community requests:
- helm/helm#8576 / helm/helm#8580 - map.yaml proposal (2020)
- helm/helm#6699 - Passing parent values to subcharts (2020)
- helm/helm#12323 - Templated values for subchart dependencies (2023)
- helm/helm#13493 - Value CEL mapping (2024)

Depends on: Chart-defined plugins HIP (helm#433)

Signed-off-by: Scott Rigby <scott@r6by.com>

Author: scottrigby

hips/hip-9999.md

@@ -0,0 +1,260 @@
+---
+hip: 9999
+title: "Chart values/v1 Plugin Type"
+authors: ["Scott Rigby <scott@r6by.com>"]
+created: "2026-01-11"
+type: feature
+status: draft
+requires: [chart-defined-plugins]
+helm-version: "4"
+---
+
+## Abstract
+
+This HIP proposes a new chart-defined plugin type, `values/v1`, that enables plugins to transform chart values before they are coalesced and distributed to subchart dependencies.
+
+## Motivation
+
+### Problem Statement
+
+Umbrella chart authors face a usability challenge when depending on community-maintained subcharts. While leveraging upstream charts reduces operational burden, it forces end users to understand and configure the complex, often inconsistent values structures of each subchart.
+
+**Example:** An umbrella chart might depend on 5+ subcharts, each with different conventions for:
+
+- Domain configuration (`.host`, `.domain`, `.ingress.hosts[0].host`)
+- Replica counts (`.replicaCount`, `.replicas`, `.primary.replicas`)
+- TLS settings (nested under various paths)
+
+Currently, umbrella chart `values.yaml` files must expose these implementation details to users.
+
+### User Stories
+
+**As an umbrella chart author**, I want to define a simple `values.yaml` for end users (e.g., `domain: myapp.example.com`) and have those values automatically mapped to the complex structures each subchart expects.
+
+**As an end user**, I want to configure a single `domain` value and have it apply consistently across all components.
+
+### Community Interest
+
+This problem has been raised repeatedly:
+
+- [#8576](https://github.com/helm/helm/issues/8576) / [#8580](https://github.com/helm/helm/pull/8580) - map.yaml proposal (2020)
+- [#6699](https://github.com/helm/helm/issues/6699) - Passing parent values to subcharts (2020)
+- [#12323](https://github.com/helm/helm/issues/12323) - Templated values for subchart dependencies (2023)
+- [#12668](https://github.com/helm/helm/issues/12668) - Shared values between subcharts (2023)
+- [#13493](https://github.com/helm/helm/issues/13493) - Value CEL mapping (2024)
+
+### Why a Plugin?
+
+Implementing this as a plugin type rather than a core feature:
+
+1. **Extensibility**: Different strategies (declarative mappings, CEL expressions) can compete
+2. **Independent Evolution**: Plugins iterate faster than Helm's release cycle
+3. **Reduced Core Complexity**: Keeps Helm core focused on its primary responsibilities
+
+## Specification
+
+### Plugin Type Definition
+
+```yaml
+type: values/v1
+```
+
+### Execution Point
+
+The `values/v1` plugin is invoked in the values processing pipeline:
+
+```
+1. Load chart values.yaml
+2. Merge with -f files (in order)
+3. Apply --set and --set-string flags
+4. ──► INVOKE values/v1 PLUGINS ◄──
+5. CoalesceValues() distributes values to subcharts
+6. ValidateAgainstSchema() validates coalesced values
+7. Template rendering
+```
+
+The plugin receives the fully merged user values and returns transformed values. These transformed values are then coalesced (distributed to subcharts) and schema-validated.
+
+### Plugin Interface
+
+**Input (JSON provided to the plugin):**
+
+```json
+{
+  "chartMetadata": {
+    "name": "my-umbrella-chart",
+    "version": "1.0.0",
+    "apiVersion": "v3"
+  },
+  "chartFiles": {
+    "<filename>": "<contents>",
+    ...
+  },
+  "inputValues": {
+    "domain": "myapp.example.com",
+    "highAvailability": true
+  }
+}
+```
+
+The plugin receives:
+
+- Chart metadata for context
+- Chart files (plugin may use configuration files)
+- The merged input values
+
+**Output (JSON returned by the plugin):**
+
+```json
+{
+  "transformedValues": {
+    "domain": "myapp.example.com",
+    "highAvailability": true,
+    "ingress-nginx": { ... },
+    "postgresql": { ... }
+  },
+  "errors": [],
+  "log": ["..."]
+}
+```
+
+The plugin returns:
+
+- **transformedValues**: The full values object after transformation, including subchart-namespaced keys
+- **errors**: If non-empty, Helm aborts with these error messages
+- **log**: Debug messages shown when `--debug` is used
+
+### Values Merging
+
+Transformed values follow standard Helm coalescing after plugin execution:
+
+1. Plugin returns transformed values
+2. `CoalesceValues()` merges with subchart defaults
+3. User `--set` values targeting subchart paths take precedence
+
+### Chart.yaml Declaration
+
+Charts declare `values/v1` plugins per [Chart-defined plugins HIP](https://github.com/helm/community/pull/433):
+
+```yaml
+apiVersion: v3
+name: my-umbrella-chart
+version: 1.0.0
+
+plugins:
+  - name: my-values-plugin
+    type: values/v1
+    repository: oci://ghcr.io/example/my-values-plugin
+    version: "1.0.0"
+
+subcharts:
+  - name: postgresql
+    version: 13.0.0
+    repository: https://charts.bitnami.com/bitnami
+```
+
+### Multiple Plugins
+
+Charts may declare multiple `values/v1` plugins. They execute sequentially in list order, each receiving the output of the previous plugin.
+
+### Debug Output
+
+When `--debug` is used, the plugin's log output is displayed, allowing users to see what transformations were applied.
+
+## Relationship to Schema Validation
+
+**Current behavior:**
+
+- JSON Schema validation (`values.schema.json`) runs on **coalesced** values
+- The `--skip-schema-validation` flag skips this validation
+
+**With values/v1:**
+
+- Plugin transforms values BEFORE coalescing
+- Coalescing distributes transformed values to subcharts
+- JSON Schema validation runs on coalesced (transformed) values
+- Plugin errors abort independently of schema validation
+
+**Plugin errors:**
+
+- A values/v1 plugin can return errors for any condition
+- Plugin receives ONLY the values at its invocation point:
+  - Initial user-supplied values merged with chart defaults
+  - After any preceding values/v1 plugins in the Chart.yaml list
+- Not a replacement for schema validation—complementary
+
+## Use Cases
+
+The `values/v1` plugin type enables various transformation strategies:
+
+1. **Value mapping**: Simple values → complex subchart structures
+2. **Conditional logic**: Switch/case based on input values
+3. **Custom error logic**: Return errors if business rules are violated
+4. **Value computation**: Derive values from inputs
+
+How a plugin implements these is up to the plugin author.
+
+## Backwards Compatibility
+
+- Charts without plugins continue to work unchanged
+- Charts with `values/v1` plugins fail gracefully with installation instructions
+- No changes to existing chart APIs
+
+## Security Implications
+
+### Sandboxing
+
+The plugin requires minimal capabilities:
+
+- Read: Access to chart files (already loaded in memory)
+- Compute: Transform values
+- No I/O: No filesystem, network, or exec access
+
+Wasm runtime provides sandboxing guarantees.
+
+### Transformation Visibility
+
+All transformations are logged via `--debug`, ensuring:
+
+- Users can audit changes
+- No hidden modifications
+
+## How to Teach This
+
+1. Update "Subcharts and Global Values" guide to mention values plugins
+2. Create "Values Plugins" documentation
+
+## Reference Implementation
+
+A reference implementation demonstrating rule-based transformations is planned:
+
+- **Runtime**: Wasm via Extism
+- **Configuration**: Rule-based YAML format supporting mappings, conditionals, and assertions
+- **Distribution**: OCI registry
+
+Implementation status: **Not started** (pending HIP acceptance)
+
+## Rejected Ideas
+
+### Recommend Forking Subcharts
+
+Recommending that users fork upstream charts to simplify values creates maintenance burden and security risks.
+
+### Library Chart Helpers
+
+Library chart templates execute AFTER values coalescing, so cannot transform what subcharts receive.
+
+### Include Schema Validation in values/v1
+
+Including schema validation in values/v1 rather than keeping it separate:
+
+- JSON Schema validation operates at a different stage (after coalescing)
+- values/v1 operates before coalescing
+- JSON Schema validation remains as the standard mechanism
+
+## References
+
+- [HIP-0016: Export-Values Directive](https://github.com/helm/community/blob/main/hips/hip-0016.md)
+- [HIP-0026: Wasm Plugin System](https://github.com/helm/community/blob/main/hips/hip-0026.md)
+- [Chart-defined plugins HIP (PR #433)](https://github.com/helm/community/pull/433)
+- [GitHub Issue #13493: Value CEL Mapping](https://github.com/helm/helm/issues/13493) - Most recent proposal