Configurar um pipeline e enviar atualizações por push

  • Artigo

Neste artigo, você aprenderá a usar a CLI do Desenvolvedor do Azure (azd) para enviar alterações de modelo por push por meio de um pipeline de CI/CD, como GitHub Actions ou Azure DevOps. Para este exemplo, você usará o modelo React Web App com API Node.js e MongoDB no Azure, mas poderá aplicar os princípios aprendidos neste artigo a qualquer um dos modelos da CLI do Desenvolvedor do Azure.

Observação

O comando azd pipeline config ainda está na versão beta. Leia mais sobre o suporte a recursos alfa e beta na página de controle de versão e estratégia de lançamento de recursos.

Pré-requisitos

Os modelos azd podem ou não incluir um arquivo de configuração de pipeline padrão do GitHub Actions e/ou do Azure DevOps chamado azure-dev.yml, que é necessário para configurar o CI/CD. Esse arquivo de configuração provisiona seus recursos do Azure e implanta seu código na ramificação principal. Você pode encontrar azure-dev.yml:

  • Para GitHub Actions: no diretório .github/workflows.
  • Para Azure DevOps: no diretório .azdo/pipelines.

Você pode usar o arquivo de configuração como está ou modificá-lo de acordo com suas necessidades.

Observação

Verifique se o modelo tem uma definição de pipeline (azure-dev.yaml) antes de chamar azd pipeline config. azd não cria automaticamente este arquivo. Consulte Criar uma definição de pipeline para azd abaixo.

Use o comando azd pipeline config para configurar um pipeline de CI/CD, que lida com as seguintes tarefas:

  • Cria e configura uma entidade de serviço para o aplicativo na assinatura do Azure. Seu usuário deve ter a função Owner ou funções Contributor + User Access Administrator na assinatura do Azure para permitir que o azd crie e atribua funções à entidade de serviço.
  • Orienta você por meio de um fluxo de trabalho para criar e configurar um repositório GitHub ou Azure DevOps e confirmar o código do projeto nele. Você também pode optar por usar um repositório existente.
  • Cria uma conexão segura entre o Azure e seu repositório.
  • Executa a ação do GitHub quando você faz check-in do arquivo de fluxo de trabalho.

Para obter um controle mais granular sobre esse processo, ou se o usuário não tiver as funções necessárias, você poderá configurar manualmente um pipeline.

Selecione seu provedor de pipeline preferido para continuar:

Autorizar o GitHub a implantar no Azure

Para configurar o fluxo de trabalho, você precisa autorizar uma entidade de serviço a implantar no Azure em seu nome, de uma ação do GitHub. azd cria a entidade de serviço e uma credencial federada para ela.

  1. Execute o comando a seguir para criar a entidade de serviço do Azure e configurar o pipeline:

    azd pipeline config

    Como opção, esse comando cria um repositório GitHub e envia o código para o novo repositório.

    Observação

    Por padrão, o azd pipeline config usa o OpenID Connect (OIDC), chamado de credenciais federadas. Se você preferir não usar o OIDC, execute azd pipeline config --auth-type client-credentials.

    As credenciais OIDC/federadas não têm suporte no Terraform.

    Saiba mais sobre suporte a OIDC no azd.

  2. Forneça as informações solicitadas do GitHub.

  3. Quando solicitado a confirmar e enviar suas alterações locais para iniciar uma nova execução do GitHub Actions, especifique y.

  4. Na janela do terminal, visualize os resultados do comando azd pipeline config. O comando azd pipeline config produzirá o nome do repositório GitHub para seu projeto.

  5. Usando seu navegador, abra o repositório GitHub do seu projeto.

  6. Selecione Ações para ver o fluxo de trabalho em execução.

    Captura de tela do fluxo de trabalho do GitHub em execução.

Fazer e enviar uma alteração de código

  1. No diretório /src/web/src/layout do projeto, abra header.tsx.

  2. Localize a linha <Text variant="xLarge">ToDo</Text>.

  3. Altere o literal ToDo para myTodo.

  4. Salve o arquivo.

  5. Confirme a alteração. Confirmar a alteração inicia o pipeline de ação do GitHub para implantar a atualização.

    Captura de tela das etapas necessárias para fazer e confirmar a alteração no arquivo de teste.

  6. No navegador, abra o repositório GitHub do seu projeto para ver:

    • Sua confirmação
    • A confirmação do GitHub Actions que está sendo configurado.

    Captura de tela da alteração confirmada no GitHub.

  7. Selecione Ações para ver a atualização de teste refletida no fluxo de trabalho.

    Captura de tela do fluxo de trabalho do GitHub em execução após a atualização do teste.

  8. Visite o URL do front-end da Web para inspecionar a atualização.

azd como uma ação do GitHub

Adicione azd como uma ação do GitHub. Esta ação instalará o azd. Para usar, adicione o seguinte a .github\workflows\azure-dev.yml:

on: [push]

jobs:
   build:
      runs-on: ubuntu-latest
      steps:
         - name: Install azd
         uses: Azure/setup-azd@v0.1.0

Limpar os recursos

Quando não forem mais necessários os recursos do Azure criados neste artigo, execute o comando a seguir:

azd down

Recursos avançados

Você pode estender o comando azd pipeline config para cenários ou requisitos de modelo específicos, conforme descrito nas seções a seguir.

Segredos ou variáveis adicionais

Por padrão, azd define variáveis e segredos para o pipeline. Por exemplo, o comando azd pipeline config cria subscription id, environment name e region como variáveis de pipeline sempre que é executado. Em seguida, a definição do pipeline faz referência a essas variáveis:

env:
   AZURE_CLIENT_ID: ${{ vars.AZURE_CLIENT_ID }}
   AZURE_TENANT_ID: ${{ vars.AZURE_TENANT_ID }}
   AZURE_SUBSCRIPTION_ID: ${{ vars.AZURE_SUBSCRIPTION_ID }}
   AZURE_ENV_NAME: ${{ vars.AZURE_ENV_NAME }}
   AZURE_LOCATION: ${{ vars.AZURE_LOCATION }}

Quando o pipeline é executado, azd obtém os valores do ambiente, que é mapeado para as variáveis e segredos. Dependendo do modelo, pode haver configurações que você pode controlar usando variáveis de ambiente. Por exemplo, uma variável de ambiente chamada KEY_VAULT_NAME pode ser definida para definir o nome de um recurso do Key Vault na infraestrutura do modelo. Nesses casos, a lista de variáveis e segredos pode ser definida pelo modelo, usando o azure.yaml. Por exemplo, considere a seguinte configuração do azure.yaml:

pipeline:
  variables:
    - KEY_VAULT_NAME
    - STORAGE_NAME
  secrets:
    - CONNECTION_STRING

Com essa configuração, azd verifica se alguma das variáveis ou segredos tem um valor não vazio no ambiente. azd cria uma variável ou um segredo para o pipeline usando o nome da chave na configuração como o nome da variável ou do segredo e o valor não string do ambiente para o valor.

A definição do pipeline azure-dev.yaml pode fazer referência às variáveis ou segredos:

- name: Provision Infrastructure
   run: azd provision --no-prompt
   env:
      KEY_VAULT_NAME: ${{ variables.KEY_VAULT_NAME }}
      STORAGE_NAME: ${{ variables.STORAGE_NAME }}
      CONNECTION_STRING: ${{ secrets.CONNECTION_STRING }}

Observação

Você deve executar azd pipeline config depois de atualizar a lista de segredos ou variáveis em azure.yaml para o azd redefinir os valores do pipeline.

Parâmetros de infraestrutura

Considere o seguinte exemplo do bicep:

@secure()
param BlobStorageConnection string

O parâmetro BlobStorageConnection não tem um valor padrão definido, portanto, azd solicita que o usuário insira um valor. No entanto, não há nenhum prompt interativo durante o CI/CD. azd deve solicitar o valor do parâmetro ao executar azd pipeline config, salvar o valor no pipeline e buscar o valor novamente quando o pipeline for executado.

azd usa um segredo de pipeline chamado AZD_INITIAL_ENVIRONMENT_CONFIG para salvar e definir automaticamente o valor de todos os parâmetros necessários no pipeline. Você só precisa fazer referência a esse segredo em seu pipeline:

- name: Provision Infrastructure
   run: azd provision --no-prompt
   env:
      AZD_INITIAL_ENVIRONMENT_CONFIG: ${{ secrets.AZD_INITIAL_ENVIRONMENT_CONFIG }}

Quando o pipeline é executado, azd obtém os valores dos parâmetros do segredo, eliminando a necessidade de um prompt interativo.

Observação

Você deve executar azd pipeline config novamente se adicionar um novo parâmetro.

Criar uma definição de pipeline

Se o modelo azd ainda não tiver um arquivo de definição de pipeline de CI/CD, você poderá criar um por conta própria. Uma definição de pipeline de CI/CD normalmente tem 4 seções principais:

  • gatilho
  • permissões
  • sistema operacional ou pool
  • etapas a serem executadas

Os exemplos a seguir demonstram como criar um arquivo de definição e configurações relacionadas para GitHub Actions e Pipelines do Azure.

A execução azd no GitHub Actions requer as seguintes configurações:

  • Conceda a id-token: write e contents: read acesso a escopos.
  • Instale a ação azd, a menos que você esteja usando uma imagem do docker em que azd já esteja instalado.

Você pode usar o seguinte modelo como ponto de partida para sua própria definição de pipeline:

on:
  workflow_dispatch:
  push:
    # Run when commits are pushed to mainline branch (main or master)
    # Set this to the mainline branch you are using
    branches:
      - main
      - master

# Set this permission if you are using a Federated Credential.
permissions:
  id-token: write
  contents: read

jobs:
  build:
    runs-on: ubuntu-latest
    # azd build-in variables.
    # This variables are always set by `azd pipeline config`
    # You can set them as global env (apply to all steps) or you can add them to individual steps' environment
    env:
      AZURE_CLIENT_ID: ${{ vars.AZURE_CLIENT_ID }}
      AZURE_TENANT_ID: ${{ vars.AZURE_TENANT_ID }}
      AZURE_SUBSCRIPTION_ID: ${{ vars.AZURE_SUBSCRIPTION_ID }}
      AZURE_ENV_NAME: ${{ vars.AZURE_ENV_NAME }}
      AZURE_LOCATION: ${{ vars.AZURE_LOCATION }}
      ## Define the additional variables or secrets that are required globally (provision and deploy)
      # ADDITIONAL_VARIABLE_PLACEHOLDER: ${{ variables.ADDITIONAL_VARIABLE_PLACEHOLDER }}
      # ADDITIONAL_SECRET_PLACEHOLDER: ${{ secrets.ADDITIONAL_SECRET_PLACEHOLDER }}      
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      # using the install-azd action
      - name: Install azd
        uses: Azure/setup-azd@v1.0.0

      # # If you want to use azd-daily build, or install it from a PR, you can remove previous step and
      # # use the next one:
      # - name: Install azd - daily or from PR
      #  # Update this scrip based on the OS - pool of your pipeline. This example is for a linux pipeline installing daily build
      #  run: curl -fsSL https://aka.ms/install-azd.sh | bash -s -- --version daily
      #  shell: pwsh

      # azd set up Federated Credential by default. You can remove this step if you are using Client Credentials
      - name: Log in with Azure (Federated Credentials)
        if: ${{ env.AZURE_CLIENT_ID != '' }}
        run: |
          azd auth login `
            --client-id "$Env:AZURE_CLIENT_ID" `
            --federated-credential-provider "github" `
            --tenant-id "$Env:AZURE_TENANT_ID"
        shell: pwsh

      ## If you set up your pipeline with Client Credentials, remove previous step and uncomment this one
      # - name: Log in with Azure (Client Credentials)
      #   if: ${{ env.AZURE_CREDENTIALS != '' }}
      #   run: |
      #     $info = $Env:AZURE_CREDENTIALS | ConvertFrom-Json -AsHashtable;
      #     Write-Host "::add-mask::$($info.clientSecret)"

      #     azd auth login `
      #       --client-id "$($info.clientId)" `
      #       --client-secret "$($info.clientSecret)" `
      #       --tenant-id "$($info.tenantId)"
      #   shell: pwsh
      #   env:
      #     AZURE_CREDENTIALS: ${{ secrets.AZURE_CREDENTIALS }}

      - name: Provision Infrastructure
        run: azd provision --no-prompt
        env:
         #  # uncomment this if you are using infrastructure parameters
         #  AZD_INITIAL_ENVIRONMENT_CONFIG: ${{ secrets.AZD_INITIAL_ENVIRONMENT_CONFIG }}
         ## Define the additional variables or secrets that are required only for provision 
         #  ADDITIONAL_VARIABLE_PLACEHOLDER: ${{ variables.ADDITIONAL_VARIABLE_PLACEHOLDER }}
         #  ADDITIONAL_SECRET_PLACEHOLDER: ${{ secrets.ADDITIONAL_SECRET_PLACEHOLDER }}

      - name: Deploy Application
        run: azd deploy --no-prompt
        env:
         ## Define the additional variables or secrets that are required only for deploy
         #  ADDITIONAL_VARIABLE_PLACEHOLDER: ${{ variables.ADDITIONAL_VARIABLE_PLACEHOLDER }}
         #  ADDITIONAL_SECRET_PLACEHOLDER: ${{ secrets.ADDITIONAL_SECRET_PLACEHOLDER }}