You don't have javascript enabled. Good luck! :(

Installation Docs

Find the official installation docs for v2.23 at teamhephy.info.

If you have any issues, please be sure to report it on the slack community — (Edit: temporarily, the inviter is down! Please bear with us until it's resolved...), or report them on the issue tracker on GitHub.

  Sep 19, 2022     Team Hephy     tutorials  UPDATE: Mar 4, 2024

Three Ways to Install Flux Operator

blog 2022 tutorial gitops

Thanks to the OperatorHub operator for Flux, you can install Flux as an operator on OpenShift and anywhere else that Operator Lifecycle Manager (OLM) is in use. That puts Flux in line with other CNCF operator-based projects like Pixie, etcd, Jaeger, and others built using the Operator Framework. While this is not the preferred or even an officially supported way to install Flux, as we recommend to use Flux itself to manage Flux via the canonical bootstrap method, or to achieve substantially the same thing from outside of Kubernetes via Flux’s Terraform provider. But those are not the only way to install Flux. Let’s have a look at what you can do with Flux and the Operator Lifecycle Manager!


The easiest way to take advantage of Flux with Operator Hub is if you are already running OpenShift Container Platform or the Open Source OKD4 which comes with the OpenShift Console, you may already know about operator groups and cluster service versions or you may have skipped all of that, and just use the web console to install Flux and other operators that are available through OperatorHub with a few clicks.

If you’re not using OpenShift, then things get a bit more difficult (but you can still use Flux from OperatorHub.) If you find yourself in this situation as I did, needing to understand OperatorHub well enough to test and deploy Flux from there without buying into the whole OpenShift ecosystem and Kubernetes distribution, then you’ve come to the right place.

OpenShift Supported Method: Click to Install

The best way to install for usability is through the web console, because Flux is installed cluster-wide with a specific namespace, and the OpenShift web console is the only way that implements operatorframework.io/suggested-namespace as a UI element. So if you install the Flux operator any other way, you need to be sure that it winds up in the correct flux-system namespace, or many default behaviors will be broken and the system RBAC roles will likely not be bound correctly among other potential issues.

Unfortunately, installing a standalone OpenShift web console without the rest of the OpenShift container platform distribution or other associated projects has proven quite challenging – and the work required has grown in complexity such that this method can no longer be reasonably recommended, compared to the alternatives. So since we are not on OKD or OCP, we won’t use the web console here at all.

Method 1: Follow the Instructions

If you visit Flux on OperatorHub and you do not have the OpenShift web console to handle the click on that “Install” button internally, then you will be presented with the fine instructions.

Let’s try them and see if they work:

Install OLM:

curl -sL https://github.com/operator-framework/operator-lifecycle-manager/releases/download/v0.22.0/install.sh | bash -s v0.22.0

Install Flux:

kubectl create -f https://operatorhub.io/install/flux.yaml

Check if it worked:

kubectl get csv -n operators

We see the operator’s PHASE transitions to Succeeded which seems to indicate that yes, it did work!

We’d like to test and know for sure that everything really works, so I’ll create a Flux “Bootstrap Lite” with a GitRepository and Kustomization resource in the flux-system namespace. Both are named flux-system as is the convention, and placed in a directory flux-system under the cluster path, but then at this point we realize the flux-system namespace isn’t present on the system at all.

So many flux CLI commands which default to the flux-system namespace are likely to balk or error, like flux logs.

This can ostensibly be overcome by setting and exporting FLUX_SYSTEM_NAMESPACE=operators however a quick check of flux logs indicates that it doesn’t work, even with this variable set. We’ll come back to that (TODO: let’s file a bug report). Let’s leave that variable unset for now.

Following the convention, let’s create our bootstrap lite:

apiVersion: source.toolkit.fluxcd.io/v1beta2
kind: GitRepository
metadata:
  name: flux-system
  namespace: flux-system
spec:
  gitImplementation: go-git
  interval: 1m0s
  ref:
    branch: staging
  timeout: 60s
  url: https://github.com/kingdonb/bootstrap-repo
---
apiVersion: kustomize.toolkit.fluxcd.io/v1beta2
kind: Kustomization
metadata:
  name: flux-system
  namespace: flux-system
spec:
  interval: 1m0s
  path: ./clusters/demo-cluster-1
  prune: true
  sourceRef:
    kind: GitRepository
    name: flux-system

This file is added to the path ./clusters/demo-cluster-1/flux-system in our bootstrap-repo in the branch we have specified, and in the demo-cluster-1/ directory a foobar sample configmap is placed, to verify that we can apply configurations to any place in the cluster as the default Flux installation provides (without hardening for multi-tenancy, as this is the Flux mode that OperatorHub supports).

The configmap is created and Flux is syncing it’s own configuration, that’s great!

So we have a working Flux installation, and it is pretty good, but we’d like it to be in the flux-system namespace, following the principle of least surprise, so that other Flux behaviors all work as expected, and now it’s not clear from the instructions how we can achieve this.

Method 2: Use the Krew plugin kubectl-operator

We got the instructions above for installing Operator Lifecycle Manager, which we can keep around for this next method, but we’ll uninstall Flux as we installed it from the instructions in Method 1, as we will see from this method, that method is less flexible and configurable.

kubectl delete -f https://operatorhub.io/install/flux.yaml
# This command doesn't appear to do anything...

# Also delete the operator cluster service version:
kubectl delete csv flux.v0.31.4 -n operators

There is still an Operator flux.operators which can’t be deleted (it inexplicably just re-creates itself) and the Flux CRDs are still on the cluster, but that’s OK as the Flux operator is no longer running.

We can install it again now, with the kubectl operator command! First, download kubectl-operator.

Then run:

kubectl operator install -n flux-system flux --create-operator-group

Now wait a while, check the logs as before, and you may run flux reconcile to speed things along:

$ flux reconcile source git flux-system
► annotating GitRepository flux-system in flux-system namespace
✔ GitRepository annotated
◎ waiting for GitRepository reconciliation
✔ fetched revision staging/076aee990b6c836143e0e69b06f7f5c0bd5d81bf

$ flux logs
2022-09-19T17:00:41.283Z info GitRepository/flux-system.flux-system - garbage collected 1 artifacts
2022-09-19T17:00:41.407Z info GitRepository/flux-system.flux-system - no changes since last reconcilation: observed revision 'staging/076aee990b6c836143e0e69b06f7f5c0bd5d81bf'
2022-09-19T17:01:41.481Z info GitRepository/flux-system.flux-system - no changes since last reconcilation: observed revision 'staging/076aee990b6c836143e0e69b06f7f5c0bd5d81bf'

$ flux reconcile ks flux-system
► annotating Kustomization flux-system in flux-system namespace
✔ Kustomization annotated
◎ waiting for Kustomization reconciliation
✔ applied revision staging/076aee990b6c836143e0e69b06f7f5c0bd5d81bf

Great, now we are using OLM without the OpenShift Web Console, and flux-system is the namespace that hosts the Flux controllers (conforming with the convention), so nobody will be surprised by a different namespace!

$ kubectl get operators
NAME               AGE
flux.operators     45m
flux.flux-system   40m
$ kubectl delete operator flux.operators

We can also delete the former Operator flux.operators and it is not recreated now.

This method is by far the easiest and best way to install Flux as an OLM Operator.

Method 3: OpenShift Console

We said we didn’t have OpenShift and we acknowledged before that it would present a barrier to using OperatorHub, but not an impassable one.

The author had earlier tested a method of installing Flux Operator from the OpenShift web console operated in a non-permanent way, where you can still click to install, but the amount of setup required to make this work is prohibitive.

If you have a nodejs >= 14 and yarn environment available, you might want to try the console! It’s honestly very nice, and you can run it locally, but to make Administrator things like the Operator Hub installer work, I wound up having to hijack a bearer token. The instructions may have been improved since then. Kubernetes Native OpenShift Web Console is a thing.

You can try it for yourself, maybe it works better for you, I had trouble last time and I will not explain how it is done here, other than to say the bearer token that you export needs to have Cluster Admin privileges, which should be reason enough to understand why this method is not the recommended way.

Four Methods to Install Flux

There are more than just four ways to install Flux, and any article about installing Flux would be remiss if it did not recommend new Flux users to check out the Bootstrap Install method that provides specific instructions for a few different supported Git environments and the Getting Started guide which are recommended in the Flux Docs.

If you are just learning Flux, please don’t skip reading those docs just because you found an operator that can manage Flux. Users are supposed to learn how Flux works from those docs. Without the Getting Started guide, we find many Flux users who do not understand the fundamentals.

If you have someone to guide you through Flux, or if you have already firm understanding of the way that Flux works, then an operator-based Flux installation can be really useful as it can be self-upgrading, and then ostensibly nobody has to manage Flux itself!

One drawback of this method is that while, yes, it is maintained, upgrades historically can lag somewhat behind regular Flux. Flux releases can happen somewhat frequently and cover a lot of ground. Then someone has to provide separate testing for upgrades to go out via OperatorHub.

Of course many people are subscribed to these updates on their production clusters, so we can’t just YOLO and push out every upgrade immediately without testing! For reference as of this writing, the Flux upstream is on release v0.34.0 and the OpenShift operator is still at v0.31.4. (Edit: It’s November 7, and last week at KubeCon, Flux is at v0.36.0, and I was able to tell folks that OperatorHub Flux is also at v0.36.0. So for now, it seems we have caught up! Still YMMV in the future, and this is something to be aware of, that they can become out of sync.)

Method 5: The microsoft.flux extension from Azure

See also the Microsoft version of Flux, which Microsoft actually built and supports on their own separate from the FluxCD org:

If you’re on Azure, or even if you’re on generic Kubernetes, you can use Azure Arc to manage Flux and other extensions from Microsoft on your Kubernetes cluster. This is yet another way you can install Flux as an operator on your clusters!

If you ever have trouble with Flux and have to report an issue, make sure to mention whichever way that you installed Flux along with what version it is. Without this information, it can be very difficult to know whether an issue is the same as one we already saw reported and fixed, and any difference can be material to the debugging effort.

Team Hephy uses Flux

We’re not a company so we didn’t feel it made sense to post ourselves on the Flux adopters list, but as a Flux maintainer and Team Hephy maintainer, it could be important for some people to be able to know that I have both interests. We use Flux to support Hephy Workflow development!