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, QA 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 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.
Sigue las instrucciones de la sección que te corresponda:
- 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 planees 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 versiones diferentes 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.
En estas instrucciones, se proporcionan ejemplos para sistemas Linux y es posible que debas modificarlas 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. Las instancias pueden estar alojadas en Google o en el cliente.
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 trabajo 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, se podría 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 temporal | prod_sales_scratch |
qa_sales_scratch |
dev_sales_scratch |
O bien, si se usa una base de datos única para las tres instancias, se podrían 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 temporal | 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 QA y producción generalmente apuntarán a etiquetas de Git (que se describirán con más detalle más adelante).
Pasos de configuración solo para la primera vez
Los pasos de esta sección solo deben completarse una vez por una persona con permisos de administrador de Looker y permisos de administrador en su proveedor de Git.
Credenciales de Git
El entorno de Linux de cada desarrollador debe conectarse al mismo repositorio que usas para administrar tu LookML. Es probable que se trate de 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 llave SSH para permitir que tu entorno de Linux se conecte a ese servicio automáticamente.
En el caso de GitHub, sigue las instrucciones en Cómo agregar una llave SSH nueva a tu cuenta de GitHub.
Cómo crear y configurar un repositorio de servidor de Git
Para que el flujo de trabajo de CI/CD funcione, 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 un repositorio nuevo
- En la IU de GitHub, presiona el botón + en 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 a 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. Se verá similar a
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 para este repositorio.
- Elige Configuración y, luego, Acciones - General.
- En Permisos de flujo de trabajo, verifica que esté marcada la opción Permitir que GitHub Actions cree y apruebe solicitudes de extracción y haz clic en Guardar.
- Cambia a la página Deploy keys de la configuración de GitHub.
- Haz clic en el botón Add deploy key y pega la clave de implementación en el campo Key.
- 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 Enable Advanced Deploy Mode y selecciona Save Project Configuration.
Debajo del ícono de configuración del proyecto, en el lado izquierdo, deberías ver un ícono de implementación para Deployment Manager.
Usar un repo existente
- Navega al repositorio de GitHub que almacena tu LookML.
- Elige Configuración y, luego, Acciones - General.
- En Permisos de flujo de trabajo, verifica que esté marcada la opción Permitir que GitHub Actions cree y apruebe solicitudes de extracción y haz clic en Guardar.
- Ve a la sección <> Code del repositorio de GitHub.
- Presiona el botón verde etiquetado como <> Code y copia la URL de SSH. Se verá 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, haz clic en 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 para este repositorio.
- Elige Configuración y, luego, Claves de implementación.
- Haz clic en el botón Add deploy key y pega la clave de implementación en el campo Key.
- 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 Enable Advanced Deploy Mode y selecciona Save Project Configuration.
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. Una vez configuradas, estas acciones se pueden ejecutar manualmente desde la página Actions de la IU de GitHub.
Look-At-Me-Sideways (LAMS)
LAMS es un verificador 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 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@v4
with:
ref: ${{ github.event.pull_request.head.sha }}
fetch-depth: 0
- 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
LAMS se ejecutará 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.
Release Please
Release Please es una herramienta de código abierto que etiqueta automáticamente las versiones 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
Confirmaciones convencionales
Esta acción de GitHub verificará 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 }}
permissions:
pull-requests:
read statuses: write
Envía los cambios a GitHub
Por último, usa los siguientes comandos para confirmar estos cambios en 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 la protección de ramas para la rama main, de modo que los desarrolladores comunes no puedan enviar cambios directamente a esa rama. En cambio, realizan cambios en otra rama 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 del nombre de la rama y marca las siguientes opciones:
- Exige una solicitud de extracción antes de combinar
- Solicitar aprobaciones
- Descarta las aprobaciones de solicitud de extracción obsoletas cuando se envían confirmaciones nuevas
Por último, presiona el botón Crear 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 ejecutarse por primera vez, también se pueden seleccionar en esta IU para que deban completarse correctamente antes de que se pueda combinar la solicitud de extracción en 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. Solo se debe configurar para la instancia de desarrollo. Las instancias de QA y producción usarán el Modo de implementación avanzado para obtener sus actualizaciones.
Para habilitar esta opción, ve a la página Configuración del proyecto de cada proyecto y, luego, selecciona Se requieren solicitudes de extracción 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.
De vuelta en la IU de GitHub para tu repositorio, elige Settings y, luego, Webhooks. Presiona el botón Agregar webhook en la esquina superior derecha:
- En el campo etiquetado como URL de 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.
- Para la pregunta ¿Qué eventos deseas que activen este webhook?, elige Permítanme seleccionar eventos individuales.
Verifica que estén seleccionadas las opciones Pull Requests y Pushes:
Por último, presiona el botón Agregar 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 se deben realizar 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. Deberías recibir 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 otras versiones 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.
Instala Gazer
Gazer es un proyecto de código abierto creado por empleados de Google para navegar y administrar espacios, Looks 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. Deberías recibir una respuesta similar a la siguiente:
v0.3.12
Cómo instalar los Spectacles
Spectacles es una herramienta de código abierto que se usa para probar LookML (su versión pagada ya no está disponible). Puedes encontrar detalles para instalarlo en su página de introducción.
Instala Git
El software de control de versión de Git se puede instalar en Ubuntu Linux con este comando:
sudo apt update
sudo apt install git
Confirma que la instalación se haya realizado correctamente con el comando git --version. Deberías recibir 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 otras versiones de Linux que usan el administrador de paquetes Aptitude. Es posible que debas buscar comandos que funcionen en otras versiones de Linux. Por ejemplo, puedes encontrar instrucciones para Fedora y macOS en Getting Started - Installing Git.
Configura Git
Git en tu entorno de Linux debe configurarse para interactuar con el repositorio de Git en el que se almacena 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 saber 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 de Cómo 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.
Configura 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 ingresar al repositorio. En este ejemplo, el comando sería cd sales_project.
Una vez que estés en el directorio del 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 los sistemas más antiguos, podría 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 extrajeron. git pull realiza un git fetch de forma implícita. |
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 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 crear un archivo vacío con los permisos correctos con los siguientes 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 funciona, ejecuta un comando de Gazer en cada servidor, como el siguiente:
gzr user me --host dev.example.looker.com
Deberías obtener 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 los Spectacles
Spectacles usa las mismas APIs client_id y client_secret que Gazer. En el 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 a la instancia de Looker de ese nivel, como se muestra a continuación:
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 reemplaza 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