K3S

Installation

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. To verify your K3S cluster and node info run:

$ sudo k3s kubectl cluster-info
$ sudo k3s kubectl get node

If you already have kubectl installed on your machine, you can configure it to use the K3S cluster configuration per default.

# Backup current config
$ cp $HOME/.kube/config $HOME/.kube/config.backup
# Copy K3S config
$ sudo cp -i /etc/rancher/k3s/k3s.yaml $HOME/.kube/config
$ sudo chown $(id -u):$(id -g) $HOME/.kube/config

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

K3s is installed as a service in Linux systems, so it will start on boot automatically. You can prevent k3s from starting automatically by using the systemctl command:

$ sudo systemctl disable k3s

To enable the autostart feature again run:

$ sudo systemctl enable k3s

You can always start/stop the k3s service manually by running the following command:

$ sudo systemctl start k3s
$ sudo systemctl stop k3s

Another option to stop k3s and all related tasks is to run the k3s-killall command:

$ /usr/local/bin/k3s-killall.sh

Network

In difference to the Minikube System K3S does not require additional network configuration for local environments. The network traffic is controlled by the Traefik ingress controller which is part of K3S. Traefik provides a lot of features to route network traefic into your cluster.

Persistence Volumes

When deploying Imixs-Office-Workflow or other services in K3S, 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.

$ kubectl apply -f git/imixs-office-workflow/kubernetes/k3s/local-storage-class.yaml

$ mkdir -p /opt/kubernetes-local-pv/office-dbdata

---
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

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 switch into your imixs-office-workflow folder and apply the K3S deployment:

$ kubectl apply -f ./kubernetes/k3s/office-workflow

Imixs-ML

You can install Imixs-ML as an additional service providing OCR and ML capabilities.

First create a directory for your ML models and copy the default model:

$ mkdir -p /opt/kubernetes-local-pv/office-imixs-ml
$ cp -r ./kubernetes/k3s/imixs-ml/models/invoice-de-0.2.0 /opt/kubernetes-local-pv/office-imixs-ml/

Next you can deploy the Imixs-ML module

$ kubectl apply -f ./kubernetes/k3s/imixs-ml

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

$ htpasswd -c registry-auth-file admin

$ kubectl create secret generic registry-basic-auth --from-file=registry-auth

---
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