Installazione e configurazione di CI/CD di Looker

Questa pagina spiega come installare e configurare i componenti necessari per implementare un flusso di lavoro CI/CD in Looker.

Queste istruzioni utilizzano un sistema a tre livelli che comprende sviluppo, QA e produzione. Tuttavia, gli stessi principi possono essere applicati a un sistema a due o quattro livelli.

Queste istruzioni presuppongono anche l'utilizzo di GitHub come provider Git. Puoi utilizzare altri provider Git per creare un flusso di lavoro CI/CD, ma devi disporre delle competenze necessarie per modificare queste istruzioni per il tuo provider.

Segui le istruzioni riportate nella sezione pertinente:

Prerequisiti

Ambiente Linux

Questo processo utilizza strumenti chiamati Gazer e Spectacles progettati per funzionare con sistemi operativi Unix-like. Ogni sviluppatore LookML deve avere accesso alla riga di comando in un ambiente Linux o macOS in cui prevedi di eseguire il flusso di lavoro CI/CD.

Se utilizzi Windows, Gazer e Spectacles possono essere utilizzati all'interno del Windows Subsystem for Linux (WSL) di Microsoft. WSL ti consente di eseguire una serie di diverse versioni di Linux. Se non hai un sistema operativo Linux preferito, la versione più recente di Ubuntu Linux è una buona scelta per via del suo ampio supporto.

Queste istruzioni forniscono esempi per i sistemi Linux e potrebbero richiedere modifiche se utilizzi macOS o WSL.

Un'istanza Looker per livello

Per attivare questa configurazione, devi avere un'istanza Looker per ogni livello del sistema. Ad esempio, un sistema con una fase di sviluppo, una fase di QA e una fase di produzione richiederà tre istanze distinte. Le istanze possono essere ospitate da Google o dal cliente.

Nomi di connessioni identici

Le connessioni al database devono avere lo stesso nome in ogni istanza di Looker, indipendentemente dal livello che rappresentano. Ad esempio, una connessione sales deve avere questo nome in tutte le istanze, anziché sales_dev o sales_qa.

Le connessioni possono puntare allo stesso database o a database diversi. Tuttavia, se rimandano allo stesso database, devono avere schemi scratch diversi definiti in modo che le tabelle derivate permanenti nell'istanza di sviluppo o QA non interferiscano con la produzione.

Ad esempio, se viene utilizzato lo stesso database per tutte e tre le istanze, queste potrebbero essere configurate come segue:

Produzione QA Sviluppo
Nome connessione sales sales sales
Database sales_db sales_db sales_db
Schema di Scratch prod_sales_scratch qa_sales_scratch dev_sales_scratch

In alternativa, se viene utilizzato un database univoco per tutte e tre le istanze, queste potrebbero essere configurate come segue:

Produzione QA Sviluppo
Nome connessione sales sales sales
Database sales_db_prod sales_db_qa sales_db_dev
Schema di Scratch sales_scratch sales_scratch sales_scratch

Repository Git

Per ogni progetto verrà utilizzato un unico repository Git in tutti e tre i livelli. L'istanza di sviluppo monitora il ramo main, mentre le istanze di QA e produzione in genere puntano ai tag git (descritti in dettaglio di seguito).

Procedura di configurazione solo per la prima volta

I passaggi di questa sezione devono essere completati una sola volta da un utente con autorizzazioni di amministratore di Looker e autorizzazioni di amministratore sul proprio provider Git.

Credenziali Git

L'ambiente Linux di ogni sviluppatore deve connettersi allo stesso repository che utilizzi per gestire il LookML. Probabilmente si tratta di un repository esterno ospitato in un servizio come GitHub. Per configurare il repository, devi disporre di un account con il servizio che abbia le credenziali appropriate. Con l'account, puoi configurare una chiave SSH per consentire al tuo ambiente Linux di connettersi automaticamente al servizio.

Per GitHub, segui le istruzioni riportate in Aggiunta di una nuova chiave SSH all'account GitHub.

Creazione e configurazione di un repository del server Git

Affinché il flusso di lavoro CI/CD funzioni, il codice LookML deve essere archiviato in un repository Git e collegato a un progetto Looker. Nelle impostazioni del progetto, Nome ramo di produzione Git deve essere impostato su main e Attiva modalità di deployment avanzata deve essere attivata.

Se i passaggi che seguono non sono già stati eseguiti, segui queste istruzioni per GitHub:

Crea nuovo repository

  1. Nell'interfaccia utente di GitHub, premi il pulsante + nell'angolo in alto a destra e seleziona Nuovo repository.
  2. Seleziona il proprietario (probabilmente la tua organizzazione) e inserisci un REPOSITORY_NAME.
  3. Scegli se rendere il repository pubblico o privato (i repository privati richiedono un abbonamento a GitHub a pagamento) e seleziona la casella per inizializarlo con un file README.
  4. Premi il pulsante Crea repository.
  5. Premi il pulsante verde <> Codice e copia l'URL SSH. Sarà simile a: git@github.com:org_name/REPOSITORY_NAME.git.
  6. In Looker, crea un nuovo progetto.
  7. Entra in modalità di sviluppo e scegli l'elemento delle impostazioni del progetto dalla barra laterale sinistra, quindi Configura Git.
  8. Incolla l'URL del repository (git@github.com:org_name/REPOSITORY_NAME.git in questo esempio) e seleziona Continua.
  9. Copia la chiave di deployment e torna all'interfaccia utente di GitHub per questo repository.
  10. Scegli Impostazioni e poi Esegui il deployment delle chiavi.
  11. Fai clic sul pulsante Aggiungi chiave di deployment e incolla la chiave di deployment nel campo Chiave.
  12. Aggiungi un titolo, ad esempio Looker-REPOSITORY_NAME, seleziona la casella di controllo Consenti accesso in scrittura e premi il pulsante Aggiungi chiave.
  13. Torna a Looker e scegli Testa e completa la configurazione.
  14. Scegli di nuovo le impostazioni del progetto dalla barra laterale sinistra. Modifica il nome del ramo di produzione Git in main.
  15. Scegli Attiva modalità di deployment avanzata e seleziona Salva configurazione progetto.

Sotto l'icona delle impostazioni del progetto, a sinistra, dovresti vedere un'icona di deployment per Deployment Manager.

Utilizza repository esistente

  1. Vai al repository GitHub in cui è archiviato il tuo LookML.
  2. Premi il pulsante verde <> Codice e copia l'URL SSH. Sarà simile a: git@github.com:org_name/REPOSITORY_NAME.git.
  3. In Looker, crea un nuovo progetto.
  4. Entra in modalità di sviluppo e scegli l'elemento delle impostazioni del progetto dalla barra laterale sinistra, quindi Configura Git.
  5. Incolla l'URL del repository (git@github.com:org_name/REPOSITORY_NAME.git in questo esempio) e seleziona Continua.
  6. Copia la chiave di deployment e torna all'interfaccia utente di GitHub per questo repository.
  7. Scegli Impostazioni e poi Esegui il deployment delle chiavi.
  8. Fai clic sul pulsante Aggiungi chiave di deployment e incolla la chiave di deployment nel campo Chiave.
  9. Aggiungi un titolo, ad esempio Looker-REPOSITORY_NAME, seleziona la casella di controllo Consenti accesso in scrittura e premi il pulsante Aggiungi chiave.
  10. Torna a Looker e scegli Testa e completa la configurazione.
  11. Scegli di nuovo le impostazioni del progetto dalla barra laterale sinistra. Modifica il nome del ramo di produzione Git in main.
  12. Scegli Attiva modalità di deployment avanzata e seleziona Salva configurazione progetto.

Sotto l'icona delle impostazioni del progetto, a sinistra, dovresti vedere un'icona di deployment per Deployment Manager.

Creazione di azioni GitHub

È utile creare diverse azioni GitHub in modo che vengano eseguiti vari controlli automaticamente ogni volta che vengono apportate modifiche a LookML. L'aggiunta di queste azioni richiede che tu possa apportare modifiche al tuo repository Git nell'ambiente Linux. Se non è già disponibile, segui le istruzioni per la configurazione di Git.

Per aggiungere le azioni GitHub, vai alla directory del tuo repository nell'ambiente Linux e aggiungi la sottodirectory .github/workflows. Una volta configurate, queste azioni possono essere eseguite manualmente dalla pagina Azioni dell'interfaccia utente di GitHub.

Look-At-Me-Sideways (LAMS)

LAMS è un lint open source che controlla il tuo LookML per rilevare errori e cattive pratiche. Aggiungi un file denominato lams.yml alla directory .github/workflows con i seguenti contenuti:

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

LAMS viene eseguito ogni volta che viene eseguito il push di un commit su GitHub o viene aperta una richiesta di pull per unire il codice con il ramo main.

Rilascia

Release Please è uno strumento open source che contrassegna automaticamente le release con i numeri di versione corretti.

Aggiungi un file denominato release-please.yml alla directory .github/workflows con i seguenti contenuti:

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

Commit convenzionali

Questa azione GitHub garantisce che una richiesta di pull venga aperta con un titolo conforme allo standard del commit convenzionale.

Aggiungi un file denominato lint_pr_title.yml alla directory .github/workflows con i seguenti contenuti:

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

Esegui il push delle modifiche su GitHub

Infine, utilizza i seguenti comandi per eseguire il commit di queste modifiche di GitHub Action e inviarle a GitHub:

git add .github/workflows/
git commit -m "chore: Added github actions"
git push

Protezione del ramo main

Nell'interfaccia utente di GitHub, devi attivare le protezioni dei branch per il branch main in modo che gli sviluppatori normali non possano inviare modifiche direttamente a quel branch. Invece, apportano modifiche in un ramo diverso e poi aprono una richiesta pull. La richiesta di pull può essere esaminata da un altro sviluppatore prima di essere approvata e unita a main.

Per configurare la protezione dei rami, vai all'interfaccia utente di GitHub per il repository, scegli Impostazioni e poi Rami e premi il pulsante Aggiungi regola di protezione dei rami:

Interfaccia utente di GitHub per l&#39;aggiunta della protezione dei rami.

Inserisci main come Pattern del nome del ramo e seleziona le seguenti opzioni:

  • Richiedere una richiesta pull prima dell'unione
  • Richiedi approvazioni
  • Ignorare le approvazioni delle richieste pull non aggiornate quando vengono eseguiti push di nuovi commit

Interfaccia utente di GitHub per l&#39;impostazione delle opzioni di protezione dei rami.

Infine, premi il pulsante Crea nella parte inferiore della pagina.

Quando viene creata una richiesta di pull, vengono eseguite le azioni GitHub configurate in precedenza in queste istruzioni. Dopo l'esecuzione per la prima volta, possono essere selezionati anche in questa UI in modo che debbano essere completati correttamente prima che la richiesta di pull possa essere unita a main.

Configurazione delle richieste di pull

In Looker puoi richiedere l'utilizzo delle richieste pull e consentire a Looker di aprirle per conto dello sviluppatore. Questo valore deve essere configurato solo per l'istanza di sviluppo. L'istanza di QA e di produzione utilizzerà la modalità di deployment avanzata per ricevere gli aggiornamenti.

Per attivare questa opzione, vai alla pagina Configurazione progetto per ogni progetto e seleziona Pull request richieste nella sezione Integrazione GitHub.

Premi il pulsante per impostare un secret webhook, copia la stringa casuale generata e premi il pulsante Salva configurazione progetto.

Torna all'interfaccia utente di GitHub per il tuo repository, scegli Impostazioni e poi Webhook. Premi il pulsante Aggiungi webhook in alto a destra:

  • Nel campo URL del payload, inserisci https://LOOKER_HOST_NAME/webhooks/projects/PROJECT_NAME/deploy
  • Nel campo Secret, incolla il secret che hai salvato da Looker
  • Alla domanda Quali eventi vuoi attivare con questo webhook?, scegli Fammi selezionare i singoli eventi.

Interfaccia utente di GitHub per la configurazione dei webhook.

Assicurati che Pull request e Push siano selezionati:

Caselle di controllo di GitHub per richieste pull e push.

Infine, premi il pulsante Aggiungi webhook in fondo alla pagina.

Procedura di configurazione per ogni sviluppatore Looker

Tutti i passaggi di installazione che seguono devono essere eseguiti nel tuo ambiente Linux.

Installazione di Ruby

Per eseguire Gazer è necessario installare il linguaggio di programmazione Ruby. Qualsiasi versione di Ruby successiva alla 2.7.7 funzionerà con Gazer, ma è preferibile Ruby 3.x.x. Per installare Ruby su Ubuntu Linux, esegui questi comandi:

sudo apt update
sudo apt install ruby

Verifica che Ruby sia installato correttamente eseguendo ruby -v. Dovresti ricevere una risposta simile alla seguente:

ruby 3.1.3p185 (2022-11-24 revision 1a6b16756e) [x86_64-linux]

Questi comandi funzioneranno anche su Debian Linux, Linux Mint e su diversi altri sistemi operativi Linux che utilizzano il gestore dei pacchetti Aptitude. Potresti dover cercare comandi che funzionino su altri tipi di Linux o comandi da installare su macOS. Per ulteriori informazioni, consulta Installazione di Ruby.

Installazione di Gazer

Gazer è un progetto open source creato dai dipendenti di Google per navigare e gestire spazi, look e dashboard utilizzando uno strumento a riga di comando.

Una volta installato Ruby, puoi utilizzare lo strumento Gem di Ruby per installare Gazer:

gem install gazer

Verifica che Gazer sia installato con il comando gzr version. Dovresti ricevere una risposta simile alla seguente:

v0.3.12

Installare gli occhiali Spectacles

Spectacles è uno strumento non Google utilizzato per testare LookML. Spectacles è disponibile sia in una versione a pagamento sia in una versione open source. I dettagli per l'installazione sono disponibili nella pagina Inizia.

Installazione di Git

Il software di controllo delle versioni Git può essere installato su Ubuntu Linux con questo comando:

sudo apt update
sudo apt install git

Verifica che l'installazione sia andata a buon fine con il comando git --version. Dovresti ricevere una risposta simile alla seguente:

git version 2.42.0.609.gbb76f46606

Questi comandi funzioneranno anche su Debian Linux, Linux Mint e su diversi altri sistemi operativi Linux che utilizzano il gestore dei pacchetti Aptitude. Potresti dover cercare comandi che funzionino su altri tipi di Linux. Le istruzioni per Fedora e macOS, ad esempio, sono disponibili nella pagina Guida introduttiva - Installazione di Git.

Configurazione di Git

Git nell'ambiente Linux deve essere configurato per interagire con il repository Git in cui è archiviato il tuo LookML. Queste istruzioni sono state scritte per i repository Git LookML archiviati in GitHub.

Nome ed email

GitHub (e la maggior parte delle altre implementazioni di Git) deve conoscere il tuo nome e il tuo indirizzo email per poter registrare l'attività. Configura il tuo nome e la tua email in Git eseguendo i seguenti comandi:

git config --global user.name "FIRST_NAME LAST_NAME"
git config --global user.email "EMAIL_ADDRESS"

Credenziali Git

Nella configurazione iniziale di CI/CD sono state create le credenziali Git. La chiave SSH privata generata deve essere configurata in un file $HOME/.ssh/config. Per creare il file, utilizza questi comandi:

touch $HOME/.ssh/config
chmod 600 $HOME/.ssh/config

Inserisci il seguente testo nel file $HOME/.ssh/config:

Host github.com
  User git
  IdentityFile ~/.ssh/KEY_NAME
  ControlMaster auto
  ControlPath ~/.ssh/ctrl-%r@%h:%p
  ControlPersist yes

Al posto di KEY_NAME, utilizza il nome del file della chiave privata che hai generato seguendo le istruzioni per aggiungere una nuova chiave SSH al tuo account GitHub. Il file della chiave privata ha lo stesso nome del file della chiave pubblica, ma senza l'estensione .pub. Ad esempio, se hai utilizzato la chiave pubblica trovata nel file id_ed25519.pub, la chiave privata avrà il nome id_ed25519.

Configurazione del repository Git locale

Dopo aver configurato il repository LookML, devi crearne una copia nel tuo ambiente Linux. Per farlo, esegui questo comando:

git clone GIT_URL

Ad esempio, il comando potrebbe avere il seguente aspetto:

git clone git@github.com:my_org_name/sales_project.git

Il repository LookML verrà copiato in una sottodirectory, ad esempio sales_project. Utilizza il comando cd SUB_DIRECTORY per accedere al repository. In questo esempio, il comando è cd sales_project.

Una volta nella directory del repository, puoi utilizzare i seguenti comandi:

Comando Finalità
git checkout BRANCH_NAME Utilizzato per cambiare branch. Nella maggior parte dei casi, il ramo principale è chiamato main; tuttavia, nei sistemi precedenti potrebbe essere chiamato master.
git fetch Utilizzato per recuperare le ultime modifiche dal server.
git pull Viene utilizzato per applicare le modifiche ai file locali sottoposti a check-out. git pull esegue implicitamente un git fetch.
git tag Utilizzato per creare un tag significativo per una determinata revisione.
git push Viene utilizzato per inviare le modifiche locali al server.

Configurazione di Gazer

Per utilizzare Gazer, sono necessarie le credenziali API per ogni istanza di sviluppo, QA e produzione. Per istruzioni su come creare le credenziali API, consulta la pagina Impostazioni amministratore - Utenti. Le credenziali API potrebbero essere già state create dalla persona che ha configurato inizialmente il flusso di lavoro CI/CD. In questo caso, puoi utilizzare le credenziali esistenti; non sarà necessario generare nuove credenziali per ogni persona.

Memorizza le credenziali API in un file .netrc con autorizzazioni minime nella tua home directory. Puoi creare un file vuoto con le autorizzazioni corrette utilizzando questi comandi:

touch $HOME/.netrc
chmod 600 $HOME/.netrc

Aggiungi al file voci come quelle riportate di seguito, ma utilizza i nomi host dei tuoi server Looker per machine, l'API client_id per l'accesso e l'API client_secret per la password. Ad esempio:

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

Verifica che funzioni eseguendo un semplice comando Gazer su ciascun server, ad esempio il seguente:

gzr user me --host dev.example.looker.com

Dovresti ottenere un risultato simile a questo:

+----+---------------+---------+----------+------------------+--------------+
|  id|email          |last_name|first_name|personal_folder_id|home_folder_id|
+----+---------------+---------+----------+------------------+--------------+
|2345|jsm@example.com|Smith    |John      |              2161|           708|
+----+---------------+---------+----------+------------------+--------------+

Se il comando precedente non funziona, potrebbe essere necessario aggiungere --port 443 alla fine del comando gzr, come segue:

gzr user me --host dev.example.looker.com --port 443

Configurare Spectacles

Spectacles utilizza le stesse API client_id e client_secret di Gazer. Nella directory Spectacles, crea un file per ogni livello denominato config-TIER.yaml, ad esempio config-dev.yaml. Aggiungi i seguenti contenuti ai file in base all'istanza Looker del livello, ad esempio:

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

Puoi testare ogni file eseguendo il seguente comando e sostituendo ogni nome file:

$ spectacles connect --config-file config-dev.yaml

Dovresti ricevere una risposta simile alla seguente:

Connected to Looker version 23.18.60 using Looker API 4.0