flux-local is a set of tools and libraries for managing a local flux gitops repository focused on validation steps to help improve quality of commits, PRs, and general local testing.
This library uses command line tools like kustomize and helm to replicate the behavior of flux to gather objects in the cluster. It only looks at the local git repo, and not a live cluster. However, this is fine since the local repository has enough information and the definition is simple. Secrets are ignored as the content is not needed to validate the cluster is creating valid objects.
This library at first glance is little more than shell scripts running commands, but is easier to test, maintain, and evolve. This does not support all features of flux, but should be close enough for home use.
See documentation for full quickstart and API reference. See the github project.
The CLI is written in python and packaged as part of the flux-local
python library, which can be installed using pip:
$ pip3 install flux-local
You can use the flux-local
cli to inspect objects in the cluster, similar to how you might
use the flux command on a real cluster.
This example lists all Kustomizations in the cluster:
$ flux-local get ks -o wide
NAME PATH HELMREPOS RELEASES
apps ./tests/testdata/cluster/apps/prod 0 0
infra-controllers ./tests/testdata/cluster/infrastructure/controllers 0 0
infra-configs ./tests/testdata/cluster/infrastructure/configs 2 0
This example lists all HelmReleases in the cluster:
$ flux-local get hr -A
NAMESPACE NAME REVISION CHART SOURCE
podinfo podinfo 6.3.2 podinfo-podinfo podinfo
metallb metallb 4.1.14 metallb-metallb bitnami
This example lists all HelmReleases in a specific namespace:
$ flux-local get hr -n metallb
NAME REVISION CHART SOURCE
metallb 4.1.14 metallb-metallb bitnami
You can use the flux-local
cli to build all objects in a cluster, similar to how you
use kustomize build
, which is used underneath. Here is an example to build all flux
Kustomization
objects within a git repository, using kustomize cfg count
to parse
the yaml output:
$ flux-local build tests/testdata/cluster/ | kustomize cfg count
ClusterPolicy: 1
ConfigMap: 1
HelmRelease: 2
HelmRepository: 2
Namespace: 1
You can also specify the root to build all clusters.
Additionally, you can inflate HelmRelease
objects inside each Kustomization
by adding
the --enable-helm
command line flag. This example again shows kustomize cfg count
to parse the yaml output which now includes the resources from HelmRelease
objects
defined in the cluster:
$ flux-local build tests/testdata/cluster/ --enable-helm --skip-crds | kustomize cfg count
ClusterPolicy: 1
ClusterRole: 2
ClusterRoleBinding: 2
ConfigMap: 3
DaemonSet: 1
Deployment: 3
HelmRelease: 2
HelmRepository: 2
Ingress: 1
Namespace: 1
Role: 3
RoleBinding: 3
Secret: 1
Service: 3
ServiceAccount: 2
ValidatingWebhookConfiguration: 1
You may also use flux-local
to verify your local changes to cluster resources have the desird
effect. This is similar to flux diff
but entirely local. This will run a local kustomize build
first against the local repo then again against a prior repo revision, then prints the output:
$ flux-local diff ks apps
---
+++
@@ -2,6 +2,13 @@
kind: Namespace
metadata:
name: podinfo
+- apiVersion: v1
+ data:
+ foo: bar
+ kind: ConfigMap
+ metadata:
+ name: podinfo-config
+ namespace: podinfo
- apiVersion: helm.toolkit.fluxcd.io/v2beta1
kind: HelmRelease
metadata:
Additionally flux-local
can inflate a HelmRelease
locally and show diffs in the output
objects. This is similar to flux diff
but for HelmReleases:
$ flux-local diff hr -n podinfo podinfo
---
+++
@@ -33,8 +33,8 @@
labels:
app.kubernetes.io/managed-by: Helm
app.kubernetes.io/name: podinfo
- app.kubernetes.io/version: 6.3.2
- helm.sh/chart: podinfo-6.3.2
+ app.kubernetes.io/version: 6.3.3
+ helm.sh/chart: podinfo-6.3.3
name: podinfo
spec:
ports:
...
You may also use an external diff program such as dyff which is more compact for diffing yaml resources:
$ git status
On branch dev
Your branch is up to date with 'origin/dev'.
Changes not staged for commit:
modified: home/dev/hajimari-values.yaml
$ export DIFF="dyff between --omit-header --color on"
$ flux-local diff ks home --path clusters/dev/
spec.chart.spec.version (HelmRelease/hajimari/hajimari)
± value change
- 2.0.2
+ 2.0.1
$ flux-local diff hr hajimari -n hajimari --path clusters/dev/
metadata.labels.helm.sh/chart (ClusterRoleBinding/default/hajimari)
± value change
- hajimari-2.0.2
+ hajimari-2.0.1
metadata.labels.helm.sh/chart (PersistentVolumeClaim/default/hajimari-data)
± value change
- hajimari-2.0.2
+ hajimari-2.0.1
You can verify that the resources in the cluster are formatted properly before commit or as part
of a CI system. The flux-local test
command will build the Kustomization
resources in the
cluster:
$ flux-local test
============================================= test session starts =============================================
collected 18 items
clusters/dev ......... [ 50%]
clusters/prod ......... [100%]
============================================= 18 passed in 11.43s =============================================
$ flux-local test -v
============================================= test session starts =============================================
collected 18 items
./clusters/dev::certmanager::kustomization PASSED [ 5%]
./clusters/dev::crds::kustomization PASSED [ 11%]
./clusters/dev::games::kustomization PASSED [ 16%]
./clusters/dev::home::kustomization PASSED [ 22%]
./clusters/dev::infrastructure::kustomization PASSED [ 27%]
./clusters/dev::monitoring::kustomization PASSED [ 33%]
./clusters/dev::network::kustomization PASSED [ 38%]
./clusters/dev::services::kustomization PASSED [ 44%]
./clusters/dev::settings::kustomization PASSED [ 50%]
./clusters/prod::certmanager::kustomization PASSED [ 55%]
./clusters/prod::crds::kustomization PASSED [ 61%]
./clusters/prod::games::kustomization PASSED [ 66%]
./clusters/prod::home::kustomization PASSED [ 72%]
./clusters/prod::infrastructure::kustomization PASSED [ 77%]
./clusters/prod::monitoring::kustomization PASSED [ 83%]
./clusters/prod::network::kustomization PASSED [ 88%]
./clusters/prod::services::kustomization PASSED [ 94%]
./clusters/prod::settings::kustomization PASSED [100%]
============================================= 18 passed in 11.81s ============================================
You may also validate HelmRelease
objects can be templated properly with the --enable-helm
flag. This will run kustomize build
then run helm template
on all the HelmRelease
objects
found. Additionally the --enable-kyverno
flag will apply any found ClusterPolicy
objects to
all objects in the cluster and verify they pass:
$ flux-local test --enable-helm --enable-kyverno
============================================= test session starts =============================================
collected 81 items
clusters/dev ..................................... [ 45%]
clusters/prod ............................................ [100%]
======================================== 81 passed in 75.40s (0:01:15) ========================================
You may use flux-local
as a github action to verify the health of the cluster on changes
or PRs. The actions expect to find the flux
and kustomize
binaries installed.
The test
action will validate the cluster will build, and can optionally
validate flux HelmRelease
builds and also verify that all objects pass
kyverno policies (e.g. for determining there are no deprecated api resources
or that ingress objects are valid).
This example will run flux-local test
against the cluster in clusters/prod
with
helm release expansion enabled.
- name: Setup Flux CLI
uses: fluxcd/flux2/action@v2.2.2
- uses: allenporter/flux-local/action/test@4.3.1
with:
path: clusters/prod
enable-helm: true
enable-kyverno: false
The diff
action will show you the final diffs of Kustomization
or HelmRelease
objects that are fully built. While typically you can just read diffs to understand
how kustomzations may be affected, this action also supports overlays and multiple
clusters showing you the final output.
This is an example that diffs a HelmRelease
:
- name: Setup Flux CLI
uses: fluxcd/flux2/action@v2.2.3
- uses: allenporter/flux-local/action/diff@4.3.1
id: diff
with:
live-branch: main
path: clusters/prod
resource: helmrelease
- name: PR Comments
uses: mshick/add-pr-comment@v2
if: ${{ steps.diff.outputs.diff != '' }}
with:
repo-token: ${{ secrets.GITHUB_TOKEN }}
message-failure: Unable to post diff
message: |
`````diff
${{ steps.diff.outputs.diff }}
`````
This is an example of a workflow that will diff Kustomization
and HelmRelease
objects
in a repo with multiple clusters (dev
and prod
):
jobs:
diffs:
name: Compute diffs
runs-on: ubuntu-latest
strategy:
matrix:
cluster_path:
- clusters/dev
- clusters/prod
resource:
- helmrelease
- kustomization
steps:
- name: Setup Flux CLI
uses: fluxcd/flux2/action@v2.2.3
- uses: allenporter/flux-local/action/diff@4.3.1
id: diff
with:
live-branch: main
path: ${{ matrix.cluster_path }}
resource: ${{ matrix.resource }}
- name: PR Comments
uses: mshick/add-pr-comment@v2
if: ${{ steps.diff.outputs.diff != '' }}
with:
repo-token: ${{ secrets.GITHUB_TOKEN }}
message-id: ${{ github.event.pull_request.number }}/${{ matrix.cluster_path }}/${{ matrix.resource }}
message-failure: Unable to post kustomization diff
message: |
`````diff
${{ steps.diff.outputs.diff }}
`````
The flux_local
library documentation for details
on the python APIs provided.