Utilisation et workflow du CI/CD Looker

Cette page explique comment utiliser un workflow CI/CD dans Looker une fois qu'il a été installé et configuré.

Ces instructions utilisent un système à trois niveaux comprenant le développement, l'assurance qualité et la production. Toutefois, vous pouvez appliquer les mêmes principes à un système à deux ou quatre niveaux.

Ces instructions supposent également que vous utilisez GitHub comme fournisseur Git. Vous pouvez utiliser d'autres fournisseurs Git pour créer un workflow CI/CD. Toutefois, vous devez être en mesure de modifier ces instructions pour votre fournisseur.

Présentation du workflow

Les développeurs LookML commencent par écrire du code dans leur branche de développement, qui est généralement nommée dev-my-user-ydnv, testent leurs modifications avec Spectacles et valident leur code. Enfin, ils ouvrent une demande d'extraction pour fusionner leur code avec la branche main.

Lorsque la demande d'extraction est ouverte, le développeur est redirigé vers GitHub. Le développeur doit rédiger un titre de demande d'extraction pertinent en utilisant le style des commits conventionnels et ajouter un commentaire à la description qui sera inclus dans le journal des modifications. Les résultats des tests Spectacles doivent être ajoutés en tant que commentaires à la demande d'extraction.

Le développeur doit ensuite sélectionner un réviseur dans GitHub. Le réviseur recevra une notification et pourra ajouter son avis à la demande de pull. Si l'examinateur approuve la modification, la demande d'extraction est fusionnée avec la branche main. Un WebHook est appelé et l'environnement de développement voit maintenant le changement.

L'automatisation Release Please s'exécute automatiquement et ouvre une deuxième demande d'extraction pour créer une version taguée. Si une demande d'extraction est déjà ouverte à cet effet, Release Please la met à jour. La RP de version est associée à un numéro de version, ainsi qu'à un journal des modifications qui inclut les titres et les descriptions des modifications incluses.

Lorsque la demande d'extraction générée par Release Please est approuvée et fusionnée, un nouveau tag de version est généré et le journal des modifications est fusionné avec la branche main. Les instances de production et d'assurance qualité de Looker peuvent sélectionner cette version à l'aide du mode de déploiement avancé.

Bonnes pratiques pour numéroter les versions et nommer les commits

Les versions et leurs tags associés peuvent être nommés et numérotés de la manière qui vous convient le mieux dans votre environnement. Toutefois, la gestion sémantique des versions est utilisée ici et est fortement recommandée, car elle fonctionne bien avec le plug-in Release Please.

Dans la gestion sémantique des versions, la version se compose de trois nombres séparés par des points : MAJOR.MINOR.PATCH.

  • PATCH est incrémenté chaque fois qu'une version corrige un bug.
  • MINOR est incrémenté et PATCH est remis à zéro chaque fois que la version ajoute ou affine une fonctionnalité tout en étant rétrocompatible.
  • MAJOR est incrémenté, et MINOR et PATCH sont définis sur zéro lorsqu'une fonctionnalité non rétrocompatible est ajoutée.

Conventional Commits est un système de dénomination des commits en fonction de leur impact sur les utilisateurs finaux. Bien que cela ne soit pas obligatoire, l'utilisation de noms de commit conventionnels est également utile pour le plug-in Release Please.

Dans la convention de nommage des commits, chaque message de commit est précédé d'un indicateur de l'étendue de la modification :

  • Un correctif est indiqué par fix:, comme fix: set proper currency symbol on sale_amt format.
  • Une nouvelle fonctionnalité est indiquée par l'icône feat:, comme feat: added explore for sales by territory.
  • Une fonctionnalité avec une modification radicale est indiquée par feat!:, comme feat!: rewrote sales explore to use the new calendar view.
  • Lorsque la documentation est mise à jour, mais que le LookML n'est pas modifié, le message de commit commence par doc:.

Si les commits conventionnels sont utilisés de manière cohérente, il est généralement facile de déterminer le numéro sémantique à utiliser ensuite. Si le journal des commits ne contient que des commits fix: et doc:, le PATCH doit être incrémenté. Si un commit feat: est présent, MINOR doit être incrémenté. Si un feat!: est présent, MAJOR doit être incrémenté. Le plug-in Release Please peut même générer un fichier CHANGELOG et taguer la version automatiquement.

Utiliser le mode Déploiement avancé

Une fois les modifications apportées et envoyées en tant que demande d'extraction sur l'instance de développement, le plug-in Release Please les marquera avec un tag de version tel que v1.2.3. Le mode de déploiement avancé de Looker rend ensuite ces versions disponibles dans l'interface utilisateur de Looker pour les instances de QA et de production.

Pour déployer une modification, sélectionnez Deployment Manager dans l'IDE Looker :

Emplacement de Looker Deployment Manager dans l'IDE.

Cliquez sur le lien Select Commit (Sélectionner et valider) en haut à droite de Deployment Manager. Ensuite, sélectionnez le menu à trois points associé au tag que vous souhaitez déployer, puis choisissez Déployer dans l'environnement :

Interface utilisateur de Looker Deployment Manager pour le déploiement dans l'environnement.

Vous n'avez pas besoin de taguer à nouveau le déploiement. Choisissez donc Deploy without tagging (Déployer sans taguer), puis appuyez sur le bouton Deploy to Environment (Déployer dans l'environnement) :

Interface utilisateur de Deployment Manager Looker pour le déploiement sans tag.

Enfin, déployez en production à l'aide de Deployment Manager.

Utiliser Spectacles

Chaque développeur peut utiliser Spectacles pour vérifier ses modifications lorsqu'elles se trouvent encore dans sa branche de développement. Spectacles propose quatre validateurs différents :

Lorsqu'un développeur envoie une demande d'extraction d'extraction, il est recommandé d'exécuter ces tests et de copier les résultats dans un commentaire de la demande d'extraction.

Programme de validation SQL

Le validateur SQL teste chaque exploration pour vérifier que tous les champs définis dans les vues LookML correspondent à des colonnes SQL réelles ou à des expressions SQL valides dans la base de données. Le validateur SQL est appelé comme indiqué ci-dessous :

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

Exemple :

$ 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.

Programme de validation de LookML

Le validateur LookML vérifie que les modifications LookML sont valides et ne contiennent pas d'erreurs de syntaxe. Elle est appelée comme suit :

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

Exemple :

$ 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.

Validation de contenu

Le validateur de contenu vérifie que tout contenu enregistré, comme les Looks et les tableaux de bord définis par l'utilisateur (UDD), fonctionne toujours après les modifications. Pour que le job s'exécute plus rapidement et fournisse des résultats gérables, la validation n'est effectuée que pour le contenu basé sur les explorations que vous spécifiez. Le validateur de contenu est appelé comme suit :

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

Exemple :

$ 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.

Validation Assert

Les tests de validation des assertions vérifient les assertions de données que vous avez ajoutées à votre LookML pour s'assurer que les données sont lues correctement. Par exemple, un test de données dans votre LookML peut se présenter comme suit :

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 ;;
  }
}

La validation Assert est appelée comme suit :

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

Exemple :

$ 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.

Par défaut, les présentations et les tableaux de bord reçoivent des ID numériques croissants qui sont utilisés dans l'URL de la présentation ou du tableau de bord. Toutefois, il n'existe aucun moyen de les synchroniser entre les systèmes. Par conséquent, une URL pour un tableau de bord spécifique en cours de développement ne pointera pas vers le même tableau de bord en contrôle qualité ou en production.

Pour les UDD, vous pouvez utiliser un slug au lieu d'un ID dans l'URL. Le slug est un ensemble de caractères semi-aléatoires plutôt qu'un nombre. Le slug peut être défini lors de l'importation afin qu'une URL similaire puisse pointer vers la même UDD dans les environnements de développement, de contrôle qualité et de production. Il est recommandé d'utiliser des slugs plutôt que des ID, en particulier lorsque vous cliquez pour accéder à une UDD depuis Look ou une autre UDD.

Vous trouverez le slug en inspectant le résultat de gzr dashboard cat. Le slug peut être utilisé dans l'URL du tableau de bord à la place de l'ID numérique.

Migrer le contenu utilisateur avec Gazer

Il est souvent utile de copier du contenu tel que des Looks et des tableaux de bord entre les environnements de développement, d'assurance qualité et de production. Vous pouvez créer du contenu qui présente les nouveaux ajouts LookML ou vérifier que le contenu enregistré fonctionne toujours correctement après les modifications LookML. Dans ce cas, vous pouvez utiliser Gazer pour copier du contenu entre les instances.

Tableaux de bord LookML

Les tableaux de bord LookML sont synchronisés entre les instances lors du workflow CI/CD LookML habituel. Toutefois, si des UDD sont synchronisés avec des tableaux de bord LookML, ils peuvent être mis à jour avec Gazer à l'aide de la commande suivante :

gzr dashboard sync_lookml DASHBOARD_ID --host TARGET_SYSTEM_URL

Tableaux de bord définis par l'utilisateur

Vous pouvez migrer les tableaux de bord définis par l'utilisateur (UDD) avec Gazer en référençant l'ID du tableau de bord et l'URL de l'instance Looker où se trouve l'UDD. Gazer enregistre la configuration du tableau de bord dans un fichier JSON, qui est ensuite importé dans l'instance Looker cible.

La commande permettant d'extraire la configuration UDD est la suivante :

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

Un fichier nommé Dashboard_DASHBOARD_ID_DASHBOARD_NAME.json contenant la configuration du tableau de bord sera alors généré.

Le fichier UDD peut être importé dans le système cible à l'aide de la commande suivante :

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

Looks

La migration des looks fonctionne de manière très similaire à la migration des données définies par l'utilisateur. Commencez par utiliser Gazer pour enregistrer la configuration du Look dans un fichier JSON :

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

Ensuite, importez le Look dans l'instance cible :

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