Looker-CI/CD-Nutzung und -Workflow

Auf dieser Seite wird beschrieben, wie Sie einen CI/CD-Workflow in Looker verwenden, nachdem er installiert und konfiguriert wurde.

In dieser Anleitung wird ein dreistufiges System verwendet, das aus Entwicklung, Qualitätssicherung und Produktion besteht. Sie können die gleichen Prinzipien jedoch auch auf ein Zwei- oder Vier-Stufen-System anwenden.

In dieser Anleitung wird auch davon ausgegangen, dass Sie GitHub als Git-Anbieter verwenden. Sie können andere Git-Anbieter verwenden, um einen CI/CD-Workflow zu erstellen. Sie müssen jedoch über das Fachwissen verfügen, um diese Anleitung für Ihren Anbieter zu ändern.

Workflowübersicht

LookML-Entwickler beginnen damit, Code in ihrem Entwicklungszweig zu schreiben, der normalerweise einen Namen wie dev-my-user-ydnv hat. Sie testen ihre Änderungen mit Spectacles und committen ihren Code. Schließlich erstellen sie eine Pull-Anfrage, um ihren Code mit dem main-Zweig zusammenzuführen.

Wenn die Pull-Anfrage geöffnet wird, wird der Entwickler zu GitHub weitergeleitet. Der Entwickler sollte einen aussagekräftigen PR-Titel im Stil von Conventional Commits schreiben und der Beschreibung einen Kommentar hinzufügen, der im Changelog enthalten sein soll. Die Ergebnisse der Spectacles-Tests sollten als Kommentare zum PR hinzugefügt werden.

Als Nächstes sollte der Entwickler in GitHub einen Prüfer auswählen. Der Prüfer wird benachrichtigt und kann seine Rezension dem Pull-Request hinzufügen. Wenn der Prüfer die Änderung genehmigt, wird die Pull-Anfrage mit dem main-Zweig zusammengeführt. Ein WebHook wird aufgerufen und die Änderung ist jetzt in der Entwicklungsumgebung sichtbar.

Die Release Please-Automatisierung wird automatisch ausgeführt und öffnet einen zweiten PR, um einen neuen getaggten Release zu erstellen. Wenn bereits eine Pull-Anfrage für diesen Zweck geöffnet ist, wird sie von Release Please aktualisiert. Die Release-PR hat eine Versionsnummer und ein Changelog mit den Titeln und Beschreibungen der enthaltenen Änderungen.

Wenn der von Release Please generierte PR genehmigt und zusammengeführt wird, wird ein neues Versions-Tag generiert und das Changelog wird mit dem main-Branch zusammengeführt. Die QA- und Produktionsinstanzen von Looker können diese Version über den erweiterten Bereitstellungsmodus auswählen.

Best Practices für die Nummerierung von Releases und die Benennung von Commits

Die Releases und die zugehörigen Tags können beliebig benannt und nummeriert werden. Hier wird jedoch die semantische Versionsverwaltung verwendet, die dringend empfohlen wird, da sie gut mit dem Release Please-Plug-in funktioniert.

Bei der semantischen Versionierung besteht die Version aus drei Zahlen, die durch Punkte getrennt sind: MAJOR.MINOR.PATCH

  • PATCH wird jedes Mal erhöht, wenn in einer Version ein Fehler behoben wird.
  • MINOR wird erhöht und PATCH wird auf null zurückgesetzt, wenn in der Version eine Funktion hinzugefügt oder verbessert wird, die abwärtskompatibel ist.
  • MAJOR wird inkrementiert und sowohl MINOR als auch PATCH werden auf null gesetzt, wenn ein Feature hinzugefügt wird, das nicht abwärtskompatibel ist.

Conventional Commits ist ein System zum Benennen von Commits nach ihrer Auswirkung auf Endnutzer. Die Verwendung von konventionellen Commit-Namen ist zwar nicht erforderlich, aber auch für das Release Please-Plug-in nützlich.

Bei der herkömmlichen Commit-Benennung wird jeder Commit-Nachricht ein Indikator für den Umfang der Änderung vorangestellt:

  • Eine Fehlerkorrektur wird mit fix: gekennzeichnet, z. B. fix: set proper currency symbol on sale_amt format.
  • Eine neue Funktion wird mit feat: gekennzeichnet, z. B. feat: added explore for sales by territory.
  • Eine Funktion mit einer grundlegenden Änderung wird durch feat!: wie feat!: rewrote sales explore to use the new calendar view gekennzeichnet.
  • Wenn die Dokumentation aktualisiert, aber LookML nicht geändert wird, beginnt die Commit-Nachricht mit doc:.

Wenn Conventional Commits konsistent verwendet werden, ist es in der Regel einfach, die nächste semantische Nummer zu bestimmen. Wenn das Commit-Log nur aus fix:- und doc:-Commits besteht, sollte PATCH erhöht werden. Wenn es einen feat:-Commit gibt, sollte MINOR inkrementiert werden. Wenn ein feat!: vorhanden ist, sollte MAJOR inkrementiert werden. Das Release Please-Plug-in kann sogar eine CHANGELOG-Datei generieren und das Release automatisch taggen.

Erweiterten Bereitstellungsmodus verwenden

Nachdem Änderungen vorgenommen und als Pull-Request in der Entwicklungsinstanz eingereicht wurden, kennzeichnet das Release Please-Plug-in die Änderungen mit einem Versionstag wie v1.2.3. Im erweiterten Bereitstellungsmodus von Looker werden diese Versionen dann in der Looker-Benutzeroberfläche für die QA- und Produktionsinstanzen verfügbar gemacht.

So stellen Sie eine Änderung bereit:

Speicherort von Looker Deployment Manager in der IDE.

Klicken Sie rechts oben im Deployment Manager auf den Link Select Commit (Commit auswählen). Wählen Sie dann das Dreipunkt-Menü für das Tag aus, das Sie bereitstellen möchten, und wählen Sie In Umgebung bereitstellen aus:

Looker Deployment Manager-Benutzeroberfläche für die Bereitstellung in der Umgebung

Sie müssen die Bereitstellung nicht noch einmal taggen. Wählen Sie Ohne Tagging bereitstellen aus und klicken Sie auf die Schaltfläche In Umgebung bereitstellen:

Looker Deployment Manager-UI für die Bereitstellung ohne Tagging.

Stellen Sie die Änderungen schließlich mit Deployment Manager in der Produktion bereit.

Spectacles verwenden

Spectacles können von jedem Entwickler verwendet werden, um Änderungen zu überprüfen, während sie sich noch im Entwicklungszweig befinden. Spectacles bietet vier verschiedene Validatoren:

Wenn ein Entwickler einen Pull-Request einreicht, ist es ratsam, diese Tests auszuführen und die Ergebnisse in einen Kommentar im PR zu kopieren.

SQL-Validator

Mit dem SQL-Validator wird jedes Explore getestet, um zu prüfen, ob alle in LookML-Ansichten definierten Felder tatsächlichen SQL-Spalten oder gültigen SQL-Ausdrücken in der Datenbank entsprechen. Der SQL-Validator wird wie folgt aufgerufen:

$ spectacles sql --config-file config-dev.yaml \
    --project PROJECT_NAME \
    --explores MODEL_NAME/EXPLORE_NAME \
    --branch DEV_BRANCH_NAME

Beispiel:

$ spectacles sql --config-file config-dev.yaml \
    --project thelook_cicd \
    --explores thelook_cicd/users \
    --branch dev-my-user-ydnv

Connected to Looker version 23.18.60 using Looker API 4.0

=================== Testing 1/1 explores [concurrency = 10] ===================

✓ thelook_cicd.users passed

Completed SQL validation in 1 minute and 7 seconds.

LookML-Validator

Mit dem LookML-Validator wird geprüft, ob LookML-Änderungen gültig sind und keine Syntaxfehler enthalten. Sie wird wie folgt aufgerufen:

$ spectacles lookml --config-file config-dev.yaml \
    --project PROJECT_NAME \
    --branch DEV_BRANCH_NAME

Beispiel:

$ spectacles lookml --config-file config-dev.yaml \
    --project thelook_cicd \
    --branch dev-my-user-ydnv

Connected to Looker version 23.18.60 using Looker API 4.0

============= Validating LookML in project thelook_cicd [warning] ==============

✗ thelook_cicd/business_pulse.dashboard.lookml failed
✗ thelook_cicd/thelook_cicd.model.lkml failed

================ thelook_cicd/business_pulse.dashboard.lookml:28 ===============

[Error] Unknown field "users.state" in explore "users" for field_filter.

LookML: https://gcpl2318.cloud.looker.com/projects/thelook_cicd/files/business_pulse.dashboard.lookml?line=28

================ thelook_cicd/business_pulse.dashboard.lookml:36 ===============

[Warning] Unknown field "users.state" (for explore "orders" in model
"thelook_cicd") referenced in dashboard element.

LookML: https://gcpl2318.cloud.looker.com/projects/thelook_cicd/files/business_pulse.dashboard.lookml?line=36

[Additional errors snipped]

Completed validation in 6 seconds.

Inhaltsvalidierung

Mit dem Content Validator wird geprüft, ob gespeicherte Inhalte wie Looks und benutzerdefinierte Dashboards nach Änderungen weiterhin funktionieren. Damit der Job schneller ausgeführt wird und überschaubare Ergebnisse geliefert werden, erfolgt die Validierung nur für Inhalte, die auf den von Ihnen angegebenen Explores basieren. Der Content Validator wird so aufgerufen:

$ spectacles content --config-file config-dev.yaml \
    --project PROJECT_NAME \
    --explores MODEL_NAME/EXPLORE_NAME \
    --branch DEV_BRANCH_NAME

Beispiel:

$ spectacles content --config-file config-dev.yaml \
    --project thelook_cicd \
    --explores thelook_cicd/users \
    --branch dev-my-user-ydnv

Connected to Looker version 23.18.60 using Looker API 4.0
Building LookML project hierarchy for project 'thelook_cicd' @ dev-my-user-ydnv

==================== Validating content based on 5 explores ====================

✗ thelook_cicd.users failed

================= test dashboard for spectacles [TheLook_CICD] =================

Tile 'test dashboard for spectacles' failed validation.

Error in thelook_cicd/users: Unknown field "users.state".

Dashboard: https://gcpl2318.cloud.looker.com/dashboards/223

========================= Business Pulse [TheLook_CICD] ========================

Filter 'State / Region' failed validation.

Error in thelook_cicd/users: Unknown field "users.state".

Dashboard: https://gcpl2318.cloud.looker.com/dashboards/190

Completed content validation in 27 seconds.

Assert-Validierung

Mit Assert-Validierungstests werden Datenbehauptungen getestet, die Sie Ihrem LookML-Code hinzugefügt haben, um zu prüfen, ob Daten richtig gelesen werden. Ein Datentest in Ihrem LookML könnte beispielsweise so aussehen:

test: historic_revenue_is_accurate {
  explore_source: orders {
    column: total_revenue { field: orders.total_revenue }
    filters: [orders.created_date: "2019"]
  }
  assert: revenue_is_expected_value {
    expression: ${orders.total_revenue} = 626000 ;;
  }
}

Die Assert-Validierung wird wie unten dargestellt aufgerufen:

$ spectacles assert --config-file config-dev.yaml \
    --project PROJECT_NAME \
    --explores MODEL_NAME/EXPLORE_NAME \
    --branch DEV_BRANCH_NAME

Beispiel:

$ spectacles assert --config-file config-dev.yaml \
    --project thelook_cicd \
    --explores thelook_cicd/users \
    --branch dev-my-user-ydnv

Connected to Looker version 23.18.60 using Looker API 4.0
Building LookML project hierarchy for project 'thelook_cicd' @ dev-my-user-ydnv

==================== Running data tests based on 1 explore =====================

✗ thelook_cicd.users failed

================ thelook_cicd/users/california_users_is_accurate ===============

Unknown filter field "users.state" in lookml test "california_users_is_accurate"
declaration.

LookML: https://gcpl2318.cloud.looker.com/projects/thelook_cicd/files/thelook_cicd.model.lkml?line=55

================ thelook_cicd/users/california_users_is_accurate ===============

Invalid filter: users.state

LookML: https://gcpl2318.cloud.looker.com/projects/thelook_cicd/files/thelook_cicd.model.lkml?line=55

================ thelook_cicd/users/california_users_is_accurate ===============

Assertion "count_is_expected_value" failed: expression evaluated to "No".

LookML: https://gcpl2318.cloud.looker.com/projects/thelook_cicd/files/thelook_cicd.model.lkml?line=55

Completed data test validation in 14 seconds.

Standardmäßig erhalten Looks und Dashboards aufsteigende numerische IDs, die in der URL für den Look oder das Dashboard verwendet werden. Es gibt jedoch keine Möglichkeit, diese systemübergreifend zu synchronisieren. Eine URL für ein bestimmtes Dashboard in der Entwicklung verweist daher nicht auf dasselbe Dashboard in der Qualitätssicherung oder Produktion.

Bei benutzerdefinierten Dimensionen gibt es die Möglichkeit, anstelle einer ID einen Slug als Teil der URL zu verwenden. Der Slug ist eine halbzufällige Zeichenfolge und keine Zahl. Der Slug kann im Rahmen des Imports festgelegt werden, sodass eine ähnliche URL in der Entwicklung, Qualitätssicherung und Produktion auf dieselbe UDD verweisen kann. Die Verwendung von Kurz-URLs anstelle von IDs ist eine Best Practice, insbesondere wenn Sie von einem Look oder einer anderen benutzerdefinierten Dimension auf eine benutzerdefinierte Dimension klicken.

Den Slug finden Sie in der Ausgabe von gzr dashboard cat. Der Alias kann anstelle der numerischen ID in der Dashboard-URL verwendet werden.

Nutzerinhalte mit Gazer migrieren

Das Kopieren von Inhalten wie Looks und Dashboards zwischen Entwicklung, Qualitätssicherung und Produktion ist oft nützlich. Möglicherweise möchten Sie Inhalte erstellen, in denen neue LookML-Ergänzungen vorgestellt werden, oder überprüfen, ob gespeicherte Inhalte nach LookML-Änderungen noch richtig funktionieren. In diesen Situationen kann Gazer verwendet werden, um Inhalte zwischen Instanzen zu kopieren.

LookML-Dashboards

LookML-Dashboards werden während des regulären LookML-CI/CD-Workflows zwischen Instanzen synchronisiert. Wenn jedoch UDDs mit LookML-Dashboards synchronisiert werden, können sie mit Gazer aktualisiert werden. Verwenden Sie dazu den folgenden Befehl:

gzr dashboard sync_lookml DASHBOARD_ID --host TARGET_SYSTEM_URL

Benutzerdefinierte Dashboards

Benutzerdefinierte Dashboards (User Defined Dashboards, UDDs) können mit Gazer migriert werden, indem auf die ID des Dashboards und die URL der Looker-Instanz verwiesen wird, in der sich das UDD befindet. Gazer speichert die Dashboard-Konfiguration in einer JSON-Datei, die dann in die Looker-Zielinstanz importiert wird.

Der Befehl zum Extrahieren der UDD-Konfiguration lautet so:

gzr dashboard cat DASHBOARD_ID --host TARGET_SYSTEM_URL --dir .

Dadurch wird eine Datei mit dem Namen Dashboard_DASHBOARD_ID_DASHBOARD_NAME.json erstellt, die die Konfiguration des Dashboards enthält.

Die UDD kann mit dem folgenden Befehl in das Zielsystem importiert werden:

gzr dashboard import Dashboard_DASHBOARD_ID_DASHBOARD_NAME.json FOLDER_ID \
    --host TARGET_SYSTEM_URL

Looks

Die Look-Migration funktioniert sehr ähnlich wie die Migration von benutzerdefinierten Dimensionen. Speichern Sie zuerst die Look-Konfiguration mit Gazer in einer JSON-Datei:

gzr look cat LOOK_ID --host SOURCE_SYSTEM_URL --dir .

Importieren Sie den Look dann in die Zielinstanz:

gzr look import Look_LOOK_ID_LOOK_NAME.json FOLDER_ID \
    --host TARGET_SYSTEM_URL