Tutorial: Executar um fluxo de trabalho de contentor de vários passos na cloud ao consolidar o código fonte

Além de uma tarefa rápida, o ACR Tasks suporta fluxos de trabalho multi-passos baseados em vários contentores que podem ser acionados automaticamente quando consolida o código fonte num repositório Git.

Neste tutorial, vai aprender a utilizar ficheiros YAML de exemplo para definir tarefas de vários passos que criam, executam e enviam uma ou mais imagens de contentor para um registo quando consolida o código fonte. Para criar uma tarefa que só automatiza uma única compilação de imagem na consolidação de código, veja Tutorial: Automatizar compilações de imagens de contentor na cloud ao consolidar o código fonte. Para obter uma descrição geral das Tarefas do ACR, veja Automatizar a aplicação de patches do SO e da arquitetura com o ACR Tasks,

Neste tutorial:

  • Definir uma tarefa de vários passos com um ficheiro YAML
  • Criar uma tarefa
  • Opcionalmente, adicione credenciais à tarefa para ativar o acesso a outro registo
  • Testar a tarefa
  • Ver estado da tarefa
  • Acionar a tarefa com uma consolidação do código

Este tutorial parte do princípio de que já concluiu os passos no tutorial anterior. Se ainda não o fez, conclua os passos na secção Pré-requisitos do tutorial anterior antes de continuar.

Pré-requisitos

Obter o código de exemplo

Este tutorial parte do princípio de que já concluiu os passos no tutorial anterior e já bifurcou e clonou o repositório de exemplo. Se ainda não o fez, conclua os passos na secção Pré-requisitos do tutorial anterior antes de continuar.

Registo de contentor

Para concluir este tutorial tem de ter um registo de contentor do Azure na sua subscrição do Azure. Se precisar de um registo, veja o tutorial anterior ou Início Rápido: Criar um registo de contentor com a CLI do Azure.

Criar um token de acesso pessoal do GitHub

Para acionar uma tarefa numa consolidação para um repositório Git, as Tarefas do ACR precisam de um token de acesso pessoal (PAT) para aceder ao repositório. Se ainda não tiver um PAT, siga estes passos para gerar um no GitHub:

  1. Navegue para a página de criação do PAT no GitHub em https://github.com/settings/tokens/new

  2. Escrever uma descrição breve para o token, por exemplo, "Demonstração do ACR Tasks"

  3. Selecione âmbitos para o ACR aceder ao repositório. Para aceder a um repositório público como neste tutorial, em repositório, ative repo:status e public_repo

    Captura de ecrã da página de geração do Token de Acesso Pessoal no GitHub

    Nota

    Para gerar um PAT para aceder a um repositório privado , selecione o âmbito do controlo de repositório completo.

  4. Selecione o botão Gerar token (poderá ser-lhe pedido para confirmar a palavra-passe)

  5. Copie e guarde o token gerado numa localização segura (irá utilizar este token na definição de uma tarefa de compilação na secção seguinte)

    Captura de ecrã do Token de Acesso Pessoal gerado no GitHub

Prepare o seu ambiente para o CLI do Azure

Criar uma tarefa com vários passos

Agora que concluiu os passos necessários para permitir que o ACR Tasks leia o estado de consolidação e crie webhooks num repositório, crie uma tarefa de vários passos que acione a criação, execução e em envio de uma imagem de contentor.

Ficheiro YAML

Define os passos para uma tarefa de vários passos num ficheiro YAML. A primeira tarefa de vários passos de exemplo para este tutorial é definida no ficheiro taskmulti.yaml, que está na raiz do repositório do GitHub que clonou:

version: v1.1.0
steps:
# Build target image
- build: -t {{.Run.Registry}}/hello-world:{{.Run.ID}} -f Dockerfile .
# Run image 
- cmd: -t {{.Run.Registry}}/hello-world:{{.Run.ID}}
  id: test
  detach: true
  ports: ["8080:80"]
- cmd: docker stop test
# Push image
- push:
  - {{.Run.Registry}}/hello-world:{{.Run.ID}}

Esta tarefa de vários passos faz o seguinte:

  1. Executa um build passo para criar uma imagem a partir do Dockerfile no diretório de trabalho. A imagem destina-se a , o Run.Registryregisto onde a tarefa é executada e é etiquetada com um ID de execução exclusivo do ACR Tasks.
  2. Executa um cmd passo para executar a imagem num contentor temporário. Este exemplo inicia um contentor de execução prolongada em segundo plano e devolve o ID de contentor e, em seguida, para o contentor. Num cenário real, pode incluir passos para testar o contentor em execução para garantir que é executado corretamente.
  3. Num push passo, envia a imagem que foi criada para o registo de execução.

Comando Tarefa

Em primeiro lugar, preencha estas variáveis de ambiente da shell com os valores adequados para o seu ambiente. Este passo não é estritamente necessário, mas facilita um pouco a execução dos comandos da CLI do Azure com várias linhas neste tutorial. Se não preencher estas variáveis de ambiente, tem de substituir manualmente cada valor onde for apresentado nos comandos de exemplo.

ACR_NAME=<registry-name>        # The name of your Azure container registry
GIT_USER=<github-username>      # Your GitHub user account name
GIT_PAT=<personal-access-token> # The PAT you generated in the previous section

Agora, crie a tarefa ao executar o seguinte comando az acr task create :

az acr task create \
    --registry $ACR_NAME \
    --name example1 \
    --context https://github.com/$GIT_USER/acr-build-helloworld-node.git#main \
    --file taskmulti.yaml \
    --git-access-token $GIT_PAT

Esta tarefa especifica que, sempre que o código for consolidado no ramo principal no repositório especificado pelo --context, o ACR Tasks executará a tarefa de vários passos a partir do código nesse ramo. O ficheiro YAML especificado pela --file raiz do repositório define os passos.

O resultado de um comando az acr task create com êxito é semelhante ao seguinte:

{
  "agentConfiguration": {
    "cpu": 2
  },
  "creationDate": "2020-11-20T03:14:31.763887+00:00",
  "credentials": null,
  "id": "/subscriptions/<Subscription ID>/resourceGroups/myregistry/providers/Microsoft.ContainerRegistry/registries/myregistry/tasks/taskmulti",
  "location": "westus",
  "name": "example1",
  "platform": {
    "architecture": "amd64",
    "os": "linux",
    "variant": null
  },
  "provisioningState": "Succeeded",
  "resourceGroup": "myresourcegroup",
  "status": "Enabled",
  "step": {
    "baseImageDependencies": null,
    "contextAccessToken": null,
    "contextPath": "https://github.com/gituser/acr-build-helloworld-node.git#main",
    "taskFilePath": "taskmulti.yaml",
    "type": "FileTask",
    "values": [],
    "valuesFilePath": null
  },
  "tags": null,
  "timeout": 3600,
  "trigger": {
    "baseImageTrigger": {
      "baseImageTriggerType": "Runtime",
      "name": "defaultBaseimageTriggerName",
      "status": "Enabled"
    },
    "sourceTriggers": [
      {
        "name": "defaultSourceTriggerName",
        "sourceRepository": {
          "branch": "main",
          "repositoryUrl": "https://github.com/gituser/acr-build-helloworld-node.git#main",
          "sourceControlAuthProperties": null,
          "sourceControlType": "Github"
        },
        "sourceTriggerEvents": [
          "commit"
        ],
        "status": "Enabled"
      }
    ]
  },
  "type": "Microsoft.ContainerRegistry/registries/tasks"
}

Testar o fluxo de trabalho de vários passos

Para testar a tarefa de vários passos, acione-a manualmente ao executar o comando az acr task run :

az acr task run --registry $ACR_NAME --name example1

Por predefinição, o comando az acr task run transmite a saída de registo para a consola quando executar o comando. O resultado mostra o progresso da execução de cada um dos passos da tarefa. A saída abaixo é condensada para mostrar os passos principais.

Queued a run with ID: cab
Waiting for an agent...
2020/11/20 00:03:31 Downloading source code...
2020/11/20 00:03:33 Finished downloading source code
2020/11/20 00:03:33 Using acb_vol_cfe6bd55-3076-4215-8091-6a81aec3d1b1 as the home volume
2020/11/20 00:03:33 Creating Docker network: acb_default_network, driver: 'bridge'
2020/11/20 00:03:34 Successfully set up Docker network: acb_default_network
2020/11/20 00:03:34 Setting up Docker configuration...
2020/11/20 00:03:34 Successfully set up Docker configuration
2020/11/20 00:03:34 Logging in to registry: myregistry.azurecr.io
2020/11/20 00:03:35 Successfully logged into myregistry.azurecr.io
2020/11/20 00:03:35 Executing step ID: acb_step_0. Working directory: '', Network: 'acb_default_network'
2020/11/20 00:03:35 Scanning for dependencies...
2020/11/20 00:03:36 Successfully scanned dependencies
2020/11/20 00:03:36 Launching container with name: acb_step_0
Sending build context to Docker daemon  24.06kB
[...]
Successfully built f669bfd170af
Successfully tagged myregistry.azurecr.io/hello-world:cf19
2020/11/20 00:03:43 Successfully executed container: acb_step_0
2020/11/20 00:03:43 Executing step ID: acb_step_1. Working directory: '', Network: 'acb_default_network'
2020/11/20 00:03:43 Launching container with name: acb_step_1
279b1cb6e092b64c8517c5506fcb45494cd5a0bd10a6beca3ba97f25c5d940cd
2020/11/20 00:03:44 Successfully executed container: acb_step_1
2020/11/20 00:03:44 Executing step ID: acb_step_2. Working directory: '', Network: 'acb_default_network'
2020/11/20 00:03:44 Pushing image: myregistry.azurecr.io/hello-world:cf19, attempt 1
[...]
2020/11/20 00:03:46 Successfully pushed image: myregistry.azurecr.io/hello-world:cf19
2020/11/20 00:03:46 Step ID: acb_step_0 marked as successful (elapsed time in seconds: 7.425169)
2020/11/20 00:03:46 Populating digests for step ID: acb_step_0...
2020/11/20 00:03:47 Successfully populated digests for step ID: acb_step_0
2020/11/20 00:03:47 Step ID: acb_step_1 marked as successful (elapsed time in seconds: 0.827129)
2020/11/20 00:03:47 Step ID: acb_step_2 marked as successful (elapsed time in seconds: 2.112113)
2020/11/20 00:03:47 The following dependencies were found:
2020/11/20 00:03:47
- image:
    registry: myregistry.azurecr.io
    repository: hello-world
    tag: cf19
    digest: sha256:6b981a8ca8596e840228c974c929db05c0727d8630465de536be74104693467a
  runtime-dependency:
    registry: registry.hub.docker.com
    repository: library/node
    tag: 15-alpine
    digest: sha256:8dafc0968fb4d62834d9b826d85a8feecc69bd72cd51723c62c7db67c6dec6fa
  git:
    git-head-revision: 1a3065388a0238e52865db1c8f3e97492a43444c

Run ID: cab was successful after 18s

Acionar uma compilação com uma consolidação

Agora que testou a tarefa através de uma execução manual, acione-a automaticamente com uma alteração do código de origem.

Em primeiro lugar, confirme que está no diretório que contém o clone local do repositório:

cd acr-build-helloworld-node

Em seguida, execute os comandos seguintes para criar, consolidar e emitir um novo ficheiro para a bifurcação do repositório no GitHub:

echo "Hello World!" > hello.txt
git add hello.txt
git commit -m "Testing ACR Tasks"
git push origin main

Poderá ser-lhe pedido para fornecer as credenciais do GitHub, quando executar o comando git push. Forneça o seu nome de utilizador do GitHub e introduza o token de acesso pessoal (PAT) que criou anteriormente para a palavra-passe.

Username for 'https://github.com': <github-username>
Password for 'https://githubuser@github.com': <personal-access-token>

Depois de emitir uma consolidação para o seu repositório, o webhook criado pelo ACR Tasks é acionado e inicia a tarefa no Azure Container Registry. Apresente os registos da compilação atualmente em execução para verificar e monitorizar o progresso da mesma:

az acr task logs --registry $ACR_NAME

O resultado é semelhante ao seguinte, apresentando a compilação atualmente em execução (ou a última executada):

Showing logs of the last created run.
Run ID: cad

[...]

Run ID: cad was successful after 37s

Listar as compilações

Para ver uma lista das execuções de tarefas que o ACR Tasks concluiu para o seu registo, execute o comando az acr task list-runs:

az acr task list-runs --registry $ACR_NAME --output table

O resultado do comando deve ter um aspeto semelhante ao que se segue. As execuções do ACR Tasks são apresentadas e “Consolidação de Git” aparece na coluna ACIONAR da tarefa mais recente:

RUN ID    TASK            PLATFORM    STATUS     TRIGGER    STARTED               DURATION
--------  --------------  ----------  ---------  ---------  --------------------  ----------
cad       example1        linux       Succeeded  Commit     2020-11-20T00:22:15Z  00:00:35
cac       taskhelloworld  linux       Succeeded  Commit     2020-11-20T00:22:15Z  00:00:22
cab       example1        linux       Succeeded  Manual     2020-11-20T00:18:36Z  00:00:47

Criar uma tarefa com vários passos de registo

Por predefinição, o ACR Tasks tem permissões para emitir ou extrair imagens do registo onde a tarefa é executada. Poderá querer executar uma tarefa de vários passos que visa um ou mais registos, além do registo de execução. Por exemplo, poderá ter de criar imagens num registo e armazenar imagens com etiquetas diferentes num segundo registo que é acedido por um sistema de produção. Este exemplo mostra-lhe como criar essa tarefa e fornecer credenciais para outro registo.

Se ainda não tiver um segundo registo, crie um para este exemplo. Se precisar de um registo, veja o tutorial anterior ou Início Rápido: Criar um registo de contentor com a CLI do Azure.

Para criar a tarefa, precisa do nome do servidor de início de sessão do registo, que é do formulário mycontainerregistrydate.azurecr.io (todas em minúsculas). Neste exemplo, vai utilizar o segundo registo para armazenar imagens marcadas pela data de compilação.

Ficheiro YAML

A segunda tarefa de vários passos de exemplo para este tutorial é definida no ficheiro taskmulti-multiregistry.yaml, que está na raiz do repositório do GitHub que clonou:

version: v1.1.0
steps:
# Build target images
- build: -t {{.Run.Registry}}/hello-world:{{.Run.ID}} -f Dockerfile .
- build: -t {{.Values.regDate}}/hello-world:{{.Run.Date}} -f Dockerfile .
# Run image 
- cmd: -t {{.Run.Registry}}/hello-world:{{.Run.ID}}
  id: test
  detach: true
  ports: ["8080:80"]
- cmd: docker stop test
# Push images
- push:
  - {{.Run.Registry}}/hello-world:{{.Run.ID}}
  - {{.Values.regDate}}/hello-world:{{.Run.Date}}

Esta tarefa de vários passos faz o seguinte:

  1. Executa dois build passos para criar imagens a partir do Dockerfile no diretório de trabalho:
    • O primeiro destina-se ao Run.Registry, o registo onde a tarefa é executada e está marcado com o ID de execução das Tarefas do ACR.
    • O segundo destina-se ao registo identificado pelo valor de regDate, que definiu quando cria a tarefa (ou fornece através de um ficheiro externo values.yaml transmitido para az acr task create). Esta imagem está marcada com a data de execução.
  2. Executa um cmd passo para executar um dos contentores criados. Este exemplo inicia um contentor de execução prolongada em segundo plano e devolve o ID do contentor e, em seguida, para o contentor. Num cenário real, pode testar um contentor em execução para garantir que é executado corretamente.
  3. Num push passo, envia as imagens que foram criadas, a primeira para o registo de execução, a segunda para o registo identificado por regDate.

Comando tarefa

Com as variáveis de ambiente de shell definidas anteriormente, crie a tarefa ao executar o seguinte comando az acr task create . Substitua o nome do seu registo por mycontainerregistrydate.

az acr task create \
    --registry $ACR_NAME \
    --name example2 \
    --context https://github.com/$GIT_USER/acr-build-helloworld-node.git#main \
    --file taskmulti-multiregistry.yaml \
    --git-access-token $GIT_PAT \
    --set regDate=mycontainerregistrydate.azurecr.io

Adicionar credencial de tarefa

Para enviar imagens para o registo identificado pelo valor de regDate, utilize o comando az acr task credential add para adicionar credenciais de início de sessão para esse registo à tarefa.

Para este exemplo, recomendamos que crie um principal de serviço com acesso ao registo no âmbito da função AcrPush , para que tenha permissões para emitir imagens. Para criar o principal de serviço, utilize o seguinte script:

#!/bin/bash
# This script requires Azure CLI version 2.25.0 or later. Check version with `az --version`.

# Modify for your environment.
# ACR_NAME: The name of your Azure Container Registry
# SERVICE_PRINCIPAL_NAME: Must be unique within your AD tenant
ACR_NAME=$containerRegistry
SERVICE_PRINCIPAL_NAME=$servicePrincipal

# Obtain the full registry ID
ACR_REGISTRY_ID=$(az acr show --name $ACR_NAME --query "id" --output tsv)
# echo $registryId

# Create the service principal with rights scoped to the registry.
# Default permissions are for docker pull access. Modify the '--role'
# argument value as desired:
# acrpull:     pull only
# acrpush:     push and pull
# owner:       push, pull, and assign roles
PASSWORD=$(az ad sp create-for-rbac --name $SERVICE_PRINCIPAL_NAME --scopes $ACR_REGISTRY_ID --role acrpull --query "password" --output tsv)
USER_NAME=$(az ad sp list --display-name $SERVICE_PRINCIPAL_NAME --query "[].appId" --output tsv)

# Output the service principal's credentials; use these in your services and
# applications to authenticate to the container registry.
echo "Service principal ID: $USER_NAME"
echo "Service principal password: $PASSWORD"

Transmita o ID da aplicação do principal de serviço e a palavra-passe no seguinte az acr task credential add comando. Certifique-se de que atualiza o nome do servidor de início de sessão mycontainerregistrydate com o nome do segundo registo:

az acr task credential add --name example2 \
    --registry $ACR_NAME \
    --login-server mycontainerregistrydate.azurecr.io \
    --username <service-principal-application-id> \
    --password <service-principal-password>

A CLI devolve o nome do servidor de início de sessão do registo que adicionou.

Testar o fluxo de trabalho de vários passos

Tal como no exemplo anterior, para testar a tarefa de vários passos, acione-a manualmente ao executar o comando az acr task run . Para acionar a tarefa com uma consolidação para o repositório Git, veja a secção Acionar uma compilação com uma consolidação.

az acr task run --registry $ACR_NAME --name example2

Por predefinição, o comando az acr task run transmite a saída de registo para a consola quando executar o comando. Tal como anteriormente, o resultado mostra o progresso da execução de cada um dos passos da tarefa. A saída é condensada para mostrar os passos principais.

Resultado:

Queued a run with ID: cf1g
Waiting for an agent...
2020/11/20 04:33:39 Downloading source code...
2020/11/20 04:33:41 Finished downloading source code
2020/11/20 04:33:42 Using acb_vol_4569b017-29fe-42bd-83b2-25c45a8ac807 as the home volume
2020/11/20 04:33:42 Creating Docker network: acb_default_network, driver: 'bridge'
2020/11/20 04:33:43 Successfully set up Docker network: acb_default_network
2020/11/20 04:33:43 Setting up Docker configuration...
2020/11/20 04:33:44 Successfully set up Docker configuration
2020/11/20 04:33:44 Logging in to registry: mycontainerregistry.azurecr.io
2020/11/20 04:33:45 Successfully logged into mycontainerregistry.azurecr.io
2020/11/20 04:33:45 Logging in to registry: mycontainerregistrydate.azurecr.io
2020/11/20 04:33:47 Successfully logged into mycontainerregistrydate.azurecr.io
2020/11/20 04:33:47 Executing step ID: acb_step_0. Working directory: '', Network: 'acb_default_network'
2020/11/20 04:33:47 Scanning for dependencies...
2020/11/20 04:33:47 Successfully scanned dependencies
2020/11/20 04:33:47 Launching container with name: acb_step_0
Sending build context to Docker daemon  25.09kB
[...]
Successfully tagged mycontainerregistry.azurecr.io/hello-world:cf1g
2020/11/20 04:33:55 Successfully executed container: acb_step_0
2020/11/20 04:33:55 Executing step ID: acb_step_1. Working directory: '', Network: 'acb_default_network'
2020/11/20 04:33:55 Scanning for dependencies...
2020/11/20 04:33:56 Successfully scanned dependencies
2020/11/20 04:33:56 Launching container with name: acb_step_1
Sending build context to Docker daemon  25.09kB
[...]
Successfully tagged mycontainerregistrydate.azurecr.io/hello-world:20190503-043342z
2020/11/20 04:33:57 Successfully executed container: acb_step_1
2020/11/20 04:33:57 Executing step ID: acb_step_2. Working directory: '', Network: 'acb_default_network'
2020/11/20 04:33:57 Launching container with name: acb_step_2
721437ff674051b6be63cbcd2fa8eb085eacbf38d7d632f1a079320133182101
2020/11/20 04:33:58 Successfully executed container: acb_step_2
2020/11/20 04:33:58 Executing step ID: acb_step_3. Working directory: '', Network: 'acb_default_network'
2020/11/20 04:33:58 Launching container with name: acb_step_3
test
2020/11/20 04:34:09 Successfully executed container: acb_step_3
2020/11/20 04:34:09 Executing step ID: acb_step_4. Working directory: '', Network: 'acb_default_network'
2020/11/20 04:34:09 Pushing image: mycontainerregistry.azurecr.io/hello-world:cf1g, attempt 1
The push refers to repository [mycontainerregistry.azurecr.io/hello-world]
[...]
2020/11/20 04:34:12 Successfully pushed image: mycontainerregistry.azurecr.io/hello-world:cf1g
2020/11/20 04:34:12 Pushing image: mycontainerregistrydate.azurecr.io/hello-world:20190503-043342z, attempt 1
The push refers to repository [mycontainerregistrydate.azurecr.io/hello-world]
[...]
2020/11/20 04:34:19 Successfully pushed image: mycontainerregistrydate.azurecr.io/hello-world:20190503-043342z
2020/11/20 04:34:19 Step ID: acb_step_0 marked as successful (elapsed time in seconds: 8.125744)
2020/11/20 04:34:19 Populating digests for step ID: acb_step_0...
2020/11/20 04:34:21 Successfully populated digests for step ID: acb_step_0
2020/11/20 04:34:21 Step ID: acb_step_1 marked as successful (elapsed time in seconds: 2.009281)
2020/11/20 04:34:21 Populating digests for step ID: acb_step_1...
2020/11/20 04:34:23 Successfully populated digests for step ID: acb_step_1
2020/11/20 04:34:23 Step ID: acb_step_2 marked as successful (elapsed time in seconds: 0.795440)
2020/11/20 04:34:23 Step ID: acb_step_3 marked as successful (elapsed time in seconds: 11.446775)
2020/11/20 04:34:23 Step ID: acb_step_4 marked as successful (elapsed time in seconds: 9.734973)
2020/11/20 04:34:23 The following dependencies were found:
2020/11/20 04:34:23
- image:
    registry: mycontainerregistry.azurecr.io
    repository: hello-world
    tag: cf1g
    digest: sha256:75354e9edb995e8661438bad9913deed87a185fddd0193811f916d684b71a5d2
  runtime-dependency:
    registry: registry.hub.docker.com
    repository: library/node
    tag: 15-alpine
    digest: sha256:8dafc0968fb4d62834d9b826d85a8feecc69bd72cd51723c62c7db67c6dec6fa
  git:
    git-head-revision: 9d9023473c46a5e2c315681b11eb4552ef0faccc
- image:
    registry: mycontainerregistrydate.azurecr.io
    repository: hello-world
    tag: 20190503-043342z
    digest: sha256:75354e9edb995e8661438bad9913deed87a185fddd0193811f916d684b71a5d2
  runtime-dependency:
    registry: registry.hub.docker.com
    repository: library/node
    tag: 15-alpine
    digest: sha256:8dafc0968fb4d62834d9b826d85a8feecc69bd72cd51723c62c7db67c6dec6fa
  git:
    git-head-revision: 9d9023473c46a5e2c315681b11eb4552ef0faccc

Run ID: cf1g was successful after 46s

Passos seguintes

Neste tutorial, aprendeu a criar tarefas baseadas em vários passos e em vários contentores que acionam automaticamente quando consolida código fonte num repositório Git. Para obter funcionalidades avançadas de tarefas de vários passos, incluindo a execução de passos paralelos e dependentes, veja a referência YAML das Tarefas do ACR. Avance para o tutorial seguinte para saber como criar tarefas que acionam compilações quando a imagem de base de uma imagem do contentor é atualizada.