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, le contrôle 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 disposer de l'expertise nécessaire pour 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 normalement nommée quelque chose comme 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, elle redirige le développeur vers GitHub. Le développeur doit écrire un titre de demande d'extraction explicite en utilisant le style de validation conventionnel et ajouter un commentaire à la description qui sera incluse dans le journal des modifications. Les résultats des tests Spectacles doivent être ajoutés sous forme de commentaires à la demande d'extraction.

Ensuite, le développeur doit sélectionner un examinateur dans GitHub. L'examinateur recevra une notification et pourra ajouter son examen à la demande d'extraction. 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 désormais la modification.

L'automatisation Release Please s'exécute automatiquement et ouvre une deuxième demande d'extraction pour créer une nouvelle version taguée. Si une demande d'extraction est déjà ouverte à cet effet, Release Please la met à jour. La demande d'extraction de la 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 contrôle qualité et de production de Looker peuvent sélectionner cette version à l'aide du mode de déploiement avancé.

Bonnes pratiques pour la numérotation des versions et la dénomination des validations

Les versions et les tags associés peuvent être nommés et numérotés de n'importe quelle manière dans votre environnement. Toutefois, la gestion sémantique des versions est utilisée ici et est fortement suggéré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 remis à zéro lorsqu'une fonctionnalité non rétrocompatible est ajoutée.

Les validations conventionnelles sont un système de dénomination des validations en fonction de leur impact sur les utilisateurs finaux. Bien que cela ne soit pas obligatoire, l'utilisation d'une dénomination de validation conventionnelle est également utile pour le plug-in Release Please.

Dans la dénomination de validation conventionnelle, chaque message de validation est précédé d'un indicateur de la portée de la modification :

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

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

Utiliser le mode de 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 taguera 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 contrôle qualité et de production.

Pour déployer une modification, choisissez le gestionnaire de déploiement dans l'IDE Looker :

Emplacement du gestionnaire de déploiement Looker dans l'IDE.

Cliquez sur le lien Select Commit (Sélectionner la validation) en haut à droite du gestionnaire de déploiement. Ensuite, sélectionnez le menu à trois points associé au tag que vous souhaitez déployer, puis choisissez Deploy to Environment (Déployer dans l'environnement) :

Interface utilisateur de Deployment Manager Looker 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, envoyez en production à l'aide du gestionnaire de déploiement.

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, 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 programme de validation 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 programme de validation 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 LookML

Le programme de validation LookML vérifie que les modifications LookML sont valides et ne comportent pas d'erreurs de syntaxe. Il est appelé comme indiqué ci-dessous :

$ 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 programme de validation de contenu teste que tout contenu enregistré, tel que les Looks et les tableaux de bord définis par l'utilisateur, fonctionne toujours après les modifications. Pour accélérer l'exécution du job et fournir des résultats gérables, la validation n'est effectuée que pour le contenu basé sur les explorations que vous spécifiez. Le programme de validation 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

La validation Assert teste les assertions de données que vous avez ajoutées à votre LookML pour vérifier 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 indiqué ci-dessous :

$ 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 Looks et les tableaux de bord reçoivent des ID numériques ascendants qui sont utilisés dans l'URL du Look 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 développement ne pointera pas vers le même tableau de bord en contrôle qualité ou en production.

Pour les tableaux de bord définis par l'utilisateur, vous pouvez utiliser un slug au lieu d'un ID dans l'URL. Le slug est un ensemble de caractères semi-aléatoire plutôt qu'un nombre. Le slug peut être défini dans le cadre de l'importation afin qu'une URL similaire puisse pointer vers le même tableau de bord défini par l'utilisateur en développement, en contrôle qualité et en production. Il est recommandé d'utiliser des slugs au lieu d'ID, en particulier lorsque vous cliquez sur un tableau de bord défini par l'utilisateur à partir d'un Look ou d'un autre tableau de bord défini par l'utilisateur.

Le slug peut être trouvé en inspectant la sortie 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 le développement, le contrôle qualité et la production. Vous pouvez créer du contenu qui présente de nouveaux ajouts LookML ou vérifier que le contenu enregistré fonctionne toujours correctement après les modifications LookML. Dans ces situations, Gazer peut être utilisé 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 régulier. Toutefois, si des tableaux de bord définis par l'utilisateur 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

Les tableaux de bord définis par l'utilisateur peuvent être migrés avec Gazer en référençant l'ID du tableau de bord et l'URL de l'instance Looker où réside le tableau de bord défini par l'utilisateur. 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 du tableau de bord défini par l'utilisateur est la suivante :

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

Cela génère un fichier nommé Dashboard_DASHBOARD_ID_DASHBOARD_NAME.json qui contient la configuration du tableau de bord.

Le tableau de bord défini par l'utilisateur 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 tableaux de bord définis par l'utilisateur. Tout d'abord, utilisez 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