Mirrors/flux2
1
0
Fork 0
mirror of synced 2026-02-14 05:26:56 +00:00
Code Issues Packages Projects Releases Wiki Activity

Add customize Flux manifests section to install docs

Browse Source 
Signed-off-by: Stefan Prodan <stefan.prodan@gmail.com>
This commit is contained in:
Stefan Prodan
2020-11-07 13:19:42 +02:00
parent d5844bbdaa
commit 47a1743965
1 changed files with 98 additions and 42 deletions
Download Patch File Download Diff File Expand all files Collapse all files

140
docs/guides/installation.md
View File

@@ -44,12 +44,12 @@ Kubernetes cluster and configure it to manage itself from a Git
repository. repository.
The bootstrap creates a Git repository if one doesn't exist and The bootstrap creates a Git repository if one doesn't exist and
commits the Flux components manifests to the main branch. Then it commits the Flux components manifests to the main branch. Then it
configures the target cluster to synchronize with that repository by configures the target cluster to synchronize with that repository by
setting up SSH deploy keys. setting up SSH deploy keys.
If the Flux components are present on the cluster, the bootstrap If the Flux components are present on the cluster, the bootstrap
command will perform an upgrade if needed. The bootstrap is command will perform an upgrade if needed. The bootstrap is
idempotent, it's safe to run the command as many times as you want. 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: You can choose what components to install and for which cluster with:
@@ -57,7 +57,7 @@ You can choose what components to install and for which cluster with:
```sh ```sh
flux bootstrap <GIT-PROVIDER> \ flux bootstrap <GIT-PROVIDER> \
--components=source-controller,kustomize-controller,helm-controller,notification-controller \ --components=source-controller,kustomize-controller,helm-controller,notification-controller \
--path=my-cluster \ --path=clusters/my-cluster \
--version=latest --version=latest
``` ```
@@ -71,15 +71,16 @@ If you wish to install a specific version, use the Flux
With `--path` you can configure the directory which will be used to reconcile the target cluster. With `--path` you can configure the directory which will be used to reconcile the target cluster.
To control multiple clusters from the same Git repository, you have to set a unique path per To control multiple clusters from the same Git repository, you have to set a unique path per
cluster e.g. `staging-cluster` and `production-cluster`: cluster e.g. `clusters/staging` and `clusters/production`:
```sh ```sh
├── staging-cluster # <- path=staging-cluster ./clusters/
├── staging # <- path=clusters/staging
│   └── flux-system # <- namespace dir generated by bootstrap │   └── flux-system # <- namespace dir generated by bootstrap
│   ├── gotk-components.yaml │   ├── gotk-components.yaml
│   ├── gotk-sync.yaml │   ├── gotk-sync.yaml
│   └── kustomization.yaml │   └── kustomization.yaml
└── production-cluster # <- path=production-cluster └── production-cluster # <- path=clusters/production
└── flux-system └── flux-system
``` ```
@@ -87,6 +88,9 @@ cluster e.g. `staging-cluster` and `production-cluster`:
If you wish to change the branch to something else than main, create the repository manually, If you wish to change the branch to something else than main, create the repository manually,
push a branch to origin and then use `flux bootstrap <GIT-PROVIDER> --branch=your-branch`. push a branch to origin and then use `flux bootstrap <GIT-PROVIDER> --branch=your-branch`.
For examples on how you can structure your Git repository see:
* [flux2-kustomize-helm-example](https://github.com/fluxcd/flux2-kustomize-helm-example)
### GitHub and GitHub Enterprise ### GitHub and GitHub Enterprise
Generate a [personal access token](https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line) Generate a [personal access token](https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line)
@@ -104,7 +108,7 @@ Run the bootstrap for a repository on your personal GitHub account:
flux bootstrap github \ flux bootstrap github \
--owner=my-github-username \ --owner=my-github-username \
--repository=my-repository \ --repository=my-repository \
--path=my-cluster \ --path=clusters/my-cluster \
--personal --personal
``` ```
@@ -116,7 +120,7 @@ flux bootstrap github \
--repository=my-repository \ --repository=my-repository \
--team=team1-slug \ --team=team1-slug \
--team=team2-slug \ --team=team2-slug \
--path=my-cluster --path=clusters/my-cluster
``` ```
When you specify a list of teams, those teams will be granted maintainer access to the repository. When you specify a list of teams, those teams will be granted maintainer access to the repository.
@@ -129,7 +133,7 @@ flux bootstrap github \
--owner=my-github-organization \ --owner=my-github-organization \
--repository=my-repository \ --repository=my-repository \
--branch=main \ --branch=main \
--path=my-cluster --path=clusters/my-cluster
``` ```
### GitLab and GitLab Enterprise ### GitLab and GitLab Enterprise
@@ -150,7 +154,7 @@ flux bootstrap gitlab \
--owner=my-gitlab-username \ --owner=my-gitlab-username \
--repository=my-repository \ --repository=my-repository \
--branch=master \ --branch=master \
--path=my-cluster \ --path=clusters/my-cluster \
--personal --personal
``` ```
@@ -162,7 +166,7 @@ flux bootstrap gitlab \
--owner=my-gitlab-username \ --owner=my-gitlab-username \
--repository=my-repository \ --repository=my-repository \
--branch=master \ --branch=master \
--path=my-cluster --path=clusters/my-cluster
``` ```
!!! hint "Authentication" !!! hint "Authentication"
@@ -177,7 +181,7 @@ flux bootstrap gitlab \
--owner=my-gitlab-group \ --owner=my-gitlab-group \
--repository=my-repository \ --repository=my-repository \
--branch=master \ --branch=master \
--path=my-cluster --path=clusters/my-cluster
``` ```
To run the bootstrap for a repository hosted on GitLab on-prem or enterprise, you have to specify your GitLab hostname: To run the bootstrap for a repository hosted on GitLab on-prem or enterprise, you have to specify your GitLab hostname:
@@ -188,7 +192,7 @@ flux bootstrap gitlab \
--owner=my-gitlab-group \ --owner=my-gitlab-group \
--repository=my-repository \ --repository=my-repository \
--branch=master \ --branch=master \
--path=my-cluster --path=clusters/my-cluster
``` ```
### Generic Git Server ### Generic Git Server
@@ -205,7 +209,7 @@ cd my-repository
Create a directory inside the repository: Create a directory inside the repository:
```sh ```sh
mkdir -p ./my-cluster/flux-system mkdir -p ./clusters/my-cluster/flux-system
``` ```
Generate the Flux manifests with: Generate the Flux manifests with:
@@ -214,7 +218,7 @@ Generate the Flux manifests with:
# on ARM64/AARCH64 clusters use --arch=arm64 # on ARM64/AARCH64 clusters use --arch=arm64
flux install --version=latest \ flux install --version=latest \
--arch=amd64 \ --arch=amd64 \
--export > ./my-cluster/flux-system/gotk-components.yaml --export > ./clusters/my-cluster/flux-system/gotk-components.yaml
``` ```
If your cluster must pull images from a private container registry, first you should pull If your cluster must pull images from a private container registry, first you should pull
@@ -242,7 +246,7 @@ Set your registry domain, and the pull secret when generating the manifests:
flux install --version=latest \ flux install --version=latest \
--registry=registry.internal/fluxcd \ --registry=registry.internal/fluxcd \
--image-pull-secret=regcred \ --image-pull-secret=regcred \
--export > ./my-cluster/flux-system/gotk-components.yaml --export > ./clusters/my-cluster/flux-system/gotk-components.yaml
``` ```
Commit and push the manifest to the master branch: Commit and push the manifest to the master branch:
@@ -254,7 +258,7 @@ git add -A && git commit -m "add components" && git push
Apply the manifests on your cluster: Apply the manifests on your cluster:
```sh ```sh
kubectl apply -f ./my-cluster/flux-system/gotk-components.yaml kubectl apply -f ./clusters/my-cluster/flux-system/gotk-components.yaml
``` ```
Verify that the controllers have started: Verify that the controllers have started:
@@ -302,12 +306,12 @@ Export both objects, generate a `kustomization.yaml`, commit and push the manife
```sh ```sh
flux export source git flux-system \ flux export source git flux-system \
> ./my-cluster/flux-system/gotk-sync.yaml > ./clusters/my-cluster/flux-system/gotk-sync.yaml
flux export kustomization flux-system \ flux export kustomization flux-system \
>> ./my-cluster/flux-system/gotk-sync.yaml >> ./clusters/my-cluster/flux-system/gotk-sync.yaml
cd ./my-cluster/flux-system && kustomize create --autodetect cd ./clusters/my-cluster/flux-system && kustomize create --autodetect
git add -A && git commit -m "add sync manifests" && git push git add -A && git commit -m "add sync manifests" && git push
``` ```
@@ -316,7 +320,7 @@ To upgrade the Flux components to a newer version, run the install command and c
```sh ```sh
flux install --version=latest \ flux install --version=latest \
--export > ./my-cluster/flux-system/gotk-components.yaml --export > ./clusters/my-cluster/flux-system/gotk-components.yaml
git add -A && git commit -m "update flux" && git push git add -A && git commit -m "update flux" && git push
``` ```
@@ -324,15 +328,74 @@ git add -A && git commit -m "update flux" && git push
The source-controller will pull the changes on the cluster, then the kustomize-controller The source-controller will pull the changes on the cluster, then the kustomize-controller
will perform a rolling update of all Flux components including itself. will perform a rolling update of all Flux components including itself.
## Dev install ## Customize Flux manifests
For testing purposes you can install Flux without storing its manifests in a Git repository. You can customize the Flux components in the Git repository where you've run bootstrap with Kustomize patches.
Here is the equivalent to `fluxctl install`: First clone the repository locally and generate a `kustomization.yaml` file with:
```sh ```sh
flux install \ cd ./clusters/production && kustomize create --autodetect
--components=source-controller,kustomize-controller ```
Assuming you want to add custom annotations and labels to the Flux controllers in `clusters/production`.
Create a Kustomize patch and set the metadata for source-controller and kustomize-controller pods:
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: source-controller
namespace: flux-system
spec:
template:
metadata:
annotations:
custom: annotation
labels:
custom: label
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: kustomize-controller
namespace: flux-system
spec:
template:
metadata:
annotations:
custom: annotation
labels:
custom: label
```
Save the above file as `flux-system-patch.yaml` inside the `clusters/production` dir.
Edit `clusters/production/kustomization.yaml` and add the patch:
```yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
- flux-system
patchesStrategicMerge:
- flux-system-patch.yaml
```
Push the changes to main branch:
```sh
git add -A && git commit -m "add production metadata" && git push
```
Flux will detect the change and will update itself on the production cluster.
## Dev install
For testing purposes you can install Flux without storing its manifests in a Git repository:
```sh
flux install --arch=amd64
``` ```
Then you can register Git repositories and reconcile them on your cluster: Then you can register Git repositories and reconcile them on your cluster:
@@ -353,27 +416,20 @@ flux create kustomization podinfo-default \
--health-check-timeout=2m --health-check-timeout=2m
``` ```
Here is the equivalent to `helm install helm-operator`: You can register Helm repositories and create Helm releases:
```sh ```sh
flux install \ flux create source helm bitnami \
--components=source-controller,kustomize-controller,helm-controller
```
Then you can register Helm repositories and create Helm releases:
```sh
flux create source helm stable \
--interval=1h \ --interval=1h \
--url=https://charts.helm.sh/stable --url=https://charts.bitnami.com/bitnami
flux create helmrelease sealed-secrets \ flux create helmrelease nginx \
--interval=1h \ --interval=1h \
--release-name=sealed-secrets \ --release-name=nginx-ingress-controller \
--target-namespace=flux-system \ --target-namespace=kube-system \
--source=HelmRepository/stable \ --source=HelmRepository/bitnami \
--chart=sealed-secrets \ --chart=nginx-ingress-controller \
--chart-version="1.10.x" --chart-version="5.x.x"
``` ```
## Monitoring with Prometheus and Grafana ## Monitoring with Prometheus and Grafana