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 zweistufiges oder vierstufiges 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 öffnen 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 Release mit Tag 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 mit der Version eine Funktion hinzugefügt oder verbessert wird, die abwärtskompatibel ist.
  • MAJOR wird erhöht 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 wird, 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ü aus, das dem Tag zugeordnet ist, 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 das Deployment 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 seine Änderungen zu überprüfen, während sie sich noch in seinem 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 überprü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 liefert, 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 Datenassertions getestet, die Sie Ihrer LookML hinzugefügt haben, um zu prüfen, ob Daten richtig gelesen werden. Ein Datentest in Ihrem LookML-Code 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 folgt 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.

Looks und Dashboards erhalten standardmäßig 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. Daher verweist eine URL für ein bestimmtes Dashboard in der Entwicklung nicht auf dasselbe Dashboard in der Qualitätssicherung oder Produktion.

Bei benutzerdefinierten Dimensionen und Messwerten kann anstelle einer ID ein Slug als Teil der URL verwendet werden. Der Slug ist eine halb zufä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 Kurzbezeichnungen anstelle von IDs ist eine Best Practice, insbesondere wenn Sie von Look oder einer anderen UDD aus auf eine UDD 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 Ziel-Looker-Instanz 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 UDD-Migration. 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