Merge pull request #10 from onmetal/documentation

Added overview documentation

.github/workflows/gh-pages.yml

@@ -58,6 +58,7 @@ jobs:
           version: v3.6.3
 
       - name: Run chart-releaser
+        if: ${{ github.event_name == 'push' }}
         uses: helm/[email protected]
         env:
           CR_TOKEN: "${{ secrets.GITHUB_TOKEN }}"

README.md

@@ -1,15 +1,15 @@
 # virtual-controlplane
 
+![Gardener on Metal Logo](docs/assets/logo.png)
+
 This project contains a collection of helm charts to deploy a virtual/nodeless Kubernetes API server.
 
-The API server can be deployed using various storage backends
+## Start using or developing the virual-controlplane locally
+
+For more details please check [documentation](https://onmetal.github.io/virtual-controlplane/) or the content in the `/docs` folder.
 
-* Etcd
-* Postgress
-* CockroachDB
+## Feedback and Support
 
-## Usage
+Feedback and contributions are always welcome!
 
-```shell
-helm repo add vc https://onmetal.github.io/virtual-controlplane/
-```
+In order to report bugs, submit suggestions or post questions please open a [Github issue](https://github.com/onmetal/virtual-controlplane/issues).

docs/index.md

@@ -1 +1,40 @@
-# Virtual Controlplane
+# Virtual Controlplane
+
+The project contains a collection of helm charts to deploy a virtual/nodeless [Kubernetes API server](https://kubernetes.io/docs/reference/command-line-tools-reference/kube-apiserver/).
+
+## Background
+
+Why do we need such a thing as a nodeless Kubernetes cluster?
+
+When developing a custom controlplane by [extending Kubernetes](https://kubernetes.io/docs/concepts/extend-kubernetes/) and using the [Operator Pattern](https://kubernetes.io/docs/concepts/extend-kubernetes/operator/) we typically might not be interested in objects like `Pods`, `Deployments` and others. The goal instead is to introduce new [CustomResourceDefinitions](https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/) on which our controllers will operate by leveraging the concepts the Kubernetes API machinery is offering us. 
+
+In order to do it, we will need certain things such as:
+
+- `etcd` server (ideally with a [backup and restore sidecar](https://github.com/gardener/etcd-backup-restore)[^1])
+- `kube-api-server` and `kube-controller-manager` 
+
+Since this Kubernetes API server setup does not have any nodes, we don't need to deploy the `kube-scheduler` as we won't be deploying any `Pods`.
+
+Those components can be easily deployed on an existing Kubernetes cluster[^2].
+
+![virtual controlplane](assets/vc.png)
+
+The figure above illustrates the core components which are deployed on a _vanilla_ Kubernetes runtime cluster.
+
+![virtual controlplane controller](assets/vc-controller.png)
+
+Your custom controllers can now also be deployed on the same (or different) runtime cluster as illustrated in the image above.
+
+## Advantages
+
+The main advantage of this approach is, that controllers and the content inside of virtual Kubernetes API server are no longer physically bound to the underlying runtime cluster as your CRDs are not mixed with content of the runtime clusters API server.
+
+Since the virtual controlplane in our scenario is just another workload running in a Kubernetes cluster, it can be moved and restored to a different cluster in case disaster strikes and the runtime cluster becomes unavailable.
+
+Another advantage is, that the performance of the virtual Kubernetes API server becomes a lot more predictable since nobody besides your controllers[^3] are working against it.
+
+[^1]: In our setup we are reusing the great work from the [Gardener](https://gardener.cloud/) project.
+[^2]: This can also be done on a classical virtual machine based setup.
+[^3]: And maybe the `kube-controller-manager`.
+
+--8<-- "hack/docs/abbreviations.md"

hack/docs/abbreviations.md

@@ -0,0 +1,7 @@
+*[CRD]: Custom Resource Definition
+*[CRDs]: Custom Resource Definitions
+*[CR]: Custom Resource
+*[CRs]: Custom Resources
+*[PR]: Pull Request
+*[PRs]: Pull Requests
+*[DCO]: Developer Certificate of Origin

mkdocs.yml

@@ -1,4 +1,4 @@
-site_name: OnMetal Virtual Controlplane
+site_name: Virtual Controlplane
 repo_url: https://github.com/onmetal/virtual-controlplane/
 edit_uri: edit/main/docs/
 theme:
@@ -29,14 +29,13 @@ markdown_extensions:
   - pymdownx.snippets
   - codehilite
   - admonition
+  - footnotes
   - abbr
   - toc:
       permalink: true
 
 nav:
   - Home: index.md
-  - Concepts: concept/index.md
-  - Architecture: architecture/index.md
   - Usage: usage/index.md
   - Developer Guide:
       - Local Setup: development/setup.md