Nesta página, explicamos 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, controle de qualidade e produção. No entanto, os mesmos princípios podem ser aplicados a um sistema de duas ou quatro camadas.
Estas instruções também pressupõem o uso do GitHub como seu provedor do Git. Você pode usar outros provedores do Git para criar um fluxo de trabalho de CI/CD. No entanto, é necessário ter experiência para modificar essas instruções para seu provedor.
Siga as instruções na seção relevante para você:
- Pré-requisitos
- Etapas de configuração para a primeira vez
- Etapas de configuração para cada desenvolvedor do Looker
Pré-requisitos
Ambiente Linux
Esse processo usa ferramentas chamadas Gazer e Spectacles, projetadas para funcionar com sistemas operacionais semelhantes ao Unix. Cada desenvolvedor de 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 poderão ser usados no Subsistema Windows para Linux (WSL, na sigla em inglês) da Microsoft. Com o WSL, é possível executar várias versões diferentes do Linux. Se você não tiver um sistema operacional Linux preferido, a versão mais recente do Ubuntu Linux será uma boa opção devido ao amplo suporte.
Estas instruções fornecem exemplos para sistemas Linux e podem precisar de modificações se você estiver usando macOS ou WSL.
Uma instância do Looker por nível
Para ativar essa configuração, você precisa de uma instância do Looker para cada nível do seu sistema. Por exemplo, um sistema com um estágio de desenvolvimento, um estágio de controle de qualidade e um estágio 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, independente 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 eles apontarem para o mesmo banco de dados, será necessário definir esquemas temporários diferentes para que as tabelas derivadas permanentes na instância de desenvolvimento ou controle de qualidade não interfiram na produção.
Por exemplo, se o mesmo banco de dados for usado para todas 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 |
sales_db |
sales_db |
| Esquema de trabalho | prod_sales_scratch |
qa_sales_scratch |
dev_sales_scratch |
Ou, se um banco de dados exclusivo for usado para todas 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 de trabalho | sales_scratch |
sales_scratch |
sales_scratch |
Repositório do Git
Um único repositório git será usado para cada projeto em todos os três níveis. A instância de desenvolvimento vai rastrear a ramificação main, enquanto as instâncias de controle de qualidade e produção geralmente apontam para tags do Git (descritas em mais detalhes posteriormente).
Etapas de configuração única
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 Git.
Credenciais do Git
O ambiente Linux de cada desenvolvedor precisa se conectar ao mesmo repositório que você está usando para gerenciar a LookML. Provavelmente, é um repositório externo hospedado em um serviço como o GitHub. Você vai precisar de uma conta com esse serviço que tenha as credenciais adequadas para configurar o repositório. Com ela, é possível configurar uma chave SSH para permitir que seu ambiente Linux se conecte automaticamente a esse serviço.
Para o GitHub, siga as instruções em Adicionar uma nova chave SSH à sua conta do GitHub.
Como criar e configurar um repositório de servidor Git
Para que o fluxo de trabalho de CI/CD funcione, a LookML precisa ser armazenada em um repositório Git e conectada a um projeto do Looker. Nas configurações do projeto, o Nome da ramificação de produção do Git precisa ser definido como main e a opção Ativar o modo de implantação avançado precisa estar ativada.
Se as etapas a seguir ainda não foram realizadas, siga estas instruções para o GitHub:
Criar novo repositório
- Na interface do GitHub, pressione o botão + no canto superior direito e selecione Novo repositório.
- Selecione o proprietário (provavelmente sua organização) e insira um REPOSITORY_NAME.
- Escolha se o repositório será público ou privado (repositórios privados exigem uma assinatura paga do GitHub) e marque a caixa para inicializá-lo com um arquivo README.
- Clique no botão Criar repositório.
- Pressione o botão verde <> Code e copie o URL do SSH. Ele será semelhante a:
git@github.com:org_name/REPOSITORY_NAME.git. - No Looker, crie um projeto.
- Entre no modo de desenvolvimento e escolha o item de configurações do projeto na barra lateral esquerda. Em seguida, clique em Configurar Git.
- Cole o URL do repositório (
git@github.com:org_name/REPOSITORY_NAME.gitneste exemplo) e selecione Continuar. - Copie a chave de implantação e volte para a interface do GitHub desse repositório.
- Escolha Configurações e depois Ações - Geral.
- Em Permissões de fluxo de trabalho, verifique se a opção Permitir que o GitHub Actions crie e aprove solicitações de envio está marcada e clique em Salvar.
- Acesse a página Chaves de implantação nas configurações do GitHub.
- Clique no botão Adicionar chave de implantação e cole a chave no campo Chave.
- Adicione um título, como
Looker-REPOSITORY_NAME, marque a caixa de seleção Permitir acesso de gravação e clique no botão Adicionar chave. - Volte para o Looker e escolha Testar e finalizar a configuração.
- Escolha "Configurações do projeto" novamente na barra lateral esquerda. Mude o Nome do branch de produção do Git para
main. - Escolha Ativar o modo de implantação avançada 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 do Deployment Manager.
Usar repositório atual
- Navegue até o repositório do GitHub que armazena sua LookML.
- Escolha Configurações e depois Ações - Geral.
- Em Permissões de fluxo de trabalho, verifique se a opção Permitir que o GitHub Actions crie e aprove solicitações de envio está marcada e clique em Salvar.
- Acesse a seção <> Code do repositório do GitHub.
- Pressione o botão verde <> Code e copie o URL do SSH. Ele será semelhante a:
git@github.com:org_name/REPOSITORY_NAME.git. - No Looker, crie um projeto.
- Entre no modo de desenvolvimento e escolha o item de configurações do projeto na barra lateral esquerda. Em seguida, clique em Configurar Git.
- Cole o URL do repositório (
git@github.com:org_name/REPOSITORY_NAME.gitneste exemplo) e selecione Continuar. - Copie a chave de implantação e volte para a interface do GitHub desse repositório.
- Escolha Configurações e depois Implantar chaves.
- Clique no botão Adicionar chave de implantação e cole a chave no campo Chave.
- Adicione um título, como
Looker-REPOSITORY_NAME, marque a caixa de seleção Permitir acesso de gravação e clique no botão Adicionar chave. - Volte para o Looker e escolha Testar e finalizar a configuração.
- Escolha "Configurações do projeto" novamente na barra lateral esquerda. Mude o Nome do branch de produção do Git para
main. - Escolha Ativar o modo de implantação avançada 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 do 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 forem feitas mudanças na LookML. Para adicionar essas ações, é necessário fazer mudanças no repositório Git no ambiente Linux. Se ele ainda não estiver disponível, siga as instruções em Configurar o 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 é um linter de código aberto que inspeciona sua LookML em busca de 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@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
O LAMS é executado sempre que uma confirmação é enviada para o GitHub ou uma solicitação de envio é aberta para mesclar o código com a ramificação main.
Release Please
O Release Please (link em inglês) é uma ferramenta de código aberto que marca automaticamente os lançamentos com os números de versão adequados.
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
Commits convencionais
Essa ação do GitHub verifica se uma solicitação de envio foi aberta com um título que segue o padrão de commit 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 }}
permissions:
pull-requests:
read statuses: write
Envie as mudanças para o GitHub
Por fim, use os comandos a seguir para confirmar e enviar essas mudanças da ação do GitHub:
git add .github/workflows/
git commit -m "chore: Added github actions"
git push
Proteção da ramificação main
Na interface do GitHub, ative as proteções de ramificação para a ramificação main. Assim, os desenvolvedores comuns não poderão enviar mudanças diretamente para ela. Em vez disso, eles fazem mudanças em uma ramificação diferente e abrem uma solicitação de envio. A solicitação de envio pode ser revisada por outro desenvolvedor antes de ser aprovada e mesclada com main.
Para configurar a proteção de ramificação, acesse a interface do GitHub para o repositório, escolha Configurações e Ramificações e pressione o botão Adicionar regra de 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 de mesclar
- Exigir aprovações
- Dispensar aprovações de solicitação de envio desatualizadas quando novos commits forem enviados
Por fim, clique no 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 UI para que precisem ser concluídos antes que a solicitação de envio possa ser mesclada com main.
Como configurar solicitações de envio
No Looker, é possível exigir que as solicitações de pull sejam usadas e fazer com que o Looker abra PRs em nome do desenvolvedor. Isso só deve ser configurado para a instância de desenvolvimento. As instâncias de QA e produção usam o modo de implantação avançada para receber atualizações.
Para ativar, acesse a página Configuração do projeto de cada projeto e selecione Solicitações de envio necessárias no cabeçalho Integração do GitHub.
Pressione o botão para definir um secret de webhook, copie a string aleatória gerada e pressione o botão Salvar configuração do projeto.
De volta à interface do GitHub para seu repositório, escolha Configurações e Webhooks. Clique no botão Adicionar webhook no canto superior direito:
- No campo URL de payload, insira
https://LOOKER_HOST_NAME/webhooks/projects/PROJECT_NAME/deploy. - No campo Secret, cole o secret salvo do Looker.
- Na pergunta Quais eventos você quer que acionem este webhook?, escolha Quero selecionar eventos individuais.
Verifique se as opções Pull Requests e Pushes estão selecionadas:
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 seu ambiente Linux.
Como instalar o Ruby
A linguagem de programação Ruby precisa ser instalada para executar o Gazer. Qualquer versão do Ruby após a 2.7.7 funciona com o Gazer, mas a 3.x.x é preferível. Para instalar o Ruby no Ubuntu Linux, execute estes comandos:
sudo apt update
sudo apt install ruby
Execute ruby -v para confirmar se o Ruby está instalado corretamente. 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, no Linux Mint e em várias outras versõ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. Confira Como instalar o Ruby para mais informações.
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 código aberto usada para testar o LookML. A versão paga não está mais disponível. Confira detalhes sobre a instalação na página de início.
Como instalar o Git
O software de controle de versões do 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. Isso vai gerar uma resposta semelhante a esta:
git version 2.42.0.609.gbb76f46606
Esses comandos também funcionam no Debian Linux, no Linux Mint e em várias outras versões do Linux que usam o gerenciador de pacotes Aptitude. Talvez seja necessário pesquisar comandos que funcionem em outras variações do Linux. As instruções para Fedora e macOS, por exemplo, podem ser encontradas em Primeiros passos - Instalar o Git.
Como configurar o Git
O Git no seu ambiente Linux precisa ser configurado para interagir com o repositório Git em que a LookML está armazenada. Estas instruções foram escritas para repositórios Git do LookML 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 texto a seguir 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 em 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 LookML, faça uma cópia dele no seu ambiente Linux. Para isso, execute este comando:
git clone GIT_URL
Por exemplo, o comando pode aparecer assim:
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, use os seguintes comandos:
| Comando | Finalidade |
|---|---|
git checkout BRANCH_NAME |
Usado para alternar 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 recuperar as mudanças mais recentes do servidor. |
git pull |
Usado para aplicar mudanças aos arquivos locais extraídos. git pull faz implicitamente um git fetch. |
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ê precisa 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 de administrador - Usuários. As credenciais da API podem já ter sido criadas pela pessoa que configurou o fluxo de trabalho de CI/CD. 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 seu 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 entradas como as seguintes ao arquivo, 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 do Gazer em cada servidor, como este:
gzr user me --host dev.example.looker.com
Isso vai gerar um resultado 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, da seguinte maneira:
gzr user me --host dev.example.looker.com --port 443
Como configurar os Spectacles
Os Spectacles usam as mesmas APIs client_id e client_secret do Gazer. No diretório do Spectacles, crie um arquivo para cada nível chamado config-TIER.yaml, por exemplo, config-dev.yaml. Adicione o seguinte conteúdo aos arquivos, conforme apropriado para a instância do Looker daquele 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 a seguir 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