Instalação e configuração do CI/CD do Looker

Esta página explica como instalar e configurar os componentes necessários para implementar um fluxo de trabalho de CI/CD no Looker.

Estas instruções usam um sistema de três camadas que inclui desenvolvimento, controle de qualidade e produção. No entanto, os mesmos princípios podem ser aplicados a um sistema de dois ou quatro níveis.

Estas instruções também pressupõem o uso do GitHub como seu provedor do Git. É possível usar outros provedores do Git para criar um fluxo de trabalho de CI/CD. No entanto, você precisa ter experiência para modificar essas instruções para o provedor.

Siga as instruções na seção relevante para você:

Pré-requisitos

Ambiente Linux

Esse processo usa ferramentas chamadas Gazer e Spectacles, que foram projetadas para funcionar com sistemas operacionais semelhantes ao Unix. Cada desenvolvedor do LookML precisa ter acesso à linha de comando em um ambiente Linux ou macOS em que você planeja executar o fluxo de trabalho de CI/CD.

Se você estiver usando o Windows, o Gazer e o Spectacles podem ser usados no Subsistema Windows para Linux (WSL) da Microsoft. O WSL permite executar vários tipos diferentes de Linux. Se você não tiver um sistema operacional Linux preferido, a versão mais recente do Ubuntu Linux é uma boa escolha devido ao amplo suporte.

Estas instruções fornecem exemplos para sistemas Linux e podem precisar de modificações se você estiver usando o macOS ou o WSL.

Uma instância do Looker por camada

Para ativar essa configuração, você vai precisar de uma instância do Looker para cada camada do sistema. Por exemplo, um sistema com um estágio de desenvolvimento, um de controle de qualidade e um de produção vai precisar de três instâncias separadas. As instâncias podem ser hospedadas pelo Google ou pelo cliente.

Nomes de conexão idênticos

As conexões de banco de dados precisam ter o mesmo nome em cada instância do Looker, independentemente do nível que representam. Por exemplo, uma conexão sales precisa ter esse nome em todas as instâncias, em vez de sales_dev ou sales_qa.

As conexões podem apontar para o mesmo banco de dados ou para bancos de dados diferentes. No entanto, se elas apontarem para o mesmo banco de dados, terão esquemas iniciais diferentes definidos para que as tabelas derivadas persistentes na instância de desenvolvimento ou de controle de qualidade não interfiram na produção.

Por exemplo, se o mesmo banco de dados for usado nas três instâncias, elas poderão ser configuradas da seguinte maneira:

Production QA Development
Nome da conexão sales sales sales
banco de dados sales_db sales_db sales_db
Esquema do Scratch prod_sales_scratch qa_sales_scratch dev_sales_scratch

Ou, se um banco de dados único for usado para as três instâncias, elas poderão ser configuradas da seguinte maneira:

Production QA Development
Nome da conexão sales sales sales
banco de dados sales_db_prod sales_db_qa sales_db_dev
Esquema do Scratch sales_scratch sales_scratch sales_scratch

Repositório do Git

Um único repositório do Git será usado para cada projeto nas três camadas. A instância de desenvolvimento vai rastrear a ramificação main, enquanto as instâncias de controle de qualidade e de produção geralmente apontam para tags do Git (descritas em mais detalhes mais adiante).

Etapas de configuração apenas para a primeira vez

As etapas desta seção só precisam ser concluídas uma vez por alguém com permissões de administrador do Looker e do provedor de git.

Credenciais do Git

O ambiente Linux de cada desenvolvedor precisa se conectar ao mesmo repositório que você está usando para gerenciar o LookML. Esse é provavelmente um repositório externo hospedado em um serviço como o GitHub. Você vai precisar de uma conta com as credenciais adequadas para configurar o repositório. Com a conta, você pode configurar uma chave SSH para permitir que o ambiente Linux se conecte ao serviço automaticamente.

No GitHub, siga as instruções em Adicionar uma nova chave SSH à sua conta do GitHub.

Criar e configurar um repositório do servidor Git

Para que o fluxo de trabalho de CI/CD funcione, o LookML precisa ser armazenado em um repositório do Git e conectado a um projeto do Looker. Nas configurações do projeto, o Git Production Branch Name precisa ser definido como main e a opção Enable Advanced Deploy Mode precisa estar ativada.

Se as etapas a seguir ainda não foram realizadas, siga estas instruções para o GitHub:

Criar novo repositório

  1. Na interface do GitHub, pressione o botão + no canto superior direito e selecione Novo repositório.
  2. Selecione o proprietário (provavelmente sua organização) e insira um REPOSITORY_NAME.
  3. Escolha se o repositório será público ou privado (os repositórios privados exigem uma assinatura paga do GitHub) e marque a caixa para inicializar com um arquivo README.
  4. Pressione o botão Criar repositório.
  5. Pressione o botão verde <> Code e copie o URL do SSH. Ele será semelhante a: git@github.com:org_name/REPOSITORY_NAME.git.
  6. No Looker, crie um novo projeto.
  7. Entre no modo de desenvolvimento, escolha o item de configurações do projeto na barra lateral esquerda e clique em Configurar Git.
  8. Cole o URL do repositório (git@github.com:org_name/REPOSITORY_NAME.git neste exemplo) e selecione Continuar.
  9. Copie a chave de implantação e volte para a interface do GitHub desse repositório.
  10. Escolha Configurações e Implantar chaves.
  11. Clique no botão Adicionar chave de implantação e cole a chave de implantação no campo Chave.
  12. Adicione um título, como Looker-REPOSITORY_NAME, marque a caixa de seleção Permitir acesso de gravação e pressione o botão Adicionar chave.
  13. Volte para o Looker e escolha Testar e finalizar a configuração.
  14. Escolha as configurações do projeto novamente na barra lateral esquerda. Mude o Nome do branch de produção do Git para main.
  15. Escolha Ativar o modo de implantação avançado e selecione Salvar configuração do projeto.

Abaixo do ícone de configurações do projeto, no lado esquerdo, você vai encontrar um ícone de implantação para o Deployment Manager.

Usar o repositório atual

  1. Acesse o repositório do GitHub que armazena o LookML.
  2. Pressione o botão verde <> Code e copie o URL do SSH. Ele será semelhante a: git@github.com:org_name/REPOSITORY_NAME.git.
  3. No Looker, crie um novo projeto.
  4. Entre no modo de desenvolvimento, escolha o item de configurações do projeto na barra à esquerda e clique em Configurar Git.
  5. Cole o URL do repositório (git@github.com:org_name/REPOSITORY_NAME.git neste exemplo) e selecione Continuar.
  6. Copie a chave de implantação e volte para a interface do GitHub desse repositório.
  7. Escolha Configurações e Implantar chaves.
  8. Clique no botão Adicionar chave de implantação e cole a chave de implantação no campo Chave.
  9. Adicione um título, como Looker-REPOSITORY_NAME, marque a caixa de seleção Permitir acesso de gravação e pressione o botão Adicionar chave.
  10. Volte para o Looker e escolha Testar e finalizar a configuração.
  11. Escolha as configurações do projeto novamente na barra lateral esquerda. Mude o Nome do branch de produção do Git para main.
  12. Escolha Ativar o modo de implantação avançado e selecione Salvar configuração do projeto.

Abaixo do ícone de configurações do projeto, no lado esquerdo, você vai encontrar um ícone de implantação para o Deployment Manager.

Como criar ações do GitHub

É útil criar várias ações do GitHub para que várias verificações ocorram automaticamente sempre que houver mudanças no LookML. Para adicionar essas ações, é necessário fazer alterações no repositório Git no ambiente Linux. Se ainda não estiver disponível, siga as instruções de Configuração do Git.

Para adicionar as ações do GitHub, acesse o diretório do repositório no ambiente Linux e adicione o subdiretório .github/workflows. Depois de configuradas, essas ações podem ser executadas manualmente na página Ações da interface do GitHub.

Look-At-Me-Sideways (LAMS)

O LAMS (link em inglês) é um lint de código aberto que inspeciona o LookML para detectar erros e práticas inadequadas. Adicione um arquivo chamado lams.yml ao diretório .github/workflows com este conteúdo:

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

Sempre que uma confirmação for enviada ao GitHub ou uma solicitação de envio for aberta para mesclar o código com a ramificação main, o LAMS será executado.

Release Please

O Release Please é uma ferramenta de código aberto que marca automaticamente as versões com os números de versão corretos.

Adicione um arquivo chamado release-please.yml ao diretório .github/workflows com este conteúdo:

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

Confirmações convencionais

Essa ação do GitHub garante que uma solicitação de envio seja aberta com um título que adere ao padrão de confirmação convencional.

Adicione um arquivo chamado lint_pr_title.yml ao diretório .github/workflows com este conteúdo:

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

Envie as alterações para o GitHub

Por fim, use os seguintes comandos para confirmar essas alterações e fazer o push delas para o GitHub:

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

Proteger a ramificação main

Na interface do GitHub, ative as proteções de ramificação para a ramificação main para que desenvolvedores comuns não possam enviar mudanças diretamente para essa ramificação. Em vez disso, eles fazem mudanças em uma ramificação diferente e depois abrem uma solicitação de envio. A solicitação de envio pode ser analisada por outro desenvolvedor antes de ser aprovada e mesclada com main.

Para configurar a proteção de branch, acesse a interface do GitHub do repositório, escolha Settings e Branches e pressione o botão Add branch protection rule:

Interface do GitHub para adicionar proteção de ramificação.

Insira main como o padrão do nome da ramificação e marque as seguintes opções:

  • Exigir uma solicitação de envio antes da mesclagem
  • Exigir aprovações
  • Descartar aprovações de solicitações de envio desaturadas quando novos commits forem enviados

Interface do GitHub para definir opções de proteção de branch.

Por fim, pressione o botão Criar na parte de baixo da página.

Quando uma solicitação de envio é criada, as ações do GitHub configuradas anteriormente nestas instruções são executadas. Depois de serem executados pela primeira vez, eles também podem ser selecionados nessa interface para que o pull request seja mesclado a main.

Como configurar solicitações de envio

No Looker, você pode exigir que as solicitações de pull sejam usadas e que o Looker abra PRs em nome do desenvolvedor. Isso só deve ser configurado para a instância de desenvolvimento. A instância de QA e de produção vai usar o modo de implantação avançado para receber as atualizações.

Para ativar essa opção, acesse a página Configuração do projeto de cada projeto e selecione Solicitações de envio obrigatório no título Integração do GitHub.

Pressione o botão para definir um secret de webhook, copie a string aleatória gerada e clique no botão Salvar configuração do projeto.

Na interface do GitHub do seu repositório, escolha Settings e Webhooks. Pressione o botão Adicionar webhook no canto superior direito:

  • No campo URL do payload, insira https://LOOKER_HOST_NAME/webhooks/projects/PROJECT_NAME/deploy.
  • No campo Secret, cole o secret salvo no Looker.
  • Para a pergunta Quais eventos você quer acionar com este webhook?, escolha Deixe-me selecionar eventos individuais

Interface do GitHub para configurar webhooks.

Verifique se as opções Solicitações de pull e Pushes estão selecionadas:

Caixas de seleção do GitHub para solicitações de envio e envios.

Por fim, clique no botão Adicionar webhook na parte de baixo da página.

Etapas de configuração para cada desenvolvedor do Looker

Todas as etapas de instalação a seguir precisam ser realizadas no ambiente Linux.

Instalar o Ruby

A linguagem de programação Ruby precisa estar instalada para executar o Gazer. Qualquer versão do Ruby após a 2.7.7 vai funcionar com o Gazer, mas o Ruby 3.x.x é o preferido. Para instalar o Ruby no Ubuntu Linux, execute estes comandos:

sudo apt update
sudo apt install ruby

Confirme se o Ruby está instalado corretamente executando ruby -v. Isso vai gerar uma resposta semelhante a esta:

ruby 3.1.3p185 (2022-11-24 revision 1a6b16756e) [x86_64-linux]

Esses comandos também funcionam no Debian Linux, Linux Mint e várias outras variações do Linux que usam o gerenciador de pacotes Aptitude. Talvez seja necessário pesquisar comandos que funcionem em outras versões do Linux ou para instalar no macOS. Consulte Como instalar o Ruby para mais informações.

Como instalar o Gazer

O Gazer é um projeto de código aberto criado por funcionários do Google para navegar e gerenciar espaços, looks e painéis usando uma ferramenta de linha de comando.

Com o Ruby instalado, a ferramenta Gem do Ruby pode ser usada para instalar o Gazer:

gem install gazer

Confirme se o Gazer está instalado com o comando gzr version. Isso vai gerar uma resposta semelhante a esta:

v0.3.12

Como instalar os Spectacles

O Spectacles é uma ferramenta de terceiros usada para testar o LookML. Os Spectacles oferecem uma versão paga e uma versão de código aberto. Os detalhes da instalação podem ser encontrados na página de início.

Como instalar o Git

O software de controle de versão do Git pode ser instalado no Ubuntu Linux com este comando:

sudo apt update
sudo apt install git

Confirme se a instalação foi concluída com o comando git --version. Isso vai gerar uma resposta semelhante a esta:

git version 2.42.0.609.gbb76f46606

Esses comandos também funcionam no Debian Linux, Linux Mint e várias outras variações do Linux que usam o gerenciador de pacotes Aptitude. Talvez seja necessário pesquisar comandos que funcionem em outras versões do Linux. As instruções para Fedora e macOS, por exemplo, podem ser encontradas em Primeiros passos: instalação do Git.

Como configurar o Git

O Git no seu ambiente Linux precisa ser configurado para interagir com o repositório Git em que o LookML está armazenado. Estas instruções foram escritas para repositórios do LookML Git armazenados no GitHub.

Nome e e-mail

O GitHub (e a maioria das outras implementações do Git) precisa saber seu nome e endereço de e-mail para registrar a atividade. Configure seu nome e e-mail no Git executando os seguintes comandos:

git config --global user.name "FIRST_NAME LAST_NAME"
git config --global user.email "EMAIL_ADDRESS"

Credenciais do Git

Na configuração inicial de CI/CD, as credenciais do Git foram criadas. A chave privada SSH gerada precisa ser configurada em um arquivo $HOME/.ssh/config. Para criar o arquivo, use estes comandos:

touch $HOME/.ssh/config
chmod 600 $HOME/.ssh/config

Insira o seguinte texto no arquivo $HOME/.ssh/config:

Host github.com
  User git
  IdentityFile ~/.ssh/KEY_NAME
  ControlMaster auto
  ControlPath ~/.ssh/ctrl-%r@%h:%p
  ControlPersist yes

Em vez de KEY_NAME, use o nome do arquivo de chave privada que você gerou com as instruções de Adicionar uma nova chave SSH à sua conta do GitHub. O arquivo de chave privada tem o mesmo nome do arquivo de chave pública, mas sem a extensão .pub. Por exemplo, se você usou a chave pública encontrada no arquivo id_ed25519.pub, a chave privada seria chamada id_ed25519.

Como configurar seu repositório Git local

Depois de configurar o repositório do LookML, você precisa fazer uma cópia dele no ambiente do Linux. Para fazer isso, execute este comando:

git clone GIT_URL

Por exemplo, o comando pode aparecer da seguinte maneira:

git clone git@github.com:my_org_name/sales_project.git

Isso vai copiar o repositório do LookML para um subdiretório, por exemplo, sales_project. Use o comando cd SUB_DIRECTORY para acessar o repositório. Neste exemplo, o comando seria cd sales_project.

No diretório do repositório, você pode usar os seguintes comandos:

Comando Finalidade
git checkout BRANCH_NAME Usado para alternar entre as ramificações. Na maioria dos casos, a ramificação principal é chamada de main. No entanto, em sistemas mais antigos, ela pode ser chamada de master.
git fetch Usado para extrair as mudanças mais recentes do servidor.
git pull Usado para aplicar mudanças aos arquivos locais retirados. git pull faz uma git fetch implicitamente.
git tag Usado para criar uma tag significativa para uma revisão específica.
git push Usado para enviar mudanças locais ao servidor.

Como configurar o Gazer

Para usar o Gazer, você vai precisar de credenciais de API para cada uma das instâncias de desenvolvimento, controle de qualidade e produção. Para instruções sobre como criar credenciais de API, consulte a página Configurações do administrador: usuários. As credenciais da API podem ter sido criadas pela pessoa que configurou o fluxo de trabalho de CI/CD inicialmente. Nesse caso, você pode usar a credencial atual. Não é necessário gerar novas credenciais para cada pessoa.

Armazene as credenciais da API em um arquivo .netrc com permissões mínimas no diretório inicial. É possível criar um arquivo vazio com as permissões corretas usando estes comandos:

touch $HOME/.netrc
chmod 600 $HOME/.netrc

Adicione ao arquivo entradas como a seguinte, mas use seus próprios nomes de host do servidor do Looker para machine, a API client_id para o login e a API client_secret para a senha. Exemplo:

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 testar se isso funciona, execute um comando Gazer simples em cada servidor, como este:

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

O resultado será semelhante a este:

+----+---------------+---------+----------+------------------+--------------+
|  id|email          |last_name|first_name|personal_folder_id|home_folder_id|
+----+---------------+---------+----------+------------------+--------------+
|2345|jsm@example.com|Smith    |John      |              2161|           708|
+----+---------------+---------+----------+------------------+--------------+

Se o comando anterior não funcionar, talvez seja necessário adicionar --port 443 ao final do comando gzr, conforme mostrado abaixo:

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

Como configurar os Spectacles

O Spectacles usa a mesma API client_id e client_secret do Gazer. No diretório Spectacles, crie um arquivo para cada nível com o nome config-TIER.yaml, por exemplo, config-dev.yaml. Adicione o seguinte conteúdo aos arquivos conforme apropriado para a instância do Looker do nível, como:

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 testar cada arquivo, execute o comando abaixo e substitua cada nome de arquivo:

$ spectacles connect --config-file config-dev.yaml

Você vai receber uma resposta semelhante a esta:

Connected to Looker version 23.18.60 using Looker API 4.0