diff --git a/docs/guides/flux-v1-migration.md b/docs/guides/flux-v1-migration.md new file mode 100644 index 00000000..48168a6c --- /dev/null +++ b/docs/guides/flux-v1-migration.md @@ -0,0 +1,315 @@ +# Migrate from Flux v1 to v2 + +This guide walks you through migrating from Flux v1 to v2. +Read the [FAQ](../faq/index.md) to find out what differences are between v1 and v2. + +!!! info "Automated image updates" + The image automation feature is under development in Flux v2. + Please consult the [roadmap](../roadmap/index.md) for more details. + +## Prerequisites + +You will need a Kubernetes cluster version **1.16** or newer +and kubectl version **1.18** or newer. + +### Install Flux v2 CLI + +With Homebrew: + +```sh +brew install fluxcd/tap/flux +``` + +With Bash: + +```sh +curl -s https://toolkit.fluxcd.io/install.sh | sudo bash + +# enable completions in ~/.bash_profile +. <(flux completion bash) +``` + +Command-line completion for `zsh`, `fish`, and `powershell` +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). + +Verify that your cluster satisfies the prerequisites with: + +```sh +flux check --pre +``` + +## GitOps migration + +Flux v2 offers an installation procedure that is declarative first +and disaster resilient. + +Using the `flux bootstrap` command you can install Flux on a +Kubernetes cluster and configure it to manage itself from a Git +repository. The Git repository created during bootstrap can be used +to define the state of your fleet of Kubernetes clusters. + +For a detailed walk-through of the bootstrap procedure please see the [installation guide](installation.md). + +After you've installed Flux v2 on your cluster using bootstrap, +you can delete the Flux v1 from your clusters and move the manifests from the +Flux v1 repository to the bootstrap one. + +## In-place migration + +!!! warning + For production use we recommend using the **bootstrap** procedure, + but if you wish to install Flux v2 in the + same way as Flux v1 then follow along. + +### Flux read-only mode + +Assuming you've installed Flux v1 to sync a directory with plain YAMLs from a private Git repo: + +```sh +# create namespace +kubectl create ns flux + +# deploy Flux v1 +fluxctl install \ +--git-url=git@github.com:org/app \ +--git-branch=main \ +--git-path=./deploy \ +--git-readonly \ +--namespace=flux | kubectl apply -f - + +# print deploy key +fluxctl identity --k8s-fwd-ns flux + +# trigger sync +fluxctl sync --k8s-fwd-ns flux +``` + +!!! hint "Uninstall Flux v1" + Before you proceed, scale the Flux v1 deployment to zero + or delete its namespace and RBAC. + +If there are YAML files in your `deploy` dir that are not meant to be +applied on the cluster, you can exclude them by placing a `.sourceignore` in your repo root: + +```console +$ cat .sourceignore +# exclude all +/* +# include deploy dir +!/deploy +# exclude files from deploy dir +/deploy/**/eksctl.yaml +/deploy/**/charts +``` + +Install Flux v2 in the `flux-system` namespace: + +```console +$ flux install \ + --arch=amd64 \ + --network-policy=true \ + --watch-all-namespaces=true \ + --namespace=flux-systen +✚ generating manifests +✔ manifests build completed +► installing components in flux-system namespace +✔ install completed +◎ verifying installation +✔ source-controller ready +✔ kustomize-controller ready +✔ helm-controller ready +✔ notification-controller ready +✔ install finished +``` + +Register your Git repository and add the deploy key with read-only access: + +```console +$ flux create source git app \ + --url=ssh://git@github.com/org/app \ + --branch=main \ + --interval=1m +► generating deploy key pair +ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCp2x9ghVmv1zD... +Have you added the deploy key to your repository: y +► collecting preferred public key from SSH server +✔ collected public key from SSH server: +github.com ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEAq2A... +► applying secret with keys +✔ authentication configured +✚ generating GitRepository source +► applying GitRepository source +✔ GitRepository source created +◎ waiting for GitRepository source reconciliation +✔ GitRepository source reconciliation completed +✔ fetched revision: main/5302d04c2ab8f0579500747efa0fe7abc72c8f9b +``` + +Configure the reconciliation of the `deploy` dir on your cluster: + +```console +$ flux create kustomization app \ + --source=app \ + --path="./deploy" \ + --prune=true \ + --interval=10m +✚ generating Kustomization +► applying Kustomization +✔ Kustomization created +◎ waiting for Kustomization reconciliation +✔ Kustomization app is ready +✔ applied revision main/5302d04c2ab8f0579500747efa0fe7abc72c8f9b +``` + +If your repository contains secrets encrypted with Mozilla SOPS, please read this [guide](mozilla-sops.md). + +Pull changes from Git and apply them immediately: + +```sh +flux reconcile kustomization app --with-source +``` + +List all Kubernetes objects reconciled by `app`: + +```sh +kubectl get all --all-namespaces \ +-l=kustomize.toolkit.fluxcd.io/name=app \ +-l=kustomize.toolkit.fluxcd.io/namespace=flux-system +``` + +### Flux with Kustomize + +Assuming you've installed Flux v1 to sync a Kustomize overlay from an HTTPS Git repository: + +```sh +fluxctl install \ +--git-url=https://github.com/org/app \ +--git-branch=main \ +--manifest-generation \ +--namespace=flux | kubectl apply -f - +``` + +With the following `.flux.yaml` in the root dir: + +```yaml +version: 1 +patchUpdated: + generators: + - command: kustomize build ./overlays/prod + patchFile: flux-patch.yaml +``` + +!!! hint "Uninstall Flux v1" + Before you proceed, delete the Flux v1 namespace + and remove the `.flux.yaml` from your repo. + +Install Flux v2 in the `flux-system` namespace: + +```sh +flux install +``` + +Register the Git repository using a personal access token: + +```sh +flux create source git app \ + --url=https://github.com/org/app \ + --branch=main \ + --username=git \ + --password=token \ + --interval=1m +``` + +Configure the reconciliation of the `prod` overlay on your cluster: + +```sh +flux create kustomization app \ + --source=app \ + --path="./overlays/prod" \ + --prune=true \ + --interval=10m +``` + +Check the status of the Kustomization reconciliation: + +```console +$ flux get kustomizations app +NAME REVISION SUSPENDED READY +app main/5302d04c2ab8f0579500747efa0fe7abc72c8f9b False True +``` + +### Flux with Slack notifications + +Assuming you've configured Flux v1 to send notifications to Slack with FluxCloud. + +With Flux v2, create an alert provider for a Slack channel: + +```sh +flux create alert-provider slack \ + --type=slack \ + --channel=general \ + --address=https://hooks.slack.com/services/YOUR/SLACK/WEBHOOK +``` + +And configure notifications for the `app` reconciliation events: + +```sh +flux create alert app \ + --provider-ref=slack \ + --event-severity=info \ + --event-source=GitRepository/app \ + --event-source=Kustomization/app +``` + +For more details, read the guides on how to configure +[notifications](notifications.md) and [webhooks](webhook-receivers.md). + +### Flux debugging + +Check the status of Git operations: + +```console +$ kubectl -n flux-system get gitrepositories +NAME READY MESSAGE +app True Fetched revision: main/5302d04c2ab8f0579500747efa0fe7abc72c8f9b +test False SSH handshake failed: unable to authenticate, attempted methods [none publickey] +``` + +Check the status of the cluster reconciliation with kubectl: + +```console +$ kubectl -n flux-system get kustomizations +NAME READY STATUS +app True Applied revision: main/5302d04c2ab8f0579500747efa0fe7abc72c8f9 +test False The Service 'backend' is invalid: spec.type: Unsupported value: 'Ingress' +``` + +Suspend a reconciliation: + +```console +$ flux suspend kustomization app +► suspending kustomization app in flux-system namespace +✔ kustomization suspended +``` + +Check the status with kubectl: + +```console +$ kubectl -n flux-system get kustomization app +NAME READY STATUS +app False Kustomization is suspended, skipping reconciliation +``` + +Resume a reconciliation: + +```console +$ flux resume kustomization app +► resuming Kustomization app in flux-system namespace +✔ Kustomization resumed +◎ waiting for Kustomization reconciliation +✔ Kustomization reconciliation completed +✔ applied revision main/5302d04c2ab8f0579500747efa0fe7abc72c8f9b +``` diff --git a/docs/roadmap/index.md b/docs/roadmap/index.md index e283f752..390f4b5f 100644 --- a/docs/roadmap/index.md +++ b/docs/roadmap/index.md @@ -12,7 +12,7 @@ All of the above will constitute "Flux v2". ### Flux read-only feature parity -[= 90% "90%"] +[= 100% "100%"] This would be the first stepping stone: we want Flux v2 to be on-par with today's Flux in [read-only mode](https://github.com/fluxcd/flux/blob/master/docs/faq.md#can-i-run-flux-with-readonly-git-access) @@ -20,8 +20,8 @@ and [FluxCloud](https://github.com/justinbarrick/fluxcloud) notifications. Goals -- Offer a migration guide for those that are using Flux in read-only mode to synchronize plain manifests -- Offer a migration guide for those that are using Flux in read-only mode to synchronize Kustomize overlays +- :material-check-bold: [Offer a migration guide for those that are using Flux in read-only mode to synchronize plain manifests](https://toolkit.fluxcd.io/guides/flux-v1-migration/) +- :material-check-bold: [Offer a migration guide for those that are using Flux in read-only mode to synchronize Kustomize overlays](https://toolkit.fluxcd.io/guides/flux-v1-migration/) - :material-check-bold: [Offer a dedicated component for forwarding events to external messaging platforms](https://toolkit.fluxcd.io/guides/notifications/) Non-Goals @@ -38,7 +38,7 @@ Tasks - [x] Implement a notification controller for Slack, MS Teams, Discord, Rocket - [x] Implement Prometheus metrics in source and kustomize controllers - [x] Review the git source and kustomize APIs -- [ ] Create a migration guide for `flux.yaml` kustomize users +- [x] Create a migration guide for `flux.yaml` kustomize users - [x] Include support for SOPS ### Flux image update feature parity @@ -91,5 +91,5 @@ Tasks - [x] Implement conditional remediation on (failed) Helm actions - [x] Implement support for Helm charts from Git - [x] Implement support for referring to an alternative chart values file -- [ ] Stabilize API +- [x] Stabilize API - [ ] Create a migration guide for Helm Operator users diff --git a/mkdocs.yml b/mkdocs.yml index cc42f858..f336ba12 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -52,6 +52,7 @@ nav: - Monitoring with Prometheus: guides/monitoring.md - Sealed Secrets: guides/sealed-secrets.md - Mozilla SOPS: guides/mozilla-sops.md + - Migrate from Flux v1 to v2: guides/flux-v1-migration.md - Toolkit Components: - Source Controller: - Overview: components/source/controller.md @@ -140,8 +141,8 @@ nav: - Reconcile source helm: cmd/flux_reconcile_source_helm.md - Reconcile source bucket: cmd/flux_reconcile_source_bucket.md - Uninstall: cmd/flux_uninstall.md - - Roadmap: roadmap/index.md - - Contributing: contributing/index.md - Dev Guides: - Watching for source changes: dev-guides/source-watcher.md + - Roadmap: roadmap/index.md + - Contributing: contributing/index.md - FAQ: faq/index.md