docs: changing the object to always be available

Signed-off-by: Andrew Shoell <mrlunchbox777@gmail.com>

Author: mrlunchbox777

hips/hip-0027.md

@@ -11,7 +11,7 @@ status: "draft"
 
 This HIP proposes exposing metadata from the currently deployed chart version during template rendering for upgrade and rollback operations. Currently, Helm templates have access to `.Chart` which provides metadata about the chart being installed (name, version, appVersion, etc.), but no equivalent access to information about the release currently deployed in the cluster. This limitation prevents chart authors from implementing upgrade-aware logic, forcing them to rely on complex workarounds such as post-renderers, pre-upgrade hooks, or manual values file conventions.
 
-The proposal introduces a new `.DeployedChart` object available in the template context during `helm upgrade` and `helm rollback` operations. This object contains the same metadata structure as `.Chart` but is populated with values from the chart version currently running in the cluster. When no deployed release exists (such as during initial installation), `.DeployedChart` is nil, allowing templates to safely check for its existence with `{{ if .DeployedChart }}`.
+The proposal introduces a new `.DeployedChart` object available in the template context during all Helm operations. This object contains the same metadata structure as `.Chart` but is populated with values from the chart version currently running in the cluster during upgrade and rollback operations. When no deployed release exists (such as during initial installation, dry-run operations, or when explicitly disabled), `.DeployedChart` is nil, allowing templates to safely check for its existence with `{{ if .DeployedChart }}`.
 
 This enhancement enables chart maintainers to build intelligent upgrade paths that can detect version transitions, implement breaking change migrations, conditionally apply resources based on version deltas, and provide seamless user experiences during chart lifecycle operations—all within the chart itself without requiring external tooling. An optional `--disable-deployed-chart` flag allows users to opt out of this feature for security or determinism requirements.
 
@@ -93,16 +93,27 @@ This decision provides:
 
 ### Available During Upgrade and Rollback Operations
 
-`.DeployedChart` is populated during both `helm upgrade` and `helm rollback` operations because both scenarios involve transitioning from one deployed state to another. In both cases:
+`.DeployedChart` is always available as a template object but is populated with chart metadata only during `helm upgrade` and `helm rollback` operations when a deployed release exists in the cluster. In all other scenarios, `.DeployedChart` is nil.
 
-- There is a currently deployed release that templates may need to reason about
-- Version-aware logic is valuable (e.g., handling migrations, conditional resources)
-- The semantics of "deployed chart" remain clear and unambiguous
+**Populated with chart metadata:**
+- `helm upgrade` (when upgrading an existing release)
+- `helm rollback` (when rolling back to a previous revision)
 
-`.DeployedChart` is explicitly **not** available (always nil) during:
-- `helm install`: No deployed chart exists
-- `helm template`: See "Dry-Run and Template Operations" below
-- `helm install --dry-run`: See "Dry-Run and Template Operations" below
+**Always nil:**
+- `helm install` - No deployed release exists yet
+- `helm upgrade` (first install) - Treated as install, no prior release
+- `helm template` - No cluster context available
+- `helm install --dry-run` - No cluster context available
+- `helm upgrade --dry-run` - No cluster access during dry-run
+- When `--disable-deployed-chart` flag is used - Explicitly disabled
+
+The object is always present in the template context to ensure templates can be written consistently across all operations. Chart authors can rely on `.DeployedChart` being a valid object reference (though it may be nil) without worrying about undefined variable errors.
+
+**Why always available but sometimes nil:**
+- Consistent template behavior - templates don't need to conditional logic to check if the object exists vs. if it has data
+- Follows Go template conventions - nil is the idiomatic way to represent absence of data
+- Simplifies template code - `{{ if .DeployedChart }}` works in all scenarios
+- Enables testing - templates using `.DeployedChart` can be tested with `helm template` without errors
 
 ### Chart Metadata Only (Not Full Release Data)
 
@@ -167,7 +178,9 @@ Chart authors who need to inspect actual cluster state should use the `lookup()`
 
 ### Dry-Run and Template Operations
 
-`.DeployedChart` is **not** available during `helm template` or `helm install --dry-run` operations because these commands are intentionally cluster-agnostic and should remain deterministic without cluster context.
+`.DeployedChart` is always available as a template object but is always nil during `helm template` and dry-run operations (`helm install --dry-run`, `helm upgrade --dry-run`) because these commands are intentionally cluster-agnostic and should remain deterministic without cluster context.
+
+The object is present (but nil) to ensure templates that reference `.DeployedChart` don't fail with undefined variable errors during templating and dry-run operations.
 
 However, we recognize that chart authors may want to test templates that use `.DeployedChart`. To support this use case:
 
@@ -201,13 +214,23 @@ The following outlines the syntax and semantics of the proposed changes.
 
 ### New Template Object: `.DeployedChart`
 
-A new top-level template object `.DeployedChart` will be available during `helm upgrade` and `helm rollback` operations.
+A new top-level template object `.DeployedChart` will be available in all template contexts. The object is populated with chart metadata during `helm upgrade` and `helm rollback` operations when a deployed release exists. In all other scenarios, the object is nil.
+
+**Always available:** The `.DeployedChart` object is present in the template context for all Helm operations to ensure consistent template behavior and prevent undefined variable errors.
 
-**Availability:**
-- **Available**: `helm upgrade`, `helm rollback`
-- **Not available (nil)**: `helm install`, `helm template`, `helm install --dry-run`, or when `--disable-deployed-chart` flag is used
+**Populated with data:**
+- `helm upgrade` (when upgrading an existing release)
+- `helm rollback` (when rolling back to a previous revision)
 
-**Populated from:** The metadata of the chart version currently deployed in the cluster, retrieved from Helm's release record.
+**Always nil:**
+- `helm install` - No deployed release exists
+- `helm upgrade` (first install) - No deployed release exists
+- `helm template` - No cluster context
+- `helm install --dry-run` - No cluster context
+- `helm upgrade --dry-run` - No cluster context during dry-run
+- When `--disable-deployed-chart` flag is used
+
+**Populated from:** When not nil, the metadata of the chart version currently deployed in the cluster, retrieved from Helm's release record.
 
 ### Metadata Fields
 
@@ -314,15 +337,18 @@ When this flag is set, `.DeployedChart` will be nil regardless of whether a depl
 
 ### Behavior During Different Operations
 
-| Operation | `.DeployedChart` Value |
-|-----------|----------------------|
-| `helm install` | Always `nil` (no deployed release) |
-| `helm upgrade` (first install) | `nil` (no deployed release) |
-| `helm upgrade` (actual upgrade) | Populated with deployed chart metadata |
-| `helm upgrade --disable-deployed-chart` | `nil` (explicitly disabled) |
-| `helm rollback` | Populated with currently deployed chart metadata |
-| `helm template` | Always `nil` (no cluster context) |
-| `helm install --dry-run` | Always `nil` (no cluster context) |
+| Operation | `.DeployedChart` Availability | `.DeployedChart` Value |
+|-----------|------------------------------|----------------------|
+| `helm install` | Always available | Always `nil` (no deployed release) |
+| `helm upgrade` (first install) | Always available | `nil` (no deployed release) |
+| `helm upgrade` (actual upgrade) | Always available | Populated with deployed chart metadata |
+| `helm upgrade --disable-deployed-chart` | Always available | `nil` (explicitly disabled) |
+| `helm upgrade --dry-run` | Always available | Always `nil` (no cluster context) |
+| `helm rollback` | Always available | Populated with currently deployed chart metadata |
+| `helm template` | Always available | Always `nil` (no cluster context) |
+| `helm install --dry-run` | Always available | Always `nil` (no cluster context) |
+
+**Note:** The object is always present to prevent template errors when referencing `.DeployedChart`, even when it contains no data.
 
 ## Backwards Compatibility
 
@@ -395,8 +421,14 @@ Show chart authors how to replace existing workarounds:
 apiVersion: batch/v1
 kind: Job
 metadata:
-  name: migrate-v1-to-v2
-# ...
+  name: {{ include "mychart.fullname" . }}-migration
+spec:
+  template:
+    spec:
+      containers:
+      - name: migrate
+        image: myapp/migrator:{{ .Chart.AppVersion }}
+        command: ["migrate", "v1-to-v2"]
 {{- end }}
 {{- end }}
 ```
@@ -525,62 +557,22 @@ The following ideas were considered during the design of this HIP but were ultim
 
 ### Making Available During `helm install`
 
-**Idea:** Make `.DeployedChart` available during fresh installs (would always be nil).
+**Idea:** Make `.DeployedChart` unavailable (not present in template context) during fresh installs.
 
 **Rejection Reason:**
-- Provides no value (would always be nil anyway)
-- Adds unnecessary complexity to install code path
-- Could cause confusion ("why is it nil during my install?")
-- Templates that check `{{ if .DeployedChart }}` work correctly without special handling
+- Would cause template errors when templates reference `.DeployedChart` during install
+- Inconsistent behavior - templates would need to handle both "object doesn't exist" and "object is nil" cases
+- Makes testing harder - templates would fail during `helm template` with undefined variable errors
+- Having the object always present but nil is more idiomatic and user-friendly
+- Templates written with `{{ if .DeployedChart }}` work correctly in all scenarios
 
 ### Making Available During `helm template`
 
-**Idea:** Allow `.DeployedChart` to be populated during `helm template` by querying the cluster.
+**Idea:** Make `.DeployedChart` unavailable (not present in template context) during `helm template`.
 
 **Rejection Reason:**
-- Violates the design principle that `helm template` should be cluster-agnostic
-- Would make template rendering non-deterministic
-- Could cause security issues if templating in one environment with data from another
-- A future mock/plugin system is a better solution for testing
-
-### Different Naming Conventions
-
-**Ideas considered:**
-- `.PreviousChart` (ambiguous for rollbacks)
-- `.InstalledChart` (confusing with current install)
-- `.CurrentChart` (ambiguous which is "current")
-- `.Release.Deployed.Chart` (unnecessarily nested)
-- `.OldChart` (informal and ambiguous)
-
-**Rejection Reason:** `.DeployedChart` is the clearest and most consistent with Helm terminology.
-
-### Exposing Only Version Strings
-
-**Idea:** Only expose `.DeployedVersion` and `.DeployedAppVersion` as simple strings instead of the full chart object.
-
-**Rejection Reason:**
-- Inconsistent with `.Chart` object structure
-- Prevents access to other useful metadata (type, deprecated status, annotations)
-- Would need to be expanded later anyway if more fields are needed
-- Simpler to reuse existing Chart metadata structure
-
-### Environment Variable or Config File
-
-**Idea:** Control the feature via environment variable or Helm configuration file instead of CLI flag.
-
-**Rejection Reason:**
-- Less explicit than a CLI flag
-- Harder to see in scripts and documentation
-- Doesn't follow Helm's pattern of operation-specific flags
-- Could cause confusion if set globally but not desired for specific operations
-
-## Open Issues
-
-None at this time. This HIP is ready for community review and feedback.
-
-## References
-
-- [Helm Built-in Objects Documentation](https://helm.sh/docs/chart_template_guide/builtin_objects/)
-- [Helm Template Functions and Pipelines](https://helm.sh/docs/chart_template_guide/functions_and_pipelines/)
-- [Go Template Documentation](https://pkg.go.dev/text/template)
-- [Semantic Versioning 2.0.0](https://semver.org/)
+- Would cause template errors when templates reference `.DeployedChart`
+- Violates the design principle that `helm template` should work for all valid templates
+- Makes development harder - chart authors couldn't validate template syntax
+- Having the object present but nil allows templates to render successfully
+- A future mock/plugin system is a better solution for providing test data