docs: update install instructions and versioning (#562)

clastix · Aug 29, 2024 · ae540b4 · ae540b4
1 parent a6ab731
commit ae540b4
Show file tree

Hide file tree

Showing 6 changed files with 45 additions and 61 deletions.
diff --git a/README.md b/README.md
@@ -13,7 +13,7 @@
 
 ### 🤔 What is Kamaji?
 
-**Kamaji** is a **Kubernetes Control Plane Manager** leveraging on the concept of [**Hosted Control Plane**](https://clastix.io/post/the-raise-of-hosted-control-plane-in-kubernetes/).
+**Kamaji** is the **Kubernetes Control Plane Manager** leveraging on the concept of [**Hosted Control Plane**](https://clastix.io/post/the-raise-of-hosted-control-plane-in-kubernetes/).
 
 Kamaji's approach is based on running the Kubernetes Control Plane components in Pods instead of dedicated machines.
 This allows operating Kubernetes clusters at scale, with a fraction of the operational burden.

diff --git a/charts/kamaji/Chart.lock b/charts/kamaji/Chart.lock
@@ -1,6 +1,6 @@
 dependencies:
 - name: kamaji-etcd
   repository: https://clastix.github.io/charts
-  version: 0.7.0
-digest: sha256:2e23a11b06da2aa3a935a56a93d56876c6c8ef0a7800ee44070f9a269dfbca71
-generated: "2024-08-10T23:03:35.382486587+02:00"
+  version: 0.8.0
+digest: sha256:525b0eb2b5bae709d62de9328312d42c54b5219c6df67061de0da79eeca04fb3
+generated: "2024-08-25T08:44:24.92211307+02:00"
diff --git a/docs/content/getting-started.md b/docs/content/getting-started.md
@@ -73,33 +73,45 @@ helm install \
 
 ## Install Kamaji Controller
 
-Installing Kamaji via Helm charts is the preferred way. The Kamaji controller needs to access a Datastore in order to save data of the tenants' clusters. The Kamaji Helm Chart provides the installation of a basic unmanaged `etcd` as datastore, out of box. 
-
-Install Kamaji with `helm` using an unmanaged `etcd` as default datastore:
+Installing Kamaji via Helm charts is the preferred way. Run the following commands to install a stable release of Kamaji:
 
 ```bash
 helm repo add clastix https://clastix.github.io/charts
 helm repo update
 helm install kamaji clastix/kamaji -n kamaji-system --create-namespace
 ```
 
-!!! note "A managed datastore is highly recommended in production"
-     The [kamaji-etcd](https://github.com/clastix/kamaji-etcd) project provides the code to setup a multi-tenant `etcd` running as StatefulSet made of three replicas. Optionally, Kamaji offers support for a more robust storage system, as `MySQL` or `PostgreSQL` compatible database, thanks to the native [kine](https://github.com/k3s-io/kine) integration.
+!!! info "Stable Releases"
+    As of July 2024 [Clastix Labs](https://github.com/clastix) does no longer publish stable release artifacts. Stable releases are offered on a subscription basis by [CLASTIX](https://clastix.io), the main Kamaji project contributor. 
 
-Now you should end up with a working Kamaji instance, including the default `datastore`:
+Run the following commands to install latest edge release of Kamaji:
+
+```bash
+git clone https://github.com/clastix/kamaji
+cd kamaji
+helm install kamaji charts/kamaji -n kamaji-system --create-namespace \
+    --set image.tag=latest
+```
+
+After installation, verify that Kamaji and its components are running:
+
+```bash
+kubectl -n kamaji-system get pods
+```
+
+Expected output:
 
 ```bash
 kubectl -n kamaji-system get pods
 NAME                         READY   STATUS      RESTARTS      AGE
-etcd-0                       1/1     Running     0             50s
-etcd-1                       1/1     Running     0             60s
-etcd-2                       1/1     Running     0             90s
+kamaji-etcd-0                1/1     Running     0             50s
+kamaji-etcd-1                1/1     Running     0             60s
+kamaji-etcd-2                1/1     Running     0             90s
 kamaji-7949578bfb-lj44p      1/1     Running     0             12s
 ```
 
-> An unsuccessful first installation could fail for several reasons, such as missing a `StorageClass`, or even for a trivial `Ctrl+C` during the installation phase.
->
-> See the [Cleanup](#cleanup) section before to retry an aborted installation. 
+!!! info "Kamaji Datastore"
+    Kamaji installs [kamaji-etcd](https://github.com/clastix/kamaji-etcd) as its default datastore, which is a multi-tenant `etcd`. Optionally, Kamaji offers support for other storage systems, as `PostgreSQL`, `MySQL` or `NATS`, thanks to the native [kine](https://github.com/k3s-io/kine) integration.
 
 ## Create Tenant Cluster
 
@@ -259,6 +271,9 @@ And make sure it is `${TENANT_ADDR}:${TENANT_PORT}`.
 
 The Tenant Control Plane is made of pods running in the Kamaji Management Cluster. At this point, the Tenant Cluster has no worker nodes. So, the next step is to join some worker nodes to the Tenant Control Plane.
 
+!!! warning "Opening Ports"
+    To make sure worker nodes can join the Tenant Control Plane, you must allow incoming connections to: `${TENANT_ADDR}:${TENANT_PORT}` and `${TENANT_ADDR}:${TENANT_PROXY_PORT}`
+
 Kamaji does not provide any helper for creation of tenant worker nodes, instead it leverages the [Cluster Management API](https://github.com/kubernetes-sigs/cluster-api). This allows you to create the Tenant Clusters, including worker nodes, in a completely declarative way. Refer to the [Cluster API guide](guides/cluster-api.md) to learn more about supported providers.
 
 An alternative approach for joining nodes is to use the `kubeadm` command on each node. Follow the related [documentation](https://kubernetes.io/docs/setup/production-environment/tools/kubeadm/install-kubeadm/) in order to:
@@ -386,4 +401,13 @@ kubectl delete ValidatingWebhookConfiguration kamaji-validating-webhook-configur
 kubectl delete MutatingWebhookConfiguration kamaji-mutating-webhook-configuration
 ```
 
+And if still present, delete the datastore:
+
+```bash
+kubectl patch datastore default --type='json' \
+  -p='[{"op": "remove", "path": "/metadata/finalizers"}]'
+
+kubectl delete datastore default
+```
+
 That's all folks!
diff --git a/docs/content/guides/kamaji-azure-deployment.md b/docs/content/guides/kamaji-azure-deployment.md
@@ -14,8 +14,7 @@ The guide requires:
 
   * [Prepare the bootstrap workspace](#prepare-the-bootstrap-workspace)
   * [Access Management Cluster](#access-management-cluster)
-  * [Install Cert Manager](#install-cert-manager)
-  * [Install Kamaji controller](#install-kamaji-controller)
+  * [Install Kamaji](#install-kamaji)
   * [Create Tenant Cluster](#create-tenant-cluster)
   * [Cleanup](#cleanup)
 
@@ -97,35 +96,9 @@ And check you can access:
 kubectl cluster-info
 ```
 
-## Install Cert Manager
+## Install Kamaji
 
-Kamaji takes advantage of the [dynamic admission control](https://kubernetes.io/docs/reference/access-authn-authz/extensible-admission-controllers/), such as validating and mutating webhook configurations. These webhooks are secured by a TLS communication, and the certificates are managed by [`cert-manager`](https://cert-manager.io/), making it a prerequisite that must be installed:
-
-```bash
-helm repo add jetstack https://charts.jetstack.io
-helm repo update
-helm install \
-  cert-manager jetstack/cert-manager \
-  --namespace cert-manager \
-  --create-namespace \
-  --version v1.11.0 \
-  --set installCRDs=true
-```
-
-## Install Kamaji Controller
-
-Installing Kamaji via Helm charts is the preferred way. The Kamaji controller needs to access a Datastore in order to save data of the tenants' clusters. The Kamaji Helm Chart provides the installation of a basic unmanaged `etcd` as datastore, out of box. 
-
-Install Kamaji with `helm` using an unmanaged `etcd` as default datastore:
-
-```bash
-helm repo add clastix https://clastix.github.io/charts
-helm repo update
-helm install kamaji clastix/kamaji -n kamaji-system --create-namespace
-```
-
-!!! note "A managed datastore is highly recommended in production"
-     The [kamaji-etcd](https://github.com/clastix/kamaji-etcd) project provides the code to setup a multi-tenant `etcd` running as StatefulSet made of three replicas. Optionally, Kamaji offers support for a more robust storage system, as `MySQL`, `PostgreSQL`, or `NATS` compatible database, thanks to the native [kine](https://github.com/k3s-io/kine) integration.
+Follow the [Getting Started](../getting-started.md) to install Cert Manager and the Kamaji Controller.
 
 ## Create Tenant Cluster
 

diff --git a/docs/content/index.md b/docs/content/index.md
@@ -1,6 +1,6 @@
 # Kamaji
 
-**Kamaji** is a **Kubernetes Control Plane Manager**. It operates Kubernetes at scale with a fraction of the operational burden.
+**Kamaji** is the **Kubernetes Control Plane Manager**. It operates Kubernetes at scale with a fraction of the operational burden.
 
 ## How it works
 Kamaji turns any Kubernetes cluster into a _“Management Cluster”_ to orchestrate other Kubernetes clusters called _“Tenant Clusters”_. Kamaji is special because the Control Plane components are running inside pods instead of dedicated machines. This solution makes running multiple Control Planes cheaper and easier to deploy and operate. 

diff --git a/docs/content/reference/versioning.md b/docs/content/reference/versioning.md
@@ -18,21 +18,8 @@ Stable Release artifacts of Kamaji follow semantic versioning, whereby changes i
 
 | Kamaji | Management Cluster | Tenant Cluster       |
 |--------|--------------------|----------------------|
-| v0.3.0 | v1.22+             | [v1.21.0 .. v1.27.0] |
-| v0.3.1 | v1.22+             | [v1.21.0 .. v1.27.3] |
-| v0.3.2 | v1.22+             | [v1.21.0 .. v1.27.3] |
-| v0.3.3 | v1.22+             | [v1.21.0 .. v1.27.3] |
-| v0.3.4 | v1.22+             | [v1.21.0 .. v1.28.1] |
-| v0.3.5 | v1.22+             | [v1.21.0 .. v1.28.1] |
-| v0.3.5 | v1.22+             | [v1.21.0 .. v1.28.1] |
-| v0.4.0 | v1.22+             | [v1.21.0 .. v1.29.0] |
-| v0.4.1 | v1.22+             | [v1.21.0 .. v1.29.1] |
-| v0.4.2 | v1.22+             | [v1.21.0 .. v1.29.1] |
-| v0.5.0 | v1.22+             | [v1.21.0 .. v1.30.0] |
-| v0.6.0 | v1.22+             | [v1.21.0 .. v1.30.1] |
 | v1.0.0 | v1.22+             | [v1.21.0 .. v1.30.2] |
 
-As of July 2024 [Clastix Labs](https://github.com/clastix) organization does no longer provide stable release artifacts.
-Stable Release artefacts are offered on a subscription basis by [CLASTIX](https://clastix.io), the main Kamaji project contributor.
+As of July 2024 [Clastix Labs](https://github.com/clastix) organization does no longer provide stable release artifacts. Stable Release artifacts are offered on a subscription basis by [CLASTIX](https://clastix.io), the main Kamaji project contributor.
 
 > Learn more about [available subscription plans](https://clastix.io/support/) from CLASTIX.