En esta página, se explica cómo usar un flujo de trabajo de CI/CD en Looker después de que se instaló y configuró.
En estas instrucciones, se usa un sistema de tres niveles que incluye desarrollo, QA y producción. Sin embargo, puedes aplicar los mismos principios a un sistema de dos o cuatro niveles.
En estas instrucciones, también se supone que usas GitHub como tu proveedor de Git. Puedes usar otros proveedores de Git para crear un flujo de trabajo de CI/CD. Sin embargo, debes tener la experiencia necesaria para modificar estas instrucciones según tu proveedor.
Descripción general del flujo de trabajo
Los desarrolladores de LookML comienzan escribiendo código en su rama de desarrollo, que normalmente se llama algo como dev-my-user-ydnv, prueban sus cambios con Spectacles y confirman su código. Por último, abren una solicitud de extracción para combinar su código con la rama main.
Cuando se abre la solicitud de extracción, se dirige al desarrollador a GitHub. El desarrollador debe escribir un título significativo para la solicitud de extracción con el estilo de los commits convencionales y agregar un comentario a la descripción que se incluirá en el registro de cambios. Los resultados de las pruebas de Spectacles se deben agregar como comentarios a la PR.
A continuación, el desarrollador debe seleccionar un revisor en GitHub. El revisor recibirá una notificación y podrá agregar su revisión a la PR. Si el revisor aprueba el cambio, la PR se combina con la rama main. Se llama a un webhook y el entorno de desarrollo ahora ve el cambio.
Automáticamente, se ejecutará la automatización de Release Please y se abrirá una segunda solicitud de extracción para crear una nueva versión etiquetada. O bien, si ya hay una PR abierta para este propósito, Release Please la actualiza. La PR de la versión tiene un número de versión asociado, así como un registro de cambios que incluye los títulos y las descripciones de los cambios incluidos.
Cuando se aprueba y se combina la PR generada por Release Please, se genera una nueva etiqueta de versión y el registro de cambios se combina con la rama main. Las instancias de producción y QA de Looker pueden seleccionar esta versión con el Modo de implementación avanzado.
Prácticas recomendadas para numerar versiones y nombrar confirmaciones
Las versiones y sus etiquetas asociadas se pueden nombrar y numerar de cualquier manera que tenga sentido en tu entorno. Sin embargo, aquí se usa el control de versiones semántico, que se recomienda mucho porque funciona bien con el complemento Release Please.
En el control de versiones semántico, la versión consta de tres números separados por puntos: MAJOR.MINOR.PATCH
PATCHse incrementa cada vez que una versión corrige un error.MINORse incrementa yPATCHse restablece a cero cada vez que la versión agrega o perfecciona una función y, al mismo tiempo, es compatible con versiones anteriores.MAJORse incrementa yMINORyPATCHse establecen en cero cuando se agrega una función que no es compatible con versiones anteriores.
Conventional Commits es un sistema para nombrar las confirmaciones según el impacto que tienen en los usuarios finales. Si bien no es obligatorio, el uso de nombres de confirmación convencionales también es útil para el complemento de Release Please.
En la nomenclatura de confirmación convencional, cada mensaje de confirmación se antepone con un indicador del alcance del cambio:
- Las correcciones de errores se indican con
fix:, comofix: set proper currency symbol on sale_amt format. - Las funciones nuevas se indican con
feat:, comofeat: added explore for sales by territory. - Una función con un cambio que genera errores se indica con
feat!:, comofeat!: rewrote sales explore to use the new calendar view. - Cuando se actualiza la documentación, pero no se cambia LookML, el mensaje de confirmación comienza con
doc:.
Si los commits convencionales se usan de forma coherente, determinar el número semántico que se usará a continuación suele ser sencillo. Si el registro de confirmaciones solo consta de confirmaciones fix: y doc:, se debe incrementar el valor de PATCH. Si hay una confirmación de feat:, se debe incrementar MINOR. Si hay un feat!:, se debe incrementar MAJOR. El complemento de Release Please incluso puede generar un archivo CHANGELOG y etiquetar la versión automáticamente.
Cómo usar el modo de implementación avanzada
Después de que se realicen los cambios y se envíen como una PR en la instancia de desarrollo, el complemento Release Please etiquetará los cambios con una etiqueta de versión como v1.2.3. Luego, el modo de implementación avanzado de Looker hace que estas versiones estén disponibles en la IU de Looker para las instancias de QA y producción.
Para implementar un cambio, elige Deployment Manager en el IDE de Looker:
Haz clic en el vínculo Select Commit en la esquina superior derecha del Administrador de implementaciones. A continuación, selecciona el menú de tres puntos asociado con la etiqueta que deseas implementar y elige Implementar en el entorno:
No es necesario que vuelvas a etiquetar la implementación, así que elige Implementar sin etiquetar y presiona el botón Implementar en el entorno:
Por último, envía a producción con Deployment Manager.
Cómo usar los Spectacles
Cada desarrollador puede usar Spectacles para verificar sus cambios mientras aún están en su rama de desarrollo. Spectacles ofrece cuatro validadores diferentes:
Cuando un desarrollador envía una solicitud de extracción, es una buena práctica ejecutar estas pruebas y copiar los resultados en un comentario de la solicitud de extracción.
Validador de SQL
El validador de SQL prueba cada Explorar para verificar que todos los campos definidos en las vistas de LookML correspondan a columnas de SQL reales o expresiones de SQL válidas en la base de datos. Se llama al validador de SQL como se muestra a continuación:
$ spectacles sql --config-file config-dev.yaml \
--project PROJECT_NAME \
--explores MODEL_NAME/EXPLORE_NAME \
--branch DEV_BRANCH_NAME
Por ejemplo:
$ 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.
Validador de LookML
El validador de LookML verifica que los cambios de LookML sean válidos y no tengan errores de sintaxis. Se llama como se muestra a continuación:
$ spectacles lookml --config-file config-dev.yaml \
--project PROJECT_NAME \
--branch DEV_BRANCH_NAME
Por ejemplo:
$ 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.
Validador de contenido
El Validador de contenido prueba que todo el contenido guardado, como los Looks y los paneles definidos por el usuario (UDD), sigan funcionando después de que se realicen los cambios. Para que el trabajo se ejecute más rápido y proporcione resultados fáciles de administrar, la validación solo se realiza para el contenido que se basa en las Exploraciones que especificas. El validador de contenido se llama de la siguiente manera:
$ spectacles content --config-file config-dev.yaml \
--project PROJECT_NAME \
--explores MODEL_NAME/EXPLORE_NAME \
--branch DEV_BRANCH_NAME
Por ejemplo:
$ 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.
Validación de aserciones
Las pruebas de Assert Validation verifican las aserciones de datos que agregaste a tu LookML para verificar que los datos se lean correctamente. Por ejemplo, una prueba de datos en tu LookML podría verse de la siguiente manera:
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 validación de la aserción se llama como se muestra a continuación:
$ spectacles assert --config-file config-dev.yaml \
--project PROJECT_NAME \
--explores MODEL_NAME/EXPLORE_NAME \
--branch DEV_BRANCH_NAME
Por ejemplo:
$ 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.
Estabilidad de los vínculos para las Vistas y los paneles
De forma predeterminada, a los Looks y los paneles se les asignan IDs numéricos ascendentes que se usan en la URL del Look o el panel. Sin embargo, no hay forma de mantenerlos sincronizados en todos los sistemas. Por lo tanto, la URL de un panel específico en desarrollo no apuntará al mismo panel en QA o producción.
En el caso de los UDD, existe la opción de usar un slug en lugar de un ID como parte de la URL. El slug es un conjunto de caracteres semi aleatorio en lugar de un número. El slug se puede establecer como parte de la importación, de modo que una URL similar pueda dirigir al mismo UDD en el desarrollo, el control de calidad y la producción. Usar slugs en lugar de IDs es una práctica recomendada, en especial cuando se hace clic para acceder a una UDD desde Look o desde otra UDD.
Puedes encontrar el slug si inspeccionas el resultado de gzr dashboard cat. El slug se puede usar en la URL del panel en lugar del ID numérico.
Migra contenido del usuario con Gazer
A menudo, es útil copiar contenido, como Looks y paneles, entre los entornos de desarrollo, QA y producción. Es posible que desees producir contenido que muestre las nuevas incorporaciones de LookML o verificar que el contenido guardado siga funcionando correctamente después de los cambios en LookML. En estas situaciones, se puede usar Gazer para copiar contenido entre instancias.
Paneles de LookML
Los paneles de LookML se sincronizan entre las instancias durante el flujo de trabajo habitual de CI/CD de LookML. Sin embargo, si alguna UDD está sincronizada con los paneles de LookML, se puede actualizar con Gazer usando el siguiente comando:
gzr dashboard sync_lookml DASHBOARD_ID --host TARGET_SYSTEM_URL
Paneles definidos por el usuario
Los paneles definidos por el usuario (UDD) se pueden migrar con Gazer haciendo referencia al ID del panel y a la URL de la instancia de Looker en la que reside el UDD. Gazer guarda la configuración del panel en un archivo JSON que luego se importa a la instancia de Looker de destino.
El comando para extraer la configuración de UDD es el siguiente:
gzr dashboard cat DASHBOARD_ID --host TARGET_SYSTEM_URL --dir .
Esto generará un archivo llamado Dashboard_DASHBOARD_ID_DASHBOARD_NAME.json que contiene la configuración del panel.
El UDD se puede importar al sistema de destino con el siguiente comando:
gzr dashboard import Dashboard_DASHBOARD_ID_DASHBOARD_NAME.json FOLDER_ID \
--host TARGET_SYSTEM_URL
Vistas
La migración de aspecto funciona de manera muy similar a la migración de UDD. Primero, usa Gazer para guardar la configuración del Look en un archivo JSON:
gzr look cat LOOK_ID --host SOURCE_SYSTEM_URL --dir .
Luego, importa el Look a la instancia de destino:
gzr look import Look_LOOK_ID_LOOK_NAME.json FOLDER_ID \
--host TARGET_SYSTEM_URL