From c93181c0ad6c555cb6115b5dd2470eaab086e610 Mon Sep 17 00:00:00 2001 From: Michael Bridgen Date: Wed, 4 Nov 2020 13:37:01 +0000 Subject: [PATCH 1/4] Add section on target users Signed-off-by: Michael Bridgen --- docs/index.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/docs/index.md b/docs/index.md index 4160740d..1dfba9b3 100644 --- a/docs/index.md +++ b/docs/index.md @@ -14,6 +14,18 @@ Flux v2 is constructed with the [GitOps Toolkit](#gitops-toolkit), a set of composable APIs and specialized tools for building Continuous Delivery on top of Kubernetes. +## Who is Flux for? + +Flux helps + +- **cluster operators** who automate provision and configuration of clusters; +- **platform engineers** who build continuous delivery for developer teams; +- **app developers** who rely on continuous delivery to get their code live. + +The [GitOps Toolkit](#gitops-toolkit) is for **platform engineers** +who want to make their own continuous delivery system, and have +requirements not covered by Flux. + Features: - Source management (Git and Helm repositories, S3 compatible buckets) From 107e7424d1cd0c9b0cdf015a49c5dbd3f5c34229 Mon Sep 17 00:00:00 2001 From: Michael Bridgen Date: Wed, 4 Nov 2020 14:08:40 +0000 Subject: [PATCH 2/4] Explain more up-front in website homepage This commit - adds a brief explanation of what Flux does - makes the target features a little more self-explanatory - gives GitOps Toolkit its own index page Signed-off-by: Michael Bridgen --- docs/dev-guides/index.md | 27 +++++++++++++ docs/index.md | 83 ++++++++++++++++++---------------------- 2 files changed, 65 insertions(+), 45 deletions(-) create mode 100644 docs/dev-guides/index.md diff --git a/docs/dev-guides/index.md b/docs/dev-guides/index.md new file mode 100644 index 00000000..e91f878a --- /dev/null +++ b/docs/dev-guides/index.md @@ -0,0 +1,27 @@ +# GitOps Toolkit + +The GitOps Toolkit is the set of APIs and controllers that make up the +runtime for Flux v2. The APIs comprise Kubernetes custom resources, +which can be created and updated by a cluster user, or by other +automation tooling. + +You can use the toolkit to extend Flux, and to build your own systems +for continuous delivery. The [the source-watcher +guide](https://toolkit.fluxcd.io/dev-guides/source-watcher/) is a good +place to start. + +A reference for each component is linked below. + +- [Source Controller](../components/source/controller.md) + - [GitRepository CRD](../components/source/gitrepositories.md) + - [HelmRepository CRD](../components/source/helmrepositories.md) + - [HelmChart CRD](../components/source/helmcharts.md) + - [Bucket CRD](../components/source/buckets.md) +- [Kustomize Controller](../components/kustomize/controller.md) + - [Kustomization CRD](../components/kustomize/kustomization.md) +- [Helm Controller](../components/helm/controller.md) + - [HelmRelease CRD](../components/helm/helmreleases.md) +- [Notification Controller](../components/notification/controller.md) + - [Provider CRD](../components/notification/provider.md) + - [Alert CRD](../components/notification/alert.md) + - [Receiver CRD](../components/notification/receiver.md) diff --git a/docs/index.md b/docs/index.md index 1dfba9b3..4441c342 100644 --- a/docs/index.md +++ b/docs/index.md @@ -10,8 +10,8 @@ components of the Kubernetes ecosystem. In version 2, Flux supports multi-tenancy and support for syncing an arbitrary number of Git repositories, among other long-requested features. -Flux v2 is constructed with the [GitOps Toolkit](#gitops-toolkit), a -set of composable APIs and specialized tools for building Continuous +Flux v2 is constructed with the [GitOps Toolkit](dev-guides/index.md), +a set of composable APIs and specialized tools for building Continuous Delivery on top of Kubernetes. ## Who is Flux for? @@ -22,62 +22,55 @@ Flux helps - **platform engineers** who build continuous delivery for developer teams; - **app developers** who rely on continuous delivery to get their code live. -The [GitOps Toolkit](#gitops-toolkit) is for **platform engineers** -who want to make their own continuous delivery system, and have -requirements not covered by Flux. +The [GitOps Toolkit](dev-guides/index.md) is for **platform +engineers** who want to make their own continuous delivery system, and +have requirements not covered by Flux. -Features: +## What can I do with Flux? -- Source management (Git and Helm repositories, S3 compatible buckets) -- Kustomize and Helm support -- Event-based and on-a-schedule reconciliation -- Role-based reconciliation (multi-tenancy) -- Health assessment (clusters and workloads) -- Dependency management (infra and workloads) -- Alerting to external systems (webhook senders) -- External events handling (webhook receivers) -- Source write-back (automated patching) -- Policy driven validation (OPA, admission controllers) -- Seamless integration with Git providers (GitHub, GitLab, Bitbucket) -- Interoperability with workflow providers (GitHub Actions, Tekton, Argo) -- Interoperability with CAPI providers +Flux is based on a set of Kubernetes API extensions ("custom +resources"), which control how git repositories and other sources of +configuration are applied into the cluster ("synced"). +For example, you create a `GitRepository` object to mirror +configuration from a Git repository, then a `Kustomization` object to +sync that configuration. -## GitOps Toolkit +Flux works with Kubernetes' role-based access control (RBAC), so you +can lock down what any particular sync can change. It can send +notifications to Slack and other like systems when configuration is +synced and ready, and receive webhooks to tell it when to sync. -The GitOps Toolkit is the set of APIs and controllers that make up the -runtime for Flux v2. The APIs comprise Kubernetes custom resources, -which can be created and updated by a cluster user, or by other -automation tooling. +The `flux` command-line tool is a convenient way to bootstrap the +system in a cluster, and to access the custom resources that make up +the API. ![overview](diagrams/gitops-toolkit.png) -You can use the toolkit to extend Flux, or to build your own systems -for continuous delivery -- see [the developer -guides](https://toolkit.fluxcd.io/dev-guides/source-watcher/). - -Components: - -- [Source Controller](components/source/controller.md) - - [GitRepository CRD](components/source/gitrepositories.md) - - [HelmRepository CRD](components/source/helmrepositories.md) - - [HelmChart CRD](components/source/helmcharts.md) - - [Bucket CRD](components/source/buckets.md) -- [Kustomize Controller](components/kustomize/controller.md) - - [Kustomization CRD](components/kustomize/kustomization.md) -- [Helm Controller](components/helm/controller.md) - - [HelmRelease CRD](components/helm/helmreleases.md) -- [Notification Controller](components/notification/controller.md) - - [Provider CRD](components/notification/provider.md) - - [Alert CRD](components/notification/alert.md) - - [Receiver CRD](components/notification/receiver.md) - -## Get Started +## Where do I start? !!!hint "Get started with Flux v2!" Following this [guide](get-started/index.md) will just take a couple of minutes to complete: After installing the `flux` CLI and running a couple of very simple commands, you will have a GitOps workflow setup which involves a staging and a production cluster. +## More detail on what's in Flux + +Features: + +- Source management (Git and Helm repositories, S3 compatible buckets) +- Kustomize and Helm support +- Event-triggered and periodic reconciliation +- Integration with Kubernetes RBAC +- Health assessment (clusters and workloads) +- Dependency management (infrastructure and workloads) +- Alerting to external systems (webhook senders) +- External events handling (webhook receivers) +- Configuration update automation (automated patching) +- Policy-driven validation (OPA, admission controllers) +- Seamless integration with Git providers (GitHub, GitLab, Bitbucket) +- Interoperability with workflow providers (GitHub Actions, Tekton, Argo) +- Interoperability with Cluster API (CAPI) providers + ## Community The Flux project is always looking for new contributors and there are a multitude of ways to get involved. From 932c91d022ec335953db7cbe3a84a4de3f0376c3 Mon Sep 17 00:00:00 2001 From: Michael Bridgen Date: Wed, 4 Nov 2020 15:10:11 +0000 Subject: [PATCH 3/4] Move gitops toolkit index under components/ Signed-off-by: Michael Bridgen --- docs/components/index.md | 26 ++++++++++++++++++++++++++ docs/dev-guides/index.md | 27 --------------------------- docs/index.md | 4 ++-- mkdocs.yml | 1 + 4 files changed, 29 insertions(+), 29 deletions(-) create mode 100644 docs/components/index.md delete mode 100644 docs/dev-guides/index.md diff --git a/docs/components/index.md b/docs/components/index.md new file mode 100644 index 00000000..b32efa28 --- /dev/null +++ b/docs/components/index.md @@ -0,0 +1,26 @@ +# GitOps Toolkit components + +The GitOps Toolkit is the set of APIs and controllers that make up the +runtime for Flux v2. The APIs comprise Kubernetes custom resources, +which can be created and updated by a cluster user, or by other +automation tooling. + +You can use the toolkit to extend Flux, and to build your own systems +for continuous delivery. The [the source-watcher +guide](../dev-guides/source-watcher/) is a good place to start. + +A reference for each component and API type is linked below. + +- [Source Controller](source/controller.md) + - [GitRepository CRD](source/gitrepositories.md) + - [HelmRepository CRD](source/helmrepositories.md) + - [HelmChart CRD](source/helmcharts.md) + - [Bucket CRD](source/buckets.md) +- [Kustomize Controller](kustomize/controller.md) + - [Kustomization CRD](kustomize/kustomization.md) +- [Helm Controller](helm/controller.md) + - [HelmRelease CRD](helm/helmreleases.md) +- [Notification Controller](notification/controller.md) + - [Provider CRD](notification/provider.md) + - [Alert CRD](notification/alert.md) + - [Receiver CRD](notification/receiver.md) diff --git a/docs/dev-guides/index.md b/docs/dev-guides/index.md deleted file mode 100644 index e91f878a..00000000 --- a/docs/dev-guides/index.md +++ /dev/null @@ -1,27 +0,0 @@ -# GitOps Toolkit - -The GitOps Toolkit is the set of APIs and controllers that make up the -runtime for Flux v2. The APIs comprise Kubernetes custom resources, -which can be created and updated by a cluster user, or by other -automation tooling. - -You can use the toolkit to extend Flux, and to build your own systems -for continuous delivery. The [the source-watcher -guide](https://toolkit.fluxcd.io/dev-guides/source-watcher/) is a good -place to start. - -A reference for each component is linked below. - -- [Source Controller](../components/source/controller.md) - - [GitRepository CRD](../components/source/gitrepositories.md) - - [HelmRepository CRD](../components/source/helmrepositories.md) - - [HelmChart CRD](../components/source/helmcharts.md) - - [Bucket CRD](../components/source/buckets.md) -- [Kustomize Controller](../components/kustomize/controller.md) - - [Kustomization CRD](../components/kustomize/kustomization.md) -- [Helm Controller](../components/helm/controller.md) - - [HelmRelease CRD](../components/helm/helmreleases.md) -- [Notification Controller](../components/notification/controller.md) - - [Provider CRD](../components/notification/provider.md) - - [Alert CRD](../components/notification/alert.md) - - [Receiver CRD](../components/notification/receiver.md) diff --git a/docs/index.md b/docs/index.md index 4441c342..b82fa88b 100644 --- a/docs/index.md +++ b/docs/index.md @@ -10,7 +10,7 @@ components of the Kubernetes ecosystem. In version 2, Flux supports multi-tenancy and support for syncing an arbitrary number of Git repositories, among other long-requested features. -Flux v2 is constructed with the [GitOps Toolkit](dev-guides/index.md), +Flux v2 is constructed with the [GitOps Toolkit](components/index.md), a set of composable APIs and specialized tools for building Continuous Delivery on top of Kubernetes. @@ -22,7 +22,7 @@ Flux helps - **platform engineers** who build continuous delivery for developer teams; - **app developers** who rely on continuous delivery to get their code live. -The [GitOps Toolkit](dev-guides/index.md) is for **platform +The [GitOps Toolkit](components/index.md) is for **platform engineers** who want to make their own continuous delivery system, and have requirements not covered by Flux. diff --git a/mkdocs.yml b/mkdocs.yml index 9bcb799b..0bd48d2c 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -56,6 +56,7 @@ nav: - From Flux v1: guides/flux-v1-migration.md - From the Helm Operator: guides/helm-operator-migration.md - Toolkit Components: + - Overview: components/index.md - Source Controller: - Overview: components/source/controller.md - GitRepository CRD: components/source/gitrepositories.md From 71995b4f8361e812b37112dd3ae7fb5532fde8d3 Mon Sep 17 00:00:00 2001 From: Michael Bridgen Date: Wed, 4 Nov 2020 15:15:31 +0000 Subject: [PATCH 4/4] Refine description of Sources Signed-off-by: Michael Bridgen --- docs/index.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/index.md b/docs/index.md index b82fa88b..f721fb50 100644 --- a/docs/index.md +++ b/docs/index.md @@ -57,7 +57,8 @@ the API. Features: -- Source management (Git and Helm repositories, S3 compatible buckets) +- Source configuration from Git and Helm repositories, and + S3-compatible buckets (e.g., Minio) - Kustomize and Helm support - Event-triggered and periodic reconciliation - Integration with Kubernetes RBAC