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 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
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 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 distintas. Las instancias pueden estar alojadas por Google o por 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 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 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 utiliza una base de datos única para las tres instancias, estas 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 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
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 de GitHub) y marca la casilla para inicializarlo con un archivo README.
- Presiona el botón Crear repositorio.
- Presiona el botón verde con la etiqueta <> 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, 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.
- 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 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.
Cómo usar un 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, 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 regresa 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 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í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 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í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 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 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 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, selecciona 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
- Exigir 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 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.
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 QA y producción usará el modo de implementación avanzada para obtener sus actualizaciones.
Para habilitar esta función, ve a la página Configuración del proyecto de cada proyecto y, luego, selecciona Solicitud de extracción obligatoria 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 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 etiquetado como Secreto, pega el secreto que guardaste de Looker.
- Para la pregunta ¿Qué eventos le gustaría 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 siguientes pasos de instalación 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 otros tipos 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, 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
Instalación de anteojos
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. 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ó 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 otros tipos 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 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 SSH privada 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 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.
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 ir 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, 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 retiraron. git pull realiza implícitamente un git fetch. |
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 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 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
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
Configuración de anteojos
Spectacles usa las mismas APIs 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 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 esperar una respuesta similar a la siguiente:
Connected to Looker version 23.18.60 using Looker API 4.0