From f5366f2ea8b7937e8dca63bb0770493c8dae9125 Mon Sep 17 00:00:00 2001 From: mehak151 <66996176+mehak151@users.noreply.github.com> Date: Sun, 16 Jul 2023 18:06:08 +0500 Subject: [PATCH 01/30] Create & update Installation folder _index.md Remove the following sections to be included in the Bootstrap section later as per https://github.com/fluxcd/website/issues/1560 Generic Git Server GitHub GitLab BitBucket AWS CodeCommit Azure DevOps Google Cloud Source Signed-off-by: mehak151 <66996176+mehak151@users.noreply.github.com> --- content/en/flux/installation/_index.md | 308 +++++++++++++++++++++++++ 1 file changed, 308 insertions(+) create mode 100644 content/en/flux/installation/_index.md diff --git a/content/en/flux/installation/_index.md b/content/en/flux/installation/_index.md new file mode 100644 index 000000000..ba8a67a8b --- /dev/null +++ b/content/en/flux/installation/_index.md @@ -0,0 +1,308 @@ +--- +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](./bootstrap/aws-code-commit.md#flux-installation-for-aws-codecommit) +* [Azure DevOps](./bootstrap/azure.md#flux-installation-for-azure-devops) +* [Bitbucket Server and Data Center](./bootstrap/bitbucket.md#bitbucket-server-and-data-center) +* [GitHub.com and GitHub Enterprise](./bootstrap/github.md#github-and-github-enterprise) +* [GitLab.com and GitLab Enterprise](./bootstrap/gitlab.md#gitlab-and-gitlab-enterprise) + +## 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) 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" +``` From f09915f9ec68f3b7608ab37eaeb36d70a8f9f5ba Mon Sep 17 00:00:00 2001 From: mehak151 <66996176+mehak151@users.noreply.github.com> Date: Sun, 16 Jul 2023 18:11:12 +0500 Subject: [PATCH 02/30] Delete installation.md Signed-off-by: mehak151 <66996176+mehak151@users.noreply.github.com> --- content/en/flux/installation.md | 794 -------------------------------- 1 file changed, 794 deletions(-) delete mode 100644 content/en/flux/installation.md 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 %}} From a7e1c4b36cb1c90a7ff3a9dd74e9ce520d009d47 Mon Sep 17 00:00:00 2001 From: mehak151 <66996176+mehak151@users.noreply.github.com> Date: Sun, 16 Jul 2023 21:29:18 +0500 Subject: [PATCH 03/30] Create Bootstrap folder & _index.md Signed-off-by: mehak151 <66996176+mehak151@users.noreply.github.com> --- content/en/flux/bootstrap/_index.md | 6 ++++++ 1 file changed, 6 insertions(+) create mode 100644 content/en/flux/bootstrap/_index.md diff --git a/content/en/flux/bootstrap/_index.md b/content/en/flux/bootstrap/_index.md new file mode 100644 index 000000000..93b84a2e0 --- /dev/null +++ b/content/en/flux/bootstrap/_index.md @@ -0,0 +1,6 @@ +--- +title: "Bootstrap" +linkTitle: "Bootstrap" +description: "" +weight: 20 +--- From 57508e30f38ec91b2ca3abf5ca20567c557dcb5f Mon Sep 17 00:00:00 2001 From: mehak151 <66996176+mehak151@users.noreply.github.com> Date: Sun, 16 Jul 2023 21:31:17 +0500 Subject: [PATCH 04/30] Delete content/en/flux/bootstrap directory Need to create one in installation folder instead Signed-off-by: mehak151 <66996176+mehak151@users.noreply.github.com> --- content/en/flux/bootstrap/_index.md | 6 ------ 1 file changed, 6 deletions(-) delete mode 100644 content/en/flux/bootstrap/_index.md diff --git a/content/en/flux/bootstrap/_index.md b/content/en/flux/bootstrap/_index.md deleted file mode 100644 index 93b84a2e0..000000000 --- a/content/en/flux/bootstrap/_index.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: "Bootstrap" -linkTitle: "Bootstrap" -description: "" -weight: 20 ---- From d4e5a5fb1534d77b7d754c76cd2180e94d8aad3e Mon Sep 17 00:00:00 2001 From: mehak151 <66996176+mehak151@users.noreply.github.com> Date: Sun, 16 Jul 2023 22:27:23 +0500 Subject: [PATCH 05/30] Create installation/bootstrap folder & add _index.md Signed-off-by: mehak151 <66996176+mehak151@users.noreply.github.com> --- content/en/flux/installation/bootstrap/_index.md | 6 ++++++ 1 file changed, 6 insertions(+) create mode 100644 content/en/flux/installation/bootstrap/_index.md diff --git a/content/en/flux/installation/bootstrap/_index.md b/content/en/flux/installation/bootstrap/_index.md new file mode 100644 index 000000000..93b84a2e0 --- /dev/null +++ b/content/en/flux/installation/bootstrap/_index.md @@ -0,0 +1,6 @@ +--- +title: "Bootstrap" +linkTitle: "Bootstrap" +description: "" +weight: 20 +--- From 4c204262f729f272479f45a6eb64b48c76fcccad Mon Sep 17 00:00:00 2001 From: mehak151 <66996176+mehak151@users.noreply.github.com> Date: Sun, 16 Jul 2023 22:33:32 +0500 Subject: [PATCH 06/30] Add bootstrap/generic-git-server.md Signed-off-by: mehak151 <66996176+mehak151@users.noreply.github.com> --- .../bootstrap/generic-git-server.md | 74 +++++++++++++++++++ 1 file changed, 74 insertions(+) create mode 100644 content/en/flux/installation/bootstrap/generic-git-server.md diff --git a/content/en/flux/installation/bootstrap/generic-git-server.md b/content/en/flux/installation/bootstrap/generic-git-server.md new file mode 100644 index 000000000..534618eb0 --- /dev/null +++ b/content/en/flux/installation/bootstrap/generic-git-server.md @@ -0,0 +1,74 @@ +--- +title: Generic Git Server +linkTitle: Generic Git server +description: "Generic Git Server" +weight: 20 +--- +### 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) From a95852b92a25c0a4a1287b2a90fb1c55ee95d970 Mon Sep 17 00:00:00 2001 From: mehak151 <66996176+mehak151@users.noreply.github.com> Date: Sun, 16 Jul 2023 22:35:45 +0500 Subject: [PATCH 07/30] Add bootstrap/github.md Signed-off-by: mehak151 <66996176+mehak151@users.noreply.github.com> --- .../en/flux/installation/bootstrap/github.md | 78 +++++++++++++++++++ 1 file changed, 78 insertions(+) create mode 100644 content/en/flux/installation/bootstrap/github.md diff --git a/content/en/flux/installation/bootstrap/github.md b/content/en/flux/installation/bootstrap/github.md new file mode 100644 index 000000000..8820249db --- /dev/null +++ b/content/en/flux/installation/bootstrap/github.md @@ -0,0 +1,78 @@ +--- +title: GitHub +linkTitle: GitHub +description: "GitHub installation method" +weight: 20 +--- +### 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 +``` From cd231ba3ddcd37c7ae7fd1cb92f5060ff05f0485 Mon Sep 17 00:00:00 2001 From: mehak151 <66996176+mehak151@users.noreply.github.com> Date: Sun, 16 Jul 2023 22:53:06 +0500 Subject: [PATCH 08/30] Add bootstrap/gitlab.md Signed-off-by: mehak151 <66996176+mehak151@users.noreply.github.com> --- .../en/flux/installation/bootstrap/gitlab.md | 85 +++++++++++++++++++ 1 file changed, 85 insertions(+) create mode 100644 content/en/flux/installation/bootstrap/gitlab.md diff --git a/content/en/flux/installation/bootstrap/gitlab.md b/content/en/flux/installation/bootstrap/gitlab.md new file mode 100644 index 000000000..237e6ac82 --- /dev/null +++ b/content/en/flux/installation/bootstrap/gitlab.md @@ -0,0 +1,85 @@ +--- +title: GitLab +linkTitle: GitLab +description: "GitLab installation method" +weight: 30 +--- + +### 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 +``` From 2d88676fe70097caaa89b0219e61d3c92fbdb9b7 Mon Sep 17 00:00:00 2001 From: mehak151 <66996176+mehak151@users.noreply.github.com> Date: Sun, 16 Jul 2023 23:04:11 +0500 Subject: [PATCH 09/30] Add bootstrap/bitbucket.md Signed-off-by: mehak151 <66996176+mehak151@users.noreply.github.com> --- .../flux/installation/bootstrap/bitbucket.md | 80 +++++++++++++++++++ 1 file changed, 80 insertions(+) create mode 100644 content/en/flux/installation/bootstrap/bitbucket.md diff --git a/content/en/flux/installation/bootstrap/bitbucket.md b/content/en/flux/installation/bootstrap/bitbucket.md new file mode 100644 index 000000000..41013309e --- /dev/null +++ b/content/en/flux/installation/bootstrap/bitbucket.md @@ -0,0 +1,80 @@ +--- +title: Bitbucket +linkTitle: Bitbucket +description: "How to follow bootstrap procedure for Flux using Bitbucket" +weight: 40 +--- + +### 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 +``` From 23a42cdc4837f3db70932e114bd1b672ca99a381 Mon Sep 17 00:00:00 2001 From: mehak151 <66996176+mehak151@users.noreply.github.com> Date: Sun, 16 Jul 2023 23:05:11 +0500 Subject: [PATCH 10/30] Update description for boostrap/github.md Signed-off-by: mehak151 <66996176+mehak151@users.noreply.github.com> --- content/en/flux/installation/bootstrap/github.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/flux/installation/bootstrap/github.md b/content/en/flux/installation/bootstrap/github.md index 8820249db..d9511a9ae 100644 --- a/content/en/flux/installation/bootstrap/github.md +++ b/content/en/flux/installation/bootstrap/github.md @@ -1,7 +1,7 @@ --- title: GitHub linkTitle: GitHub -description: "GitHub installation method" +description: "How to follow bootstrap procedure for Flux using GitHub" weight: 20 --- ### GitHub and GitHub Enterprise From 61888c41c2ff583e298b2422a1889f8e93915445 Mon Sep 17 00:00:00 2001 From: mehak151 <66996176+mehak151@users.noreply.github.com> Date: Sun, 16 Jul 2023 23:05:45 +0500 Subject: [PATCH 11/30] Update description for bootstrap/gitlab.md Signed-off-by: mehak151 <66996176+mehak151@users.noreply.github.com> --- content/en/flux/installation/bootstrap/gitlab.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/flux/installation/bootstrap/gitlab.md b/content/en/flux/installation/bootstrap/gitlab.md index 237e6ac82..6d96933c7 100644 --- a/content/en/flux/installation/bootstrap/gitlab.md +++ b/content/en/flux/installation/bootstrap/gitlab.md @@ -1,7 +1,7 @@ --- title: GitLab linkTitle: GitLab -description: "GitLab installation method" +description: "How to follow bootstrap procedure for Flux using GitLab" weight: 30 --- From 2f4700dc20b205f576288a140647c4e59ab66b5a Mon Sep 17 00:00:00 2001 From: mehak151 <66996176+mehak151@users.noreply.github.com> Date: Sun, 16 Jul 2023 23:30:34 +0500 Subject: [PATCH 12/30] Add bootstrap/aws-code-commit.md Signed-off-by: mehak151 <66996176+mehak151@users.noreply.github.com> --- .../installation/bootstrap/aws-code-commit.md | 115 ++++++++++++++++++ 1 file changed, 115 insertions(+) create mode 100644 content/en/flux/installation/bootstrap/aws-code-commit.md diff --git a/content/en/flux/installation/bootstrap/aws-code-commit.md b/content/en/flux/installation/bootstrap/aws-code-commit.md new file mode 100644 index 000000000..1cf2d48b9 --- /dev/null +++ b/content/en/flux/installation/bootstrap/aws-code-commit.md @@ -0,0 +1,115 @@ +--- +title: AWS Code Commit +linkTitle: AWS Code Commit +description: "How to follow bootstrap procedure for Flux using AWS Code Commit" +weight: 50 +--- + +## 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#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#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) and see the +[ECR specific section](../../guides/image-update#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. From ee0724976f254283f85986498aed60017d6793c7 Mon Sep 17 00:00:00 2001 From: mehak151 <66996176+mehak151@users.noreply.github.com> Date: Mon, 17 Jul 2023 07:56:38 +0500 Subject: [PATCH 13/30] Add bootstrap/azure.md Signed-off-by: mehak151 <66996176+mehak151@users.noreply.github.com> --- .../en/flux/installation/bootstrap/azure.md | 241 ++++++++++++++++++ 1 file changed, 241 insertions(+) create mode 100644 content/en/flux/installation/bootstrap/azure.md diff --git a/content/en/flux/installation/bootstrap/azure.md b/content/en/flux/installation/bootstrap/azure.md new file mode 100644 index 000000000..5596b8e92 --- /dev/null +++ b/content/en/flux/installation/bootstrap/azure.md @@ -0,0 +1,241 @@ +--- +title: Azure DevOps +linkTitle: Azure DevOps +description: "How to follow bootstrap procedure for Flux using Azure DevOps" +weight: 60 +--- + +## 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 bootstrap git`](../../installation#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#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) and see the +[ACR specific section](../../guides/image-update#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#azure-event-hub). From d20aebf3675cb9c1e672f5cd22dce55df35758c7 Mon Sep 17 00:00:00 2001 From: mehak151 <66996176+mehak151@users.noreply.github.com> Date: Mon, 17 Jul 2023 07:59:03 +0500 Subject: [PATCH 14/30] Add bootstrap/google-cloud-source.md Signed-off-by: mehak151 <66996176+mehak151@users.noreply.github.com> --- .../bootstrap/google-cloud-source.md | 110 ++++++++++++++++++ 1 file changed, 110 insertions(+) create mode 100644 content/en/flux/installation/bootstrap/google-cloud-source.md diff --git a/content/en/flux/installation/bootstrap/google-cloud-source.md b/content/en/flux/installation/bootstrap/google-cloud-source.md new file mode 100644 index 000000000..23845ce20 --- /dev/null +++ b/content/en/flux/installation/bootstrap/google-cloud-source.md @@ -0,0 +1,110 @@ +--- +title: Google Cloud Source +linkTitle: Google Cloud Source +description: "How to use bootstrap procedure for Flux using Google Cloud Source" +weight: 70 +--- + +### 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](/flux/installation#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](/flux/installation#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#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) 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. From 2a67442ef4e8817ebcc9ccaa3e79a78ab418d2ef Mon Sep 17 00:00:00 2001 From: mehak151 <66996176+mehak151@users.noreply.github.com> Date: Mon, 17 Jul 2023 08:04:08 +0500 Subject: [PATCH 15/30] Add installation/upgrade.md Signed-off-by: mehak151 <66996176+mehak151@users.noreply.github.com> --- content/en/flux/installation/upgrade.md | 86 +++++++++++++++++++++++++ 1 file changed, 86 insertions(+) create mode 100644 content/en/flux/installation/upgrade.md diff --git a/content/en/flux/installation/upgrade.md b/content/en/flux/installation/upgrade.md new file mode 100644 index 000000000..f9dee6bd6 --- /dev/null +++ b/content/en/flux/installation/upgrade.md @@ -0,0 +1,86 @@ +--- +title: Upgrade +linkTitle: Upgrade (CLI bootstrap, GH Action, Renovate, terraform, in-cluster) +description: "Upgrade (CLI bootstrap, GH Action, Renovate, terraform, in-cluster)" +weight: 40 +--- + +## 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](/flux/installation#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- +``` From 66b270e8d12d8dcec410d88ccb859973cc03f7bd Mon Sep 17 00:00:00 2001 From: mehak151 <66996176+mehak151@users.noreply.github.com> Date: Mon, 17 Jul 2023 08:06:34 +0500 Subject: [PATCH 16/30] Add installation/uninstall.md Signed-off-by: mehak151 <66996176+mehak151@users.noreply.github.com> --- content/en/flux/installation/uninstall.md | 37 +++++++++++++++++++++++ 1 file changed, 37 insertions(+) create mode 100644 content/en/flux/installation/uninstall.md diff --git a/content/en/flux/installation/uninstall.md b/content/en/flux/installation/uninstall.md new file mode 100644 index 000000000..b4c6ac7ba --- /dev/null +++ b/content/en/flux/installation/uninstall.md @@ -0,0 +1,37 @@ +--- +title: Uninstall +linkTitle: Uninstall (CLI uninstall) +description: "Uninstall Flux using CLI uninstall method" +weight: 50 +--- + +## 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 %}} From 736c05e8ba851bf356b94edbbb3a0969890becfc Mon Sep 17 00:00:00 2001 From: mehak151 <66996176+mehak151@users.noreply.github.com> Date: Mon, 17 Jul 2023 08:44:27 +0500 Subject: [PATCH 17/30] Update _redirects as per structural changes Added redirects for following: Bootstrap Generic Git Server GitHub GitLab BitBucket AWS CodeCommit Azure DevOps Google Cloud Source Upgrade Uninstall Signed-off-by: mehak151 <66996176+mehak151@users.noreply.github.com> --- static/_redirects | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/static/_redirects b/static/_redirects index a332e1e98..86780a408 100644 --- a/static/_redirects +++ b/static/_redirects @@ -26,6 +26,18 @@ /flagger/usage/kuma-progressive-delivery /flagger/tutorials/kuma-progressive-delivery 301! /flagger/usage/gatewayapi-progressive-delivery /flagger/tutorials/gatewayapi-progressive-delivery 301! +/flux/installation/#bootstrap /flux/installation/bootstrap 301! +/flux/installation/#bitbucket-server-and-data-center /flux/installation/bootstrap/bitbucket 301! +/flux/installation/#generic-git-server /flux/installation/bootstrap/generic-git-server 301! +/flux/installation/#github-and-github-enterprise /flux/installation/bootstrap/github 301! +/flux/installation/#gitlab-and-gitlab-enterprise /flux/installation/bootstrap/gitlab 301! +/flux/installation/#upgrade /flux/installation/upgrade 301! +/flux/installation/#uninstall /flux/installation/uninstall 301! +/flux/use-cases/aws-codecommit/* /flux/installation/bootstrap/aws-code-commit 301! +/flux/use-cases/azure/* /flux/installation/bootstrap/azure 301! +/flux/use-cases/gcp-source-repository /flux/installation/bootstrap/google-cloud-source 301! 301! + + /docs/contributing/* /contributing/:splat 301! /docs/* /flux/:splat 301! From 9f2394d957505deb1973b7e464c7f6154a2a1eb8 Mon Sep 17 00:00:00 2001 From: mehak151 <66996176+mehak151@users.noreply.github.com> Date: Wed, 19 Jul 2023 07:52:30 +0500 Subject: [PATCH 18/30] Update description in upgrade.md Co-authored-by: Stefan Prodan Signed-off-by: mehak151 <66996176+mehak151@users.noreply.github.com> --- content/en/flux/installation/upgrade.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/en/flux/installation/upgrade.md b/content/en/flux/installation/upgrade.md index f9dee6bd6..7b7792e0a 100644 --- a/content/en/flux/installation/upgrade.md +++ b/content/en/flux/installation/upgrade.md @@ -1,7 +1,7 @@ --- title: Upgrade -linkTitle: Upgrade (CLI bootstrap, GH Action, Renovate, terraform, in-cluster) -description: "Upgrade (CLI bootstrap, GH Action, Renovate, terraform, in-cluster)" +linkTitle: Upgrade +description: "Upgrade Flux using bootstrap" weight: 40 --- From 3430e7f9a76de7d459ba5165dc683df8889637ce Mon Sep 17 00:00:00 2001 From: mehak151 <66996176+mehak151@users.noreply.github.com> Date: Wed, 19 Jul 2023 07:53:43 +0500 Subject: [PATCH 19/30] Update title in github.md Co-authored-by: Stefan Prodan Signed-off-by: mehak151 <66996176+mehak151@users.noreply.github.com> --- content/en/flux/installation/bootstrap/github.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/flux/installation/bootstrap/github.md b/content/en/flux/installation/bootstrap/github.md index d9511a9ae..80513812c 100644 --- a/content/en/flux/installation/bootstrap/github.md +++ b/content/en/flux/installation/bootstrap/github.md @@ -1,5 +1,5 @@ --- -title: GitHub +title: GitHub and GitHub Enterprise linkTitle: GitHub description: "How to follow bootstrap procedure for Flux using GitHub" weight: 20 From 15ed78368dcf292049fbc3d00b57ea5a3ca440fe Mon Sep 17 00:00:00 2001 From: mehak151 <66996176+mehak151@users.noreply.github.com> Date: Wed, 19 Jul 2023 07:56:12 +0500 Subject: [PATCH 20/30] Update title for github.md Co-authored-by: Stefan Prodan Signed-off-by: mehak151 <66996176+mehak151@users.noreply.github.com> --- content/en/flux/installation/bootstrap/github.md | 1 - 1 file changed, 1 deletion(-) diff --git a/content/en/flux/installation/bootstrap/github.md b/content/en/flux/installation/bootstrap/github.md index 80513812c..f507d78a1 100644 --- a/content/en/flux/installation/bootstrap/github.md +++ b/content/en/flux/installation/bootstrap/github.md @@ -4,7 +4,6 @@ linkTitle: GitHub description: "How to follow bootstrap procedure for Flux using GitHub" weight: 20 --- -### 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 From 44d27079fdec1debf1501269ffd64656426e938f Mon Sep 17 00:00:00 2001 From: mehak151 <66996176+mehak151@users.noreply.github.com> Date: Wed, 19 Jul 2023 07:56:39 +0500 Subject: [PATCH 21/30] Update description for generic-git-server.md Co-authored-by: Stefan Prodan Signed-off-by: mehak151 <66996176+mehak151@users.noreply.github.com> --- content/en/flux/installation/bootstrap/generic-git-server.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/flux/installation/bootstrap/generic-git-server.md b/content/en/flux/installation/bootstrap/generic-git-server.md index 534618eb0..f7d2396b9 100644 --- a/content/en/flux/installation/bootstrap/generic-git-server.md +++ b/content/en/flux/installation/bootstrap/generic-git-server.md @@ -1,7 +1,7 @@ --- title: Generic Git Server linkTitle: Generic Git server -description: "Generic Git Server" +description: ""How to bootstrap Flux with a generic Git server" weight: 20 --- ### Generic Git Server From fea55c0eeeffcbf04c4004811b11d8445e61a4a0 Mon Sep 17 00:00:00 2001 From: mehak151 <66996176+mehak151@users.noreply.github.com> Date: Wed, 19 Jul 2023 07:57:04 +0500 Subject: [PATCH 22/30] Update heading in _index.md Co-authored-by: Stefan Prodan Signed-off-by: mehak151 <66996176+mehak151@users.noreply.github.com> --- content/en/flux/installation/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/flux/installation/_index.md b/content/en/flux/installation/_index.md index ba8a67a8b..0b3525e18 100644 --- a/content/en/flux/installation/_index.md +++ b/content/en/flux/installation/_index.md @@ -93,7 +93,7 @@ A container image with `kubectl` and `flux` is available on DockerHub and GitHub * `docker.io/fluxcd/flux-cli:` * `ghcr.io/fluxcd/flux-cli:` -## Bootstrap +## Bootstrap with Flux CLI Using the `flux bootstrap` command you can install Flux on a Kubernetes cluster and configure it to manage itself from a Git From 4f39d285d961ee38b5bbe5c3e59c1d8a9e3845e1 Mon Sep 17 00:00:00 2001 From: mehak151 <66996176+mehak151@users.noreply.github.com> Date: Wed, 19 Jul 2023 07:57:31 +0500 Subject: [PATCH 23/30] Update description in aws-code-commit.md Co-authored-by: Stefan Prodan Signed-off-by: mehak151 <66996176+mehak151@users.noreply.github.com> --- content/en/flux/installation/bootstrap/aws-code-commit.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/flux/installation/bootstrap/aws-code-commit.md b/content/en/flux/installation/bootstrap/aws-code-commit.md index 1cf2d48b9..493fb22dc 100644 --- a/content/en/flux/installation/bootstrap/aws-code-commit.md +++ b/content/en/flux/installation/bootstrap/aws-code-commit.md @@ -1,7 +1,7 @@ --- title: AWS Code Commit linkTitle: AWS Code Commit -description: "How to follow bootstrap procedure for Flux using AWS Code Commit" +description: "How to bootstrap Flux with AWS Code Commit" weight: 50 --- From 8953108a04ba26202cd0a67e8aa49ab0a2577845 Mon Sep 17 00:00:00 2001 From: mehak151 <66996176+mehak151@users.noreply.github.com> Date: Wed, 19 Jul 2023 18:51:19 +0500 Subject: [PATCH 24/30] Fixed syntax error in generic-git-server.md Signed-off-by: mehak151 <66996176+mehak151@users.noreply.github.com> --- content/en/flux/installation/bootstrap/generic-git-server.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/flux/installation/bootstrap/generic-git-server.md b/content/en/flux/installation/bootstrap/generic-git-server.md index f7d2396b9..fefbfebed 100644 --- a/content/en/flux/installation/bootstrap/generic-git-server.md +++ b/content/en/flux/installation/bootstrap/generic-git-server.md @@ -1,7 +1,7 @@ --- title: Generic Git Server linkTitle: Generic Git server -description: ""How to bootstrap Flux with a generic Git server" +description: "How to bootstrap Flux with a generic Git server" weight: 20 --- ### Generic Git Server From 38f918ff3ef0a313dfeb133e2b4375c0f943ada7 Mon Sep 17 00:00:00 2001 From: mehak151 <66996176+mehak151@users.noreply.github.com> Date: Thu, 20 Jul 2023 08:23:12 +0500 Subject: [PATCH 25/30] Add description in bootstrap/_index.md Signed-off-by: mehak151 <66996176+mehak151@users.noreply.github.com> --- content/en/flux/installation/bootstrap/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/flux/installation/bootstrap/_index.md b/content/en/flux/installation/bootstrap/_index.md index 93b84a2e0..14b638c0f 100644 --- a/content/en/flux/installation/bootstrap/_index.md +++ b/content/en/flux/installation/bootstrap/_index.md @@ -1,6 +1,6 @@ --- title: "Bootstrap" linkTitle: "Bootstrap" -description: "" +description: "How to bootstrap Flux" weight: 20 --- From 56daf48273829335fc9ada60741e9a68f814c863 Mon Sep 17 00:00:00 2001 From: mehak151 <66996176+mehak151@users.noreply.github.com> Date: Thu, 20 Jul 2023 08:24:34 +0500 Subject: [PATCH 26/30] Update description in azure.md Signed-off-by: mehak151 <66996176+mehak151@users.noreply.github.com> --- content/en/flux/installation/bootstrap/azure.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/flux/installation/bootstrap/azure.md b/content/en/flux/installation/bootstrap/azure.md index 5596b8e92..6e1dfae50 100644 --- a/content/en/flux/installation/bootstrap/azure.md +++ b/content/en/flux/installation/bootstrap/azure.md @@ -1,7 +1,7 @@ --- title: Azure DevOps linkTitle: Azure DevOps -description: "How to follow bootstrap procedure for Flux using Azure DevOps" +description: "How to follow bootstrap Flux with Azure DevOps" weight: 60 --- From dc5a66006078a06959ec45bdd2855738a22926a8 Mon Sep 17 00:00:00 2001 From: mehak151 <66996176+mehak151@users.noreply.github.com> Date: Thu, 20 Jul 2023 08:28:10 +0500 Subject: [PATCH 27/30] Update description in bitbucket.md Signed-off-by: mehak151 <66996176+mehak151@users.noreply.github.com> --- content/en/flux/installation/bootstrap/bitbucket.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/flux/installation/bootstrap/bitbucket.md b/content/en/flux/installation/bootstrap/bitbucket.md index 41013309e..b2be5a0f6 100644 --- a/content/en/flux/installation/bootstrap/bitbucket.md +++ b/content/en/flux/installation/bootstrap/bitbucket.md @@ -1,7 +1,7 @@ --- title: Bitbucket linkTitle: Bitbucket -description: "How to follow bootstrap procedure for Flux using Bitbucket" +description: "How to bootstrap Flux with Bitbucket" weight: 40 --- From 86d8c7e6f1dd8c9a5aa45afb2fcf64db9f8fbf1e Mon Sep 17 00:00:00 2001 From: mehak151 <66996176+mehak151@users.noreply.github.com> Date: Thu, 20 Jul 2023 08:29:14 +0500 Subject: [PATCH 28/30] Update description in github.md Signed-off-by: mehak151 <66996176+mehak151@users.noreply.github.com> --- content/en/flux/installation/bootstrap/github.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/flux/installation/bootstrap/github.md b/content/en/flux/installation/bootstrap/github.md index f507d78a1..9dcfc649b 100644 --- a/content/en/flux/installation/bootstrap/github.md +++ b/content/en/flux/installation/bootstrap/github.md @@ -1,7 +1,7 @@ --- title: GitHub and GitHub Enterprise linkTitle: GitHub -description: "How to follow bootstrap procedure for Flux using GitHub" +description: "How to bootstrap Flux with GitHub" weight: 20 --- From 53a071b7fc931a04173a76f5c0412b037d7e02f3 Mon Sep 17 00:00:00 2001 From: mehak151 <66996176+mehak151@users.noreply.github.com> Date: Thu, 20 Jul 2023 08:29:52 +0500 Subject: [PATCH 29/30] Update gitlab.md Signed-off-by: mehak151 <66996176+mehak151@users.noreply.github.com> --- content/en/flux/installation/bootstrap/gitlab.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/flux/installation/bootstrap/gitlab.md b/content/en/flux/installation/bootstrap/gitlab.md index 6d96933c7..91518ff6f 100644 --- a/content/en/flux/installation/bootstrap/gitlab.md +++ b/content/en/flux/installation/bootstrap/gitlab.md @@ -1,7 +1,7 @@ --- title: GitLab linkTitle: GitLab -description: "How to follow bootstrap procedure for Flux using GitLab" +description: "How to bootstrap Flux with GitLab" weight: 30 --- From 61c7b12e1507843d303e947a51952985e83ae559 Mon Sep 17 00:00:00 2001 From: mehak151 <66996176+mehak151@users.noreply.github.com> Date: Thu, 20 Jul 2023 08:30:16 +0500 Subject: [PATCH 30/30] Update description in google-cloud-source.md Signed-off-by: mehak151 <66996176+mehak151@users.noreply.github.com> --- content/en/flux/installation/bootstrap/google-cloud-source.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/flux/installation/bootstrap/google-cloud-source.md b/content/en/flux/installation/bootstrap/google-cloud-source.md index 23845ce20..c82ab4585 100644 --- a/content/en/flux/installation/bootstrap/google-cloud-source.md +++ b/content/en/flux/installation/bootstrap/google-cloud-source.md @@ -1,7 +1,7 @@ --- title: Google Cloud Source linkTitle: Google Cloud Source -description: "How to use bootstrap procedure for Flux using Google Cloud Source" +description: "How bootstrap Flux with Google Cloud Source" weight: 70 ---