Jupyter Notebooks mit Papermill in STACKIT Workflows ausführen

Voraussetzungen

• Sie verfügen über eine aktive STACKIT Workflows-Instanz. Siehe Workflow Instanz erstellen und verwalten.
• Sie haben ein Git-Repository mit Ihrer Workflows-Instanz verknüpft, das Ihre Notebooks enthält.
• Sie verfügen über einen STACKIT Object Storage Bucket (falls Sie die Ergebnisse Ihrer Notebook-Läufe dauerhaft speichern möchten).

In dieser Anleitung lernen Sie, wie Sie die Ausführung von Jupyter Notebooks mithilfe des STACKITSparkScriptOperator und Papermill automatisieren.

Übersicht der Papermill-Integration

Papermill ist ein Werkzeug zum Konfigurieren und Ausführen von Jupyter Notebooks. Innerhalb von STACKIT Workflows erkennt der STACKITSparkScriptOperator automatisch .ipynb-Dateien und nutzt Papermill, um diese als Spark-Jobs auszuführen. Dadurch können Sie Notebooks wie produktionsreife Daten-Pipelines behandeln.

Wenn Sie Notebooks entwickeln, die sowohl interaktiv in STACKIT Notebooks als auch automatisiert im Produktionsbetrieb über Papermill/Workflows laufen, können Sie die Umgebungsvariable STACKIT__PAPERMILL nutzen, um den aktuellen Ausführungskontext zu erkennen. Dies ermöglicht Ihnen die flexible Steuerung von Szenarien wie Secret-Management, Fortschrittsanzeigen oder Logging.

Konfiguration des Operators

Beim Ausführen eines Notebooks müssen Sie festlegen, wo die erzeugte Ausführungsversion (inklusive der Ergebnisse und Zell-Logs) gespeichert werden soll. Sie können das Ergebnis entweder in einen S3-kompatiblen Bucket schreiben oder die Ausgabe direkt in die Airflow-Task-Logs (stdout) leiten.

Einrichtung der Verbindung (Airflow Connection)

Um Ergebnisse in S3 zu speichern, stellen Sie sicher, dass eine Airflow Connection mit den Anmeldedaten Ihres Object Storage konfiguriert ist. In diesem Beispiel verwenden wir eine Connection ID namens s3_papermill_output.

Connection ID	Connection-Typ	Beschreibung
s3_papermill_output	S3	Zugangsdaten für den Ziel-Bucket, in dem die ausgeführten Notebooks gespeichert werden.
lakehouse-rest	HTTP/Custom	Vorkonfigurierte Verbindung für die Integration von STACKIT Lakehouse.

Implementierungsbeispiel

Der folgende DAG demonstriert zwei Aufgaben (Tasks): Eine, die das ausgeführte Notebook in S3 speichert, und eine weitere, welche die Ausgabe direkt in die Airflow-Task-Logs schreibt.

import pendulum
import os

from airflow.decorators import dag
from airflow.models.connection import Connection
from stackit_workflows.workflows_plugin.operators import STACKITSparkScriptOperator
from stackit_workflows import config

# S3-Zugangsdaten aus den Airflow Secrets abrufen
s3_connection = Connection.get_connection_from_secrets("s3_papermill_output")

@dag(
    schedule=None,
    start_date=pendulum.datetime(2021, 1, 1, tz="UTC"),
    catchup=False,
    tags=["demo"],
    dag_id="demo_jupyter_notebook",
)
def spark_full_configuration():

    output_s3 = STACKITSparkScriptOperator(
        task_id="papermill_s3",
        # Spezifisches Spark-Image angeben oder leer lassen für den Standard
        image="schwarzit-xx-sit-dp-customer-artifactory-docker-local.jfrog.io/stackit-spark:spark3.5.3-0.1.2",
        get_logs=True,
        # Explizit setzen oder durch den Operator durch Dateiendung automatisch erkennen lassen
        is_papermill=True,
        # Relativer Pfad innerhalb Ihres git-sync-Ordners
        script="Demo/scripts/my_spark_notebook.ipynb",
        # S3-Zielpfad für das ausgeführte Notebook
        papermill_target_folder="s3://internal-airflow-papermill-output/notebooks",
        s3_arguments={
            "AWS_ACCESS_KEY_ID": s3_connection.login,
            "AWS_SECRET_ACCESS_KEY": s3_connection.password,
            "BOTO3_ENDPOINT_URL": s3_connection.host
        },
        lakehouse_connections=["lakehouse-rest"],
    )

    output_stdout = STACKITSparkScriptOperator(
        task_id="papermill_stdout",
        image="schwarzit-xx-sit-dp-customer-artifactory-docker-local.jfrog.io/stackit-spark:spark3.5.3-0.1.2",
        get_logs=True,
        is_papermill=True,
        script="Demo/scripts/my_spark_notebook.ipynb",
        # Durch Angabe von "-" wird die JSON-Ausgabe des Notebooks in die Airflow-Logs geleitet
        papermill_target_folder="-",
        s3_arguments={
            "AWS_ACCESS_KEY_ID": s3_connection.login,
            "AWS_SECRET_ACCESS_KEY": s3_connection.password,
            "BOTO3_ENDPOINT_URL": s3_connection.host
        },
        lakehouse_connections=["lakehouse-rest"],
    )

    output_stdout >> output_s3

spark_full_configuration()

Ausführen des Workflows / DAG

1. Notebook hochladen

   Stellen Sie sicher, dass Ihre .ipynb-Datei in dem Git-Repository committet ist, das mit Ihrer STACKIT Workflows-Instanz verknüpft ist. Der Parameter script im Operator muss exakt mit dem relativen Pfad in Ihrem Repository übereinstimmen. Ein Beispiel-Notebook mit Spark und Papermill finden Sie unter Spark verwenden.

2. DAG hochladen

   Committen und pushen Sie den DAG, der das Notebook ausführt (siehe Beispiel oben), ebenso in Ihr Git-Repository. In unserem Beispiel heißt dieser demo_jupyter_notebook.

3. DAG ausführen

   Navigieren Sie zur Airflow-Benutzeroberfläche, suchen Sie nach demo_jupyter_notebook und starten Sie den DAG manuell.

4. Ausführung überwachen

   Gehen Sie auf die Aufgabe papermill_stdout und wählen Sie Logs. Sie können dort verfolgen, wie die Spark-Sitzung initialisiert wird und Papermill jede Zelle nacheinander ausführt.

5. Ergebnis überprüfen

   Sobald die Aufgabe papermill_s3 abgeschlossen ist, prüfen Sie Ihren (STACKIT) Object Storage Bucket. Dort finden Sie eine neue Notebook-Datei, die sowohl den ursprünglichen Code als auch alle generierten Zell-Ausgaben des Durchlaufs enthält.

Die Einstellung papermill_target_folder="-" eignet sich hervorragend zur Fehlersuche und zum Debuggen. Für Audits im Produktionsbetrieb sollten Sie Ihre Notebooks jedoch stets in S3 speichern, um einen historischen Verlauf aller Datenzustände aufzubewahren.