Esta página explica 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 camadas 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. É 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.
Visão geral do fluxo de trabalho
Os desenvolvedores do LookML começam escrevendo o código na ramificação de desenvolvimento, que normalmente é chamada de dev-my-user-ydnv, testam as mudanças com o Spectacles e confirmam o 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 significativo para a solicitação de pull usando o estilo de confirmação convencional e adicionar um comentário à descrição que será incluída no registro de alterações. Os resultados dos testes dos óculos Spectacles devem ser adicionados como comentários à 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 percebe a mudança.
Automaticamente, a automatização do Release Please vai ser executada e abrir uma segunda PR para criar uma nova versão com tags. Ou, se já houver uma PR aberta para esse fim, o Release Please atualizará essa PR. O comunicado de lançamento tem um número de versão associado e um registro de alterações que inclui os títulos e as descrições das mudanças incluídas.
Quando a solicitação de lançamento gerada pelo Release Please é aprovada e mesclada, uma nova tag de versão é gerada e o registro de mudanças é mesclado com a ramificação main. As instâncias de QA e de 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 confirmações
As versões e as tags associadas podem ser nomeadas e numeradas de qualquer maneira que faça sentido no seu ambiente. No entanto, o controle de versão semântico é usado aqui e é altamente recomendado porque funciona bem com o plug-in Release Please.
No controle de versão semântica, 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- O
MINORé incrementado e oPATCHé redefinido para zero sempre que a versão adiciona ou refina um recurso, sendo compatível com versões anteriores. MAJORé incrementado, eMINORePATCHsão definidos como zero quando um recurso não compatível com versões anteriores é adicionado.
Comit convencional é um sistema de nomeação de confirmações com base no impacto delas nos usuários finais. Embora não seja obrigatório, o uso de nomes de confirmação convencionais também é útil para o plug-in Release Please.
Na nomenclatura convencional de confirmação, cada mensagem de confirmação é precedida por um indicador do escopo da alteração:
- 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 alteração interruptiva é indicado por
feat!:, comofeat!: rewrote sales explore to use the new calendar view. - Quando os documentos são atualizados, mas o LookML não é alterado, a mensagem de confirmação começa com
doc:
Se as confirmações convencionais forem usadas de forma consistente, determinar o número semântico a ser usado em seguida geralmente é simples. Se o registro de confirmação consistir apenas de confirmações fix: e doc:, o PATCH precisará ser incrementado. Se houver uma confirmação feat:, MINOR precisará ser incrementada. Se houver um feat!:, o 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 são feitas e enviadas como uma PR na instância de desenvolvimento, o plug-in Release Please marca as mudanças com uma tag de versão, como v1.2.3. O modo de implantação avançado do Looker disponibiliza essas versões na interface do Looker para as instâncias de controle de qualidade e de 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 Gerenciador de implantações. Em seguida, selecione o menu de três pontos associado à tag que você quer implantar e escolha Implantar no ambiente:
Não é necessário marcar a implantação novamente. Por isso, escolha Implantar sem marcar e clique no botão Implantar no ambiente:
Por fim, envie para produção usando o Deployment Manager.
Como usar os Spectacles
Os óculos 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 um pull request, é recomendável executar esses testes e copiar os resultados para um comentário no pull request.
Validador SQL
O validador SQL testa cada análise para garantir que todos os campos definidos nas visualizações do LookML correspondam a colunas SQL reais ou expressões SQL válidas no banco de dados. O validador 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 garante que as mudanças do LookML sejam válidas e não tenham erros de sintaxe. Ele é chamado da seguinte forma:
$ 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 Validador de conteúdo testa se o conteúdo salvo, como Looks e painéis definidos pelo usuário (UDDs, na sigla em inglês), ainda funciona após as mudanças. Para que o job seja executado mais rápido e gere resultados gerenciáveis, a validação é feita apenas para conteúdo com base nas Análises que você especificar. 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 ato
A validação de afirmação testa as afirmações de dados que você adicionou ao LookML para garantir que os dados sejam lidos corretamente. Por exemplo, um teste de dados no LookML pode ser parecido com este:
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 afirmaçã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 painéis
Por padrão, os looks e painéis recebem IDs numéricos crescentes que são usados no URL do look ou painel. No entanto, não há como manter a sincronização entre 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 semi-aleatório de caracteres, 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 no desenvolvimento, controle de qualidade e produção. É recomendável usar slugs em vez de IDs, principalmente ao clicar em uma UDD de Look ou de outra UDD.
O slug pode ser encontrado inspecionando a saída de gzr dashboard cat. O slug pode ser usado no URL do painel em vez do ID numérico.
Como migrar o conteúdo do usuário com o Gazer
Copiar conteúdo, como Looks e painéis, entre o desenvolvimento, o controle de qualidade e a produção geralmente é útil. Você pode produzir conteúdo que mostre novas adições do LookML ou garantir que o conteúdo salvo ainda funcione corretamente após as mudanças do LookML. Nesses casos, o Gazer pode ser usado para copiar conteúdo entre instâncias.
Dashboards do LookML
Os dashboards do LookML são sincronizados entre as instâncias durante o fluxo de trabalho de CI/CD do LookML. No entanto, se os UDDs forem sincronizados com os painéis do LookML, eles poderão ser atualizados 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 ao referenciar o ID do painel e o URL da instância do Looker em que o UDD está localizado. 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.
A UDD pode ser importada 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 aparência funciona de maneira muito semelhante à migração de UDD. Primeiro, use o Gazer para salvar a configuração do visual 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