From 107e7424d1cd0c9b0cdf015a49c5dbd3f5c34229 Mon Sep 17 00:00:00 2001
From: Michael Bridgen <michael@weave.works>
Date: Wed, 4 Nov 2020 14:08:40 +0000
Subject: [PATCH] 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 <michael@weave.works>
---
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.
-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.