Merge pull request #246 from SovereignCloudStack/245-update-docs-for-…

…use-in-docsscscommunity

📖 Update docs for use in docs.scs.community

docs/architecture/overview.md

@@ -1,12 +1,14 @@
-# Architecture
+# Overview
+
+## Architecture
 
 ![Cluster Stacks](../pics/syself-cluster-stacks-web.png)
 
 ## Cluster stacks
 
 The cluster stacks are opinionated templates of clusters in which all configuration and all core components are defined. They can be implemented on any provider.
 
-There can be multiple cluster stacks that acknowledge the many ways in which a cluster can be set up. There is no right or wrong and cluster stacks make sure that the flexibility is not lost. 
+There can be multiple cluster stacks that acknowledge the many ways in which a cluster can be set up. There is no right or wrong and cluster stacks make sure that the flexibility is not lost.
 
 At the same time, they offer ready-made templates for users, who do not have to spend a lot of thought on how to build clusters so that everything works well together.
 
@@ -20,23 +22,23 @@ To sum up, there are three components of a cluster stack:
 2. Cluster API objects: The `ClusterClass` object makes it easier to use Cluster-API. The cluster stack contains a `ClusterClass` object and other Cluster-API objects that are necessary in order to use the `ClusterClass`. These objects have to be applied in the management cluster.
 3. Node images: Node images can be provided to the user in different form. They are released and tested together with the other two components of the cluster stack.
 
-More information about cluster stacks and their three parts can be found in https://github.com/SovereignCloudStack/cluster-stacks/blob/main/README.md. 
+More information about cluster stacks and their three parts can be found in https://github.com/SovereignCloudStack/cluster-stacks/blob/main/README.md.
 
 ## Cluster Stack Operator
 
 The Cluster Stack Operator takes care of all steps that have to be done in order to use a certain cluster stack implementation.
 
-It has to be installed in the management cluster and can be interacted with by applying custom resources. It extends the functionality of the Cluster API operators. 
+It has to be installed in the management cluster and can be interacted with by applying custom resources. It extends the functionality of the Cluster API operators.
 
 The Cluster Stack Operator mainly applies the two Helm charts from a cluster stack implementation. It is also able to automatically fetch a remote Github repository to see whether there are new releases of a certain cluster stack.
 
-The first and second component of a cluster stack are handled by the Cluster Stack Operator. 
+The first and second component of a cluster stack are handled by the Cluster Stack Operator.
 
 The node images, on the other hand, have to be handled by separate provider integrations, similar to the ones that [Cluster-API uses](https://cluster-api.sigs.k8s.io/developer/providers/implementers-guide/overview).
 
 ## Cluster Stack Provider Integrations
 
-The Cluster Stack Operator is accompanied by Cluster Stack Provider Integrations. A provider integration is also an operator that works together with the Cluster Stack Operator in a specific way, which is described in the docs about building [provider integrations](../develop/provider-integration.md). 
+The Cluster Stack Operator is accompanied by Cluster Stack Provider Integrations. A provider integration is also an operator that works together with the Cluster Stack Operator in a specific way, which is described in the docs about building [provider integrations](../develop/provider-integration.md).
 
 A provider integration makes sure that the node images are taken care of and made available to the user.
 
@@ -46,7 +48,7 @@ If there is no work to be done for node images, then the Cluster Stack Operator
 
 There are many steps that are needed in order to make cluster stacks ready to use. In order to understand the full flow better and to get an idea of how much work there is and how many personas are involved, we will give an overview of how to start from scratch with a new cluster stack and provider.
 
-We will assume that this operator exists, but that you want to use a new cluster stack and provider. 
+We will assume that this operator exists, but that you want to use a new cluster stack and provider.
 
 ### Defining a cluster stack
 
@@ -58,8 +60,8 @@ The next step is to implement your cluster stack for your provider. You can take
 
 ### Implementing a Cluster Stack Provider Integration
 
-We assume that you need to do some manual tasks in order to make node images accessible on your provider. These steps should be implemented in a Cluster Stack Provider Integration, which of course has to work together with the details of how you implemented your cluster stack. 
+We assume that you need to do some manual tasks in order to make node images accessible on your provider. These steps should be implemented in a Cluster Stack Provider Integration, which of course has to work together with the details of how you implemented your cluster stack.
 
 ### Using everything
 
-Finally, you can use the new cluster stack you defined and implemented on the infrastructure of your provider. Enjoy!
+Finally, you can use the new cluster stack you defined and implemented on the infrastructure of your provider. Enjoy!

docs/develop/develop.md

@@ -1,7 +1,9 @@
-# Develop Cluster Stack Operator
+# Contributing
 
+## Develop Cluster Stack Operator
 
-Developing our operator is quite easy. First, you need to install some base requirements: Docker and Go. Second, you need to configure your environment variables. Then you can start developing with the local Kind cluster and the Tilt UI to create a workload cluster that is already pre-configured. 
+
+Developing our operator is quite easy. First, you need to install some base requirements: Docker and Go. Second, you need to configure your environment variables. Then you can start developing with the local Kind cluster and the Tilt UI to create a workload cluster that is already pre-configured.
 
 ## Setting Tilt up
 1. Install Docker and Go. We expect you to run on a Linux OS.
@@ -10,8 +12,8 @@ Developing our operator is quite easy. First, you need to install some base requ
 ## Developing with Tilt
 
 <p align="center">
-<img alt="tilt" src="./docs/pics/tilt.png" width=800px/>
-</p> 
+<img alt="tilt" src="./docs/pics/tilt.png" width="800px" />
+</p>
 
 Operator development requires a lot of iteration, and the “build, tag, push, update deployment” workflow can be very tedious. Tilt makes this process much simpler by watching for updates and automatically building and deploying them. To build a kind cluster and to start Tilt, run:
 
@@ -23,7 +25,7 @@ make tilt-up
 
 You should make sure that everything in the UI looks green. If not, e.g. if the clusterstack has not been synced, you can trigger the Tilt workflow again. In case of the clusterstack button this might be necessary, as it cannot be applied right after startup of the cluster and fails. Tilt unfortunately does not include a waiting period.
 
-If everything is green, then you can already check for your clusterstack that has been deployed. You can use a tool like k9s to have a look at the management cluster and its custom resources. 
+If everything is green, then you can already check for your clusterstack that has been deployed. You can use a tool like k9s to have a look at the management cluster and its custom resources.
 
 Example:
 
@@ -47,12 +49,12 @@ In case you want to change some code, you can do so and see that Tilt triggers o
 
 If you want to change something in your ClusterStack or Cluster custom resources, you can have a look at `.cluster.yaml` and `.clusterstack.yaml`, which Tilt uses.
 
-To tear down the workload cluster press the "Delete Workload Cluster" button. After a few minutes the resources should be deleted. 
+To tear down the workload cluster press the "Delete Workload Cluster" button. After a few minutes the resources should be deleted.
 
 To tear down the kind cluster, use:
 
 ```shell
 $ make delete-bootstrap-cluster
 ```
 
-If you have any trouble finding the right command, then you can use `make help` to get a list of all available make targets. 
+If you have any trouble finding the right command, then you can use `make help` to get a list of all available make targets.

docs/reference/clusterstack.md

@@ -1,16 +1,16 @@
 ## ClusterStack
 
-The `ClusterStack` object is the main resource for users to work with. It contains the most important details of a cluster stack and its releases (i.e. certain versions). In its status is the main source of information of the state of everything related to cluster stacks. 
+The `ClusterStack` object is the main resource for users to work with. It contains the most important details of a cluster stack and its releases (i.e. certain versions). In its status is the main source of information of the state of everything related to cluster stacks.
 
 
 
 ### Lifecycle of a ClusterStack
 
 The `ClusterStack` object has a sub-resource `ClusterStackRelease` for every release that should be provided to the user, either by specifying them manually in the versions array, or automatically through the auto-subscribe functionality.
 
-The controller reconciles the two sources of information and checks whether for every release that should exist, there is actually one. It also deletes `ClusterStackRelease` objects that are not required anymore. 
+The controller reconciles the two sources of information and checks whether for every release that should exist, there is actually one. It also deletes `ClusterStackRelease` objects that are not required anymore.
 
-Additionally, it fetches information from the `ClusterStackRelease` objects and populates its own state with it. 
+Additionally, it fetches information from the `ClusterStackRelease` objects and populates its own state with it.
 
 In case that a provider integration is used, it will create `ProviderClusterStackRelease` objects in addition to `ClusterStackRelease` objects, based on the `ProviderClusterStackReleaseTemplate` objects given as reference in `spec.providerRef`.
 
@@ -21,7 +21,7 @@ In case that a provider integration is used, it will create `ProviderClusterStac
 | ------------------------ | --------- | ------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | provider                 | string       |         | yes      | Name of the provider, e.g. "docker". It is used in various places, e.g. while fetching the respective release assets or while naming resources (ClusterStackReleases, ProviderClusterStackResources, etc.).|
 | name          | string    |         | yes       | Name of the cluster stack. It is used as well for fetching release assets and other tasks. |
-| kubernetesVersion      | string    |         | yes      | Kubernetes version in the format '<majorVersion>.<minorVersion>', e.g. 1.26. Specifies the Kubernetes minor version of the cluster stack that should be taken.|
+| kubernetesVersion      | string    |         | yes      | Kubernetes version in the format `<majorVersion>.<minorVersion>`, e.g. 1.26. Specifies the Kubernetes minor version of the cluster stack that should be taken.|
 | channel     | string    | stable         | no       | Name of release channel that is used, e.g. stable channel ("v1", "v2", etc.) or beta channel (e.g. "v0-beta.1").|
 | versions | []string |         | no       | List of versions that the controller should make available of a cluster stack. Used only in case very specific versions are supposed to be used. Not required if always the latest versions should be made available. |
 | autoSubscribe              | bool    | true        | no       | Specifies whether the controller should automatically check whether there are new releases of the cluster stack and if so automatically download them. |
@@ -45,4 +45,4 @@ spec:
   channel: stable
   autoSubscribe: true
   noProvider: true
-```
+```

docs/topics/troubleshoot.md

@@ -1,5 +1,4 @@
-
-## Troubleshooting
+# Troubleshooting
 
 Check the latest events:
 
@@ -10,7 +9,7 @@ kubectl get events -A  --sort-by=.lastTimestamp
 Check the conditions:
 
 ```shell
-go run github.com/guettli/check-conditions@latest all 
+go run github.com/guettli/check-conditions@latest all
 ```
 
 Check with `clusterctl`: