Referência de tarefas ACR: YAML

A definição de tarefas em várias etapas no ACR Tasks fornece uma primitiva de computação centrada em contêineres focada na criação, teste e aplicação de patches em contêineres. Este artigo aborda os comandos, parâmetros, propriedades e sintaxe para os arquivos YAML que definem suas tarefas de várias etapas.

Este artigo contém referência para criar arquivos YAML de tarefa de várias etapas para tarefas ACR. Se você quiser uma introdução às Tarefas ACR, consulte a Visão geral das Tarefas ACR.

Formato de arquivo acr-task.yaml

ACR Tasks suporta declaração de tarefa de várias etapas na sintaxe YAML padrão. Você define as etapas de uma tarefa em um arquivo YAML. Em seguida, você pode executar a tarefa manualmente passando o arquivo para o comando az acr run . Ou use o arquivo para criar uma tarefa com az acr task create que é acionada automaticamente em uma confirmação do Git, uma atualização de imagem base ou uma agenda. Embora este artigo se refira como acr-task.yaml o arquivo que contém as etapas, ACR Tasks suporta qualquer nome de arquivo válido com uma extensão suportada.

As primitivas de nível acr-task.yaml superior são propriedades de tarefa, tipos de etapa e propriedades de etapa:

• As propriedades da tarefa aplicam-se a todas as etapas durante a execução da tarefa. Há várias propriedades de tarefa global, incluindo:
  • version
  • stepTimeout
  • workingDirectory
• Os tipos de etapa de tarefa representam os tipos de ações que podem ser executadas em uma tarefa. Existem três tipos de passos:
  • build
  • push
  • cmd
• As propriedades da etapa da tarefa são parâmetros que se aplicam a uma etapa individual. Existem várias propriedades de etapa, incluindo:
  • startDelay
  • timeout
  • when
  • ... e muitos mais.

Segue-se o formato base de um acr-task.yaml ficheiro, incluindo algumas propriedades de passos comuns. Embora não seja uma representação exaustiva de todas as propriedades de etapa disponíveis ou uso de tipo de etapa, ele fornece uma visão geral rápida do formato de arquivo básico.

version: # acr-task.yaml format version.
stepTimeout: # Seconds each step may take.
steps: # A collection of image or container actions.
  - build: # Equivalent to "docker build," but in a multi-tenant environment
  - push: # Push a newly built or retagged image to a registry.
    when: # Step property that defines either parallel or dependent step execution.
  - cmd: # Executes a container, supports specifying an [ENTRYPOINT] and parameters.
    startDelay: # Step property that specifies the number of seconds to wait before starting execution.

Extensões de nome de arquivo de tarefa suportadas

ACR Tasks reservou várias extensões de nome de arquivo, incluindo .yaml, que ele processará como um arquivo de tarefa. Qualquer extensão que não esteja na lista a seguir é considerada pelo ACR Tasks como um Dockerfile: .yaml, .yml, .toml, .json, .sh, .bash, .zsh, .ps1, .ps, .cmd, .bat, .ts, .js, .php, .py, .rb, .lua

YAML é o único formato de arquivo atualmente suportado pelo ACR Tasks. As outras extensões de nome de arquivo são reservadas para possível suporte futuro.

Executar as tarefas de exemplo

Há vários arquivos de tarefa de exemplo referenciados nas seções a seguir deste artigo. As tarefas de exemplo estão em um repositório público do GitHub, Azure-Samples/acr-tasks. Você pode executá-los com o comando az acr run da CLI do Azure. Os comandos de exemplo são semelhantes a:

az acr run -f build-push-hello-world.yaml https://github.com/Azure-Samples/acr-tasks.git

A formatação dos comandos de exemplo pressupõe que você tenha configurado um registro padrão na CLI do Azure, portanto, eles omitem o --registry parâmetro. Para configurar um registro padrão, use o comando az config com o set comando, que aceita um par de defaults.acr=REGISTRY_NAME valores de chave.

Por exemplo, para configurar a CLI do Azure com um registro padrão chamado "myregistry":

az config set defaults.acr=myregistry

Propriedades da tarefa

As propriedades da tarefa normalmente aparecem na parte superior de um acr-task.yaml arquivo e são propriedades globais que se aplicam durante toda a execução das etapas da tarefa. Algumas dessas propriedades globais podem ser substituídas em uma etapa individual.

segredo

O objeto secreto tem as seguintes propriedades.

rede

O objeto de rede tem as seguintes propriedades.

volume

O objeto de volume tem as seguintes propriedades.

Tipos de etapas de tarefas

O ACR Tasks suporta três tipos de passos. Cada tipo de etapa suporta várias propriedades, detalhadas na seção para cada tipo de etapa.

compilação

Crie uma imagem de contêiner. O build tipo de etapa representa um meio seguro e multilocatário de execução docker build na nuvem como uma primitiva de primeira classe.

Sintaxe: build

version: v1.1.0
steps:
  - [build]: -t [imageName]:[tag] -f [Dockerfile] [context]
    [property]: [value]

Execute o comando az acr runpara obter a versão docker.

az acr run -r $ACR_NAME --cmd "docker version" /dev/null

Adicione a variável DOCKER_BUILDKIT=1 de ambiente no arquivo yaml para habilitar buildkit e usar secret com buildkito .

O build tipo de etapa suporta os parâmetros na tabela a seguir. O build tipo de etapa também suporta todas as opções de compilação do comando docker build , como --build-arg definir variáveis de tempo de compilação.

Propriedades: construir

O build tipo de etapa suporta as seguintes propriedades. Encontre detalhes dessas propriedades na seção Propriedades da etapa de tarefa deste artigo.

Exemplos: build

Construir imagem - contexto na raiz

az acr run -f build-hello-world.yaml https://github.com/AzureCR/acr-tasks-sample.git

version: v1.1.0
steps:
  - build: -t $Registry/hello-world -f hello-world.dockerfile .

Construir imagem - contexto no subdiretório

version: v1.1.0
steps:
  - build: -t $Registry/hello-world -f hello-world.dockerfile ./subDirectory

Passagem de variável dinâmica em tarefas ACR

Ao trabalhar com tarefas do Registro de contêiner do Azure (ACR), você pode precisar passar valores diferentes para seu processo de compilação sem alterar a definição da tarefa usando o sinalizador --set com o az acr task run comando.

Exemplo: Definindo a marca de imagem em tempo de execução

Suponha que você tenha uma tarefa ACR definida em um acr-task.yml arquivo com um espaço reservado para a tag de imagem:

steps:
  - build: -t $Registry/hello-world:{{.Values.tag}}

Você pode disparar a tarefa e definir a tag variável como v2 em tempo de execução usando o seguinte comando da CLI do Azure:

az acr task run --registry myregistry --name mytask --set tag=v2

Este comando iniciará a tarefa ACR nomeada mytask e construirá a imagem usando a v2 tag , substituindo o espaço reservado no acr-task.yml arquivo.

Essa abordagem permite a personalização em seus pipelines de CI/CD, permitindo que você ajuste dinamicamente os parâmetros com base em suas necessidades atuais sem alterar as definições de tarefas.

emitir

Envie uma ou mais imagens criadas ou remarcadas para um registro de contêiner. Dá suporte ao envio por push para registros privados, como o Registro de Contêiner do Azure, ou para o Docker Hub, público.

Sintaxe: push

O push tipo de etapa suporta uma coleção de imagens. A sintaxe da coleção YAML suporta formatos embutidos e aninhados. O envio por push de uma única imagem é normalmente representado usando sintaxe embutida:

version: v1.1.0
steps:
  # Inline YAML collection syntax
  - push: ["$Registry/hello-world:$ID"]

Para maior legibilidade, use sintaxe aninhada ao enviar várias imagens:

version: v1.1.0
steps:
  # Nested YAML collection syntax
  - push:
    - $Registry/hello-world:$ID
    - $Registry/hello-world:latest

Propriedades: push

O push tipo de etapa suporta as seguintes propriedades. Encontre detalhes dessas propriedades na seção Propriedades da etapa de tarefa deste artigo.

Exemplos: push

Envie várias imagens por push

az acr run -f build-push-hello-world.yaml https://github.com/Azure-Samples/acr-tasks.git

version: v1.1.0
steps:
  - build: -t $Registry/hello-world:$ID -f hello-world.dockerfile .
  - push: 
    - $Registry/hello-world:$ID

Construir, empurrar e executar

az acr run -f build-run-hello-world.yaml https://github.com/Azure-Samples/acr-tasks.git

version: v1.1.0
steps:
  - build: -t $Registry/hello-world:$ID -f hello-world.dockerfile .
  - push:
    - $Registry/hello-world:$ID
  - cmd: $Registry/hello-world:$ID

CMD

O cmd tipo de etapa executa um contêiner.

Sintaxe: cmd

version: v1.1.0
steps:
  - [cmd]: [containerImage]:[tag (optional)] [cmdParameters to the image]

Propriedades: cmd

O cmd tipo de etapa suporta as seguintes propriedades:

Você pode encontrar detalhes dessas propriedades na seção Propriedades da etapa de tarefa deste artigo.

Exemplos: cmd

Executar imagem hello-world

Este comando executa o hello-world.yaml arquivo de tarefa, que faz referência à imagem hello-world no Docker Hub.

az acr run -f hello-world.yaml https://github.com/Azure-Samples/acr-tasks.git

version: v1.1.0
steps:
  - cmd: mcr.microsoft.com/hello-world

Execute a imagem bash e ecoe "hello world"

Este comando executa o bash-echo.yaml arquivo de tarefa, que faz referência à imagem bash no Docker Hub.

az acr run -f bash-echo.yaml https://github.com/Azure-Samples/acr-tasks.git

version: v1.1.0
steps:
  - cmd: bash echo hello world

Executar tag de imagem bash específica

Para executar uma versão de imagem específica, especifique a tag no cmd.

Este comando executa o bash-echo-3.yaml arquivo de tarefa, que faz referência à imagem bash:3.0 no Docker Hub.

az acr run -f bash-echo-3.yaml https://github.com/Azure-Samples/acr-tasks.git

version: v1.1.0
steps:
  - cmd: bash:3.0 echo hello world

Executar imagens personalizadas

O cmd tipo de etapa faz referência a imagens usando o formato padrão docker run . Presume-se que as imagens não precedidas de um registo são originárias de docker.io. O exemplo anterior poderia igualmente ser representado como:

version: v1.1.0
steps:
  - cmd: docker.io/bash:3.0 echo hello world

Usando a convenção de referência de imagem padrão docker run , cmd pode executar imagens de qualquer registro privado ou do Docker Hub público. Se você estiver fazendo referência a imagens no mesmo registro em que a Tarefa ACR está sendo executada, não será necessário especificar nenhuma credencial do Registro.

• Execute uma imagem de um registro de contêiner do Azure. O exemplo a seguir pressupõe que você tenha um registro chamado myregistry, e uma imagem myimage:mytagpersonalizada .

  version: v1.1.0
  steps:
      - cmd: myregistry.azurecr.io/myimage:mytag
  

• Generalizar a referência do Registro com uma variável Run ou alias

  Em vez de codificar o nome do Registro em um acr-task.yaml arquivo, você pode torná-lo mais portátil usando uma variável Run ou um alias. A Run.Registry variável ou alias se expande $Registry em tempo de execução para o nome do registro no qual a tarefa está sendo executada.

  Por exemplo, para generalizar a tarefa anterior para que ela funcione em qualquer registro de contêiner do Azure, faça referência à variável $Registry no nome da imagem:

  version: v1.1.0
  steps:
    - cmd: $Registry/myimage:mytag
  

Aceder a volumes secretos

A volumes propriedade permite que volumes e seu conteúdo secreto sejam especificados para build e cmd etapas em uma tarefa. Dentro de cada etapa, uma propriedade opcional volumeMounts lista os volumes e os caminhos de contêiner correspondentes a serem montados no contêiner nessa etapa. Os segredos são fornecidos como arquivos no caminho de montagem de cada volume.

Execute uma tarefa e monte dois segredos em uma etapa: um armazenado em um cofre de chaves e outro especificado na linha de comando:

az acr run -f mounts-secrets.yaml --set-secret mysecret=abcdefg123456 https://github.com/Azure-Samples/acr-tasks.git

# This template demonstrates mounting a custom volume into a container at a CMD step
secrets:
  - id: sampleSecret
    keyvault: https://myacbvault2.vault.azure.net/secrets/SampleSecret # Replace with valid keyvault with access

volumes:
  - name: mysecrets
    secret:
      mysecret1: {{.Secrets.sampleSecret | b64enc}}
      mysecret2: {{.Values.mysecret | b64enc}}

steps:
  - cmd: bash cat /run/test/mysecret1 /run/test/mysecret2
    volumeMounts:
      - name: mysecrets
        mountPath: /run/test

Propriedades da etapa da tarefa

Cada tipo de etapa suporta várias propriedades apropriadas para seu tipo. A tabela a seguir define todas as propriedades de etapa disponíveis. Nem todos os tipos de etapa suportam todas as propriedades. Para ver quais dessas propriedades estão disponíveis para cada tipo de etapa, consulte as seções de referência de tipo de etapa cmd, build e push .

montagem em volume

O objeto volumeMount tem as seguintes propriedades.

Exemplos: propriedades da etapa da tarefa

Exemplo: id

Crie duas imagens, instanciando uma imagem de teste funcional. Cada etapa é identificada por uma única id que outras etapas na tarefa referenciam em sua when propriedade.

az acr run -f when-parallel-dependent.yaml https://github.com/Azure-Samples/acr-tasks.git

version: v1.1.0
steps:
  # build website and func-test images, concurrently
  - id: build-hello-world
    build: -t $Registry/hello-world:$ID -f hello-world.dockerfile .
    when: ["-"]
  - id: build-hello-world-test
    build: -t hello-world-test -f hello-world.dockerfile .
    when: ["-"]
  # run built images to be tested
  - id: hello-world
    cmd: $Registry/hello-world:$ID
    when: ["build-hello-world"]
  - id: func-tests
    cmd: hello-world-test
    env:
      - TEST_TARGET_URL=hello-world
    when: ["hello-world"]
  # push hello-world if func-tests are successful  
  - push: ["$Registry/hello-world:$ID"]
    when: ["func-tests"]

Exemplo: quando

A when propriedade especifica a dependência de uma etapa em outras etapas dentro da tarefa. Ele suporta dois valores de parâmetro:

• when: ["-"] - Indica não haver dependência de outras etapas. Uma especificação when: ["-"] de etapa iniciará a execução imediatamente e habilitará a execução simultânea da etapa.
• when: ["id1", "id2"] - Indica que a etapa depende das etapas com id "id1" e id "id2". Esta etapa não será executada até que ambas as etapas "id1" e "id2" sejam concluídas.

Se when não for especificado em uma etapa, essa etapa dependerá da conclusão da etapa anterior no acr-task.yaml arquivo.

Execução de etapas sequenciais sem when:

az acr run -f when-sequential-default.yaml https://github.com/Azure-Samples/acr-tasks.git

version: v1.1.0
steps:
    - cmd: bash echo one
    - cmd: bash echo two
    - cmd: bash echo three

Execução de etapas sequenciais com when:

az acr run -f when-sequential-id.yaml https://github.com/Azure-Samples/acr-tasks.git

version: v1.1.0
steps:
    - id: step1
      cmd: bash echo one
    - id: step2
      cmd: bash echo two
      when: ["step1"]
    - id: step3
      cmd: bash echo three
      when: ["step2"]

Imagens paralelas construem:

az acr run -f when-parallel.yaml https://github.com/Azure-Samples/acr-tasks.git

version: v1.1.0
steps:
  # build website and func-test images, concurrently
  - id: build-hello-world
    build: -t $Registry/hello-world:$ID -f hello-world.dockerfile .
    when: ["-"]
  - id: build-hello-world-test
    build: -t hello-world-test -f hello-world.dockerfile .
    when: ["-"]

Construção de imagem paralela e testes dependentes:

az acr run -f when-parallel-dependent.yaml https://github.com/Azure-Samples/acr-tasks.git

version: v1.1.0
steps:
  # build website and func-test images, concurrently
  - id: build-hello-world
    build: -t $Registry/hello-world:$ID -f hello-world.dockerfile .
    when: ["-"]
  - id: build-hello-world-test
    build: -t hello-world-test -f hello-world.dockerfile .
    when: ["-"]
  # run built images to be tested
  - id: hello-world
    cmd: $Registry/hello-world:$ID
    when: ["build-hello-world"]
  - id: func-tests
    cmd: hello-world-test
    env:
      - TEST_TARGET_URL=hello-world
    when: ["hello-world"]
  # push hello-world if func-tests are successful  
  - push: ["$Registry/hello-world:$ID"]
    when: ["func-tests"]

Executar variáveis

As Tarefas ACR incluem um conjunto padrão de variáveis que estão disponíveis para as etapas da tarefa quando são executadas. Essas variáveis podem ser acessadas usando o formato {{.Run.VariableName}}, onde VariableName é um dos seguintes:

• Run.ID
• Run.SharedVolume
• Run.Registry
• Run.RegistryName
• Run.Date
• Run.OS
• Run.Architecture
• Run.Commit
• Run.Branch
• Run.TaskName

Os nomes das variáveis são geralmente autoexplicativos. Seguem-se detalhes para as variáveis mais utilizadas. A partir da versão v1.1.0YAML , você pode usar um alias de tarefa abreviado e predefinido no lugar da maioria das variáveis de execução. Por exemplo, no lugar de {{.Run.Registry}}, use o $Registry alias.

Run.ID

Cada execução, através az acr runde , ou execução baseada em gatilho de tarefas criadas através az acr task createde , tem um ID exclusivo. O ID representa a Execução que está sendo executada no momento.

Normalmente usado para uma marcação exclusiva de uma imagem:

version: v1.1.0
steps:
    - build: -t $Registry/hello-world:$ID .

Run.SharedVolume

O identificador exclusivo de um volume compartilhado que é acessível por todas as etapas da tarefa. O volume é montado c:\workspace no Windows ou /workspace no Linux.

Run.Registry

O nome do servidor totalmente qualificado do registro. Normalmente usado para referenciar genericamente o registro onde a tarefa está sendo executada.

version: v1.1.0
steps:
  - build: -t $Registry/hello-world:$ID .

Run.RegistryName

O nome do registro de contêiner. Normalmente usado em etapas de tarefas que não exigem um nome de servidor totalmente qualificado, por exemplo, cmd etapas que executam comandos da CLI do Azure em registros.

version 1.1.0
steps:
# List repositories in registry
- cmd: az login --identity
- cmd: az acr repository list --name $RegistryName

Run.Date

A hora UTC atual em que a execução começou.

Executar.Confirmar

Para uma tarefa acionada por uma confirmação em um repositório GitHub, o identificador de confirmação.

Run.Branch

Para uma tarefa acionada por uma confirmação em um repositório GitHub, o nome da filial.

Aliases

A partir de , as Tarefas ACR suportam aliases que estão disponíveis para as etapas de v1.1.0tarefas quando são executadas. Os aliases são semelhantes em conceito aos aliases (atalhos de comando) suportados em bash e alguns outros shells de comando.

Com um alias, você pode iniciar qualquer comando ou grupo de comandos (incluindo opções e nomes de arquivos) inserindo uma única palavra.

O ACR Tasks suporta vários aliases predefinidos e também aliases personalizados que você cria.

Aliases predefinidos

Os seguintes aliases de tarefa estão disponíveis para uso no lugar de variáveis de execução:

Nas etapas da tarefa, preceda um alias com a $ diretiva, como neste exemplo:

version: v1.1.0
steps:
  - build: -t $Registry/hello-world:$ID -f hello-world.dockerfile .

Aliases de imagem

Cada um dos aliases a seguir aponta para uma imagem estável no Microsoft Container Registry (MCR). Você pode consultar cada um deles na cmd seção de um arquivo de tarefa sem usar uma diretiva.

A tarefa de exemplo a seguir usa vários aliases para limpar marcas de imagem com mais de 7 dias no repositório samples/hello-world no registro de execução:

version: v1.1.0
steps:
  - cmd: acr tag list --registry $RegistryName --repository samples/hello-world
  - cmd: acr purge --registry $RegistryName --filter samples/hello-world:.* --ago 7d

Alias personalizado

Defina um alias personalizado em seu arquivo YAML e use-o como mostrado no exemplo a seguir. Um alias pode conter apenas caracteres alfanuméricos. A diretiva padrão para expandir um alias é o $ caractere.

version: v1.1.0
alias:
  values:
    repo: myrepo
steps:
  - build: -t $Registry/$repo/hello-world:$ID -f Dockerfile .

Você pode vincular a um arquivo YAML remoto ou local para definições de alias personalizadas. O exemplo a seguir vincula a um arquivo YAML no armazenamento de blob do Azure:

version: v1.1.0
alias:
  src:  # link to local or remote custom alias files
    - 'https://link/to/blob/remoteAliases.yml?readSasToken'
[...]

Próximos passos

Para obter uma visão geral das tarefas de várias etapas, consulte Executar tarefas de compilação, teste e patch em várias etapas em Tarefas do ACR.

Para compilações de etapa única, consulte a visão geral de tarefas ACR.