Merge pull request #433 from fluxcd/customize-flux-manifests

Add customize Flux manifests section to install docs
4 years ago · 1df45e4857
parent d5844bbdaa 47a1743965
commit 1df45e4857
1 changed files with 98 additions and 42 deletions
--- a/docs/guides/installation.md
+++ b/docs/guides/installation.md
@ -57,7 +57,7 @@ You can choose what components to install and for which cluster with:
 ```sh
 flux bootstrap <GIT-PROVIDER> \
  --components=source-controller,kustomize-controller,helm-controller,notification-controller \
-  --path=my-cluster \
+  --path=clusters/my-cluster \
  --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.
 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
-├── staging-cluster # <- path=staging-cluster
+./clusters/
+├── staging # <- path=clusters/staging
 │   └── flux-system # <- namespace dir generated by bootstrap
 │       ├── gotk-components.yaml
 │       ├── gotk-sync.yaml
 │       └── kustomization.yaml
-└── production-cluster # <- path=production-cluster
+└── production-cluster # <- path=clusters/production
    └── 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,
    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

 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 \
  --owner=my-github-username \
  --repository=my-repository \
-  --path=my-cluster \
+  --path=clusters/my-cluster \
  --personal
 ```

@ -116,7 +120,7 @@ flux bootstrap github \
  --repository=my-repository \
  --team=team1-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.
@ -129,7 +133,7 @@ flux bootstrap github \
  --owner=my-github-organization \
  --repository=my-repository \
  --branch=main \
-  --path=my-cluster
+  --path=clusters/my-cluster
 ```

 ### GitLab and GitLab Enterprise
@ -150,7 +154,7 @@ flux bootstrap gitlab \
  --owner=my-gitlab-username \
  --repository=my-repository \
  --branch=master \
-  --path=my-cluster \
+  --path=clusters/my-cluster \
  --personal
 ```

@ -162,7 +166,7 @@ flux bootstrap gitlab \
  --owner=my-gitlab-username \
  --repository=my-repository \
  --branch=master \
-  --path=my-cluster
+  --path=clusters/my-cluster
 ```

 !!! hint "Authentication"
@ -177,7 +181,7 @@ flux bootstrap gitlab \
  --owner=my-gitlab-group \
  --repository=my-repository \
  --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:
@ -188,7 +192,7 @@ flux bootstrap gitlab \
  --owner=my-gitlab-group \
  --repository=my-repository \
  --branch=master \
-  --path=my-cluster
+  --path=clusters/my-cluster
 ```

 ### Generic Git Server
@ -205,7 +209,7 @@ cd my-repository
 Create a directory inside the repository:

 ```sh
-mkdir -p ./my-cluster/flux-system
+mkdir -p ./clusters/my-cluster/flux-system
 ```

 Generate the Flux manifests with:
@ -214,7 +218,7 @@ Generate the Flux manifests with:
 # on ARM64/AARCH64 clusters use --arch=arm64
 flux install --version=latest \
  --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
@ -242,7 +246,7 @@ Set your registry domain, and the pull secret when generating the manifests:
 flux install --version=latest \
  --registry=registry.internal/fluxcd \
  --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:
@ -254,7 +258,7 @@ git add -A && git commit -m "add components" && git push
 Apply the manifests on your cluster:

 ```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:
@ -302,12 +306,12 @@ Export both objects, generate a `kustomization.yaml`, commit and push the manife

 ```sh
 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 \
-  >> ./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
 ```
@ -316,7 +320,7 @@ To upgrade the Flux components to a newer version, run the install command and c

 ```sh
 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
 ```
@ -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
 will perform a rolling update of all Flux components including itself.

-## Dev install
+## Customize Flux manifests
+
+You can customize the Flux components in the Git repository where you've run bootstrap with Kustomize patches.
+
+First clone the repository locally and generate a `kustomization.yaml` file with:
+
+```sh
+cd ./clusters/production && kustomize create --autodetect
+```
+
+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:

-For testing purposes you can install Flux without storing its manifests in a Git repository.
+```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.

-Here is the equivalent to `fluxctl install`:
+## Dev install
+
+For testing purposes you can install Flux without storing its manifests in a Git repository:

 ```sh
-flux install \
-  --components=source-controller,kustomize-controller
+flux install --arch=amd64
 ```

 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
 ```

-Here is the equivalent to `helm install helm-operator`:
-
-```sh
-flux install \
-  --components=source-controller,kustomize-controller,helm-controller
-```
-
-Then you can register Helm repositories and create Helm releases:
+You can register Helm repositories and create Helm releases:

 ```sh
-flux create source helm stable \
+flux create source helm bitnami \
  --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 \
-  --release-name=sealed-secrets \
-  --target-namespace=flux-system \
-  --source=HelmRepository/stable \
-  --chart=sealed-secrets \
-  --chart-version="1.10.x"
+  --release-name=nginx-ingress-controller \
+  --target-namespace=kube-system \
+  --source=HelmRepository/bitnami \
+  --chart=nginx-ingress-controller \
+  --chart-version="5.x.x"
 ```

 ## Monitoring with Prometheus and Grafana