| Name | flux-local JSON |
| Version |
6.0.0
JSON |
| download |
| home_page | https://github.com/allenporter/flux-local |
| Summary | flux-local is a python library and set of tools for managing a flux gitops repository, with validation steps to help improve quality of commits, PRs, and general local testing. |
| upload_time | 2024-10-08 14:33:25 |
| maintainer | None |
| docs_url | None |
| author | Allen Porter |
| requires_python | >=3.10 |
| license | Apache-2.0 |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
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](https://allenporter.github.io/flux-local/) for full quickstart and API reference.
See the [github project](https://github.com/allenporter/flux-local).
## flux-local CLI
The CLI is written in python and packaged as part of the `flux-local` python library, which can be installed using pip:
```bash
$ pip3 install flux-local
```
### flux-local get
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:
```bash
$ 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:
```bash
$ 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:
```bash
$ flux-local get hr -n metallb
NAME REVISION CHART SOURCE
metallb 4.1.14 metallb-metallb bitnami
```
### flux-local build
You can use the `flux-local` cli to build 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:
```bash
$ flux-local build ks --path tests/testdata/cluster/ | kustomize cfg count
Certificate: 2
ClusterPolicy: 1
ConfigMap: 2
GitRepository: 1
HelmRelease: 3
HelmRepository: 3
Kustomization: 4
Namespace: 1
```
Additionally, you can inflate `HelmRelease` objects inside a `Kustomization`. This example
again shows `kustomize cfg count` to parse the yaml output of an inflated `HelmRelease`
objects defined in the cluster:
```bash
$ flux-local build hr podinfo -n podinfo --path tests/testdata/cluster/ | kustomize cfg count
ConfigMap: 1
Deployment: 2
Ingress: 1
Service: 2
```
### flux-local diff
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:
```diff
$ 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:
```diff
$ 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](https://github.com/homeport/dyff) which
is more compact for diffing yaml resources:
```bash
$ 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
```
### flux-local test
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) ========================================
```
## GitHub Action
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.
### test action
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.
```yaml
- 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
```
### diff action
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`:
```yaml
- 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`):
```yaml
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 }}
`````
```
## Library
The `flux_local` [library documentation](https://allenporter.github.io/flux-local/) for details
on the python APIs provided.
Raw data
{
"_id": null,
"home_page": "https://github.com/allenporter/flux-local",
"name": "flux-local",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": null,
"author": "Allen Porter",
"author_email": "allen.porter@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/5f/57/4299e74279fc8f2127551b09a8fecf96b2d72d627e1e265f1df46a2ad73d/flux_local-6.0.0.tar.gz",
"platform": null,
"description": "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.\n\nThis library uses command line tools like kustomize and helm to replicate the behavior of\nflux to gather objects in the cluster. It only looks at the local git repo, and not a live\ncluster. However, this is fine since the local repository has enough information and the\ndefinition is simple. Secrets are ignored as the content is not needed to validate the\ncluster is creating valid objects.\n\nThis library at first glance is little more than shell scripts running commands, but is easier\nto test, maintain, and evolve. This does not support all features of flux, but should\nbe close enough for home use.\n\nSee [documentation](https://allenporter.github.io/flux-local/) for full quickstart and API reference.\nSee the [github project](https://github.com/allenporter/flux-local).\n\n## flux-local CLI\n\nThe CLI is written in python and packaged as part of the `flux-local` python library, which can be installed using pip:\n\n```bash\n$ pip3 install flux-local\n```\n\n### flux-local get\n\nYou can use the `flux-local` cli to inspect objects in the cluster, similar to how you might\nuse the flux command on a real cluster.\n\nThis example lists all Kustomizations in the cluster:\n```bash\n$ flux-local get ks -o wide\nNAME PATH HELMREPOS RELEASES\napps ./tests/testdata/cluster/apps/prod 0 0\ninfra-controllers ./tests/testdata/cluster/infrastructure/controllers 0 0\ninfra-configs ./tests/testdata/cluster/infrastructure/configs 2 0\n```\n\nThis example lists all HelmReleases in the cluster:\n```bash\n$ flux-local get hr -A\nNAMESPACE NAME REVISION CHART SOURCE\npodinfo podinfo 6.3.2 podinfo-podinfo podinfo\nmetallb metallb 4.1.14 metallb-metallb bitnami\n```\n\nThis example lists all HelmReleases in a specific namespace:\n```bash\n$ flux-local get hr -n metallb\nNAME REVISION CHART SOURCE\nmetallb 4.1.14 metallb-metallb bitnami\n```\n\n### flux-local build\n\nYou can use the `flux-local` cli to build objects in a cluster, similar to how you\nuse `kustomize build`, which is used underneath. Here is an example to build all flux\n`Kustomization` objects within a git repository, using `kustomize cfg count` to parse\nthe yaml output:\n\n```bash\n$ flux-local build ks --path tests/testdata/cluster/ | kustomize cfg count\nCertificate: 2\nClusterPolicy: 1\nConfigMap: 2\nGitRepository: 1\nHelmRelease: 3\nHelmRepository: 3\nKustomization: 4\nNamespace: 1\n```\n\nAdditionally, you can inflate `HelmRelease` objects inside a `Kustomization`. This example\nagain shows `kustomize cfg count` to parse the yaml output of an inflated `HelmRelease`\nobjects defined in the cluster:\n\n```bash\n$ flux-local build hr podinfo -n podinfo --path tests/testdata/cluster/ | kustomize cfg count\nConfigMap: 1\nDeployment: 2\nIngress: 1\nService: 2\n```\n\n### flux-local diff\n\nYou may also use `flux-local` to verify your local changes to cluster resources have the desird\neffect. This is similar to `flux diff` but entirely local. This will run a local `kustomize build`\nfirst against the local repo then again against a prior repo revision, then prints the output:\n```diff\n$ flux-local diff ks apps\n---\n\n+++\n\n@@ -2,6 +2,13 @@\n\n kind: Namespace\n metadata:\n name: podinfo\n+- apiVersion: v1\n+ data:\n+ foo: bar\n+ kind: ConfigMap\n+ metadata:\n+ name: podinfo-config\n+ namespace: podinfo\n - apiVersion: helm.toolkit.fluxcd.io/v2beta1\n kind: HelmRelease\n metadata:\n\n```\n\nAdditionally `flux-local` can inflate a `HelmRelease` locally and show diffs in the output\nobjects. This is similar to `flux diff` but for HelmReleases:\n\n```diff\n$ flux-local diff hr -n podinfo podinfo\n---\n\n+++\n\n@@ -33,8 +33,8 @@\n\n labels:\n app.kubernetes.io/managed-by: Helm\n app.kubernetes.io/name: podinfo\n- app.kubernetes.io/version: 6.3.2\n- helm.sh/chart: podinfo-6.3.2\n+ app.kubernetes.io/version: 6.3.3\n+ helm.sh/chart: podinfo-6.3.3\n name: podinfo\n spec:\n ports:\n...\n```\n\nYou may also use an external diff program such as [dyff](https://github.com/homeport/dyff) which\nis more compact for diffing yaml resources:\n```bash\n$ git status\nOn branch dev\nYour branch is up to date with 'origin/dev'.\n\nChanges not staged for commit:\n\tmodified: home/dev/hajimari-values.yaml\n\n$ export DIFF=\"dyff between --omit-header --color on\"\n$ flux-local diff ks home --path clusters/dev/\n\nspec.chart.spec.version (HelmRelease/hajimari/hajimari)\n \u00b1 value change\n - 2.0.2\n + 2.0.1\n\n$ flux-local diff hr hajimari -n hajimari --path clusters/dev/\n\nmetadata.labels.helm.sh/chart (ClusterRoleBinding/default/hajimari)\n \u00b1 value change\n - hajimari-2.0.2\n + hajimari-2.0.1\n\nmetadata.labels.helm.sh/chart (PersistentVolumeClaim/default/hajimari-data)\n \u00b1 value change\n - hajimari-2.0.2\n + hajimari-2.0.1\n```\n\n\n### flux-local test\n\nYou can verify that the resources in the cluster are formatted properly before commit or as part\nof a CI system. The `flux-local test` command will build the `Kustomization` resources in the\ncluster:\n\n```\n$ flux-local test\n============================================= test session starts =============================================\ncollected 18 items\n\nclusters/dev ......... [ 50%]\nclusters/prod ......... [100%]\n\n============================================= 18 passed in 11.43s =============================================\n$ flux-local test -v\n============================================= test session starts =============================================\ncollected 18 items\n\n./clusters/dev::certmanager::kustomization PASSED [ 5%]\n./clusters/dev::crds::kustomization PASSED [ 11%]\n./clusters/dev::games::kustomization PASSED [ 16%]\n./clusters/dev::home::kustomization PASSED [ 22%]\n./clusters/dev::infrastructure::kustomization PASSED [ 27%]\n./clusters/dev::monitoring::kustomization PASSED [ 33%]\n./clusters/dev::network::kustomization PASSED [ 38%]\n./clusters/dev::services::kustomization PASSED [ 44%]\n./clusters/dev::settings::kustomization PASSED [ 50%]\n./clusters/prod::certmanager::kustomization PASSED [ 55%]\n./clusters/prod::crds::kustomization PASSED [ 61%]\n./clusters/prod::games::kustomization PASSED [ 66%]\n./clusters/prod::home::kustomization PASSED [ 72%]\n./clusters/prod::infrastructure::kustomization PASSED [ 77%]\n./clusters/prod::monitoring::kustomization PASSED [ 83%]\n./clusters/prod::network::kustomization PASSED [ 88%]\n./clusters/prod::services::kustomization PASSED [ 94%]\n./clusters/prod::settings::kustomization PASSED [100%]\n\n============================================= 18 passed in 11.81s ============================================\n```\n\nYou may also validate `HelmRelease` objects can be templated properly with the `--enable-helm`\nflag. This will run `kustomize build` then run `helm template` on all the `HelmRelease` objects\nfound. Additionally the `--enable-kyverno` flag will apply any found `ClusterPolicy` objects to\nall objects in the cluster and verify they pass:\n```\n$ flux-local test --enable-helm --enable-kyverno\n============================================= test session starts =============================================\ncollected 81 items\n\nclusters/dev ..................................... [ 45%]\nclusters/prod ............................................ [100%]\n\n======================================== 81 passed in 75.40s (0:01:15) ========================================\n```\n\n## GitHub Action\n\nYou may use `flux-local` as a github action to verify the health of the cluster on changes\nor PRs. The actions expect to find the `flux` and `kustomize` binaries installed.\n\n### test action\n\nThe `test` action will validate the cluster will build, and can optionally\nvalidate flux `HelmRelease` builds and also verify that all objects pass\nkyverno policies (e.g. for determining there are no deprecated api resources\nor that ingress objects are valid).\n\nThis example will run `flux-local test` against the cluster in `clusters/prod` with\nhelm release expansion enabled.\n\n```yaml\n- name: Setup Flux CLI\n uses: fluxcd/flux2/action@v2.2.2\n- uses: allenporter/flux-local/action/test@4.3.1\n with:\n path: clusters/prod\n enable-helm: true\n enable-kyverno: false\n```\n\n### diff action\n\nThe `diff` action will show you the final diffs of `Kustomization` or `HelmRelease`\nobjects that are fully built. While typically you can just read diffs to understand\nhow kustomzations may be affected, this action also supports overlays and multiple\nclusters showing you the final output.\n\nThis is an example that diffs a `HelmRelease`:\n\n```yaml\n- name: Setup Flux CLI\n uses: fluxcd/flux2/action@v2.2.3\n- uses: allenporter/flux-local/action/diff@4.3.1\n id: diff\n with:\n live-branch: main\n path: clusters/prod\n resource: helmrelease\n- name: PR Comments\n uses: mshick/add-pr-comment@v2\n if: ${{ steps.diff.outputs.diff != '' }}\n with:\n repo-token: ${{ secrets.GITHUB_TOKEN }}\n message-failure: Unable to post diff\n message: |\n `````diff\n ${{ steps.diff.outputs.diff }}\n `````\n```\n\nThis is an example of a workflow that will diff `Kustomization` and `HelmRelease` objects\nin a repo with multiple clusters (`dev` and `prod`):\n\n```yaml\njobs:\n diffs:\n name: Compute diffs\n runs-on: ubuntu-latest\n strategy:\n matrix:\n cluster_path:\n - clusters/dev\n - clusters/prod\n resource:\n - helmrelease\n - kustomization\n steps:\n - name: Setup Flux CLI\n uses: fluxcd/flux2/action@v2.2.3\n - uses: allenporter/flux-local/action/diff@4.3.1\n id: diff\n with:\n live-branch: main\n path: ${{ matrix.cluster_path }}\n resource: ${{ matrix.resource }}\n - name: PR Comments\n uses: mshick/add-pr-comment@v2\n if: ${{ steps.diff.outputs.diff != '' }}\n with:\n repo-token: ${{ secrets.GITHUB_TOKEN }}\n message-id: ${{ github.event.pull_request.number }}/${{ matrix.cluster_path }}/${{ matrix.resource }}\n message-failure: Unable to post kustomization diff\n message: |\n `````diff\n ${{ steps.diff.outputs.diff }}\n `````\n```\n\n## Library\n\nThe `flux_local` [library documentation](https://allenporter.github.io/flux-local/) for details\non the python APIs provided.\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "flux-local is a python library and set of tools for managing a flux gitops repository, with validation steps to help improve quality of commits, PRs, and general local testing.",
"version": "6.0.0",
"project_urls": {
"Homepage": "https://github.com/allenporter/flux-local"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ea0784cd0ffe60350719f311e0ef2aea334ab8990ae51d5073dfab674ed791c2",
"md5": "50a03131492f0245ca0a73e2adcb2782",
"sha256": "53b7607d3fd80e6e931a28b1f251f0a29446f2ae5acfb46f9ba8bf8d8c134083"
},
"downloads": -1,
"filename": "flux_local-6.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "50a03131492f0245ca0a73e2adcb2782",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 53934,
"upload_time": "2024-10-08T14:33:24",
"upload_time_iso_8601": "2024-10-08T14:33:24.626784Z",
"url": "https://files.pythonhosted.org/packages/ea/07/84cd0ffe60350719f311e0ef2aea334ab8990ae51d5073dfab674ed791c2/flux_local-6.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "5f574299e74279fc8f2127551b09a8fecf96b2d72d627e1e265f1df46a2ad73d",
"md5": "6353dc332c62166aa116a9cd71809910",
"sha256": "850df40d1ca88a7ad4b45d6390b043102da06240050d0115ef73c1d558a1a72e"
},
"downloads": -1,
"filename": "flux_local-6.0.0.tar.gz",
"has_sig": false,
"md5_digest": "6353dc332c62166aa116a9cd71809910",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 56720,
"upload_time": "2024-10-08T14:33:25",
"upload_time_iso_8601": "2024-10-08T14:33:25.844174Z",
"url": "https://files.pythonhosted.org/packages/5f/57/4299e74279fc8f2127551b09a8fecf96b2d72d627e1e265f1df46a2ad73d/flux_local-6.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-08 14:33:25",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "allenporter",
"github_project": "flux-local",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "flux-local"
}
