Merge pull request #54 from fluxcd/docs-components

Add toolkit components to docs

.github/workflows/docs.yaml

@@ -15,6 +15,10 @@ jobs:
       - name: Copy assets
         run: |
           cp install/tk.sh docs/install.sh
+          curl https://raw.githubusercontent.com/fluxcd/source-controller/master/docs/api/source.md > docs/components/source/api.md
+          curl https://raw.githubusercontent.com/fluxcd/source-controller/master/docs/spec/v1alpha1/gitrepositories.md > docs/components/source/gitrepositories.md
+          curl https://raw.githubusercontent.com/fluxcd/kustomize-controller/master/docs/api/kustomize.md > docs/components/kustomize/api.md
+          curl https://raw.githubusercontent.com/fluxcd/kustomize-controller/master/docs/spec/v1alpha1/kustomization.md > docs/components/kustomize/kustomization.md
       - name: Deploy docs
         uses: mhausenblas/mkdocs-deploy-gh-pages@master
         env:

docs/components/kustomize/controller.md

@@ -0,0 +1,23 @@
+# Kustomize Controller
+
+The kustomize-controller is a Kubernetes operator,
+specialized in running continuous delivery pipelines for infrastructure and
+workloads defined with Kubernetes manifests and assembled with Kustomize.
+
+![](../../_files/kustomize-controller.png)
+
+Features:
+
+- Reconciles the cluster state from multiple sources (provided by source-controller)
+- Generates manifests with Kustomize (from plain Kubernetes yamls or Kustomize overlays)
+- Validates manifests against Kubernetes API
+- Impersonates service accounts (multi-tenancy RBAC)  
+- Health assessment of the deployed workloads
+- Runs pipelines in a specific order (depends-on relationship)
+- Prunes objects removed from source (garbage collection) 
+- Reports cluster state changes (Slack/Discord)
+
+Links:
+
+- Source code [fluxcd/kustomize-controller](https://github.com/fluxcd/kustomize-controller)
+- Specification [docs](https://github.com/fluxcd/kustomize-controller/tree/master/docs/spec)

docs/components/source/controller.md

@@ -0,0 +1,24 @@
+# Source Controller
+
+The main role of the source management component is to provide a common interface for artifacts acquisition.
+The source API defines a set of Kubernetes objects that cluster admins and various automated operators can
+interact with to offload the Git and Helm repositories operations to a dedicated controller.
+
+![](../../_files/source-controller.png)
+
+Features:
+
+- Validate source definitions
+- Authenticate to sources (SSH, user/password, API token)
+- Validate source authenticity (PGP)
+- Detect source changes based on update policies (semver)
+- Fetch resources on-demand and on-a-schedule
+- Package the fetched resources into a well-known format (tar.gz, yaml)
+- Make the artifacts addressable by their source identifier (sha, version, ts)
+- Make the artifacts available in-cluster to interested 3rd parties
+- Notify interested 3rd parties of source changes and availability (status conditions, events, hooks)
+
+Links:
+
+- Source code [fluxcd/source-controller](https://github.com/fluxcd/source-controller)
+- Specification [docs](https://github.com/fluxcd/source-controller/tree/master/docs/spec)

docs/index.md

@@ -9,12 +9,17 @@ cluster admins or by other automated tools.
 The GitOps Toolkit components interact with each other via Kubernetes
 events and are responsible for the reconciliation of their designated API objects. 
 
-![](diagrams/tk-overview.png)
+!!! hint "Work in Progress"
+    We envision a feature where **Flux v2** and **Helm Operator v2** will be assembled from
+    the GitOps Toolkit components. The Flux CD team is looking for feedback and help as 
+    the toolkit is in an active experimentation phase.
+    If you wish to take part in this quest please reach out to us on Slack and GitHub.
 
 Components:
 
 - [Toolkit CLI](https://github.com/fluxcd/toolkit)
-- [Source Controller](https://github.com/fluxcd/source-controller)
-- [Kustomize Controller](https://github.com/fluxcd/kustomize-controller)
+- [Source Controller](components/source/controller.md)
+- [Kustomize Controller](components/kustomize/controller.md)
 
 To get started with the toolkit please follow this [guide](get-started/index.md).
+

mkdocs.yml

@@ -37,6 +37,13 @@ markdown_extensions:
 nav:
   - Introduction: index.md
   - Get Started: get-started/index.md
+  - Toolkit Components:
+    - Source Controller: components/source/controller.md
+    - GitRepository CRD: components/source/gitrepositories.md
+    - Source API Reference: components/source/api.md
+    - Kustomize Controller: components/kustomize/controller.md
+    - Kustomization CRD: components/kustomize/kustomization.md
+    - Kustomize API Reference: components/kustomize/api.md
   - Toolkit CLI:
     - Bootstrap: cmd/tk_bootstrap.md
     - Check: cmd/tk_check.md