Questa pagina spiega come utilizzare un flusso di lavoro CI/CD in Looker dopo che è stato installato e configurato.
Queste istruzioni utilizzano un sistema a tre livelli che comprende sviluppo, QA e produzione. Tuttavia, puoi applicare gli stessi principi 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 le competenze per modificare queste istruzioni per il tuo provider.
Panoramica del flusso di lavoro
Gli sviluppatori LookML iniziano scrivendo il codice nel ramo di sviluppo, che in genere ha un nome simile a dev-my-user-ydnv, testano le modifiche con Spectacles ed eseguono il commit del codice. Infine, aprono una richiesta di pull per unire il codice al ramo main.
Quando viene aperta la richiesta di pull, lo sviluppatore viene indirizzato a GitHub. Lo sviluppatore deve scrivere un titolo di richiesta di pull significativo utilizzando lo stile dei commit convenzionali e aggiungere un commento alla descrizione che verrà inclusa nel log delle modifiche. I risultati dei test di Spectacles devono essere aggiunti come commenti alla richiesta di pull.
Successivamente, lo sviluppatore deve selezionare un revisore in GitHub. Il revisore riceverà una notifica e potrà aggiungere la sua revisione alla richiesta di pull. Se il revisore approva la modifica, la richiesta di pull viene unita al ramo main. Viene chiamato un webhook e l'ambiente di sviluppo ora vede la modifica.
Automaticamente, l'automazione Release Please verrà eseguita e aprirà una seconda richiesta di pull per creare una nuova release con tag. In alternativa, se è già aperta una richiesta di pull a questo scopo, Release Please la aggiorna. La richiesta di pull della release ha un numero di versione associato, nonché un log delle modifiche che include i titoli e le descrizioni delle modifiche incluse.
Quando la richiesta di pull generata da Release Please viene approvata e unita, viene generato un nuovo tag di versione e il log delle modifiche viene unito al ramo main. Le istanze di Looker di QA e produzione possono selezionare questa versione utilizzando la modalità di deployment avanzata.
Best practice per la numerazione delle release e la denominazione dei commit
Le release e i relativi tag possono essere denominati e numerati in qualsiasi modo abbia senso nel tuo ambiente. Tuttavia, qui viene utilizzata la versione semantica, che è altamente consigliata perché funziona bene con il plug-in Release Please.
Nella versione semantica, la versione è composta da tre numeri separati da punti: MAJOR.MINOR.PATCH
PATCHviene incrementato ogni volta che una release corregge un bugMINORviene incrementato ePATCHviene riportato a zero ogni volta che la release aggiunge o perfeziona una funzionalità pur essendo compatibile con le versioni precedentiMAJORviene incrementato e siaMINORchePATCHvengono impostati su zero quando viene aggiunta una funzionalità non compatibile con le versioni precedenti
I commit convenzionali sono un sistema di denominazione dei commit in base al loro impatto sugli utenti finali. Sebbene non sia obbligatorio, l'utilizzo della denominazione dei commit convenzionali è utile anche per il plug-in Release Please.
Nella denominazione dei commit convenzionali, ogni messaggio di commit è preceduto da un indicatore dell'ambito della modifica:
- Una correzione di bug è indicata con
fix:, ad esempiofix: set proper currency symbol on sale_amt format - Una nuova funzionalità è indicata con
feat:, ad esempiofeat: added explore for sales by territory - Una funzionalità con una modifica che causa interruzioni è indicata da
feat!:, ad esempiofeat!: rewrote sales explore to use the new calendar view - Quando la documentazione viene aggiornata, ma LookML non viene modificato, il messaggio di commit inizia con
doc:
Se i commit convenzionali vengono utilizzati in modo coerente, in genere è semplice determinare il numero semantico da utilizzare successivamente. Se il log dei commit è composto solo da commit fix: e doc:, PATCH deve essere incrementato. Se è presente un commit feat:, MINOR deve essere incrementato. Se è presente un commit feat!:, MAJOR deve essere incrementato. Il plug-in Release Please può persino generare automaticamente un file CHANGELOG e taggare la release.
Utilizzo della modalità di deployment avanzata
Dopo che le modifiche sono state apportate e inviate come richiesta di pull nell'istanza di sviluppo, il plug-in Release Please le taggherà con un tag di versione come v1.2.3. La modalità di deployment avanzata di Looker rende quindi disponibili queste versioni nell'interfaccia utente di Looker per le istanze di QA e produzione.
Per eseguire il deployment di una modifica, scegli Deployment Manager dall'IDE Looker:
Fai clic sul link Seleziona commit in alto a destra di Deployment Manager. Quindi, seleziona il menu con tre puntini associato al tag di cui vuoi eseguire il deployment e scegli Esegui il deployment nell'ambiente:
Non devi taggare di nuovo il deployment, quindi scegli Esegui il deployment senza taggare e premi il pulsante Esegui il deployment nell'ambiente:
Infine, esegui il push in produzione utilizzando Deployment Manager.
Utilizzo di Spectacles
Ogni sviluppatore può utilizzare Spectacles per verificare le modifiche mentre si trova ancora nel ramo di sviluppo. Spectacles offre quattro diversi strumenti di convalida:
Quando uno sviluppatore invia una richiesta di pull, è buona norma eseguire questi test e copiare i risultati in un commento nella richiesta di pull.
Strumento di convalida SQL
Lo strumento di convalida SQL testa ogni Esplora per verificare che tutti i campi definiti nelle viste LookML corrispondano a colonne SQL effettive o a espressioni SQL valide nel database. Lo strumento di convalida SQL viene chiamato come mostrato di seguito:
$ spectacles sql --config-file config-dev.yaml \
--project PROJECT_NAME \
--explores MODEL_NAME/EXPLORE_NAME \
--branch DEV_BRANCH_NAME
Ad esempio:
$ 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.
Strumento di convalida LookML
Lo strumento di convalida LookML verifica che le modifiche LookML siano valide e non contengano errori di sintassi. Viene chiamato come mostrato di seguito:
$ spectacles lookml --config-file config-dev.yaml \
--project PROJECT_NAME \
--branch DEV_BRANCH_NAME
Ad esempio:
$ 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.
Strumento di convalida dei contenuti
Lo strumento di convalida dei contenuti verifica che tutti i contenuti salvati, come i Look e le dashboard definite dall'utente, continuino a funzionare dopo l'apporto delle modifiche. Per velocizzare l'esecuzione del job e fornire risultati gestibili, la convalida viene eseguita solo per i contenuti basati sulle esplorazioni specificate. Lo strumento di convalida dei contenuti viene chiamato come segue:
$ spectacles content --config-file config-dev.yaml \
--project PROJECT_NAME \
--explores MODEL_NAME/EXPLORE_NAME \
--branch DEV_BRANCH_NAME
Ad esempio:
$ 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.
Convalida Assert
La convalida Assert testa le asserzioni dei dati che hai aggiunto a LookML per verificare che i dati vengano letti correttamente. Ad esempio, un test dei dati in LookML potrebbe avere il seguente aspetto:
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 convalida Assert viene chiamata come mostrato di seguito:
$ spectacles assert --config-file config-dev.yaml \
--project PROJECT_NAME \
--explores MODEL_NAME/EXPLORE_NAME \
--branch DEV_BRANCH_NAME
Ad esempio:
$ 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.
Stabilità dei link per Look e dashboard
Per impostazione predefinita, a Look e dashboard vengono assegnati ID numerici crescenti utilizzati nell'URL del Look o della dashboard. Tuttavia, non è possibile mantenerli sincronizzati tra i sistemi. Di conseguenza, un URL per una dashboard specifica in fase di sviluppo non rimanderà alla stessa dashboard in QA o produzione.
Per le dashboard definite dall'utente è disponibile un'opzione per utilizzare uno slug anziché un ID come parte dell'URL. Lo slug è un insieme di caratteri semi-casuali anziché un numero. Lo slug può essere impostato come parte dell'importazione, in modo che un URL simile possa rimandare alla stessa dashboard definita dall'utente in fase di sviluppo, QA e produzione. L'utilizzo di slug anziché ID è una best practice, in particolare quando si fa clic su una dashboard definita dall'utente da Look o da un'altra dashboard definita dall'utente.
Lo slug può essere trovato esaminando l'output di gzr dashboard cat. Lo slug può essere utilizzato nell'URL della dashboard al posto dell'ID numerico.
Migrazione dei contenuti dell'utente con Gazer
La copia di contenuti come Look e dashboard tra sviluppo, QA e produzione è spesso utile. Potresti voler produrre contenuti che mostrino le nuove aggiunte LookML o verificare che i contenuti salvati continuino a funzionare correttamente dopo le modifiche LookML. In queste situazioni, Gazer può essere utilizzato per copiare i contenuti tra le istanze.
Dashboard LookML
Le dashboard LookML vengono sincronizzate tra le istanze durante il normale flusso di lavoro CI/CD LookML. Tuttavia, se le dashboard definite dall'utente vengono sincronizzate con le dashboard LookML, possono essere aggiornate con Gazer utilizzando il seguente comando:
gzr dashboard sync_lookml DASHBOARD_ID --host TARGET_SYSTEM_URL
Dashboard definite dall'utente
Le dashboard definite dall'utente possono essere migrate con Gazer facendo riferimento all'ID della dashboard e all'URL dell'istanza di Looker in cui si trova la dashboard definita dall'utente. Gazer salva la configurazione della dashboard in un file JSON che viene poi importato nell'istanza di Looker di destinazione.
Il comando per estrarre la configurazione della dashboard definita dall'utente è il seguente:
gzr dashboard cat DASHBOARD_ID --host TARGET_SYSTEM_URL --dir .
Verrà generato un file denominato Dashboard_DASHBOARD_ID_DASHBOARD_NAME.json che contiene la configurazione della dashboard.
La dashboard definita dall'utente può essere importata nel sistema di destinazione utilizzando il seguente comando:
gzr dashboard import Dashboard_DASHBOARD_ID_DASHBOARD_NAME.json FOLDER_ID \
--host TARGET_SYSTEM_URL
Look
La migrazione di Look funziona in modo molto simile alla migrazione di dashboard definite dall'utente. Innanzitutto, utilizza Gazer per salvare la configurazione di Look in un file JSON:
gzr look cat LOOK_ID --host SOURCE_SYSTEM_URL --dir .
Quindi, importa Look nell'istanza di destinazione:
gzr look import Look_LOOK_ID_LOOK_NAME.json FOLDER_ID \
--host TARGET_SYSTEM_URL