From d8d08091cc9b72b59a6c651c211a24ec3cb07ca7 Mon Sep 17 00:00:00 2001 From: Stefan Prodan Date: Wed, 7 Apr 2021 19:01:22 +0300 Subject: [PATCH 1/6] Move Azure DevOps bootstrap to Azure docs Signed-off-by: Stefan Prodan --- docs/use-cases/azure.md | 140 +++++++++++++++++++++++++++++++++++----- 1 file changed, 123 insertions(+), 17 deletions(-) diff --git a/docs/use-cases/azure.md b/docs/use-cases/azure.md index e1e75044..9e01ff1b 100644 --- a/docs/use-cases/azure.md +++ b/docs/use-cases/azure.md @@ -52,23 +52,129 @@ az aks create \ ## Flux Installation with Azure DevOps Repos -Ensure you can login to [dev.azure.com](https://dev.azure.com) for your proper organization, and create a new repo to hold your -flux install and other necessary config. - -There is no bootstrap provider currently for Azure DevOps Repos, -but you can clone your Azure Repo, then use the [Generic Git Server](../guides/installation.md#generic-git-server) -guide to manually bootstrap Flux. (It must be a Git repo; TFVC Repos are not supported by source-controller) -Take note of the Azure DevOps specific section within the guide. - -If you use the generated SSH deploy key from `flux create source git`, ensure it is an RSA key (not an elliptic curve). -Make sure to use the `libgit2` provider for all `GitRepository` objects fetching from Azure Repos since they use Git Protocol v2. - -Whether you're using the generated SSH deploy key or a Personal Access Token, the credentials used by -Flux will need to be owned by an Azure DevOps User with access to the repo. -Consider creating a machine-user and granting it granular permissions to access what's needed. -This allows changing user access without affecting Flux. -Since PAT's expire on Azure DevOps, using a machine-user's login password to authenticate with HTTPS and `libgit2` -can be a good option that avoids the need to renew the credential while also having the benefit of more granular permissions. +Ensure you can login to [dev.azure.com](https://dev.azure.com) for your proper organization, +and create a new repo to hold your Flux install and other necessary config. + +Clone the Git repository locally: + +```sh +git clone ssh://git@ssh.dev.azure.com/v3/// +cd my-repository +``` + +Create a directory inside the repository: + +```sh +mkdir -p ./clusters/my-cluster/flux-system +``` + +Generate the Flux manifests with: + +```sh +flux install \ + --export > ./clusters/my-cluster/flux-system/gotk-components.yaml +``` + +Commit and push the manifest to the master branch: + +```sh +git add -A && git commit -m "add components" && git push +``` + +Apply the manifests on your cluster: + +```sh +kubectl apply -f ./clusters/my-cluster/flux-system/gotk-components.yaml +``` + +Verify that the controllers have started: + +```sh +flux check +``` + +Create a `GitRepository` object on your cluster by specifying the SSH address of your repo: + +```sh +flux create source git flux-system \ + --git-implementation=libgit2 \ + --ssh-key-algorithm=rsa \ + --ssh-rsa-bits=4096 \ + --url=ssh://git@ssh.dev.azure.com/v3/// \ + --branch=main \ + --interval=1m +``` + +This config uses the `main` branch, but your repo may be older and need to specify `master` instead. + +Note that 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`. + +You will be prompted to add a deploy key to your repository. +If you don't specify the SSH algorithm, then `flux` will generate an RSA 2048 bits key. + +The `flux create source git` command 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 being mindful that removing them from the repo may revoke Flux's access. +As an alternative, 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 that is needed. + +If you wish to use Git over HTTPS, then generate a personal access token and supply it as the password: + +```sh +flux create source git flux-system \ + --git-implementation=libgit2 \ + --url=https://dev.azure.com///_git/ \ + --branch=master \ + --username=git \ + --password=${AZ_PAT_TOKEN} \ + --interval=1m +``` + +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. + +Create a `Kustomization` object on your cluster: + +```sh +flux create kustomization flux-system \ + --source=flux-system \ + --path="./clusters/my-cluster" \ + --prune=true \ + --interval=10m +``` + +Export both objects, generate a `kustomization.yaml`, commit and push the manifests to Git: + +```sh +flux export source git flux-system \ + > ./clusters/my-cluster/flux-system/gotk-sync.yaml + +flux export kustomization flux-system \ + >> ./clusters/my-cluster/flux-system/gotk-sync.yaml + +cd ./clusters/my-cluster/flux-system && kustomize create --autodetect + +git add -A && git commit -m "add sync manifests" && git push +``` + +To upgrade the Flux components to a newer version, download the latest `flux` binary, +run the install command and commit the changes: + +```sh +flux install \ + --export > ./clusters/my-cluster/flux-system/gotk-components.yaml + +git add -A && git commit -m "update flux" && git push +``` + +The source-controller will pull the changes on the cluster, then the kustomize-controller +will perform a rolling update of all Flux components including itself. ## Helm Repositories on Azure Container Registry From f4adfc3029eb6ac13a7c9d05b9b78bf11befd84f Mon Sep 17 00:00:00 2001 From: Stefan Prodan Date: Wed, 7 Apr 2021 19:01:50 +0300 Subject: [PATCH 2/6] Add bootstrap git to install docs Signed-off-by: Stefan Prodan --- docs/guides/installation.md | 227 ++++++++---------------------------- docs/use-cases/azure.md | 89 +++++++------- 2 files changed, 100 insertions(+), 216 deletions(-) diff --git a/docs/guides/installation.md b/docs/guides/installation.md index 99cf53ba..6ff8a795 100644 --- a/docs/guides/installation.md +++ b/docs/guides/installation.md @@ -42,32 +42,57 @@ flux check --pre Using the `flux bootstrap` command you can install Flux on a Kubernetes cluster and configure it to manage itself from a Git repository. - -The bootstrap creates a Git repository if one doesn't exist and -commits the Flux components manifests to the main branch. Then it -configures the target cluster to synchronize with that repository by -setting up SSH deploy keys. - 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. -You can choose what components to install and for which cluster with: +!!! hint "Multi-arch images" + The component images are published as [multi-arch container images](https://docs.docker.com/docker-for-mac/multi-arch/) + with support for Linux `amd64`, `arm64` and `armv7` (e.g. 32bit Raspberry Pi) + architectures. + +### 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. + +Run bootstrap for a Git repository and authenticate with your SSH agent: ```sh -flux bootstrap \ - --components=source-controller,kustomize-controller,helm-controller,notification-controller \ - --components-extra=image-reflector-controller,image-automation-controller \ +flux bootstrap git \ + --url=ssh://git@// \ + --branch= \ --path=clusters/my-cluster ``` -!!! hint "Multi-arch images" - The component images are published as [multi-arch container images](https://docs.docker.com/docker-for-mac/multi-arch/) - with support for Linux `amd64`, `arm64` and `armv7` (e.g. 32bit Raspberry Pi) - architectures. +The above command will generate a SSH key (defaults to RSA 2048 but can be changed with `--ssh-key-algorithm`), +and it will prompt you to add the SSH public key as a deploy key to your repository. + +If SSH agent is not available on your machine, you can provide a **passwordless** private key using +`--private-key-file=`. + +!!! hint "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`. + +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=`. If you wish to install a specific version, use the Flux -[release tag](https://github.com/fluxcd/flux2/releases) e.g. `--version=v0.9.0`. +[release tag](https://github.com/fluxcd/flux2/releases) e.g. `--version=v0.12.0`. If you wish to deploy the Flux components onto [tainted Kubernetes nodes](https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration/), @@ -84,17 +109,13 @@ cluster e.g. `clusters/staging` and `clusters/production`: │   ├── gotk-components.yaml │   ├── gotk-sync.yaml │   └── kustomization.yaml -└── production-cluster # <- path=clusters/production +└── 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. -!!! hint "Change the default branch" - If you wish to change the branch to something else than main, create the repository manually, - push a branch to origin and then use `flux bootstrap --branch=your-branch`. - For examples on how you can structure your Git repository see: * [flux2-kustomize-helm-example](https://github.com/fluxcd/flux2-kustomize-helm-example) @@ -102,6 +123,11 @@ For examples on how you can structure your Git repository see: ### 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 a 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) that can create repositories by checking all permissions under `repo`. @@ -166,6 +192,11 @@ flux bootstrap github \ ### 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 a 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. @@ -274,162 +305,6 @@ 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`. -### Generic Git Server - -For other Git providers such as Bitbucket, Gogs, Gitea, Azure DevOps, etc -you can manually setup the repository and deploy key. - -Create a Git repository and clone it locally: - -```sh -git clone ssh:////my-repository -cd my-repository -``` - -Create a directory inside the repository: - -```sh -mkdir -p ./clusters/my-cluster/flux-system -``` - -Generate the Flux manifests with: - -```sh -flux install \ - --export > ./clusters/my-cluster/flux-system/gotk-components.yaml -``` - -Commit and push the manifest to the master branch: - -```sh -git add -A && git commit -m "add components" && git push -``` - -Apply the manifests on your cluster: - -```sh -kubectl apply -f ./clusters/my-cluster/flux-system/gotk-components.yaml -``` - -Verify that the controllers have started: - -```sh -flux check -``` - -Create a `GitRepository` object on your cluster by specifying the SSH address of your repo: - -```sh -flux create source git flux-system \ - --url=ssh://git@// \ - --ssh-key-algorithm=ecdsa \ - --ssh-ecdsa-curve=p521 \ - --branch=master \ - --interval=1m -``` - -You will be prompted to add a deploy key to your repository. -If you don't specify the SSH algorithm, then `flux` will generate an RSA 2048 bits key. - -!!! hint "Azure DevOps" - Azure DevOps requires a non-default Git implementation (`libgit2`) to be enabled, so that the Git v2 protocol is supported. - Note that this implementation does not support shallow cloning, and it is therefore advised to only resort to this option if a - connection fails with the default configuration. - - Azure DevOps [only supports RSA SSH keys](https://developercommunity.visualstudio.com/t/support-non-rsa-keys-for-ssh-authentication/365980), - you cannot use elliptic curve SSH keys like ecdsa or ed25519. - - Here is how to specify the `libgit2` implementation and generate a proper RSA key: - - ```sh - flux create source git flux-system \ - --git-implementation=libgit2 \ - --ssh-key-algorithm=rsa \ - --ssh-rsa-bits=4096 \ - --url=ssh://git@ssh.dev.azure.com/v3/// \ - --branch=main \ - --interval=1m - ``` - - This config uses the `main` branch, but your repo may be older and need to specify `master` instead. - - Note that 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`. - - The `flux create source git` command 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 being mindful that removing them from the repo may revoke Flux's access. - As an alternative, 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 that is needed. - - If you wish to use Git over HTTPS, then generate a personal access token and supply it as the password: - - ```sh - flux create source git flux-system \ - --git-implementation=libgit2 \ - --url=https://dev.azure.com///_git/ \ - --branch=master \ - --username=git \ - --password=${AZ_PAT_TOKEN} \ - --interval=1m - ``` - - 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. - -If your Git server supports basic auth, you can set the URL to HTTPS and specify the credentials with: - -```sh -flux create source git flux-system \ - --url=https:////my-repository \ - --username=my-username \ - --password=my-password \ - --branch=master \ - --interval=1m -``` - -Create a `Kustomization` object on your cluster: - -```sh -flux create kustomization flux-system \ - --source=flux-system \ - --path="./clusters/my-cluster" \ - --prune=true \ - --interval=10m -``` - -Export both objects, generate a `kustomization.yaml`, commit and push the manifests to Git: - -```sh -flux export source git flux-system \ - > ./clusters/my-cluster/flux-system/gotk-sync.yaml - -flux export kustomization flux-system \ - >> ./clusters/my-cluster/flux-system/gotk-sync.yaml - -cd ./clusters/my-cluster/flux-system && kustomize create --autodetect - -git add -A && git commit -m "add sync manifests" && git push -``` - -To upgrade the Flux components to a newer version, download the latest `flux` binary, -run the install command and commit the changes: - -```sh -flux install \ - --export > ./clusters/my-cluster/flux-system/gotk-components.yaml - -git add -A && git commit -m "update flux" && git push -``` - -The source-controller will pull the changes on the cluster, then the kustomize-controller -will perform a rolling update of all Flux components including itself. - ## Bootstrap with Terraform The bootstrap procedure can be implemented with Terraform using the Flux provider published on diff --git a/docs/use-cases/azure.md b/docs/use-cases/azure.md index 9e01ff1b..62b48e96 100644 --- a/docs/use-cases/azure.md +++ b/docs/use-cases/azure.md @@ -6,9 +6,10 @@ 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. +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. @@ -21,24 +22,23 @@ Depending on the features you are interested in using with Flux, you may want to 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. +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. +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. !!! note 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. + 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. ### Cluster Creation -!!! 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` - The following creates an AKS cluster with some minimal configuration that will work well with Flux: ```sh @@ -50,10 +50,14 @@ az aks create \ --name="my-cluster" ``` +!!! 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`. + ## Flux Installation with Azure DevOps Repos Ensure you can login to [dev.azure.com](https://dev.azure.com) for your proper organization, -and create a new repo to hold your Flux install and other necessary config. +and create a new repository to hold your Flux install and other Kubernetes resources. Clone the Git repository locally: @@ -98,28 +102,27 @@ Create a `GitRepository` object on your cluster by specifying the SSH address of ```sh flux create source git flux-system \ --git-implementation=libgit2 \ + --url=ssh://git@ssh.dev.azure.com/v3/// \ + --branch= \ --ssh-key-algorithm=rsa \ --ssh-rsa-bits=4096 \ - --url=ssh://git@ssh.dev.azure.com/v3/// \ - --branch=main \ --interval=1m ``` -This config uses the `main` branch, but your repo may be older and need to specify `master` instead. - -Note that 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`. - -You will be prompted to add a deploy key to your repository. -If you don't specify the SSH algorithm, then `flux` will generate an RSA 2048 bits key. - -The `flux create source git` command will prompt you to add a deploy key to your repository, but Azure DevOps +The above command 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 being mindful that removing them from the repo may revoke Flux's access. -As an alternative, 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 that is needed. +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. + +!!! note + 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`. If you wish to use Git over HTTPS, then generate a personal access token and supply it as the password: @@ -127,7 +130,7 @@ If you wish to use Git over HTTPS, then generate a personal access token and sup flux create source git flux-system \ --git-implementation=libgit2 \ --url=https://dev.azure.com///_git/ \ - --branch=master \ + --branch=main \ --username=git \ --password=${AZ_PAT_TOKEN} \ --interval=1m @@ -163,30 +166,35 @@ cd ./clusters/my-cluster/flux-system && kustomize create --autodetect git add -A && git commit -m "add sync manifests" && git push ``` +### Flux Upgrade + To upgrade the Flux components to a newer version, download the latest `flux` binary, -run the install command and commit the changes: +run the install command in your repository root, commit and push the changes: ```sh flux install \ --export > ./clusters/my-cluster/flux-system/gotk-components.yaml -git add -A && git commit -m "update flux" && git push +git add -A && git commit -m "Upgrade to $(flux -v)" && git push ``` -The source-controller will pull the changes on the cluster, then the kustomize-controller +The [source-controller](../components/source/controller.md) will pull the changes on the cluster, +then [kustomize-controller](../components/source/controller.md) will perform a rolling update of all Flux components including itself. ## Helm Repositories on Azure Container Registry -The Flux `HelmRepository` object currently supports [Chart Repositories](https://helm.sh/docs/topics/chart_repository/) +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. +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. -[Newer ACR Helm documentation](https://docs.microsoft.com/en-us/azure/container-registry/container-registry-helm-repos) suggests -using ACR as an experimental [Helm OCI Registry](https://helm.sh/docs/topics/registries/). +[Newer ACR Helm documentation](https://docs.microsoft.com/en-us/azure/container-registry/container-registry-helm-repos) +suggests using ACR as an experimental [Helm OCI Registry](https://helm.sh/docs/topics/registries/). This will not work with Flux, because using Charts from OCI Registries is not yet supported. ## Secrets Management with SOPS and Azure Key Vault @@ -214,5 +222,6 @@ flux install \ Follow the [Image Update Automation Guide](../guides/image-update.md) and see the [ACR specific section](../guides/image-update.md#azure-container-registry) for more details. -Your AKS cluster's configuration can also be updated to [allow the kubelets to pull images from ACR](https://docs.microsoft.com/en-us/azure/aks/cluster-container-registry-integration) +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. From 719ef3c44c5bc789df84159b35a57f1131a7e3f7 Mon Sep 17 00:00:00 2001 From: Stefan Prodan Date: Wed, 7 Apr 2021 20:31:02 +0300 Subject: [PATCH 3/6] Add flux CLI container image to docs Signed-off-by: Stefan Prodan --- README.md | 5 +++++ docs/guides/installation.md | 26 +++++++++++++++----------- docs/use-cases/azure.md | 10 ++++++++-- 3 files changed, 28 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index e0c3324b..e59111ff 100644 --- a/README.md +++ b/README.md @@ -49,6 +49,11 @@ Arch Linux (AUR) packages: Binaries for macOS, Windows and Linux AMD64/ARM are available to download on the [release page](https://github.com/fluxcd/flux2/releases). +A container image with `kubectl` and `flux` is available on Docker Hub and GitHub: + +* `docker.io/fluxcd/flux-cli:` +* `ghcr.io/fluxcd/flux-cli:` + Verify that your cluster satisfies the prerequisites with: ```sh diff --git a/docs/guides/installation.md b/docs/guides/installation.md index 6ff8a795..9db002b1 100644 --- a/docs/guides/installation.md +++ b/docs/guides/installation.md @@ -31,6 +31,11 @@ are also supported with their own sub-commands. Binaries for macOS, Windows and Linux AMD64/ARM are available for download on the [release page](https://github.com/fluxcd/flux2/releases). +A container image with `kubectl` and `flux` is available on DockerHub and GitHub: + +* `docker.io/fluxcd/flux-cli:` +* `ghcr.io/fluxcd/flux-cli:` + Verify that your cluster satisfies the prerequisites with: ```sh @@ -46,10 +51,16 @@ 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. -!!! hint "Multi-arch images" - The component images are published as [multi-arch container images](https://docs.docker.com/docker-for-mac/multi-arch/) - with support for Linux `amd64`, `arm64` and `armv7` (e.g. 32bit Raspberry Pi) - architectures. +The 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 **GitHub**, **GitLab** or **Azure DevOps** please follow the specific bootstrap procedure: + +* [GitHub.com and GitHub Enterprise](#github-and-github-enterprise) +* [GitLab.com and GitLab Enterprise](#gitlab-and-gitlab-enterprise) +* [Azure DevOps](../use-cases/azure.md#flux-installation-for-azure-devops) ### Generic Git Server @@ -91,13 +102,6 @@ flux bootstrap git \ If your Git server uses a self-signed TLS certificate, you can specify the CA file with `--ca-file=`. -If you wish to install a specific version, use the Flux -[release tag](https://github.com/fluxcd/flux2/releases) e.g. `--version=v0.12.0`. - -If you wish to deploy the Flux components onto -[tainted Kubernetes nodes](https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration/), -you can specify the toleration keys with `--toleration-keys=node.kubernetes.io/dedicated-to-flux`. - With `--path` you can configure the directory which will be used to reconcile the target cluster. To control multiple clusters from the same Git repository, you have to set a unique path per cluster e.g. `clusters/staging` and `clusters/production`: diff --git a/docs/use-cases/azure.md b/docs/use-cases/azure.md index 62b48e96..e6ae6565 100644 --- a/docs/use-cases/azure.md +++ b/docs/use-cases/azure.md @@ -54,7 +54,7 @@ az aks create \ 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`. -## Flux Installation with Azure DevOps Repos +## Flux Installation for Azure DevOps 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. @@ -72,7 +72,7 @@ Create a directory inside the repository: mkdir -p ./clusters/my-cluster/flux-system ``` -Generate the Flux manifests with: +Download the [Flux CLI](../guides/installation.md#install-the-flux-cli) and generate the manifests with: ```sh flux install \ @@ -166,6 +166,12 @@ cd ./clusters/my-cluster/flux-system && kustomize create --autodetect git add -A && git commit -m "add sync manifests" && git push ``` +Wait for Flux to reconcile your previous commit with: + +```sh +watch flux get kustomization flux-system +``` + ### Flux Upgrade To upgrade the Flux components to a newer version, download the latest `flux` binary, From 1ea5d4d2e30f033233a60755c9c8973962e46103 Mon Sep 17 00:00:00 2001 From: Stefan Prodan Date: Thu, 8 Apr 2021 12:11:01 +0300 Subject: [PATCH 4/6] Remove sourceignore from SOPS guide No longer needed due to https://github.com/fluxcd/source-controller/pull/329 Signed-off-by: Stefan Prodan --- docs/guides/mozilla-sops.md | 12 +----------- 1 file changed, 1 insertion(+), 11 deletions(-) diff --git a/docs/guides/mozilla-sops.md b/docs/guides/mozilla-sops.md index 6877b7d8..4f3449a6 100644 --- a/docs/guides/mozilla-sops.md +++ b/docs/guides/mozilla-sops.md @@ -143,23 +143,13 @@ Multiple directories can use separate SOPS configs. Contributors using the `sops` CLI to create and encrypt files won't have to worry about specifying the proper key for the target cluster or namespace. -`encrypted_regex` helps encrypt the the proper `data` and `stringData` fields for Secrets. +`encrypted_regex` helps encrypt the `data` and `stringData` fields for Secrets. You may wish to add other fields if you are encrypting other types of Objects. !!! hint Note that you should encrypt only the `data` or `stringData` section. Encrypting the Kubernetes secret metadata, kind or apiVersion is not supported by kustomize-controller. -Ignore all `.sops.yaml` files in a [`.sourceignore`](../components/source/gitrepositories#excluding-files) -file at the root of your repo. - -```sh -touch .sourceignore -echo '**/.sops.yaml' >> .sourceignore -``` - -You can now commit your SOPS config. - ## Encrypt secrets Generate a Kubernetes secret manifest with kubectl: From 65d5cadf293663662a756cbbb34d2739508045ab Mon Sep 17 00:00:00 2001 From: Stefan Prodan Date: Thu, 8 Apr 2021 12:15:29 +0300 Subject: [PATCH 5/6] Update the alert providers list in notifications guide Signed-off-by: Stefan Prodan --- docs/guides/notifications.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/notifications.md b/docs/guides/notifications.md index 98398540..37186d5b 100644 --- a/docs/guides/notifications.md +++ b/docs/guides/notifications.md @@ -45,7 +45,7 @@ spec: name: slack-url ``` -The provider type can be `slack`, `msteams`, `discord`, `rocket`, `github`, `gitlab` or `generic`. +The provider type can be `slack`, `msteams`, `discord`, `rocket`, `googlechat`, `webex`, `sentry` or `generic`. When type `generic` is specified, the notification controller will post the incoming [event](../components/notification/event.md) in JSON format to the webhook address. From a58c40f2d7c8b41da24bf7a3708016fd9032ddc1 Mon Sep 17 00:00:00 2001 From: Stefan Prodan Date: Thu, 8 Apr 2021 14:06:42 +0300 Subject: [PATCH 6/6] Add note about providing a SSH key to bootstrap Signed-off-by: Stefan Prodan --- docs/guides/installation.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/guides/installation.md b/docs/guides/installation.md index 9db002b1..086764ea 100644 --- a/docs/guides/installation.md +++ b/docs/guides/installation.md @@ -80,8 +80,9 @@ flux bootstrap git \ The above command will generate a SSH key (defaults to RSA 2048 but can be changed with `--ssh-key-algorithm`), and it will prompt you to add the SSH public key as a deploy key to your repository. -If SSH agent is not available on your machine, you can provide a **passwordless** private key using +If you want to use your own SSH key, you can provide a **passwordless** private key using `--private-key-file=`. +This option can also be used if no SSH agent is available on your machine. !!! hint "Bootstrap options" There are many options available when bootstrapping Flux, such as installing a subset of Flux components,