From 18637bca662f9634ef70a17a8525d726083e75c6 Mon Sep 17 00:00:00 2001 From: Danny Eiselt Date: Wed, 21 Aug 2024 14:17:25 +0200 Subject: [PATCH 1/6] fixed: md formatting causing docs build to fail Signed-off-by: Danny Eiselt --- docs/preparing_your_clusterstack_directory.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/preparing_your_clusterstack_directory.md b/docs/preparing_your_clusterstack_directory.md index cc5ec4ea..b18215a2 100644 --- a/docs/preparing_your_clusterstack_directory.md +++ b/docs/preparing_your_clusterstack_directory.md @@ -2,7 +2,7 @@ A [Cluster Stack](https://github.com/SovereignCloudStack/cluster-stacks) is full template of a Kubernetes cluster. A Cluster Stack can be configured on every provider that supports Cluster API. -The Cluster Stack Operator facilitates using Cluster Stacks by automating all steps that users would have to do manually given they have a Cluster API management cluster. +The Cluster Stack Operator facilitates using Cluster Stacks by automating all steps that users would have to do manually given they have a Cluster API management cluster. The csctl helps to generate all files and build node images based on provided scripts in a format that the Cluster Stack Operator can use. @@ -18,7 +18,7 @@ You should must have the following content inside your directory: - node-image directory (optional): the directory containing config and associated scripts to build node images -## Configuring csctl +## Configuring csctl The configuration of csctl has to be specified in the `csctl.yaml`. It needs to follow this structure: ```yaml @@ -32,16 +32,16 @@ config: config: ``` -The apiVersion specifies the version of this configuration. Currently, there is only the version `csctl.clusterstack.x-k8s.io/v1alpha1`. +The apiVersion specifies the version of this configuration. Currently, there is only the version `csctl.clusterstack.x-k8s.io/v1alpha1`. -Furthermore, the Kubernetes version in the format "v.." (e.g. 1.27.5) has to be specified as well as the name that should be given to the Cluster Stack. +Furthermore, the Kubernetes version in the format 'v..' (e.g. 1.27.5) has to be specified as well as the name that should be given to the Cluster Stack. Depending on your plugin, there might be a provider-specific configuration. ## Templating the versions -There are three different versions in a Cluster Stack that can be templated by `csctl`: +There are three different versions in a Cluster Stack that can be templated by `csctl`: ```markdown - << .ClusterAddonVersion >> @@ -50,4 +50,4 @@ There are three different versions in a Cluster Stack that can be templated by ` ``` If you want to specify one of these versions in your Helm chart or other configuration files, then use the one of the above mentioned templated versions. -To reference your node images, you will also need << .NodeImageRegistry >>. \ No newline at end of file +To reference your node images, you will also need '<< .NodeImageRegistry >>'. From d15a3d957d39f6daa80098b13e775d606e76e23c Mon Sep 17 00:00:00 2001 From: Danny Eiselt Date: Wed, 21 Aug 2024 14:35:13 +0200 Subject: [PATCH 2/6] added: updated quickstart.md Signed-off-by: Danny Eiselt --- docs/quickstart.md | 62 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 62 insertions(+) create mode 100644 docs/quickstart.md diff --git a/docs/quickstart.md b/docs/quickstart.md new file mode 100644 index 00000000..4054c9b4 --- /dev/null +++ b/docs/quickstart.md @@ -0,0 +1,62 @@ +# Quickstart + +## Installation +To download `csctl` there are two ways. +Go to https://github.com/SovereignCloudStack/csctl/releases/latest and then click on the binary. The name of the binary looks similar to this `csctl_0.0.3_linux_amd64.tar.gz` for Linux amd64 architecture. + +This will download the binary in your `~/Downloads` directory. Use the following commands to move it to your PATH. +```bash +tar xvzf ~/Downloads/csctl__linux_amd64.tar.gz +chmod u+x ~/Downloads/csctl +sudo mv ~/Downloads/csctl /usr/local/bin/csctl +``` + +Alternative way of installing the binary is to use `[gh](https://github.com/cli/cli)` command line tool. +Use the following command to download the latest binary from GitHub. +```bash +gh release download -p 'csctl__linux_amd64.tar.gz' -R SovereignCloudStack/csctl +tar xvzf csctl__linux_amd64.tar.gz +chmod u+x csctl +sudo mv ./csctl /usr/local/bin/csctl +``` +For darwin based systems, the steps are similar, you'll have to choose darwin based binaries instead of linux one mentioned above. You'll also need to update your destination directory. + +## Creating Cluster Stacks + +The most important subcommand is `create`. This command takes a path to the directory where you configured your Cluster Stack and generates the necessary files in the output directory via the `--output` flag: + +```bash +$ csctl create --output +``` + +You can specify your node image registry with the flag `--node-image-registry`. The plugin of your provider will update the node images in the respective container registry. + +You can use the `--mode` flag to specify the mode you want to use. + +For example: + +```bash +$ csctl create --output --mode hash --node-image-registry +``` + +You have to be authenticated to your cloud provider and container registry to which you want to upload the node images. + +## Different modes of csctl + +The csctl has multiple modes that can be used for different use cases. + +### Hash mode + +This mode is the most used one, as it allows quick iterations and testing of a cluster stack. It takes the hash of the content of the cluster stack and generates a semver version on this. You can combine it with the `custom` channel of Cluster Stack Operator and test your Cluster Stacks easily! + +### Stable mode + +This mode checks for existing releases of cluster stacks and versions your cluster stack accordingly. If you have an existing release of "v1", then it would use "v2" for the new one. It also checks whether the node images and cluster addons have changed or not and will only update the versions if something actually changed. + +### Beta mode + +Similar to stable mode, but for a beta release channel. It versions according to "v0-beta.1", etc. + +### Custom mode + +The custom mode can be used to define your own version. You can input any semver version and your cluster stack will be versioned accordingly. From 1149bf67c2bce92fc488920932c6184bdc0fa8b9 Mon Sep 17 00:00:00 2001 From: Danny Eiselt Date: Wed, 21 Aug 2024 14:39:15 +0200 Subject: [PATCH 3/6] added: overview.md Signed-off-by: Danny Eiselt --- docs/overview.md | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) create mode 100644 docs/overview.md diff --git a/docs/overview.md b/docs/overview.md new file mode 100644 index 00000000..e95838df --- /dev/null +++ b/docs/overview.md @@ -0,0 +1,30 @@ +# Overview + +## Introduction + +The [Cluster Stack Operator](https://github.com/SovereignCloudStack/cluster-stack-operator) facilitates the usage of [Cluster Stacks](https://github.com/SovereignCloudStack/cluster-stacks) by automating all steps that can be automated. It takes Cluster Stacks release assets that consist mainly of two Helm charts, one to deploy in the management cluster, the other one to deploy in the workload clusters, as well as provider-specific node image (build) information. + +Users can take existing releases of Cluster Stacks and the operator and will be able to create clusters easily. + +This project facilitates building node image artifacts and release assets that can be used with the Cluster Stack Operator. + +## What does csctl do? + +As a user, you can create clusters based on Cluster Stacks with the help of the Cluster Stack Operator. The operator needs certain files, e.g. to apply the required Helm charts, and to get the necessary information about the versions in the cluster stack. + +In order to not generate these files manually, this CLI tool takes a certain pre-defined directory structure, in which users can configure all necessary Helm charts and build scripts for node images, and generates the assets that the Cluster Stack Operator can process. + +Therefore, this tool can be used to configure Cluster Stacks and to test them with the Cluster Stack Operator. It can also be used to release stable releases of Cluster Stacks that can be published for a broader community. + +## Features of csctl +1. Testing and quick iterations +csctl is created with a single focus of building Cluster Stacks and testing them with Cluster Stack Operator quickly. This tool helps in doing quick iterations and facilitates testing Cluster Stacks. + +2. Versioning +When configuring Cluster Stacks, it is necessary to put versions in the configuration, e.g. to version a Helm chart or node images. This process is facilitated by the csctl through its own templating and mechanism to generate the right version, based on the content hash (for testing) or on a previous version (stable or beta channel). Users only have to use the right templating and the csctl will do all the versioning automatically. + +3. Plugin mechanism for providers +The plugin mechanism of csctl allows providers to implement all provider-specific steps that are needed for this provider. This can contain a fully automated building and uploading process for node images, which can be referenced in the Cluster Stack (using the templating logic for versioning). + +4. Automated testing of Cluster Stacks +The csctl enables automated testing of Cluster Stacks if integrated in a CI process that first builds all necessary files as well as node images (if needed) and then uses them to create a workload cluster based on the Cluster Stack. From ccb26b930ebbd94ae997dd7e2df077f64f6654fe Mon Sep 17 00:00:00 2001 From: Danny Eiselt Date: Wed, 21 Aug 2024 14:48:13 +0200 Subject: [PATCH 4/6] changed: getting_started file Signed-off-by: Danny Eiselt --- ...paring_your_clusterstack_directory.md => getting_started.md} | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) rename docs/{preparing_your_clusterstack_directory.md => getting_started.md} (98%) diff --git a/docs/preparing_your_clusterstack_directory.md b/docs/getting_started.md similarity index 98% rename from docs/preparing_your_clusterstack_directory.md rename to docs/getting_started.md index b18215a2..0c3e014c 100644 --- a/docs/preparing_your_clusterstack_directory.md +++ b/docs/getting_started.md @@ -1,4 +1,4 @@ -# Configuring a Cluster Stack +# Getting started A [Cluster Stack](https://github.com/SovereignCloudStack/cluster-stacks) is full template of a Kubernetes cluster. A Cluster Stack can be configured on every provider that supports Cluster API. From 7f1021bce2cadfb94a11ffcd1c422ea5b90c9197 Mon Sep 17 00:00:00 2001 From: Danny Eiselt Date: Wed, 21 Aug 2024 14:52:51 +0200 Subject: [PATCH 5/6] added: deprecation note for how_to_use_csctl.md Signed-off-by: Danny Eiselt --- docs/how_to_use_csctl.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/docs/how_to_use_csctl.md b/docs/how_to_use_csctl.md index 1d3f8781..0564c49a 100644 --- a/docs/how_to_use_csctl.md +++ b/docs/how_to_use_csctl.md @@ -1,7 +1,9 @@ +> Obsolete, content moved to overview.md and quickstart.md for use in docs.scs.community + # Using csctl -## What does csctl do? +## What does csctl do? As a user, you can create clusters based on Cluster Stacks with the help of the Cluster Stack Operator. The operator needs certain files, e.g. to apply the required Helm charts, and to get the necessary information about the versions in the cluster stack. @@ -9,7 +11,7 @@ In order to not generate these files manually, this CLI tool takes a certain pre Therefore, this tool can be used to configure Cluster Stacks and to test them with the Cluster Stack Operator. It can also be used to release stable releases of Cluster Stacks that can be published for a broader community. -## Different modes of csctl +## Different modes of csctl The csctl has multiple modes that can be used for different use cases. @@ -51,7 +53,7 @@ commit: f252304eb013014b35f8a91abf1f61aff2062601 If you don't see a version there, then something has gone wrong. Re-check above steps and open an issue if it still does not work! -If you're using `gh` CLI then you can also use the following to download it. +If you're using `gh` CLI then you can also use the following to download it. ```bash $ gh release download -p csctl_0.0.2_linux_amd64 -R SovereignCloudStack/csctl ``` @@ -61,10 +63,10 @@ $ gh release download -p csctl_0.0.2_linux_amd64 -R SovereignCloudStack/csctl The most important subcommand is `create`. This command takes a path to the directory where you configured your Cluster Stack and generates the necessary files in the output directory via the `--output` flag: ```bash -$ csctl create --output +$ csctl create --output ``` -You can specify your node image registry with the flag `--node-image-registry`. The plugin of your provider will update the node images in the respective container registry. +You can specify your node image registry with the flag `--node-image-registry`. The plugin of your provider will update the node images in the respective container registry. You can use the `--mode` flag to specify the mode you want to use. @@ -74,4 +76,4 @@ For example: $ csctl create --output --mode hash --node-image-registry ``` -You have to be authenticated to your cloud provider and container registry to which you want to upload the node images. \ No newline at end of file +You have to be authenticated to your cloud provider and container registry to which you want to upload the node images. From 2bbcd956a27f09b756a07b329d0e0397310499c7 Mon Sep 17 00:00:00 2001 From: Jan Schoone <6106846+jschoone@users.noreply.github.com> Date: Wed, 21 Aug 2024 16:26:25 +0200 Subject: [PATCH 6/6] Update getting_started.md Signed-off-by: Jan Schoone <6106846+jschoone@users.noreply.github.com> --- docs/getting_started.md | 14 -------------- 1 file changed, 14 deletions(-) diff --git a/docs/getting_started.md b/docs/getting_started.md index 0c3e014c..54f154cc 100644 --- a/docs/getting_started.md +++ b/docs/getting_started.md @@ -37,17 +37,3 @@ The apiVersion specifies the version of this configuration. Currently, there is Furthermore, the Kubernetes version in the format 'v..' (e.g. 1.27.5) has to be specified as well as the name that should be given to the Cluster Stack. Depending on your plugin, there might be a provider-specific configuration. - - -## Templating the versions - -There are three different versions in a Cluster Stack that can be templated by `csctl`: - -```markdown -- << .ClusterAddonVersion >> -- << .ClusterClassVersion >> -- << .NodeImageVersion >> -``` -If you want to specify one of these versions in your Helm chart or other configuration files, then use the one of the above mentioned templated versions. - -To reference your node images, you will also need '<< .NodeImageRegistry >>'.