Flux - kamialie/knowledge_corner GitHub Wiki

Flux

Kubernetes operator that implements pull-based deployments mechanism. Can also scan images used in deployments, monitor registry repositories for changes and update container image along with writing changes to the repository.

By default Flux assumes that the latest image should be deployed; with repository write access it can also push updated image tag to the repository. This behavior can be managed with image tag filters, which is defined as fluxcd.io/tag.<container_name>: <value> annotation (multiple annotations can be specified to reflect multiple containers): | Type | Example | Description | | SemVer | semver:~1.0.5 | Semantic versioning | | Regexp | regex:^[a-f0-9]{7}$ | Regular expressions, e.g. commit hashes | | Glob | glob:staging-* | Globbing syntax |

Common directory structure:

.
|-- flux-system
|   |-- gotk-components.yaml
|   |-- gotk-sync.yaml
|   |-- kustomization.yaml
|
|-- notifications
    |-- alerts
        |-- discord-bot-alert.yaml
    |-- providers
        |-- discord.yaml
    |-- kustomization.yaml

Set of tools that comprise Flux are also referred as GitOps toolkit. Controllers within Flux:

Installation

install command installs Flux components, while bootstrap does the installation, but also creates a remote repository to store configuration of toolkit components (allows Flux to also manage itself according to GitOps principles).

Installation needs a Kubernetes namespace and Git repository details, such as URL, username and user email.

$ fluxctl install \
	--namespace <kubernetes_namespace> \
	--gir-url <ssh_url> \
	--git-user <git_username> \
	--git-email <git_email> | kubectl apply -f -

Source

Source controller periodically syncs and monitors configured source and triggers update on changes.

Identity

Flux is automatically configured to trust its own source repo during bootstrap due to permissive personal access token. This might not be always available, and ideally least privilege principle should be followed. Remote Git based system usually uses SSH protocol for communication with external software.

Flux CLI can be used to generate an SSH secret, which contains public/private key elements along with known_hosts content:

# Creates Kubernetes secret object
$ flux create secret git gitops-deploy-auth \
    --url=<ssh_repo_url>

Add public key as a deploy key in source system to finish the setup.

GitRepository

Configures Git repository that is monitored for changes.

  • GitRepository resource example: 
    apiVersion: source.toolkit.fluxcd.io/v1beta1
kind: GitRepository
metadata:
  name: nginx
spec:
  url: <repo_ssh_url>
  ref:
    branch: main
  secretRef:
    name: gitops-deploy-auth
  intervals: 1m0s
  • Create from CLI: 
    $ flux create source git nginx \
    --url=<repo_ssh_url> \
    --branch=main \
    --secret-ref=gitops-deploy-auth \
    --namespace default \
    --export # doesn't create a resource in the cluster

HelmRepository

For Helm repo url setting is a http(s) URL. If registry requires authentication, a secret with basic authentication details can be provided.

For OCI repo URL is prefixed with oci instead, also type setting has to be set to oci. Authentication is provided via docker-registry type of secret.

  • HelmRepository resource example: 
    apiVersion: source.toolkit.fluxcd.io/v1beta1
kind: HelmRepository
metadata:
  name: nginx
spec:
  url: <repo_ssh_url>
  ref:
    branch: main
  secretRef:
    name: gitops-deploy-auth
  intervals: 1m0s
  • Create from CLI: 
    $ flux create source helm nginx \
    --url=oci://<url> \
    --namespace default \
    --export # doesn't create a resource in the cluster

Kustomize

Configures Kustomization resource and monitors changes configured by source configuration. Works with YAML files and Kustomize overlays; verifies and applies them on changes.

Namespace must be specified either in source config or as targetNamespace parameter in Kustomization config.

  • Kustomization resource example: 
    apiVersion: kustomize.toolkit.fluxcd.io/v1beta1
kind: Kustomization
metadata:
  name: nginx
spec:
  sourceRef:
    kind: GitRepository
    name: nginx
    namespace: default
  path: ./deploy
  intervals: 1m0s
  prune: true
  targetNamespace: default
  • Create from CLI: 
    $ flux create kustomization nginx \
    --source=GitRepository/nginx.default \
    --path=./deploy \
    --prune=true \ # garbage collect resource that are removed from repo
    --target-namespace=default \
    --namespace default \
    --export # doesn't create a resource in the cluster

Helm

Currently supported sources for Helm are S3-compatible storage (entire content is fetched for sync operation), Git repository (specific branch can be monitored along with other features) and Helm/OCI-compliant registry (good option to apply SemVer constraints).

Helm controller fetches the source for the chart archive or builds tarbal from it. HelmChart resource is automatically created based on HelmRelease resource definition.

Helm controller itself is built with Helm SDK, which allows it to perform various actions with releases. By default, controller doesn't perform any remediation in the event of failed deployment (allows to perform debugging). However, Failed install (default for fresh installation), which uninstalls the release, or Failed updated (default for upgrades), which performs a rollback, strategies can be configured. Helm tests by default trigger remediation (explicitly ignore, if this is undesired). -1 value set for retries (default is 0) setting forced controller to infinitely retry installation/upgrade.

HelmRelease

reconcileStrategy for HelmRepository source type is set to ChartVersion - new artifact is created when Chart's version changes. For GitRepository and Bucket sources it is set to Revision.

  • HelmRelease resource example: 
    apiVersion: helm.toolkit.fluxcd.io/v1beta1
kind: HelmRelease
metadata:
  name: nginx
  namespace: default
spec:
  interval: 1m0s
  chart:
    spec:
      chart: nginx
      sourceRef:
        kind: HelmRepository
        name: nginx
      reconcileStrategy: ChartVersion
  • Create from CLI: 
    $ flux create helmrelease nginx \
    --source=HelmRepository/nginx \
    --chart=nginx \
    --values=../values.yaml \ # local file located relative to command execution
    --namespace default \
    --export # doesn't create a resource in the cluster

Default values of a chart can be overridden inline or via references to Kubernetes Secrets or ConfigMaps. References objects are merged in the same order they are defined in the configuration. Also inline values override any values that are referenced.

  • Inline: 
    spec:
  values:
    key: value
  • Reference 
    spec:
  valuesFrom:
    - kind: ConfigMap
      name: chart-values

Notification

Receives events from external sources and components of GitOps toolkit, which are consumed by other controllers (e.g. webhook); also sends notifications and events to external systems (communication platforms).

Provider

Provider API offers abstraction layer for external sources and components and can be configured via YAML files.

  • Provider resource example: 
    apiVersion: notification.toolkit.fluxcd.io/v1beta1
kind: Provider
metadata:
  name: discord
  namespace: default
spec:
  type: discord
  channel: gitops-lab
  username: Fluxbot
  secretRef:
    name: discord
  • Create from CLI: 
    $ flux create alert-provider discord \
    --type=discord \
    --secret-ref=discord
    --channel=gitops-lab
    --username=Fluxbot
    --export # doesn't create a resource in the cluster

Alert

Alerts resource is used to specify what type of events to send.

  • Alert resource example: 
    apiVersion: notification.toolkit.fluxcd.io/v1beta1
kind: Alert
metadata:
  name: discord-bot-alert
  namespace: default
spec:
  providerRef:
    name: discord
  eventSources:
    - kind: GitRepository
      name: '*'
    - kind: Kustomization
      name: '*'
  eventSeverity: info
  • Create from CLI: 
    $ flux create alert discord-bot-alert \
    --event-severity=info \
    --event-source=GitRepository/*,Kustomization/* \
    --provider-ref=discord \
    --export # doesn't create a resource in the cluster

Image reflector

Image reflector controller monitors container registries and discovers available image tags. Retrieved information is stored locally with the controller (local database file). Make sure to take into account registry rate limits.

Authentication with private registries can be configured via TLS certificate or registry credentials (both stored as Kubernetes secret).

ImageRepository

ImageRepository resource configures target repository and image, polling setting and so on. Retrieved tags are stored locally.

  • ImageRepository example: 
    apiVersion: image.toolkit.fluxcd.io/v1beta1
kind: ImageRepository
metadata:
  name: hello
  namespace: default
spec:
  image: gcr.io/google-samples/hello-app
  interval: 5m0s
  • Create from CLI: 
    $ flux create image repository hello \
    --image=gcr.io/google-samples/hello-app \
    --interval=5m \
    --namespace=default \
    --export # doesn't create a resource in the cluster

ImagePolicy

ImagePolicy resource identifies the strategy to select an image tag from a repository using policies. Set of tags can be, therefore, sorted alphabetically, numerically, or according to SemVer. Once tags are sorted, the top one is chosen as latest.

  • ImagePolicy example: 
    apiVersion: image.toolkit.fluxcd.io/v1beta1
kind: ImagePolicy
metadata:
  name: hello
  namespace: default
spec:
  imageRepositoryRef:
    name: hello
  policy:
    semver:
      range: '>=1.0'
  • Create from CLI: 
    $ flux create image policy hello \
    --image-ref=hello \
    --select-semver='>=1.0' \
    --namespace=default \
    --export # doesn't create a resource in the cluster

A pattern to apply policy to can be first extracted from the tag convention. The following config extract the time stamp from the REL.2023-01-11T17-32-12Z.fix tag.

spec:
  policy:
    filterTags:
      pattern: '^REL\.(?P<ts>.*)Z.*$'
      extract: '$ts'
    alphabetical:
      order: asc

Image automation

Image automation is performed by writing latest tag to the source (e.g. Git repository), and letting normal source update process to kick in.

Image automation marker (setter strategy) is simply a comment in YAML file, which is used to point to an image field in the file residing under path that needs to be updated:

spec:
  containers:
    - image: gcr.io/google-samples/hello-app # {"$imagepolicy": "default:hello"}

For Git repository source checkout and/or push branch(es) can be specified, along with user name and user email.

  • ImageUpdateAutomation example: 
    apiVersion: image.toolkit.fluxcd.io/v1beta1
kind: ImageUpdateAutomation
metadata:
  name: hello
  namespace: default
spec:
  sourceRef:
    kind: GitRepository
    name: hello
    namespace: default
  update:
    path: ./deploy # path within repo
    strategy: Setters
  • Create from CLI: 
    $ flux create image update hello \
    --git-repo-ref=hello \
    --git-repo-path=./deploy \
    --checkout-branch=main \
    --push-branch=main \
    --author-name=flux \
    [email protected] \
    --commit-template="{{ range .Updated.images }}{{ println . }}{{ end }}" \
    --namespace=default \
    --export # doesn't create a resource in the cluster

References

⚠️ **GitHub.com Fallback** ⚠️