Versions Compared

Old Version 2

changes.mady.by.user Susanne Tilgner

Saved on

compared with

New Version Current

changes.mady.by.user Daniel Molkentin

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Excerpt
nameen Installation Kubernetes (comments)

Unser Installationsbundle für den Kommentierungsserver auf Kubernetes besteht aus mehreren Dateien:

Im Folgenden gehen wir davon aus, dass Ihnen bekannt ist, wie Dockerfiles und .yml Konfigurationsdateien in Kubernetes zu verwenden sindOur installation bundle for the comment server on Kubernetes consists of several files:

In the following, we assume that you know how to use Dockerfiles and .yml configuration files in Kubernetes.

Dockerfile*

In den drei Dockerfiles befinden sich die Anweisungen, wie die drei für die Kommentierung benötigten Container erstellt werden. Die so erstellten Container müssen dann in Ihre docker-registry gepusht werden um sie in Kubernetes zu nutzen.

Ordner The three Dockerfiles contain the instructions on how to create the three containers needed for commenting. The containers created in this way must then be pushed into your docker registry in order to use them in Kubernetes.

Files comments-keycloak-theme, commenting.jar, nginx.conf, keycloak-docker-entrypoint.sh

Diese Dateien werden von den Dockerfiles verwendet um die einzelnen Container zu erstellen. Eine Modifikation ist hier in der Regel nicht notwendigThese files are used by the Dockerfiles to create the individual containers. A modification is usually not necessary here.

*-kubernetes-*.ymlIn den fünf YAML-Dateien befinden sich die Konfigurationen für Kubernetes um unseren Service starten zu können. Diese dienen als Orientierung und es können je nach Ihrer Kubernetes-Konfiguration Anpassungen nötig sein. In der

The five YAML files contain the configurations for Kubernetes to be able to start our service. These serve as orientation and adjustments may be necessary depending on your Kubernetes configuration.

  • The 0-kubernetes-ns.yml

ist der Namespace definiert, in dem die graphomate comments Entitäten in Kubernetes erstellt werden. Die

  • defines the namespace in which the graphomate comments entities are created in Kubernetes.

  • The 1-kubernetes-role.yml

definiert die Rollen die notwendig sind, damit die graphomate services die Konfigurationen lesen dürfen. Die Datei

  • defines the roles necessary to allow graphomate services to read the configurations.

  • The 2-kubernetes-config.yml

definiert unterschiedliche Konfigurationsparameter für den unseren Service. Dazu gehören die Verbindungsdaten für die Datenbanken in denen die Kommentare und die Benutzer gespeichert werden. Diese können auch in der selben Datenbank gespeichert werden. Dafür sind in PostgreSQL zwei Schemata notwendig. Bisher konnten wir auch erfolgreich MSSQL auf Azure ohne Schemata testen. Die Konfiguration dafür ist in etwas komplexer als die für PostgreSQL und kann bei Bedarf durch uns erklärt werden. Auch die Definition für den Mailserver werden hier getätigt. Dieser wird verwendet um einem Benutzer der in einem Kommentar erwähnt wurde darüber per Mail zu benachrichtigen. In der

  • file defines various configuration parameters for our service. This includes the connection details for the databases where the comments and users are stored. These can also be stored in the same database. This requires two schemas in PostgreSQL. So far, we have also been able to successfully test MSSQL on Azure without schemas. The configuration for this is somewhat more complex than for PostgreSQL and can be explained by us if required. The definition for the mail server is also done here. This is used to notify a user mentioned in a comment by mail.

  • In the 3-kubernetes-secrets.yml

werden Zugangsdaten für die Datenbanken, den Mailserver und den initialen Administrator gepflegt. Diese sind wie für Kubernetes üblich Base64 encodiert.

  • , access data for the databases, the mail server and the initial administrator are maintained. These are Base64 encoded as usual for Kubernetes.

  • In 4-kubernetes-deployment.yml

werden die drei für unseren Service benötigten Container Konfiguriert. Diese sind in unserem Bespiel alle in einem Pod vereint und verwenden temporäre in-memory Volumes. Es steht ihnen natürlich frei, andere, bespielsweise persistente, Volumes zu verwenden und die Container für besseres Load-Balancing in unterschiedlichen Pods zu verteilen. Dafür ist allerdings im Fall von dem keycloak-Container eine relative komplexe Konfiguration und eine Anpassung der nginx.conf für den Nginx-Container notwendig, auf die wir in diesem Rahmen nicht eingehen wollen.

Installationsvorgang

Die drei Docker-Container müssen mit den von uns ausgelieferten Dockerfiles erstellt und in Ihre von kubernetes verwendete Docker-Registry gepusht werden. Nachdem die Konfigurationsparameter und Secrets angepasst wurden sollten diese in Kubernetes angewendet werden. Außer der erstellung einer Datenbank und der Schematas übernimmt unser Service die restliche Konfiguration der Datenbank selbst, sobald der Service das erste Mal gestartet wird. Vor den Port 80 des Nginx-Containers sollten Sie bspw. einen Ingress-Controller setzen, der die SSL Terminierung übernimmt und den Port nach außen mit SSL gesichert exponiert. Weitere Ports auf unseren Service sind nicht notwending, da der Nginx-Container hier als Reverse-Proxy fungiert. Wenn Sie den Service erfolgreich installiert haben, können Sie drei Dinge tun um dessen Funktionsfähigkeit zu überprüfen. An der Root-URL auf den Service, sollten ein JSON mit Informationen zu dem Service und der installierten Version erscheinen. <Server URL>/auth sollte die Bedienoberfläche von Keycloak öffnen, in der Sie sich mit den Daten des initialen Admin-Benutzers einloggen können, wenn Sie auf “Administration Console” klicken. Hier können Sie auch andere Ident-Provider an unseren Service anbinden. Bswp. sind hier Active Directory per SAML und externe OAuth Provider zu nennen. Für weitere Informationen hierzu konsultieren Sie bitte die Dokumentation von Keycloak. Als letztes überprüfen Sie bitte, ob unter <Server URL>/commenting/administration/ unsere Bedienoberfläche für das Backend erscheint. Hier können Sie, mit einem gültigen Benutzer (bspw. wieder der Admin), bestehende Kommentare einsehen, diese bearbeiten und auch neue erstellen. Gleichzeitig haben Sie die Möglichkeit neue Benutzer zu erstellen und diese auf Kontextkombinationen zu berechtigen

  • , the three containers needed for our service are configured. In our example, these are all united in a pod and use temporary in-memory volumes. Of course, you are free to use other, for example persistent, volumes and to distribute the containers in different pods for better load balancing. However, in the case of the keycloak container, this requires a relatively complex configuration and an adaptation of the nginx.conf for the Nginx container, which we will not go into here.

Installation process

The three Docker containers have to be created with the Dockerfiles we deliver and pushed into your Docker registry used by kubernetes.

After the configuration parameters and secrets have been adjusted, they should be applied in Kubernetes. Apart from creating a database and the schemas, our service takes care of the rest of the configuration of the database itself once the service is started for the first time.

In front of port 80 of the Nginx container, for example, you should set an ingress controller that takes over the SSL termination and exposes the port to the outside secured with SSL. Further ports on our service are not necessary, as the Nginx container acts here as a reverse proxy.

After the first start, the client secret must be read from the Keycloak UI under <server URL>/auth for the "frontend" client. This should then be inserted into the Kubernetes secrets under "KEYCLOAK_CLIENT_SECRET". A subsequent restart of the containers is necessary.

Once you have successfully installed the service, there are three things you can do to check that it is working:

  • At the root URL to the service, a JSON should appear with information about the service and the installed version.

  • <Server URL>/auth should open the user interface of Keycloak, where you can log in with the initial admin user data by clicking on "Administration Console". Here you can also connect other ident providers to our service. For example, Active Directory via SAML and external OAuth providers. For more information, please consult the Keycloak documentation.

  • Finally, please check whether our user interface for the backend appears under <server URL>/commenting/administration/. Here you can, with a valid user (e.g. the admin again), view existing comments, edit them and also create new ones. You have the option of creating new users and authorising them to use context combinations.