diff --git a/docs/faq/index.md b/docs/faq/index.md index 5832d847..9749c3ba 100644 --- a/docs/faq/index.md +++ b/docs/faq/index.md @@ -253,93 +253,21 @@ when Bitnami publishes a new version of the metrics-server chart. ## Flux v1 vs v2 questions -### What does Flux v2 mean for Flux? +### What are the differences between v1 and v2? -Flux v1 is a monolithic do-it-all operator; Flux v2 separates the functionalities into specialized controllers, collectively called the GitOps Toolkit. +Flux v1 is a monolithic do-it-all operator; +Flux v2 separates the functionalities into specialized controllers, collectively called the GitOps Toolkit. -You can install and operate Flux v2 simply using the `flux` command. You can easily pick and choose the functionality you need and extend it to serve your own purposes. +You can find a detailed comparison of Flux v1 and v2 features in the [migration FAQ](../guides/faq-migration.md). -The timeline we are looking at right now is: +### How can I migrate from v1 to v2? -1. Put Flux v1 into maintenance mode (no new features being added; bugfixes and CVEs patched only). -1. Continue work on the [Flux v2 roadmap](https://toolkit.fluxcd.io/roadmap/). -1. We will provide transition guides for specific user groups, e.g. users of Flux v1 in read-only mode, or of Helm Operator v1, etc. once the functionality is integrated into Flux v2 and it's deemed "ready". -1. Once the use-cases of Flux v1 are covered, we will continue supporting Flux v1 for 6 months. This will be the transition period before it's considered unsupported. +The Flux community has created guides and example repositories +to help you migrate to Flux v2: -### Why did you rewrite Flux? - -Flux v2 implements its functionality in individual controllers, which allowed us to address long-standing feature requests much more easily. - -By basing these controllers on modern Kubernetes tooling (`controller-runtime` libraries), they can be dynamically configured with Kubernetes custom resources either by cluster admins or by other automated tools -- and you get greatly increased observability. - -This gave us the opportunity to build Flux v2 with the top Flux v1 feature requests in mind: - -- Supporting multiple source Git repositories -- Operational insight through health checks, events and alerts -- Multi-tenancy capabilities, like applying each source repository with its own set of permissions - -On top of that, testing the individual components and understanding the codebase becomes a lot easier. - -### What are significant new differences between Flux v1 and Flux v2? - -#### Reconciliation - -Flux v1 | Flux v2 ----------------------------------- | ---------------------------------- -Limited to a single Git repository | Multiple Git repositories -Declarative config via arguments in the Flux deployment | `GitRepository` custom resource, which produces an artifact which can be reconciled by other controllers -Follow `HEAD` of Git branches | Supports Git branches, pinning on commits and tags, follow SemVer tag ranges -Suspending of reconciliation by downscaling Flux deployment | Reconciliation can be paused per resource by suspending the `GitRepository` -Credentials config via Arguments and/or Secret volume mounts in the Flux pod | Credentials config per `GitRepository` resource: SSH private key, HTTP/S username/password/token, OpenPGP public keys - -#### `kustomize` support - -Flux v1 | Flux v2 ----------------------------------- | ---------------------------------- -Declarative config through `.flux.yaml` files in the Git repository | Declarative config through a `Kustomization` custom resource, consuming the artifact from the GitRepository -Manifests are generated via shell exec and then reconciled by `fluxd` | Generation, server-side validation, and reconciliation is handled by a specialised `kustomize-controller` -Reconciliation using the service account of the Flux deployment | Support for service account impersonation -Garbage collection needs cluster role binding for Flux to query the Kubernetes discovery API | Garbage collection needs no cluster role binding or access to Kubernetes discovery API -Support for custom commands and generators executed by fluxd in a POSIX shell | No support for custom commands - -#### Helm integration - -Flux v1 | Flux v2 ----------------------------------- | ---------------------------------- -Declarative config in a single Helm custom resource | Declarative config through `HelmRepository`, `GitRepository`, `Bucket`, `HelmChart` and `HelmRelease` custom resources -Chart synchronisation embedded in the operator | Extensive release configuration options, and a reconciliation interval per source -Support for fixed SemVer versions from Helm repositories | Support for SemVer ranges for `HelmChart` resources -Git repository synchronisation on a global interval | Planned support for charts from GitRepository sources -Limited observability via the status object of the HelmRelease resource | Better observability via the HelmRelease status object, Kubernetes events, and notifications -Resource heavy, relatively slow | Better performance -Chart changes from Git sources are determined from Git metadata | Chart changes must be accompanied by a version bump in `Chart.yaml` to produce a new artifact - -#### Notifications, webhooks, observability - -Flux v1 | Flux v2 ----------------------------------- | ---------------------------------- -Emits "custom Flux events" to a webhook endpoint | Emits Kubernetes events for included custom resources -RPC endpoint can be configured to a 3rd party solution like FluxCloud to be forwarded as notifications to e.g. Slack | Flux v2 components can be configured to POST the events to a `notification-controller` endpoint. Selective forwarding of POSTed events as notifications using `Provider` and `Alert` custom resources. -Webhook receiver is a side-project | Webhook receiver, handling a wide range of platforms, is included -Unstructured logging | Structured logging for all components -Custom Prometheus metrics | Generic / common `controller-runtime` Prometheus metrics - -### How can I get involved? - -There are a variety of ways and we look forward to having you on board building the future of GitOps together: - -- [Discuss the direction](https://github.com/fluxcd/flux2/discussions) of Flux v2 with us -- Join us in #flux-dev on the [CNCF Slack](https://slack.cncf.io) -- Check out our [contributor docs](https://toolkit.fluxcd.io/contributing/) -- Take a look at the [roadmap for Flux v2](https://toolkit.fluxcd.io/roadmap/) - -### Are there any breaking changes? - -- In Flux v1 Kustomize support was implemented through `.flux.yaml` files in the Git repository. As indicated in the comparison table above, while this approach worked, we found it to be error-prone and hard to debug. The new [Kustomization CR](https://github.com/fluxcd/kustomize-controller/blob/master/docs/spec/v1alpha1/kustomization.md) should make troubleshooting much easier. Unfortunately we needed to drop the support for custom commands as running arbitrary shell scripts in-cluster poses serious security concerns. -- Helm users: we redesigned the `HelmRelease` API and the automation will work quite differently, so upgrading to `HelmRelease` v2 will require a little work from you, but you will gain more flexibility, better observability and performance. - -### Is the GitOps Toolkit related to the GitOps Engine? - -In an announcement in August 2019, the expectation was set that the Flux project would integrate the GitOps Engine, then being factored out of ArgoCD. Since the result would be backward-incompatible, it would require a major version bump: Flux v2. - -After experimentation and considerable thought, we (the maintainers) have found a path to Flux v2 that we think better serves our vision of GitOps: the GitOps Toolkit. In consequence, we do not now plan to integrate GitOps Engine into Flux. +- [Migrate from Flux v1](https://toolkit.fluxcd.io/guides/flux-v1-migration/) +- [Migrate from `.flux.yaml` and kustomize](https://toolkit.fluxcd.io/guides/flux-v1-migration/) +- [Migrate from Flux v1 automated container image updates](https://toolkit.fluxcd.io/guides/flux-v1-automation-migration/) +- [How to manage multi-tenant clusters with Flux v2](https://github.com/fluxcd/flux2-multi-tenancy) +- [Migrate from Helm Operator to Flux v2](https://toolkit.fluxcd.io/guides/helm-operator-migration/) +- [How to structure your HelmReleases](https://github.com/fluxcd/flux2-kustomize-helm-example) diff --git a/docs/guides/faq-migration.md b/docs/guides/faq-migration.md new file mode 100644 index 00000000..2570be5f --- /dev/null +++ b/docs/guides/faq-migration.md @@ -0,0 +1,92 @@ +## Flux v1 vs v2 questions + +### What does Flux v2 mean for Flux? + +Flux v1 is a monolithic do-it-all operator; Flux v2 separates the functionalities into specialized controllers, collectively called the GitOps Toolkit. + +You can install and operate Flux v2 simply using the `flux` command. You can easily pick and choose the functionality you need and extend it to serve your own purposes. + +The timeline we are looking at right now is: + +1. Put Flux v1 into maintenance mode (no new features being added; bugfixes and CVEs patched only). +1. Continue work on the [Flux v2 roadmap](https://toolkit.fluxcd.io/roadmap/). +1. We will provide transition guides for specific user groups, e.g. users of Flux v1 in read-only mode, or of Helm Operator v1, etc. once the functionality is integrated into Flux v2 and it's deemed "ready". +1. Once the use-cases of Flux v1 are covered, we will continue supporting Flux v1 for 6 months. This will be the transition period before it's considered unsupported. + +### Why did you rewrite Flux? + +Flux v2 implements its functionality in individual controllers, which allowed us to address long-standing feature requests much more easily. + +By basing these controllers on modern Kubernetes tooling (`controller-runtime` libraries), they can be dynamically configured with Kubernetes custom resources either by cluster admins or by other automated tools -- and you get greatly increased observability. + +This gave us the opportunity to build Flux v2 with the top Flux v1 feature requests in mind: + +- Supporting multiple source Git repositories +- Operational insight through health checks, events and alerts +- Multi-tenancy capabilities, like applying each source repository with its own set of permissions + +On top of that, testing the individual components and understanding the codebase becomes a lot easier. + +### What are significant new differences between Flux v1 and Flux v2? + +#### Reconciliation + +Flux v1 | Flux v2 +---------------------------------- | ---------------------------------- +Limited to a single Git repository | Multiple Git repositories +Declarative config via arguments in the Flux deployment | `GitRepository` custom resource, which produces an artifact which can be reconciled by other controllers +Follow `HEAD` of Git branches | Supports Git branches, pinning on commits and tags, follow SemVer tag ranges +Suspending of reconciliation by downscaling Flux deployment | Reconciliation can be paused per resource by suspending the `GitRepository` +Credentials config via Arguments and/or Secret volume mounts in the Flux pod | Credentials config per `GitRepository` resource: SSH private key, HTTP/S username/password/token, OpenPGP public keys + +#### `kustomize` support + +Flux v1 | Flux v2 +---------------------------------- | ---------------------------------- +Declarative config through `.flux.yaml` files in the Git repository | Declarative config through a `Kustomization` custom resource, consuming the artifact from the GitRepository +Manifests are generated via shell exec and then reconciled by `fluxd` | Generation, server-side validation, and reconciliation is handled by a specialised `kustomize-controller` +Reconciliation using the service account of the Flux deployment | Support for service account impersonation +Garbage collection needs cluster role binding for Flux to query the Kubernetes discovery API | Garbage collection needs no cluster role binding or access to Kubernetes discovery API +Support for custom commands and generators executed by fluxd in a POSIX shell | No support for custom commands + +#### Helm integration + +Flux v1 | Flux v2 +---------------------------------- | ---------------------------------- +Declarative config in a single Helm custom resource | Declarative config through `HelmRepository`, `GitRepository`, `Bucket`, `HelmChart` and `HelmRelease` custom resources +Chart synchronisation embedded in the operator | Extensive release configuration options, and a reconciliation interval per source +Support for fixed SemVer versions from Helm repositories | Support for SemVer ranges for `HelmChart` resources +Git repository synchronisation on a global interval | Planned support for charts from GitRepository sources +Limited observability via the status object of the HelmRelease resource | Better observability via the HelmRelease status object, Kubernetes events, and notifications +Resource heavy, relatively slow | Better performance +Chart changes from Git sources are determined from Git metadata | Chart changes must be accompanied by a version bump in `Chart.yaml` to produce a new artifact + +#### Notifications, webhooks, observability + +Flux v1 | Flux v2 +---------------------------------- | ---------------------------------- +Emits "custom Flux events" to a webhook endpoint | Emits Kubernetes events for included custom resources +RPC endpoint can be configured to a 3rd party solution like FluxCloud to be forwarded as notifications to e.g. Slack | Flux v2 components can be configured to POST the events to a `notification-controller` endpoint. Selective forwarding of POSTed events as notifications using `Provider` and `Alert` custom resources. +Webhook receiver is a side-project | Webhook receiver, handling a wide range of platforms, is included +Unstructured logging | Structured logging for all components +Custom Prometheus metrics | Generic / common `controller-runtime` Prometheus metrics + +### Are there any breaking changes? + +- In Flux v1 Kustomize support was implemented through `.flux.yaml` files in the Git repository. As indicated in the comparison table above, while this approach worked, we found it to be error-prone and hard to debug. The new [Kustomization CR](https://github.com/fluxcd/kustomize-controller/blob/master/docs/spec/v1alpha1/kustomization.md) should make troubleshooting much easier. Unfortunately we needed to drop the support for custom commands as running arbitrary shell scripts in-cluster poses serious security concerns. +- Helm users: we redesigned the `HelmRelease` API and the automation will work quite differently, so upgrading to `HelmRelease` v2 will require a little work from you, but you will gain more flexibility, better observability and performance. + +### Is the GitOps Toolkit related to the GitOps Engine? + +In an announcement in August 2019, the expectation was set that the Flux project would integrate the GitOps Engine, then being factored out of ArgoCD. Since the result would be backward-incompatible, it would require a major version bump: Flux v2. + +After experimentation and considerable thought, we (the maintainers) have found a path to Flux v2 that we think better serves our vision of GitOps: the GitOps Toolkit. In consequence, we do not now plan to integrate GitOps Engine into Flux. + +### How can I get involved? + +There are a variety of ways and we look forward to having you on board building the future of GitOps together: + +- [Discuss the direction](https://github.com/fluxcd/flux2/discussions) of Flux v2 with us +- Join us in #flux-dev on the [CNCF Slack](https://slack.cncf.io) +- Check out our [contributor docs](https://toolkit.fluxcd.io/contributing/) +- Take a look at the [roadmap for Flux v2](https://toolkit.fluxcd.io/roadmap/) diff --git a/docs/guides/flux-v1-migration.md b/docs/guides/flux-v1-migration.md index 16836dea..0b89b9c9 100644 --- a/docs/guides/flux-v1-migration.md +++ b/docs/guides/flux-v1-migration.md @@ -1,7 +1,7 @@ # 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. +Read the [FAQ](faq-migration.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. @@ -125,7 +125,6 @@ Install Flux v2 in the `flux-system` namespace: ```console $ flux install \ - --arch=amd64 \ --network-policy=true \ --watch-all-namespaces=true \ --namespace=flux-system @@ -243,7 +242,7 @@ Configure the reconciliation of the `prod` overlay on your cluster: ```sh flux create kustomization app \ - --source=app \ + --source=GitRepository/app \ --path="./overlays/prod" \ --prune=true \ --interval=10m diff --git a/mkdocs.yml b/mkdocs.yml index ca41115b..5cbefe28 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -50,6 +50,7 @@ nav: - Migrate from Flux v1: guides/flux-v1-migration.md - Migrate from Flux v1 image update automation: guides/flux-v1-automation-migration.md - Migrate from the Helm Operator: guides/helm-operator-migration.md + - FAQ: guides/faq-migration.md - Guides: - Installation: guides/installation.md - Manage Helm Releases: guides/helmreleases.md