kamaji/docs/getting-started-with-kamaji.md

Setup a minimal Kamaji for development

This document explains how to deploy a minimal Kamaji setup on KinD for development scopes. Please refer to the Kamaji documentation for understanding all the terms used in this guide, as for example: admin cluster and tenant control plane.

Pre-requisites

We assume you have installed on your workstation:

• Docker
• KinD
• kubectl
• kubeadm
• jq
• openssl
• cfssl
• cfssljson

Setup Kamaji on KinD

The instance of Kamaji is made of a single node hosting:

• admin control-plane
• admin worker
• multi-tenant etcd cluster

Standard

You can install your KinD cluster, ETCD multi-tenant cluster and Kamaji operator with a single command:

$ make -C deploy/kind

Now you can create your first TenantControlPlane.

Data store-specific

ETCD

The multi-tenant etcd cluster is deployed as statefulset into the Kamaji node.

Run make reqs to setup Kamaji's requisites on KinD:

$ make -C deploy/kind reqs

At this moment you will have your KinD up and running and ETCD cluster in multitenant mode.

Now you're ready to install Kamaji operator.

Kine

The MySQL-compatible cluster provisioning is omitted here.

Kamaji offers the possibility of using a different storage system than ETCD for the tenants, like MySQL or PostgreSQL compatible databases.

Read it more in the provided guide.

Assuming you adjusted the Kamaji manifest to connect to Kine and compatible database using the proper driver, you can now install it.

Install Kamaji

$ kubectl apply -f config/install.yaml

Deploy Tenant Control Plane

Now it is the moment of deploying your first tenant control plane.

$ kubectl apply -f - <<EOF
apiVersion: kamaji.clastix.io/v1alpha1
kind: TenantControlPlane
metadata:
  name: tenant1
spec:
  controlPlane:
    deployment:
      replicas: 2
      additionalMetadata:
        annotations:
          environment.clastix.io: tenant1
          tier.clastix.io: "0"
        labels:
          tenant.clastix.io: tenant1
          kind.clastix.io: deployment
    service:
      additionalMetadata:
        annotations:
          environment.clastix.io: tenant1
          tier.clastix.io: "0"
        labels:
          tenant.clastix.io: tenant1
          kind.clastix.io: service
      serviceType: NodePort
  kubernetes:
    version: "v1.23.4"
    kubelet:
      cgroupfs: cgroupfs
    admissionControllers:
    - LimitRanger
    - ResourceQuota
  networkProfile:
    address: "172.18.0.2"
    port: 31443
    certSANs:
    - "test.clastixlabs.io"
    serviceCidr: "10.96.0.0/16"
    podCidr: "10.244.0.0/16"
    dnsServiceIPs: 
    - "10.96.0.10"
  addons:
    coreDNS: {}
    kubeProxy: {}
EOF

Check networkProfile fields according to your installation To let Kamaji works in kind, you have indicate that the service must be NodePort

Get Kubeconfig

Let's retrieve kubeconfig and store in /tmp/kubeconfig

$ kubectl get secrets tenant1-admin-kubeconfig -o json \
 | jq -r '.data["admin.conf"]' \
 | base64 -d > /tmp/kubeconfig

It can be export it, to facilitate the next tasks:

$ export KUBECONFIG=/tmp/kubeconfig

Install CNI

We highly recommend to install kindnet as CNI for your kamaji TCP.

$ kubectl create -f https://raw.githubusercontent.com/aojea/kindnet/master/install-kindnet.yaml

Join worker nodes

$ make kamaji-kind-worker-join

To add more worker nodes, run again the command above.

Check out the node:

$ kubectl get nodes
NAME           STATUS   ROLES    AGE   VERSION
d2d4b468c9de   Ready    <none>   44s   v1.23.4

For more complex scenarios (exposing port, different version and so on), run join-node.bash

Tenant control plane provision has been finished in a minimal Kamaji setup based on KinD. Therefore, you could develop, test and make your own experiments with Kamaji.

Cleanup

$ make destroy