YAML anchors/aliases spanning resources break during post-render: "unknown anchor referenced"

[Subetov]

Describe the bug

A chart template that defines a YAML anchor (&name) on one resource and references it with an alias (*name) on another resource in the same rendered output fails to reconcile on helm-controller v1.6.x. Reconciliation errors out during the post-render stage with:

error while running post render on files: MalformedYAMLError: yaml: unknown anchor 'jobSpec' referenced

The same chart:

• renders correctly with helm template (anchors are preserved as text and resolve when the manifest is parsed as a single stream), and
• installed/upgraded correctly on older helm-controller v1.0.x (Helm SDK v3).

It looks like the post-render pipeline parses/re-serializes the manifest per-document (or otherwise splits the anchor definition from the alias reference), so the alias can no longer find its anchor.

Steps to reproduce

1. A chart with a template that shares a spec between two resources via a YAML anchor. Minimal, abstract example:

   # templates/example.yaml
   apiVersion: v1
   kind: List
   items:
     - apiVersion: batch/v1
       kind: Job
       metadata:
         name: example
       spec: &jobSpec
         template:
           spec:
             restartPolicy: Never
             containers:
               - name: main
                 image: busybox:latest
                 command: ["true"]
     - apiVersion: batch/v1
       kind: CronJob
       metadata:
         name: example
       spec:
         schedule: "0 0 * * *"
         jobTemplate:
           spec: *jobSpec        # <-- alias reference

2. A HelmRelease that installs this chart, with no postRenderers, commonMetadata, etc. configured:

   apiVersion: helm.toolkit.fluxcd.io/v2
   kind: HelmRelease
   metadata:
     name: example
     namespace: default
   spec:
     interval: 5m
     chart:
       spec:
         chart: example
         version: 0.1.0
         sourceRef:
           kind: HelmRepository
           name: example

3. Reconcile.

Expected behavior

The alias resolves to the anchored node (as it does with helm template and as it did on helm-controller v1.0.x), and the release installs successfully.

Actual behavior

Reconciliation fails during post-render:

Helm install failed for release default/example with chart example@0.1.0:
error while running post render on files: MalformedYAMLError: yaml: unknown anchor 'jobSpec' referenced

Note: the post-render stage runs even though the HelmRelease configures no post-renderer.

Additional context

• The failure is in the post-render stage, before apply. Setting spec.install.serverSideApply: false and spec.upgrade.serverSideApply: disabled (client-side apply) makes no difference — the release never reaches the apply stage. So this is unrelated to the client-side/server-side apply change.
• Verified by deleting and re-creating the HelmRelease from scratch (new object, fresh generation): the very first reconcile fails identically, so it is not stale/cached state.
• Reproduced on both v1.6.2 and v1.6.3 (confirmed by running ghcr.io/fluxcd/helm-controller:v1.6.3 directly — identical failure), so it is not fixed in the latest release.
• This is a behavior change between helm-controller v1.0.x (Helm SDK v3) and v1.6.x (Helm SDK v4). It may originate in the upstream Helm SDK's post-render handling rather than helm-controller itself — filing here since that is where the regression surfaced; happy to move it upstream if that is the right place.

A named template (define/include) is a working post-render-safe replacement for the anchor, so there is a workaround. Filing because YAML anchors are valid, previously worked, and the failure mode ("unknown anchor") is confusing to diagnose.

Steps to reproduce — versions

• helm-controller version: v1.6.2 (also present on latest v1.6.3)
• flux2 (community chart): 2.19.0 (appVersion 2.9.1)
• Kubernetes version: v1.34.x (k3s)

[matheuscscp]

Can you please bisect which minor version of helm-controller introduced the bug?

[zanarellidev]

Bisect notes (also covered in #1558):

• Reproduced on current main: Helm v4 annotateAndMerge unwraps kind:List into separate documents while keeping &anchor / *alias markers, so OriginLabels (always-on post-renderer) hits "unknown anchor referenced".
• The List example in the issue is the right shape. After unwrap it becomes cross-document aliases; a single-document List before unwrap parses fine.
• OriginLabels has failed on raw cross-doc aliases since at least v1.0.0. What changed for this chart class is Helm v4 landing in helm-controller v1.5.0 (Helm v4.1.x); v1.6.0 is on Helm v4.2.x. Helm v3 controllers did not unwrap List this way before post-render.

Fix in #1558: inflate aliases in Combined.Run only when ParseAll fails with an unknown-anchor error (re-wrap as List, DeAnchor, re-serialize). Fail-before/pass-after covered in the PR tests.

[matheuscscp]

Looks like the bug is in helm, not helm-controller

[matheuscscp]

@Subetov Which chart has this? Is it a public chart?

[Subetov]

@matheuscscp

Thanks for confirming — the pattern we hit is exactly what's reproduced in helm/helm#32203: a kind: List with two items sharing a YAML anchor/alias (ours is a private chart we can't share directly, but the shape is identical). Nothing chart-specific on our end, so that repro should cover it.

Saw #1558 got closed given the root cause is upstream. Understood — this stays blocked on a fix landing in helm/helm#32203 and helm-controller picking it up via a Helm SDK bump. We'll keep an eye on that issue and follow up here once it lands.

Thanks !

[stefanprodan]

@Subetov I would spend 20 bucks on some AI Agent to rewrite the chart with proper Helm templating. IMO there is really no reason to use Lists with anchor/alias nowadays when Helm has full support for Named Templates inside _helpers.tpl.

[matheuscscp]

the pattern we hit is exactly what's reproduced in helm/helm#32203

Thanks, I bumped the issue there: helm/helm#32203 (comment)