Konzepte

Diese Seite bietet detaillierte Informationen zu den wichtigsten Konzepten und Konfigurationen für STACKIT Workflows.

DAGs-Repository

STACKIT Workflows erkennt und lädt DAGs automatisch aus Ihrem verbundenen Git-Repository. Der Dienst fragt Ihr Repository kontinuierlich nach (hochgeladenen) Änderungen ab und synchronisiert DAG-Dateien, um Ihre Workflows auf dem neuesten Stand zu halten. Airflow parst automatisch alle Python-Dateien in Ihrem Repository, die sowohl das Wort airflow als auch DAG enthalten, als potenzielle DAGs.

Die ideale Struktur des Git-Repositorys variiert je nach Anwendungsfall. Eine typische Struktur könnte wie folgt aussehen:

your-dags-repo/
├── dags/                        # Verzeichnis für DAG-Dateien
│   ├── data_pipeline_dag.py
│   ├── ml_training_dag.py
│   ├── maintenance_dag.py
│   └── tasks/                   # Optionales Modul, das die Geschäftslogik enthält.
│       ├── clean_timestamps.py  # Importieren Sie hier für Python- oder Spark-Jobs aber nichts aus Airflow.
│       └── compute_stats.py     # (sollte nicht die Wörter "airflow" oder "DAG" enthalten)
├── include/
│   └── sql
│       └── kpi_revenue.sql
├── plugins/                    # Für alle benutzerdefinierten oder Community-Airflow-Plugins
│   └── custom_operators.py
└── README.md

Als Best-Practice empfehlen wir, die Orchestrierungslogik (DAGs, Airflow-Tasks) von der Geschäftslogik (in der Datenbank ausgeführte SQL, Python-Skripte zur Datenverarbeitung != DAG / Task-Definition, Spark-Logik usw.) zu trennen. Dies erleichtert das Testen und Verwalten Ihres Codes, da Geschäftslogik-Funktionen unabhängig von Airflow getestet werden können, zum Beispiel im Dienst STACKIT Notebooks. Um Geschäfts- von Orchestrierungslogik zu trennen, legen Sie die Geschäftslogik in separate Python-Dateien (z. B. compute_stats.py oder kpi_revenue.sql im obigen Beispiel), die keine Referenzen auf Airflow oder DAGs enthalten. Diese Dateien können dann in Ihre DAG-Dateien importiert und verwendet werden. Alternativ kann die Geschäftslogik auch in separaten Git-Repositories liegen, die pro Task über die Parameter git_sync_* des STACKITPythonScriptOperator oder des Decorators @stackit.workflows_python_kubernetes_task konfiguriert werden können.

Verfügbare Pakete / Operatoren

STACKIT Workflows wird mit einer breiten Palette an vorinstallierten Python-Paketen und Airflow-Operatoren ausgeliefert, die Sie bei der Erstellung Ihrer Workflows unterstützen. Die Umgebung umfasst die folgenden Standard-Airflow-Provider:

apache-airflow-providers-amazon
apache-airflow-providers-celery
apache-airflow-providers-cncf-kubernetes
apache-airflow-providers-databricks
apache-airflow-providers-elasticsearch
apache-airflow-providers-fab
apache-airflow-providers-ftp
apache-airflow-providers-google
apache-airflow-providers-grpc
apache-airflow-providers-hashicorp
apache-airflow-providers-http
apache-airflow-providers-imap
apache-airflow-providers-microsoft-mssql
apache-airflow-providers-microsoft
apache-airflow-providers-mongo
apache-airflow-providers-mysql
apache-airflow-providers-odbc
apache-airflow-providers-openlineage
apache-airflow-providers-postgres
apache-airflow-providers-redis
apache-airflow-providers-sftp
apache-airflow-providers-slack
apache-airflow-providers-smtp
apache-airflow-providers-snowflake
apache-airflow-providers-sqlite
apache-airflow-providers-ssh

Zusätzlich enthält die Umgebung das Provider-Paket stackit_workflows, das die Ausführung von Python- und Spark-Jobs von der Workflows-Instanz aus vereinfacht:

@stackit_python_kubernetes_task: Airflow-Task-Decorator, um die dekorierte Python-Funktion auf Kubernetes im standardmäßigen STACKIT Python-Runtime-Image auszuführen.
STACKITPythonScriptOperator: Airflow-Operator, der ein Python-Skript im standardmäßigen STACKIT Python-Runtime-Image ausführt.
@stackit_spark_kubernetes_task: Airflow-Task-Decorator, um die dekorierte Python-Funktion auf Kubernetes im STACKIT Spark-Runtime-Image auszuführen, in dem Spark und die stackit_spark-Pakete vorinstalliert sind.
STACKITSparkScriptOperator: Airflow-Operator zur Ausführung eines bereitgestellten PySpark-Skripts im STACKIT Spark-Runtime-Image.

Beispiele für die Verwendung finden Sie im Abschnitt Tutorials.

Alle Pakete werden aktuell gehalten und gewartet, um Kompatibilität und Sicherheit zu gewährleisten. Die vollständige Liste der Versionen finden Sie im Package-Manifest in Ihrer Umgebung. Dieses kann durch Starten der DAGs Development Environment (DDE) und Ausführen von pip freeze in einem Terminal abgerufen werden. Bitte beachten Sie, dass Pakete mit jedem neuen Workflows-Release aktualisiert werden.

Integration von Monitoring / Observability

Wenn das Monitoring für eine Workflows-Instanz aktiviert ist, werden Metriken von allen Tasks, die von DAGs gestartet werden, sowie Core-Airflow-Metriken an die ausgewählte STACKIT Observability-Instanz weitergeleitet. Ein vorkonfiguriertes Grafana-Dashboard steht zur Visualisierung dieser Metriken zur Verfügung.

Zusätzlich zu gängigen Container-Metriken wie CPU- und Speichernutzung pro Task sind auch Airflow-spezifische aggregierte Metriken verfügbar. Eine detaillierte Beschreibung finden Sie in der Dokumentation zur Airflow-Metriken-Beschreibung.

Rollen im STACKIT Portal

Die folgenden Rollen sind im STACKIT Portal zur Verwaltung von Workflows-Instanzen verfügbar:

Workflows Admin: Vollständiger administrativer Zugriff auf alle STACKIT Workflows-Ressourcen.
Workflows Editor: Berechtigungen zum Erstellen, Ändern und Verwalten von STACKIT Workflows-Unterressourcen (DAGs-Repository, Konfiguration des Identitätsanbieters usw.).
Workflows Reader: Lesezugriff auf alle STACKIT Workflows-Ressourcen.

Diese Berechtigungen werden über das STACKIT Portal und die STACKIT API verwaltet.

Rollen in der Airflow-UI

Die Berechtigungen innerhalb der Airflow-UI sind von der Zugriffssteuerung im STACKIT Portal getrennt. Der Zugriff auf die Airflow-UI wird über die rollenbasierte Zugriffssteuerung (RBAC) unter Verwendung Ihres verbundenen Identitätsanbieters (IdP) verwaltet.

Wenn sich Benutzer anmelden, werden ihre Rollen aus dem vom IdP bereitgestellten Authentifizierungstoken extrahiert. Diese Rollen bestimmen, worauf Benutzer innerhalb der Airflow-Oberfläche zugreifen und was sie dort ausführen können. Detaillierte Konfigurationsanweisungen finden Sie im Abschnitt Identitätsanbieter.

Die folgenden Rollen sind innerhalb von Airflow verfügbar:

Admin: Vollständiger Zugriff auf alle Airflow-Funktionen, Einstellungen und Konfigurationen.
User: Kann DAGs anzeigen und auslösen, aber keine Systemeinstellungen oder Konfigurationen ändern.
Viewer: Lesezugriff zum Anzeigen von DAGs und deren Ausführungsstatus.

Preisgestaltung

Die Preisgestaltung von STACKIT Workflows setzt sich aus einer festen monatlichen Gebühr für die Workflows-Instanz zusammen, die alle Core-Airflow-Komponenten wie den Scheduler, Webserver, die Metadaten-Datenbank und den Log-Speicher enthält. Zusätzlich wird jeder ausgeführte Task in einem dedizierten Kubernetes-Pod gestartet, was zusätzliche Kosten basierend auf den zugewiesenen Ressourcen (CPU, Speicher, Dauer) verursacht. Detaillierte Informationen zur Preisgestaltung finden Sie im Bestellprozess im STACKIT Portal.

Identitätsanbieter

STACKIT Workflows lässt sich in externe OIDC-fähige Identitätsanbieter (IdP) integrieren, um die Benutzerauthentifizierung und -autorisierung zu verwalten. Dies ermöglicht es Unternehmen, ihre vorhandenen Identitätsmanagementsysteme für den sicheren Zugriff auf Airflow zu nutzen.

Entra ID (Azure)

Um Entra ID (ehemals Azure AD) als Ihren Identitätsanbieter zu konfigurieren, folgen Sie diesen Schritten:

Erstellen Sie eine neue “App-Registrierung”
- Name: Beliebig wählen, für dieses Beispiel wählen wir STACKIT Workflows (dev)
- Unterstützte Kontotypen: Wählen Sie für typische Bereitstellungen “Nur Konten in diesem Organisationsverzeichnis” (einzelner Mandant)
- Umleitungs-URI: Vorerst leer lassen, wir werden sie später festlegen. Klicken Sie auf “Registrieren”, um die Anwendung zu erstellen.
Notieren Sie sich auf der Seite “Übersicht” der “App-Registrierung” die Anwendungs-ID (Client). Notieren Sie sich auch die Verzeichnis-ID (Mandant).
Navigieren Sie zu “Verwalten” -> “Zertifikate & Geheimnisse” und erstellen Sie ein neues “Client-Geheimnis”. Notieren Sie sich den generierten “Wert” (nicht die Geheimnis-ID), da dieser nur einmal angezeigt wird.
Geben Sie im STACKIT Portal die folgenden Werte im Abschnitt zur Konfiguration des Identitätsanbieters ein:
- Name des Identitätsanbieters: Azure
- Client-ID: Die Anwendungs-ID (Client) aus Schritt 2
- Client-Secret: Der “Wert” des in Schritt 3 erstellten Client-Geheimnisses.
- Scopes: openid email
- Discovery-Endpunkt: https://login.microsoftonline.com/<Verzeichnis-ID (Mandant)>/.well-known/openid-configuration (ersetzen Sie <Verzeichnis-ID (Mandant)> durch den Wert aus Schritt 2)

Nachdem die Workflows-Instanz erstellt wurde, navigieren Sie zur Workflows-Instanz im STACKIT Portal und kopieren Sie die “Redirect-URL” aus dem Abschnitt “Identitätsanbieter”. Gehen Sie zurück zur “App-Registrierung” in Entra ID und navigieren Sie zu “Verwalten” -> “Authentifizierung”. Fügen Sie eine neue Plattform “Web” hinzu und geben Sie die kopierte “Redirect-URL” ein. Speichern Sie die Änderungen.

Abschließend müssen wir Benutzern oder Gruppen in Entra ID Rollen zuweisen, damit ausgewählte Benutzer auf Airflow zugreifen können. Navigieren Sie zu “Verwalten” -> “App-Rollen” und erstellen Sie die folgenden Rollen. Wir empfehlen, mindestens die Rolle “Admin” zu erstellen, andere Rollen können bei Bedarf erstellt werden. Die verfügbaren Berechtigungen für jede Rolle sind in der Airflow-Dokumentation dokumentiert.

Anzeigename	Zulässige Mitgliedstypen	Wert	Beschreibung
Admin	Benutzer/Gruppen & Anwendungen	Admin	Workflows-Administrator
Viewer	Benutzer/Gruppen & Anwendungen	Viewer	Workflows-Viewer
User	Benutzer/Gruppen & Anwendungen	User	Workflows-Benutzer
Op	Benutzer/Gruppen & Anwendungen	Op	Workflows-Op

Schließlich müssen wir die erstellten Rollen Benutzern oder Gruppen zuweisen. Navigieren Sie zur Seite “Übersicht” der “App-Registrierung” und klicken Sie auf den Namen der Enterprise-Anwendung neben der Bezeichnung “Verwaltete Anwendung im lokalen Verzeichnis”. Gehen Sie zu “Verwalten” -> “Benutzer und Gruppen” und weisen Sie den Benutzern oder Gruppen die erstellten Rollen nach Bedarf zu.

Okta

Um Okta als Ihren Identitätsanbieter zu konfigurieren, folgen Sie diesen Schritten:

Wählen Sie im Menü “Applications” die Option “Create App Integration”. Wählen Sie “OIDC - OpenID Connect” als Anmeldemethode und “Web Application” als Anwendungstyp. Klicken Sie auf “Next”.
Konfigurieren Sie die folgenden Einstellungen:
- App integration name: Beliebig wählen, für dieses Beispiel wählen wir STACKIT Workflows (dev)
- Sign-in redirect URIs: Vorerst leer lassen, wir werden sie später festlegen.
- Assignments: Wählen Sie “Assign to people only” oder “Assign to groups only” basierend auf Ihren Anforderungen. Sie können auch “No assignment required” wählen, um allen Benutzern in Ihrer Okta-Organisation den Zugriff auf die Anwendung zu ermöglichen. Klicken Sie auf “Save”, um die Anwendung zu erstellen.
Notieren Sie sich im Tab “General” der erstellten Anwendung die Client ID und das Client Secret.
Geben Sie im STACKIT Portal die folgenden Werte im Abschnitt zur Konfiguration des Identitätsanbieters ein:
- Name des Identitätsanbieters: Okta
- Client-ID: Die Client ID aus Schritt 2
- Client-Secret: Das Client Secret aus Schritt 2
- Scopes: openid email
- Discovery-Endpunkt: https://<ihre-okta-domain>/.well-known/openid-configuration (ersetzen Sie <ihre-okta-domain> durch Ihre Okta-Domain)

Nachdem die Workflows-Instanz erstellt wurde, navigieren Sie zur Workflows-Instanz im STACKIT Portal und kopieren Sie die “Redirect-URL” aus dem Abschnitt “Identitätsanbieter”. Gehen Sie zurück zur Okta Developer Console und bearbeiten Sie die erstellte Anwendung. Fügen Sie die kopierte “Redirect-URL” zu den “Sign-in redirect URIs” hinzu. Speichern Sie die Änderungen.

Nun müssen wir Rollen in STACKIT Workflows Benutzern oder Gruppen in Okta zuweisen:

Wählen Sie im Menü “Directory” die Option “Profile Editor”. Wählen Sie die zuvor erstellte Anwendung aus.
Wählen Sie “Add Attribute” und erstellen Sie ein neues Attribut mit den folgenden Einstellungen:
- Type: string
- Display name: STACKIT Workflows Roles
- Variable name: roles
- Enum: ja (ausgewählt) – Erstellen Sie die folgenden Enums mit identischen Werten und Anzeigenamen: Admin, User, Viewer, Op
- Description: Roles for STACKIT Workflows
- Attribute required: ja (ausgewählt)
- Attribute type: Je nach Bedarf, in diesem Beispiel verwenden wir “Group”
Navigieren Sie nach dem Speichern des Attributs zu “Directory” -> “Groups” und wählen Sie eine Gruppe aus. Wählen Sie den Tab “Applications” und klicken Sie auf “Assign Applications”. Wählen Sie die zuvor erstellte Anwendung aus und weisen Sie der Gruppe die gewünschte Rolle zu. Wiederholen Sie diesen Schritt für alle Gruppen, die Zugriff auf STACKIT Workflows benötigen.

Keycloak

Um Keycloak als Ihren Identitätsanbieter zu konfigurieren, folgen Sie diesen Schritten:

Navigieren Sie in der Keycloak-Administrationskonsole zu Ihrem Realm und gehen Sie zu “Clients”. Klicken Sie auf “Create client”.
Konfigurieren Sie die Client-Einstellungen:
- Client type: OpenID Connect
- Client ID: Beliebig wählen, für dieses Beispiel verwenden wir stackit-workflows-dev
- Name: Beliebig wählen, für dieses Beispiel verwenden wir STACKIT Workflows (dev)
- Klicken Sie auf “Next”
Konfigurieren Sie die Capability-Einstellungen:
- Client authentication: On (um ein Client-Secret zu erhalten) – Workflows ist ein vertraulicher / privater Client
- Authorization: Off
- Authentication flow: Wählen Sie “Standard flow” und “Direct access grants” aus
- Klicken Sie auf “Next”
Login-Einstellungen:
- Web origins: +
- Lassen Sie andere Felder vorerst leer, wir werden die Redirect-URI später festlegen.
- Klicken Sie auf “Save”
Notieren Sie sich im Tab “Credentials” des erstellten Clients das Client secret.
Geben Sie im STACKIT Portal die folgenden Werte im Abschnitt zur Konfiguration des Identitätsanbieters ein:
- Name des Identitätsanbieters: keycloak
- Client-ID: Die Client-ID aus Schritt 2 (z. B. stackit-workflows-dev)
- Client-Secret: Das Client-Secret aus Schritt 5
- Scopes: openid email
- Discovery-Endpunkt: https://<ihre-keycloak-domain>/realms/<realm-name>/.well-known/openid-configuration (ersetzen Sie <ihre-keycloak-domain> und <realm-name> durch Ihre Werte)

Nachdem die Workflows-Instanz erstellt wurde, navigieren Sie zur Workflows-Instanz im STACKIT Portal und kopieren Sie die “Redirect-URL” aus dem Abschnitt “Identitätsanbieter”. Gehen Sie zurück zu Keycloak und bearbeiten Sie den erstellten Client. Fügen Sie die kopierte “Redirect-URL” in das Feld “Valid redirect URIs” ein. Speichern Sie die Änderungen.

So weisen Sie Benutzern in Keycloak Rollen zu:

Navigieren Sie zu “Realm roles” und erstellen Sie die folgenden Rollen:
- Admin – Workflows-Administrator
- User – Workflows-Benutzer
- Viewer – Workflows-Viewer
- Op – Workflows-Op
Navigieren Sie zu “Users” und wählen Sie einen Benutzer aus. Gehen Sie zum Tab “Role mapping” und weisen Sie dem Benutzer die entsprechenden Realm-Rollen zu.
Damit die Rollen im Token enthalten sind, gehen Sie zu “Client scopes” → “roles” → “Mappers” und stellen Sie sicher, dass der Mapper “realm roles” wie folgt konfiguriert ist:
- Token Claim Name: roles
- Add to ID token: On
- Add to access token: On
- Add to userinfo: On

Alternativ können Sie Gruppen erstellen und den Gruppen Rollen zuweisen und anschließend Benutzer den Gruppen zuweisen, um die Verwaltung zu vereinfachen.