Nesta página, explicamos como usar um fluxo de trabalho de CI/CD no Looker depois que ele for instalado e configurado.
Estas instruções usam um sistema de três níveis que inclui desenvolvimento, controle de qualidade e produção. No entanto, é possível aplicar os mesmos princípios 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.
Visão geral do fluxo de trabalho
Os desenvolvedores de LookML começam escrevendo código na ramificação de desenvolvimento, que normalmente tem um nome como dev-my-user-ydnv, testam as mudanças com o Spectacles e fazem o commit do código. Por fim, eles abrem uma solicitação de envio para mesclar o código com a ramificação main.
Quando a solicitação de envio é aberta, ela leva o desenvolvedor ao GitHub. O desenvolvedor precisa escrever um título de solicitação de pull significativo usando o estilo de commits convencionais e adicionar um comentário à descrição que será incluída no changelog. Os resultados dos testes do Spectacles precisam ser adicionados como comentários ao PR.
Em seguida, o desenvolvedor precisa selecionar um revisor no GitHub. O revisor vai receber uma notificação e poderá adicionar a avaliação ao PR. Se o revisor aprovar a mudança, a solicitação de envio será mesclada com a ramificação main. Um WebHook é chamado, e o ambiente de desenvolvimento agora vê a mudança.
Automaticamente, a automação do Release Please será executada e abrirá uma segunda solicitação de pull para criar uma nova versão com tag. Ou, se já houver um PR aberto para essa finalidade, o Release Please vai atualizar esse PR. O RP de lançamento tem um número de versão associado a ele, bem como um changelog que inclui os títulos e as descrições das mudanças incluídas.
Quando o PR gerado pelo Release Please é aprovado e mesclado, uma nova tag de versão é gerada, e o changelog é mesclado com a ramificação main. As instâncias de QA e produção do Looker podem selecionar essa versão usando o Modo de implantação avançado.
Práticas recomendadas para numerar versões e nomear commits
Os lançamentos e as tags associadas podem ser nomeados e numerados de qualquer maneira que faça sentido no seu ambiente. No entanto, o controle de versões semântico é usado aqui e é altamente recomendado porque funciona bem com o plug-in Release Please.
No controle de versão semântico, a versão consiste em três números separados por pontos: MAJOR.MINOR.PATCH
PATCHé incrementado sempre que uma versão corrige um bug.MINORé incrementado ePATCHé redefinido como zero sempre que a versão adiciona ou refina um recurso, mantendo a compatibilidade com versões anteriores.MAJORé incrementado, eMINORePATCHsão definidos como zero quando um recurso não compatível com versões anteriores é adicionado.
O Conventional Commits é um sistema de nomenclatura de commits pelo impacto que eles têm nos usuários finais. Embora não seja obrigatório, o uso de nomes de commit convencionais também é útil para o plug-in Release Please.
Na nomenclatura convencional de commits, cada mensagem de commit é precedida por um indicador do escopo da mudança:
- Uma correção de bug é indicada com
fix:, comofix: set proper currency symbol on sale_amt format - Um novo recurso é indicado com
feat:, comofeat: added explore for sales by territory - Um recurso com uma mudança interruptiva é indicado por
feat!:, comofeat!: rewrote sales explore to use the new calendar view. - Quando a documentação é atualizada, mas o LookML não é alterado, a mensagem de confirmação começa com
doc:
Se os commits convencionais forem usados de forma consistente, determinar o número semântico a ser usado em seguida geralmente é simples. Se o registro de commit consistir apenas em commits fix: e doc:, o PATCH vai ser incrementado. Se houver um commit feat:, MINOR precisará ser incrementado. Se houver um feat!:, MAJOR precisará ser incrementado. O plug-in Release Please pode até gerar um arquivo CHANGELOG e marcar a versão automaticamente.
Como usar o modo de implantação avançado
Depois que as mudanças forem feitas e enviadas como uma solicitação de pull na instância de desenvolvimento, o plug-in Release Please vai marcar as mudanças com uma tag de versão, como v1.2.3. O Modo de implantação avançada do Looker disponibiliza essas versões na interface do Looker para as instâncias de controle de qualidade e produção.
Para implantar uma mudança, escolha o Deployment Manager no Looker IDE:
Clique no link Selecionar confirmação no canto superior direito do Deployment Manager. Em seguida, selecione o menu de três pontos associado à tag que você quer implantar e escolha Implantar no ambiente:
Não é necessário adicionar tags à implantação novamente. Escolha Implantar sem adicionar tags e pressione o botão Implantar no ambiente:
Por fim, envie para produção usando o Deployment Manager.
Como usar os Spectacles
Os Spectacles podem ser usados por cada desenvolvedor para verificar as mudanças enquanto ainda estão na ramificação de desenvolvimento. O Spectacles oferece quatro validadores diferentes:
Quando um desenvolvedor envia uma solicitação de envio, é recomendável executar esses testes e copiar os resultados para um comentário na solicitação.
Validador de SQL
O validador de SQL testa cada análise para verificar se todos os campos definidos nas visualizações da LookML correspondem a colunas SQL reais ou expressões SQL válidas no banco de dados. O validador de SQL é chamado conforme mostrado a seguir:
$ spectacles sql --config-file config-dev.yaml \
--project PROJECT_NAME \
--explores MODEL_NAME/EXPLORE_NAME \
--branch DEV_BRANCH_NAME
Exemplo:
$ spectacles sql --config-file config-dev.yaml \
--project thelook_cicd \
--explores thelook_cicd/users \
--branch dev-my-user-ydnv
Connected to Looker version 23.18.60 using Looker API 4.0
=================== Testing 1/1 explores [concurrency = 10] ===================
✓ thelook_cicd.users passed
Completed SQL validation in 1 minute and 7 seconds.
Validador do LookML
O validador do LookML verifica se as mudanças no LookML são válidas e não têm erros de sintaxe. Ele é chamado como mostrado a seguir:
$ spectacles lookml --config-file config-dev.yaml \
--project PROJECT_NAME \
--branch DEV_BRANCH_NAME
Exemplo:
$ spectacles lookml --config-file config-dev.yaml \
--project thelook_cicd \
--branch dev-my-user-ydnv
Connected to Looker version 23.18.60 using Looker API 4.0
============= Validating LookML in project thelook_cicd [warning] ==============
✗ thelook_cicd/business_pulse.dashboard.lookml failed
✗ thelook_cicd/thelook_cicd.model.lkml failed
================ thelook_cicd/business_pulse.dashboard.lookml:28 ===============
[Error] Unknown field "users.state" in explore "users" for field_filter.
LookML: https://gcpl2318.cloud.looker.com/projects/thelook_cicd/files/business_pulse.dashboard.lookml?line=28
================ thelook_cicd/business_pulse.dashboard.lookml:36 ===============
[Warning] Unknown field "users.state" (for explore "orders" in model
"thelook_cicd") referenced in dashboard element.
LookML: https://gcpl2318.cloud.looker.com/projects/thelook_cicd/files/business_pulse.dashboard.lookml?line=36
[Additional errors snipped]
Completed validation in 6 seconds.
Validador de conteúdo
O Content Validator testa se o conteúdo salvo, como análises detalhadas e painéis definidos pelo usuário (UDDs), ainda funciona após as mudanças. Para acelerar a execução do job e fornecer resultados gerenciáveis, a validação é feita apenas para conteúdo baseado nas análises detalhadas especificadas. O Content Validator é chamado da seguinte maneira:
$ spectacles content --config-file config-dev.yaml \
--project PROJECT_NAME \
--explores MODEL_NAME/EXPLORE_NAME \
--branch DEV_BRANCH_NAME
Exemplo:
$ spectacles content --config-file config-dev.yaml \
--project thelook_cicd \
--explores thelook_cicd/users \
--branch dev-my-user-ydnv
Connected to Looker version 23.18.60 using Looker API 4.0
Building LookML project hierarchy for project 'thelook_cicd' @ dev-my-user-ydnv
==================== Validating content based on 5 explores ====================
✗ thelook_cicd.users failed
================= test dashboard for spectacles [TheLook_CICD] =================
Tile 'test dashboard for spectacles' failed validation.
Error in thelook_cicd/users: Unknown field "users.state".
Dashboard: https://gcpl2318.cloud.looker.com/dashboards/223
========================= Business Pulse [TheLook_CICD] ========================
Filter 'State / Region' failed validation.
Error in thelook_cicd/users: Unknown field "users.state".
Dashboard: https://gcpl2318.cloud.looker.com/dashboards/190
Completed content validation in 27 seconds.
Validação de asserção
O Assert Validation testa as declarações de dados que você adicionou ao LookML para verificar se os dados estão sendo lidos corretamente. Por exemplo, um teste de dados no LookML pode ser assim:
test: historic_revenue_is_accurate {
explore_source: orders {
column: total_revenue { field: orders.total_revenue }
filters: [orders.created_date: "2019"]
}
assert: revenue_is_expected_value {
expression: ${orders.total_revenue} = 626000 ;;
}
}
A validação de asserção é chamada conforme mostrado a seguir:
$ spectacles assert --config-file config-dev.yaml \
--project PROJECT_NAME \
--explores MODEL_NAME/EXPLORE_NAME \
--branch DEV_BRANCH_NAME
Exemplo:
$ spectacles assert --config-file config-dev.yaml \
--project thelook_cicd \
--explores thelook_cicd/users \
--branch dev-my-user-ydnv
Connected to Looker version 23.18.60 using Looker API 4.0
Building LookML project hierarchy for project 'thelook_cicd' @ dev-my-user-ydnv
==================== Running data tests based on 1 explore =====================
✗ thelook_cicd.users failed
================ thelook_cicd/users/california_users_is_accurate ===============
Unknown filter field "users.state" in lookml test "california_users_is_accurate"
declaration.
LookML: https://gcpl2318.cloud.looker.com/projects/thelook_cicd/files/thelook_cicd.model.lkml?line=55
================ thelook_cicd/users/california_users_is_accurate ===============
Invalid filter: users.state
LookML: https://gcpl2318.cloud.looker.com/projects/thelook_cicd/files/thelook_cicd.model.lkml?line=55
================ thelook_cicd/users/california_users_is_accurate ===============
Assertion "count_is_expected_value" failed: expression evaluated to "No".
LookML: https://gcpl2318.cloud.looker.com/projects/thelook_cicd/files/thelook_cicd.model.lkml?line=55
Completed data test validation in 14 seconds.
Estabilidade de links para Looks e dashboards
Por padrão, as análises e os painéis recebem IDs numéricos ascendentes que são usados no URL da análise ou do painel. No entanto, não há como manter esses dados sincronizados em todos os sistemas. Portanto, um URL de um painel específico em desenvolvimento não vai apontar para o mesmo painel em controle de qualidade ou produção.
Para UDDs, há uma opção de usar um slug em vez de um ID como parte do URL. O slug é um conjunto de caracteres semialeatório, e não um número. O slug pode ser definido como parte da importação para que um URL semelhante possa apontar para o mesmo UDD em desenvolvimento, controle de qualidade e produção. Usar slugs em vez de IDs é uma prática recomendada, principalmente ao clicar em uma UDD no Look ou em outra UDD.
Para encontrar o slug, inspecione a saída de gzr dashboard cat. O slug pode ser usado no URL do painel no lugar do ID numérico.
Migrar conteúdo do usuário com o Gazer
Copiar conteúdo, como aparências e painéis, entre o desenvolvimento, o controle de qualidade e a produção costuma ser útil. Talvez você queira produzir conteúdo que mostre novas adições do LookML ou verificar se o conteúdo salvo ainda funciona corretamente após as mudanças no LookML. Nessas situações, o Gazer pode ser usado para copiar conteúdo entre instâncias.
Dashboards do LookML
Os dashboards do LookML são sincronizados entre instâncias durante o fluxo de trabalho regular de CI/CD do LookML. No entanto, se algum UDD estiver sincronizado com painéis do LookML, ele poderá ser atualizado com o Gazer usando o seguinte comando:
gzr dashboard sync_lookml DASHBOARD_ID --host TARGET_SYSTEM_URL
Painéis definidos pelo usuário
Os painéis definidos pelo usuário (UDDs, na sigla em inglês) podem ser migrados com o Gazer fazendo referência ao ID do painel e ao URL da instância do Looker em que o UDD reside. O Gazer salva a configuração do painel em um arquivo JSON, que é importado para a instância de destino do Looker.
O comando para extrair a configuração do UDD é o seguinte:
gzr dashboard cat DASHBOARD_ID --host TARGET_SYSTEM_URL --dir .
Isso vai gerar um arquivo chamado Dashboard_DASHBOARD_ID_DASHBOARD_NAME.json que contém a configuração do painel.
O UDD pode ser importado para o sistema de destino usando o seguinte comando:
gzr dashboard import Dashboard_DASHBOARD_ID_DASHBOARD_NAME.json FOLDER_ID \
--host TARGET_SYSTEM_URL
Looks
A migração de pesquisas funciona de maneira muito semelhante à migração de UDD. Primeiro, use o Gazer para salvar a configuração do Look em um arquivo JSON:
gzr look cat LOOK_ID --host SOURCE_SYSTEM_URL --dir .
Em seguida, importe o Look para a instância de destino:
gzr look import Look_LOOK_ID_LOOK_NAME.json FOLDER_ID \
--host TARGET_SYSTEM_URL