GitOps on AKS with the Managed Flux Extension: Deploying a Helm Chart

GitOps on AKS with the Managed Flux Extension: Deploying a Helm Chart

Deploy Helm charts on AKS with the managed Flux extension, using GitRepository and HelmRelease resources to automate installs and upgrades from Git.

In the first post of this series I set up the AKS managed Flux extension and used it to reconcile a plain Kustomize sample, Podinfo. That proved the basics: a Flux configuration, a GitRepository, and a Kustomization that applies whatever is at a Git path.

Most real clusters also run Helm charts, so the natural next question is: does the managed extension handle Helm the same way, or does it need something extra? I kept the same cluster and extension from the first post and added a second, independent Flux configuration that deploys a Helm chart from Git. Short answer: yes it works, and there is one extra thing you need to get right — RBAC for the Helm release — that the Kustomize demo never had to deal with.

Everything is in the same Code-Snippets repository as the first post. This lesson adds its own files; it does not replace or change the Kustomize demo.

New to this series? Start with Getting started with the AKS Flux extension for the cluster, the extension, and the Kustomize basics. If you are coming from self-managed Flux, Bootstrapping Flux on AKS covers flux bootstrap instead.


One Cluster, Independent Lessons

The whole point of this series is that I provision the AKS cluster and the microsoft.flux extension once, in terraform/main.tf, and then add one lesson per Flux configuration on top of it. Terraform loads every .tf file in the directory, so adding helm-demo.tf does not create a second infrastructure stack — it is still the same cluster and the same extension.

Layer or lessonFilesAzure configurationApplication namespace
Shared foundationterraform/main.tfManaged extension in flux-systemShared AKS cluster
Git + Kustomizeterraform/kustomize-demo.tf, gitops/kustomizecluster-configflux-demo
Helm chart in Gitterraform/helm-demo.tf, gitops/helmhelm-demo-configkubeplay-helm

Neither Flux configuration knows about the other. A failed Helm release does not make cluster-config non-compliant, and deleting the Helm configuration later does not touch Podinfo. They show up as two separate rows in the Azure portal’s GitOps list on the same cluster.

The chart I deploy is KubePlay, a small multi-service demo app, pulled from its own repository rather than from Code-Snippets. That is deliberate: it shows Flux reconciling a chart that lives somewhere other than the manifests repository, which is closer to how most teams actually keep charts and application config separate.


What We Are Building

  • A second Azure Flux configuration, helm-demo-config, pointing at gitops/helm in the same Git repository and branch as the Kustomize demo.
  • A GitRepository (helm-demo-chart) that clones the external k8s-demo-sample-app repository and packages only its chart directory.
  • A HelmRelease (helm-demo-kubeplay) that builds the chart and installs it into a new kubeplay-helm namespace.
  • A dedicated ServiceAccount, Role, and RoleBinding so Helm can manage its release without needing cluster-wide permissions.

This lesson currently teaches a chart stored in Git, not a published HTTP HelmRepository or an OCI registry. That is a deliberate scope decision so this post stays focused on the RBAC and release mechanics; a future post can cover HelmRepository or OCI sources in their own lesson.


The Terraform: A Second, Independent Flux Configuration

The important part is that this is a completely separate azurerm_kubernetes_flux_configuration, not a change to the one from the first post:

# Reconcile the Helm lesson independently using the shared cluster and extension.
resource "azurerm_kubernetes_flux_configuration" "kubeplay" {
  count                             = contains(var.enabled_demos, "helm") ? 1 : 0
  name                              = "helm-demo-config"
  cluster_id                        = azurerm_kubernetes_cluster.this.id
  namespace                         = "helm-demo-config"
  scope                             = "cluster"
  continuous_reconciliation_enabled = true

  git_repository {
    url                      = var.git_repository_url
    reference_type           = "branch"
    reference_value          = var.git_branch
    sync_interval_in_seconds = 60
    timeout_in_seconds       = 120
  }

  kustomizations {
    name                       = "helm"
    path                       = var.gitops_helm_path
    garbage_collection_enabled = true
    sync_interval_in_seconds   = 60
    retry_interval_in_seconds  = 30
    timeout_in_seconds         = 600
  }

  depends_on = [azurerm_kubernetes_cluster_extension.flux]

  lifecycle {
    precondition {
      condition     = var.git_repository_url != "" && var.gitops_helm_path != null
      error_message = "The Helm demo requires git_repository_url and a non-null gitops_helm_path."
    }
  }
}

A few things worth calling out:

  • namespace = "helm-demo-config" is a different source namespace from cluster-config in the first post. Azure names the generated Flux Kustomization helm-demo-config-helm, following the same <configuration>-<kustomization name> pattern I noted last time.
  • count gated by enabled_demos is how deploy.sh --demo helm enables this configuration without touching the Kustomize one. Pass --demo all to enable both.
  • timeout_in_seconds = 600 is longer than the Kustomize demo’s five minutes. Pulling a chart, templating it, and waiting for a Helm install to report healthy legitimately takes longer than applying plain manifests.
  • The precondition is a small safety net: Terraform fails fast with a clear message instead of applying a Flux configuration that points nowhere.

The Flux Kustomization inside this configuration is called helm, but it still applies the Kubernetes manifests using server-side apply. Those manifests include a GitRepository and a HelmRelease; the source and Helm controllers then use them to package and install the chart.


The GitOps Directory, Piece by Piece

gitops/
  helm/
    kustomization.yaml      # includes prerequisites, source, and release
    gitrepository.yaml      # clones the chart repository
    helmrelease.yaml         # installs the chart with override values
    prerequisites/
      kustomization.yaml
      namespace.yaml         # the kubeplay-helm namespace
      rbac.yaml              # ServiceAccount, Role, RoleBinding

1. Package the chart directory

# Flux source that clones the repository containing the Helm chart.
apiVersion: source.toolkit.fluxcd.io/v1
kind: GitRepository
metadata:
  name: helm-demo-chart
  namespace: kubeplay-helm
spec:
  interval: 1m
  url: https://github.com/kasunsjc/k8s-demo-sample-app
  ref:
    branch: main
  # Include only the chart directory in the packaged artifact.
  ignore: |
    /*
    !/deploy/helm/kubeplay

The ignore block flips the usual Flux ignore semantics: exclude everything, then explicitly re-include the one chart directory. Flux clones the repository, then packages only deploy/helm/kubeplay into the GitRepository artifact. The source controller builds a HelmChart artifact from that path for the Helm controller. Unrelated files are excluded from the artifact, although the GitRepository still tracks the branch’s revision.

2. Install the chart with override values

This is the initial HelmRelease used for the installation below. The repository now contains the later values and drift-detection changes described in the hands-on sections.

# Installs the chart from the GitRepository above. Values here override the chart's values.yaml.
apiVersion: helm.toolkit.fluxcd.io/v2
kind: HelmRelease
metadata:
  name: helm-demo-kubeplay
  namespace: kubeplay-helm
spec:
  releaseName: helm-demo-kubeplay
  serviceAccountName: helm-demo-deployer
  interval: 5m
  timeout: 10m
  chart:
    spec:
      chart: ./deploy/helm/kubeplay
      reconcileStrategy: Revision
      sourceRef:
        kind: GitRepository
        name: helm-demo-chart
  install:
    remediation:
      retries: 3
  upgrade:
    remediation:
      retries: 3
  values:
    global:
      imageRegistry: ''
      imageTag: '0.1.2'
      imagePullPolicy: IfNotPresent
    ui:
      image: kasunsjc/kubeplay-ui-gateway
      title: KubePlay via Flux
    inspector:
      image: kasunsjc/kubeplay-inspector-api
      replicas: 3
      hpa:
        enabled: false
    notes:
      image: kasunsjc/kubeplay-notes-api
    worker:
      image: kasunsjc/kubeplay-worker
    redis:
      storage:
        storageClass: managed-csi
    ingress:
      enabled: false

The settings I paid the most attention to:

  • chart.spec.chart: ./deploy/helm/kubeplay is the path to the chart inside the GitRepository’s artifact, not a repository URL. Because the source already excludes everything else, this path only needs to resolve within what Flux kept.
  • reconcileStrategy: Revision means Flux watches the Git revision for changes to the chart itself, not just a chart version field. Push a change to the chart’s templates and Flux picks it up on the next sync, exactly like the Kustomize demo picks up manifest changes.
  • values here override the chart’s own values.yaml. This is the same place you would put per-environment values if you had more than one.
  • install.remediation.retries / upgrade.remediation.retries tell the Helm controller to retry a failed install or upgrade up to three times before giving up, instead of leaving the release stuck on the first failure.
  • Images are pulled straight from Docker Hub (kasunsjc/kubeplay-<service>:0.1.2), so there is no container registry to attach to the cluster for this demo.

3. Tie it together

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - prerequisites
  - gitrepository.yaml
  - helmrelease.yaml

This is the Kustomize build file that the Flux Kustomization named helm applies. It bundles the namespace and RBAC prerequisites together with the Helm source and release, so one Flux configuration creates everything the chart needs, in the right order.


Why a Helm Release Needs Its Own RBAC

This was the one part that was not obvious to me coming from the Kustomize demo, where I never had to think about RBAC at all.

apiVersion: v1
kind: Namespace
metadata:
  name: kubeplay-helm
---
apiVersion: v1
kind: ServiceAccount
metadata:
  name: helm-demo-deployer
  namespace: kubeplay-helm
automountServiceAccountToken: false
---
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: helm-demo-deployer
  namespace: kubeplay-helm
rules:
  - apiGroups: ['']
    resources: [configmaps, persistentvolumeclaims, pods, secrets, serviceaccounts, services]
    verbs: [get, list, watch, create, update, patch, delete]
  - apiGroups: [apps]
    resources: [deployments, replicasets, statefulsets]
    verbs: [get, list, watch, create, update, patch, delete]
  - apiGroups: [batch]
    resources: [cronjobs, jobs]
    verbs: [get, list, watch, create, update, patch, delete]
  - apiGroups: [networking.k8s.io]
    resources: [ingresses, networkpolicies]
    verbs: [get, list, watch, create, update, patch, delete]
  - apiGroups: [autoscaling]
    resources: [horizontalpodautoscalers]
    verbs: [get, list, watch, create, update, patch, delete]
  - apiGroups: [policy]
    resources: [poddisruptionbudgets]
    verbs: [get, list, watch, create, update, patch, delete]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: helm-demo-deployer
  namespace: kubeplay-helm
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: Role
  name: helm-demo-deployer
subjects:
  - kind: ServiceAccount
    name: helm-demo-deployer
    namespace: kubeplay-helm

Why does a Helm release need a service account and a Role at all? In this managed-extension setup, the Helm controller runs with --default-service-account=flux-applier. Instead of using its own controller permissions, it impersonates a service account in the HelmRelease’s namespace. Service accounts with the same name in different namespaces are different identities, so permissions granted to helm-demo-config/flux-applier do not carry over to kubeplay-helm/flux-applier.

This demo sidesteps that by explicitly selecting a different, purpose-built identity with spec.serviceAccountName: helm-demo-deployer. The ServiceAccount supplies the identity, the Role grants namespace-scoped permissions, and the RoleBinding connects them. Helm needs access to Secrets to store release history, plus permission to manage whatever resource types the chart creates. Without these permissions, installation fails early with something like secrets is forbidden, before any application pod gets created.

With a typical self-managed OSS Flux installation, the Helm controller’s own service account usually already has broad permissions, so this per-release RBAC may not be strictly necessary there. OSS Flux also supports restricted service-account impersonation if you want it. This is a controller-configuration distinction, not something tied to the chart source — switching from a Git chart to a HelmRepository later would not remove the need for this RBAC.

The Role grants permissions only within kubeplay-helm, including some optional chart resource kinds. If another chart needs additional namespaced resource kinds, add the required permissions to the Role. CRDs and other cluster-scoped resources are different: adding them to a namespaced Role does not grant access. Provision them separately with an authorized identity, or explicitly grant the Helm service account the necessary cluster-level permissions through a ClusterRole and ClusterRoleBinding.

Because gitops/helm/kustomization.yaml includes prerequisites as one of its resources, Terraform and the Flux configuration never need a separate manual RBAC step — publishing the Git path is enough.


Deploy It

I kept the same Terraform directory, state, cluster, and extension from the first post. If you have not set that up yet, do that first with bash deploy.sh --demo kustomize, then come back here.

cd AKS-Flux-Extension
az login
az account set --subscription "<your-subscription-name>"

If you already created terraform/terraform.tfvars for the Kustomize demo, you do not need to change it — the default Helm path already matches this repository’s layout:

git_repository_url = "https://github.com/YOUR-ACCOUNT/Code-Snippets.git"
git_branch         = "main"
gitops_path        = "./AKS-Flux-Extension/gitops/kustomize"

# Override only if your repository layout differs:
# gitops_helm_path = "./AKS-Flux-Extension/gitops/helm"

Then enable just the Helm lesson:

bash deploy.sh --demo helm

Use --demo all instead if you want both lessons enabled from a clean cluster. Either way, deploy.sh still runs terraform apply -auto-approve, so read your variables first if you want to see the plan before it runs.


Check That It Actually Worked

Same two-level check as the first post: Azure’s view of compliance, and the cluster’s view of the actual objects. These are the real outputs from my own cluster.

In the Azure portal, open the AKS resource and select GitOps. The helm-demo-config row shows Compliant and a provisioning state of Succeeded:

Azure portal GitOps list showing helm-demo-config as Compliant with state Succeeded in the helm-demo-config namespace

Select helm-demo-config to open its overview. Here you can check the source repository, tracked branch, last synced commit, and reconciliation settings. The repository shown is Code-Snippets, which supplies the Flux manifests; the separate chart source is defined inside those manifests.

Flux configuration overview showing four configuration objects, the Code-Snippets Git source on main, a one-minute sync interval, and cluster scope

These portal screenshots show the initial installation, before the values change and Helm upgrade demonstrated later in this post.

For the same compliance information from the CLI:

RESOURCE_GROUP="$(terraform -chdir=terraform output -raw resource_group_name)"
CLUSTER_NAME="$(terraform -chdir=terraform output -raw cluster_name)"

az k8s-configuration flux show --resource-group "$RESOURCE_GROUP" \
  --cluster-name "$CLUSTER_NAME" --cluster-type managedClusters --name helm-demo-config \
  --query "{complianceState:complianceState, statuses:statuses[].{kind:kind, name:name, namespace:namespace, complianceState:complianceState}}"
{
  "complianceState": "Compliant",
  "statuses": [
    { "kind": "GitRepository", "name": "helm-demo-config", "namespace": "helm-demo-config", "complianceState": "Compliant" },
    { "kind": "Kustomization", "name": "helm-demo-config-helm", "namespace": "helm-demo-config", "complianceState": "Compliant" },
    { "kind": "HelmRelease", "name": "helm-demo-kubeplay", "namespace": "kubeplay-helm", "complianceState": "Compliant" },
    { "kind": "GitRepository", "name": "helm-demo-chart", "namespace": "kubeplay-helm", "complianceState": "Compliant" }
  ]
}

Four tracked objects, not two. That is the first thing worth noticing: a Helm lesson involves two GitRepository objects, one Kustomization, and one HelmRelease, where the Kustomize lesson only ever had one GitRepository and one Kustomization. The next section explains why.

The portal’s Configuration objects view lists those four objects and their namespaces. Its Applied by column links helm-demo-chart and helm-demo-kubeplay to the parent helm-demo-config-helm Kustomization:

Configuration objects view showing two GitRepositories, one Kustomization, and one HelmRelease, all Compliant, with the chart source and release applied by helm-demo-config-helm

From inside the cluster, the controllers doing the work are the same flux-system pods as before, plus two I had not used yet:

kubectl get pods -n flux-system
NAME                                       READY   STATUS    RESTARTS   AGE
fluxconfig-agent-7c5d9bc6dc-thkcj          2/2     Running   0          18m
fluxconfig-controller-56f5b6c7c6-jhzmp     2/2     Running   0          18m
helm-controller-6559bbfbfd-blpv4           1/1     Running   0          18m
kustomize-controller-7598648dff-tf586      1/1     Running   0          18m
notification-controller-86cf699f75-vk2tg   1/1     Running   0          18m
source-controller-84449dc7b5-9j47h         1/1     Running   0          18m

helm-controller is new here. It is already part of the managed extension, it just had nothing to do until this lesson created a HelmRelease.

What Azure Generated For You

As with the Kustomize demo, I never wrote these Flux objects by hand — Terraform and the Git path generated them. Here is what is actually on my cluster, with noisy fields (UIDs, resource versions, timestamps) removed for readability.

The Azure-generated source, in the helm-demo-config namespace. This is the one azurerm_kubernetes_flux_configuration created for me, the same way cluster-config’s GitRepository was generated in the first post:

apiVersion: source.toolkit.fluxcd.io/v1
kind: GitRepository
metadata:
  name: helm-demo-config
  namespace: helm-demo-config
  labels:
    clusterconfig.azure.com/is-managed: "true"
    clusterconfig.azure.com/name: helm-demo-config
    clusterconfig.azure.com/namespace: helm-demo-config
  ownerReferences:
  - apiVersion: clusterconfig.azure.com/v1alpha1
    blockOwnerDeletion: true
    controller: true
    kind: FluxConfig
    name: helm-demo-config
spec:
  interval: 1m0s
  ref:
    branch: main
  timeout: 2m0s
  url: https://github.com/kasunsjc/Code-Snippets.git
status:
  artifact:
    revision: main@sha1:c0d7b501706d79dbbc971552aecec15811501754
    size: 454105
  conditions:
  - message: stored artifact for revision 'main@sha1:c0d7b501706d79dbbc971552aecec15811501754'
    reason: Succeeded
    status: "True"
    type: Ready

Notice the clusterconfig.azure.com labels and the FluxConfig owner reference — exactly the markers from the first post that tell you Azure generated and owns this object. Its artifact is 454 KB because it clones the whole Code-Snippets repository, same as cluster-config did.

The Kustomize-applied source, in the kubeplay-helm namespace. This one I wrote by hand in gitrepository.yaml, and it reconciles through the Flux Kustomization, not directly from Terraform:

apiVersion: source.toolkit.fluxcd.io/v1
kind: GitRepository
metadata:
  name: helm-demo-chart
  namespace: kubeplay-helm
  labels:
    kustomize.toolkit.fluxcd.io/name: helm-demo-config-helm
    kustomize.toolkit.fluxcd.io/namespace: helm-demo-config
spec:
  interval: 1m
  ref:
    branch: main
  timeout: 60s
  url: https://github.com/kasunsjc/k8s-demo-sample-app
  ignore: |
    /*
    !/deploy/helm/kubeplay
status:
  artifact:
    revision: main@sha1:2a016b705539b99d507c46603b582387b2ccc3f7
    size: 6364
  conditions:
  - message: stored artifact for revision 'main@sha1:2a016b705539b99d507c46603b582387b2ccc3f7'
    reason: Succeeded
    status: "True"
    type: Ready

Different labels this time: kustomize.toolkit.fluxcd.io/* instead of clusterconfig.azure.com/*, and no FluxConfig owner reference. This object is not Azure-generated — it is a plain YAML file I wrote, applied like any other resource by the helm-demo-config-helm Kustomization. Its artifact is only 6 KB because the ignore block excludes everything except the chart directory. Two objects, same kind, two very different ownership stories — that distinction was not obvious to me until I compared the actual YAML.

The Kustomization that ties it together, in helm-demo-config:

apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
  name: helm-demo-config-helm
  namespace: helm-demo-config
  labels:
    clusterconfig.azure.com/is-managed: "true"
    clusterconfig.azure.com/name: helm-demo-config
    clusterconfig.azure.com/namespace: helm-demo-config
  ownerReferences:
  - apiVersion: clusterconfig.azure.com/v1alpha1
    blockOwnerDeletion: true
    controller: true
    kind: FluxConfig
    name: helm-demo-config
spec:
  interval: 1m0s
  path: ./AKS-Flux-Extension/gitops/helm
  prune: true
  retryInterval: 30s
  serviceAccountName: flux-applier
  sourceRef:
    kind: GitRepository
    name: helm-demo-config
    namespace: helm-demo-config
  timeout: 10m0s
  wait: true
status:
  conditions:
  - message: 'Applied revision: main@sha1:c0d7b501706d79dbbc971552aecec15811501754'
    reason: ReconciliationSucceeded
    status: "True"
    type: Ready
  - message: Health check passed in 71.627067ms
    reason: Succeeded
    status: "True"
    type: Healthy
  inventory:
    entries:
    - id: _kubeplay-helm__Namespace
      v: v1
    - id: kubeplay-helm_helm-demo-deployer__ServiceAccount
      v: v1
    - id: kubeplay-helm_helm-demo-deployer_rbac.authorization.k8s.io_Role
      v: v1
    - id: kubeplay-helm_helm-demo-deployer_rbac.authorization.k8s.io_RoleBinding
      v: v1
    - id: kubeplay-helm_helm-demo-kubeplay_helm.toolkit.fluxcd.io_HelmRelease
      v: v2
    - id: kubeplay-helm_helm-demo-chart_source.toolkit.fluxcd.io_GitRepository
      v: v1
  lastAppliedRevision: main@sha1:c0d7b501706d79dbbc971552aecec15811501754

This is the part that explains the layering: status.inventory here only has six entries — the namespace, the three RBAC objects, the HelmRelease, and the GitRepository. There is no Deployment, Service, StatefulSet, or CronJob in this list, even though the chart creates all of those: the Kustomization applies the gitops/helm manifests, while Helm manages the chart’s resources. Because wait: true is set, the Kustomization also checks the health of its applied resources, including the HelmRelease, before reporting success. serviceAccountName: flux-applier here is this Kustomization’s own identity (with cluster-wide permissions, same as the first post), which is a completely different identity from helm-demo-deployer inside the HelmRelease itself.

The HelmRelease, in kubeplay-helm, is where the actual chart installation is tracked:

apiVersion: helm.toolkit.fluxcd.io/v2
kind: HelmRelease
metadata:
  name: helm-demo-kubeplay
  namespace: kubeplay-helm
spec:
  chart:
    spec:
      chart: ./deploy/helm/kubeplay
      reconcileStrategy: Revision
      sourceRef:
        kind: GitRepository
        name: helm-demo-chart
  releaseName: helm-demo-kubeplay
  serviceAccountName: helm-demo-deployer
  interval: 5m
  timeout: 10m
status:
  conditions:
  - message: Helm install succeeded for release kubeplay-helm/helm-demo-kubeplay.v1
      with chart kubeplay@0.1.1+2a016b705539
    reason: InstallSucceeded
    status: "True"
    type: Ready
  - message: Helm install succeeded for release kubeplay-helm/helm-demo-kubeplay.v1
      with chart kubeplay@0.1.1+2a016b705539
    reason: InstallSucceeded
    status: "True"
    type: Released
  history:
  - action: install
    chartName: kubeplay
    chartVersion: 0.1.1+2a016b705539
    name: helm-demo-kubeplay
    namespace: kubeplay-helm
    status: deployed
    version: 1
  inventory:
    entries:
    - id: kubeplay-helm_ui-gateway_apps_Deployment
      v: v1
    - id: kubeplay-helm_notes-api_apps_Deployment
      v: v1
    - id: kubeplay-helm_inspector-api_apps_Deployment
      v: v1
    - id: kubeplay-helm_worker_apps_Deployment
      v: v1
    - id: kubeplay-helm_redis_apps_StatefulSet
      v: v1
    - id: kubeplay-helm_worker-report_batch_CronJob
      v: v1
    - id: kubeplay-helm_inspector-api_policy_PodDisruptionBudget
      v: v1
    - id: kubeplay-helm_redis-allow-clients_networking.k8s.io_NetworkPolicy
      v: v1
    - id: kubeplay-helm_notes-api-allow-gateway_networking.k8s.io_NetworkPolicy
      v: v1

(I trimmed the Services, Secrets, ConfigMap, and ServiceAccounts from this inventory listing for space — the full list has 18 entries.)

This is the second, separate inventory I mentioned above, owned by the Helm controller instead of the Kustomize controller. status.history is Helm’s own release history (install, then one entry per upgrade), and status.inventory is every object that release currently owns and will prune on an uninstall or on removal from Git. If you have used Helm directly before, this is the same bookkeeping helm list and helm get manifest give you, just reconciled continuously instead of run on demand.

Put together: the Flux Kustomization owns the namespace, RBAC, and the two Flux objects (GitRepository and HelmRelease); the HelmRelease separately owns everything the chart actually creates. Two controllers, two inventories, one continuously reconciled result.

Confirm the Application Resources

The inventory list is useful, but seeing the actual running objects is more convincing:

kubectl get all -n kubeplay-helm
NAME                                 READY   STATUS      RESTARTS   AGE
pod/inspector-api-66c7f7b77d-94pql   1/1     Running     0          16m
pod/inspector-api-66c7f7b77d-f64l7   1/1     Running     0          16m
pod/inspector-api-66c7f7b77d-hzp8w   1/1     Running     0          16m
pod/notes-api-58b66cd549-g8nj7       1/1     Running     0          16m
pod/notes-api-58b66cd549-vddhq       1/1     Running     0          16m
pod/redis-0                          1/1     Running     0          16m
pod/ui-gateway-6cdcd5466f-6tmqm      1/1     Running     0          16m
pod/ui-gateway-6cdcd5466f-xnvdf      1/1     Running     0          16m
pod/worker-67655dcd7d-t722d          1/1     Running     0          16m
pod/worker-report-29905620-qhkxc     0/1     Completed   0          2m57s

NAME                    TYPE        CLUSTER-IP     EXTERNAL-IP   PORT(S)    AGE
service/inspector-api   ClusterIP   10.0.231.211   <none>        80/TCP     16m
service/notes-api       ClusterIP   10.0.247.201   <none>        80/TCP     16m
service/redis           ClusterIP   None           <none>        6379/TCP   16m
service/ui-gateway      ClusterIP   10.0.168.237   <none>        80/TCP     16m

NAME                            READY   UP-TO-DATE   AVAILABLE   AGE
deployment.apps/inspector-api   3/3     3            3           16m
deployment.apps/notes-api       2/2     2            2           16m
deployment.apps/ui-gateway      2/2     2            2           16m
deployment.apps/worker          1/1     1            1           16m

NAME                     READY   AGE
statefulset.apps/redis   1/1     16m

NAME                          SCHEDULE      SUSPEND   ACTIVE   LAST SCHEDULE   AGE
cronjob.batch/worker-report   */5 * * * *   False     0        2m58s           16m

Every one of these — four Deployments, one StatefulSet, four Services, a CronJob, and their Pods — came from the helm-demo-deployer service account installing the chart, not from anything I ran by hand. The inspector-api Deployment shows 3/3, matching the inspector.replicas: 3 value I set in helmrelease.yaml.

Find the UI service and port-forward to see it:

kubectl get svc -n kubeplay-helm
kubectl port-forward -n kubeplay-helm service/ui-gateway 8080:80

Open http://localhost:8080 while the port-forward is running:

KubePlay UI deployed by the Helm-based Flux configuration, showing the configured title and the running services

The namespace, service account, RBAC, chart source, release, and every application object came from Git. The only kubectl commands I ran were to look at the result, not to create it.


Try It: Change a Value Through Git

The point of this demo is seeing a Helm upgrade happen the same way the Kustomize demo showed a manifest change happen: through a Git push, not a pipeline or a helm upgrade command.

The current repository already contains my updated title and four replicas. To repeat the same change, first restore the initial values in the repository and branch Flux tracks. Use a fork you can push to if necessary, and configure Flux to track that fork. Edit only these fields in the existing spec.values block of AKS-Flux-Extension/gitops/helm/helmrelease.yaml, keeping the other settings, including inspector.hpa.enabled: false:

spec:
  values:
    ui:
      title: KubePlay via Flux
    inspector:
      replicas: 3

Commit and push the baseline to the tracked branch, or merge it there through a pull request. From the AKS-Flux-Extension directory, for a direct push:

git add gitops/helm/helmrelease.yaml
git commit -m "Restore KubePlay values for the upgrade demo"
git push

Before continuing, check that the Kustomization applied the baseline commit from the tracked branch, the HelmRelease has the initial values and Ready=True for its current generation, and the Deployment is 3/3 ready:

kubectl get kustomization helm-demo-config-helm -n helm-demo-config \
  -o jsonpath='{.status.lastAppliedRevision}{"\n"}'
kubectl get helmrelease helm-demo-kubeplay -n kubeplay-helm -o yaml
kubectl get deployment inspector-api -n kubeplay-helm

Compare the Kustomization revision with the tracked branch’s baseline commit. In the HelmRelease output, check the values, that metadata.generation matches status.observedGeneration, and that the Ready condition is True with the same observedGeneration. If you merged a pull request, use the resulting tracked-branch commit rather than assuming it matches your local commit.

Now make the same two changes I tested: the UI title from KubePlay via Flux to KubePlay via Flux Helm, and the inspector replica count from 3 to 4. Again, edit these fields in the existing block without replacing the other values:

spec:
  values:
    ui:
      title: KubePlay via Flux Helm
    inspector:
      replicas: 4

Commit and push to the branch Flux tracks, or merge your pull request into that branch. From the AKS-Flux-Extension directory:

git add gitops/helm/helmrelease.yaml
git commit -m "Update KubePlay title and inspector replica count"
git push

My commit e513495 contains just those two value changes:

GitHub diff changing the KubePlay title to KubePlay via Flux Helm and inspector replicas from 3 to 4

Follow the Change From Git to Helm

Watch the release while Flux picks up the commit:

kubectl get helmrelease helm-demo-kubeplay -n kubeplay-helm --watch

The Git source revision and the Kustomization’s applied revision tell you whether the configuration repository change reached the cluster:

kubectl get gitrepository helm-demo-config -n helm-demo-config \
  -o jsonpath='{.status.artifact.revision}{"\n"}'
kubectl get kustomization helm-demo-config-helm -n helm-demo-config \
  -o jsonpath='{.status.lastAppliedRevision}{"\n"}'

After reconciliation, both reported my new commit:

main@sha1:e51349572bd0ad633e8c89fd8be1ac467b03edb6
main@sha1:e51349572bd0ad633e8c89fd8be1ac467b03edb6

Then check the Helm release itself:

kubectl get helmrelease helm-demo-kubeplay -n kubeplay-helm -o yaml

This is an excerpt from my cluster after the upgrade, with unrelated fields omitted:

metadata:
  generation: 2
status:
  observedGeneration: 2
  conditions:
  - lastTransitionTime: "2026-11-11T22:30:32Z"
    message: Helm upgrade succeeded for release kubeplay-helm/helm-demo-kubeplay.v2
      with chart kubeplay@0.1.1+2a016b705539
    observedGeneration: 2
    reason: UpgradeSucceeded
    status: "True"
    type: Ready
  history:
  - action: upgrade
    chartName: kubeplay
    chartVersion: 0.1.1+2a016b705539
    status: deployed
    version: 2
  - chartName: kubeplay
    chartVersion: 0.1.1+2a016b705539
    status: superseded
    version: 1
  lastAttemptedReleaseAction: upgrade
  lastAttemptedReleaseActionDuration: 11.231033611s

Here is how I read that:

  • generation: 2 and observedGeneration: 2 show that the controller has processed the updated release spec. Do not rely on an old Ready=True condition without checking its observedGeneration.
  • reason: UpgradeSucceeded and history[0].version: 2 confirm a successful Helm upgrade, not another install. Release revision 1 is now superseded.
  • The chart version stayed 0.1.1+2a016b705539. I changed values in the configuration repository, not the chart in k8s-demo-sample-app. The configuration Git SHA, chart version, and Helm release revision are three different things; a values-only upgrade does not need a new chart version.

The controller logs captured the handoff too:

kubectl logs -n flux-system deployment/helm-controller --since=10m

These are selected log fields from this run; I removed the repeated controller and reconciliation identifiers:

{"ts":"2026-11-11T22:30:21.150Z","msg":"release out-of-sync with desired state: release config values changed"}
{"ts":"2026-11-11T22:30:21.186Z","msg":"running 'upgrade' action with timeout of 10m0s"}
{"ts":"2026-11-11T22:30:32.486Z","msg":"release in-sync with desired state"}

Combining the Git commit timestamp and the source, Kustomize, and Helm controller logs gives this sequence. All times are UTC on 11 November 2026:

TimeWhat happened
22:30:08The values change was committed to main.
22:30:20source-controller stored the new configuration repository artifact.
22:30:21kustomize-controller applied the updated HelmRelease; helm-controller detected the changed values and started an upgrade.
22:30:32The Helm upgrade succeeded as release revision 2.
22:30:36The parent Kustomization finished reconciliation after its health checks.

That was about 24 seconds from the commit timestamp to Helm reporting success in this run, not a timing guarantee. There was no second Terraform apply, manual reconciliation request, or helm upgrade command.

Verify the Replicas and the UI

Check the workload independently of the release status:

kubectl get deployment inspector-api -n kubeplay-helm
NAME            READY   UP-TO-DATE   AVAILABLE   AGE
inspector-api   4/4     4            4           45m

Refresh the port-forwarded UI. If the upgrade replaced the gateway Pod and ended your existing port-forward, rerun it first:

kubectl port-forward -n kubeplay-helm service/ui-gateway 8080:80

The new title is KubePlay via Flux Helm, and the pod fleet shows four serving inspector Pods:

KubePlay UI after the Git-driven Helm upgrade, showing KubePlay via Flux Helm and four serving inspector Pods

The fleet view discovers Pods by polling the Service, so it may take a few requests to show all four. Use the Deployment’s 4/4 readiness as the Kubernetes check rather than treating the UI counter as the desired replica count.

This test changed only the inline values. reconcileStrategy: Revision is what also allows chart-template changes in the chart’s own Git repository to produce a new chart artifact without bumping Chart.yaml each time; it is not what triggers a values-only upgrade.


Try It: Recover From Configuration Drift

A Git change is intentional. Drift is a change made directly in the cluster that disagrees with the desired state. In this setup, recovery depends on which object someone changes:

Manual changeWhat restores it
Edit the HelmRelease values with kubectlkustomize-controller reapplies the HelmRelease manifest from Git.
Scale a Deployment or edit another Helm-managed workloadhelm-controller corrects it when Helm drift detection is enabled.

Use the disposable demo for these tests, not a production workload. The examples assume you completed the previous Git change and now have inspector.replicas: 4.

Change the HelmRelease Configuration Directly

The parent Kustomization already reconciles gitops/helm every minute. To see it restore a value without a new Git commit, temporarily change the live HelmRelease to one inspector replica:

kubectl patch helmrelease helm-demo-kubeplay -n kubeplay-helm \
  --type=merge -p '{"spec":{"values":{"inspector":{"replicas":1}}}}'

kubectl get helmrelease helm-demo-kubeplay -n kubeplay-helm \
  -o custom-columns=NAME:.metadata.name,REPLICAS:.spec.values.inspector.replicas \
  --watch

You should see the value return to 4 after the parent Kustomization reconciles. Stop the watch with Ctrl+C. Git still says four replicas, so the manual edit is overwritten even though there is no new commit.

The Helm controller may process the temporary value before Kustomize restores it, causing an upgrade to one replica followed by an upgrade back to four. Alternatively, Kustomize may restore the value before Helm acts. Do not assume the Deployment will visibly scale down just because the HelmRelease briefly changed.

This is configuration drift correction by Kustomize, not Helm workload drift detection.

Recover Helm-Managed Workloads

Directly running kubectl scale deployment/inspector-api changes a different object: the Deployment rendered by Helm. The parent Kustomization does not manage that Deployment directly, and a five-minute HelmRelease interval alone does not guarantee that manual workload changes are undone.

To enable recovery, I added this field under the existing spec in gitops/helm/helmrelease.yaml and pushed the change to Git:

spec:
  driftDetection:
    mode: enabled

The initial HelmRelease shown earlier predates this change; the current repository manifest includes it. If you are adapting an older manifest, add the field while keeping the existing chart settings and values.

After the commit, the configuration GitRepository stored revision 0c8d5f97900aea806f2948f2c72f5e84887e6c4e, and the parent Kustomization reported the same revision as applied. Verify that Git reconciliation applied the setting before testing:

kubectl get helmrelease helm-demo-kubeplay -n kubeplay-helm \
  -o custom-columns=MODE:.spec.driftDetection.mode,GENERATION:.metadata.generation,OBSERVED:.status.observedGeneration

In my cluster, the result was:

MODE      GENERATION   OBSERVED
enabled   3            3

The HelmRelease also reported Ready=True and Drifted=False with reason NoDriftDetected for generation 3. That confirms the setting was reconciled and no drift was detected at that point; it does not by itself demonstrate a correction.

Check that MODE is enabled and the observed generation matches the current generation. Then, on the disposable demo cluster, deliberately scale the live Deployment:

kubectl scale deployment/inspector-api -n kubeplay-helm --replicas=1
kubectl get deployment inspector-api -n kubeplay-helm --watch

With drift detection enabled, Helm’s controller compares the live resources with the rendered release manifest stored by Helm and corrects the difference. The Deployment should return to four replicas and eventually 4/4 ready. Allow for the HelmRelease’s five-minute reconciliation interval and Pod startup time; this is not an instant correction.

In my test on November 12, the Deployment controller recorded the scale-down from four to one at 13:03:27 UTC. The Helm controller detected and corrected the drift at 13:08:12 UTC, and my watch observed all four Pods ready by 13:08:18 UTC:

TIME (UTC)   DESIRED   CURRENT   READY   AVAILABLE
13:04:36     1         1         1       1
13:08:13     4         4         1       1
13:08:18     4         4         4       4

These are observations from this run, not a guaranteed recovery time. The relevant Helm controller log messages were:

13:08:12  detected changes in cluster state: removed: 0, changed: 1, excluded: 0
13:08:12  running 'correct cluster drift' action with timeout of 10m0s
13:08:13  release in-sync with desired state

The HelmRelease events identified the object that changed:

Warning  DriftDetected   Deployment/kubeplay-helm/inspector-api changed (0 additions, 1 changes, 0 removals)
Normal   DriftCorrected  Deployment/kubeplay-helm/inspector-api configured

The controller also logged a Drifted status-condition merge conflict immediately after the correction. It retried, reported the release in sync again, and the final HelmRelease conditions were Ready=True and Drifted=False (NoDriftDetected). The conflict did not prevent recovery in this run; investigate recurring errors rather than assuming every conflict is harmless.

For evidence of the detection and correction, inspect events and controller logs:

kubectl get events -n kubeplay-helm --sort-by=.lastTimestamp
kubectl logs -n flux-system deployment/helm-controller --since=15m

The Git commit can stay unchanged throughout this test: Flux is restoring the existing desired state, not deploying a new Git revision. For a permanent change, edit the HelmRelease values in Git instead.

Avoid competing with autoscalers. This demo disables the inspector HPA. If HPA or KEDA owns a workload’s replica count, configure drift-detection ignore rules for that field rather than having Flux reset the autoscaler’s changes. mode: warn only reports drift; mode: enabled also corrects it. See the Flux Helm drift detection documentation for ignore rules and behavior.

This recovery applies to Kubernetes resources managed by Flux. It does not automatically revert portal edits to the Terraform-owned Azure Flux configuration; those need a reviewed Terraform plan and apply.


Removing Just This Lesson

Because the two Flux configurations are independent, I can remove the Helm lesson while leaving Podinfo and the cluster running. First stop the release from reconciling by removing helmrelease.yaml from gitops/helm/kustomization.yaml and publishing that change, then wait for the uninstall:

kubectl wait --for=delete helmrelease/helm-demo-kubeplay -n kubeplay-helm --timeout=600s

Once that succeeds, remove the Azure Flux configuration itself:

export ARM_SUBSCRIPTION_ID="$(az account show --query id --output tsv)"
terraform -chdir=terraform plan -var='enabled_demos=["kustomize"]'
terraform -chdir=terraform apply -var='enabled_demos=["kustomize"]'

Review the plan before applying — you want to see only the Helm configuration being removed. Garbage collection then removes the kubeplay-helm namespace along with everything in it, including any demo data, so check for retained persistent volumes afterward if the chart created any. The Kustomize foundation and the managed extension are untouched.

I deliberately did not use cleanup.sh for this: it destroys the whole cluster, which is the wrong tool for removing one lesson while keeping the others.


When It Does Not Work

A few failure modes were specific to the Helm path, on top of the general checklist from the first post:

SymptomWhat to check
secrets is forbidden during installThe Role bound to serviceAccountName does not grant access to Secrets, or serviceAccountName was left unset so it fell back to the wrong namespace’s flux-applier.
HelmChart not readyThe GitRepository’s ignore block may be excluding the chart path, or chart.spec.chart does not match the path inside the source.
Install succeeds, chart’s extra resources failThe Role’s resource list has not been kept in sync with everything the chart actually creates.
Upgrade never triggers after a chart-only changeConfirm reconcileStrategy: Revision is set, and that the GitRepository picked up the new commit (kubectl describe gitrepository helm-demo-chart -n kubeplay-helm).
A manually scaled Helm Deployment stays changedEnable spec.driftDetection.mode: enabled through Git, check for ignore rules, and inspect Helm controller events for correction failures.
helm-demo-config compliant, but cluster-config affectedIt should not be — they are independent. If you see cross-impact, check for a shared namespace or object name between the two Git paths.

These commands usually explain what happened:

kubectl describe gitrepository helm-demo-chart -n kubeplay-helm
kubectl describe helmrelease helm-demo-kubeplay -n kubeplay-helm
kubectl logs -n flux-system deployment/helm-controller --tail=100
kubectl logs -n flux-system deployment/source-controller --tail=100

What’s Next

This post added a second, independent lesson to the same cluster: a Helm chart deployed through Git, with its own RBAC so the managed extension’s Helm controller can install it safely. The Kustomize demo from the first post kept running the whole time, unaffected.

A natural next lesson is swapping the Git-based chart source for a published HelmRepository or an OCI registry chart, and seeing what changes (and what does not) compared with what is in this post. I will cover that, along with namespace-scoped Flux configurations for multi-team clusters, in later posts in this series.

Found this helpful?
Back to all posts