Cette page explique comment installer et configurer les composants nécessaires à l'implémentation d'un workflow CI/CD dans Looker.
Ces instructions reposent sur un système à trois niveaux comprenant le développement, le contrôle qualité et la production. Toutefois, les mêmes principes peuvent s'appliquer à un système à deux ou quatre niveaux.
Ces instructions supposent également que vous utilisez GitHub comme fournisseur Git. Vous pouvez faire appel à d'autres fournisseurs Git pour créer un workflow CI/CD. Cependant, vous devez posséder les compétences nécessaires pour modifier ces instructions pour votre fournisseur.
Suivez les instructions de la section qui vous concerne:
- Prérequis
- Procédure de configuration initiale uniquement
- Procédure de configuration pour chaque développeur Looker
Prérequis
Environnement Linux
Ce processus fait appel à des outils appelés Gazer et Spectacles, conçus pour fonctionner avec les systèmes d'exploitation de type Unix. Chaque développeur LookML doit avoir accès à la ligne de commande dans un environnement Linux ou macOS où vous prévoyez d'exécuter votre workflow CI/CD.
Si vous utilisez Windows, Gazer et Spectacles peuvent être utilisés dans le sous-système Windows pour Linux (WSL) de Microsoft. WSL vous permet d’exécuter une variété de versions Linux différentes. Si vous n'avez pas de système d'exploitation Linux préféré, la dernière version d'Ubuntu Linux est un bon choix en raison de sa compatibilité étendue.
Ces instructions fournissent des exemples pour les systèmes Linux et peuvent nécessiter des modifications si vous utilisez macOS ou WSL.
Une instance Looker par niveau
Pour activer cette configuration, vous aurez besoin d'une instance Looker pour chaque niveau de votre système. Par exemple, un système comportant une étape de développement, une étape de contrôle qualité et une étape de production nécessitera trois instances distinctes. Les instances peuvent être hébergées par Google ou par le client.
Noms de connexion identiques
Les connexions à la base de données doivent avoir le même nom dans chaque instance Looker, quel que soit le niveau qu'elles représentent. Par exemple, une connexion sales
doit porter ce nom dans toutes les instances, plutôt que sales_dev
ou sales_qa
.
Les connexions peuvent pointer vers la même base de données ou vers différentes bases de données. Toutefois, s'ils pointent vers la même base de données, des schémas entièrement nouveaux doivent être définis de sorte que les tables dérivées persistantes dans l'instance de développement ou de contrôle qualité n'interfèrent pas avec la production.
Par exemple, si la même base de données est utilisée pour les trois instances, elles peuvent être configurées comme suit:
Production | Contrôle qualité | Développement | |
Nom de la connexion | sales |
sales |
sales |
Database (Base de données) | sales_db |
sales_db |
sales_db |
Schéma de Scratch | prod_sales_scratch |
qa_sales_scratch |
dev_sales_scratch |
Ou, si une base de données unique est utilisée pour les trois instances, celles-ci peuvent être configurées comme suit:
Production | Contrôle qualité | Développement | |
Nom de la connexion | sales |
sales |
sales |
Database (Base de données) | sales_db_prod |
sales_db_qa |
sales_db_dev |
Schéma de Scratch | sales_scratch |
sales_scratch |
sales_scratch |
Dépôt Git
Un seul dépôt Git sera utilisé pour chaque projet sur les trois niveaux. L'instance de développement suivra la branche main
, tandis que les instances de contrôle qualité et de production pointeront généralement vers des tags Git (décrits plus en détail ultérieurement).
Première procédure de configuration uniquement
Les étapes de cette section ne doivent être effectuées qu'une seule fois par une personne disposant des autorisations d'administrateur Looker, ainsi que des autorisations d'administrateur au niveau de son fournisseur Git.
Identifiants Git
L'environnement Linux de chaque développeur doit se connecter au même référentiel que celui que vous utilisez pour gérer votre code LookML. Il s'agit probablement d'un dépôt externe hébergé sur un service tel que GitHub. Vous aurez besoin d'un compte avec ce service disposant des identifiants appropriés pour configurer le dépôt. À l'aide de ce compte, vous pouvez configurer une clé SSH pour permettre à votre environnement Linux de se connecter automatiquement à ce service.
Pour GitHub, suivez les instructions de la section Ajouter une clé SSH à votre compte GitHub.
Créer et configurer un dépôt de serveur Git
Pour que le workflow CI/CD fonctionne, LookML doit être stocké dans un dépôt Git et connecté à un projet Looker. Dans les paramètres du projet, le nom de la branche de production Git doit être défini sur main
, et l'option Activer le mode de déploiement avancé doit être activée.
Si vous n'avez pas encore effectué les étapes suivantes, suivez ces instructions pour GitHub:
Créer un dépôt
- Dans l'interface utilisateur de GitHub, appuyez sur le bouton + en haut à droite, puis sélectionnez Nouveau dépôt.
- Sélectionnez le propriétaire (votre organisation, probablement) et saisissez un REPOSITORY_NAME.
- Choisissez de rendre le dépôt public ou privé (les dépôts privés nécessitent un abonnement payant à GitHub), puis cochez la case pour l'initialiser avec un fichier README.
- Appuyez sur le bouton Créer un dépôt.
- Appuyez sur le bouton vert <> Code et copiez l'URL SSH. Il doit ressembler à ceci:
git@github.com:org_name/REPOSITORY_NAME.git
. - Dans Looker, créez un projet.
- Passez en mode développement et choisissez l'élément des paramètres du projet dans la barre latérale de gauche, puis cliquez sur Configure Git (Configurer Git).
- Collez l'URL du dépôt (
git@github.com:org_name/REPOSITORY_NAME.git
dans cet exemple), puis sélectionnez Continuer. - Copiez la clé de déploiement et revenez à l'interface utilisateur GitHub pour ce dépôt.
- Sélectionnez Paramètres, puis Déployer les clés.
- Cliquez sur le bouton Ajouter une clé de déploiement et collez la clé de déploiement dans le champ Clé.
- Ajoutez un titre tel que
Looker-REPOSITORY_NAME
, cochez la case Allow write access (Autoriser l'accès en écriture), puis appuyez sur le bouton Add key (Ajouter une clé). - Revenez dans Looker et sélectionnez Tester et finaliser la configuration.
- Sélectionnez de nouveau les paramètres du projet dans la barre latérale de gauche. Remplacez le nom de la branche de production Git par
main
. - Choisissez Enable Advanced Deploy Mode (Activer le mode Déploiement avancé), puis sélectionnez Save Project Configuration (Enregistrer la configuration du projet).
Sous l'icône des paramètres du projet, à gauche, vous devriez voir une icône de déploiement pour Deployment Manager.
Utiliser un dépôt existant
- Accédez au dépôt GitHub qui stocke votre LookML.
- Appuyez sur le bouton vert <> Code et copiez l'URL SSH. Il doit ressembler à ceci:
git@github.com:org_name/REPOSITORY_NAME.git
. - Dans Looker, créez un projet.
- Passez en mode développement et choisissez l'élément des paramètres du projet dans la barre latérale de gauche, puis cliquez sur Configurer Git.
- Collez l'URL du dépôt (
git@github.com:org_name/REPOSITORY_NAME.git
dans cet exemple), puis sélectionnez Continuer. - Copiez la clé de déploiement et revenez à l'interface utilisateur GitHub pour ce dépôt.
- Sélectionnez Paramètres, puis Déployer les clés.
- Cliquez sur le bouton Ajouter une clé de déploiement et collez la clé de déploiement dans le champ Clé.
- Ajoutez un titre tel que
Looker-REPOSITORY_NAME
, cochez la case Allow write access (Autoriser l'accès en écriture), puis appuyez sur le bouton Add key (Ajouter une clé). - Revenez dans Looker et sélectionnez Tester et finaliser la configuration.
- Sélectionnez de nouveau les paramètres du projet dans la barre latérale de gauche. Remplacez le nom de la branche de production Git par
main
. - Choisissez Enable Advanced Deploy Mode (Activer le mode Déploiement avancé), puis sélectionnez Save Project Configuration (Enregistrer la configuration du projet).
Sous l'icône des paramètres du projet, à gauche, vous devriez voir une icône de déploiement pour Deployment Manager.
Créer des actions GitHub
Il est utile de créer plusieurs actions GitHub afin que diverses vérifications soient effectuées automatiquement chaque fois que des modifications LookML sont apportées. Pour ajouter ces actions, vous devez être en mesure de modifier votre dépôt Git dans votre environnement Linux. Si ce n'est pas déjà fait, suivez les instructions de configuration de Git.
Pour ajouter les actions GitHub, accédez au répertoire de votre dépôt dans l'environnement Linux et ajoutez le sous-répertoire .github/workflows
. Une fois configurées, ces actions peuvent être exécutées manuellement à partir de la page Actions de l'interface utilisateur GitHub.
Look-at-me-Sideways
LAMS est un outil lint Open Source qui inspecte votre code LookML à la recherche d'erreurs et de mauvaises pratiques. Ajoutez un fichier nommé lams.yml
au répertoire .github/workflows
avec le contenu suivant:
name: LAMS
on:
pull_request:
branches: [ main ]
push:
workflow_dispatch:
jobs:
lams_job:
runs-on: ubuntu-latest
name: LAMS LookML Linter Job
steps:
- name: Checkout your LookML
uses: actions/checkout@v1
- name: Setup Node
uses: actions/setup-node@v1
with:
node-version: '16.x'
- name: Install LAMS
run: npm install -g @looker/look-at-me-sideways@3
- name: Run LAMS
run: lams --reporting=no
Chaque fois qu'un commit est transmis à GitHub ou qu'une demande d'extraction est ouverte pour fusionner le code avec la branche main
, LAMS s'exécute.
Libérer s'il vous plaît
Release S'il vous plaît est un outil Open Source qui tague automatiquement les versions avec les numéros de version appropriés.
Ajoutez un fichier nommé release-please.yml
au répertoire .github/workflows
avec le contenu suivant:
name: release-please
on:
push:
branches:
- main
workflow_dispatch:
permissions:
contents: write
pull-requests: write
jobs:
release-please:
runs-on: ubuntu-latest
steps:
- uses: google-github-actions/release-please-action@v3
with:
release-type: simple
package-name: sales_project
Commits classiques
Cette action GitHub garantit qu'une demande d'extraction est ouverte avec un titre conforme à la norme de commit conventionnel.
Ajoutez un fichier nommé lint_pr_title.yml
au répertoire .github/workflows
avec le contenu suivant:
name: "Lint Pull Request Title"
on:
pull_request_target:
types:
- opened
- edited
- synchronize
jobs:
main:
name: Validate PR title
runs-on: ubuntu-latest
steps:
- uses: amannn/action-semantic-pull-request@v5
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
Transférer les modifications vers GitHub
Enfin, exécutez les commandes suivantes pour valider ces modifications d'action GitHub et les transférer vers GitHub:
git add .github/workflows/
git commit -m "chore: Added github actions"
git push
Protéger la branche main
Dans l'interface utilisateur GitHub, vous devez activer les protections pour la branche main
afin que les développeurs ordinaires ne puissent pas appliquer les modifications directement à cette branche. Au lieu de cela, ils effectuent les modifications dans une branche différente, puis ouvrent une demande d'extraction;extraction. La demande d'extraction peut être examinée par un autre développeur avant d'être approuvée et fusionnée avec main
.
Pour configurer la protection des branches, accédez à l'interface utilisateur GitHub du dépôt, sélectionnez Settings (Paramètres), puis Branches (Branches), puis cliquez sur le bouton Add branch protection policy (Ajouter une règle de protection des branches) :
Saisissez main
comme Modèle de nom de branche et cochez les options suivantes:
- Exiger une demande d'extraction avant la fusion
- Exiger des approbations
- Ignorer les approbations de demande d'extraction obsolètes lors de l'envoi de nouveaux commits
Enfin, cliquez sur le bouton Créer en bas de la page.
Lorsqu'une demande d'extraction est créée, les actions GitHub configurées précédemment dans ces instructions s'exécutent. Après leur première exécution, vous pouvez également les sélectionner dans cette interface utilisateur. Elles doivent aboutir avant que la demande d'extraction ne puisse être fusionnée avec main
.
Configurer les demandes d'extraction
Dans Looker, vous pouvez exiger l'utilisation de demandes d'extraction et rendre les demandes d'extraction ouvertes au nom du développeur. Elle ne doit être configurée que pour l'instance de développement. L'instance de contrôle qualité et l'instance de production obtiendront les mises à jour utiliseront le mode de déploiement avancé.
Pour ce faire, accédez aux Paramètres de projet pour chaque projet, puis sélectionnez Demandes d'extraction requises sous l'en-tête Intégration GitHub:
Appuyez sur le bouton pour définir un secret de webhook, copiez la chaîne aléatoire générée, puis cliquez sur le bouton Save Project Configuration (Enregistrer la configuration du projet).
De retour dans l'interface utilisateur GitHub de votre dépôt, sélectionnez Settings (Paramètres), puis Webhooks. Appuyez sur le bouton Add webhook (Ajouter un webhook) en haut à droite:
- Dans le champ Payload URL (URL de charge utile), saisissez
https://LOOKER_HOST_NAME/webhooks/projects/PROJECT_NAME/deploy
. - Dans le champ Secret, collez le secret que vous avez enregistré depuis Looker.
- À la question Quels événements souhaitez-vous définir pour ce webhook ?, choisissez Je souhaite sélectionner des événements individuels.
Assurez-vous que les options Demandes d'extraction et Transferts sont sélectionnées:
Enfin, appuyez sur le bouton Ajouter un webhook en bas de la page.
Étapes de configuration pour chaque développeur Looker
Toutes les étapes d'installation ci-dessous doivent être effectuées dans votre environnement Linux.
Installer Ruby
Le langage de programmation Ruby doit être installé pour exécuter Gazer. Toutes les versions de Ruby ultérieures à la version 2.7.7 fonctionneront avec Gazer, mais il est préférable d'utiliser Ruby 3.x.x. Pour installer Ruby sur Ubuntu Linux, exécutez les commandes suivantes:
sudo apt update
sudo apt install ruby
Vérifiez que Ruby est correctement installé en exécutant ruby -v
. Vous devriez obtenir un résultat semblable à celui-ci:
ruby 3.1.3p185 (2022-11-24 revision 1a6b16756e) [x86_64-linux]
Ces commandes fonctionnent également sur Debian Linux, Linux Mint et plusieurs autres versions Linux qui utilisent le gestionnaire de paquets Aptitude. Vous devrez peut-être rechercher des commandes qui fonctionnent avec d'autres versions de Linux ou des commandes à installer sur macOS. Pour en savoir plus, consultez la page Installer Ruby.
Installation de Gazer
Gazer est un projet Open Source créé par des employés de Google. Il permet de parcourir et de gérer les espaces, les Looks et les tableaux de bord à l'aide d'un outil de ligne de commande.
Une fois Ruby installé, vous pouvez utiliser l'outil Gem de Ruby pour installer Gazer:
gem install gazer
Vérifiez que Gazer est installé à l'aide de la commande gzr version
. Vous devriez obtenir un résultat semblable à celui-ci:
v0.3.12
Installer des lunettes
Spectacles est un outil non-Google utilisé pour tester LookML. Les lunettes offrent à la fois une version payante et une version Open Source. Des informations détaillées sur l'installation de cette version sont disponibles sur la page Premiers pas.
Installer Git
Le logiciel de contrôle des versions Git peut être installé sur Ubuntu Linux à l'aide de la commande suivante:
sudo apt update
sudo apt install git
Vérifiez que l'installation a réussi à l'aide de la commande git --version
. Vous devriez obtenir un résultat semblable à celui-ci:
git version 2.42.0.609.gbb76f46606
Ces commandes fonctionnent également sur Debian Linux, Linux Mint et plusieurs autres versions Linux qui utilisent le gestionnaire de paquets Aptitude. Vous devrez peut-être rechercher des commandes qui fonctionnent avec d'autres versions de Linux. Par exemple, des instructions pour Fedora et macOS sont disponibles dans Getting Started - Installing Git (Premiers pas - Installation de Git).
Configurer Git
Dans votre environnement Linux, vous devez configurer Git pour interagir avec le dépôt Git dans lequel votre LookML est stocké. Ces instructions ont été écrites pour les dépôts Git LookML stockés dans GitHub.
Nom et adresse e-mail
GitHub (et la plupart des autres implémentations Git) doivent connaître votre nom et votre adresse e-mail pour pouvoir enregistrer l'activité. Configurez votre nom et votre adresse e-mail dans Git en exécutant les commandes suivantes:
git config --global user.name "FIRST_NAME LAST_NAME"
git config --global user.email "EMAIL_ADDRESS"
Identifiants Git
Dans la configuration CI/CD initiale, des identifiants Git ont été créés. La clé SSH privée générée doit être configurée dans un fichier $HOME/.ssh/config
. Pour créer le fichier, utilisez les commandes suivantes:
touch $HOME/.ssh/config
chmod 600 $HOME/.ssh/config
Insérez le texte suivant dans le fichier $HOME/.ssh/config
:
Host github.com
User git
IdentityFile ~/.ssh/KEY_NAME
ControlMaster auto
ControlPath ~/.ssh/ctrl-%r@%h:%p
ControlPersist yes
À la place de KEY_NAME, utilisez le nom du fichier de clé privée que vous avez généré en suivant les instructions Ajouter une clé SSH à votre compte GitHub. Le fichier de clé privée porte le même nom que le fichier de clé publique, mais sans l'extension .pub
. Par exemple, si vous avez utilisé la clé publique qui se trouve dans le fichier id_ed25519.pub
, la clé privée sera nommée id_ed25519
.
Configurer votre dépôt Git local
Après avoir configuré votre dépôt LookML, vous devez en créer une copie dans votre environnement Linux. Pour ce faire, exécutez la commande suivante:
git clone GIT_URL
Par exemple, la commande peut se présenter comme suit:
git clone git@github.com:my_org_name/sales_project.git
Le dépôt LookML sera copié dans un sous-répertoire, par exemple sales_project
. Utilisez la commande cd SUB_DIRECTORY
pour accéder au dépôt. Dans cet exemple, la commande est cd sales_project
.
Une fois dans le répertoire de votre dépôt, vous pouvez utiliser les commandes suivantes:
Commande | Objectif |
---|---|
git checkout BRANCH_NAME |
Permet de changer de branche. Dans la plupart des cas, la branche principale s'appelle main . Toutefois, dans les systèmes plus anciens, il peut s'appeler master . |
git fetch |
Permet de récupérer les dernières modifications sur le serveur. |
git pull |
Utilisé pour appliquer les modifications aux fichiers locaux récupérés. git pull effectue implicitement un git fetch . |
git tag |
Permet de créer un tag significatif pour une révision particulière. |
git push |
Utilisé pour transmettre les modifications locales au serveur. |
Configurer Gazer
Pour utiliser Gazer, vous avez besoin d'identifiants d'API pour chacune des instances de développement, de contrôle qualité et de production. Pour savoir comment créer des identifiants pour l'API, consultez la page Paramètres de l'administrateur – Utilisateurs. Les identifiants de l'API ont peut-être déjà été créés par la personne qui a initialement configuré le workflow CI/CD. Dans ce cas, vous pouvez utiliser les identifiants existants. de nouveaux identifiants n'ont pas à être générés pour chaque personne.
Stockez vos identifiants d'API dans un fichier .netrc
avec des autorisations minimales dans votre répertoire d'accueil. Vous pouvez créer un fichier vide avec les autorisations appropriées à l'aide des commandes suivantes:
touch $HOME/.netrc
chmod 600 $HOME/.netrc
Ajoutez des entrées au fichier comme suit, mais utilisez vos propres noms d'hôte de serveur Looker pour machine
, l'API client_id
pour la connexion et l'API client_secret
pour le mot de passe. Exemple :
machine dev.example.looker.com
login 80ka7nl6lj87ftmn
password u7kw3mj5h2trfz0
machine qa.example.looker.com
login fi3qtv5at5crvd1q
password bdxtaeghnzyz0wm
machine example.looker.com
login k7lr6yv57wvzy9p2
password wcvr5qjd2isbs2s
Vérifiez que cela fonctionne en exécutant une commande Gazer simple sur chaque serveur, comme celle-ci:
gzr user me --host dev.example.looker.com
Vous devriez obtenir un résultat semblable à celui-ci:
+----+---------------+---------+----------+------------------+--------------+
| id|email |last_name|first_name|personal_folder_id|home_folder_id|
+----+---------------+---------+----------+------------------+--------------+
|2345|jsm@example.com|Smith |John | 2161| 708|
+----+---------------+---------+----------+------------------+--------------+
Si la commande précédente ne fonctionne pas, vous devrez peut-être ajouter --port 443
à la fin de la commande gzr
, comme suit:
gzr user me --host dev.example.looker.com --port 443
Configurer des lunettes
Spectacles utilise les mêmes API client_id
et client_secret
que Gazer. Dans votre répertoire Spectacles, créez un fichier pour chaque niveau nommé config-TIER.yaml
(par exemple, config-dev.yaml
). Ajoutez le contenu suivant aux fichiers appropriés pour l'instance Looker de ce niveau, par exemple:
config-dev.yaml.
base_url: https://dev.example.looker.com/
client_id: 80ka7nl6lj87ftmn
client_secret: u7kw3mj5h2trfz0
config-qa.yaml
base_url: https://qa.example.looker.com/
client_id: fi3qtv5at5crvd1q
client_secret: bdxtaeghnzyz0wm
config-prod.yaml
base_url: https://example.looker.com/
client_id: k7lr6yv57wvzy9p2
client_secret: wcvr5qjd2isbs2s
Vous pouvez tester chaque fichier en exécutant la commande suivante et en remplaçant chaque nom de fichier:
$ spectacles connect --config-file config-dev.yaml
Vous devriez recevoir une réponse semblable à celle-ci:
Connected to Looker version 23.18.60 using Looker API 4.0