Questa pagina spiega come utilizzare un flusso di lavoro CI/CD in Looker dopo averlo 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 disporre delle competenze necessarie per modificare queste istruzioni per il tuo provider.
Panoramica del flusso di lavoro
Gli sviluppatori LookML iniziano scrivendo il codice nel proprio ramo di sviluppo, che in genere si chiama dev-my-user-ydnv, testano le modifiche con Spectacles e eseguono il commit del codice. Infine, aprono una richiesta di pull per unire il proprio codice al ramo main.
Quando la richiesta di pull viene aperta, lo sviluppatore viene indirizzato a GitHub. Lo sviluppatore deve scrivere un titolo significativo della RP utilizzando lo stile dei commit convenzionali e aggiungere un commento alla descrizione che verrà incluso nel log delle modifiche. I risultati dei test di Spectacles devono essere aggiunti come commenti alla RP.
Successivamente, lo sviluppatore deve selezionare un revisore su GitHub. Il revisore riceverà una notifica e potrà aggiungere la sua recensione alla RP. Se il revisore approva la modifica, la PR viene unita al ramo main. Viene chiamato un webhook e l'ambiente di sviluppo ora vede la modifica.
Verrà eseguita automaticamente l'automazione Release Please e verrà aperta una seconda PR per creare una nuova release con tag. In alternativa, se esiste già una RP aperta a questo scopo, Release Please aggiorna la RP. Al comunicato stampa della release è associato un numero di versione, 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 QA e di produzione di Looker 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 associati possono essere denominati e numerati in qualsiasi modo abbia senso nel tuo ambiente. Tuttavia, qui viene utilizzato il versionamento semantico, che è vivamente consigliato perché funziona bene con il plug-in Release Please.
Nelle versioni semantiche, la versione è composta da tre numeri separati da punti: MAJOR.MINOR.PATCH
PATCHviene incrementato ogni volta che una release corregge un bugMINORviene incrementato ePATCHviene reimpostato su zero ogni volta che la release aggiunge o perfeziona una funzionalità mantenendo la compatibilità 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 all'impatto che hanno sugli utenti finali. Sebbene non sia obbligatorio, l'utilizzo di una convenzione di denominazione dei commit è utile anche per il plug-in Release Please.
Nella convenzione di denominazione dei commit, a ogni messaggio del commit viene anteposto 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 comporta l'interruzione è indicata da
feat!:, ad esempiofeat!: rewrote sales explore to use the new calendar view - Quando i documenti vengono aggiornati, ma LookML non viene modificato, il messaggio del commit inizia con
doc:
Se i commit convenzionali vengono utilizzati in modo coerente, determinare il numero semantico da utilizzare successivamente è generalmente semplice. Se il log dei commit è costituito solo da commit fix: e doc:, PATCH deve essere incrementato. Se esiste un commit feat:, MINOR deve essere incrementato. Se è presente un feat!:, MAJOR deve essere incrementato. Il plug-in Release Please può anche generare un file CHANGELOG e taggare la release automaticamente.
Utilizzo della modalità di deployment avanzata
Dopo che le modifiche sono state apportate e inviate come PR nell'istanza di sviluppo, il plug-in Release Please taggherà le modifiche con un tag di versione come v1.2.3. La modalità di deployment avanzata di Looker rende quindi queste versioni disponibili nell'interfaccia utente di Looker per le istanze di QA e di produzione.
Per eseguire il deployment di una modifica, scegli Deployment Manager dall'IDE di Looker:
Fai clic sul link Seleziona commit in alto a destra in 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 è necessario taggare di nuovo il deployment, quindi scegli Esegui il deployment senza tagging e premi il pulsante Esegui il deployment nell'ambiente:
Infine, esegui il push in produzione utilizzando Deployment Manager.
Utilizzare Spectacles
Spectacles può essere utilizzato da ogni sviluppatore per verificare le modifiche mentre si trovano ancora nel ramo di sviluppo. Spectacles offre quattro diversi tipi di verifica:
Quando uno sviluppatore invia una richiesta di pull, è buona norma eseguire questi test e copiare i risultati in un commento nella richiesta.
Strumento di convalida SQL
Lo strumento di convalida SQL testa ogni esplorazione per assicurarsi che tutti i campi definiti nelle visualizzazioni LookML corrispondano a colonne SQL effettive o a espressioni SQL valide nel database. Il validatore 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.
Validatore di LookML
Lo strumento di convalida di LookML garantisce che le modifiche di 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, funzionino ancora dopo le modifiche. Per velocizzare l'esecuzione del job e fornire risultati gestibili, la convalida viene eseguita solo per i contenuti basati sulle esplorazioni specificate. Il validatore 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 dell'affermazione
La convalida delle asserzioni verifica le asserzioni dei dati che hai aggiunto a LookML per assicurarti 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 dell'affermazione 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 che vengono utilizzati nell'URL del look o della dashboard. Tuttavia, non è possibile mantenerli sincronizzati tra i sistemi. Pertanto, un URL per una dashboard specifica in fase di sviluppo non indirizzerà alla stessa dashboard in QA o in produzione.
Per i dati proprietari è possibile utilizzare un slug anziché un ID all'interno dell'URL. Il slug è un insieme di caratteri semi-casuali anziché un numero. Lo slug può essere impostato nell'ambito dell'importazione in modo che un URL simile possa puntare allo stesso UDD in fase di sviluppo, QA e produzione. L'utilizzo di slug anziché ID è una best practice, in particolare quando si "fa clic" su un UDD da Look o da un altro UDD.
Puoi trovare il slug esaminando l'output di gzr dashboard cat. Lo slug può essere utilizzato nell'URL della dashboard al posto dell'ID numerico.
Eseguire la migrazione dei contenuti utente con Gazer
Spesso è utile copiare contenuti come look e dashboard tra lo sviluppo, il QA e la produzione. Potresti voler produrre contenuti che mettano in evidenza le nuove aggiunte a LookML o assicurarti che i contenuti salvati funzionino ancora correttamente dopo le modifiche a 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 di LookML. Tuttavia, se gli UDD sono sincronizzati con le dashboard LookML, possono essere aggiornati con Gazer utilizzando il seguente comando:
gzr dashboard sync_lookml DASHBOARD_ID --host TARGET_SYSTEM_URL
Dashboard definite dall'utente
È possibile eseguire la migrazione delle dashboard definite dall'utente (UDD) con Gazer facendo riferimento all'ID della dashboard e all'URL dell'istanza Looker in cui risiede l'UDD. Gazer salva la configurazione della dashboard in un file JSON che viene poi importato nell'istanza Looker di destinazione.
Il comando per estrarre la configurazione UDD è il seguente:
gzr dashboard cat DASHBOARD_ID --host TARGET_SYSTEM_URL --dir .
Verrà generato un file denominato Dashboard_DASHBOARD_ID_DASHBOARD_NAME.json contenente la configurazione della dashboard.
L'UDD può essere importato 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 UDD. Innanzitutto, utilizza Gazer per salvare la configurazione del look in un file JSON:
gzr look cat LOOK_ID --host SOURCE_SYSTEM_URL --dir .
Importa quindi il look nell'istanza di destinazione:
gzr look import Look_LOOK_ID_LOOK_NAME.json FOLDER_ID \
--host TARGET_SYSTEM_URL