ProcessCube.ArtifactShipper

Neuauflage des BPMN.Shippers. Diesmal Artefakt-agnostisch (anfangs nur für BPMNs und Flows, später für mehr)

Verwendung

Scope

Aktuell unterstützt der ArtifactShipper das Deployen von BPMN-Dateien, sowie Lowcode-Flows aus dem lokalen Dateisystem (bspw. mounted oder config map) und Git-Repositories gegen ProcessCube.Engine und ProcessCube.LowCode.

Konfiguration

Der ArtifactShipper benötigt eine Config-Datei, die unter /config/config.json gemounted wird oder zu der der Pfad mit der Umgebungsvariable CONFIG_PATH angegeben werden kann. Anstelle einer Config-Datei können auch alle Werte mit Umgebungsvariablen nach der ProcessCube-typischen Syntax mit __-Seperatoren konfiguriert werden.

{
  "general": {
    "minLogLevel": "trace",
    // Das Verzeichnis, dass der interne git-Client zum Klonen der Repositories nutzt
    "gitWorkingDirectory": "/tmp/git",
  },
  // Hier können beliebig viele Credentials für eine client_credentials-Anmeldung mittels OpenID gegen eine Authority hinterlegt werden
  "credentials": {
    // Der Name, mit dem die Credentials unter Targets zur Authorisierung beim Deployment referenziert werden können
    "authorityClient": {
      // Optional: Für OpenID. Die clientId, die in der Authority hinterlegt sein muss
      "clientId": "artifact_shipper",
      // Optional: Für OpenID. Das clientSecret, dass passend zur clientId in der Authority hinterlegt sein muss
      "clientSecret": "artifact_shipper",
      // Optional: Für OpenID. Die Scopes, die angefragt werden, um die nötigen Rechte für ein Deployment zu erhalten
      "scope": "engine_read engine_write",
      // Optional: Für OpenID. Wenn angegeben, werden die Credentials gegen die angegebene Adresse authorisiert. Andernfalls versucht der Shipper die Adresse der Authority automatisch anhand der TargetUrl (bspw. Engine zu ermitteln). Für lowcode-Targets *muss* die authorityUrl angegeben werden, weil die Lowcode-Plattform Stand heute keine Authority-URL exportiert.
      "authorityUrl": "http://authority.localhost",
    },
    "gitToken": {
      // Optional: Es kann auch einfach ein gültiger Token angegeben werden
      "token": "eyQWEGHHHHH324ye",
    },
  },
  // Hier können beliebig viele Artefakt-Sources definiert werden, aus denen BPMNs (und später auch JSON oder DMNs) bezogen werden
  "artifacts": {
    // Der Name, mit dem die Artefakte von dieser Quelle beim Deployen unter 'targets' referenziert werden
    "local": {
      // Ein Menge von glob Dateipfaden zu einem Ordner oder mehreren Dateien mit der Endung .bpmn. Kann als Array oder einzelner String angegeben werden. Für glob-Syntax "siehe": https://www.npmjs.com/package/fast-glob#pattern-syntax
      "sourcePaths": "/tmp/processes/*.bpmn",
      // 'bpmn', 'json', 'yaml' oder 'yml' (equivalent) - Art des Artefakts.
      "artifactType": "bpmn",
    },
    "localFlows": {
      // Ein Glob, der nach .json Dateien sucht, wie sie für flows verwendet werden
      "sourcePaths": "/tmp/flows/**/*.json",
      "artifactType": "json",
    },
    "gitSource": {
      // Es können auch mehrere Pfade angegeben werden
      "sourcePaths": ["processes/Parent.bpmn", "processes/child.bpmn"],
      "artifactType": "bpmn",
      // Optional: Eine Referenz auf ein unter der Konfiguration 'credentials' definierte Credentials für die Authorisierung
      "credentials": "gitToken",
      // Optional: Wenn angegeben, wird nach dem sourcePath in dem angegebenen git-Repository gesucht. "Hinweis": Hier muss die https:// URL zu dem Repository verwendet werden
      "gitRepository": "https://github.com/5minds/ProcessCube.ArtifactShipper.git",
      // Optional: Gibt die Revision an, die bei gitRepository verwendet werden soll. Andernfalls wird der defaultBranch verwendet. Revision kann entweder ein Branch oder Tag sein
      "gitRevision": "feature/test_shipping_from_git",
    },
    "anotherGitSource": {
      // Es können directories verwendet werden
      "sourcePaths": ["processes"],
      "artifactType": "bpmn",
      "credentials": "gitToken",
      "gitRepository": "https://github.com/5minds/ProcessCube.ArtifactShipper.git",
      "gitRevision": "feature/test_shipping_from_git",
    },
    "yamlSource": {
      "sourcePaths": ["flows/yaml"],
      // Es wird nach Dateien mit den Endungen 'yaml' und 'yml' gesucht
      "artifactType": "yaml",
      "credentials": "gitToken",
      "gitRepository": "https://github.com/5minds/ProcessCube.ArtifactShipper.git",
      "gitRevision": "feature/test_shipping_from_git",
      // Der hier definierte Preprocessor wird vor dem Deployment aufgerufen, um die SRC-Files zu transformieren. In dem Fall Flows von yaml nach json
      "preprocessor": "flowRewriter",
    }
  },
  // Preprocessor definieren API-Endpunkte, die vor einem Deployment aufgerufen werden, um die Artefakte zu transformieren oder ähnliche Operationen auszuführen
  // Der hier verwendete Preprocessor "flowRewriter" konvertiert eine Liste von Node-Red-Flows im yaml-Format in eine Liste von Node-Red-Flows im json-Format
  "preprocessors": {
    "flowRewriter": {
      "url": "http://flowrewriter:14060/api/converter/convert?outputFormat=json"
    }
  },
  // Hier können beliebig viele Targets definiert werden, zu denen Artefakte aus der 'artifacts'-Konfiguration deployed werden
  "targets": {
    // Der Name des Targets, wie es im Log auftaucht
    "engine": {
      // Eine Menge von URLs, gegen die deployed wird. Kann als Array oder einzelner String angegeben werden
      "targetPaths": "http://engine.localhost",
      // Mögliche Typen sind 'engine', 'lowcode' und 'filesystem'
      "targetType": "engine",
      // Eine Referenz auf ein unter der Konfiguration 'artifacts' definiertes Artefakt. Für den Target-Type 'engine' müssen hier .bpmn-Dateien verwendet werden
      "artifacts": ["local", "gitSource"],
      // Optional: Eine Referenz auf ein unter der Konfiguration 'credentials' definierte Credentials für die Authorisierung
      "credentials": "authorityClient",
      // Optional, Default 'merge'
      // merge: Fügt neue hinzu und überschreibt bestehende, aber löscht keine Artefakte
      // replace: Löscht alle bestehenden und fügt danach neue Artefakte hinzu
      "strategy": "merge"
    },
    "lowcode": {
      "targetPaths": "http://lowcode.localhost",
      "targetType": "lowcode",
      // Für den Target-Type 'lowcode' müssen hier .json-Dateien als artifacts angegeben werden
      "artifacts": "localFlows",
      "credentials": "authorityClient",
      "strategy": "replace"
    },
      "filesystem": {
      "targetPaths": "/tmp/out",
      // Der Filesystem-Target-Type kopiert die Dateien an die Zielfpade im Container des ArtifactShippers. Als Init-Container kann der ArtifactShipper so in ein gemeinsam genutztes Mount schreiben, dass der nachfolgende Container nutzen kann. Siehe https://kubernetes.io/docs/tasks/configure-pod-container/configure-pod-initialization/#create-a-pod-that-has-an-init-container und https://github.com/5minds/ProcessCube.ArtifactShipper/blob/develop/deployment/ProcessCube.LowCode/deployment.yaml#L25-L40 bzw https://github.com/5minds/ProcessCube.ArtifactShipper/blob/develop/deployment/ProcessCube.Engine/deployment.yaml#L20-L35
      "targetType": "filesystem",
      // Optional, default 'false'
      // Wenn true, wird die Verzeichnis-Struktur des Src-Folders ignoriert und alle Dateien ohne Struktur in das Target-Folder gelegt
      // Andernfalls wird die gleiche Verzeichnis-Struktur aus dem Src-Folder übernommen und im Target-Folder erstellt
      "flatten": "false",
      "artifacts": "yamlSource"
    },
  },
}

Deployment

Empfehlenswert ist es den Shipper als Kubernetes-Ressource 'Job' in ein bestehendes ProcessCube-Setup oder als Teil des ProcessCube-Setups zu deployen. Als Orientierungshilfe kann dafür die job.yaml unter ./deployment/ProcessCube.ArtifactShipper/job.yaml dienen.

Entwicklung

Vorraussetzungen zur Entwicklng

• Skaffold installieren: https://skaffold.dev/
• Docker Desktop mit Kubernetes installieren: https://docs.docker.com/desktop/kubernetes/
• NGINX Ingress in Docker Desktop Kubernetes Cluster installieren: https://kubernetes.github.io/ingress-nginx/deploy/#quick-start

# WICHTIG: Vorher sicherstellen, dass der richtige Kubernetes-Context verwendet wird, damit die Installation auch ins lokale Cluster erfolgt
kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-v1.11.2/deploy/static/provider/cloud/deploy.yaml

Engine ist erreichbar unter http://engine.localhost, Authority ist erreichbar unter http://authority.localhost

Docker Credentials / regcred

Für das Deployment des low-code-Images werden Docker Credentials benötigt. Beim Ausführen von skaffold dev werden diese automatisch aus den Umgebungsvariablen verwendet:

export DOCKER_USERNAME=""
export DOCKER_PASSWORD=""
export DOCKER_EMAIL=""

Als Password empfiehlt sich ein read-only-PAT. Dieses kann entweder selbst generiert oder aus dem 1Password-Tresor Infrastruktur -> DockerHub -> Read-Only-PAT for CI-Purposes verwendet werden.

Git Token

Falls ein git Token verwendet werden soll, um bspw. git als Source zu testen, so sucht das Test-Setup nach der Environment-Variable GIT_TOKEN. Wenn diese gesetzt ist, wird sie automatisch für die Credentials git als Token gesetzt. Als Token wird am besten ein PAT mit Repo-Leserechten verwendet.

export GIT_TOKEN=""

Intellisense

Um Intellisense in der IDE nutzen zu können, müssen die NPM-Pakete einmal lokal installiert werden:

npm ci

Ausführung der Dev-Umgebung

# Wenn alle nötigen Umgebungsvariablen bereits exportiert sind
skaffold dev

```sh
# Falls die nötigen Umgebungsvariablen noch exportiert werden müssen
export DOCKER_USERNAME=""
export DOCKER_PASSWORD=""
export DOCKER_EMAIL=""
export GIT_TOKEN=""
skaffold dev

Artifact Shipper Job mit anderen Konfigurationen neu ausführen

1. deployment/ProcessCube.ArtifactShipper/config.json editieren

2. Datei speichern. So lange skaffold dev läuft, sollte der Job mit der neuen Konfiguration gebaut und gestartet werden. Manchmal kann es vorkommen, dass Skaffold das Deployment ausführen will, bevor das neue Image gebaut wurde. Dann gibt es einen Fehler, dass das Image nicht gepullt werden kann. Leider noch keine einfache Möglichkeit gefunden das Problem zu beheben. In dem Fall die Config Datei einfach nochmal editieren und speichern.