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
- Etapas de configuração apenas 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 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
- 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:
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 para a interface do GitHub desse 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 a 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ç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
- Acesse o repositório do GitHub que armazena o LookML.
- 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 novo projeto.
- Entre no modo de desenvolvimento, escolha o item de configurações do projeto na barra à 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 para a interface do GitHub desse 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 a 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ç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:
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
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
Verifique se as opções Solicitações de pull 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 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