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 níveis que inclui desenvolvimento, controlo 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 a utilização do GitHub como fornecedor de Git. Pode usar outros fornecedores do Git para criar um fluxo de trabalho de CI/CD. No entanto, tem de ter conhecimentos para modificar estas instruções para o seu fornecedor.
Siga as instruções na secção relevante para si:
Pré-requisitos
Ambiente Linux
Este processo usa ferramentas denominadas Gazer e Spectacles, concebidas para funcionar com sistemas operativos semelhantes ao Unix. Cada programador de LookML tem de ter acesso à linha de comandos num ambiente Linux ou macOS onde planeia executar o fluxo de trabalho de CI/CD.
Se estiver a usar o Windows, o Gazer e os Spectacles podem ser usados no subsistema Windows para Linux (WSL) da Microsoft. O WSL permite-lhe executar uma variedade de diferentes versões do Linux. Se não tiver um sistema operativo Linux preferencial, a versão mais recente do Ubuntu Linux é uma boa escolha devido ao seu amplo suporte.
Estas instruções fornecem exemplos para sistemas Linux e podem exigir modificação se estiver a usar o macOS ou o WSL.
Uma instância do Looker por nível
Para ativar esta configuração, precisa de uma instância do Looker para cada nível do seu sistema. Por exemplo, um sistema com uma fase de desenvolvimento, uma fase de controlo de qualidade e uma fase de produção precisa de três instâncias separadas. As instâncias podem ser alojadas pela Google ou pelo cliente.
Nomes de associações idênticos
As ligações à base de dados devem ter o mesmo nome em cada instância do Looker, independentemente do nível que representam. Por exemplo, uma ligação sales deve ter esse nome em todas as instâncias, em vez de sales_dev ou sales_qa.
As associações podem apontar para a mesma base de dados ou para bases de dados diferentes. No entanto, se apontarem para a mesma base de dados, devem ter esquemas temporários diferentes definidos para que as tabelas derivadas persistentes na instância de desenvolvimento ou de controlo de qualidade não interfiram com a produção.
Por exemplo, se a mesma base de dados for usada para todas as três instâncias, podem ser configuradas da seguinte forma:
| Produção | QA | Desenvolvimento | |
| Nome da associação | sales |
sales |
sales |
| Base de dados | sales_db |
sales_db |
sales_db |
| Scratch Schema | prod_sales_scratch |
qa_sales_scratch |
dev_sales_scratch |
Em alternativa, se for usada uma base de dados única para todas as três instâncias, estas podem ser configuradas da seguinte forma:
| Produção | QA | Desenvolvimento | |
| Nome da associação | sales |
sales |
sales |
| Base de dados | sales_db_prod |
sales_db_qa |
sales_db_dev |
| Scratch Schema | sales_scratch |
sales_scratch |
sales_scratch |
Repositório Git
É usado um único repositório git para cada projeto em todos os três níveis. A instância de desenvolvimento acompanha o ramo main, enquanto as instâncias de controlo de qualidade e produção apontam geralmente para etiquetas git (descritas mais detalhadamente mais tarde).
Passos de configuração únicos
Os passos nesta secção só têm de ser concluídos uma vez por alguém com autorizações de administrador do Looker, bem como autorizações de administrador no respetivo fornecedor de Git.
Credenciais do Git
O ambiente Linux de cada programador tem de se ligar ao mesmo repositório que está a usar para gerir o seu LookML. É provável que seja um repositório externo alojado num serviço como o GitHub. Precisa de uma conta com esse serviço que tenha as credenciais adequadas para configurar o repositório. Com a conta, pode configurar uma chave SSH para permitir que o seu ambiente Linux se ligue automaticamente a esse serviço.
Para o 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 tem de ser armazenado num repositório git e associado a um projeto do Looker. Nas definições do projeto, o Nome do ramo de produção do Git tem de estar definido como main e a opção Ativar modo de implementação avançado tem de estar ativada.
Se os passos seguintes ainda não tiverem sido realizados, siga estas instruções para o GitHub:
Crie um novo repositório
- Na IU do GitHub, prima o botão + no canto superior direito e, de seguida, selecione New repository (Novo repositório).
- Selecione o proprietário (provavelmente a sua organização) e introduza um REPOSITORY_NAME.
- Escolha se quer tornar o repositório público ou privado (os repositórios privados requerem uma subscrição paga do GitHub) e selecione a caixa para o inicializar com um ficheiro README.
- Prima o botão Criar repositório.
- Prima o botão verde com a etiqueta <> Código e copie o URL SSH. Tem um aspeto semelhante ao seguinte:
git@github.com:org_name/REPOSITORY_NAME.git. - No Looker, crie um novo projeto.
- Entre no modo de desenvolvimento, escolha o item de definições do projeto na barra lateral esquerda e, de seguida, configure o Git.
- Cole o URL do repositório (
git@github.com:org_name/REPOSITORY_NAME.gitneste exemplo) e selecione Continuar. - Copie a chave de implementação e volte à IU do GitHub para este repositório.
- Escolha Definições e, de seguida, Ações – Geral.
- Em Autorizações do fluxo de trabalho, verifique se a opção Permitir que as ações do GitHub criem e aprovem pedidos de envio está selecionada e clique em Guardar.
- Mude para a página Chaves de implementação das definições do GitHub.
- Clique no botão Adicionar chave de implementação e cole a chave de implementação no campo Chave.
- Adicione um título, como
Looker-REPOSITORY_NAME, selecione a caixa de verificação Permitir acesso de escrita e prima o botão Adicionar chave. - Regresse ao Looker e escolha Testar e finalizar configuração.
- Escolha novamente as definições do projeto na barra lateral esquerda. Altere o Nome do ramo de produção do Git para
main. - Escolha Ativar modo de implementação avançado e selecione Guardar configuração do projeto.
Abaixo do ícone de definições do projeto, no lado esquerdo, deve ver um ícone de implementação para o Deployment Manager.
Use Existing Repo
- Navegue para o repositório do GitHub que armazena o seu LookML.
- Escolha Definições e, de seguida, Ações – Geral.
- Em Autorizações do fluxo de trabalho, verifique se a opção Permitir que as ações do GitHub criem e aprovem pedidos de envio está selecionada e clique em Guardar.
- Aceda à secção <> Código do repositório do GitHub.
- Prima o botão verde com a etiqueta <> Código e copie o URL SSH. Tem um aspeto semelhante ao seguinte:
git@github.com:org_name/REPOSITORY_NAME.git. - No Looker, crie um novo projeto.
- Entre no modo de desenvolvimento e escolha o item de definições do projeto na barra lateral esquerda e, de seguida, Configure o Git.
- Cole o URL do repositório (
git@github.com:org_name/REPOSITORY_NAME.gitneste exemplo) e selecione Continuar. - Copie a chave de implementação e volte à IU do GitHub para este repositório.
- Escolha Definições e, de seguida, Implementar chaves.
- Clique no botão Adicionar chave de implementação e cole a chave de implementação no campo Chave.
- Adicione um título, como
Looker-REPOSITORY_NAME, selecione a caixa de verificação Permitir acesso de escrita e prima o botão Adicionar chave. - Regresse ao Looker e escolha Testar e finalizar configuração.
- Escolha novamente as definições do projeto na barra lateral esquerda. Altere o Nome do ramo de produção do Git para
main. - Escolha Ativar modo de implementação avançado e selecione Guardar configuração do projeto.
Abaixo do ícone de definições do projeto, no lado esquerdo, deve ver um ícone de implementação para o Deployment Manager.
Criar ações do GitHub
É útil criar várias ações do GitHub para que sejam feitas várias verificações automaticamente sempre que são feitas alterações ao LookML. A adição destas ações requer que possa fazer alterações ao seu repositório Git no seu 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, aceda ao diretório do seu repositório no ambiente Linux e adicione o subdiretório .github/workflows. Depois de configuradas, estas ações podem ser executadas manualmente a partir da página Ações da IU do GitHub.
Look-At-Me-Sideways (LAMS)
O LAMS é um linter de código aberto que inspeciona o seu LookML para verificar a existência de erros e práticas inadequadas. Adiciona um ficheiro com o nome lams.yml ao diretório .github/workflows com o seguinte 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@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
Sempre que um commit é enviado para o GitHub ou um pedido de envio é aberto para unir código com a ramificação main, o LAMS é executado.
Release Please
O Release Please é uma ferramenta de código aberto que etiqueta automaticamente os lançamentos com os números de versão adequados.
Adiciona um ficheiro com o nome release-please.yml ao diretório .github/workflows com o seguinte 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
Consolidações convencionais
Esta ação do GitHub vai validar se um pedido de envio é aberto com um título que cumpre a norma de confirmação convencional.
Adiciona um ficheiro com o nome lint_pr_title.yml ao diretório .github/workflows com o seguinte 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 }}
permissions:
pull-requests:
read statuses: write
Envie as alterações para o GitHub
Por último, use os seguintes comandos para confirmar estas alterações da ação do GitHub e enviá-las para o GitHub:
git add .github/workflows/
git commit -m "chore: Added github actions"
git push
Proteger o ramo main
Na IU do GitHub, deve ativar as proteções de ramificações para a ramificação main, para que os programadores comuns não possam enviar alterações diretamente para essa ramificação. Em alternativa, fazem alterações num ramo diferente e, em seguida, abrem um pedido de obtenção. O pedido de envio pode ser revisto por outro programador antes de ser aprovado e sincronizado com main.
Para configurar a proteção de ramificações, aceda à IU do GitHub para o repositório, escolha Definições e, de seguida, Ramificações e prima o botão Adicionar regra de proteção de ramificações:
Introduza main como o Padrão do nome da ramificação e selecione as seguintes opções:
- Exija um pedido de obtenção antes da união
- Exija aprovações
- Ignorar aprovações de pedidos de obtenção desatualizadas quando são enviados novos commits
Por fim, prima o botão Criar na parte inferior da página.
Quando é criado um pedido de envio, as ações do GitHub configuradas anteriormente nestas instruções são executadas. Depois de serem executados pela primeira vez, também podem ser selecionados nesta IU para que tenham de ser bem-sucedidos antes de o pedido de obtenção poder ser unido a main.
Configurar pedidos de envio
No Looker, pode exigir que sejam usados pedidos de envio e fazer com que o Looker abra PRs em nome do programador. Esta opção só deve ser configurada para a instância de desenvolvimento. A instância de controlo de qualidade e produção vai usar o modo de implementação avançado para receber as respetivas atualizações.
Para ativar esta opção, aceda à página Configuração do projeto de cada projeto e, de seguida, selecione Pedidos de envio necessários no cabeçalho Integração do GitHub.
Prima o botão para definir um segredo de webhook, copie a string aleatória gerada e prima o botão Guardar configuração do projeto.
De volta à IU do GitHub para o seu repositório, escolha Definições e, de seguida, Webhooks. Prima o botão Adicionar webhook na parte superior direita:
- No campo com a etiqueta URL de carga útil, introduza
https://LOOKER_HOST_NAME/webhooks/projects/PROJECT_NAME/deploy - No campo com a etiqueta Chave secreta, cole a chave secreta que guardou do Looker
- Para a pergunta Que eventos quer acionar este webhook?, escolha Permitir-me selecionar eventos individuais
Verifique se as opções Pull requests e Pushes estão selecionadas:
Por fim, prima o botão Adicionar webhook na parte inferior da página.
Passos de configuração para cada programador do Looker
Todos os passos de instalação seguintes devem ser realizados no seu ambiente Linux.
Instalar o Ruby
Tem de instalar a linguagem de programação Ruby para executar o Gazer. Qualquer versão do Ruby posterior à 2.7.7 funciona com o Gazer, mas o Ruby 3.x.x é preferível. Para instalar o Ruby no Ubuntu Linux, execute estes comandos:
sudo apt update
sudo apt install ruby
Confirme que o Ruby está instalado corretamente executando ruby -v. Isto deve dar uma resposta semelhante à seguinte:
ruby 3.1.3p185 (2022-11-24 revision 1a6b16756e) [x86_64-linux]
Estes comandos também funcionam no Debian Linux, no Linux Mint e em várias outras versões do Linux que usam o gestor de pacotes Aptitude. Pode ter de pesquisar comandos que funcionem noutras versões do Linux ou comandos para instalar no macOS. Consulte o artigo Instalar o Ruby para mais informações.
Instalar o Gazer
O Gazer é um projeto de código aberto criado por funcionários da Google para navegar e gerir espaços, visuais e painéis de controlo através de uma ferramenta de linha de comandos.
Com o Ruby instalado, pode usar a ferramenta Gem do Ruby para instalar o Gazer:
gem install gazer
Confirme se o Gazer está instalado com o comando gzr version. Isto deve dar uma resposta semelhante à seguinte:
v0.3.12
Instalar os Spectacles
O Spectacles é uma ferramenta de código aberto usada para testar o LookML (a respetiva versão paga já não está disponível). Pode encontrar detalhes sobre a instalação na respetiva página de introdução.
Instalar o Git
O software de controlo de versões Git pode ser instalado no Ubuntu Linux com este comando:
sudo apt update
sudo apt install git
Confirme se a instalação foi bem-sucedida com o comando git --version. Isto deve dar uma resposta semelhante à seguinte:
git version 2.42.0.609.gbb76f46606
Estes comandos também funcionam no Debian Linux, no Linux Mint e em várias outras versões do Linux que usam o gestor de pacotes Aptitude. Pode ter de pesquisar comandos que funcionem noutras versões do Linux. Por exemplo, pode encontrar instruções para o Fedora e o macOS em Introdução: instalar o Git.
Configurar o Git
O Git no seu ambiente Linux tem de ser configurado para interagir com o repositório Git no qual o LookML está armazenado. Estas instruções foram escritas para repositórios Git do LookML armazenados no GitHub.
Nome e email
O GitHub (e a maioria das outras implementações do Git) precisa de saber o seu nome e endereço de email para poder registar a atividade. Configure o seu nome e email 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, foram criadas credenciais do Git. A chave SSH privada gerada deve ser configurada num ficheiro $HOME/.ssh/config. Para criar o ficheiro, use estes comandos:
touch $HOME/.ssh/config
chmod 600 $HOME/.ssh/config
Insira o seguinte texto no ficheiro $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 ficheiro de chave privada que gerou com as instruções em Adicionar uma nova chave SSH à sua conta do GitHub. O ficheiro de chave privada tem o mesmo nome que o ficheiro de chave pública, mas sem a extensão .pub. Por exemplo, se usou a chave pública encontrada no ficheiro id_ed25519.pub, a chave privada teria o nome id_ed25519.
Configurar o repositório Git local
Depois de configurar o repositório LookML, tem de fazer uma cópia do mesmo no seu ambiente Linux. Para o fazer, execute este comando:
git clone GIT_URL
Por exemplo, o comando pode aparecer da seguinte forma:
git clone git@github.com:my_org_name/sales_project.git
Esta ação copia o repositório LookML para uma subdiretoria, por exemplo, sales_project. Use o comando cd SUB_DIRECTORY para aceder ao repositório. Neste exemplo, o comando seria cd sales_project.
Assim que estiver no diretório do repositório, pode usar os seguintes comandos:
| Comando | Finalidade |
|---|---|
git checkout BRANCH_NAME |
Usado para mudar de ramificações. Na maioria dos casos, o ramo principal chama-se main. No entanto, em sistemas mais antigos, pode chamar-se master. |
git fetch |
Usado para obter as alterações mais recentes do servidor. |
git pull |
Usado para aplicar alterações aos ficheiros locais extraídos. git pull faz implicitamente um git fetch. |
git tag |
Usado para criar uma etiqueta significativa para uma revisão específica. |
git push |
Usado para enviar alterações locais para o servidor. |
Configurar o Gazer
Para usar o Gazer, precisa de credenciais da API para cada uma das instâncias de desenvolvimento, controlo de qualidade e produção. Para obter instruções sobre como criar credenciais da API, consulte a página Definições de administrador – Utilizadores. As credenciais da API podem já ter sido criadas pela pessoa que configurou inicialmente o fluxo de trabalho de CI/CD. Nesse caso, pode usar a credencial existente. Não é necessário gerar novas credenciais para cada pessoa.
Armazene as suas credenciais da API num ficheiro .netrc com o mínimo de autorizações no seu diretório inicial. Pode criar um ficheiro vazio com as autorizações corretas através destes comandos:
touch $HOME/.netrc
chmod 600 $HOME/.netrc
Adicione entradas como as seguintes ao ficheiro, mas use os seus próprios nomes de anfitriões do servidor do Looker para machine, a API client_id para o início de sessão e a API client_secret para a palavra-passe. Por 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
Teste se isto funciona executando um comando Gazer em cada servidor, como o seguinte:
gzr user me --host dev.example.looker.com
Isto deve dar um resultado semelhante ao seguinte:
+----+---------------+---------+----------+------------------+--------------+
| 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, pode ter de adicionar --port 443 ao final do comando gzr, da seguinte forma:
gzr user me --host dev.example.looker.com --port 443
Configurar os Spectacles
Os Spectacles usam a mesma API client_id e client_secret que o Gazer. No diretório dos Spectacles, crie um ficheiro para cada nível com o nome config-TIER.yaml, por exemplo, config-dev.yaml. Adicione o seguinte conteúdo aos ficheiros, conforme adequado para a instância do Looker desse nível, como o seguinte:
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
Pode testar cada ficheiro executando o seguinte comando e substituindo cada nome de ficheiro:
$ spectacles connect --config-file config-dev.yaml
Deve esperar uma resposta semelhante à seguinte:
Connected to Looker version 23.18.60 using Looker API 4.0