Installing Flux and Argo CD

Installing Flux and Argo CD

If a cluster has no Flux or Argo CD, Sextant can install them for you, from the projects' own official manifests, through the Kubernetes API. You choose a version, look at exactly what will be created, and confirm. Nothing is installed without your click: AI agents and extensions cannot start an install.

Contents: Where to find it · What gets installed · Where the files come from · Rights you need · The preview · Installing · Stop, disconnect, partial installs · After Argo CD · Removing them by hand · Troubleshooting

Where to find it

The offer lives with the cluster, because the Flux and Argo CD sections of the sidebar stay hidden while the tool is missing (see Flux and Argo CD):

• Right-click a connected cluster in the cluster rail (or use its menu) and choose Install Flux… or Install Argo CD….
• Or open the cluster's settings (right-click the cluster → Settings) and look at the GitOps section at the bottom. It shows Installed, Partly installed or Not installed for each tool, and Install Flux… / Install Argo CD… next to one that is not fully installed.

The entries appear only for a connected cluster, and only for a tool that is not fully installed (see how Sextant tells). When the install has finished, the new section appears in the sidebar by itself, without reconnecting.

What gets installed

	Flux	Argo CD
Namespace	flux-system	argocd
Which file	install.yaml of a fluxcd/flux2 release	manifests/install.yaml of an argoproj/argo-cd release (the standard install: cluster-wide, with the web UI, not highly available)
What you get	The same as flux install does by default: the source, kustomize, helm and notification controllers	The standard set: API server and UI, repo server, application controller, ApplicationSet controller, notifications controller, Dex, Redis
Left out	Image automation (image-reflector-controller, image-automation-controller) and the source watcher: their Deployments, ServiceAccounts, Services and CRDs are not installed	Nothing

Both installs create cluster-wide objects: a Namespace, CustomResourceDefinitions, ClusterRoles and ClusterRoleBindings. The namespace cannot be changed, because the RBAC in the official files names flux-system and argocd. Helm charts, high-availability and namespace-scoped Argo CD installs, and Flux's image automation are not offered; use the project's own tools for those.

For Argo CD, Sextant creates the Namespace argocd itself (the official file does not contain it) and puts every namespaced object into it. For Flux, the shared role bindings of the official file (such as crd-controller) are written without the ServiceAccounts of the left-out components, as flux install writes them.

Sextant refuses a manifest that contains a kind the official files do not use, an object in another namespace, or something that is not the tool's install.yaml. A new version that starts using a new kind is refused until Sextant is updated.

Where the files come from

The only choice you make is the version, so only these addresses are ever used, all over HTTPS:

What	Address
The list of versions	https://api.github.com/repos/fluxcd/flux2/releases and https://api.github.com/repos/argoproj/argo-cd/releases (30 newest)
Flux manifest	https://github.com/fluxcd/flux2/releases/download/<tag>/install.yaml
Flux checksums	https://github.com/fluxcd/flux2/releases/download/<tag>/flux_<version>_checksums.txt
Argo CD manifest	https://raw.githubusercontent.com/argoproj/argo-cd/<tag>/manifests/install.yaml

• Versions. The list holds the stable releases (no pre-releases, no drafts), tags like v2.9.6, newest first, and the newest is chosen. If GitHub cannot be asked (no network, or GitHub's limit of 60 anonymous requests an hour per address), the dialog says so and offers only the version Sextant was tested with: Flux v2.9.6 and Argo CD v3.5.5 in this release.
• Flux is verified. The SHA-256 of install.yaml must match the one in the flux_<version>_checksums.txt of the same release. If it does not, nothing is installed.
• Argo CD is not verified, because the project publishes no checksum for this file. The preview shows the SHA-256 of what was downloaded, so you can compare it with a copy you trust. The file is trusted as GitHub serves it for that tag.
• A download may be redirected only to GitHub's own release hosts, may not exceed 20 MiB, and is cut off after 60 seconds.

Downloading starts when you press Download and preview; Sextant contacts GitHub only for that (and for the update check, see Settings).

Rights you need

An install changes the whole cluster, so you need cluster-admin rights, or something equivalent: to create Namespaces, CustomResourceDefinitions, ClusterRoles and ClusterRoleBindings (Kubernetes lets you create a role only if you already hold the permissions it grants), and workloads in the new namespace.

Before you confirm, Sextant asks the cluster whether you may create CustomResourceDefinitions and ClusterRoleBindings and warns when the answer is no. The warning does not block the button, because the answer is the cluster's guess and the decision is yours; expect the install to fail at the first object you may not create. An answer of "yes" is not a promise either: a policy engine or admission webhook can still refuse an object.

The preview

After Download and preview the dialog shows, before anything is sent to the cluster:

• the version, the source address and its SHA-256, with "matches the checksums file of the release" for Flux or "the project publishes no checksum for this file" for Argo CD;
• the namespace;
• how many objects of each kind there are, and the list of all objects (kind, namespace, name) with the cluster-wide ones marked cluster-wide;
• the warnings that apply:
  • installing changes the whole cluster and needs cluster-admin rights;
  • you may not create CustomResourceDefinitions, or ClusterRoleBindings, here;
  • the tool is already installed, or partly installed (its namespace or some of its CRDs exist): the existing objects will be updated;
  • cluster-wide objects with the same names exist already (a list): they will be overwritten, whoever made them;
  • Flux only: controllers that flux install leaves out (image automation, the source watcher) already run in flux-system. The install removes their ServiceAccounts from the shared role bindings, so they lose their permissions.

Back returns to the version choice. A prepared install waits for 10 minutes; after that, prepare it again. The objects are applied with the field manager sextant, forcing ownership of conflicting fields, like flux install and kubectl apply --server-side --force-conflicts do. That is why the preview says what is overwritten.

Installing

Press Install. Sextant applies the objects one by one, in this order: the Namespace, the CustomResourceDefinitions, then the rest in the order of the file (after the CRDs it asks the cluster again which kinds it serves). The dialog shows how many objects are applied.

Then it waits for the controllers. It checks every 3 seconds, for up to 5 minutes, that every Deployment (and, for Argo CD, the StatefulSet of the application controller) of the install exists and is ready, and lists each as ready or not ready, with the reason for those that are not (for example a pod's ImagePullBackOff, or no node with enough room).

Result	What it means
"… is installed and running. Its section is in the sidebar."	Everything was applied and every controller became ready.
"Everything was applied, but not every controller was ready within 5 minutes."	Nothing is rolled back. The controllers may still come up (a slow image pull); look at the pods of the namespace. The list shows what each one was waiting for.
"The install failed."	The first object that could not be applied ended the install, with the cluster's reason and how many objects were applied before it. Nothing after it was sent.
"The install was stopped."	See below.

The dialog also lists what was applied and, after a failure or a stop, what was not applied.

Stop, disconnect and partial installs

• Stop ends the install after the object being applied; it also ends the wait for the controllers. The objects applied so far stay in the cluster.
• Closing the dialog while an install runs asks "Stop the install?" first.
• Disconnecting the cluster, reloading the window and quitting Sextant stop a running install too. The last message says how many objects were applied; the object being sent at that moment may or may not have been applied.
• Hiding the window in the tray does not stop it (see Settings).

Nothing is ever rolled back. A failed, stopped or timed-out install leaves what it applied, so the tool can be partly installed. To finish, run the install again: the preview then warns that the tool is partly installed, and the second run updates what exists and adds the rest. To abandon it, remove what is there by hand (next section).

Sextant asks the cluster whether a tool is installed. It counts as installed when all of its CustomResourceDefinitions exist and the controllers every install has are in its namespace: for Flux the Deployments source-controller and kustomize-controller in flux-system; for Argo CD the Deployments argocd-server, argocd-repo-server and the StatefulSet argocd-application-controller in argocd. Optional parts (Flux's helm and notification controllers, Argo CD's Dex, notifications, ApplicationSet controller and Redis) are not checked, so a Flux bootstrapped with fewer components, an Argo CD from its Helm chart with some of them turned off (recognized by the app.kubernetes.io/name labels) and a high-availability install count as installed. The last controller the official file applies is among those checked, so an install that stopped part way is still caught. It is partly installed when only some of that exists: the namespace, some of the CRDs, or all the CRDs but not every controller, which is what an install that stopped or failed part way leaves. A partly installed tool keeps its Install entries, and the GitOps section says Partly installed, even when its section already shows in the sidebar (the sidebar only needs the CRDs). Running the install again is enough to finish it.

Two cases count as installed although Sextant cannot see the controllers: the CRDs exist but the namespace flux-system or argocd does not (the tool was installed into another namespace), and you may not list Deployments in that namespace. Until the cluster answers, or when it cannot be asked, the cluster menu and the section fall back to the kinds the cluster serves (Kustomization of kustomize.toolkit.fluxcd.io for Flux, Application of argoproj.io for Argo CD).

After Argo CD

Sextant signs in to Argo CD by itself for the diff, using argocd-initial-admin-secret that the install created (see Argo CD). The dialog reminds you to change the admin password in Argo CD, and then to delete that secret. Open Argo CD UI in the dialog opens the web interface in your browser through a port forward.

To read the initial password yourself (to sign in to the web interface):

kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath='{.data.password}' | base64 -d

The user name is admin. Once you change the password and delete the secret, Sextant can no longer sign in by itself; enter the new login when the diff asks, and tick Remember on this computer if you want to keep it.

Removing Flux or Argo CD by hand

Sextant does not uninstall. These are the manual steps; they are the same as for any install from the official files. Use the same version you installed (Version in the preview, or the image tags in the namespace), and look before you delete.

Mind what you are deleting.

• Deleting a CustomResourceDefinition deletes every object of that kind in the cluster: all Flux Kustomizations, HelmReleases and sources, or all Argo CD Applications, ApplicationSets and AppProjects.
• What the tools deployed can go with them. A Flux Kustomization with prune: true can remove the objects it applied when it is deleted, and a HelmRelease uninstalls its release; an Argo CD Application with the finalizer resources-finalizer.argocd.argoproj.io deletes its resources. If those workloads must stay, deal with them first (see the project's documentation) and do not delete the namespace in a hurry.
• Custom resources with finalizers need their controller to run to be deleted. Delete them before the controllers, or the namespace and the CRDs may hang in Terminating.

List what exists first (nothing is deleted by these):

# Flux
kubectl get gitrepositories,ocirepositories,helmrepositories,helmcharts,buckets,kustomizations,helmreleases -A
# Argo CD
kubectl get applications,applicationsets,appprojects -A

Delete the custom resources you do not want to keep, one by one, while the controllers still run and wait for them to go (for example kubectl delete kustomization <name> -n <namespace>). Then remove the install with the file of the same version:

# Flux
curl -fLO https://github.com/fluxcd/flux2/releases/download/v2.9.6/install.yaml
kubectl delete -f install.yaml --ignore-not-found

# Argo CD
kubectl delete -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/v3.5.5/manifests/install.yaml
kubectl delete namespace argocd

Replace v2.9.6 and v3.5.5 with the version you installed. This file lists everything the install created, including the CRDs, ClusterRoles and ClusterRoleBindings, so no cluster-wide leftovers stay. For Flux, it also lists the image automation and source watcher objects, which --ignore-not-found skips if they were never installed; if you installed those yourself, they are removed as well, which is what you want when you remove Flux. The Flux file contains its namespace, so the namespace goes too; check kubectl get ns flux-system afterwards.

The Flux project's own flux uninstall does the same job, if you have the flux command; see its documentation for what it does with the objects Flux deployed.

When the objects are gone, the Flux or Argo CD section disappears from the sidebar by itself (Sextant watches for CRDs), and GitOps in the cluster's settings says Not installed again.

Troubleshooting

"Could not get the list of releases from GitHub, so only the tested version is offered." No network or no way to GitHub from this computer, or GitHub's limit for anonymous requests. The tested version still works if the download itself works; otherwise try again later, or install from a terminal.

"Download and preview" fails. The message names the cause: a download that is too large or too slow, a refused address, a Flux checksum that does not match (nothing is installed in that case; try again, and if it keeps happening report it), or a manifest Sextant does not accept.

"The prepared install expired or was already used; prepare it again." A preview is good for 10 minutes and for one install. Press Back and Download and preview again.

The install fails at an object. Read the reason: usually your account may not create it (see Rights you need), or an admission policy refused it. Fix that and run the install again: it starts over and updates what is there.

Controllers are "not ready". The reason under each controller comes from its pods. Typical ones: the cluster cannot pull the images (ghcr.io, quay.io, Docker Hub; a registry mirror or a firewall), or no node has room. Look at the pods of flux-system or argocd in the Workloads section.

The entries "Install Flux…" and "Install Argo CD…" are not there. The cluster is not connected, or its discovery has not come yet, or the tool is already served by the cluster. See GitOps in the cluster's settings.

Back to Using Sextant, Settings and Troubleshooting.