Smartbib Installation mit HELM

Dieses Tutorial zeigt, wie man Smartbib mit Hilfe von microk8s und helm installieren kann.

Einleitung

Dieses Tutorial dient als Step-by-Step Anleitung und zeigt wie man Smartbib in einer Kubernetes Umgebung installieren kann.

Für die Installationanleitung wird MicroK8s von Canonical verwendet. https://microk8s.io/

SNAP installieren

Für die generelle Installation ist snap (https://snapcraft.io/) erforderlich, da microk8s über den Snap Store verfügbar ist.

In den meisten Ubuntu-basierten Distributionen ist der snapd Daemon bereits vorinstalliert.

Falls man andere Distributionen verwenden möchte, dann findet man unter https://snapcraft.io/docs/installing-snapd die notwendigen Installationsschritte.

So gibt es z.B. snapd ab Debian 9 (Strech) bereits als APT Package.

$ sudo apt install snapd

Microk8s

Micro Kubernetes installieren

Es kann nun microk8s in der aktuellen Version mit Hilfe von Snap über installiert werden.

$ sudo snap install microk8s --classic

Alternativ: Version festlegen

Sollte man eine spezielle Kubernetes Version verwenden wollen, so kann man dies alternativ über die Angabe des Channels festlegten.

$ sudo snap install microk8s --classic --channel=1.19/stable

Die verfügbaren Channels kann man sich mit snap info microk8s anzeigen lassen.

Berechtigungen für aktuellen User setzen

Wenn man nicht mit sudo sondern direkt mit dem aktuellen Benutzer einen Zugriff auf die kubernetes Installation haben möchte, dann empfiehlt sich eine Anpassung der Benutzerberechtigungen.

Folgender Befehl gibt dem aktuellen User die erforderliche Gruppenberechtigung.

$ sudo usermod -a -G microk8s $USER

Alias setzen

Grundsätzlich sind nun alle kubernetes Commands per microk8s. Prefix über die Shell verfügbar. (z.B. microk8s.kubectl)

Bei häufig genutzen Commands - wie dies bei kubectl meist der Fall ist - empfiehlt es sich, dass man Shell Aliase setzt.

Hier ein Beispiel, falls man BASH verwendet:

$ echo "alias kubectl='microk8s.kubectl'" >> ~/.bash_aliases
$ echo "alias helm='microk8s.helm'" >> ~/.bash_aliases

Nach der Neuanmeldung stehen dann die Aliase zur Verfügung.

$ su - $USER

Microk8s Module installieren

Nun können erforderliche MicroK8s Module aktiviert werden.

Für die Smartbib-Installation werden folgende Module benötigt:

dns: CoreDNS (verwendet als Default 8.8.8.8 u.w. als Upstream DNS)
storage: Dateipfade des Hosts werden als Storage zur Verfügung gestellt
ingress: NGINX Ingress Controller (für Namesbaisertes Virtual Hosting)

Die Module können mit folgendem Befehl installiert werden:

$ microk8s.enable dns storage ingress

HELM- und Docker-Repository

Um das Deployment von Smartbib zu vereinfachen wird der Package Manager helm (https://helm.sh/) verwendet.

Wir stellen für Smartbib ein helm und docker-repository zur Verfügung:

docker: https://registry.smartbib.net
helm: https://registry.smartbib.net/charts/

Für den Zugriff benötigen Sie einen Benutzernamen und ein Passwort.
Bei folgenden Anleitungen werden hierfür die Environment-Variablen $USERNAME und $PASSWORD verwendet.

HELM Package Manager installieren

Der aktuelle HELM Package Manger kann per microk8s.enable oder SNAP installiert werden.
Die integrierte Version in microk8s ist jedoch meist etwas veraltet.
Aus diesem Grund wird die Installation mit snap gewählt:

$ sudo snap install helm --classic

Damit der HELM Package Manager - ohne weitere Konfiguration - Zugriff auf die MicroK8s Installation erhält, kann ein symbolischer Link in der microk8s-Installlation angelegt werden.

$ sudo mkdir -p /var/snap/microk8s/current/bin
$ sudo ln -s /snap/bin/helm /var/snap/microk8s/current/bin/helm

Smartbib Helm Repository hinzufügen

Ihre Zugangsdaten müssen sich in den Environment-Variablen $USERNAME und $PASSWORD befinden.

Hinzufügen das Smartbib HELM Repositories:

$ helm repo add smartbib https://registry.smartbib.net/charts/ --username $USERNAME --password $PASSWORD
$ helm repo update

Das Helm Respostory kann nun kurz mit folgendem Befehl geprüft werden:

$ helm search repo

Docker Repositiory Credentials setzen

$ kubectl create secret docker-registry regcred --docker-server=registry.smartbib.net --docker-username=$USERNAME --docker-password=$PASSWORD

Optional: Cert-Manager installieren

Um die Ausstellung von Zertifikaten zu vereinfachen, kann für Kubernetes der Cert-Manager (https://cert-manager.io) verwendet werden.

Im folgenden Beispiel wird der Cert-Manager mit Hilfe des HELM Package Managers installiert und es werden Issuer für Letscrypt-Zertikatsausstellungen (production und staging) angelegt.
Es wird dabei der HTTP Solver verwendet.

Nach Abschluss wird es dann möglich sein, dass die automatische Zertifkatserstellung direkt per Annotation bei der Ingress Definition hinterlegt werden kann.

Helm Repository hinzufügen

Der Cert-Manager kann sehr einfach über HELM depolyed werden.
Als erster Schritt muss hierfür das Jetstack HELM-Repository hinzugefügt werden:

$ helm repo add jetstack https://charts.jetstack.io
$ helm repo update

Cert-Manager mit HELM installieren

Nun kann der Cert-Manager bereit gestellt werden.
Es bietet sich hier die Verwendung eines eigenen Namespaces (z.B. cert-manager) an.

$ kubectl create namespace cert-manager
$ helm install cert-manager jetstack/cert-manager --namespace cert-manager --version v1.1.0 --set installCRDs=true

Create Letsencrypt Certificate Issuers

Es werden nun die Issuer für die Zertifikat-Requests erstellt.
Es wird ein ClusterIssuer verwendet, der namespace-übergreifend funktioniert, aber die Verwendung des Issuer ist genauso möglich.
Im Folgenden werden 2 neue YAML Dateien angelegt, die für Production und für Staging-Requests genutzt werden können.

Die Email-Adresse muss entsprechend angepasst werden.
Im Beispiel wird ein HTTP Challenge Solver verwendet.

Production

letsencrypt-cluster-issuer.yaml

apiVersion: cert-manager.io/v1alpha2
kind: ClusterIssuer
metadata:
  name: letsencrypt
spec:
  acme:
    # You must replace this email address with your own.
    # Let's Encrypt will use this to contact you about expiring
    # certificates, and issues related to your account.
    email: email@example.com
    server: https://acme-v02.api.letsencrypt.org/directory
    privateKeySecretRef:
      # Secret resource that will be used to store the account's private key.
      name: letsencrypt-account-key
    # Add a single challenge solver, HTTP01 using nginx
    solvers:
    - http01:
        ingress:
          class: nginx

Staging

letsencrypt-staging-cluster-issuer.yaml:

apiVersion: cert-manager.io/v1alpha2
kind: ClusterIssuer
metadata:
  name: letsencrypt-staging
spec:
  acme:
    email: email@example.com
    server: https://acme-staging-v02.api.letsencrypt.org/directory
    privateKeySecretRef:
      name: letsencrypt-staging-account-key
    solvers:
    - http01:
        ingress:
          class: nginx

Letencrypt Issuers

Nun können die 2 Issuers mit Hilfe von kubectl apply hinzugefügt werden.

$ kubectl apply -f letsencrypt-cluster-issuer.yaml
$ kubectl apply -f letsencrypt-staging-cluster-issuer.yaml

Verwenden der Issuer

Nun können die Issuer in den Annotations der Ingress Konfguration verwendet werden:

ingress:
  ...
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt

oder

ingress:
  ...
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-staging

YAML Konfiguration für HELM erzeugen

Nun muss eine HELM Konfiguration erstellt werden oder sie erhalten eine vorkonfigurierte Datei.

Im folgenden Texten und Dateiausschnitten wird der Begriff CUSTOMER_TOKEN verwendet.
An all diesen Stellen sollten sie ihr eigenes TOKEN angeben, dass sie von uns erhalten haben.

CUSTOMER_TOKEN.yaml:

# Wichtig: Token setzen
customer: CUSTOMER_TOKEN 

solr:
  keep: true # Solr Index auch beim Löschen des Charts behalten

# Ingress für namebased virtual hosting und Letscrypt Certificate Requests
ingress:
  enabled: true
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt
  hosts:
    - host: smartbib.example.com
      paths: [""]
  tls:
    - secretName: smartbib.example.com
      hosts:
        - smartbib.example.com

# Optional: BibConnector Konfigurationen
bibcon:
  enabled: true
  configFiles:
    data:
      bibConnector.xml: |-
        <configuration>
          <bibConnector>BIBL</bibConnector>
          ...
          <port>8040</port>
        </configuration>        
      BIBL.xml: |-
        <configuration>
        ...
        </configuration>

Nur HTTP Ingress verwenden

Falls der Cert-Manager nicht verwendet wird und die Zertifikatsausstellung an anderer Stelle, z.B. durch einen Proxy erledigt wird, dann ist es möglich, dass man die automatische HTTP -> HTTPS Weiterleitung deaktivieren kann.
Hierfür muss eine Annotation hinzugefügt werden: nginx.ingress.kubernetes.io/ssl-redirect: "false".
Auf den Block tls kann nun komplett verzichtet werden.

Beispiel:

...

# Ingress für namebased virtual hosting und Letscrypt Certificate Requests
ingress:
  enabled: true
  annotations:
    nginx.ingress.kubernetes.io/ssl-redirect: "false"
  hosts:
    - host: smartbib.example.com
      paths: [""]
...

Smartbib starten

$ helm install smartbib-CUSTOMER_TOKEN smartbib/smartbib -f CUSTOMER_TOKEN.yaml

Installation prüfen

Zuerst sollte man warten bis alle Pods gestartet wurden:

$ kubectl get pods -w

(Abbruch mit Strg+C)

Zugriff auf die Logs

ENV Variable erstellen

Im ersten Schritt ist es hilfreich, dass man eine Environment Variable erstellt, damit man den HASH des Pods nicht per Hand eingeben muss:

$ export SMARTBIB_POD=$(microk8s.kubectl get pods --namespace default -l "app.kubernetes.io/name=smartbib,app.kubernetes.io/instance=smartbib-CUSTOMER_TOKEN" -o jsonpath="{.items[0].metadata.name}")

(smartbib-CUSTOMER_TOKEN muss entsprechend angepasst werden)

Logs anzeigen/verfolgen

Hier ein Bespiel wie man z.b die BibConnector-Ausgabe einsehen kann:

$ kubectl logs $SMARTBIB_POD -c bibcon -f

Eine komplette Liste aller Möglichkeiten erhält man, wenn man den -c Parameter weglässt:

$ kubectl logs $SMARTBIB_POD

Zuletzt geändert 28.01.2021