Se usó la API de Cloud Translation para traducir esta página.

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 después de instalarlo y configurarlo.

En estas instrucciones, se usa un sistema de tres niveles que comprende 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 supone 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 para tu proveedor.

Descripción general del flujo de trabajo

Los desarrolladores de LookML comienzan por escribir código en su rama de desarrollo, que suele llamarse dev-my-user-ydnv, prueban sus cambios con Spectacles y confirman su código. Por último, abre una solicitud de extracción para combinar su código con la rama main.

Cuando se abre la solicitud de extracción, el desarrollador se dirige a GitHub. El desarrollador debe escribir un título de PR significativo con el estilo de confirmación convencional y agregar un comentario a la descripción que se incluirá en el registro de cambios. Los resultados de las pruebas de Spectacles deben agregarse 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 opinión a la PR. 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.

De forma automática, se ejecutará la automatización de Release Please y se abrirá una segunda solicitud de cambios para crear una nueva versión etiquetada. O bien, si ya hay una PR abierta para este fin, Release Please actualiza esa PR. La PR de lanzamiento 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 solicitud de cambios 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 QA y producción de Looker pueden seleccionar esta versión con el modo de implementación avanzada.

Prácticas recomendadas para numerar las versiones y nombrar las 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 enfáticamente 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

PATCH se incrementa cada vez que una versión corrige un error.
MINOR se incrementa y PATCH se restablece a cero cada vez que la versión agrega o define mejor una función sin dejar de ser retrocompatible.
MAJOR se incrementa y MINOR y PATCH se establecen en cero cuando se agrega una función que no es retrocompatible.

Las confirmaciones convencionales son un sistema de nombres de 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 Release Please.

En la nomenclatura de confirmación convencional, a cada mensaje de confirmación se le antepone un indicador del alcance del cambio:

Una corrección de errores se indica con fix:, como fix: set proper currency symbol on sale_amt format.
Una función nueva se indica con feat:, como feat: added explore for sales by territory.
Una función con un cambio drástico se indica con feat!:, como feat!: rewrote sales explore to use the new calendar view.
Cuando se actualizan los documentos, pero no se cambia LookML, el mensaje de confirmación comienza con doc:.

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

Cómo usar el modo de implementación avanzada

Después de realizar los cambios y enviarlos como una solicitud de cambios 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 pone estas versiones a disposición de la IU de Looker para las instancias de QA y producción.

Para implementar un cambio, elige Deployment Manager en el IDE de Looker:

Ubicación de Looker Deployment Manager en el IDE.

Haz clic en el vínculo Seleccionar confirmación en la parte 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:

IU de Deployment Manager de Looker para implementar en el entorno

No es necesario volver a etiquetar la implementación, así que elige Implementar sin etiquetar y presiona el botón Implementar en el entorno:

IU de Deployment Manager de Looker para implementar sin etiquetado

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

Cómo usar Spectacles

Cada desarrollador puede usar Spectacles para verificar sus cambios mientras aún están en la rama de desarrollo. Spectacles ofrece cuatro validadores diferentes:

SQL
LookML
Contenido
Confirmar

Cuando un desarrollador envía una solicitud de extracción, se recomienda ejecutar estas pruebas y copiar los resultados en un comentario de la solicitud.

Validador de SQL

El validador de SQL prueba cada Explorar para garantizar 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 garantiza 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 el contenido guardado, como los diseños y los paneles definidos por el usuario (UDD), siga funcionando después de realizar cambios. Para que la tarea 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 especifiques. Se llama al validador de contenido 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 aserción

La validación de aserciones prueba las aserciones de datos que agregaste a tu LookML para garantizar 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 ;;
  }
}

Se llama a la validación de aserción 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, los informes y los paneles tienen IDs numéricos ascendentes que se usan en la URL del informe o panel. Sin embargo, no hay forma de mantenerlos sincronizados en todos los sistemas. Por lo tanto, una URL para 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 fragmento en lugar de un ID como parte de la URL. El slug es un conjunto semialeatorio de caracteres en lugar de un número. El fragmento se puede configurar como parte de la importación para que una URL similar pueda dirigir a la misma UDD en desarrollo, control de calidad y producción. Una práctica recomendada es usar slugs en lugar de IDs, en especial cuando se hace clic en una UDD desde Look o desde otra UDD.

Para encontrar el fragmento, inspecciona el resultado de gzr dashboard cat. El fragmento se puede usar en la URL del panel en lugar del ID numérico.

Cómo migrar el contenido de los usuarios con Gazer

A menudo, es útil copiar contenido, como los diseños y los paneles, entre el desarrollo, el control de calidad y la producción. Te recomendamos que crees contenido que muestre las nuevas incorporaciones de LookML o que te asegures de 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 de CI/CD de LookML normal. Sin embargo, si hay UDD sincronizadas con paneles de LookML, se pueden actualizar con Gazer mediante 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 .

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

La 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 de Look en un archivo JSON:

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

Luego, importa la vista en la instancia de destino:

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