Instalación y configuración de CI/CD de Looker

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, 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 para modificar estas instrucciones para tu proveedor.

Sigue las instrucciones de la sección que sea pertinente para ti:

• Requisitos previos
• Pasos de configuración por única 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 modificarlos 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 control de calidad y una etapa de producción necesitará tres instancias separadas. Las instancias pueden estar alojadas por Google o por el cliente.

Nombres de conexión 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 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 esquemas de prueba diferentes para que las tablas derivadas persistentes en la instancia de desarrollo o de control de calidad no interfieran con la producción.

Por ejemplo, si se usa la misma base de datos para las tres instancias, se pueden configurar de la siguiente manera:

O bien, si se usa una base de datos única para las tres instancias, se pueden configurar de la siguiente manera:

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, por lo general, apuntarán a etiquetas de Git (que se describen con más detalle más adelante).

Pasos de configuración por única vez

Los pasos de esta sección solo deben completarlos una vez alguien con permisos de administrador de Looker, así como 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 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 en Cómo agregar una clave SSH nueva a tu cuenta de GitHub.

Crea y configura 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:

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 que estén configuradas, estas acciones se pueden ejecutar de forma manual desde la página Actions 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 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@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

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.

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 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

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 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 }}

permissions:
  pull-requests:
    read statuses: write

Envía los cambios a GitHub

Por último, usa los siguientes comandos para confirmar estos cambios en las acciones de GitHub y enviarlos a GitHub:

git add .github/workflows/
git commit -m "chore: Added github actions"
git push

Protege 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 cambio, 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 rama, ve a la IU de GitHub para el repositorio, elige Settings y, luego, Branches y presiona el botón Add branch protection rule:

Ingresa main como el Branch name pattern y marca las siguientes opciones:

• Require a solicitud de extracción before merging
• Require approvals
• Dismiss stale solicitud de extracción approvals when new commits are pushed

Por último, presiona el botón Create en la parte inferior de la página.

Cuando se cree una solicitud de extracción, se ejecutarán las acciones de GitHub configuradas anteriormente en estas instrucciones. Después de que se ejecuten por primera vez, también se pueden seleccionar en esta IU para que deban tener éxito 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 solicitudes de extracción en nombre del desarrollador. Esto solo se debe configurar para la instancia de desarrollo. La instancia de control de calidad y producción usará el modo de implementación avanzada para obtener sus actualizaciones.

Para habilitar esta opción, ve a la página Project Configuration de cada proyecto y, luego, selecciona Pull Requests Required en el encabezado GitHub Integration.

Presiona el botón para configurar 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 Add webhook en la esquina superior derecha:

• En el campo con la etiqueta Payload URL , ingresa https://LOOKER_HOST_NAME/webhooks/projects/PROJECT_NAME/deploy.
• En el campo con la etiqueta Secret , pega el secreto que guardaste de Looker.
• Para la pregunta Which events would you like to trigger this webhook? , elige Let me select individual events.

Verifica que estén seleccionados Pull Requests y Pushes:

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 se deben realizar en tu entorno de Linux.

Instala Ruby

Es necesario 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 los siguientes 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 Instala 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

Instala 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 realizó 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 Introducción: Instala 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 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. Para configurar tu nombre y correo electrónico en Git, ejecuta los siguientes comandos:

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 clave SSH nueva 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á id_ed25519.

Configura tu repositorio de Git local

Después de configurar tu repositorio de LookML, debes hacer 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

Esto copiará el repositorio de LookML a 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 en el directorio de tu repositorio, puedes usar los siguientes comandos:

Configura Gazer

Para usar Gazer, necesitarás credenciales de API para cada una de las instancias de desarrollo, control de calidad y producción. Si deseas obtener instrucciones para 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 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 usando 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, el client_id de la API para el acceso y el client_secret de la API 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 de Gazer en cada servidor, como el siguiente:

gzr user me --host dev.example.looker.com

Deberías obtener un resultado similar a este:

+----+---------------+---------+----------+------------------+--------------+
|  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

Configura Spectacles

Spectacles usa el mismo client_id y client_secret de la API 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 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