Nesta página, explicamos como instalar e configurar os componentes necessários para implementar um fluxo de trabalho de CI/CD de várias camadas 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 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 uma ferramenta chamada Gazer, projetada para funcionar com sistemas operacionais semelhantes ao Unix. Cada desenvolvedor do LookML que precisa migrar o conteúdo do usuário precisa ter acesso à linha de comando em um ambiente Linux ou macOS onde você planeja executar o fluxo de trabalho de CI/CD.
Se você estiver usando o Windows, o Gazer poderá ser usado no Subsistema do 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 de teste 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 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 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çada 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 inicializar 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 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.
- Mude para a página Chaves de implantação das 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 da ramificação 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 do Deployment Manager.
Usar o repositório atual
- Acesse o repositório do GitHub que armazena sua LookML. (Insira o nome do seu repositório aqui: REPOSITORY_NAME.)
- Escolha Configurações e 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 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 da ramificação 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 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 um commit é enviado ao GitHub ou uma solicitação de envio é aberta para mesclar o código com a ramificação main.
Liberar
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 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
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 fazer commit dessas mudanças na 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. 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 analisada 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.
Configurar solicitações de pull
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 controle de qualidade e produção vão usar o Modo de implantação avançado para receber as 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 Solicitações de envio e Envios estão selecionadas:
Por fim, pressione o 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 mais informações em Como instalar o Ruby.
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 configurar a integração contínua do Looker
Para testar e validar o LookML, use a integração contínua do Looker. A integração contínua é integrada ao Looker e não requer instalação local da CLI.
Para usar a integração contínua, siga estas etapas:
- Verifique se a instância atende aos requisitos de integração contínua.
- Peça para um administrador do Looker ativar a integração contínua e instalar o app GitHub da CI.
- Crie um pacote de integração contínua para configurar os validadores e gatilhos do seu projeto.
Para mais informações, consulte a documentação de integração contínua do Looker.
Como instalar o Git
O software de controle 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. 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 versões do Linux. As instruções para Fedora e macOS, por exemplo, podem ser encontradas em Introdução - Instalar o Git.
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 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 será chamada de id_ed25519.
Como configurar seu repositório Git local
Depois de configurar o repositório LookML, faça uma cópia dele no ambiente 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 vai copiar o repositório 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 verificados. git pull faz um 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ê 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 suas credenciais de 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. 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
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 forma:
gzr user me --host dev.example.looker.com --port 443
Como configurar pacotes de integração contínua
Crie pacotes de integração contínua no Looker para especificar suas regras de validação e configurações de teste.
Em um conjunto de CI, é possível configurar o seguinte:
- Opções de acionamento para executar a validação automaticamente em solicitações de pull, de acordo com uma programação ou manualmente no IDE do Looker.
- Validador de SQL para testar dimensões no banco de dados.
- Assert Validator para executar testes de dados do LookML.
- Validador de conteúdo para testar Looks e dashboards.
- Validador do LookML para verificar a sintaxe do LookML.
- O validador de estilo para aplicar padrões de programação do LookML, convenções de nomenclatura e práticas recomendadas estruturais em todo o projeto.
Para instruções sobre como configurar pacotes, consulte Criar um pacote de integração contínua.