diff --git a/content/en/flux/cheatsheets/bootstrap.md b/content/en/flux/cheatsheets/bootstrap.md deleted file mode 100644 index 68d79b37a..000000000 --- a/content/en/flux/cheatsheets/bootstrap.md +++ /dev/null @@ -1,670 +0,0 @@ ---- -title: "Bootstrap cheatsheet" -linkTitle: "Bootstrap" -description: "Showcase various configurations of Flux controllers at bootstrap time." -weight: 29 ---- - -## How to customize Flux - -To customize the Flux controllers during bootstrap, -first you'll need to create a Git repository and clone it locally. - -Create the file structure required by bootstrap with: - -```sh -mkdir -p clusters/my-cluster/flux-system -touch clusters/my-cluster/flux-system/gotk-components.yaml \ - clusters/my-cluster/flux-system/gotk-sync.yaml \ - clusters/my-cluster/flux-system/kustomization.yaml -``` - -The Flux controller deployments, container command arguments, node affinity, etc can be customized using -[Kustomize strategic merge patches and JSON patches](https://github.com/kubernetes-sigs/kustomize/blob/master/examples/patchMultipleObjects.md). - -You can make changes to all controllers using a single patch or -target a specific controller: - -```yaml -apiVersion: kustomize.config.k8s.io/v1beta1 -kind: Kustomization -resources: # manifests generated during bootstrap - - gotk-components.yaml - - gotk-sync.yaml -patches: - # target all controllers - - patch: | - # strategic merge or JSON patch - target: - kind: Deployment - labelSelector: "app.kubernetes.io/part-of=flux" - # target controllers by name - - patch: | - # strategic merge or JSON patch - target: - kind: Deployment - name: "(kustomize-controller|helm-controller)" - # add a command argument to a single controller - - patch: | - - op: add - path: /spec/template/spec/containers/0/args/- - value: --concurrent=5 - target: - kind: Deployment - name: "image-reflector-controller" -``` - -Push the changes to main branch: - -```sh -git add -A && git commit -m "init flux" && git push -``` - -And run the bootstrap for `clusters/my-cluster`: - -```sh -flux bootstrap git \ - --url=ssh://git@// \ - --branch=main \ - --path=clusters/my-cluster -``` - -To make further amendments, pull the changes locally, -edit the kustomization.yaml file, push the changes upstream -and rerun bootstrap. - -## Customization examples - -### Safe to evict - -Allow the cluster autoscaler to evict the Flux controller pods: - -```yaml -apiVersion: kustomize.config.k8s.io/v1beta1 -kind: Kustomization -resources: - - gotk-components.yaml - - gotk-sync.yaml -patches: - - patch: | - apiVersion: apps/v1 - kind: Deployment - metadata: - name: all - spec: - template: - metadata: - annotations: - cluster-autoscaler.kubernetes.io/safe-to-evict: "true" - target: - kind: Deployment - labelSelector: app.kubernetes.io/part-of=flux -``` - -### Node affinity and tolerations - -Pin the Flux controllers to specific nodes: - -```yaml -apiVersion: kustomize.config.k8s.io/v1beta1 -kind: Kustomization -resources: - - gotk-components.yaml - - gotk-sync.yaml -patches: - - patch: | - apiVersion: apps/v1 - kind: Deployment - metadata: - name: all - spec: - template: - spec: - affinity: - nodeAffinity: - requiredDuringSchedulingIgnoredDuringExecution: - nodeSelectorTerms: - - matchExpressions: - - key: role - operator: In - values: - - flux - tolerations: - - effect: NoSchedule - key: role - operator: Equal - value: flux - target: - kind: Deployment - labelSelector: app.kubernetes.io/part-of=flux -``` - -The above configuration pins Flux to nodes tainted and labeled with: - -```sh -kubectl taint nodes role=flux:NoSchedule -kubectl label nodes role=flux -``` - -### Increase the number of workers - -If Flux is managing hundreds of applications, you may want to increase the number of reconciliations -that can be performed in parallel and bump the resources limits: - -```yaml -apiVersion: kustomize.config.k8s.io/v1beta1 -kind: Kustomization -resources: - - gotk-components.yaml - - gotk-sync.yaml -patches: - - patch: | - - op: add - path: /spec/template/spec/containers/0/args/- - value: --concurrent=20 - - op: add - path: /spec/template/spec/containers/0/args/- - value: --kube-api-qps=500 - - op: add - path: /spec/template/spec/containers/0/args/- - value: --kube-api-burst=1000 - - op: add - path: /spec/template/spec/containers/0/args/- - value: --requeue-dependency=5s - target: - kind: Deployment - name: "(kustomize-controller|helm-controller|source-controller)" - - patch: | - apiVersion: apps/v1 - kind: Deployment - metadata: - name: all - spec: - template: - spec: - containers: - - name: manager - resources: - limits: - cpu: 2000m - memory: 2Gi - target: - kind: Deployment - name: "(kustomize-controller|helm-controller|source-controller)" -``` - -{{% alert color="info" title="Horizontal scaling" %}} -When vertical scaling is not an option, you can use sharding to horizontally scale -the Flux controllers. For more details please see the [sharding guide](sharding.md). -{{% /alert %}} - -### Persistent storage for Flux internal artifacts - -Flux maintains a local cache of artifacts acquired from external sources. -By default, the cache is stored in an `EmptyDir` volume, which means that after a restart, -Flux has to restore the local cache by fetching the content of all Git -repositories, Buckets, Helm charts and OCI artifacts. To avoid losing the cached artifacts, -you can configure source-controller with a persistent volume. - -Create a Kubernetes PVC definition named `gotk-pvc.yaml` and place it in your `flux-system` directory: - -```yaml -apiVersion: v1 -kind: PersistentVolumeClaim -metadata: - name: gotk-pvc - namespace: flux-system -spec: - accessModes: - - ReadWriteOnce - storageClassName: standard - resources: - requests: - storage: 2Gi -``` - -Add the PVC file to the `kustomization.yaml` resources and patch the source-controller volumes: - -```yaml -apiVersion: kustomize.config.k8s.io/v1beta1 -kind: Kustomization -resources: - - gotk-components.yaml - - gotk-sync.yaml - - gotk-pvc.yaml -patches: - - patch: | - - op: add - path: '/spec/template/spec/volumes/-' - value: - name: persistent-data - persistentVolumeClaim: - claimName: gotk-pvc - - op: replace - path: '/spec/template/spec/containers/0/volumeMounts/0' - value: - name: persistent-data - mountPath: /data - target: - kind: Deployment - name: source-controller -``` - -### Enable Helm repositories caching - -For large Helm repository index files, you can enable -caching to reduce the memory footprint of source-controller: - -```yaml -apiVersion: kustomize.config.k8s.io/v1beta1 -kind: Kustomization -resources: - - gotk-components.yaml - - gotk-sync.yaml -patches: - - patch: | - - op: add - path: /spec/template/spec/containers/0/args/- - value: --helm-cache-max-size=10 - - op: add - path: /spec/template/spec/containers/0/args/- - value: --helm-cache-ttl=60m - - op: add - path: /spec/template/spec/containers/0/args/- - value: --helm-cache-purge-interval=5m - target: - kind: Deployment - name: source-controller -``` - -When `helm-cache-max-size` is reached, an error is logged and the index is instead -read from file. Cache hits are exposed via the `gotk_cache_events_total` Prometheus -metrics. Use this data to fine-tune the configuration flags. - -### Enable Helm drift detection - -At present, Helm releases are not by default checked for drift compared to -cluster-state. To enable experimental drift detection, you must add the -`--feature-gates=DetectDrift=true` flag to the helm-controller Deployment. - -Enabling it will cause the controller to check for drift on all Helm releases -using a dry-run Server Side Apply, triggering an upgrade if a change is detected. -For detailed information about this feature, [refer to the -documentation](/flux/components/helm/helmreleases/#drift-detection). - -```yaml -apiVersion: kustomize.config.k8s.io/v1beta1 -kind: Kustomization -resources: - - gotk-components.yaml - - gotk-sync.yaml -patches: - - patch: | - # Enable drift detection feature - - op: add - path: /spec/template/spec/containers/0/args/- - value: --feature-gates=DetectDrift=true - # Enable debug logging for diff output (optional) - - op: replace - path: /spec/template/spec/containers/0/args/2 - value: --log-level=debug - target: - kind: Deployment - name: helm-controller -``` - -### Enable Helm near OOM detection - -When memory usage of the helm-controller exceeds the configured limit, the -controller will forcefully be killed by Kubernetes' OOM killer. This may result -in a Helm release being left in a `pending-*` state which causes the HelmRelease -to get stuck in an `another operation (install/upgrade/rollback) is in progress` -error loop. - -To prevent this from happening, the controller offers an OOM watcher which can -be enabled with `--feature-gates=OOMWatch=true`. When enabled, the memory usage -of the controller will be monitored, and a graceful shutdown will be triggered -when it reaches a certain threshold (default 95% utilization). - -When gracefully shutting down, running Helm actions may mark the release as -`failed`. Because of this, enabling this feature is best combined with -thoughtful [remediation strategies](/flux/components/helm/helmreleases/#configuring-failure-remediation). - -```yaml -apiVersion: kustomize.config.k8s.io/v1beta1 -kind: Kustomization -resources: - - gotk-components.yaml - - gotk-sync.yaml -patches: - - patch: | - # Enable OOM watch feature - - op: add - path: /spec/template/spec/containers/0/args/- - value: --feature-gates=OOMWatch=true - # Threshold at which to trigger a graceful shutdown (optional, default 95%) - - op: add - path: /spec/template/spec/containers/0/args/- - value: --oom-watch-memory-threshold=95 - # Interval at which to check memory usage (optional, default 500ms) - - op: add - path: /spec/template/spec/containers/0/args/- - value: --oom-watch-interval=500ms - target: - kind: Deployment - name: helm-controller -``` - -### Allow Helm DNS lookups - -By default, the helm-controller will not perform DNS lookups when rendering Helm -templates in clusters because of potential [security -implications](https://github.com/helm/helm/security/advisories/GHSA-pwcw-6f5g-gxf8). - -To enable DNS lookups, you must add the `--feature-gates=AllowDNSLookups=true` -flag to the helm-controller Deployment. - -```yaml -apiVersion: kustomize.config.k8s.io/v1beta1 -kind: Kustomization -resources: - - gotk-components.yaml - - gotk-sync.yaml -patches: - - patch: | - # Allow Helm DNS lookups - - op: add - path: /spec/template/spec/containers/0/args/- - value: --feature-gates=AllowDNSLookups=true - target: - kind: Deployment - name: helm-controller -``` - -### Using HTTP/S proxy for egress traffic - -If your cluster must use an HTTP proxy to reach GitHub or other external services, -you must set `NO_PROXY=.cluster.local.,.cluster.local,.svc` -to allow the Flux controllers to talk to each other: - -```yaml -apiVersion: kustomize.config.k8s.io/v1beta1 -kind: Kustomization -resources: - - gotk-components.yaml - - gotk-sync.yaml -patches: - - patch: | - apiVersion: apps/v1 - kind: Deployment - metadata: - name: all - spec: - template: - spec: - containers: - - name: manager - env: - - name: "HTTPS_PROXY" - value: "http://proxy.example.com:3129" - - name: "NO_PROXY" - value: ".cluster.local.,.cluster.local,.svc" - target: - kind: Deployment - labelSelector: app.kubernetes.io/part-of=flux -``` - -### Git repository access via SOCKS5 SSH proxy - -If your cluster has Internet restrictions, requiring egress traffic to go -through a proxy, you must use a SOCKS5 SSH proxy to be able to reach GitHub -(or other external Git servers) via SSH. - -To configure a SOCKS5 proxy set the environment variable `ALL_PROXY` to allow -both source-controller and image-automation-controller to connect through the -proxy. - -``` -ALL_PROXY=socks5://: -``` - -The following is an example of patching the Flux setup kustomization to add the -`ALL_PROXY` environment variable in source-controller and -image-automation-controller: - -```yaml -apiVersion: kustomize.config.k8s.io/v1beta1 -kind: Kustomization -resources: - - gotk-components.yaml - - gotk-sync.yaml -patches: - - patch: | - apiVersion: apps/v1 - kind: Deployment - metadata: - name: all - spec: - template: - spec: - containers: - - name: manager - env: - - name: "ALL_PROXY" - value: "socks5://proxy.example.com:1080" - target: - kind: Deployment - labelSelector: app.kubernetes.io/part-of=flux - name: "(source-controller|image-automation-controller)" -``` - -### Test release candidates - -To test release candidates, you can patch the container image tags: - -```yaml -apiVersion: kustomize.config.k8s.io/v1beta1 -kind: Kustomization -resources: - - gotk-components.yaml - - gotk-sync.yaml -images: - - name: ghcr.io/fluxcd/source-controller - newTag: rc-254ba51d - - name: ghcr.io/fluxcd/kustomize-controller - newTag: rc-ca0a9b8 -``` - -### OpenShift compatibility - -Allow Flux controllers to run as non-root: - -```shell -#!/usr/bin/env bash -set -e - -FLUX_NAMESPACE="flux-system" -FLUX_CONTROLLERS=( -"source-controller" -"kustomize-controller" -"helm-controller" -"notification-controller" -"image-reflector-controller" -"image-automation-controller" -) - -for i in ${!FLUX_CONTROLLERS[@]}; do - oc adm policy add-scc-to-user nonroot system:serviceaccount:${FLUX_NAMESPACE}:${FLUX_CONTROLLERS[$i]} -done -``` - -Set the user to nobody and delete the seccomp profile from the security context: - -```yaml -apiVersion: kustomize.config.k8s.io/v1beta1 -kind: Kustomization -resources: - - gotk-components.yaml - - gotk-sync.yaml -patches: - - patch: | - apiVersion: apps/v1 - kind: Deployment - metadata: - name: all - spec: - template: - spec: - containers: - - name: manager - securityContext: - runAsUser: 65534 - seccompProfile: - $patch: delete - target: - kind: Deployment - labelSelector: app.kubernetes.io/part-of=flux -``` - -### IAM Roles for Service Accounts - -To allow Flux access to an AWS service such as KMS or S3, after setting up IRSA, -you can annotate the controller service account with the role ARN: - -```yaml -apiVersion: kustomize.config.k8s.io/v1beta1 -kind: Kustomization -resources: - - gotk-components.yaml - - gotk-sync.yaml -patches: - - patch: | - apiVersion: v1 - kind: ServiceAccount - metadata: - name: kustomize-controller - annotations: - eks.amazonaws.com/role-arn: arn:aws:iam:::role/ - target: - kind: ServiceAccount - name: kustomize-controller - - patch: | - apiVersion: v1 - kind: ServiceAccount - metadata: - name: source-controller - annotations: - eks.amazonaws.com/role-arn: arn:aws:iam:::role/ - target: - kind: ServiceAccount - name: source-controller -``` - -### Multi-tenancy lockdown - -Lock down Flux on a multi-tenant cluster by disabling cross-namespace references and Kustomize remote bases, and -by setting a default service account: - -```yaml -apiVersion: kustomize.config.k8s.io/v1beta1 -kind: Kustomization -resources: - - gotk-components.yaml - - gotk-sync.yaml -patches: - - patch: | - - op: add - path: /spec/template/spec/containers/0/args/- - value: --no-cross-namespace-refs=true - target: - kind: Deployment - name: "(kustomize-controller|helm-controller|notification-controller|image-reflector-controller|image-automation-controller)" - - patch: | - - op: add - path: /spec/template/spec/containers/0/args/- - value: --no-remote-bases=true - target: - kind: Deployment - name: "kustomize-controller" - - patch: | - - op: add - path: /spec/template/spec/containers/0/args/- - value: --default-service-account=default - target: - kind: Deployment - name: "(kustomize-controller|helm-controller)" - - patch: | - - op: add - path: /spec/serviceAccountName - value: kustomize-controller - target: - kind: Kustomization - name: "flux-system" -``` - -### Disable Kubernetes cluster role aggregations - -By default, Flux [RBAC](/flux/security/#controller-permissions) grants Kubernetes builtin `view`, `edit` and `admin` roles -access to Flux custom resources. To disable the RBAC aggregation, you can remove the `flux-view` and `flux-edit` -cluster roles with: - -```yaml -apiVersion: kustomize.config.k8s.io/v1beta1 -kind: Kustomization -resources: - - gotk-components.yaml - - gotk-sync.yaml -patches: - - patch: | - apiVersion: rbac.authorization.k8s.io/v1 - kind: ClusterRole - metadata: - name: flux - $patch: delete - target: - kind: ClusterRole - name: "(flux-view|flux-edit)-flux-system" -``` - -### Enable notifications for third party controllers - -Enable notifications for 3rd party Flux controllers such as [tf-controller](https://github.com/weaveworks/tf-controller): - -```yaml -apiVersion: kustomize.config.k8s.io/v1beta1 -kind: Kustomization -resources: - - gotk-components.yaml - - gotk-sync.yaml -patches: - - patch: | - - op: add - path: /spec/versions/0/schema/openAPIV3Schema/properties/spec/properties/eventSources/items/properties/kind/enum/- - value: Terraform - - op: add - path: /spec/versions/1/schema/openAPIV3Schema/properties/spec/properties/eventSources/items/properties/kind/enum/- - value: Terraform - target: - kind: CustomResourceDefinition - name: alerts.notification.toolkit.fluxcd.io - - patch: | - - op: add - path: /spec/versions/0/schema/openAPIV3Schema/properties/spec/properties/resources/items/properties/kind/enum/- - value: Terraform - - op: add - path: /spec/versions/1/schema/openAPIV3Schema/properties/spec/properties/resources/items/properties/kind/enum/- - value: Terraform - target: - kind: CustomResourceDefinition - name: receivers.notification.toolkit.fluxcd.io - - patch: | - - op: add - path: /rules/- - value: - apiGroups: [ 'infra.contrib.fluxcd.io' ] - resources: [ '*' ] - verbs: [ '*' ] - target: - kind: ClusterRole - name: crd-controller-flux-system -``` diff --git a/content/en/flux/installation.md b/content/en/flux/installation.md deleted file mode 100644 index d016e28c0..000000000 --- a/content/en/flux/installation.md +++ /dev/null @@ -1,794 +0,0 @@ ---- -title: "Installation" -description: "Flux install, bootstrap, upgrade and uninstall documentation." -weight: 30 ---- - -This guide walks you through setting up Flux to -manage one or more Kubernetes clusters. - -## Prerequisites - -You will need a Kubernetes cluster that matches one of the following versions: - -| Kubernetes version | Minimum required | -|--------------------|------------------| -| `v1.24` | `>= 1.24.0` | -| `v1.25` | `>= 1.25.0` | -| `v1.26` | `>= 1.26.0` | -| `v1.27` and later | `>= 1.27.1` | - -{{% alert color="info" title="Kubernetes EOL" %}} -Note that Flux may work on older versions of Kubernetes e.g. 1.19, -but we don't recommend running [EOL versions](https://endoflife.date/kubernetes) -in production nor do we offer support for these versions. -{{% /alert %}} - -## Install the Flux CLI - -The Flux CLI is available as a binary executable for all major platforms, -the binaries can be downloaded from GitHub -[releases page](https://github.com/fluxcd/flux2/releases). - -{{< tabpane text=true >}} -{{% tab header="Homebrew" %}} - -With [Homebrew](https://brew.sh) for macOS and Linux: - -```sh -brew install fluxcd/tap/flux -``` - -{{% /tab %}} -{{% tab header="bash" %}} - -With [Bash](https://www.gnu.org/software/bash/) for macOS and Linux: - -```sh -curl -s https://fluxcd.io/install.sh | sudo bash -``` - -{{% /tab %}} -{{% tab header="yay" %}} - -With [yay](https://github.com/Jguer/yay) (or another [AUR helper](https://wiki.archlinux.org/title/AUR_helpers)) for Arch Linux: - -```sh -yay -S flux-bin -``` - -{{% /tab %}} -{{% tab header="nix" %}} - -With [nix-env](https://nixos.org/manual/nix/unstable/command-ref/nix-env.html) for NixOS: - -```sh -nix-env -i fluxcd -``` - -{{% /tab %}} -{{% tab header="Chocolatey" %}} - -With [Chocolatey](https://chocolatey.org/) for Windows: - -```powershell -choco install flux -``` - -{{% /tab %}} -{{< /tabpane >}} - -To configure your shell to load `flux` [bash completions](./cmd/flux_completion_bash.md) add to your profile: - -```sh -. <(flux completion bash) -``` - -[`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. - -A container image with `kubectl` and `flux` is available on DockerHub and GitHub: - -* `docker.io/fluxcd/flux-cli:` -* `ghcr.io/fluxcd/flux-cli:` - -## Bootstrap - -Using the `flux bootstrap` command you can install Flux on a -Kubernetes cluster and configure it to manage itself from a Git -repository. - -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. - -The Flux component images are published to DockerHub and GitHub Container Registry -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. - -If your Git provider is **AWS CodeCommit**, **Azure DevOps**, **Bitbucket Server**, **GitHub** or **GitLab** please -follow the specific bootstrap procedure: - -* [AWS CodeCommit](./use-cases/aws-codecommit.md#flux-installation-for-aws-codecommit) -* [Azure DevOps](./use-cases/azure.md#flux-installation-for-azure-devops) -* [Bitbucket Server and Data Center](#bitbucket-server-and-data-center) -* [GitHub.com and GitHub Enterprise](#github-and-github-enterprise) -* [GitLab.com and GitLab Enterprise](#gitlab-and-gitlab-enterprise) - -### Generic Git Server - -The `bootstrap git` command takes an existing Git repository, clones it and -commits the Flux components manifests to the specified branch. Then it -configures the target cluster to synchronize with that repository. - -{{% alert color="warning" %}} -:warning: Note that if set, your SSH hostname and port could be overwritten by your [ssh_config](https://linux.die.net/man/5/ssh_config). -{{% /alert %}} - -Run bootstrap for a Git repository and authenticate with your SSH agent: - -```sh -flux bootstrap git \ - --url=ssh://git@// \ - --branch= \ - --path=clusters/my-cluster -``` - -The above command will generate an SSH key (defaults to ECDSA P-384 but can be changed with `--ssh-key-algorithm` and -`--ssh-ecdsa-curve`), and it will prompt you to add the SSH public key as a deploy key to your repository. - -If you want to use your own SSH key, you can provide a private key using -`--private-key-file=` (you can supply the passphrase with `--password=`). -This option can also be used if no SSH agent is available on your machine. - -{{% alert color="info" title="Bootstrap options" %}} -There are many options available when bootstrapping Flux, such as installing a subset of Flux components, -setting the Kubernetes context, changing the Git author name and email, enabling Git submodules, and more. -To list all the available options run `flux bootstrap git --help`. -{{% /alert %}} - -If your Git server doesn't support SSH, you can run bootstrap for Git over HTTPS: - -```sh -flux bootstrap git \ - --url=https://// \ - --username= \ - --password= \ - --token-auth=true \ - --path=clusters/my-cluster -``` - -If your Git server uses a self-signed TLS certificate, you can specify the CA file with -`--ca-file=`. - -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. `clusters/staging` and `clusters/production`: - -```sh -./clusters/ -├── staging # <- path=clusters/staging -│   └── flux-system # <- namespace dir generated by bootstrap -│   ├── gotk-components.yaml -│   ├── gotk-sync.yaml -│   └── kustomization.yaml -└── production # <- path=clusters/production - └── flux-system -``` - -After running bootstrap you can place Kubernetes YAMLs inside a dir under path -e.g. `clusters/staging/my-app`, and Flux will reconcile them on your cluster. - -For examples on how you can structure your Git repository see: - -* [flux2-kustomize-helm-example](https://github.com/fluxcd/flux2-kustomize-helm-example) -* [flux2-multi-tenancy](https://github.com/fluxcd/flux2-multi-tenancy) - -### GitHub and GitHub Enterprise - -The `bootstrap github` command creates a GitHub repository if one doesn't exist and -commits the Flux components manifests to specified branch. Then it -configures the target cluster to synchronize with that repository by -setting up an SSH deploy key or by using token-based authentication. - -Generate a [personal access token](https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line) -(PAT) that can create repositories by checking all permissions under `repo`. If -a pre-existing repository is to be used the PAT's user will require `admin` -[permissions](https://docs.github.com/en/organizations/managing-access-to-your-organizations-repositories/repository-roles-for-an-organization#permissions-for-each-role) -on the repository in order to create a deploy key. - -Export your GitHub personal access token as an environment variable: - -```sh -export GITHUB_TOKEN= -``` - -Run the bootstrap for a repository on your personal GitHub account: - -```sh -flux bootstrap github \ - --owner=my-github-username \ - --repository=my-repository \ - --path=clusters/my-cluster \ - --personal -``` - -{{% alert color="info" title="Deploy key" %}} -The bootstrap command creates an SSH key which it stores as a secret in the -Kubernetes cluster. The key is also used to create a deploy key in the GitHub -repository. The new deploy key will be linked to the personal access token used -to authenticate. **Removing the personal access token will also remove the deploy key.** -{{% /alert %}} - -Run the bootstrap for a repository owned by a GitHub organization: - -```sh -flux bootstrap github \ - --owner=my-github-organization \ - --repository=my-repository \ - --team=team1-slug \ - --team=team2-slug \ - --path=clusters/my-cluster -``` - -When you specify a list of teams, those teams will be granted maintainer access to the repository. - -To run the bootstrap for a repository hosted on GitHub Enterprise, you have to specify your GitHub hostname: - -```sh -flux bootstrap github \ - --hostname=my-github-enterprise.com \ - --ssh-hostname=my-github-enterprise.com \ - --owner=my-github-organization \ - --repository=my-repository \ - --branch=main \ - --path=clusters/my-cluster -``` - -If your GitHub Enterprise has SSH access disabled, you can use HTTPS and token authentication with: - -```sh -flux bootstrap github \ - --token-auth \ - --hostname=my-github-enterprise.com \ - --owner=my-github-organization \ - --repository=my-repository \ - --branch=main \ - --path=clusters/my-cluster -``` - -### GitLab and GitLab Enterprise - -The `bootstrap gitlab` command creates a GitLab repository if one doesn't exist and -commits the Flux components manifests to specified branch. Then it -configures the target cluster to synchronize with that repository by -setting up an SSH deploy key or by using token-based authentication. - -Generate a [personal access token](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html) -that grants complete read/write access to the GitLab API. - -Export your GitLab personal access token as an environment variable: - -```sh -export GITLAB_TOKEN= -``` - -Run the bootstrap for a repository on your personal GitLab account: - -```sh -flux bootstrap gitlab \ - --owner=my-gitlab-username \ - --repository=my-repository \ - --branch=master \ - --path=clusters/my-cluster \ - --token-auth \ - --personal -``` - -To use a [GitLab deploy token](https://docs.gitlab.com/ee/user/project/deploy_tokens/) instead of your personal access token -or an SSH deploy key, you can specify the `--deploy-token-auth` option: - -```sh -flux bootstrap gitlab \ - --owner=my-gitlab-username \ - --repository=my-repository \ - --branch=master \ - --path=clusters/my-cluster \ - --deploy-token-auth -``` - -To run the bootstrap for a repository using deploy keys for authentication, you have to specify the SSH hostname: - -```sh -flux bootstrap gitlab \ - --ssh-hostname=gitlab.com \ - --owner=my-gitlab-username \ - --repository=my-repository \ - --branch=master \ - --path=clusters/my-cluster -``` - -{{% alert color="info" title="Authentication" %}} -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. -{{% /alert %}} - -Run the bootstrap for a repository owned by a GitLab (sub)group: - -```sh -flux bootstrap gitlab \ - --owner=my-gitlab-group/my-gitlab-subgroup \ - --repository=my-repository \ - --branch=master \ - --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: - -```sh -flux bootstrap gitlab \ - --hostname=my-gitlab.com \ - --token-auth \ - --owner=my-gitlab-group \ - --repository=my-repository \ - --branch=master \ - --path=clusters/my-cluster -``` - -### Bitbucket Server and Data Center - -The `bootstrap bitbucket-server` command creates a Bitbucket Server repository if one doesn't exist and -commits the Flux components manifests to the specified branch. Then it -configures the target cluster to synchronize with that repository by -setting up an SSH deploy key or by using token-based authentication. - -{{% alert color="info" title="Bitbucket versions" %}} -This bootstrap command works with Bitbucket Server and Data Center only because it targets the [1.0](https://developer.atlassian.com/server/bitbucket/reference/rest-api/) REST API. Bitbucket Cloud has migrated to the [2.0](https://developer.atlassian.com/cloud/bitbucket/rest/intro/) REST API. -{{% /alert %}} - -Generate a [personal access token](https://confluence.atlassian.com/bitbucketserver/http-access-tokens-939515499.html) -that grant read/write access to the repository. - -Export your Bitbucket personal access token as an environment variable: - -```sh -export BITBUCKET_TOKEN= -``` - -Run the bootstrap for a repository on your personal Bitbucket Server account: - -```sh -flux bootstrap bitbucket-server \ - --owner=my-bitbucket-username \ - --repository=my-repository \ - --branch=main \ - --path=clusters/my-cluster \ - --hostname=my-bitbucket-server.com \ - --personal -``` - -Run the bootstrap for a repository owned by a Bitbucket Server project: - -```sh -flux bootstrap bitbucket-server \ - --owner=my-bitbucket-project \ - --username=my-bitbucket-username \ - --repository=my-repository \ - --path=clusters/my-cluster \ - --hostname=my-bitbucket-server.com \ - --group=group-name -``` - -When you specify a list of groups, those teams will be granted write access to the repository. - -**Note:** The `username` is mandatory for `project` owned repositories. The specified user must own the `BITBUCKET_TOKEN` and have sufficient rights on the target `project` to create repositories. - -To run the bootstrap for a repository with a different SSH hostname (e.g. with a different port): - -```sh -flux bootstrap bitbucket-server \ - --hostname=my-bitbucket-server.com \ - --ssh-hostname=my-bitbucket-server.com:7999 \ - --owner=my-bitbucket-project \ - --username=my-bitbucket-username \ - --repository=my-repository \ - --branch=main \ - --path=clusters/my-cluster -``` - -If your Bitbucket Server has SSH access disabled, you can use HTTPS and token authentication with: - -```sh -flux bootstrap bitbucket-server \ - --token-auth \ - --hostname=my-bitbucket-server.com \ - --owner=my-bitbucket-project \ - --username=my-bitbucket-username \ - --repository=my-repository \ - --branch=main \ - --path=clusters/my-cluster -``` - -### Air-gapped Environments - -To bootstrap Flux on air-gapped environments without access to github.com and ghcr.io, first you'll need -to download the `flux` binary, and the container images from a computer with access to internet. - -List all container images: - -```sh -$ flux install --export | grep ghcr.io - -image: ghcr.io/fluxcd/helm-controller:v2.0.0-rc.4 -image: ghcr.io/fluxcd/kustomize-controller:v2.0.0-rc.4 -image: ghcr.io/fluxcd/notification-controller:v2.0.0-rc.4 -image: ghcr.io/fluxcd/source-controller:v2.0.0-rc.4 -``` - -Pull the images locally and push them to your container registry: - -```sh -docker pull ghcr.io/fluxcd/source-controller:v2.0.0-rc.4 -docker tag ghcr.io/fluxcd/source-controller:v2.0.0-rc.4 registry.internal/fluxcd/source-controller:v2.0.0-rc.4 -docker push registry.internal/fluxcd/source-controller:v2.0.0-rc.4 -``` - -Copy `flux` binary to a computer with access to your air-gapped cluster, -and create the pull secret in the `flux-system` namespace: - -```sh -kubectl create ns flux-system - -kubectl -n flux-system create secret generic regcred \ - --from-file=.dockerconfigjson=/.docker/config.json \ - --type=kubernetes.io/dockerconfigjson -``` - -Finally, bootstrap Flux using the images from your private registry: - -```sh -flux bootstrap \ - --registry=registry.internal/fluxcd \ - --image-pull-secret=regcred \ - --hostname=my-git-server.internal -``` - -Note that when running `flux bootstrap` without specifying a `--version`, -the CLI will use the manifests embedded in its binary instead of downloading -them from GitHub. You can determine which version you'll be installing, -with `flux --version`. - -## Bootstrap with Terraform - -The bootstrap procedure can be implemented with Terraform using the Flux provider published on -[registry.terraform.io](https://registry.terraform.io/providers/fluxcd/flux). -The provider offers a Terraform resource called -[flux_bootstrap_git](https://registry.terraform.io/providers/fluxcd/flux/latest/docs/resources/bootstrap_git) -that can be used to bootstrap Flux in the same way the Flux CLI does it. - -Example of Git HTTPS bootstrap: - -```hcl -provider "flux" { - kubernetes = { - config_path = "~/.kube/config" - } - git = { - url = var.gitlab_url - http = { - username = var.gitlab_user - password = var.gitlab_token - } - } -} - -resource "flux_bootstrap_git" "this" { - path = "clusters/my-cluster" - network_policy = true - kustomization_override = file("${path.module}/kustomization.yaml") -} -``` - -For more details on how to use the Terraform provider -please see the [Flux docs on registry.terraform.io](https://registry.terraform.io/providers/fluxcd/flux/latest/docs). - -## Customize Flux manifests - -You can customize the Flux components before or after running bootstrap. - -Assuming you want to customise the Flux controllers before they get deployed on the cluster, -first you'll need to create a Git repository and clone it locally. - -Create the file structure required by bootstrap with: - -```sh -mkdir -p clusters/my-cluster/flux-system -touch clusters/my-cluster/flux-system/gotk-components.yaml \ - clusters/my-cluster/flux-system/gotk-sync.yaml \ - clusters/my-cluster/flux-system/kustomization.yaml -``` - -Add patches to `kustomization.yaml`: - -```yaml -apiVersion: kustomize.config.k8s.io/v1 -kind: Kustomization -resources: # manifests generated during bootstrap - - gotk-components.yaml - - gotk-sync.yaml - -patches: # customize the manifests during bootstrap - - target: - kind: Deployment - labelSelector: app.kubernetes.io/part-of=flux - patch: | - # strategic merge or JSON patch -``` - -Push the changes to main branch: - -```sh -git add -A && git commit -m "init flux" && git push -``` - -And run the bootstrap for `clusters/my-cluster`: - -```sh -flux bootstrap git \ - --url=ssh://git@// \ - --branch=main \ - --path=clusters/my-cluster -``` - -To make further amendments, pull the changes locally, -edit the `kustomization.yaml` file, push the changes upstream -and rerun bootstrap or let Flux upgrade itself. - -Checkout the [bootstrap cheatsheet](cheatsheets/bootstrap.md) for various examples of how to customize Flux. - -### Multi-tenancy lockdown - -Assuming you want to lock down Flux on multi-tenant clusters, -add the following patches to `clusters/my-cluster/flux-system/kustomization.yaml`: - -```yaml -apiVersion: kustomize.config.k8s.io/v1 -kind: Kustomization -resources: - - gotk-components.yaml - - gotk-sync.yaml -patches: - - patch: | - - op: add - path: /spec/template/spec/containers/0/args/0 - value: --no-cross-namespace-refs=true - target: - kind: Deployment - name: "(kustomize-controller|helm-controller|notification-controller|image-reflector-controller|image-automation-controller)" - - patch: | - - op: add - path: /spec/template/spec/containers/0/args/- - value: --no-remote-bases=true - target: - kind: Deployment - name: "kustomize-controller" - - patch: | - - op: add - path: /spec/template/spec/containers/0/args/0 - value: --default-service-account=default - target: - kind: Deployment - name: "(kustomize-controller|helm-controller)" - - patch: | - - op: add - path: /spec/serviceAccountName - value: kustomize-controller - target: - kind: Kustomization - name: "flux-system" -``` - -With the above configuration, Flux will: - -- Deny cross-namespace access to Flux custom resources, thus ensuring that a tenant can't use another tenant's sources or subscribe to their events. -- Deny accesses to Kustomize remote bases, thus ensuring all resources refer to local files, meaning only the Flux Sources can affect the cluster-state. -- All `Kustomizations` and `HelmReleases` which don't have `spec.serviceAccountName` specified, will use the `default` account from the tenant's namespace. - Tenants have to specify a service account in their Flux resources to be able to deploy workloads in their namespaces as the `default` account has no permissions. -- The flux-system `Kustomization` is set to reconcile under a service account with cluster-admin role, - allowing platform admins to configure cluster-wide resources and provision the tenant's namespaces, service accounts and RBAC. - -To apply these patches, push the changes to the main branch and run `flux bootstrap`. - -## Dev install - -For testing purposes you can install Flux without storing its manifests in a Git repository: - -```sh -flux install -``` - -Or using kubectl: - -```sh -kubectl apply -f https://github.com/fluxcd/flux2/releases/latest/download/install.yaml -``` - -Then you can register Git repositories and reconcile them on your cluster: - -```sh -flux create source git podinfo \ - --url=https://github.com/stefanprodan/podinfo \ - --tag-semver=">=4.0.0" \ - --interval=1m - -flux create kustomization podinfo-default \ - --source=podinfo \ - --path="./kustomize" \ - --prune=true \ - --validation=client \ - --interval=10m \ - --health-check="Deployment/podinfo.default" \ - --health-check-timeout=2m \ - --target-namespace=default -``` - -You can register Helm repositories and create Helm releases: - -```sh -flux create source helm bitnami \ - --interval=1h \ - --url=https://charts.bitnami.com/bitnami - -flux create helmrelease nginx \ - --interval=1h \ - --release-name=nginx-ingress-controller \ - --target-namespace=kube-system \ - --source=HelmRepository/bitnami \ - --chart=nginx-ingress-controller \ - --chart-version="5.x.x" -``` - -## Deploy key rotation - -There are several reasons you may want to rotate the deploy key: - -- The token used to generate the key has expired. -- The key has been compromised. -- You want to change the scope of the key, e.g. to allow write access using the `--read-write-key` flag to `flux bootstrap`. - -While you can run `flux bootstrap` repeatedly, be aware that the `flux-system` Kubernetes Secret is never overwritten. -You need to manually rotate the key as described here. - -To rotate the SSH key generated at bootstrap, first delete the secret from the cluster with: - -```sh -kubectl -n flux-system delete secret flux-system -``` - -Then you have two alternatives to generate a new key: - -1. Generate a new secret with - - ```sh - flux create secret git flux-system \ - --url=ssh://git@// - ``` - The above command will print the SSH public key, once you set it as the deploy key, - Flux will resume all operations. -2. Run `flux bootstrap ...` again. This will generate a new key pair and, - depending on which Git provider you use, print the SSH public key that you then - set as deploy key or automatically set the deploy key (e.g. with GitHub). - -## Upgrade - -{{% alert color="info" title="Patch versions" %}} -It is safe and advised to use the latest PATCH version when upgrading to a -new MINOR version. -{{% /alert %}} - -Update Flux CLI to the latest release with `brew upgrade fluxcd/tap/flux` or by -downloading the binary from [GitHub](https://github.com/fluxcd/flux2/releases). - -Verify that you are running the latest version with: - -```sh -flux --version -``` - -### Bootstrap upgrade - -If you've used the [bootstrap](#bootstrap) procedure to deploy Flux, -then rerun the bootstrap command for each cluster using the same arguments as before: - -```sh -flux bootstrap github \ - --owner=my-github-username \ - --repository=my-repository \ - --branch=main \ - --path=clusters/my-cluster \ - --personal -``` - -The above command will clone the repository, it will update the components manifest in -`/flux-system/gotk-components.yaml` and it will push the changes to the remote branch. - -Tell Flux to pull the manifests from Git and upgrade itself with: - -```sh -flux reconcile source git flux-system -``` - -Verify that the controllers have been upgrade with: - -```sh -flux check -``` - -{{% alert color="info" title="Automated upgrades" %}} -You can automate the components manifest update with GitHub Actions -and open a PR when there is a new Flux version available. -For more details please see [Flux GitHub Action docs](/flux/flux-gh-action.md). -{{% /alert %}} - -### Terraform upgrade - -Update the Flux provider to the [latest release](https://github.com/fluxcd/terraform-provider-flux/releases) -and run `terraform apply`. - -Tell Flux to upgrade itself in-cluster or wait for it to pull the latest commit from Git: - -```sh -kubectl annotate --overwrite gitrepository/flux-system reconcile.fluxcd.io/requestedAt="$(date +%s)" -``` - -### In-cluster upgrade - -If you've installed Flux directly on the cluster, then rerun the install command: - -```sh -flux install -``` - -The above command will apply the new manifests on your cluster. -You can verify that the controllers have been upgraded to the latest version with `flux check`. - -If you've installed Flux directly on the cluster with kubectl, -then rerun the command using the latest manifests from the `main` branch: - -```sh -kustomize build https://github.com/fluxcd/flux2/manifests/install?ref=main | kubectl apply -f- -``` - -## Uninstall - -You can uninstall Flux with: - -```sh -flux uninstall --namespace=flux-system -``` - -The above command performs the following operations: - -- deletes Flux components (deployments and services) -- deletes Flux network policies -- deletes Flux RBAC (service accounts, cluster roles and cluster role bindings) -- removes the Kubernetes finalizers from Flux custom resources -- deletes Flux custom resource definitions and custom resources -- deletes the namespace where Flux was installed - -If you've installed Flux in a namespace that you wish to preserve, you -can skip the namespace deletion with: - -```sh -flux uninstall --namespace=infra --keep-namespace -``` - -{{% alert color="info" title="Reinstall" %}} -Note that the `uninstall` command will not remove any Kubernetes objects -or Helm releases that were reconciled on the cluster by Flux. -It is safe to uninstall Flux and rerun the bootstrap, any existing workloads -will not be affected. -{{% /alert %}} diff --git a/content/en/flux/use-cases/aws-codecommit.md b/content/en/flux/use-cases/aws-codecommit.md deleted file mode 100644 index de23423c3..000000000 --- a/content/en/flux/use-cases/aws-codecommit.md +++ /dev/null @@ -1,115 +0,0 @@ ---- -title: Using Flux on AWS With CodeCommit -linkTitle: AWS CodeCommit -description: "How to bootstrap Flux on AWS EKS with CodeCommit Git repositories." -weight: 10 ---- - -## EKS Cluster Options - -### VPC CodeCommit Access - -If your VPC is setup without internet access or you would prefer that the access was over a private connection, you -will need to set up a VPC endpoint to have access to CodeCommit. You can do this by following the guide [Using AWS -CodeCommit with interface VPC endpoints](https://docs.aws.amazon.com/codecommit/latest/userguide/codecommit-and-interface-VPC.html). - -### Cluster Creation - -The following creates an EKS cluster with some minimal configuration that will work well with Flux: - -```sh -eksctl create cluster -``` - -For more details on how to create an EKS cluster with `eksctl` please see [eksctl.io](https://eksctl.io). - -## Flux Installation for AWS CodeCommit - -You can install Flux using a AWS CodeCommit repository using the [`flux bootstrap git`](../installation.md#bootstrap) -command. -Ensure you can login to console.aws.amazon.com for your proper organization, and create a new repository to hold your Flux -install and other Kubernetes resources. - -To bootstrap using HTTPS, run the following command: -```sh -flux bootstrap git \ - --url=https://git-codecommit..amazonaws.com/v1/repos/ \ - --branch=main \ - --username= \ - --password= \ - --token-auth=true -``` - -To bootstrap using SSH, you first need to generate a SSH keypair to be used as a deploy key. -AWS CodeCommit does not support repository or org-specific SSH/deploy keys. You may add the deploy -key to a user's personal SSH keys, but take note that revoking the user's access to the repository -will also revoke Flux's access. The better alternative is to create a machine-user whose sole -purpose is to store credentials for automation. Using a machine-user also has the benefit of being -able to be read-only or restricted to specific repositories if this is needed. -```sh -aws iam upload-ssh-public-key --user-name codecommit-user --ssh-public-key-body file://sshkey.pub -``` - -The output shall contain a field `SSHPublicKeyID`, which acts as the SSH username. -```json -{ - "SSHPublicKey": { - "UserName": "codecommit-user", - "SSHPublicKeyId": "", - "Fingerprint": "", - "SSHPublicKeyBody": "", - "Status": "Active", - "UploadDate": "2022-11-14T15:15:12+00:00" - } -} -``` - -Now we can run the bootstrap command: -```sh -flux bootstrap git \ - --url=ssh://@git-codecommit..amazonaws.com/v1/repos/ - --branch=main - --private-key-file= - --password= - --silent -``` - -{{% alert color="info" %}} -Unlike other Git providers, in the case of AWS CodeCommit, you can not use HTTPS for bootstraping -and SSH for driving the reconciliation forward, i.e. you can not provide a HTTPS url without -passing `--token-auth=true` as well. -{{% /alert %}} - -{{% alert color="info" %}} -Unlike `git`, Flux does not support the ["shorter" scp-like syntax for the SSH -protocol](https://git-scm.com/book/en/v2/Git-on-the-Server-The-Protocols#_the_ssh_protocol) -(e.g. `git-codecommit..amazonaws.com:v1`). -Use the [RFC 3986 compatible syntax](https://tools.ietf.org/html/rfc3986#section-3) instead: `git-codecommit..amazonaws.com/v1`. -{{% /alert %}} - -## Secrets Management with SOPS and AWS KMS - -You will need to use AWS KMS and enable the IAM OIDC provider on the cluster. - -Patch kustomize-controller with the proper IAM credentials, so that it may access your AWS KMS, and then begin -committing SOPS encrypted files to the Git repository with the proper AWS KMS configuration. - -See the [Mozilla SOPS AWS Guide](../guides/mozilla-sops.md#aws) for further detail. - -## Image Updates with Elastic Container Registry - -You will need to create an ECR registry and setup an IAM Role with the [required -permissions](https://docs.aws.amazon.com/AmazonECR/latest/userguide/ECR_on_EKS.html). - -{{% alert color="info" %}} -If you used `eksctl` or the AWS CloudFormation templates in [Getting Started with Amazon -EKS](https://docs.aws.amazon.com/eks/latest/userguide/getting-started.html) to create your cluster and worker -node groups, these IAM permissions are applied to your worker node IAM Role by default. -{{% /alert %}} - -Follow the [Image Update Automation Guide](../guides/image-update.md) and see the -[ECR specific section](../guides/image-update.md#aws-elastic-container-registry) for more details. - -Your EKS cluster's configuration can also be updated to -[allow the kubelets to pull images from ECR](https://docs.aws.amazon.com/AmazonECR/latest/userguide/ECR_on_EKS.html) -without ImagePullSecrets as an optional, complimentary step. diff --git a/content/en/flux/use-cases/azure.md b/content/en/flux/use-cases/azure.md deleted file mode 100644 index 37410ff25..000000000 --- a/content/en/flux/use-cases/azure.md +++ /dev/null @@ -1,241 +0,0 @@ ---- -title: Using Flux on Azure -linkTitle: Azure -description: "How to bootstrap Flux on Azure AKS with DevOps Git repositories." -weight: 10 ---- - -## AKS Cluster Options - -It's important to follow some guidelines when installing Flux on AKS. - -### CNI and Network Policy - -Previously, there has been an issue with Flux and Network Policy on AKS. -([Upstream Azure Issue](https://github.com/Azure/AKS/issues/2031)) ([Flux Issue](https://github.com/fluxcd/flux2/issues/703)) -If you ensure your AKS cluster is upgraded, and your Nodes have been restarted with the most recent Node images, -this could resolve flux reconciliation failures where source-controller is unreachable. -Using `--network-plugin=azure --network-policy=calico` has been tested to work properly. -This issue only affects you if you are using `--network-policy` on AKS, which is not a default option. - -{{% alert color="warning" %}} -AKS `--network-policy` is currently in Preview -{{% /alert %}} - -### AAD Workload Identity - -[AAD Workload Identities](https://learn.microsoft.com/en-us/azure/aks/workload-identity-overview) can be used -to enable access to AAD resources from workloads in your Kubernetes cluster. - -In order to leverage AAD Workload Identities, you'll need to have `--enable-oidc-issuer` -and `--enable-workload-identity` configured in your AKS cluster. - -You will also need to establish an identity that has access to ACR. - -You can then [establish a federated identity credential](https://azure.github.io/azure-workload-identity/docs/quick-start.html#6-establish-federated-identity-credential-between-the-identity-and-the-service-account-issuer--subject) -between the identity and the Flux source-controller ServiceAccount. - -Please follow guides for [OCIRepositories and AAD Workload Identities](https://fluxcd.io/flux/components/source/ocirepositories/#workload-identity) -and [HelmRepositories and AAD Workload Identities](https://fluxcd.io/flux/components/source/helmrepositories/#azure-workload-identity). - -### AAD Pod Identity - -{{% warning %}} -[AAD Pod Identity has been deprecated](https://github.com/Azure/aad-pod-identity#-announcement) and replaced with -Azure Workload Identity. -{{% /warning %}} - -Depending on the features you are interested in using with Flux, you may want to install AAD Pod Identity. -With [AAD Pod-Identity](https://azure.github.io/aad-pod-identity/docs/), we can create Pods that have their own -cloud credentials for accessing Azure services like Azure Container Registry(ACR) and Azure Key Vault(AKV). - -If you do not use AAD Pod-Identity, you'll need to manage and store Service Principal credentials -in K8s Secrets, to integrate Flux with other Azure Services. - -As a pre-requisite, your cluster must have `--enable-managed-identity` configured. - -This software can be [installed via Helm](https://azure.github.io/aad-pod-identity/docs/getting-started/installation/) -(unmanaged by Azure). -Use Flux's `HelmRepository` and `HelmRelease` object to manage the aad-pod-identity installation -from a bootstrap repository and keep it up to date. - -{{% alert %}} -As an alternative to Helm, the `--enable-aad-pod-identity` flag for the `az aks create` is currently in Preview. -Follow the Azure guide for [Creating an AKS cluster with AAD Pod Identity](https://docs.microsoft.com/en-us/azure/aks/use-azure-ad-pod-identity) -if you would like to enable this feature with the Azure CLI. -{{% /alert %}} - -### Cluster Creation - -The following creates an AKS cluster with some minimal configuration that will work well with Flux: - -```sh -az aks create \ - --network-plugin="azure" \ - --network-policy="calico" \ - --enable-managed-identity \ - --enable-oidc-issuer \ - --enable-workload-identity \ - --name="my-cluster" -``` - -{{% alert color="info" %}} -When working with the Azure CLI, it can help to set a default `location`, `group`, and `acr`. -See `az configure --help`, `az configure --list-defaults`, and `az configure --defaults key=value` -{{% /alert %}} - -## Flux Installation for Azure DevOps - -You can install Flux using a Azure Devops repository using the [`flux bootsrap git`](../installation.md#bootstrap) -command. -Ensure you can login to [dev.azure.com](https://dev.azure.com) for your proper organization, -and create a new repository to hold your Flux install and other Kubernetes resources. - -To bootstrap using HTTPS only, run the following command: -```sh -flux bootstrap git \ - --url=https://dev.azure.com///_git/ \ - --branch=main \ - --password=${AZ_PAT_TOKEN} \ - --token-auth=true -``` - -Please consult the [Azure DevOps documentation](https://docs.microsoft.com/en-us/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate?view=azure-devops&tabs=preview-page) -on how to generate personal access tokens for Git repositories. -Azure DevOps PAT's always have an expiration date, so be sure to have some process for renewing or updating these tokens. -Similar to the lack of repo-specific deploy keys, a user needs to generate a user-specific PAT. -If you are using a machine-user, you can generate a PAT or simply use the machine-user's password which does not expire. - -To bootstrap using HTTPS but drive the reconciliation in your cluster by cloning the repository using SSH, run: -```sh -flux bootstrap git \ - --url=https://dev.azure.com///_git/ \ - --branch=main \ - --password=${AZ_PAT_TOKEN}} \ - --ssh-hostname=ssh.dev.azure.com -``` - -To bootstrap using SSH, run: -```sh -flux bootstrap git \ - --url=ssh://git@ssh.dev.azure.com/v3/// - --branch=main \ - --ssh-key-algorithm=rsa \ - --ssh-rsa-bits=4096 \ - --interval=1m -``` - -The above two commands will prompt you to add a deploy key to your repository, but Azure DevOps -[does not support repository or org-specific deploy keys](https://developercommunity.visualstudio.com/t/allow-the-creation-of-ssh-deploy-keys-for-vsts-hos/365747). -You may add the deploy key to a user's personal SSH keys, but take note that revoking -the user's access to the repository will also revoke Flux's access. -The better alternative is to create a machine-user whose sole purpose is to store credentials -for automation. Using a machine-user also has the benefit of being able to be read-only or -restricted to specific repositories if this is needed. - -{{% alert color="info" %}} -Unlike `git`, Flux does not support the ["shorter" scp-like syntax for the SSH -protocol](https://git-scm.com/book/en/v2/Git-on-the-Server-The-Protocols#_the_ssh_protocol) -(e.g. `ssh.dev.azure.com:v3`). -Use the [RFC 3986 compatible syntax](https://tools.ietf.org/html/rfc3986#section-3) instead: `ssh.dev.azure.com/v3`. -{{% /alert %}} - -## Helm Repositories on Azure Container Registry - -The Flux `HelmRepository` object currently supports -[Chart Repositories](https://helm.sh/docs/topics/chart_repository/) -as well as fetching `HelmCharts` from paths in `GitRepository` sources. - -Azure Container Registry has a sub-command ([`az acr helm`](https://docs.microsoft.com/en-us/cli/azure/acr/helm)) -for working with ACR-Hosted Chart Repositories, but it is deprecated. -If you are using these deprecated Azure Chart Repositories, -you can use Flux `HelmRepository` objects with them. - -### Using Helm OCI with Azure Container Registry - -You can use Helm OCI Charts in Azure Container Registry with Flux. - -You have to declare a `HelmRepository` object on your cluster: - -```sh -flux create source helm podinfo \ - --url=oci://my-user.azurecr.io/charts/my-chart - --username=username \ - --password=password -``` - -or if you are using a private registry: - -```sh -flux create source helm my-helm-repo \ - --url=oci://my-user.azurecr.io/charts/my-chart - --secret-ref=regcred -``` - -You can create the secret by running: - -```sh -kubectl create secret docker-registry regcred \ - --docker-server=my-user.azurecr.io \ - --docker-username=az-user \ - --docker-password=az-token -``` - -Then, you can use the `HelmRepository` object in your `HelmRelease`: - -```sh -flux create hr my-helm-release \ - --interval=10m \ - --source=HelmRepository/my-helm-repo \ - --chart=my-chart \ - --chart-version=">6.0.0" -``` - -## Secrets Management with SOPS and Azure Key Vault - -You will need to create an Azure Key Vault and bind a credential such as a Service Principal or Managed Identity to it. -If you want to use Managed Identities, install or enable [AAD Pod Identity](#aad-pod-identity). - -Patch kustomize-controller with the proper Azure credentials, so that it may access your Azure Key Vault, and then begin -committing SOPS encrypted files to the Git repository with the proper Azure Key Vault configuration. - -See the [Mozilla SOPS Azure Guide](../guides/mozilla-sops.md#azure) for further detail. - -## Image Updates with Azure Container Registry - -You will need to create an ACR registry and bind a credential such as a Service Principal or Managed Identity to it. -If you want to use Managed Identities, install or enable [AAD Pod Identity](#aad-pod-identity). - -You may need to update your Flux install to include additional components: - -```sh -flux install \ - --components-extra="image-reflector-controller,image-automation-controller" \ - --export > ./clusters/my-cluster/flux-system/gotk-components.yaml -``` - -Follow the [Image Update Automation Guide](../guides/image-update.md) and see the -[ACR specific section](../guides/image-update.md#azure-container-registry) for more details. - -Your AKS cluster's configuration can also be updated to -[allow the kubelets to pull images from ACR](https://docs.microsoft.com/en-us/azure/aks/cluster-container-registry-integration) -without ImagePullSecrets as an optional, complimentary step. - -## Azure Event Hub with Notification controller - -The Notification Controller supports both JWT and SAS based tokens but it also assumes that you will provide the notification-controller with a fresh token when needed. - -For JWT token based auth we have created a small example on how to automatically generate a new token that the notification-controller can use. - -First you will need to create a Azure Event Hub and bind a [credential](https://docs.microsoft.com/en-us/azure/event-hubs/authenticate-application) such as a Service Principal or Managed Identity to it. -If you want to use Managed Identities, install or enable [AAD Pod Identity](#aad-pod-identity). - -We have two ways to [automatically generate](https://github.com/fluxcd/flux2/tree/main/manifests/integrations/eventhub-credentials-sync) new JWT tokens. Ether running as a deployment or a cronjob. - -If you are using Azure Event Hub in Azure we recommend that you use aadpodidentity. -If you do you will need to update the [AzureIdentity config example](https://github.com/fluxcd/flux2/blob/main/manifests/integrations/eventhub-credentials-sync/azure/config-patches.yaml). - -If you are in none Azure environment like on-prem or another cloud then you can utilize client secret which you will find in the example [generic folder](https://github.com/fluxcd/flux2/tree/main/manifests/integrations/eventhub-credentials-sync/generic). -Just like aadpodidentity you can use deployment based or a cronjob. - -For more info on how to use Azure Event Hub with the [notification controller](../components/notification/provider.md#azure-event-hub). diff --git a/content/en/flux/use-cases/gcp-source-repository.md b/content/en/flux/use-cases/gcp-source-repository.md deleted file mode 100644 index 0535fcfdb..000000000 --- a/content/en/flux/use-cases/gcp-source-repository.md +++ /dev/null @@ -1,110 +0,0 @@ ---- -title: Using Flux on GCP With Source Repository -linkTitle: Google Cloud Source Repositories -description: "How to bootstrap Flux on GCP GKE with Cloud Source repositories." -weight: 10 ---- - -### Cluster Creation - -To create a cluster with Google Cloud you can use the `gcloud` cli or the Google Cloud Console. - -The following command creates a cluster with the default configuration. - -```sh -gcloud containers create sample-cluster -``` - -For more details on how to create a GKE cluster with `gcloud`, -please see [the Cloud SDK Documentation](https://cloud.google.com/sdk/gcloud/reference/container/clusters/create) - -### Source Repository Creation - -Create a Cloud Source Repository that will hold your Flux installation manifests and other Kubernetes resources. -Like the cluster, it can be created with the CLI or the console. - -### Flux Installation - -Download the [Flux CLI](../installation.md#install-the-flux-cli) and bootstrap Flux with: - -```sh -flux bootstrap git \ ---url=ssh://s@source.developers.google.com:2022/p//r/ \ ---branch=master \ ---path=clusters/my-cluster -``` - -The above command will prompt you to add a deploy key to your repository, but Cloud Source Repository -does not support repository or org-specific deploy keys. You may add the deploy key to a user's -personal SSH keys, but take note that revoking the user's access to the repository will -also revoke Flux's access. The better alternative is to create a dedicated user for Flux. - -You can also use a SSH key that was already added to Cloud Source Repository -by adding the `--private-key-file` and `--password` flags. - -### Flux Upgrade - -To upgrade Flux, first you need to download the new CLI binary -from [GitHub release](../installation.md#install-the-flux-cli). - -Flux components can be upgraded by running the `bootstrap` command again with the same arguments as before: - -```sh -flux bootstrap git \ ---url=ssh://s@source.developers.google.com:2022/p//r/ \ ---branch=master \ ---path=clusters/my-cluster -``` - -To upgrade Flux in a GitOps manner, you can generate the components manifests with the `install` command -and commit the changes to your Git repository: - -```sh -flux install --export > clusters/my-cluster/flux-system/gotk-components.yaml -git add -A -git commit -m "Update $(flux -v)" -git push -``` - -Once Flux detects the changes in Git, it will upgrade itself. - -### Secrets Management with SOPS and GCP KMS - -You would need to create GCP KMS key and have -[workload identity](https://cloud.google.com/kubernetes-engine/docs/how-to/workload-identity) enabled on the GKE cluster. -Create an IAM service account that has `Cloud KMS CryptoKey Decrypter` role and allow the kustomize-controller -service account to impersonate this service account by adding an IAM policy binding between it and the IAM service account. - -```sh -gcloud iam service-accounts add-iam-policy-binding @.iam.gserviceaccount.com \ - --role roles/iam.workloadIdentityUser \ - --member "serviceAccount:.svc.id.goog[flux-system/kustomize-controller]" -``` - -Patch the kustomize-controller with the -`iam.gke.io/gcp-service-account=@.iam.gserviceaccount.com` -annotation so that it can access GCP KMS. -You can start committing your encrypted files to Git with the proper GCP KMS configuration. - -See the [Mozilla SOPS AWS Guide](../guides/mozilla-sops.md#google-cloud) for further detail. - -### Image Updates with Google Container Registry - -You will need to create an GCR registry. Most new GKE cluster by default have access to -Google Container Registry in the same project. -But if you have enabled Workload Identity on your cluster, -you would need to create an IAM service account that has access to GCR. - -You may need to update your Flux install to include additional components: - -```sh -flux bootstrap git \ ---url=ssh://s@source.developers.google.com:2022/p//r/ \ ---branch=master \ ---path=clusters/my-cluster ---components-extra="image-reflector-controller,image-automation-controller" -``` - -Follow the [Image Update Automation Guide](../guides/image-update.md) and see the -[GCP specific Image Automation Contollers documentation](../components/image/imagerepositories/#gcp) -for more details on how to configure image update automation for GKE. diff --git a/content/en/flux/use-cases/openshift.md b/content/en/flux/use-cases/openshift.md deleted file mode 100644 index a3cc23639..000000000 --- a/content/en/flux/use-cases/openshift.md +++ /dev/null @@ -1,179 +0,0 @@ ---- -title: Using Flux on OpenShift -linkTitle: OpenShift -description: "How to bootstrap Flux on OpenShift." -weight: 20 ---- - -## OpenShift Setup - -Steps described in this document have been tested on OpenShift 4.6, 4.7 and 4.8. -You require cluster-admin privileges to install Flux on OpenShift. -This means that it currently is not possible to install Flux on the OpenShift Developer Sandbox. - -### CodeReady Containers - -An easy way to provision OpenShift is to use CodeReady Containers (CRC) for OpenShift, -which could be obtained from [here](https://developers.redhat.com/products/codeready-containers/overview). -With this setup, you require a physical Linux box. An OpenShift cluster will run inside a VM installed by CRC. - -{{% alert color="info" title="Resource Usage" %}} -Please note that your desktop / laptop should have at least 8 CPU cores with 32 GB of RAM as it is recommended to allocate -at least 4 CPU cores and 18 GB of RAM for the cluster to have a good experience. -{{% /alert %}} - -```sh -# Setup the OpenShift configuration -# You need to paste a pull secret here -crc setup - -# Start the cluster with 18 GB of RAM -crc start -c 4 -m 18432 -``` - -After the cluster is up and running, there will be a message tell us how to login. -Please make sure that you use `kubeadmin` user to login before installing Flux. - -```sh -# Prepare environment setup for the OC command -eval $(crc oc-env) - -# Login -oc login -u kubeadmin -p https://api.crc.testing:6443 -``` - -## Flux Installation with CLI - -The best way to install Flux on OpenShift currently is to use the `flux bootstrap` command. -This command works with GitHub, GitLab as well as generic Git provider. - -Before installing Flux with CLI, you need to set the **nonroot** SCC for all controllers in the `flux-system` namespace, like this: - -```sh -NS="flux-system" -oc adm policy add-scc-to-user nonroot system:serviceaccount:${NS}:kustomize-controller -oc adm policy add-scc-to-user nonroot system:serviceaccount:${NS}:helm-controller -oc adm policy add-scc-to-user nonroot system:serviceaccount:${NS}:source-controller -oc adm policy add-scc-to-user nonroot system:serviceaccount:${NS}:notification-controller -oc adm policy add-scc-to-user nonroot system:serviceaccount:${NS}:image-automation-controller -oc adm policy add-scc-to-user nonroot system:serviceaccount:${NS}:image-reflector-controller -``` - -Also, you have to patch your Kustomization to remove the SecComp Profile and enforce `runUserAs` to the same UID provided by the images to prevent OpenShift to alter the user expected by our controllers, before bootstrapping by. - -1. You’ll need to create a Git repository and clone it locally. - -2. Create the file structure required by bootstrap using the following command: - -```sh -mkdir -p clusters/my-cluster/flux-system -touch clusters/my-cluster/flux-system/gotk-components.yaml \ - clusters/my-cluster/flux-system/gotk-sync.yaml \ - clusters/my-cluster/flux-system/kustomization.yaml -``` - -3. Add the following YAML snippet and its patches section to kustomization.yaml - -```yaml -apiVersion: kustomize.config.k8s.io/v1beta1 -kind: Kustomization -resources: - - gotk-components.yaml - - gotk-sync.yaml -patches: - # Remove seccompProfile from the flux Deployments when running on OpenShift - - patch: | - apiVersion: apps/v1 - kind: Deployment - metadata: - name: all - spec: - template: - spec: - containers: - - name: manager - securityContext: - runAsUser: 65534 - seccompProfile: - $patch: delete - target: - kind: Deployment - labelSelector: app.kubernetes.io/part-of=flux - # OpenShift will overwrite these Namespace labels - # Remove them from the flux definition and leave them to openshift. - - patch: |- - - op: remove - path: /metadata/labels/pod-security.kubernetes.io~1warn - - op: remove - path: /metadata/labels/pod-security.kubernetes.io~1warn-version - target: - kind: Namespace - labelSelector: app.kubernetes.io/part-of=flux -``` - -4. Commit and push the changes to main branch: - -```sh -git add -A && git commit -m "init flux for openshift" && git push -``` - -Then you can continue with the Flux bootstrap process. Assuming that you are a GitHub user, you could start by preparing your GitHub credentials. - -```sh -export GITHUB_TOKEN= -export GITHUB_USER= -``` - -And run the Flux bootstrap command. - -```sh -flux bootstrap github \ - --owner=$GITHUB_USER \ - --repository=openshift-gitops \ - --branch=main \ - --path=./clusters/my-cluster \ - --personal -``` - -Please refer to the command's documentations [here](../installation/_index.md#bootstrap) in details. - -## Flux Upgrade - -Upgrading Flux on OpenShift is very simple and straightforward. -Please just make sure that you are already logged in as `kubeadmin` user. -Assuming you are a Homebrew user, you could upgrade Flux CLI using the following command. - -```sh -# Upgrade Flux -brew upgrade fluxcd/tap/flux - -# Check Flux version -flux -v - -# Login as kubeadmin -oc login -u kubeadmin -p https://api.crc.testing:6443 -``` - -After you obtained the Flux version you wanted, simply re-run the above `flux bootstrap` -command from the previous section, and all of your Flux component will be upgraded. - -```sh -# Re-running the bootstrap command to upgrade -flux bootstrap github \ - --owner=$GITHUB_USER \ - --repository=openshift-gitops \ - --branch=main \ - --path=./clusters/my-cluster \ - --personal -``` - -Please see also the [upgrade](../installation/_index.md#upgrade) -and the [bootstrap upgrade](../installation/_index.md#bootstrap-upgrade) documentations for details. - -## Flux Installation via OperatorHub - -Flux is available on OperatorHub and Red Hat OpenShift Community Operators, which means that you can install Flux directly from the Red Hat OperatorHub user interface. - -On the OpenShift UI, you go to "Operators -> OperatorHub" menu, search for "Flux", click the Flux Operator, then click the "Install" button. - -Here's the link to [Flux on OperatorHub](https://operatorhub.io/operator/flux).