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

Merge branch 'main' into patch-1

Browse Source
This commit is contained in:
Jonas Kello
2021-01-15 13:55:42 +01:00
committed by GitHub
parent 714f9df3cf 6a7f1e7d48
commit ca480164b7
76 changed files with 1382 additions and 595 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -1,14 +1,24 @@
# Get started with Flux v2
!!! note "Basic knowledge"
This guide assumes you have some understanding of the core concepts and have read the introduction to Flux.
The core concepts used in this guide are [GitOps](../core-concepts/index.md#gitops),
[Sources](../core-concepts/index.md#sources), [Kustomization](../core-concepts/index.md#kustomization).
In this tutorial, you will deploy an application to a kubernetes cluster with Flux
and manage the cluster in a complete GitOps manner.
You'll be using a dedicated Git repository e.g. `fleet-infra` to manage your Kubernetes clusters.
## Prerequisites
You will need two Kubernetes clusters version 1.16 or newer and kubectl version 1.18.
In order to follow the guide, you will need a Kubernetes cluster version 1.16 or newer and kubectl version 1.18.
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
Flux is installed in a GitOps way and its manifest will be pushed to the repository,
so you will also 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`).
that can create repositories (check all permissions under `repo`) to enable Flux do this.
Export your GitHub personal access token and username:
@@ -51,24 +61,13 @@ To configure your shell to load `flux` [bash completions](../cmd/flux_completion
[`zsh`](../cmd/flux_completion_zsh.md), [`fish`](../cmd/flux_completion_fish.md), and [`powershell`](../cmd/flux_completion_powershell.md) are also supported with their own sub-commands.
## GitOps workflow
## Install Flux components
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 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
- configure app deployments on both clusters (pre-releases on staging, semver releases on production)
## Staging bootstrap
Create the staging cluster using Kubernetes kind or set the kubectl context to an existing cluster:
Create the cluster using Kubernetes kind or set the kubectl context to an existing cluster:
```sh
kind create cluster --name staging
kubectl cluster-info --context kind-staging
kind create cluster
kubectl cluster-info
```
Verify that your staging cluster satisfies the prerequisites with:
@@ -88,17 +87,18 @@ flux bootstrap github \
--owner=$GITHUB_USER \
--repository=fleet-infra \
--branch=main \
--path=staging-cluster \
--path=./clusters/my-cluster \
--personal
```
!!! hint "ARM"
When deploying to a Kubernetes cluster with ARM architecture,
you can use `--arch=arm` for ARMv7 32-bit container images
and `--arch=arm64` for ARMv8 64-bit container images.
!!! hint "Multi-arch images"
The component images are published as [multi-arch container images](https://docs.docker.com/docker-for-mac/multi-arch/)
with support for Linux `amd64`, `arm64` and `armv7` (e.g. 32bit Raspberry Pi)
architectures.
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.
The bootstrap command creates a repository if one doesn't exist,
commits the manifests for the Flux components to the default branch at the specified path,
and installs the Flux components.
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:
@@ -110,13 +110,13 @@ flux bootstrap github \
--branch=<organization default branch> \
--team=<team1-slug> \
--team=<team2-slug> \
--path=staging-cluster
--path=./clusters/my-cluster
```
Example output:
```console
$ flux bootstrap github --owner=gitopsrun --repository=fleet-infra --path=staging-cluster --team=devs
$ flux bootstrap github --owner=gitopsrun --team=devs --repository=fleet-infra --path=./clusters/my-cluster
► connecting to github.com
✔ repository created
✔ devs team access granted
@@ -138,7 +138,8 @@ deployment "notification-controller" successfully rolled out
✔ bootstrap finished
```
If you prefer GitLab, export `GITLAB_TOKEN` env var and use the command [flux bootstrap gitlab](../cmd/flux_bootstrap_gitlab.md).
If you prefer GitLab, export `GITLAB_TOKEN` env var and
use the command [flux bootstrap gitlab](../guides/installation.md#gitlab-and-gitlab-enterprise).
!!! hint "Idempotency"
It is safe to run the bootstrap command as many times as you want.
@@ -147,225 +148,152 @@ If you prefer GitLab, export `GITLAB_TOKEN` env var and use the command [flux bo
You can target a specific Flux [version](https://github.com/fluxcd/flux2/releases)
with `flux bootstrap --version=<semver>`.
## Staging workflow
## Clone the git repository
Clone the repository with:
We are going to drive app deployments in a GitOps manner,
using the Git repository as the desired state for our cluster.
Instead of applying the manifests directly to the cluster,
Flux will apply it for us instead.
Therefore, we need to clone the repository to our local machine:
```sh
git clone https://github.com/$GITHUB_USER/fleet-infra
cd fleet-infra
```
Create a git source pointing to a public repository master branch:
## Add podinfo repository to Flux
We will be using a public repository [github.com/stefanprodan/podinfo](https://github.com/stefanprodan/podinfo),
podinfo is a tiny web application made with Go.
Create a [GitRepository](../components/source/gitrepositories/)
manifest pointing to podinfo repository's master branch:
```sh
flux create source git webapp \
flux create source git podinfo \
--url=https://github.com/stefanprodan/podinfo \
--branch=master \
--interval=30s \
--export > ./staging-cluster/webapp-source.yaml
--export > ./clusters/my-cluster/podinfo-source.yaml
```
Create a kustomization for synchronizing the common manifests on the cluster:
The above command generates the following manifest:
```yaml
apiVersion: source.toolkit.fluxcd.io/v1beta1
kind: GitRepository
metadata:
name: podinfo
namespace: flux-system
spec:
interval: 30s
ref:
branch: master
url: https://github.com/stefanprodan/podinfo
```
Commit and push it to the `fleet-infra` repository:
```sh
flux create kustomization webapp-common \
--source=webapp \
--path="./deploy/webapp/common" \
git add -A && git commit -m "Add podinfo GitRepository"
git push
```
## Deploy podinfo application
We will create a Flux [Kustomization](../components/kustomize/kustomization/) manifest for podinfo.
This configures Flux to build and apply the [kustomize](https://github.com/stefanprodan/podinfo/tree/master/kustomize)
directory located in the podinfo repository.
```sh
flux create kustomization podinfo \
--source=podinfo \
--path="./kustomize" \
--prune=true \
--validation=client \
--interval=1h \
--export > ./staging-cluster/webapp-common.yaml
--interval=5m \
--export > ./clusters/my-cluster/podinfo-kustomization.yaml
```
Create a kustomization for the backend service that depends on common:
The above command generates the following manifest:
```yaml
apiVersion: kustomize.toolkit.fluxcd.io/v1beta1
kind: Kustomization
metadata:
name: podinfo
namespace: flux-system
spec:
interval: 5m0s
path: ./kustomize
prune: true
sourceRef:
kind: GitRepository
name: podinfo
validation: client
```
Commit and push the `Kustomization` manifest to the repository:
```sh
flux create kustomization webapp-backend \
--depends-on=webapp-common \
--source=webapp \
--path="./deploy/webapp/backend" \
--prune=true \
--validation=client \
--interval=10m \
--health-check="Deployment/backend.webapp" \
--health-check-timeout=2m \
--export > ./staging-cluster/webapp-backend.yaml
git add -A && git commit -m "Add podinfo Kustomization"
git push
```
Create a kustomization for the frontend service that depends on backend:
The structure of your repository should look like this:
```sh
flux create kustomization webapp-frontend \
--depends-on=webapp-backend \
--source=webapp \
--path="./deploy/webapp/frontend" \
--prune=true \
--validation=client \
--interval=10m \
--health-check="Deployment/frontend.webapp" \
--health-check-timeout=2m \
--export > ./staging-cluster/webapp-frontend.yaml
```
fleet-infra
└── clusters/
└── my-cluster/
├── flux-system/
│ ├── gotk-components.yaml
│ ├── gotk-sync.yaml
│ └── kustomization.yaml
├── podinfo-kustomization.yaml
└── podinfo-source.yaml
```
Push changes to origin:
```sh
git add -A && git commit -m "add staging webapp" && git push
```
## Watch Flux sync the application
In about 30s the synchronization should start:
```console
$ watch flux get kustomizations
NAME READY MESSAGE
flux-system True Applied revision: main/6eea299fe9997c8561b826b67950afaf9a476cf8
webapp-backend False dependency 'flux-system/webapp-common' is not ready
webapp-common True Applied revision: master/7411da595c25183daba255068814b83843fe3395
webapp-frontend False dependency 'flux-system/webapp-backend' is not ready
flux-system True Applied revision: main/fc07af652d3168be329539b30a4c3943a7d12dd8
podinfo True Applied revision: master/855f7724be13f6146f61a893851522837ad5b634
```
When the synchronization finishes you can check that the webapp services are running:
When the synchronization finishes you can check that podinfo has been deployed on your cluster:
```console
$ kubectl -n webapp get deployments,services
NAME READY UP-TO-DATE AVAILABLE AGE
deployment.apps/backend 1/1 1 1 4m1s
deployment.apps/frontend 1/1 1 1 3m31s
$ kubectl -n default get deployments,services
NAME READY UP-TO-DATE AVAILABLE AGE
deployment.apps/podinfo 2/2 2 2 108s
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
service/backend ClusterIP 10.52.10.22 <none> 9898/TCP,9999/TCP 4m1s
service/frontend ClusterIP 10.52.9.85 <none> 80/TCP 3m31s
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
service/podinfo ClusterIP 10.100.149.126 <none> 9898/TCP,9999/TCP 108s
```
!!! tip
From this moment forward, any changes made to the webapp
Kubernetes manifests in the master branch will be synchronised with the staging cluster.
From this moment forward, any changes made to the podinfo
Kubernetes manifests in the master branch will be synchronised with your cluster.
If a Kubernetes manifest is removed from the webapp repository, the reconciler will remove it from your cluster.
If you delete a kustomization from the `fleet-infra` repo, the reconciler will remove all Kubernetes objects that
were previously applied from that kustomization.
If a Kubernetes manifest is removed from the podinfo repository, Flux will remove it from your cluster.
If you delete a `Kustomization` from the fleet-infra repository, Flux will remove all Kubernetes objects that
were previously applied from that `Kustomization`.
If you alter the webapp deployment using `kubectl edit`, the changes will be reverted to match
the state described in git. When dealing with an incident, you can pause the reconciliation of a
If you alter the podinfo deployment using `kubectl edit`, the changes will be reverted to match
the state described in Git. When dealing with an incident, you can pause the reconciliation of a
kustomization with `flux suspend kustomization <name>`. Once the debugging session
is over, you can re-enable the reconciliation with `flux resume kustomization <name>`.
## Production bootstrap
## Multi-cluster Setup
On production clusters, you may wish to deploy stable releases of an application.
When creating a git source instead of a branch, you can specify a git tag or a semver expression.
To use Flux to manage more than one cluster or promote deployments from staging to production, take a look at the
two approaches in the repositories listed below.
Create the production cluster using Kubernetes kind or set the kubectl context to an existing cluster:
```sh
kind create cluster --name production
kubectl cluster-info --context kind-production
```
Run the bootstrap for the production environment:
```sh
flux bootstrap github \
--owner=$GITHUB_USER \
--repository=fleet-infra \
--path=prod-cluster \
--personal
```
Pull the changes locally:
```sh
git pull
```
## Production workflow
Create a git source using a semver range to target stable releases:
```sh
flux create source git webapp \
--url=https://github.com/stefanprodan/podinfo \
--tag-semver=">=4.0.0 <4.0.2" \
--interval=30s \
--export > ./prod-cluster/webapp-source.yaml
```
Create a kustomization for webapp pointing to the production overlay:
```sh
flux create kustomization webapp \
--source=webapp \
--path="./deploy/overlays/production" \
--prune=true \
--validation=client \
--interval=10m \
--health-check="Deployment/frontend.production" \
--health-check="Deployment/backend.production" \
--health-check-timeout=2m \
--export > ./prod-cluster/webapp-production.yaml
```
Push changes to origin:
```sh
git add -A && git commit -m "add prod webapp" && git push
```
List git sources:
```console
$ flux get sources git
NAME REVISION READY MESSAGE
flux-system main/5ae055e24b2c8a78f981708b61507a97a30bd7a6 True Fetched revision: main/113360052b3153e439a0cf8de76b8e3d2a7bdf27
webapp 4.0.1/113360052b3153e439a0cf8de76b8e3d2a7bdf27 True Fetched revision: 4.0.1/113360052b3153e439a0cf8de76b8e3d2a7bdf27
```
The kubectl equivalent is `kubectl -n flux-system get gitrepositories`.
List kustomization:
```console
$ flux get kustomizations
NAME REVISION SUSPENDED READY MESSAGE
flux-system main/5ae055e24b2c8a78f981708b61507a97a30bd7a6 False True Applied revision: main/5ae055e24b2c8a78f981708b61507a97a30bd7a6
webapp 4.0.1/113360052b3153e439a0cf8de76b8e3d2a7bdf27 False True Applied revision: 4.0.1/113360052b3153e439a0cf8de76b8e3d2a7bdf27
```
The kubectl equivalent is `kubectl -n flux-system get kustomizations`.
If you want to upgrade to the latest 4.x version, you can change the semver expression to:
```sh
flux create source git webapp \
--url=https://github.com/stefanprodan/podinfo \
--tag-semver=">=4.0.0 <5.0.0" \
--interval=30s \
--export > ./prod-cluster/webapp-source.yaml
git add -A && git commit -m "update prod webapp" && git push
```
Trigger a git sync:
```console
$ flux reconcile ks flux-system --with-source
► annotating source flux-system
✔ source annotated
◎ waiting for reconcilitation
✔ git reconciliation completed
✔ fetched revision main/d751ea264d48bf0db8b588d1d08184834ac8fec9
◎ waiting for kustomization reconcilitation
✔ kustomization reconcilitation completed
✔ applied revision main/d751ea264d48bf0db8b588d1d08184834ac8fec9
```
The kubectl equivalent is `kubectl -n flux-system annotate gitrepository/flux-system fluxcd.io/reconcileAt="$(date +%s)"`.
Wait for the webapp to be upgraded:
```console
$ watch flux get kustomizations
NAME REVISION SUSPENDED READY MESSAGE
flux-system main/d751ea264d48bf0db8b588d1d08184834ac8fec9 False True Applied revision: main/d751ea264d48bf0db8b588d1d08184834ac8fec9
webapp 4.0.6/26a630c0b4b3452833d96c511d93f6f2d2e90a99 False True Applied revision: 4.0.6/26a630c0b4b3452833d96c511d93f6f2d2e90a99
```
1. [https://github.com/fluxcd/flux2-kustomize-helm-example](https://github.com/fluxcd/flux2-kustomize-helm-example)
2. [https://github.com/fluxcd/flux2-multi-tenancy](https://github.com/fluxcd/flux2-multi-tenancy)