En esta página, se explica cómo instalar y configurar los componentes necesarios para implementar un flujo de trabajo de CI/CD en Looker.
En estas instrucciones, se usa un sistema de tres niveles que incluye desarrollo, control de calidad y producción. Sin embargo, se pueden aplicar los mismos principios a un sistema de dos o cuatro niveles.
En estas instrucciones, también se supone el uso de 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 para tu proveedor.
Sigue las instrucciones de la sección que sea relevante para ti:
- Requisitos previos
- Pasos de configuración solo para la primera vez
- Pasos de configuración para cada desarrollador de Looker
Requisitos previos
Entorno de Linux
En este proceso, se usan herramientas llamadas Gazer y Spectacles que están diseñadas para funcionar con sistemas operativos similares a Unix. Cada desarrollador de LookML debe tener acceso a la línea de comandos en un entorno de Linux o macOS en el que planees ejecutar tu flujo de trabajo de CI/CD.
Si utilizas Windows, Gazer y Spectacles se pueden usar dentro del subsistema de Windows para Linux (WSL) de Microsoft. WSL te permite ejecutar una variedad de variantes de Linux. Si no tienes un sistema operativo Linux preferido, la versión más reciente de Ubuntu Linux es una buena opción debido a su amplia compatibilidad.
Estas instrucciones proporcionan ejemplos para sistemas Linux y pueden requerir modificaciones si usas macOS o WSL.
Una instancia de Looker por nivel
Para habilitar esta configuración, necesitarás una instancia de Looker para cada nivel de tu sistema. Por ejemplo, un sistema con una etapa de desarrollo, una etapa de QA y una etapa de producción necesitará tres instancias distintas. Las instancias pueden estar alojadas por Google o por el cliente.
Nombres de conexiones idénticos
Las conexiones de base de datos deben tener el mismo nombre dentro de cada instancia de Looker, independientemente del nivel que representen. Por ejemplo, una conexión sales debería tener ese nombre en todas las instancias, en lugar de sales_dev o sales_qa.
Las conexiones pueden apuntar a la misma base de datos o a diferentes bases de datos. Sin embargo, si apuntan a la misma base de datos, deben tener diferentes esquemas temporales definidos para que las tablas derivadas persistentes en la instancia de desarrollo o QA no interfieran en la producción.
Por ejemplo, si se usa la misma base de datos para las tres instancias, podrían configurarse de la siguiente manera:
| Producción | Control de calidad | Desarrollo | |
| Nombre de la conexión | sales |
sales |
sales |
| Base de datos | sales_db |
sales_db |
sales_db |
| Esquema de Scratch | prod_sales_scratch |
qa_sales_scratch |
dev_sales_scratch |
O bien, si se utiliza una base de datos única para las tres instancias, estas se podrían configurar de la siguiente manera:
| Producción | Control de calidad | Desarrollo | |
| Nombre de la conexión | sales |
sales |
sales |
| Base de datos | sales_db_prod |
sales_db_qa |
sales_db_dev |
| Esquema de Scratch | sales_scratch |
sales_scratch |
sales_scratch |
Repositorio de Git
Se usará un único repositorio de Git para cada proyecto en los tres niveles. La instancia de desarrollo realizará un seguimiento de la rama main, mientras que las instancias de QA y producción, por lo general, apuntarán a etiquetas git (que se describen en más detalle más adelante).
Pasos de configuración solo para la primera vez
Solo alguien con permisos de administrador de Looker y permisos de administrador en su proveedor de Git debe completar una vez los pasos de esta sección.
Credenciales de Git
El entorno Linux de cada desarrollador debe conectarse al mismo repositorio que usas para administrar tu LookML. Probablemente, este sea un repositorio externo alojado en un servicio como GitHub. Necesitarás una cuenta de ese servicio que tenga las credenciales adecuadas para configurar el repositorio. Con la cuenta, puedes configurar una clave SSH para permitir que tu entorno de Linux se conecte a ese servicio automáticamente.
Para GitHub, sigue las instrucciones que se indican en Agrega una clave SSH nueva a tu cuenta de GitHub.
Crea y configura un repositorio de servidor Git
Para que funcione el flujo de trabajo de CI/CD, LookML debe almacenarse en un repositorio de Git y conectarse a un proyecto de Looker. En la configuración del proyecto, el Git Production Branch Name debe estar configurado como main y la opción Enable Advanced Deploy Mode está habilitada.
Si aún no realizaste estos pasos, sigue estas instrucciones para GitHub:
Crear un repositorio nuevo
- En la IU de GitHub, presiona el botón + de la esquina superior derecha y, luego, selecciona New repository.
- Selecciona el propietario (probablemente tu organización) y, luego, ingresa un REPOSITORY_NAME.
- Elige si quieres que el repositorio sea público o privado (los repositorios privados requieren una suscripción pagada de GitHub) y marca la casilla para inicializarlo con un archivo README.
- Presiona el botón Crear repositorio.
- Presiona el botón verde etiquetado como <>. Code y copia la URL de SSH. Tendrá un aspecto similar a
git@github.com:org_name/REPOSITORY_NAME.git. - En Looker, crea un proyecto nuevo.
- Ingresa al modo de desarrollo y elige el elemento de configuración del proyecto en la barra lateral izquierda y, luego, Configurar Git.
- Pega la URL del repositorio (
git@github.com:org_name/REPOSITORY_NAME.giten este ejemplo) y selecciona Continuar. - Copia la clave de implementación y regresa a la IU de GitHub de este repositorio.
- Selecciona Configuración y, luego, Implementar claves.
- Haz clic en el botón Agregar clave de implementación y pega la clave de implementación en el campo Clave.
- Agrega un título como
Looker-REPOSITORY_NAME, marca la casilla de verificación Permitir acceso de escritura y presiona el botón Agregar clave. - Regresa a Looker y elige Test and Finalize Setup.
- Vuelve a elegir la configuración del proyecto en la barra lateral izquierda. Cambia el Git Production Branch Name a
main. - Elige Habilitar el modo de implementación avanzada y selecciona Guardar configuración del proyecto.
Debajo del ícono de configuración del proyecto en el lado izquierdo, debería ver un ícono de implementación para Deployment Manager.
Usar repositorio existente
- Navega al repositorio de GitHub que almacena tu LookML.
- Presiona el botón verde etiquetado como <>. Code y copia la URL de SSH. Tendrá un aspecto similar a
git@github.com:org_name/REPOSITORY_NAME.git. - En Looker, crea un proyecto nuevo.
- Ingresa al modo de desarrollo y elige el elemento de configuración del proyecto en la barra lateral izquierda. Luego, selecciona Configurar Git.
- Pega la URL del repositorio (
git@github.com:org_name/REPOSITORY_NAME.giten este ejemplo) y selecciona Continuar. - Copia la clave de implementación y regresa a la IU de GitHub de este repositorio.
- Selecciona Configuración y, luego, Implementar claves.
- Haz clic en el botón Agregar clave de implementación y pega la clave de implementación en el campo Clave.
- Agrega un título como
Looker-REPOSITORY_NAME, marca la casilla de verificación Permitir acceso de escritura y presiona el botón Agregar clave. - Regresa a Looker y elige Test and Finalize Setup.
- Vuelve a elegir la configuración del proyecto en la barra lateral izquierda. Cambia el Git Production Branch Name a
main. - Elige Habilitar el modo de implementación avanzada y selecciona Guardar configuración del proyecto.
Debajo del ícono de configuración del proyecto en el lado izquierdo, debería ver un ícono de implementación para Deployment Manager.
Crea acciones de GitHub
Resulta útil crear varias acciones de GitHub para que se realicen varias verificaciones automáticamente cada vez que se realicen cambios en LookML. Para agregar estas acciones, debes poder realizar cambios en tu repositorio de Git en tu entorno de Linux. Si aún no está disponible, sigue las instrucciones para configurar Git.
Para agregar las acciones de GitHub, ve al directorio de tu repositorio en el entorno de Linux y agrega el subdirectorio .github/workflows. Después de configurarlas, estas acciones se pueden ejecutar manualmente desde la página Acciones de la IU de GitHub.
Look‐At‐Me‐Sideways (LAMS)
LAMS es un linter de código abierto que inspecciona tu LookML en busca de errores y prácticas no recomendadas. Agrega un archivo llamado lams.yml al directorio .github/workflows con este contenido:
name: LAMS
on:
pull_request:
branches: [ main ]
push:
workflow_dispatch:
jobs:
lams_job:
runs-on: ubuntu-latest
name: LAMS LookML Linter Job
steps:
- name: Checkout your LookML
uses: actions/checkout@v1
- name: Setup Node
uses: actions/setup-node@v1
with:
node-version: '16.x'
- name: Install LAMS
run: npm install -g @looker/look-at-me-sideways@3
- name: Run LAMS
run: lams --reporting=no
Cada vez que se envía una confirmación a GitHub o se abre una solicitud de extracción para combinar código con la rama main, se ejecutará LAMS.
Suelta
Lanzar es una herramienta de código abierto que etiqueta automáticamente los lanzamientos con los números de versión adecuados.
Agrega un archivo llamado release-please.yml al directorio .github/workflows con este contenido:
name: release-please
on:
push:
branches:
- main
workflow_dispatch:
permissions:
contents: write
pull-requests: write
jobs:
release-please:
runs-on: ubuntu-latest
steps:
- uses: google-github-actions/release-please-action@v3
with:
release-type: simple
package-name: sales_project
Confirmaciones convencionales
Esta acción de GitHub garantizará que se abra una solicitud de extracción con un título que cumpla con el estándar de confirmación convencional.
Agrega un archivo llamado lint_pr_title.yml al directorio .github/workflows con este contenido:
name: "Lint Pull Request Title"
on:
pull_request_target:
types:
- opened
- edited
- synchronize
jobs:
main:
name: Validate PR title
runs-on: ubuntu-latest
steps:
- uses: amannn/action-semantic-pull-request@v5
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
Envía los cambios a GitHub
Por último, usa los siguientes comandos para confirmar estos cambios de acción de GitHub y enviarlos a GitHub:
git add .github/workflows/
git commit -m "chore: Added github actions"
git push
Cómo proteger la rama main
En la IU de GitHub, debes habilitar las protecciones de la rama para la rama main, de modo que los desarrolladores comunes no puedan enviar cambios directamente a esa rama. En su lugar, realizan cambios en una rama diferente y, luego, abren una solicitud de extracción. Otro desarrollador puede revisar la solicitud de extracción antes de que se apruebe y se combine con main.
Para configurar la protección de ramas, ve a la IU de GitHub del repositorio, elige Settings y, luego, Branches, y presiona el botón Add Branch protection rule:
Ingresa main como el Patrón de nombre de rama y marca las siguientes opciones:
- Requerir una solicitud de extracción antes de combinar
- Requerir aprobaciones
- Descartar aprobaciones de solicitud de extracción inactivas cuando se envíen confirmaciones nuevas
Por último, presiona el botón Crear que se encuentra en la parte inferior de la página.
Cuando se crea una solicitud de extracción, se ejecutan las acciones de GitHub configuradas anteriormente en estas instrucciones. Después de que se ejecuten por primera vez, también se podrán seleccionar en esta IU de modo que se ejecuten correctamente antes de que la solicitud de extracción se pueda combinar con main.
Configura solicitudes de extracción
En Looker, puedes exigir que se usen solicitudes de extracción y hacer que Looker abra PR en nombre del desarrollador. Esto solo debe configurarse para la instancia de desarrollo. La instancia de producción y QA usará el modo de implementación avanzada para obtener sus actualizaciones.
Para habilitar esta función, ve a Configuración del proyecto para cada proyecto y, luego, selecciona Solicitudes de extracción necesarias en el encabezado Integración en GitHub:
Presiona el botón para establecer un secreto de webhook, copia la cadena aleatoria que se genera y presiona el botón Save Project Configuration.
De regreso en la IU de GitHub de tu repositorio, elige Settings y, luego, Webhooks. Presiona el botón Add webhook (Agregar webhook) en la parte superior derecha:
- En el campo URL de carga útil, ingresa
https://LOOKER_HOST_NAME/webhooks/projects/PROJECT_NAME/deploy. - En el campo Secreto, pega el secreto que guardaste de Looker.
- Para la pregunta ¿Qué eventos desea que activen este webhook?, elija Permitirme seleccionar eventos individuales.
Asegúrate de que las Solicitudes de extracción y Envíos estén seleccionadas:
Por último, presiona el botón Add webhook (Agregar webhook) en la parte inferior de la página.
Pasos de configuración para cada desarrollador de Looker
Todos los pasos de instalación siguientes deben realizarse en tu entorno de Linux.
Cómo instalar Ruby
El lenguaje de programación Ruby debe estar instalado para ejecutar Gazer. Cualquier versión de Ruby posterior a la 2.7.7 funcionará con Gazer, pero se prefiere Ruby 3.x.x. Para instalar Ruby en Ubuntu Linux, ejecuta estos comandos:
sudo apt update
sudo apt install ruby
Ejecuta ruby -v para confirmar que Ruby esté instalado correctamente. Esto debería mostrar una respuesta similar a la siguiente:
ruby 3.1.3p185 (2022-11-24 revision 1a6b16756e) [x86_64-linux]
Estos comandos también funcionarán en Debian Linux, Linux Mint y muchas otras variantes de Linux que usan el administrador de paquetes Aptitude. Es posible que debas buscar comandos que funcionen en otras variantes de Linux, o bien comandos para instalar en macOS. Consulta Instala Ruby para obtener más información.
Cómo instalar Gazer
Gazer es un proyecto de código abierto creado por empleados de Google para navegar y administrar espacios, vistas y paneles con una herramienta de línea de comandos.
Con Ruby instalado, la herramienta Gem de Ruby se puede usar para instalar Gazer:
gem install gazer
Confirma que Gazer esté instalado con el comando gzr version. Esto debería mostrar una respuesta similar a la siguiente:
v0.3.12
Instalación de anteojos
Spectacles es una herramienta ajena a Google que se usa para probar LookML. Spectacles ofrece una versión pagada y una versión de código abierto. Puedes encontrar los detalles para instalarla en la página de introducción.
Cómo instalar Git
Puedes instalar el software de control de versión Git en Ubuntu Linux con este comando:
sudo apt update
sudo apt install git
Confirma que la instalación se realizó de forma correcta con el comando git --version. Esto debería mostrar una respuesta similar a la siguiente:
git version 2.42.0.609.gbb76f46606
Estos comandos también funcionarán en Debian Linux, Linux Mint y muchas otras variantes de Linux que usan el administrador de paquetes Aptitude. Es posible que debas buscar comandos que funcionen con otras variantes de Linux. Puedes encontrar las instrucciones para Fedora y macOS, por ejemplo, en Getting Started - Installing Git.
Configura Git
Git en tu entorno de Linux debe estar configurado para interactuar con cualquier repositorio de Git en el que esté almacenado LookML. Estas instrucciones se escribieron para los repositorios de Git de LookML almacenados en GitHub.
Nombre y correo electrónico
GitHub (y la mayoría de las otras implementaciones de Git) necesitan conocer tu nombre y dirección de correo electrónico para poder registrar la actividad. Ejecuta los siguientes comandos para configurar tu nombre y correo electrónico en Git:
git config --global user.name "FIRST_NAME LAST_NAME"
git config --global user.email "EMAIL_ADDRESS"
Credenciales de Git
En la configuración inicial de CI/CD, se crearon las credenciales de Git. La clave SSH privada que se generó debe configurarse en un archivo $HOME/.ssh/config. Para crear el archivo, usa estos comandos:
touch $HOME/.ssh/config
chmod 600 $HOME/.ssh/config
Inserta el siguiente texto en el archivo $HOME/.ssh/config:
Host github.com
User git
IdentityFile ~/.ssh/KEY_NAME
ControlMaster auto
ControlPath ~/.ssh/ctrl-%r@%h:%p
ControlPersist yes
En lugar de KEY_NAME, usa el nombre del archivo de claves privadas que generaste con las instrucciones de Agrega una nueva clave SSH a tu cuenta de GitHub. El archivo de clave privada tiene el mismo nombre que el archivo de clave pública, pero sin la extensión .pub. Por ejemplo, si usaste la clave pública que se encuentra en el archivo id_ed25519.pub, la clave privada se llamaría id_ed25519.
Configurar tu repositorio de Git local
Después de configurar tu repositorio de LookML, debes hacer una copia de él en tu entorno de Linux. Para ello, ejecuta el siguiente comando:
git clone GIT_URL
Por ejemplo, el comando podría aparecer de la siguiente manera:
git clone git@github.com:my_org_name/sales_project.git
Esto copiará el repositorio de LookML en un subdirectorio, por ejemplo, sales_project. Usa el comando cd SUB_DIRECTORY para ir al repositorio. En este ejemplo, el comando sería cd sales_project.
Cuando estés en el directorio de tu repositorio, podrás usar los siguientes comandos:
| Comando | Objetivo |
|---|---|
git checkout BRANCH_NAME |
Se usa para cambiar de rama. En la mayoría de los casos, la rama principal se llama main. Sin embargo, en sistemas más antiguos, podría llamarse master. |
git fetch |
Se usa para recuperar los últimos cambios del servidor. |
git pull |
Se usa para aplicar cambios a los archivos locales que se retiraron. git pull hace una git fetch de forma implícita. |
git tag |
Se usa con el objetivo de crear una etiqueta significativa para una revisión en particular. |
git push |
Se usa para enviar cambios locales al servidor. |
Cómo configurar Gazer
Para usar Gazer, necesitarás credenciales de API para cada una de las instancias de desarrollo, QA y producción. Si deseas obtener instrucciones para crear credenciales de API, consulta la página Configuración del administrador: Usuarios. Es posible que la persona que configuró inicialmente el flujo de trabajo de CI/CD ya haya creado las credenciales de la API. En ese caso, puedes usar la credencial existente. no será necesario generar credenciales nuevas para cada persona.
Almacena tus credenciales de API en un archivo .netrc con permisos mínimos en tu directorio principal. Puedes usar estos comandos para crear un archivo vacío con los permisos correctos:
touch $HOME/.netrc
chmod 600 $HOME/.netrc
Agrega entradas como las siguientes al archivo, pero usa tus propios nombres de host de servidor de Looker para machine, la API client_id para el acceso y la API client_secret para la contraseña. Por ejemplo:
machine dev.example.looker.com
login 80ka7nl6lj87ftmn
password u7kw3mj5h2trfz0
machine qa.example.looker.com
login fi3qtv5at5crvd1q
password bdxtaeghnzyz0wm
machine example.looker.com
login k7lr6yv57wvzy9p2
password wcvr5qjd2isbs2s
Prueba que esto funcione ejecutando un comando Gazer simple en cada servidor, como el siguiente:
gzr user me --host dev.example.looker.com
Esto debería mostrar un resultado similar al siguiente:
+----+---------------+---------+----------+------------------+--------------+
| id|email |last_name|first_name|personal_folder_id|home_folder_id|
+----+---------------+---------+----------+------------------+--------------+
|2345|jsm@example.com|Smith |John | 2161| 708|
+----+---------------+---------+----------+------------------+--------------+
Si el comando anterior no funciona, es posible que debas agregar --port 443 al final del comando gzr, de la siguiente manera:
gzr user me --host dev.example.looker.com --port 443
Configuración de anteojos
Spectacles usa la misma API de client_id y client_secret que Gazer. En tu directorio de Spectacles, crea un archivo para cada nivel llamado config-TIER.yaml, por ejemplo, config-dev.yaml. Agrega el siguiente contenido a los archivos según corresponda para la instancia de Looker de ese nivel, como los siguientes:
config-dev.yaml
base_url: https://dev.example.looker.com/
client_id: 80ka7nl6lj87ftmn
client_secret: u7kw3mj5h2trfz0
config-qa.yaml
base_url: https://qa.example.looker.com/
client_id: fi3qtv5at5crvd1q
client_secret: bdxtaeghnzyz0wm
config-prod.yaml
base_url: https://example.looker.com/
client_id: k7lr6yv57wvzy9p2
client_secret: wcvr5qjd2isbs2s
Para probar cada archivo, ejecuta el siguiente comando y sustituye cada nombre de archivo:
$ spectacles connect --config-file config-dev.yaml
Deberías esperar una respuesta similar a la siguiente:
Connected to Looker version 23.18.60 using Looker API 4.0