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 comprende desarrollo, control de calidad y producción. Sin embargo, los mismos principios se pueden aplicar 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.
Sigue las instrucciones de la sección que te resulte relevante:
- 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
Este proceso usa 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 planeas ejecutar tu flujo de trabajo de CI/CD.
Si usas Windows, Gazer y Spectacles se pueden usar dentro del Subsistema de Windows para Linux (WSL) de Microsoft. WSL te permite ejecutar una variedad de distribuciones 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 separadas. Google puede alojar las instancias o el cliente puede hacerlo.
Nombres de conexión idénticos
Las conexiones de bases de datos deben tener el mismo nombre en cada instancia de Looker, independientemente del nivel que representen. Por ejemplo, una conexión sales debe 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 bases de datos diferentes. Sin embargo, si apuntan a la misma base de datos, deben tener definidos diferentes esquemas de borrador para que las tablas derivadas persistentes en la instancia de desarrollo o QA no interfieran con la producción.
Por ejemplo, si se usa la misma base de datos para las tres instancias, estas se pueden configurar de la siguiente manera:
| Producción | QA | 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 usa una base de datos única para las tres instancias, se pueden configurar de la siguiente manera:
| Producción | QA | 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 solo repositorio de git para cada proyecto en los tres niveles. La instancia de desarrollo hará un seguimiento de la rama main, mientras que las instancias de control de calidad y producción suelen apuntar a etiquetas de git (que se describen con más detalle más adelante).
Pasos de configuración solo para la primera vez
Una persona con permisos de administrador de Looker y permisos de administrador en su proveedor de git solo debe completar los pasos de esta sección una vez.
Credenciales de Git
El entorno de Linux de cada desarrollador debe conectarse al mismo repositorio que usas para administrar tu LookML. Es probable que sea un repositorio externo alojado en un servicio como GitHub. Necesitarás una cuenta con 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 Cómo agregar una nueva clave SSH a tu cuenta de GitHub.
Cómo crear y configurar un repositorio de servidor de 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, Git Production Branch Name debe establecerse en main y Enable Advanced Deploy Mode debe estar habilitado.
Si aún no se realizaron los siguientes pasos, sigue estas instrucciones para GitHub:
Crear repositorio nuevo
- En la IU de GitHub, presiona el botón + en la esquina superior derecha y, luego, selecciona Nuevo repositorio.
- 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 a GitHub) y marca la casilla para inicializarlo con un archivo README.
- Presiona el botón Crear repositorio.
- Presiona el botón verde que dice <> Code y copia la URL de SSH. Se verá similar a lo siguiente:
git@github.com:org_name/REPOSITORY_NAME.git. - En Looker, crea un proyecto nuevo.
- Ingresa al modo de desarrollo, 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 vuelve a la IU de GitHub de este repositorio.
- Elige 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 Probar y finalizar la configuración.
- Vuelve a elegir la configuración del proyecto en la barra lateral izquierda. Cambia el Nombre de la rama de producción de Git a
main. - Elige Habilitar el modo de implementación avanzado y selecciona Guardar la configuración del proyecto.
Debajo del ícono de configuración del proyecto, en el lado izquierdo, deberías ver un ícono de implementación para Deployment Manager.
Cómo usar un repositorio existente
- Navega al repositorio de GitHub que almacena tu LookML.
- Presiona el botón verde que dice <> Code y copia la URL de SSH. Se verá similar a lo siguiente:
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, Configura 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 vuelve a la IU de GitHub de este repositorio.
- Elige 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 Probar y finalizar la configuración.
- Vuelve a elegir la configuración del proyecto en la barra lateral izquierda. Cambia el Nombre de la rama de producción de Git a
main. - Elige Habilitar el modo de implementación avanzado y selecciona Guardar la configuración del proyecto.
Debajo del ícono de configuración del proyecto, en el lado izquierdo, deberías ver un ícono de implementación para Deployment Manager.
Crea acciones de GitHub
Es ú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 de forma manual desde la página Actions de la IU de GitHub.
Mira-hacia-un-lado (LAMS)
LAMS es un lint de código abierto que inspecciona tu código LookML en busca de errores y prácticas inadecuadas. Agrega un archivo llamado lams.yml al directorio .github/workflows con el siguiente 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íe una confirmación a GitHub o se abra una solicitud de extracción para combinar código con la rama main, se ejecutará LAMS.
Lanzamiento
Release Please es una herramienta de código abierto que etiqueta automáticamente las versiones con los números de versión correctos.
Agrega un archivo llamado release-please.yml al directorio .github/workflows con el siguiente 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 se asegurará de 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 el siguiente 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 la 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 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 Patrón del nombre de la rama y marca las siguientes opciones:
- Cómo exigir una solicitud de extracción antes de la combinación
- Exigir aprobaciones
- Descarta las aprobaciones de solicitudes de extracción inactivas cuando se envían confirmaciones nuevas
Por último, presiona el botón Crear en la parte inferior de la página.
Cuando se cree una solicitud de extracción, se ejecutarán las acciones de GitHub que se configuraron antes en estas instrucciones. Después de que se ejecuten por primera vez, también se pueden seleccionar en esta IU para que se deban realizar correctamente antes de que se pueda combinar la solicitud de extracción con main.
Cómo configurar solicitudes de extracción
En Looker, puedes exigir que se usen las solicitudes de extracción y hacer que Looker abra solicitudes de extracción en nombre del desarrollador. Esto solo se debe configurar para la instancia de desarrollo. La instancia de QA y producción usará el modo de implementación avanzada para obtener sus actualizaciones.
Para habilitar esta opción, ve a la página Configuración del proyecto de cada proyecto y, luego, selecciona Solicitudes de extracción obligatorias en el encabezado Integración de 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.
En la IU de GitHub de tu repositorio, elige Configuración y, luego, Webhooks. Presiona el botón Agregar webhook en la parte superior derecha:
- En el campo etiquetado como URL de la carga útil, ingresa
https://LOOKER_HOST_NAME/webhooks/projects/PROJECT_NAME/deploy. - En el campo etiquetado como Secreto, pega el secreto que guardaste de Looker.
- En la pregunta ¿Qué eventos deseas activar con este webhook?, elige Permitirme seleccionar eventos individuales.
Asegúrate de que las opciones Pull Requests y Pushes estén seleccionadas:
Por último, presiona el botón Add webhook en la parte inferior de la página.
Pasos de configuración para cada desarrollador de Looker
Todos los siguientes pasos de instalación deben realizarse en tu entorno de Linux.
Cómo instalar Ruby
Se debe instalar el lenguaje de programación Ruby 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 varias otras variantes de Linux que usan el administrador de paquetes Aptitude. Es posible que debas buscar comandos que funcionen en otras versiones de Linux o comandos para instalar en macOS. Consulta Cómo instalar 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, temas y paneles con una herramienta de línea de comandos.
Con Ruby instalado, se puede usar la herramienta Gem de Ruby 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
Cómo instalar Spectacles
Spectacles es una herramienta que no es de Google y se usa para probar LookML. Spectacles ofrece una versión pagada y una versión de código abierto. Los detalles para instalarla se encuentran en su página de introducción.
Cómo instalar Git
El software de control de versiones de Git se puede instalar en Ubuntu Linux con este comando:
sudo apt update
sudo apt install git
Confirma que la instalación se realizó correctamente 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 varias otras variantes de Linux que usan el administrador de paquetes Aptitude. Es posible que debas buscar comandos que funcionen en otras versiones de Linux. Por ejemplo, las instrucciones para Fedora y macOS se pueden encontrar en Primeros pasos: Cómo instalar Git.
Cómo configurar Git
Git en tu entorno de Linux debe configurarse para interactuar con cualquier repositorio de Git en el que se almacene tu 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 credenciales de git. La clave privada SSH que se generó debe configurarse en un archivo $HOME/.ssh/config. Para crear el archivo, usa los siguientes 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 clave privada que generaste con las instrucciones para agregar 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.
Cómo configurar tu repositorio de Git local
Después de configurar tu repositorio de LookML, debes crear una copia 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
Esta acción copiará el repositorio de LookML en un subdirectorio, por ejemplo, sales_project. Usa el comando cd SUB_DIRECTORY para ingresar al repositorio. En este ejemplo, el comando sería cd sales_project.
Una vez que estés en el directorio de tu repositorio, puedes 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, puede llamarse master. |
git fetch |
Se usa para recuperar los cambios más recientes del servidor. |
git pull |
Se usa para aplicar cambios a los archivos locales que se retiraron. git pull realiza implícitamente un git fetch. |
git tag |
Se usa para 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. Para obtener instrucciones sobre cómo crear credenciales de API, consulta la página Configuración de 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 de inicio. Puedes crear un archivo vacío con los permisos correctos con estos comandos:
touch $HOME/.netrc
chmod 600 $HOME/.netrc
Agrega entradas como las siguientes al archivo, pero usa tus propios nombres de host del 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
Para probar que esto funcione, ejecuta 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
Cómo configurar Spectacles
Spectacles usa las mismas APIs client_id y client_secret que Gazer. En el directorio 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 a la instancia de Looker de ese nivel, como el siguiente:
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 recibir una respuesta similar a la siguiente:
Connected to Looker version 23.18.60 using Looker API 4.0