K3S
During development and also for production you can run Imixs-Office-Workflwo in the lithweight Kubernetes Environment K3S.
In it’s most easiest setup you can install and start K3S following the Quick-Start Guide
$ curl -sfL https://get.k3s.io | sh - $ sudo systemctl status k3s.service
A kubeconfig file will be written to /etc/rancher/k3s/k3s.yaml
and the kubectl installed by K3s will automatically use it. Verify your cluster and node info.
$ sudo k3s kubectl cluster-info $ sudo k3s kubectl get node
If you have kubectl installed you can configure your cluster to use the k3s configuration.
# grant access to all users $ sudo chmod a+r /etc/rancher/k3s/k3s.yaml # setting a environment variable or $ export KUBECONFIG=/etc/rancher/k3s/k3s.yaml
Now you can access your k3s cluster with kubectl directly:
$ kubectl cluster-info
K9S
We recommend the k9s tool to check your K3S cluster and your local deployments.
To run k9s connecting to your local k3s Cluster run:
$ sudo ./k9s --kubeconfig /etc/rancher/k3s/k3s.yaml
Start, Stop, Autostart Function
You can stop the k3s service if it is currently running by running the following command:
$ sudo systemctl stop k3s
This will stop the k3s service immediately. To start k3s again run:
$ sudo systemctl start k3s
K3s is typically managed as a service in Linux systems, so it will typically start on boot. You can disable it from starting automatically by using the systemctl command:
$ sudo systemctl disable k3s
This will prevent k3s from starting automatically when the system boots up.
Another option to stop k3s and all related tasks is to run:
$ /usr/local/bin/k3s-killall.sh
Network
In difference to the Minikube System K3S does not require additional network configuration for local testing. The network traffic is controlled by the Traefik ingress controller which is part of K3S.
Persistence Volumes
When deploying Imixs-Office-Workflow or other services you may need to retain data storage for the SQL Database or the Search Index. Within Kubernetes this is managed by providing a persistent storage. A storage solution is in general not part of Kubernetes but you can use the so called ‘Local Storage’ to use local disk space.
Kuberentes Local Storage
A local volume represents a mounted local storage device such as a disk, partition or directory. To use local storage within your local Kubernetes cluster first deploy the dev-storage-class:
$ kubectl apply -f git/imixs-office-workflow/kubernetes/k3s/local-storage-class.yaml
next you can create your local storage directory where the data should be stored on your disk:
$ mkdir -p /opt/kubernetes-local-pv/office-dbdata
Here is an example how to setup a Persistence Volume Claim and a Persistence Volume using the local storage:
--- apiVersion: v1 kind: PersistentVolumeClaim metadata: name: dbdata spec: accessModes: - ReadWriteOnce storageClassName: dev-local-storage resources: requests: storage: 128Mi --- apiVersion: v1 kind: PersistentVolume metadata: name: dbdata spec: capacity: storage: 128Mi accessModes: - ReadWriteOnce persistentVolumeReclaimPolicy: Retain storageClassName: dev-local-storage local: path: /opt/kubernetes-local-pv/office-dbdata nodeAffinity: required: nodeSelectorTerms: - matchExpressions: - key: node.kubernetes.io/instance-type operator: In values: - k3s
Find more details about the usage of Kubernetes Local Storage here.
Deployment Imixs-Office-Workflow
To deploy Imixs-Office-Workflow on K3S you can use the deployment configuration located in /kubernetes/k3s.
First ensure that you have created your local storage directories to store the SQL and index data:
$ mkdir -p /opt/kubernetes-local-pv/office-dbdata $ mkdir -p /opt/kubernetes-local-pv/office-index
next you can apply the deployment:
$ kubectl apply -f git/imixs-office-workflow/kubernetes/k3s/office-workflow
Container Registry
You can also easily install a private registry in K3s to push custom container images into your dev environment. These images are than accessible by your cluster:
Frist create a local storage directory for your registry data:
$ mkdir -p /opt/kubernetes-local-pv/registry-storage
next you can start the deployment:
$ kubectl apply -f git/imixs-office-workflow/kubernetes/k3s/registry
Note: You can define a HTTP Access Password by setting the environment variable REGISTRY_HTTP_SECRET
.
To test your registry open the following URL in a Web Browser:
http://localhost:5000/v2/_catalog
Secure Your Registry
You can secure the access to your registry by defining a Basic Authentication middleware via a Traefik IngressRoute
First use the commandline tool htpasswd
to generate a password file:
$ htpasswd -c registry-auth-file admin
Next you can create a corresponding Kubernetes Secret:
$ kubectl create secret generic registry-basic-auth --from-file=registry-auth
The following is an example how to define a IngressRoute with Traefik:
--- kind: Middleware apiVersion: traefik.containo.us/v1alpha1 metadata: name: registry-basic-auth spec: basicAuth: secret: registry-basic-auth --- apiVersion: traefik.containo.us/v1alpha1 kind: IngressRoute metadata: name: docker-registry spec: entryPoints: - web routes: - match: Host(`example.foo.com`) kind: Rule middlewares: - name: registry-basic-auth services: - name: docker-registry port: 5000