diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml index 0deb0910..c5a6f8b2 100644 --- a/.github/workflows/docs.yaml +++ b/.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: diff --git a/docs/_files/kustomize-controller.png b/docs/_files/kustomize-controller.png new file mode 100644 index 00000000..10a5e776 Binary files /dev/null and b/docs/_files/kustomize-controller.png differ diff --git a/docs/_files/source-controller.png b/docs/_files/source-controller.png new file mode 100644 index 00000000..6d4f4c7a Binary files /dev/null and b/docs/_files/source-controller.png differ diff --git a/docs/components/kustomize/controller.md b/docs/components/kustomize/controller.md new file mode 100644 index 00000000..af699231 --- /dev/null +++ b/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) diff --git a/docs/components/source/controller.md b/docs/components/source/controller.md new file mode 100644 index 00000000..fa4b8f00 --- /dev/null +++ b/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) \ No newline at end of file diff --git a/docs/index.md b/docs/index.md index bca35de7..876d6f6e 100644 --- a/docs/index.md +++ b/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). + diff --git a/mkdocs.yml b/mkdocs.yml index f03df7ba..e701e2c0 100644 --- a/mkdocs.yml +++ b/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