diff --git a/README.md b/README.md index 064ee77..1c4db3e 100644 --- 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 index 158db84..de60494 100644 --- 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 index 811d336..709d0c5 100644 --- a/docs/content/getting-started.md +++ b/docs/content/getting-started.md @@ -73,9 +73,7 @@ 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 @@ -83,23 +81,37 @@ 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 index dd50de2..5415e1b 100644 --- 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 index 359f2cd..2511f68 100644 --- 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 index 05bfb62..54af402 100644 --- 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.