gitops-istio wires Flux, Flagger and Istio into one progressive delivery recipe

This is a workshop repository, and the guide says so

The gitops-istio repository presents itself as a guide where you get hands-on experience with GitOps and progressive delivery using Kubernetes and Istio. That framing sets expectations properly. You fork it, clone your fork, and follow the steps against a cluster you control, and the repository is the configuration you are meant to edit. The directory layout is small and legible: a clusters directory holds the per cluster Flux configuration, an istio directory holds the Istio Helm releases, and an apps directory holds the demo workloads. The topics attached to the repository, gitops, flux, flagger, istio, kubernetes, progressive delivery, ab testing, and the e2e and analyze workflow badges at the top of the README, show that the repository is maintained as a tested example. The reading order is the README itself, from the definitions of GitOps and progressive delivery through prerequisites, cluster bootstrap, Istio customizations, control plane upgrades and finally application bootstrap.

Flux bootstraps itself and needs a deploy key with write access

The bootstrap step is the piece that matters most for anyone reusing this in a real organisation. The flux bootstrap command installs Flux on a cluster and configures it to manage itself from a Git repository, and if the Flux components are already present it performs an upgrade instead.

flux bootstrap git \
  --author-email=<YOUR-EMAIL> \
  --url=ssh://[email protected]/<YOUR-USERNAME>/gitops-istio \
  --branch=main \
  --path=clusters/my-cluster

The command requires an ssh-agent, and the Windows path is handled by separate Flux documentation. At bootstrap, Flux generates an SSH key and prints the public key, and you paste that into a deploy key on your GitHub repository with write access enabled, which is the mechanism by which Flux reconciles the cluster back to the repository. That write access is the real operational decision in this repository, since a Flux controller holding push rights to your cluster definition can change what runs in production, and GitHub branch protection and deploy key rules become the control that limits it. The repository also ships an e2e workflow and an analyze workflow, so a fork can be tested the same way the upstream one is.

Minikube and a tunnel stand in for a real load balancer

The prerequisites are spelled out and they set the size of the exercise. You need a Kubernetes cluster of version 1.20 or newer with LoadBalancer support, and for testing the guide suggests Minikube with 2 CPUs and 4GB of memory.

minikube start --cpus='2' --memory='4g'

If you use Minikube, the guide asks you to keep a tunnel running in a separate terminal for the duration of the workshop, because it assigns an external IP to the istio-gateway service and lets the helm install complete successfully.

minikube tunnel

The command line tools are equally specific: jq, yq and the flux CLI are installed with Homebrew.

brew install jq yq fluxcd/tap/flux

Then you check that the cluster satisfies the prerequisites before touching anything.

flux check --pre

Two things are worth flagging. The tunnel is a temporary workaround for a missing load balancer, not something to carry into production. And the toolchain is macOS oriented, since the installation instructions assume Homebrew, so a Linux workstation needs the equivalent package installs spelled out separately.

Reconciliation order is expressed as dependsOn between Kustomizations

The interesting mechanism in the repository is how Flux sequences the install so that Istio is ready before the workloads. The guide is explicit that the order matters, because the application pods need the Istio sidecar injected and the control plane has to be running first. With Flux v2 you express that by declaring dependencies between objects. The apps reconciliation waits for the istio-system one.

apiVersion: kustomize.toolkit.fluxcd.io/v1beta2
kind: Kustomization
metadata:
  name: apps
  namespace: flux-system
spec:
  interval: 30m0s
  dependsOn:
    - name: istio-system
  sourceRef:
    kind: GitRepository
    name: flux-system
  path: ./apps

The same idea appears inside the Istio Helm releases, where the gateway release depends on the base and the istiod releases, which is how a single push produces a correctly ordered upgrade rather than a race.

apiVersion: helm.toolkit.fluxcd.io/v2beta1
kind: HelmRelease
metadata:
  name: istio-gateway
  namespace: istio-system
spec:
  dependsOn:
    - name: istio-base
    - name: istiod
  # source: https://github.com/istio/istio/blob/master/manifests/charts/gateway/values.yaml
  values:
    autoscaling:
      enabled: true

Editing those values and pushing to Git is what reconfigures the Istio control plane, so the cluster state is a Git diff rather than a series of imperative commands.

Three flux commands cover watching, logging and listing managed resources

Once bootstrapped, the guide gives you the commands for observing what Flux is doing, and they cover the three questions you ask after every sync. What has it reconciled? What did it say? What is it managing? The first is answered by watching the Kustomizations, the second by tailing the reconciliation logs, and the third by printing the resource tree under the root Kustomization.

watch flux get kustomizations

flux logs --all-namespaces --follow --tail=10

flux tree kustomization flux-system

The tree command is the one most people skip and most benefit from, since it answers a question that cluster browsing makes awkward, namely which objects in the cluster came from which Kustomization. During bootstrap, Flux installs Istio using the Istio base, istiod and gateway Helm charts, waits for the control plane to be ready, installs Flagger, Prometheus and Grafana, creates the public gateway and the prod namespace, and creates the load tester plus the frontend and backend deployments and canaries. Being able to see that list as a tree after the fact is a good way to learn what a bootstrap really did.

An Istio version bump arrives as a pull request that CI tests on Kind

Control plane upgrades are automated rather than documented as manual steps. When a new Istio version is available, the update-istio GitHub Action workflow opens a pull request with the manifest updates needed for the upgrade. The new version is tested on Kubernetes Kind by the e2e workflow, and only when the pull request is merged into the main branch does Flux upgrade Istio on the production cluster. That chain, a bot proposes, CI validates, a human merges, Flux applies, is the part of this repository that is genuinely worth copying, because it is the mechanism that makes a GitOps upgrade reviewable and rollback is a revert commit. For Helm releases specifically, the guide shows how to watch upgrades and how to investigate failures.

flux -n istio-system get helmreleases --watch

kubectl -n istio-system describe helmrelease istio-gateway

Flux issues Kubernetes events with the errors encountered during reconciliation, and the guide notes that those events can also be published to Slack, Microsoft Teams, Discord and others through the Flux notification guide, which is where a team that does not watch the cluster continuously should start.

The tags stopped in 2022 while the branch kept moving

Maintenance facts for this repository are worth stating plainly. The last push was on 2026-05-19, the repository is not archived, and the workflow badges at the top of the README show continuous integration still running. The release list, however, has only two entries, v2.0.0 from 2022-05-17 and v1.0.0 from 2022-05-05, both early in the life of the project. So there is no tagged version to pin to for a production environment, and the usable artifact is the main branch. The licence is Apache-2.0 with the terms in the LICENSE file, which makes reuse of the manifests and the CI workflows straightforward as long as the notices travel with them. One more caveat belongs with the maintenance discussion. The workshop pins specific tool versions and manifests for Istio, Flagger and Flux at the time of writing, and the tutorial is a snapshot: the Kubernetes floor of version 1.20, the specific Istio charts named base, istiod and gateway, and the installation of Flagger, Prometheus and Grafana are all choices that a cluster two years newer may no longer want. Copying the structure is straightforward, copying the versions without review is not.

Editorial conclusion

gitops-istio is worth an afternoon for an engineer who already runs Kubernetes and Istio and wants to see GitOps delivery and progressive rollout wired together end to end, since every manifest, the bootstrap command and the upgrade workflow are in the repository rather than hidden in a talk. It is not a production platform: the README describes a workshop, the demo targets are named frontend and backend with a load tester, and the sample configuration is sized for a Minikube node with 2 CPUs and 4GB of memory. Before you copy its structure, check three things: whether your clusters still run a Kubernetes version at or above 1.20 with LoadBalancer support, whether the Istio charts and Flagger versions in the repository match the ones you already operate, and whether the fork and deploy key model, which gives Flux write access to your repository, fits your branch protection rules. The licence is Apache-2.0, the last push was on 2026-05-19, and the newest tag is v2.0.0 from 2022-05-17.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. stefanprodan/gitops-istio on GitHub