Uso y flujo de trabajo de CI/CD de Looker

En esta página se explica cómo usar un flujo de trabajo de CI/CD en Looker una vez que se ha instalado y configurado.

En estas instrucciones se utiliza un sistema de tres niveles que incluye desarrollo, control de calidad y producción. Sin embargo, puedes aplicar los mismos principios a un sistema de dos o cuatro niveles.

En estas instrucciones también se presupone que usas GitHub como proveedor de Git. Puedes usar otros proveedores de Git para crear un flujo de trabajo de CI/CD. Sin embargo, debes tener los conocimientos necesarios para modificar estas instrucciones según tu proveedor.

Información general sobre los flujos de trabajo

Los desarrolladores de LookML empiezan escribiendo código en su rama de desarrollo, que normalmente se llama dev-my-user-ydnv, prueban los cambios con Spectacles y confirman el 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 siguiendo el estilo de los commits convencionales y añadir un comentario a la descripción que se incluirá en el registro de cambios. Los resultados de las pruebas de Spectacles deben añadirse como comentarios a la PR.

A continuación, el desarrollador debe seleccionar un revisor en GitHub. El revisor recibirá una notificación y podrá añadir su revisión a la solicitud de incorporación. Si el revisor aprueba el cambio, la solicitud de extracción 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 Release Please y se abrirá una segunda solicitud de extracción para crear una nueva versión etiquetada. Si ya hay una PR abierta con este fin, Release Please la actualiza. La solicitud de extracción 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 control de calidad y de producción de Looker pueden seleccionar esta versión mediante el modo de despliegue avanzado.

Prácticas recomendadas para numerar versiones y nombrar confirmaciones

Las versiones y sus etiquetas asociadas se pueden nombrar y numerar de cualquier forma que tenga sentido en tu entorno. Sin embargo, aquí se usa el control de versiones semántico, que es muy recomendable porque funciona bien con el plugin Release Please.

En el control de versiones semántico, la versión consta de tres números separados por puntos: MAJOR.MINOR.PATCH

  • PATCH se incrementa cada vez que una versión corrige un error
  • MINOR se incrementa y PATCH vuelve a cero cada vez que la versión añade o perfecciona una función y, al mismo tiempo, es compatible con versiones anteriores.
  • MAJOR se incrementa y MINOR y PATCH se definen como cero cuando se añade una función que no es compatible con versiones anteriores

Conventional Commits es un sistema para nombrar los commits según el impacto que tienen en los usuarios finales. Aunque no es obligatorio, el uso de nombres de confirmación convencionales también es útil para el complemento Release Please.

En la nomenclatura de commits convencionales, cada mensaje de commit se precede con un indicador del ámbito del cambio:

  • Las correcciones de errores se indican con fix:, como fix: set proper currency symbol on sale_amt format.
  • Las nuevas funciones se indican con feat:, como feat: added explore for sales by territory
  • Las funciones con un cambio incompatible se indican con feat!:, como feat!: rewrote sales explore to use the new calendar view.
  • Cuando se actualiza la documentación, pero no se modifica el LookML, el mensaje de confirmación empieza por doc:.

Si los commits convencionales se usan de forma coherente, suele ser fácil determinar el número semántico que se debe usar a continuación. Si el registro de confirmaciones solo consta de confirmaciones fix: y doc:, se debe incrementar el PATCH. Si hay una confirmación de feat:, se debe incrementar MINOR. Si hay un feat!:, se debe incrementar MAJOR. El complemento Release Please puede incluso generar un archivo CHANGELOG y etiquetar la versión automáticamente.

Usar el modo de despliegue avanzado

Una vez que se hayan realizado los cambios y se hayan enviado como una solicitud de extracción en la instancia de desarrollo, el complemento Release Please etiquetará los cambios con una etiqueta de versión, como v1.2.3. El modo de implementación avanzada de Looker hace que estas versiones estén disponibles en la interfaz de usuario de Looker para las instancias de control de calidad y de producción.

Para implementar un cambio, elige Gestor de implementaciones en el IDE de Looker:

Ubicación de Deployment Manager de Looker en el IDE.

En la parte superior derecha de Deployment Manager, haga clic en el enlace Seleccionar confirmación. A continuación, seleccione el menú de tres puntos asociado a la etiqueta que quiera implementar y elija Implementar en el entorno:

Interfaz de usuario de Looker Deployment Manager para desplegar en el entorno.

No es necesario que etiquetes el despliegue de nuevo, así que elige Desplegar sin etiquetar y pulsa el botón Desplegar en el entorno:

Interfaz de usuario de Deployment Manager de Looker para implementar sin etiquetar.

Por último, envía el contenido a producción con Deployment Manager.

Usar las gafas 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 recomendable ejecutar estas pruebas y copiar los resultados en un comentario de la solicitud.

Validador de SQL

El validador de SQL prueba cada Exploración para verificar que todos los campos definidos en las vistas de LookML corresponden a columnas SQL reales o a expresiones 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 comprueba 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

Content Validator comprueba que el contenido guardado, como los gráficos y los paneles de control definidos por el usuario, siga funcionando después de que se hayan hecho cambios. Para que el trabajo se ejecute más rápido y proporcione resultados fáciles de gestionar, la validación solo se realiza en el contenido basado en las Exploraciones que especifiques. 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 validación de aserciones comprueban las aserciones de datos que haya añadido a su LookML para verificar que los datos se leen correctamente. Por ejemplo, una prueba de datos en LookML podría tener el siguiente aspecto:

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 aserciones 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.

De forma predeterminada, a los Looks y a los paneles de control se les asignan IDs numéricos ascendentes que se usan en la URL del Look o del panel de control. Sin embargo, no hay forma de mantenerlos sincronizados en todos los sistemas. Por lo tanto, una URL de un panel de control específico en desarrollo no apuntará al mismo panel de control en control de calidad o producción.

En el caso de los UDDs, 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 aleatorio en lugar de un número. El slug se puede definir como parte de la importación para que una URL similar pueda apuntar al mismo UDD en los entornos de desarrollo, control de calidad y producción. Usar slugs en lugar de IDs es una práctica recomendada, sobre todo cuando se accede a un DDU desde Look u otro DDU.

El slug se puede encontrar inspeccionando la salida de gzr dashboard cat. El slug se puede usar en la URL del panel de control en lugar del ID numérico.

Migrar contenido de usuarios con Gazer

A menudo, es útil copiar contenido, como aspectos y paneles de control, entre los entornos de desarrollo, control de calidad y producción. Puede que quieras crear contenido que muestre las nuevas incorporaciones de LookML o verificar que el contenido guardado sigue funcionando correctamente después de los cambios en LookML. En estas situaciones, puedes usar Gazer para copiar contenido entre instancias.

Paneles de control de LookML

Los paneles de control de LookML se sincronizan entre 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 mediante el siguiente comando:

gzr dashboard sync_lookml DASHBOARD_ID --host TARGET_SYSTEM_URL

Paneles de control definidos por el usuario

Los paneles definidos por el usuario se pueden migrar con Gazer haciendo referencia al ID del panel y a la URL de la instancia de Looker en la que se encuentra el panel. Gazer guarda la configuración del panel de control en un archivo JSON que 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 .

Se generará un archivo llamado Dashboard_DASHBOARD_ID_DASHBOARD_NAME.json que contiene la configuración del panel de control.

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

Looks

La migración de aspectos funciona de forma muy similar a la migración de datos definidos por el usuario. Primero, usa Gazer para guardar la configuración de Look en un archivo JSON:

gzr look cat LOOK_ID --host SOURCE_SYSTEM_URL --dir .

A continuación, importa el Look a la instancia de destino:

gzr look import Look_LOOK_ID_LOOK_NAME.json FOLDER_ID \
    --host TARGET_SYSTEM_URL