Utilização e fluxo de trabalho de CI/CD do Looker

Esta página explica como usar um fluxo de trabalho de CI/CD no Looker depois de esse fluxo de trabalho ter sido instalado e configurado.

Estas instruções usam um sistema de três níveis que inclui desenvolvimento, controlo de qualidade e produção. No entanto, pode aplicar os mesmos princípios a um sistema de dois ou quatro níveis.

Estas instruções também pressupõem a utilização do GitHub como fornecedor de Git. Pode usar outros fornecedores do Git para criar um fluxo de trabalho de CI/CD. No entanto, tem de ter conhecimentos para modificar estas instruções para o seu fornecedor.

Vista geral do fluxo de trabalho

Os programadores de LookML começam por escrever código na respetiva ramificação de desenvolvimento, que normalmente tem um nome como dev-my-user-ydnv, testam as alterações com o Spectacles e confirmam o código. Por fim, abrem um pedido de envio para unir o respetivo código ao ramo main.

Quando o pedido de obtenção é aberto, o programador é direcionado para o GitHub. O programador deve escrever um título de PR significativo usando o estilo de commits convencionais e adicionar um comentário à descrição que será incluído no registo de alterações. Os resultados dos testes dos Spectacles devem ser adicionados como comentários ao PR.

Em seguida, o programador deve selecionar um revisor no GitHub. O revisor recebe uma notificação e pode adicionar a respetiva revisão ao PR. Se o revisor aprovar a alteração, o PR é sincronizado com a ramificação main. É chamado um WebHook e o ambiente de desenvolvimento vê agora a alteração.

Automaticamente, a automatização Release Please é executada e abre um segundo pedido de envio para criar um novo lançamento etiquetado. Em alternativa, se já existir um PR aberto para este fim, o Release Please atualiza esse PR. O PR de lançamento tem um número de versão associado, bem como um registo de alterações que inclui os títulos e as descrições das alterações incluídas.

Quando o PR gerado pelo Release Please é aprovado e unido, é gerada uma nova etiqueta de versão e o registo de alterações é unido com o ramo main. As instâncias de controlo de qualidade e de produção do Looker podem selecionar esta versão através do Modo de implementação avançado.

Práticas recomendadas para numerar lançamentos e atribuir nomes a commits

Pode atribuir nomes e números às versões e às respetivas etiquetas associadas da forma que fizer sentido no seu ambiente. No entanto, aqui é usada a versão semântica, que é altamente recomendada porque funciona bem com o plug-in Release Please.

Na versão semântica, a versão consiste em três números separados por pontos: MAJOR.MINOR.PATCH

  • PATCH é incrementado sempre que um lançamento corrige um erro
  • MINOR é incrementado e PATCH é reposto a zero sempre que a versão adiciona ou refina uma funcionalidade, mantendo a compatibilidade com versões anteriores
  • MAJOR é incrementado e MINOR e PATCH são definidos como zero quando é adicionada uma funcionalidade não compatível com versões anteriores

O Conventional Commits é um sistema de atribuição de nomes aos commits pelo impacto que têm nos utilizadores finais. Embora não seja obrigatório, a utilização de nomes de commits convencionais também é útil para o plugin Release Please.

Na nomenclatura de commits convencional, cada mensagem de commit é precedida de um indicador do âmbito da alteração:

  • Uma correção de erro é indicada com fix:, como fix: set proper currency symbol on sale_amt format
  • Uma nova funcionalidade é indicada com feat:, como feat: added explore for sales by territory
  • Uma funcionalidade com uma alteração interruptiva é indicada por feat!:, como feat!: 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 usar a seguir é geralmente simples. Se o registo de confirmação consistir apenas em confirmações fix: e doc:, o valor de PATCH deve ser incrementado. Se existir um compromisso feat:, MINOR deve ser incrementado. Se existir um feat!:, o valor de MAJOR deve ser incrementado. O plugin Release Please pode até gerar um ficheiro CHANGELOG e etiquetar a versão automaticamente.

Usar o modo de implementação avançado

Depois de as alterações serem feitas e enviadas como um PR na instância de desenvolvimento, o plug-in Release Please etiqueta as alterações com uma etiqueta de versão, como v1.2.3. O Modo de implementação avançado do Looker disponibiliza estas versões na IU do Looker para as instâncias de controlo de qualidade e de produção.

Para implementar uma alteração, escolha o Gestor de implementação no IDE do Looker:

Localização do Deployment Manager do Looker no IDE.

Clique no link Selecionar confirmação na parte superior direita do Gestor de Implementações. Em seguida, selecione o menu de três pontos associado à etiqueta que quer implementar e escolha Implementar no ambiente:

IU do Deployment Manager do Looker para implementação no ambiente.

Não precisa de etiquetar a implementação novamente. Por isso, escolha Implementar sem etiquetar e prima o botão Implementar no ambiente:

Interface do utilizador do Deployment Manager do Looker para implementação sem etiquetagem.

Por último, implemente em produção através do Gestor de Implementações.

Usar os Spectacles

Os Spectacles podem ser usados por cada programador para validar as respetivas alterações enquanto ainda estão na respetiva ramificação de desenvolvimento. O Spectacles oferece quatro validadores diferentes:

Quando um programador envia um pedido de obtenção, é recomendável executar estes testes e copiar os resultados para um comentário no PR.

Validação de SQL

A validação de SQL testa cada exploração para verificar se todos os campos definidos nas vistas do LookML correspondem a colunas SQL reais ou expressões SQL válidas na base 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

Por 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.

Validação de LookML

O validador do LookML verifica se as alterações do LookML são válidas e não têm erros de sintaxe. É chamado conforme mostrado a seguir:

$ spectacles lookml --config-file config-dev.yaml \
    --project PROJECT_NAME \
    --branch DEV_BRANCH_NAME

Por 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.

Validação de conteúdo

O validador de conteúdo testa se qualquer conteúdo guardado, como visuais e painéis de controlo definidos pelo utilizador (UDDs), continua a funcionar após a realização de alterações. Para que a tarefa seja executada mais rapidamente e sejam apresentados resultados geríveis, a validação é feita apenas para conteúdo baseado nas explorações que especificar. O validador de conteúdo é chamado da seguinte forma:

$ spectacles content --config-file config-dev.yaml \
    --project PROJECT_NAME \
    --explores MODEL_NAME/EXPLORE_NAME \
    --branch DEV_BRANCH_NAME

Por 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 afirmação

A validação de asserções testa as asserções de dados que adicionou ao seu LookML para verificar se os dados estão a ser lidos corretamente. Por exemplo, um teste de dados no seu LookML pode ter o seguinte aspeto:

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ções é chamada conforme mostrado a seguir:

$ spectacles assert --config-file config-dev.yaml \
    --project PROJECT_NAME \
    --explores MODEL_NAME/EXPLORE_NAME \
    --branch DEV_BRANCH_NAME

Por 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.

Por predefinição, os Looks e os painéis de controlo recebem IDs numéricos ascendentes que são usados no URL do Look ou do painel de controlo. No entanto, não existe forma de manter estes dados sincronizados entre sistemas. Por conseguinte, um URL para um painel de controlo específico em desenvolvimento não aponta para o mesmo painel de controlo no controlo de qualidade ou na produção.

Para UDDs, existe uma opção para usar um slug em vez de um ID como parte do URL. O slug é um conjunto de carateres semialeatório em vez de 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, no controlo de qualidade e na produção. A utilização de slugs em vez de IDs é uma prática recomendada, especialmente quando "clica para aceder" a um UDD a partir do Look ou de outro UDD.

Pode encontrar o slug inspecionando o resultado de gzr dashboard cat. O slug pode ser usado no URL do painel de controlo em vez do ID numérico.

Migrar conteúdo do utilizador com o Gazer

Copiar conteúdo, como visuais e painéis de controlo, entre o desenvolvimento, o controlo de qualidade e a produção é frequentemente útil. Pode querer produzir conteúdo que apresente novas adições do LookML ou verificar se o conteúdo guardado continua a funcionar corretamente após as alterações do LookML. Nestas situações, pode usar o Gazer para copiar conteúdo entre instâncias.

Painéis de controlo do LookML

Os painéis de controlo do LookML são sincronizados entre instâncias durante o fluxo de trabalho normal de CI/CD do LookML. No entanto, se alguma UDD estiver sincronizada com painéis de controlo do LookML, pode ser atualizada com o Gazer através do seguinte comando:

gzr dashboard sync_lookml DASHBOARD_ID --host TARGET_SYSTEM_URL

Painéis de controlo definidos pelo utilizador

Os painéis de controlo definidos pelo utilizador (UDDs) podem ser migrados com o Gazer através da referência ao ID do painel de controlo e ao URL da instância do Looker onde o UDD reside. O Gazer guarda a configuração do painel de controlo num ficheiro JSON que é, em seguida, importado para a instância do Looker de destino.

O comando para extrair a configuração da UDD é o seguinte:

gzr dashboard cat DASHBOARD_ID --host TARGET_SYSTEM_URL --dir .

Isto gera um ficheiro denominado Dashboard_DASHBOARD_ID_DASHBOARD_NAME.json que contém a configuração do painel de controlo.

O UDD pode ser importado para o sistema de destino através do seguinte comando:

gzr dashboard import Dashboard_DASHBOARD_ID_DASHBOARD_NAME.json FOLDER_ID \
    --host TARGET_SYSTEM_URL

Looks

A migração de públicos-alvo semelhantes funciona de forma muito semelhante à migração de UDD. Primeiro, use o Gazer para guardar a configuração do Look num ficheiro 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