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; tuttavia, 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 come dev-my-user-ydnv, testano le modifiche con Spectacles e eseguono il commit del codice. Infine, aprono una richiesta di pull per unire il loro codice al ramo main.
Quando viene aperta la richiesta di pull, lo sviluppatore viene indirizzato a GitHub. Lo sviluppatore deve scrivere un titolo significativo per la richiesta di pull 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 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 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, verrà eseguita l'automazione Release Please e verrà aperta una seconda richiesta pull per creare una nuova release taggata. In alternativa, se esiste già una richiesta di pull aperta a questo scopo, Release Please la aggiorna. La richiesta pull di rilascio ha un numero di versione associato, nonché un log delle modifiche che include i titoli e le descrizioni delle modifiche incluse.
Quando la PR 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 QA e di produzione di Looker possono selezionare questa versione utilizzando la modalità di deployment avanzata.
Best practice per numerare le release e denominare i commit
Le release e i relativi tag possono essere denominati e numerati in qualsiasi modo abbia senso nel tuo ambiente. Tuttavia, qui viene utilizzato il controllo delle versioni semantico, che è vivamente consigliato perché funziona bene con il plug-in Release Please.
Nel controllo delle versioni semantico, 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
Conventional Commits è un sistema di denominazione dei commit in base all'impatto che hanno sugli utenti finali. Sebbene non sia obbligatorio, l'utilizzo di una denominazione convenzionale dei commit è utile anche per il plug-in Release Please.
Nella denominazione convenzionale dei commit, ogni messaggio di commit è preceduto da un indicatore dell'ambito della modifica:
- La correzione di un 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, determinare il numero semantico da utilizzare successivamente è generalmente semplice. 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 feat!:, MAJOR deve essere incrementato. Il plug-in Release Please può persino generare un file CHANGELOG e taggare automaticamente 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 contrassegnerà le modifiche 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 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 di Deployment Manager. Poi, 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.
Utilizzo di Spectacles
Spectacles può essere utilizzato da ogni sviluppatore per verificare le modifiche mentre si trova ancora nel ramo di sviluppo. Spectacles offre quattro diversi validatori:
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 esplorazione per verificare 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.
Strumento di convalida LookML
Lo strumento di convalida di LookML verifica 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
Content Validator verifica che tutti i contenuti salvati, come i Look e i dashboard definiti dall'utente, continuino a funzionare dopo l'apporto di modifiche. Per velocizzare l'esecuzione del job e fornire risultati gestibili, la convalida viene eseguita solo per i contenuti basati sulle esplorazioni che specifichi. Il validatore dei contenuti viene chiamato nel seguente modo:
$ 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 di Assert
I test di convalida delle asserzioni verificano le asserzioni dei dati che hai aggiunto al tuo 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 dell'asserzione 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, ai look e alle dashboard vengono assegnati ID numerici crescenti utilizzati nell'URL del look o della dashboard. Tuttavia, non è possibile mantenerli sincronizzati tra i sistemi. Pertanto, un URL per una specifica dashboard in fase di sviluppo non indirizzerà alla stessa dashboard in QA o produzione.
Per gli UDD è 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 durante l'importazione, in modo che un URL simile possa rimandare allo stesso UDD in fase di sviluppo, controllo qualità e produzione. L'utilizzo di slug anziché ID è una best practice, in particolare quando si fa clic su una UDD da un look o da un'altra UDD.
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 degli utenti con Gazer
Copiare contenuti come Look e dashboard tra sviluppo, controllo qualità e produzione è spesso utile. Potresti voler produrre contenuti che mostrino le nuove aggiunte di LookML o verificare 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 uno qualsiasi dei dati definiti dall'utente viene sincronizzato con le dashboard LookML, può essere aggiornato 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 si trova la 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 del dashboard.
Il file 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 dei segmenti simili funziona in modo molto simile alla migrazione dei dati definiti dall'utente. Innanzitutto, utilizza Gazer per salvare la configurazione dell'esplorazione in un file JSON:
gzr look cat LOOK_ID --host SOURCE_SYSTEM_URL --dir .
Poi, importa l'esplorazione nell'istanza di destinazione:
gzr look import Look_LOOK_ID_LOOK_NAME.json FOLDER_ID \
--host TARGET_SYSTEM_URL