docs: updated hip from notes during helm dev meeting

Signed-off-by: Andrew Shoell <[email protected]>

Author: mrlunchbox777

hips/hip-0027.md

@@ -1,17 +1,17 @@
 ---
 hip: 0027
 title: "Expose Previously Installed Chart Metadata During Template Rendering"
-authors: [ "Andrew Shoell <[email protected]>" ]
+authors: ["Andrew Shoell <[email protected]>"]
 created: "2025-11-12"
 type: "feature"
 status: "draft"
 ---
 
 ## Abstract
 
-This HIP proposes exposing metadata from the currently deployed chart version during template rendering. Currently, Helm templates have access to `.Chart` for the chart being installed but no equivalent access to the currently deployed release. This forces chart authors to use complex workarounds like post-renderers, pre-upgrade hooks, or manual values conventions to implement version-aware upgrade logic.
+This HIP proposes exposing metadata from currently deployed chart versions during template rendering. Currently, Helm templates have access to `.Chart` for the chart being installed but no equivalent access to deployed releases. This forces chart authors to use complex workarounds like post-renderers, pre-upgrade hooks, or manual values conventions to implement version-aware upgrade logic.
 
-The proposal introduces a new `.DeployedChart` object available in all template contexts, populated with the deployed chart's metadata during `helm upgrade` and `helm rollback` operations. When no deployed release exists, `.DeployedChart` is nil, allowing safe checks with `{{ if .DeployedChart }}`. An optional `--disable-deployed-chart` flag provides opt-out capability.
+The proposal introduces `.DeployedChart` (singular, latest deployed) and `.DeployedCharts` (array, multiple versions) objects available in all template contexts, populated during `helm upgrade` and `helm rollback` operations. The `--deployed-depth` flag controls how many deployed versions to retrieve (default: 1), with `--deployed-depth 0` disabling the feature.
 
 ## Motivation
 
@@ -38,34 +38,36 @@ Post-rendering solutions violate Helm's design philosophy that template renderin
 
 ## Rationale
 
-### Naming: `.DeployedChart`
+### Naming: `.DeployedChart` and `.DeployedCharts`
+
+`.DeployedChart` (singular) provides ergonomic access to the most recent deployed version. `.DeployedCharts` (array) provides access to historical deployed versions in reverse chronological order (index 0 is most recent). `.DeployedChart` is syntactic sugar for `.DeployedCharts[0]`.
 
 Alternatives considered and rejected:
+
 - `.PreviousChart` - Ambiguous during rollbacks
 - `.InstalledChart` - Confusing with current installation
 - `.CurrentChart` - Ambiguous which is "current"
 - `.Release.Deployed.Chart` - Unnecessarily nested
 
-`.DeployedChart` unambiguously means "what is currently running in the cluster" and maintains consistency with Helm terminology.
+### Always Available as Template Objects
 
-### Always Available as Template Object
-
-`.DeployedChart` is always present (though possibly nil) to ensure consistent template behavior, prevent undefined variable errors, and enable testing with `helm template`.
+`.DeployedChart` (nil or chart metadata) and `.DeployedCharts` (empty array or populated) are always present to ensure consistent template behavior, prevent undefined variable errors, and enable testing with `helm template`.
 
 ### Populated Only During Upgrades/Rollbacks
 
-`.DeployedChart` contains chart metadata only during `helm upgrade` and `helm rollback` when a deployed release exists. It's nil for:
+`.DeployedChart`/`.DeployedCharts` contain chart metadata only during `helm upgrade` and `helm rollback` when deployed releases exist. During rollback, they reflect the currently deployed version (being rolled back _from_). They're nil/empty for:
+
 - `helm install` - No deployed release
 - `helm template` / dry-runs - No cluster context
-- When `--disable-deployed-chart` is used
+- When `--deployed-depth 0` is used
 
 ### Chart Metadata Only
 
 This proposal exposes only Chart.yaml metadata (same structure as `.Chart`), not values, manifests, or release metadata. This maintains security (values may contain secrets), performance (manifests can be large), and simplicity while solving 90% of use cases. Future HIPs could extend this if needed.
 
-### Opt-Out Flag
+### Depth Control Flag
 
-The `--disable-deployed-chart` flag allows organizations to disable the feature for security or determinism requirements. A CLI flag was chosen over environment variables for explicitness and consistency with Helm's patterns.
+The `--deployed-depth` flag controls how many deployed chart versions to retrieve (default: 1). Setting `--deployed-depth 0` disables the feature for security or determinism requirements. Higher depths may impact performance and should only be used for specific multi-version migration scenarios.
 
 ### Design Decisions
 
@@ -75,17 +77,20 @@ The `--disable-deployed-chart` flag allows organizations to disable the feature
 
 ## Specification
 
-### New Template Object: `.DeployedChart`
+### New Template Objects
 
-A top-level template object available in all contexts. Populated with deployed chart metadata during upgrade/rollback; nil otherwise.
+**`.DeployedChart`**: Singular object containing the most recent deployed chart metadata (nil if none exists). Syntactic sugar for `.DeployedCharts[0]`.
 
-**Metadata Structure:** Identical to `.Chart`, including `Name`, `Version`, `AppVersion`, and other [Chart.yaml fields](https://helm.sh/docs/topics/charts/#the-chartyaml-file).
+**`.DeployedCharts`**: Array of deployed chart metadata objects in reverse chronological order (most recent first). Empty array if no deployed releases exist.
+
+**Metadata Structure:** Each chart object is identical to `.Chart`, including `Name`, `Version`, `AppVersion`, and other [Chart.yaml fields](https://helm.sh/docs/topics/charts/#the-chartyaml-file).
+
+**Usage Examples:**
 
-**Usage Example:**
 ```yaml
+# Simple case: check latest deployed version
 {{- if .DeployedChart }}
 {{- if and (semverCompare ">=2.0.0" .Chart.Version) (semverCompare "<2.0.0" .DeployedChart.Version) }}
-# Migration logic for 1.x -> 2.x upgrade
 apiVersion: batch/v1
 kind: Job
 metadata:
@@ -101,43 +106,61 @@ spec:
         command: ["migrate", "v1-to-v2"]
 {{- end }}
 {{- end }}
+
+# Multi-version migration: handle complex upgrade paths
+{{- if gt (len .DeployedCharts) 0 }}
+{{- range .DeployedCharts }}
+{{- if semverCompare "<1.5.0" .Version }}
+# Run migration for versions before 1.5.0
+{{- end }}
+{{- end }}
+{{- end }}
 ```
 
 ### Command-Line Flag
 
 ```bash
-helm upgrade myrelease mychart --disable-deployed-chart
+# Default: retrieve latest deployed chart
+helm upgrade myrelease mychart
+
+# Retrieve last 3 deployed versions
+helm upgrade myrelease mychart --deployed-depth 3
+
+# Disable feature
+helm upgrade myrelease mychart --deployed-depth 0
 ```
 
 ### Behavior Matrix
 
-| Operation | `.DeployedChart` Value |
-|-----------|------------------------|
-| `helm install` | `nil` (no deployed release) |
-| `helm upgrade` (new) | `nil` (no deployed release) |
-| `helm upgrade` (existing) | Populated with deployed metadata |
-| `helm rollback` | Populated with deployed metadata |
-| `helm template` / dry-runs | `nil` (no cluster context) |
-| With `--disable-deployed-chart` | `nil` (explicitly disabled) |
+| Operation                  | `.DeployedChart` / `.DeployedCharts`                            |
+| -------------------------- | --------------------------------------------------------------- |
+| `helm install`             | `nil` / `[]` (no deployed release)                              |
+| `helm upgrade` (new)       | `nil` / `[]` (no deployed release)                              |
+| `helm upgrade` (existing)  | Populated with deployed metadata (most recent first)            |
+| `helm rollback`            | Populated with currently deployed version (rolling back _from_) |
+| `helm template` / dry-runs | `nil` / `[]` (no cluster context)                               |
+| `--deployed-depth 0`       | `nil` / `[]` (explicitly disabled)                              |
+| `--deployed-depth N`       | Up to N most recent deployed versions                           |
 
 ## Backwards Compatibility
 
-Fully backwards compatible. The `.DeployedChart` object is purely additive—existing charts work unchanged. Go templates handle nil safely; the recommended `{{ if .DeployedChart }}` pattern works in all scenarios.
+Fully backwards compatible. The `.DeployedChart` and `.DeployedCharts` objects are purely additive—existing charts work unchanged. Go templates handle nil and empty arrays safely; the recommended `{{ if .DeployedChart }}` pattern works in all scenarios.
 
 ## Security Implications
 
 **Not Exposed:** Previous values (may contain secrets) or previous manifest (may contain sensitive data). Only Chart.yaml metadata is exposed.
 
-**Considerations:** Chart authors should not store sensitive data in Chart.yaml. The `--disable-deployed-chart` flag provides opt-out for security-sensitive environments.
+**Considerations:** Chart authors should not store sensitive data in Chart.yaml. The `--deployed-depth 0` flag provides opt-out for security-sensitive environments. Higher depth values increase data exposure; use the minimum required.
 
 ## How to Teach This
 
 ### Documentation Additions
 
-1. **Template Objects Reference:** Add `.DeployedChart` to built-in objects with availability details
-2. **Upgrade Guide:** "Implementing Version-Aware Upgrades" covering nil checks, version comparisons, and best practices
-3. **Migration Examples:** Show replacement of post-renderers and pre-upgrade hooks with `.DeployedChart`
-4. **Chart Linting:** Update `helm lint` to warn on `.DeployedChart` usage without nil checks
+1. **Template Objects Reference:** Add `.DeployedChart` and `.DeployedCharts` to built-in objects with availability details
+2. **Upgrade Guide:** "Implementing Version-Aware Upgrades" covering nil/empty checks, version comparisons, and best practices
+3. **Migration Examples:** Show replacement of post-renderers and pre-upgrade hooks
+4. **Performance Note:** Document that `--deployed-depth` should be kept minimal; default of 1 is recommended
+5. **Chart Linting:** Update `helm lint` to warn on usage without nil/empty checks
 
 ### Key Example Pattern
 
@@ -150,22 +173,27 @@ Fully backwards compatible. The `.DeployedChart` object is purely additive—exi
 ## Reference Implementation
 
 A future pull request will:
-1. Extend template rendering context to include `.DeployedChart`
-2. Populate from release records during upgrade/rollback
-3. Add `--disable-deployed-chart` flag
-4. Include comprehensive unit and integration tests
+
+1. Extend template rendering context to include `.DeployedChart` and `.DeployedCharts`
+2. Populate from release records during upgrade/rollback (reverse chronological order)
+3. Add `--deployed-depth` flag (default: 1)
+4. Implement `.DeployedChart` as alias to `.DeployedCharts[0]`
+5. Include comprehensive unit and integration tests covering depth behavior
 
 ## Rejected Ideas
 
 - **Full Release Object:** Security/performance concerns; chart metadata sufficient
 - **Only Version Strings:** Inconsistent with `.Chart`; prevents access to other metadata
 - **Environment Variable Control:** Less explicit than CLI flag
 - **Cluster Query During `helm template`:** Violates cluster-agnostic design principle
-- **Mutable `.DeployedChart`:** Violates read-only template model; no clear use case
+- **Mutable Objects:** Violates read-only template model; no clear use case
+- **Separate `--disable-deployed-chart` Flag:** Unified `--deployed-depth` with 0 value is cleaner
+- **Unlimited History:** Performance implications; requiring explicit depth prevents accidental overhead
 
 ## References
 
 - [Helm Built-in Objects](https://helm.sh/docs/chart_template_guide/builtin_objects/)
 - [Helm Chart.yaml](https://helm.sh/docs/topics/charts/#the-chartyaml-file)
 - [Go Templates](https://pkg.go.dev/text/template)
 - [Semantic Versioning](https://semver.org/)
+- [Example of current workaround](https://github.com/helm/community/pull/421#issuecomment-3662769874)