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 avere l'esperienza necessaria per modificare queste istruzioni per il tuo provider.
Segui le istruzioni riportate nella sezione pertinente:
- Prerequisiti
- Passaggi di configurazione da eseguire una sola volta
- Passaggi di configurazione per ogni sviluppatore Looker
Prerequisiti
Ambiente Linux
Questa procedura utilizza strumenti chiamati Gazer e Spectacles progettati per funzionare con sistemi operativi di tipo Unix. Ogni sviluppatore LookML deve avere accesso alla riga di comando in un ambiente Linux o macOS in cui intendi eseguire il flusso di lavoro CI/CD.
Se utilizzi Windows, Gazer e Spectacles possono essere utilizzati all'interno del sottosistema Windows per Linux (WSL) di Microsoft. WSL ti consente di eseguire una serie di varianti 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 di Looker per ogni livello del sistema. Ad esempio, un sistema con una fase di sviluppo, una fase di QA e una fase di produzione avrà bisogno di tre istanze separate. Le istanze possono essere ospitate da Google o dal cliente.
Nomi di connessione 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 temporanei diversi definiti in modo che le tabelle derivate persistenti nell'istanza di sviluppo o QA non interferiscano con la produzione.
Ad esempio, se lo stesso database viene utilizzato per tutte e tre le istanze, potrebbe essere configurato 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, potrebbe essere configurato come segue:
| 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 singolo repository Git in tutti e tre i livelli. L'istanza di sviluppo monitorerà il branch main, mentre le istanze di QA e produzione in genere punteranno ai tag Git (descritti in dettaglio più avanti).
Passaggi di configurazione da eseguire una sola volta
I passaggi descritti in questa sezione devono essere completati una sola volta da un utente con autorizzazioni di amministratore di 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. Probabilmente si tratta 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 al servizio.
Per GitHub, segui le istruzioni riportate in Aggiungere una nuova chiave SSH al tuo account GitHub.
Creare e configurare 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 progetto, Nome del branch di produzione Git deve essere impostato su main e Attiva modalità di deployment avanzata deve essere attivato.
Se i seguenti passaggi non sono ancora stati eseguiti, segui queste istruzioni per GitHub:
Crea nuovo repository
- Nell'interfaccia utente di GitHub, premi il pulsante + nell'angolo in alto a destra, quindi seleziona Nuovo repository.
- Seleziona il proprietario (probabilmente la tua organizzazione) e inserisci un REPOSITORY_NAME.
- Scegli se rendere pubblico o privato il repository (i repository privati richiedono un abbonamento GitHub a pagamento) e seleziona la casella per inizializzarlo con un file README.
- Premi il pulsante Crea repository.
- Premi il pulsante verde con l'etichetta <> Codice e copia l'URL SSH. Avrà un aspetto simile a:
git@github.com:org_name/REPOSITORY_NAME.git. - In Looker, crea un nuovo progetto.
- Attiva la modalità di sviluppo, scegli l'elemento delle impostazioni progetto dalla barra laterale sinistra e poi Configura Git.
- Incolla l'URL del repository (
git@github.com:org_name/REPOSITORY_NAME.gitin questo esempio) e seleziona Continua. - Copia la chiave di deployment e torna all'interfaccia utente di GitHub per questo repository.
- Scegli Impostazioni e poi Azioni - Generali.
- In Autorizzazioni del flusso di lavoro , verifica che la casella Consenti a GitHub Actions di creare e approvare le richieste di pull sia selezionata e fai clic su Salva.
- Passa alla pagina Chiavi di deployment delle impostazioni di GitHub.
- Fai clic sul pulsante Aggiungi chiave di deployment e incolla la chiave di deployment nel campo Chiave.
- Aggiungi un titolo come
Looker-REPOSITORY_NAME, seleziona la casella di controllo Consenti accesso in scrittura e premi il pulsante Aggiungi chiave. - Torna a Looker e scegli Testa e finalizza la configurazione.
- Scegli di nuovo le impostazioni progetto dalla barra laterale sinistra. Modifica il Nome del branch di produzione Git in
main. - Scegli Attiva 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
- Vai al repository GitHub in cui è archiviato LookML.
- Scegli Impostazioni e poi Azioni - Generali.
- In Autorizzazioni del flusso di lavoro , verifica che la casella Consenti a GitHub Actions di creare e approvare le richieste di pull sia selezionata e fai clic su Salva.
- Vai alla sezione <> Codice del repository GitHub.
- Premi il pulsante verde con l'etichetta <> Codice e copia l'URL SSH. Avrà un aspetto simile a:
git@github.com:org_name/REPOSITORY_NAME.git. - In Looker, crea un nuovo progetto.
- Attiva la modalità di sviluppo, scegli l'elemento delle impostazioni progetto dalla barra laterale sinistra e poi Configura Git.
- Incolla l'URL del repository (
git@github.com:org_name/REPOSITORY_NAME.gitin questo esempio) e seleziona Continua. - Copia la chiave di deployment e torna all'interfaccia utente di GitHub per questo repository.
- Scegli Impostazioni e poi Chiavi di deployment.
- Fai clic sul pulsante Aggiungi chiave di deployment e incolla la chiave di deployment nel campo Chiave.
- Aggiungi un titolo come
Looker-REPOSITORY_NAME, seleziona la casella di controllo Consenti accesso in scrittura e premi il pulsante Aggiungi chiave. - Torna a Looker e scegli Testa e finalizza la configurazione.
- Scegli di nuovo le impostazioni progetto dalla barra laterale sinistra. Modifica il Nome del branch di produzione Git in
main. - Scegli Attiva 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.
Creare azioni GitHub
È utile creare diverse azioni GitHub in modo che vari controlli vengano eseguiti automaticamente ogni volta che vengono apportate modifiche a LookML. Per aggiungere queste azioni, devi essere in grado di apportare modifiche al repository Git nel tuo ambiente Linux. Se non è ancora 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 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 verrà eseguito ogni volta che viene eseguito il push di un commit in GitHub o viene aperta una richiesta di pull per unire il codice con il branch main.
Release Please
Release Please è uno strumento open source che assegna automaticamente i tag alle 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 verificherà che una richiesta di pull venga aperta con un titolo conforme allo standard dei commit convenzionali.
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 ed eseguirne il push in GitHub:
git add .github/workflows/
git commit -m "chore: Added github actions"
git push
Proteggere il branch main
Nell'interfaccia utente di GitHub devi attivare le protezioni dei branch per il branch main in modo che gli sviluppatori normali non possano eseguire il push delle modifiche direttamente in questo branch. Invece, apportano modifiche in un branch diverso 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 branch, vai all'interfaccia utente di GitHub per il repository, scegli Impostazioni e poi Branch e premi il pulsante Aggiungi regola di protezione dei branch:
Inserisci main come Pattern del nome del branch e seleziona le seguenti opzioni:
- Richiedi una richiesta di pull prima dell'unione
- Richiedi approvazioni
- Ignora le approvazioni delle richieste di pull non aggiornate quando vengono eseguiti i push di nuovi commit
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 selezionate anche in questa UI in modo che debbano essere eseguite correttamente prima che la richiesta di pull possa essere unita a main.
Configurare le 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 di QA e 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 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.
Torna all'interfaccia utente di GitHub per il repository, scegli Impostazioni e poi Webhook. Premi il pulsante Aggiungi webhook in alto a destra:
- Nel campo con l'etichetta URL payload inserisci
https://LOOKER_HOST_NAME/webhooks/projects/PROJECT_NAME/deploy - Nel campo con l'etichetta Secret incolla il secret che hai salvato da Looker
- Per la domanda Quali eventi vuoi attivare questo webhook? scegli Consenti di selezionare singoli eventi
Verifica che siano selezionate le opzioni Richieste di pull e Push:
Infine, premi il pulsante Aggiungi webhook nella parte inferiore della pagina.
Passaggi di configurazione per ogni sviluppatore Looker
Tutti i passaggi di installazione seguenti 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 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 diverse altre varianti di Linux che utilizzano il gestore di pacchetti Aptitude. Potrebbe essere necessario cercare i comandi che funzionano su altre varianti di Linux o i comandi da installare su macOS. Per ulteriori informazioni, consulta Installare Ruby.
Installare 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, 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 Spectacles
Spectacles è uno strumento open source utilizzato per testare LookML (la versione a pagamento non è più disponibile). I dettagli per l'installazione sono disponibili nella pagina Guida introduttiva.
Installare 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 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 diverse altre varianti di Linux che utilizzano il gestore di pacchetti Aptitude. Potrebbe essere necessario cercare i comandi che funzionano su altre varianti di Linux. Le istruzioni per Fedora e macOS, ad esempio, sono disponibili in Guida introduttiva - Installazione di Git.
Configurare Git
Git nel tuo ambiente Linux deve essere configurato per interagire con il repository Git in cui è archiviato LookML. Queste istruzioni sono state scritte per i repository Git LookML archiviati in GitHub.
Nome e email
GitHub (e la maggior parte delle altre implementazioni Git) devono conoscere il tuo nome e indirizzo email per poter registrare l'attività. Configura il tuo nome e indirizzo 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 con le istruzioni 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 verrà denominata id_ed25519.
Configurare il 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
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 sarà 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 branch principale si chiama main; tuttavia, nei sistemi meno recenti, potrebbe essere chiamato 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. |
Configurare Gazer
Per utilizzare Gazer, avrai bisogno delle credenziali API per ciascuna delle istanze di sviluppo, QA 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; non sarà necessario generare nuove credenziali 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 il seguente:
gzr user me --host dev.example.looker.com
Dovresti ricevere 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 lo stesso 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 di 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