Mirrors/flux2
1
0
Fork 0
mirror of synced 2026-02-06 19:05:55 +00:00
Code Issues Packages Projects Releases Wiki Activity

Replace GitOps Toolkit in docs

Browse Source 
This replaces most mentions of "GitOps Toolkit" and "toolkit" with
"Flux". I have adopted the style of using "Flux v2" in the first
mention, and thereafter just "Flux".

Signed-off-by: Michael Bridgen <michael@weave.works>
This commit is contained in:
Michael Bridgen
2020-10-29 16:31:20 +00:00
parent 071982097a
commit 5e96cec95b
9 changed files with 92 additions and 91 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
CONTRIBUTING.md
View File

@@ -1,8 +1,10 @@
# Contributing
The GitOps Toolkit is [Apache 2.0 licensed](https://github.com/fluxcd/flux2/blob/master/LICENSE)
and accepts contributions via GitHub pull requests. This document outlines
some of the conventions on to make it easier to get your contribution accepted.
Flux is [Apache 2.0
licensed](https://github.com/fluxcd/flux2/blob/main/LICENSE) and
accepts contributions via GitHub pull requests. This document outlines
some of the conventions on to make it easier to get your contribution
accepted.
We gratefully welcome improvements to issues and documentation as well as to
code.
@@ -31,9 +33,9 @@ to join the conversation (there you can also add calendar invites
to your Google calendar for our [Flux
meeting](https://docs.google.com/document/d/1l_M0om0qUEN_NNiGgpqJ2tvsF2iioHkaARDeh6b70B0/view)).
## Understanding the GitOps Toolkit
## Understanding Flux and the GitOps Toolkit
If you are entirely new to the GitOps Toolkit,
If you are entirely new to Flux and the GitOps Toolkit,
you might want to take a look at the [introductory talk and demo](https://www.youtube.com/watch?v=qQBtSkgl7tI).
This project is composed of:

6
README.md
View File

@@ -53,7 +53,7 @@ To get started with Flux, start [browsing the
documentation](https://toolkit.fluxcd.io) or get started with one of
the following guides:
- [Get started with GitOps Toolkit (deep dive)](https://toolkit.fluxcd.io/get-started/)
- [Get started with Flux (deep dive)](https://toolkit.fluxcd.io/get-started/)
- [Installation](https://toolkit.fluxcd.io/guides/installation/)
- [Manage Helm Releases](https://toolkit.fluxcd.io/guides/helmreleases/)
- [Setup Notifications](https://toolkit.fluxcd.io/guides/notifications/)
@@ -88,12 +88,12 @@ guides](https://toolkit.fluxcd.io/dev-guides/).
## Community
The GitOps Toolkit is always looking for new contributors and there are a multitude of ways to get involved. Depending on what you want to do, some of the following bits might be your first steps:
The Flux project is always looking for new contributors and there are a multitude of ways to get involved. Depending on what you want to do, some of the following bits might be your first steps:
- Join our upcoming dev meetings ([meeting access and agenda](https://docs.google.com/document/d/1l_M0om0qUEN_NNiGgpqJ2tvsF2iioHkaARDeh6b70B0/view))
- Talk to us in the #flux channel on [CNCF Slack](https://slack.cncf.io/)
- Join the [planning discussions](https://github.com/fluxcd/flux2/discussions)
- And if you are completely new to the GitOps Toolkit, take a look at our [Get Started guide](https://toolkit.fluxcd.io/get-started/) and give us feedback
- And if you are completely new to Flux and the GitOps Toolkit, take a look at our [Get Started guide](https://toolkit.fluxcd.io/get-started/) and give us feedback
- To be part of the conversation about Flux's development, [join the flux-dev mailing list](https://lists.cncf.io/g/cncf-flux-dev).
- Check out [how to contribute](CONTRIBUTING.md) to the project

2
docs/dev-guides/source-watcher.md
View File

@@ -3,7 +3,7 @@
In this guide you'll be developing a Kubernetes controller with
[Kubebuilder](https://github.com/kubernetes-sigs/kubebuilder)
that subscribes to [GitRepository](../components/source/gitrepositories.md)
events and reacts to revision changes by downloading the artifact produced by
events and reacts to revision changes by downloading the artifact produced by
[source-controller](../components/source/controller.md).
## Prerequisites

34
docs/faq/index.md
View File

@@ -2,38 +2,38 @@
## General questions
### What does the GitOps Toolkit mean for Flux?
### What does Flux v2 mean for Flux?
Flux v1 is a monolithic do-it-all operator; the GitOps Toolkit separates the functionalities into specialized controllers.
Flux v1 is a monolithic do-it-all operator; Flux v2 separates the functionalities into specialized controllers, collectively called the GitOps Toolkit.
Flux v2 will be a curated configuration of the GitOps Toolkit, which you can install and operate simply using the `flux` command. You can easily pick and choose the functionality you need and extend it to serve your own purposes.
You can install and operate Flux v2 simply using the `flux` command. You can easily pick and choose the functionality you need and extend it to serve your own purposes.
The timeline we are looking at right now is:
1. Put Flux v1 into maintenance mode (no new features being added; bugfixes and CVEs patched only).
1. Continue work on [GitOps Toolkit roadmap](https://toolkit.fluxcd.io/roadmap/).
1. We will provide transition guides for specific user groups, e.g. users of Flux v1 in read-only mode, or of Helm Operator v1, etc. once the functionality is integrated in the GitOps Toolkit and it's deemed "ready".
1. Continue work on the [Flux v2 roadmap](https://toolkit.fluxcd.io/roadmap/).
1. We will provide transition guides for specific user groups, e.g. users of Flux v1 in read-only mode, or of Helm Operator v1, etc. once the functionality is integrated into Flux v2 and it's deemed "ready".
1. Once the use-cases of Flux v1 are covered, we will continue supporting Flux v1 for 6 months. This will be the transition period before it's considered unsupported.
### Why did you rewrite Flux?
The GitOps Toolkit implements its functionality in individual controllers, which allowed us to address long-standing feature requests much more easily.
Flux v2 implements its functionality in individual controllers, which allowed us to address long-standing feature requests much more easily.
By basing these controllers on modern Kubernetes tooling (`controller-runtime` libraries), they can be dynamically configured with Kubernetes custom resources either by cluster admins or by other automated tools -- and you get greatly increased observability.
This gave us the opportunity to build the GitOps Toolkit with the top Flux feature requests in mind:
This gave us the opportunity to build Flux v2 with the top Flux v1 feature requests in mind:
- Supporting multiple source Git repositories
- Operational insight through health checks, events and alerts
- Multi-tenancy capabilities, like applying each source repository with its own set of permissions
On top of that, testing the GitOps Toolkit and understanding the codebase becomes a lot easier.
On top of that, testing the individual components and understanding the codebase becomes a lot easier.
### What are significant new differences between Flux v1 and the GitOps Toolkit?
### What are significant new differences between Flux v1 and Flux v2?
#### Reconciliation
Flux v1 | Toolkit component driven "Flux v2"
Flux v1 | Flux v2
---------------------------------- | ----------------------------------
Limited to a single Git repository | Multiple Git repositories
Declarative config via arguments in the Flux deployment | `GitRepository` custom resource, which produces an artifact which can be reconciled by other controllers
@@ -43,7 +43,7 @@ Credentials config via Arguments and/or Secret volume mounts in the Flux pod | C
#### `kustomize` support
Flux v1 | Toolkit component driven "Flux v2"
Flux v1 | Flux v2
---------------------------------- | ----------------------------------
Declarative config through `.flux.yaml` files in the Git repository | Declarative config through a `Kustomization` custom resource, consuming the artifact from the GitRepository
Manifests are generated via shell exec and then reconciled by `fluxd` | Generation, server-side validation, and reconciliation is handled by a specialised `kustomize-controller`
@@ -53,7 +53,7 @@ Support for custom commands and generators executed by fluxd in a POSIX shell |
#### Helm integration
Flux v1 | Toolkit component driven "Flux v2"
Flux v1 | Flux v2
---------------------------------- | ----------------------------------
Declarative config in a single Helm custom resource | Declarative config through `HelmRepository`, `GitRepository`, `Bucket`, `HelmChart` and `HelmRelease` custom resources
Chart synchronisation embedded in the operator | Extensive release configuration options, and a reconciliation interval per source
@@ -65,10 +65,10 @@ Chart changes from Git sources are determined from Git metadata | Chart changes
#### Notifications, webhooks, observability
Flux v1 | Toolkit component driven "Flux v2"
Flux v1 | Flux v2
---------------------------------- | ----------------------------------
Emits "custom Flux events" to a webhook endpoint | Emits Kubernetes events for all custom resources part of the Toolkit
RPC endpoint can be configured to a 3rd party solution like FluxCloud to be forwarded as notifications to e.g. Slack | Toolkit components can be configured to POST the events to a `notification-controller` endpoint. Selective forwarding of POSTed events as notifications using `Provider` and `Alert` custom resources.
Emits "custom Flux events" to a webhook endpoint | Emits Kubernetes events for included custom resources
RPC endpoint can be configured to a 3rd party solution like FluxCloud to be forwarded as notifications to e.g. Slack | Flux v2 components can be configured to POST the events to a `notification-controller` endpoint. Selective forwarding of POSTed events as notifications using `Provider` and `Alert` custom resources.
Webhook receiver is a side-project | Webhook receiver, handling a wide range of platforms, is included
Unstructured logging | Structured logging for all components
Custom Prometheus metrics | Generic / common `controller-runtime` Prometheus metrics
@@ -77,10 +77,10 @@ Custom Prometheus metrics | Generic / common `controller-runtime` Prometheus met
There are a variety of ways and we look forward to having you on board building the future of GitOps together:
- [Discuss the direction](https://github.com/fluxcd/flux2/discussions) of the GitOps Toolkit with us
- [Discuss the direction](https://github.com/fluxcd/flux2/discussions) of Flux v2 with us
- Join us in #flux-dev on the [CNCF Slack](https://slack.cncf.io)
- Check out our [contributor docs](https://toolkit.fluxcd.io/contributing/)
- Take a look at the [roadmap of the GitOps Toolkit](https://toolkit.fluxcd.io/roadmap/)
- Take a look at the [roadmap for Flux v2](https://toolkit.fluxcd.io/roadmap/)
### Are there any breaking changes?

28
docs/get-started/index.md
View File

@@ -1,4 +1,4 @@
# Get started with GitOps Toolkit
# Get started with Flux v2
## Prerequisites
@@ -6,7 +6,7 @@ You will need two Kubernetes clusters version 1.16 or newer and kubectl version
For a quick local test, you can use [Kubernetes kind](https://kind.sigs.k8s.io/docs/user/quick-start/).
Any other Kubernetes setup will work as well though.
In order to follow the guide you'll need a GitHub account and a
In order to follow the guide you'll need a GitHub account and a
[personal access token](https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line)
that can create repositories (check all permissions under `repo`).
@@ -17,14 +17,13 @@ export GITHUB_TOKEN=<your-token>
export GITHUB_USER=<your-username>
```
## Install the toolkit CLI
## Install the Flux CLI
To install the latest `flux` release on MacOS and Linux using
[Homebrew](https://brew.sh/) run:
```sh
brew tap fluxcd/tap
brew install flux
brew install fluxcd/tap/flux
```
Or install `flux` by downloading precompiled binaries using a Bash script:
@@ -35,10 +34,11 @@ curl -s https://toolkit.fluxcd.io/install.sh | sudo bash
The install script downloads the flux binary to `/usr/local/bin`.
Binaries for **macOS**, **Windows** and **Linux** AMD64/ARM are available for download on the
Binaries for **macOS**, **Windows** and **Linux** AMD64/ARM are available for download on the
[release page](https://github.com/fluxcd/flux2/releases).
To configure your shell to load flux completions add to your Bash profile:
To configure your shell to load `flux` completions add to your Bash
profile:
```sh
# ~/.bashrc or ~/.bash_profile
@@ -52,7 +52,7 @@ To configure your shell to load flux completions add to your Bash profile:
You'll be using a dedicated Git repository e.g. `fleet-infra` to manage one or more Kubernetes clusters.
This guide assumes that you have two clusters, one for staging and one for production.
Using the toolkit CLI you'll do the following:
Using the Flux CLI you'll do the following:
- configure each cluster to synchronise with a directory inside the fleet repository
- register app sources (git repositories) that contain plain Kubernetes manifests or Kustomize overlays
@@ -93,8 +93,8 @@ flux bootstrap github \
you can use `--arch=arm` for ARMv7 32-bit container images
and `--arch=arm64` for ARMv8 64-bit container images.
The bootstrap command creates a repository if one doesn't exist and
commits the toolkit components manifests to the default branch at the specified path.
The bootstrap command creates a repository if one doesn't exist, and
commits the manifests for the Flux components to the default branch at the specified path.
Then it configures the target cluster to synchronize with the specified path inside the repository.
If you wish to create the repository under a GitHub organization:
@@ -137,9 +137,9 @@ If you prefer GitLab, export `GITLAB_TOKEN` env var and use the command [flux bo
!!! hint "Idempotency"
It is safe to run the bootstrap command as many times as you want.
If the toolkit components are present on the cluster,
If the Flux components are present on the cluster,
the bootstrap command will perform an upgrade if needed.
You can target a specific toolkit [version](https://github.com/fluxcd/flux2/releases)
You can target a specific Flux [version](https://github.com/fluxcd/flux2/releases)
with `flux bootstrap --version=<semver>`.
## Staging workflow
@@ -173,7 +173,7 @@ flux create kustomization webapp-common \
--export > ./staging-cluster/webapp-common.yaml
```
Create a kustomization for the backend service that depends on common:
Create a kustomization for the backend service that depends on common:
```sh
flux create kustomization webapp-backend \
@@ -188,7 +188,7 @@ flux create kustomization webapp-backend \
--export > ./staging-cluster/webapp-backend.yaml
```
Create a kustomization for the frontend service that depends on backend:
Create a kustomization for the frontend service that depends on backend:
```sh
flux create kustomization webapp-frontend \

56
docs/guides/installation.md
View File

@@ -1,20 +1,19 @@
# Installation
# Installation
This guide walks you through setting up the GitOps Toolkit
to manage one or more Kubernetes clusters.
This guide walks you through setting up Flux v2 (hereafter: "Flux") to
manage one or more Kubernetes clusters.
## Prerequisites
You will need a Kubernetes cluster version **1.16** or newer
and kubectl version **1.18** or newer.
## Install the toolkit CLI
## Install the Flux CLI
With Homebrew:
```sh
brew tap fluxcd/tap
brew install flux
brew install fluxcd/tap/flux
```
With Bash:
@@ -29,7 +28,7 @@ curl -s https://toolkit.fluxcd.io/install.sh | sudo bash
Command-line completion for `zsh`, `fish`, and `powershell`
are also supported with their own sub-commands.
Binaries for macOS, Windows and Linux AMD64/ARM are available for download on the
Binaries for macOS, Windows and Linux AMD64/ARM are available for download on the
[release page](https://github.com/fluxcd/flux2/releases).
Verify that your cluster satisfies the prerequisites with:
@@ -40,17 +39,18 @@ flux check --pre
## Bootstrap
Using the `flux bootstrap` command you can install the toolkit on a Kubernetes cluster
and configure it to manage itself from a Git repository.
Using the `flux bootstrap` command you can install Flux on a
Kubernetes cluster and configure it to manage itself from a Git
repository.
The bootstrap creates a Git repository if one doesn't exist and
commits the toolkit components manifests to the main branch.
Then it configures the target cluster to synchronize with that
repository by setting up SSH deploy keys.
commits the Flux components manifests to the main branch. Then it
configures the target cluster to synchronize with that repository by
setting up SSH deploy keys.
If the toolkit components are present on the cluster,
the bootstrap command will perform an upgrade if needed.
The bootstrap is idempotent, it's safe to run the command as many times as you want.
If the Flux components are present on the cluster, the bootstrap
command will perform an upgrade if needed. The bootstrap is
idempotent, it's safe to run the command as many times as you want.
You can choose what components to install and for which cluster with:
@@ -66,7 +66,7 @@ flux bootstrap <GIT-PROVIDER> \
you can use `--arch=arm` for ARMv7 32-bit container images
and `--arch=arm64` for ARMv8 64-bit container images.
If you wish to install a specific version, use the toolkit
If you wish to install a specific version, use the Flux
[release tag](https://github.com/fluxcd/flux2/releases) e.g. `--version=v0.0.14`.
With `--path` you can configure the directory which will be used to reconcile the target cluster.
@@ -81,7 +81,7 @@ cluster e.g. `staging-cluster` and `production-cluster`:
│   └── toolkit-source.yaml
└── production-cluster # <- path=production-cluster
└── flux-system
```
```
!!! hint "Change the default branch"
If you wish to change the branch to something else than main, create the repository manually,
@@ -166,7 +166,7 @@ flux bootstrap gitlab \
```
!!! hint "Authentication"
When providing the `--ssh-hostname`, a read-only (SSH) deploy key will be added
When providing the `--ssh-hostname`, a read-only (SSH) deploy key will be added
to your repository, otherwise your GitLab personal token will be used to
authenticate against the HTTPS endpoint instead.
@@ -208,7 +208,7 @@ Create a directory inside the repository:
mkdir -p ./my-cluster/flux-system
```
Generate the toolkit manifests with:
Generate the Flux manifests with:
```sh
flux install --version=latest \
@@ -256,7 +256,7 @@ Apply the manifests on your cluster:
kubectl apply -f ./my-cluster/flux-system/toolkit-components.yaml
```
Verify that the toolkit controllers have started:
Verify that the controllers have started:
```sh
flux check
@@ -274,7 +274,7 @@ flux create source git flux-system \
```
You will be prompted to add a deploy key to your repository.
If you don't specify the SSH algorithm, then flux will generate an RSA 2048 bits key.
If you don't specify the SSH algorithm, then `flux` will generate an RSA 2048 bits key.
If your Git server supports basic auth, you can set the URL to HTTPS and specify the credentials with:
@@ -319,11 +319,11 @@ git add -A && git commit -m "update toolkit" && git push
```
The source-controller will pull the changes on the cluster, then the kustomize-controller
will perform a rolling update of all toolkit components including itself.
will perform a rolling update of all Flux components including itself.
## Dev install
For testing purposes you can install the toolkit without storing its manifests in a Git repository.
For testing purposes you can install Flux without storing its manifests in a Git repository.
Here is the equivalent to `fluxctl install`:
@@ -375,18 +375,18 @@ flux create helmrelease sealed-secrets \
## Monitoring with Prometheus and Grafana
The GitOps Toolkit comes with a monitoring stack composed of Prometheus and Grafana. The controllers expose
metrics that can be used to track the readiness of the cluster reconciliation process.
Flux comes with a monitoring stack composed of Prometheus and Grafana. The controllers expose
metrics that can be used to track the readiness of the cluster reconciliation process.
To install the monitoring stack please follow this [guide](monitoring.md).
## Uninstall
You can uninstall the toolkit components with:
You can uninstall the Flux components with:
```sh
flux uninstall --crds
```
The above command will delete the toolkit custom resources definitions, the controllers
and the namespace where they were installed.
The above command will delete the custom resources definitions, the
controllers, and the namespace where they were installed.

6
docs/guides/monitoring.md
View File

@@ -1,8 +1,8 @@
# Monitoring
# Monitoring
This guide walks you through configuring monitoring for the GitOps Toolkit control plane.
This guide walks you through configuring monitoring for the Flux control plane.
The toolkit comes with a monitoring stack composed of:
Flux comes with a monitoring stack composed of:
* **Prometheus** server - collects metrics from the toolkit controllers and stores them for 2h
* **Grafana** dashboards - displays the control plane resource usage and reconciliation stats

33
docs/index.md
View File

@@ -1,19 +1,18 @@
# GitOps Toolkit
# Flux v2
The GitOps Toolkit is a set of composable APIs and specialized tools
that can be used to build a Continuous Delivery platform on top of Kubernetes.
Flux is a tool for keeping Kubernetes clusters in sync with sources of
configuration (like Git repositories), and automating updates to
configuration when there is new code to deploy.
These tools are build with Kubernetes controller-runtime libraries, and they
can be dynamically configured with Kubernetes custom resources either by
cluster admins or by other automated tools.
The GitOps Toolkit components interact with each other via Kubernetes
events and are responsible for the reconciliation of their designated API objects.
Flux version 2 ("Flux v2") is built from the ground up to use Kubernetes'
API extension system, and to integrate with Prometheus and other core
components of the Kubernetes ecosystem. In version 2, Flux supports
multi-tenancy and support for syncing an arbitrary number of Git
repositories, among other long-requested features.
!!! hint "Work in Progress"
We envision a future where **Flux v2** and **Helm Operator v2** will be assembled from
the GitOps Toolkit components. The Flux CD team is looking for feedback and help as
the toolkit is in an active experimentation phase.
If you wish to take part in this quest please reach out to us on Slack or GitHub.
Flux v2 is constructed with the [GitOps Toolkit](#gitops-toolkit), a
set of composable APIs and specialized tools for building Continuous
Delivery on top of Kubernetes.
![overview](diagrams/gitops-toolkit.png)
@@ -35,7 +34,7 @@ Target features:
Components:
- [Toolkit CLI](https://github.com/fluxcd/flux2)
- [Flux CLI](https://github.com/fluxcd/flux2)
- [Source Controller](components/source/controller.md)
- [GitRepository CRD](components/source/gitrepositories.md)
- [HelmRepository CRD](components/source/helmrepositories.md)
@@ -52,17 +51,17 @@ Components:
## Get Started
!!!hint "Get started with the GitOps Toolkit!"
!!!hint "Get started with Flux v2!"
Following this [guide](get-started/index.md) will just take a couple of minutes to complete: After installing the `flux` binary and running a couple of very simple commands, you will have a GitOps workflow setup which involves a staging and a production cluster.
## Community
The GitOps Toolkit is always looking for new contributors and there are a multitude of ways to get involved. Depending on what you want to do, some of the following bits might be your first steps:
The Flux project is always looking for new contributors and there are a multitude of ways to get involved. Depending on what you want to do, some of the following bits might be your first steps:
- Join our upcoming dev meetings ([meeting access and agenda](https://docs.google.com/document/d/1l_M0om0qUEN_NNiGgpqJ2tvsF2iioHkaARDeh6b70B0/view))
- Talk to us in the #flux channel on [CNCF Slack](https://slack.cncf.io/)
- Join the [planning discussions](https://github.com/fluxcd/flux2/discussions)
- And if you are completely new to the GitOps Toolkit, take a look at our [Get Started guide](get-started/index.md) and give us feedback
- And if you are completely new to Flux v2 and the GitOps Toolkit, take a look at our [Get Started guide](get-started/index.md) and give us feedback
- Check out [how to contribute](contributing/index.md) to the project
## Featured Talks

6
docs/roadmap/index.md
View File

@@ -1,6 +1,6 @@
# Roadmap
In our planning discussions for the GitOps Toolkit we identified largely three areas of work:
In our planning discussions we identified broad three areas of work:
- Feature parity with Flux v1 in read-only mode
- Feature parity with the image-update functionality in Flux v1
@@ -14,7 +14,7 @@ All of the above will constitute "Flux v2".
[= 90% "90%"]
This would be the first stepping stone: we want the GitOps Toolkit to be on-par with today's Flux in
This would be the first stepping stone: we want Flux v2 to be on-par with today's Flux in
[read-only mode](https://github.com/fluxcd/flux/blob/master/docs/faq.md#can-i-run-flux-with-readonly-git-access)
and [FluxCloud](https://github.com/justinbarrick/fluxcloud) notifications.
@@ -59,7 +59,7 @@ Tasks
- [ ] Implement an image scanning controller
- [x] <span style="color:grey">Design the automation component</span>
- [ ] Implement the image scan/patch/push workflow
- [ ] Integrate the new components in the toolkit assembler
- [ ] Integrate the new components in the Flux CLI
- [ ] Create a migration guide from Flux annotations
## The road to Helm Operator v2