Flux deployments can get out of order, causing your applications to fail because they’re missing dependencies.
Here’s how to control Flux deployment order with dependsOn:
apiVersion: helm.toolkit.fluxcd.io/v2beta1
kind: HelmRelease
metadata:
name: redis
namespace: flux-system
spec:
interval: 10m
chart:
spec:
chart: redis
version: "17.x.x"
sourceRef:
kind: HelmRepository
name: bitnami
namespace: flux-system
values:
architecture: standalone
---
apiVersion: helm.toolkit.fluxcd.io/v2beta1
kind: HelmRelease
metadata:
name: webapp
namespace: default
spec:
interval: 10m
chart:
spec:
chart: my-webapp
version: "1.x.x"
sourceRef:
kind: GitRepository
name: my-charts
namespace: flux-system
dependsOn:
- name: redis
namespace: flux-system
values:
redisHost: redis.flux-system.svc.cluster.local
The dependsOn field in a HelmRelease tells Flux that this HelmRelease cannot be reconciled until all the HelmRelease objects listed in dependsOn have been successfully reconciled. Flux traverses the dependency graph and ensures that parent resources are healthy before proceeding with child resources.
Let’s look at a more complex scenario. Imagine you have a PostgreSQL database, a Redis cache, and your webapp. The webapp needs both PostgreSQL and Redis to be up and running.
apiVersion: helm.toolkit.fluxcd.io/v2beta1
kind: HelmRelease
metadata:
name: postgresql
namespace: flux-system
spec:
interval: 10m
chart:
spec:
chart: postgresql
version: "11.x.x"
sourceRef:
kind: HelmRepository
name: bitnami
namespace: flux-system
values:
architecture: standalone
---
apiVersion: helm.toolkit.fluxcd.io/v2beta1
kind: HelmRelease
metadata:
name: redis
namespace: flux-system
spec:
interval: 10m
chart:
spec:
chart: redis
version: "17.x.x"
sourceRef:
kind: HelmRepository
name: bitnami
namespace: flux-system
values:
architecture: standalone
---
apiVersion: helm.toolkit.fluxcd.io/v2beta1
kind: HelmRelease
metadata:
name: webapp
namespace: default
spec:
interval: 10m
chart:
spec:
chart: my-webapp
version: "1.x.x"
sourceRef:
kind: GitRepository
name: my-charts
namespace: flux-system
dependsOn:
- name: postgresql
namespace: flux-system
- name: redis
namespace: flux-system
values:
databaseHost: postgresql.flux-system.svc.cluster.local
redisHost: redis.flux-system.svc.cluster.local
In this example, Flux will first ensure postgresql and redis are healthy. Once both are confirmed to be running without errors, Flux will then proceed to reconcile the webapp HelmRelease. This prevents the webapp from starting up and immediately failing because its dependencies aren’t ready.
The dependsOn field supports multiple dependencies. You can list as many HelmRelease objects as needed. Flux builds a directed acyclic graph (DAG) of these dependencies. If a circular dependency is detected (e.g., A depends on B, and B depends on A), Flux will report an error and refuse to reconcile, preventing an infinite loop.
The name and namespace fields within dependsOn are crucial. They must exactly match the metadata.name and metadata.namespace of the HelmRelease that is being depended upon. This ensures Flux can correctly identify and track the dependent resources.
Flux doesn’t just check if the dependent HelmRelease exists; it checks if it’s healthy. A HelmRelease is considered healthy when its associated Helm chart has been successfully installed or upgraded, and the deployed Kubernetes resources (Deployments, StatefulSets, etc.) are in a ready state. If a dependent HelmRelease encounters an error during reconciliation, Flux will pause the reconciliation of the dependent HelmRelease until the error in the parent is resolved.
You can also use dependsOn with other Flux resource types, like Kustomization, to manage deployment order across different reconciliation mechanisms. For instance, a Kustomization that deploys your application might depend on a HelmRelease that sets up your database.
Consider a scenario where you have a GitRepository source, and you want to deploy a Kustomization only after a specific HelmRelease is ready.
apiVersion: helm.toolkit.fluxcd.io/v2beta1
kind: HelmRelease
metadata:
name: postgresql
namespace: flux-system
spec:
# ... (PostgreSQL HelmRelease definition)
---
apiVersion: kustomize.toolkit.fluxcd.io/v1beta2
kind: Kustomization
metadata:
name: webapp-kustomization
namespace: default
spec:
interval: 10m
path: ./apps/webapp
sourceRef:
kind: GitRepository
name: my-git-repo
namespace: flux-system
dependsOn:
- name: postgresql
namespace: flux-system
Here, the webapp-kustomization will only be applied by Flux after the postgresql HelmRelease has been successfully reconciled. This is powerful for orchestrating complex deployments involving both Helm charts managed by HelmRelease and raw Kubernetes manifests managed by Kustomization.
The dependsOn mechanism is fundamental to achieving robust, ordered deployments in Flux. It allows you to explicitly define the relationships between your Kubernetes resources, ensuring that components are deployed in a sequence that respects their interdependencies, thereby preventing runtime failures due to missing services or misconfigured endpoints.
When Flux reconciles a HelmRelease that has dependsOn specified, it first queries the Kubernetes API for the status of each dependent resource. If any of the listed dependencies are not in a Ready or Success state, Flux will log a message indicating the dependency is not met and will defer the reconciliation of the current HelmRelease. Only when all dependencies are healthy will Flux proceed with installing or upgrading the Helm chart for the current HelmRelease. This state-checking is performed on every reconciliation interval, ensuring that if a dependency later fails, the dependent resource will also be paused.
If you have a HelmRelease that depends on another HelmRelease which is itself dependent on a third, Flux builds this chain. For example, if WebApp depends on Redis, and Redis depends on Zookeeper, Flux will ensure Zookeeper is ready, then Redis, and finally WebApp. This cascade of checks ensures your entire application stack is deployed in the correct order.
The most counterintuitive aspect of dependsOn is that it doesn’t just check for the existence of the dependent resource; it checks for its readiness. A HelmRelease can exist in the cluster but be in a failing state. Flux will correctly identify this as an unmet dependency and will not proceed with the dependent resource. This prevents situations where a resource is technically present but non-functional, which would still lead to application errors.
The next thing you’ll want to manage is how Flux handles drift detection and remediation for your Helm releases.