Nesta página, explicamos como instalar e configurar os componentes necessários para implementar um fluxo de trabalho de CI/CD no Looker.
Essas instruções usam um sistema de três camadas que abrange 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 Git para criar um fluxo de trabalho de CI/CD. No entanto, você precisa 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 somente 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, que foram projetadas para funcionar com sistemas operacionais do tipo Unix. Todos os desenvolvedores do LookML precisam ter acesso à linha de comando em um ambiente Linux ou macOS em que você planeja executar seu fluxo de trabalho de CI/CD.
Se você estiver usando o Windows, o Gazer e o Spectacles poderão ser usados dentro do Windows Subsystem For Linux (WSL) da Microsoft. A WSL permite executar várias variações do Linux. Se você não tem um sistema operacional Linux preferido, a versão mais recente do Ubuntu Linux é uma boa escolha devido ao amplo suporte oferecido.
Estas instruções fornecem exemplos para sistemas Linux e podem exigir modificações se você estiver usando o macOS ou a WSL.
Uma instância do Looker por nível
Para ativar essa configuração, você vai precisar de uma instância do Looker para cada camada do sistema. Por exemplo, um sistema com os estágios de desenvolvimento, controle de qualidade e produção 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 todas as instâncias do Looker, independente do nível que representem. 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 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 para as três instâncias, elas poderão ser configuradas da seguinte maneira:
| Production | Controle de qualidade | Development | |
| Nome da conexão | sales |
sales |
sales |
| banco de dados | sales_db |
sales_db |
sales_db |
| Esquema de rascunho | prod_sales_scratch |
qa_sales_scratch |
dev_sales_scratch |
Ou, se um banco de dados exclusivo for usado para as três instâncias, elas poderão ser configuradas da seguinte maneira:
| Production | Controle de qualidade | 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 git será usado para cada projeto nos três níveis. A instância de desenvolvimento rastreará a ramificação main, enquanto as instâncias de controle de qualidade e produção geralmente apontarão para tags git (descritas em mais detalhes posteriormente).
Etapas somente de primeira configuração
As etapas desta seção só precisam ser concluídas uma vez por alguém com permissões de administrador do Looker e de administrador no provedor 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. Provavelmente, é um repositório externo hospedado em um serviço como o GitHub. Você precisará de uma conta com esse serviço que tenha as credenciais apropriadas para configurar o repositório. Com a conta, você pode configurar uma chave SSH para permitir que o ambiente Linux se conecte automaticamente a esse serviço.
No GitHub, siga as instruções em Adicionar uma nova chave SSH à sua conta do GitHub.
Como 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, defina Git Production Branch Name como main e ative Enable Advanced Deploy Mode.
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 (os repositórios privados exigem uma assinatura paga do GitHub) e marque a caixa para inicializar com um arquivo README.
- Pressione o botão Criar repositório.
- Pressione o botão verde <> Code e copie o URL do SSH. Ele será semelhante a este:
git@github.com:org_name/REPOSITORY_NAME.git. - No Looker, crie um novo projeto.
- Entre no modo de desenvolvimento, escolha o item de configurações do projeto na barra lateral esquerda e 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 à interface do GitHub para esse repositório.
- Escolha Configurações e Implantar chaves.
- Clique no botão Adicionar chave de implantação e cole a chave de implantação no campo Chave.
- 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. - Volte para o Looker e escolha Testar e finalizar configuração.
- Escolha as 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ê verá um ícone de implantação do Deployment Manager.
Usar o repositório atual
- Navegue até o repositório do GitHub que armazena o LookML.
- Pressione o botão verde com o rótulo <> Code e copie o URL SSH. Ele será semelhante a:
git@github.com:org_name/REPOSITORY_NAME.git. - No Looker, crie um novo projeto.
- Entre no modo de desenvolvimento, escolha o item de configurações do projeto na barra lateral esquerda e 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 à interface do GitHub para esse repositório.
- Escolha Configurações e Implantar chaves.
- Clique no botão Adicionar chave de implantação e cole a chave de implantação no campo Chave.
- 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. - Volte para o Looker e escolha Testar e finalizar configuração.
- Escolha as 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ê verá 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 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 é 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.
Liberação por favor
Release Please é uma ferramenta de código aberto que marca automaticamente as versões com os números de versão apropriados.
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 }}
Enviar as alterações para o GitHub
Por fim, use os seguintes comandos para confirmar essas alterações de ação do GitHub e enviá-las para o GitHub:
git add .github/workflows/
git commit -m "chore: Added github actions"
git push
Como 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 contra ramificações, acesse a interface do GitHub para o repositório, selecione Settings e Branches e, em seguida, pressione o botão Adicionar regra de proteção de ramificação:
Digite main como o Padrão de 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
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 serã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, é possível exigir que as solicitações de envio sejam usadas e que o Looker abra PRs em nome do desenvolvedor. Isso só deve ser configurado para a instância de desenvolvimento. O controle de qualidade e a instância de produção usarão o modo de implantação avançada 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, selecione Settings e Webhooks. Pressione o botão Adicionar webhook no canto superior direito:
- No campo Payload URL, digite
https://LOOKER_HOST_NAME/webhooks/projects/PROJECT_NAME/deploy. - No campo Secret, cole a chave que você salvou do Looker.
- Para a pergunta Quais eventos você quer acionar com este webhook?, escolha Deixe-me selecionar eventos individuais
Verifique se Solicitações de envio e Pushes estão selecionados:
Por fim, pressione o botão Add 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.
Como instalar o Ruby
A linguagem de programação Ruby precisa estar instalada para executar o Gazer. Qualquer versão do Ruby posterior à 2.7.7 funcionará com o Gazer, mas a Ruby 3.x.x é a preferida. 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 variações do Linux ou comandos 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
Instalar os Spectacles
O Spectacles é uma ferramenta não pertencente ao Google usada para testar o LookML. O Spectacles oferece uma versão paga e uma versão de código aberto, e os detalhes de instalação podem ser encontrados na página Introdução.
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 variações do Linux. Instruções para Fedora e macOS, por exemplo, podem ser encontradas em Getting Started - Starting 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. Essas 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
Credenciais git foram criadas na configuração inicial do CI/CD. A chave SSH privada 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 que o 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 será 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 assim:
git clone git@github.com:my_org_name/sales_project.git
Isso 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 | Motivo |
|---|---|
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 alterações mais recentes do servidor. |
git pull |
Usado para aplicar mudanças nos 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ê 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 já ter sido criadas pela pessoa que configurou inicialmente 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 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 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, da seguinte maneira:
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 chamado 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