Installazione e configurazione CI/CD di Looker a più livelli

Questa pagina spiega come installare e configurare i componenti necessari per implementare un flusso di lavoro CI/CD a più livelli 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; tuttavia, devi avere le competenze per modificare queste istruzioni per il tuo provider.

Segui le istruzioni nella sezione pertinente per te:

Prerequisiti

Ambiente Linux

Questo processo utilizza uno strumento chiamato Gazer progettato per funzionare con sistemi operativi di tipo Unix. Ogni sviluppatore LookML che deve eseguire la migrazione del contenuto dell'utente 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 può essere utilizzato all'interno del sottosistema Windows per Linux (WSL) di Microsoft. WSL ti consente di eseguire una serie di diverse versioni di Linux. Se non hai un sistema operativo Linux preferito, l'ultima versione di Ubuntu Linux è una buona scelta grazie al suo ampio supporto.

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

Un'istanza di Looker per livello

Per abilitare questa configurazione, avrai bisogno di un'istanza Looker per ogni livello del tuo sistema. Ad esempio, un sistema con una fase di sviluppo, una fase di controllo qualità e una fase di produzione avrà bisogno di tre istanze separate. Le istanze possono essere ospitate da Google o dal cliente.

Nomi delle connessioni identici

Le connessioni al database devono avere lo stesso nome all'interno di 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 puntano allo stesso database, devono avere schemi scratch diversi definiti in modo che le tabelle derivate persistenti 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 temporaneo 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 nel seguente modo:

Produzione QA Sviluppo
Nome connessione sales sales sales
Database sales_db_prod sales_db_qa sales_db_dev
Schema temporaneo 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 monitorerà il ramo main, mentre le istanze QA e di produzione punteranno in genere ai tag Git (descritti in dettaglio più avanti).

Procedura di configurazione iniziale

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

Credenziali Git

L'ambiente Linux di ogni sviluppatore deve connettersi allo stesso repository che utilizzi per gestire LookML. Si tratta probabilmente di un repository esterno ospitato in un servizio come GitHub. Avrai bisogno di un account con il servizio che disponga delle credenziali appropriate per configurare il repository. Utilizzando l'account, puoi configurare una chiave SSH per consentire al tuo ambiente Linux di connettersi automaticamente a questo servizio.

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

Creazione e configurazione di un repository del server Git

Affinché il flusso di lavoro CI/CD funzioni, LookML deve essere archiviato in un repository Git e collegato a un progetto Looker. Nelle impostazioni del progetto, Git Production Branch Name deve essere impostato su main e Enable Advanced Deploy Mode deve essere attivato.

Se i seguenti passaggi non sono ancora 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 poi seleziona New repository (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 GitHub a pagamento) e seleziona la casella per inizializzarlo con un file README.
  4. Premi il pulsante Crea repository.
  5. Premi il pulsante verde con l'etichetta <> Code (Codice) e copia l'URL SSH. Avrà un aspetto simile a questo: git@github.com:org_name/REPOSITORY_NAME.git.
  6. In Looker, crea un nuovo progetto.
  7. Attiva la modalità di sviluppo, scegli l'elemento delle impostazioni progetto dalla barra laterale a sinistra e poi 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 GitHub per questo repository.
  10. Scegli Impostazioni e poi Azioni - Generali.
  11. In Autorizzazioni del flusso di lavoro, verifica che l'opzione Consenti a GitHub Actions di creare e approvare le richieste pull sia selezionata e fai clic su Salva.
  12. Passa alla pagina Deploy keys (Chiavi di deployment) delle impostazioni di GitHub.
  13. Fai clic sul pulsante Aggiungi chiave di distribuzione e incolla la chiave di distribuzione nel campo Chiave.
  14. Aggiungi un titolo, ad esempio Looker-REPOSITORY_NAME, seleziona la casella di controllo Consenti accesso in scrittura e premi il pulsante Aggiungi chiave.
  15. Torna a Looker e scegli Testa e finalizza la configurazione.
  16. Scegli di nuovo le impostazioni progetto dalla barra laterale sinistra. Modifica il Nome ramo di produzione Git in main.
  17. Scegli Abilita modalità di deployment avanzata e seleziona Salva configurazione progetto.

Sotto l'icona delle impostazioni del progetto sul lato sinistro, dovresti vedere un'icona di deployment per Deployment Manager.

Utilizza repository esistente

  1. Vai al repository GitHub che archivia il tuo LookML. (Inserisci qui il nome del tuo repository: REPOSITORY_NAME.)
  2. Scegli Impostazioni e poi Azioni - Generali.
  3. In Autorizzazioni del flusso di lavoro, verifica che l'opzione Consenti a GitHub Actions di creare e approvare le richieste pull sia selezionata e fai clic su Salva.
  4. Vai alla sezione <> Code del repository GitHub.
  5. Premi il pulsante verde con l'etichetta <> Code (Codice) e copia l'URL SSH. Avrà un aspetto simile a questo: git@github.com:org_name/REPOSITORY_NAME.git.
  6. In Looker, crea un nuovo progetto.
  7. Attiva la modalità di sviluppo e scegli l'elemento delle impostazioni progetto dalla barra laterale a sinistra, poi 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 GitHub per questo repository.
  10. Scegli Impostazioni e poi Implementa chiavi.
  11. Fai clic sul pulsante Aggiungi chiave di distribuzione e incolla la chiave di distribuzione 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 finalizza la configurazione.
  14. Scegli di nuovo le impostazioni progetto dalla barra laterale sinistra. Modifica il Nome ramo di produzione Git in main.
  15. Scegli Abilita modalità di deployment avanzata e seleziona Salva configurazione progetto.

Sotto l'icona delle impostazioni del progetto sul lato sinistro, dovresti vedere un'icona di deployment per Deployment Manager.

Creazione di azioni GitHub

È utile creare diverse azioni GitHub in modo che vengano eseguiti automaticamente vari controlli ogni volta che vengono apportate modifiche a LookML. L'aggiunta di queste azioni richiede la possibilità di apportare modifiche al 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 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 linter open source che ispeziona il codice LookML per rilevare errori e pratiche errate. Aggiungi un file denominato lams.yml alla directory .github/workflows con questi 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@v4
      with:
        ref: ${{ github.event.pull_request.head.sha }}
        fetch-depth: 0
    - 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 al ramo main.

Release Please

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

Aggiungi un file denominato release-please.yml alla directory .github/workflows con questi 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

Commit convenzionali

Questa azione GitHub verifica che una richiesta di pull venga aperta con un titolo conforme allo standard conventional commit.

Aggiungi un file denominato lint_pr_title.yml alla directory .github/workflows con questi 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 }}

permissions:
  pull-requests:
    read statuses: write

Esegui il push delle modifiche in GitHub

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

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

Protezione della filiale main

Nell'interfaccia utente di GitHub devi abilitare le protezioni dei rami per il ramo main in modo che gli sviluppatori ordinari non possano eseguire il push delle modifiche direttamente in quel ramo. Invece, apportano modifiche in un altro branch e poi aprono una richiesta di 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:

UI di GitHub per l'aggiunta della protezione dei branch.

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

  • Richiedere una richiesta di pull prima dell'unione
  • Richiedi approvazioni
  • Ignora le approvazioni delle richieste di pull obsolete quando vengono inviati nuovi commit

UI di GitHub per impostare le 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 la prima esecuzione, 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 di pull e fare in modo che Looker apra le richieste di pull per conto dello sviluppatore. Questa configurazione deve essere eseguita solo per l'istanza di sviluppo. L'istanza QA e di produzione utilizzerà la modalità di deployment avanzata per ricevere gli aggiornamenti.

Per abilitare questa opzione, vai alla pagina Configurazione progetto per ogni progetto, quindi seleziona Richieste di pull obbligatorie sotto l'intestazione Integrazione GitHub.

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

Nella UI di GitHub per il repository, scegli Impostazioni e poi Webhook. Premi il pulsante Aggiungi webhook in alto a destra:

  • Nel campo URL payload, inserisci https://LOOKER_HOST_NAME/webhooks/projects/PROJECT_NAME/deploy.
  • Nel campo etichettato Secret, incolla il secret che hai salvato da Looker.
  • Per la domanda Quali eventi vuoi che attivino questo webhook?, scegli Consenti di selezionare singoli eventi.

Interfaccia utente di GitHub per la configurazione dei webhook.

Verifica che siano selezionate le opzioni Pull Request e Push:

Caselle di controllo di GitHub per richieste di pull e push.

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

Passaggi di configurazione per ogni sviluppatore Looker

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

Installare Ruby

Per eseguire Gazer, è necessario installare il linguaggio di programmazione Ruby. Qualsiasi versione di Ruby successiva alla 2.7.7 funziona 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 funzionano anche su Debian Linux, Linux Mint e diverse altre versioni di Linux che utilizzano il gestore di pacchetti Aptitude. Potresti dover cercare comandi che funzionano su altre versioni di Linux o comandi da installare su macOS. Per saperne di più, 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.

Con Ruby installato, è possibile 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

Configurare Looker Continuous Integration

Per testare e convalidare LookML, utilizza l'integrazione continua di Looker. L'integrazione continua è integrata in Looker e non richiede l'installazione locale della CLI.

Per utilizzare l'integrazione continua:

  1. Verifica che la tua istanza soddisfi i requisiti di integrazione continua.
  2. Chiedi a un amministratore di Looker di abilitare l'integrazione continua e di installare l'app GitHub di CI.
  3. Crea una suite di integrazione continua per configurare i convalidatori e i trigger per il tuo progetto.

Per saperne di più, consulta la documentazione sull'integrazione continua di Looker.

Installazione di Git

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

sudo apt update
sudo apt install git

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

git version 2.42.0.609.gbb76f46606

Questi comandi funzionano anche su Debian Linux, Linux Mint e diverse altre versioni di Linux che utilizzano il gestore di pacchetti Aptitude. Potrebbe essere necessario cercare comandi che funzionano su altre versioni di Linux. Le istruzioni per Fedora e macOS, ad esempio, sono disponibili in Guida introduttiva - Installazione di Git.

Configurazione di Git

Git nel tuo 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) ha bisogno di 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 questi comandi:

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

Credenziali Git

Nella configurazione iniziale della 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 con le istruzioni riportate in 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 si chiamerà id_ed25519.

Configurare il repository Git locale

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

git clone GIT_URL

Ad esempio, il comando potrebbe essere visualizzato nel seguente modo:

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

In questo modo, 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 sarebbe 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 si chiama main, ma nei sistemi meno recenti potrebbe chiamarsi master.
git fetch Utilizzato per recuperare le ultime modifiche dal server.
git pull Utilizzato per applicare le modifiche ai file locali estratti. git pull esegue implicitamente un git fetch.
git tag Utilizzato per creare un tag significativo per una revisione specifica.
git push Utilizzato per eseguire il push delle modifiche locali sul server.

Configurazione di Gazer

Per utilizzare Gazer, devi disporre delle credenziali API per ogni istanza di sviluppo, controllo qualità e produzione. Per istruzioni sulla creazione delle credenziali API, consulta la pagina Impostazioni di amministrazione - 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 e non sarà necessario generarne di nuove per ogni persona.

Archivia 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 voci come le seguenti al file, ma utilizza i tuoi nomi host del 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 comando Gazer su ogni server, ad esempio:

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, potresti dover aggiungere --port 443 alla fine del comando gzr, come segue:

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

Configurazione delle suite di integrazione continua

Crea suite di integrazione continua in Looker per specificare le regole di convalida e le configurazioni di test.

In una suite CI, puoi configurare quanto segue:

Per istruzioni sulla configurazione delle suite, consulta Creazione di una suite di integrazione continua.