Upgrade Advisory

This documentation is for Flux (v1) and Helm Operator (v1). Both projects are in maintenance mode and will soon reach end-of-life. We strongly recommend you familiarise yourself with the newest Flux and start looking at your migration path.

For documentation regarding the latest Flux, please refer to this section.

Daemon (fluxd)


Flux daemon (fluxd, aka Flux agent) allows automation of application deployments and version control of cluster configuration. Version controlling of cluster manifests provides reproducibility and a historical trail of events.


Continuous Deployment

  1. Flux daemon monitors user git repo Kubernetes manifests for changes, which it then deploys to the cluster.

  2. Flux daemon monitors container registry for running container image updates. Detection of an image change (running container image tag vs container registry image tag) triggers k8s manifest update, which is committed to the user git repository, then deployed to the Kubernetes cluster.

Deployment approaches

  1. Automate vs Deautomate

    Deployment happens automatically when a new image tag is detected. Deautomated deployment will not proceed until manually released (through the CLI tool fluxctl).

  2. Lock vs Unlock

    Deployment is pinned to a particular image tag. New deployment will not proceed upon triggered release.

Setup and configuration

fluxd requires setup and offers customization through a multitude of flags.

–listen -l:3030listen address where /metrics and API will be served
–listen-metricslisten address for /metrics endpoint
–kubernetes-kubectloptional, explicit path to kubectl tool
–versionfalseoutput the version number and exit
Git repo & key etc.
–git-urlURL of git repo with Kubernetes manifests; e.g., git@github.com:fluxcd/flux-get-started
–git-branchmasterbranch of git repo to use for Kubernetes manifests
–git-ci-skipfalsewhen set, fluxd will append \n\n[ci skip] to its commit messages
–git-ci-skip-message""if provided, fluxd will append this to commit messages (overrides –git-ci-skip`)
–git-pathpath within git repo to locate Kubernetes manifests (relative path)
–git-userWeave Fluxusername to use as git committer
–git-emailsupport@weave.worksemail to use as git committer
–git-set-authorfalseif set, the author of git commits will reflect the user who initiated the commit and will differ from the git committer
–git-gpg-key-importif set, fluxd will attempt to import the gpg key(s) found on the given path
–git-signing-keyif set, commits made by fluxd to the user git repo will be signed with the provided GPG key.
–git-secretif set and a .gitsecret directory exist in the root of the git repository, Flux will execute a git secret reveal -f in the working clone before performing any operations
–git-labellabel to keep track of sync progress; overrides both –git-sync-tag and –git-notes-ref
–git-sync-tagflux-synctag to use to mark sync progress for this cluster (old config, still used if –git-label is not supplied)
–git-notes-reffluxref to use for keeping commit annotations in git notes
–git-poll-interval5mperiod at which to fetch any new commits from the git repo
–git-timeout20sduration after which git operations time out
–git-readonlyfalseIf true, the git repo will be considered read-only, and Flux will not attempt to write to it. Implies –sync-state=secret
syncing: control over how config is applied to the cluster
–sync-interval5mapply the git config to the cluster at least this often. New commits may provoke more frequent syncs
–sync-timeout1mduration after which sync operations time out
–sync-garbage-collectionfalsewhen set, fluxd will delete resources that it created, but are no longer present in git
–sync-garbage-collection-dryfalseonly log what would be garbage collected, rather than deleting. Implies –sync-garbage-collection
–sync-stategitWhere to keep sync state; either a tag in the upstream repo (git), or as an annotation on the SSH secret (secret)
registry cache: (none of these need overriding, usually)
–memcached-hostnamememcachedhostname for memcached service to use for caching image metadata
–memcached-timeout1smaximum time to wait before giving up on memcached requests
–memcached-servicememcachedSRV service used to discover memcache servers
–registry-cache-expiry1hDuration to keep cached registry tag info. Must be < 1 month.
–registry-rps200maximum registry requests per second per host
–registry-burst125maximum number of warmer connections to remote and memcache
–registry-insecure-host[]registry hosts to use HTTP for (instead of HTTPS)
–registry-exclude-image["k8s.gcr.io/*"]do not scan images that match these glob expressions
–registry-include-imagenilscan only images that match these glob expressions (the default, nil, means include everything)
–registry-use-labels["index.docker.io/weaveworks/*", "index.docker.io/fluxcd/*"]use the timestamp (RFC3339) from labels for (canonical) image refs that match these glob expressions
–docker-config""path to a Docker config file with default image registry credentials
–registry-ecr-region[]allow these AWS regions when scanning images from ECR (multiple values allowed); defaults to the detected cluster region
–registry-ecr-include-id[]include these AWS account ID(s) when scanning images in ECR (multiple values allowed); empty means allow all, unless excluded
–registry-ecr-exclude-id[<EKS SYSTEM ACCOUNT>]exclude these AWS account ID(s) when scanning ECR (multiple values allowed); defaults to the EKS system account, so system images will not be scanned
–registry-require[]exit with an error if the given services are not available. Useful for escalating misconfiguration or outages that might otherwise go undetected. Presently supported values: {ecr}
–registry-disable-scanningfalsedo not scan container image registries to fill in the registry cache
k8s-secret backed ssh keyring configuration
–k8s-secret-nameflux-git-deployname of the k8s secret used to store the private SSH key
–k8s-secret-volume-mount-path/etc/fluxd/sshmount location of the k8s secret storing the private SSH key
–k8s-secret-data-keyidentitydata key holding the private SSH key within the k8s secret
k8s configuration
–k8s-allow-namespacerestrict all operations to the provided namespaces
–k8s-default-namespacethe namespace to use for resources where a namespace is not specified
–k8s-unsafe-exclude-resource["*metrics.k8s.io/*", "webhook.certmanager.k8s.io/*", "v1/Event"]do not attempt to obtain cluster resources whose group/version/kind matches these glob expressions, e.g. coordination.k8s.io/v1beta1/Lease, coordination.k8s.io/*/Lease or coordination.k8s.io/*. Potentially unsafe, please read Flux’s troubleshooting section on --k8s-unsafe-exclude-resource before using it.
upstream service
–connectconnect to an upstream service e.g., Weave Cloud, at this base address
–tokenauthentication token for upstream service
SSH key generation
–ssh-keygen-bits-b argument to ssh-keygen (default unspecified)
–ssh-keygen-type-t argument to ssh-keygen (default unspecified)
–ssh-keygen-format-m argument to ssh-keygen (default RFC4716)
manifest generation
–manifest-generationfalsesearch for .flux.yaml files to generate manifests
–sopsfalsedecrypt SOPS-encrypted manifest files before applying them to the cluster. Provide decryption keys in the same way as providing them for sops the binary, for example with --git-gpg-key-import. The full description of how to supply sops with a key can be found in the SOPS documentation. Be aware that manifests generated with .flux.yaml files are not decrypted. Instead, make sure to output cleartext manifests by explicitly invoking the sops binary.

More information

Setting up and configuring fluxd is discussed in “Get started with Flux”.

There is also more information on garbage collection, Git commit signing, and other elements in references.

Last modified 2021-08-17: Fix fluxcd/flux#3192 (f63fd18)