Справка по задачам Реестра контейнеров Azure: YAML

Определение многошаговой задачи в службе "Задачи ACR" предоставляет ориентированный на контейнеры вычислительный примитив, направленный на сборку, тестирование и исправление контейнеров. В этой статье рассматриваются команды, параметры, свойства и синтаксис для YAML-файлов, определяющих многошаговые задачи.

Эта статья содержит справочные сведения о создании YAML-файлов многошаговых задач для службы "Задачи ACR". Общие сведения о задачах ACR см. в обзоре службы "Задачи ACR".

Формат файла acr-task.yaml

Служба "Задачи ACR" поддерживает объявление многошаговой задачи в стандартном синтаксисе YAML. Шаги задачи определяются в YAML-файле. После этого задачу можно запустить вручную, передав этот файл в команду az acr run. Также можно использовать этот файл, чтобы с помощью команды az acr task create создать задачу, которая будет вызываться автоматически при фиксации в Git, обновлении базового образа или по расписанию. Несмотря на то, что в этой статье acr-task.yaml рассматривается как файл, содержащий шаги, служба "Задачи ACR" поддерживает любое допустимое имя файла с поддерживаемым расширением.

Примитивами acr-task.yaml верхнего уровня являются свойства задачи, типы шагов и свойства шага.

• Свойства задачи применяются для всех шагов на протяжении всего выполнения задачи. Существует несколько глобальных свойств задачи, в том числе:
  • version
  • stepTimeout
  • workingDirectory
• Типы шагов задачи представляют собой типы действий, которые могут быть выполнены в задаче. Существует три типа шагов:
  • build
  • push
  • cmd
• Свойства шага задачи — параметры, которые применяются к отдельному шагу. Существует несколько свойств шага, в том числе:
  • startDelay
  • timeout
  • when
  • ...и многие другие.

Ниже приведен пример базового формата файла acr-task.yaml, включая некоторые общие свойства шага. Хотя он не является исчерпывающим представлением всех доступных свойств шага или использования типа шага, он предоставляет краткий обзор базового формата файла.

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.

Поддерживаемые расширения имен файлов задач

Для службы "Задачи ACR" зарезервированы несколько расширений имен файлов, включая .yaml, которые будут обрабатываться как файл задачи. Любое расширение, отсутствующее в следующем списке, служба "Задачи ACR" относит к Dockerfile: .yaml, .yml, .toml, .json, .sh, .bash, .zsh, .ps1, .ps, .cmd, .bat, .ts, .js, .php, .py, .rb, .lua

YAML — единственный формат файлов, который сейчас поддерживает служба "Задачи ACR". Другие расширения имен файлов зарезервированы для возможной будущей поддержки.

Запуск примеров задач

В следующих разделах этой статьи приводятся ссылки на несколько примеров файлов задач. Примеры задач расположены в общедоступном репозитории GitHub Azure-Samples/acr-tasks. Их можно запустить с помощью команды az acr run в Azure CLI. Примеры команд выглядят приблизительно так:

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

Форматирование в примерах команд предполагает, что вы уже настроили реестр по умолчанию в Azure CLI, поэтому параметр --registry опускается. Чтобы настроить реестр по умолчанию, воспользуйтесь командой az configс параметром set, который принимает пару "ключ — значение" defaults.acr=REGISTRY_NAME.

Например, чтобы настроить Azure CLI с реестром myregistry по умолчанию, выполните следующую команду:

az config set defaults.acr=myregistry

Свойства задачи

Свойства задачи обычно представлены в верхней части файла acr-task.yaml и являются глобальными, то есть применяются в процессе выполнения всех шагов задачи. Некоторые из этих глобальных свойств могут быть переопределены в рамках отдельного шага.

secret

Объект secret имеет следующие свойства.

сеть

Объект network имеет следующие свойства.

том

Объект volume имеет следующие свойства.

Типы шагов задач

Служба "Задачи ACR" поддерживает три типа шагов. Каждый тип шага поддерживает несколько свойств, подробно описанных в соответствующих разделах о каждом из типов.

сборка

Сборка образа контейнера. Тип шага build представляет мультитенантное защищенное средство запуска docker build в облаке в качестве примитива первого класса.

Синтаксис: build

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

Выполните команду az acr run, чтобы получить версию docker.

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

Добавьте переменную DOCKER_BUILDKIT=1 среды в yaml-файл для включения buildkit и использования secretbuildkit.

Тип шага build поддерживает параметры, описанные в следующей таблице. Тип шага build также поддерживает все параметры сборки из команды docker build, такие как --build-arg, для определения переменных во время сборки.

Свойства: build

Тип шага build поддерживает следующие свойства. Сведения об этих свойствах см. в разделе Свойства шага задачи этой статьи.

Примеры: build

Сборка образа — контекст в корне

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 .

Сборка образа — контекст в подкаталоге

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

Динамическая переменная, передаваемая в задачах ACR

При работе с задачами реестра контейнеров Azure (ACR) может потребоваться передать в процесс сборки разные значения, не изменив определение задачи с помощью флага --set с командой az acr task run .

Пример. Настройка тега изображения во время выполнения

Предположим, у вас есть задача ACR, определенная в acr-task.yml файле с заполнителем для тега изображения:

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

Вы можете активировать задачу и задать tag переменную v2 во время выполнения с помощью следующей команды Azure CLI:

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

Эта команда запустит задачу ACR с именем mytask и создаст изображение с помощью тега v2 , переопределяя заполнитель в acr-task.yml файле.

Этот подход позволяет настраивать в конвейерах CI/CD, что позволяет динамически настраивать параметры в зависимости от текущих потребностей без изменения определений задач.

отправка

Отправляет командой один или несколько из только что созданных или перемаркированных образов в реестр контейнеров. Команда push поддерживается для таких закрытых реестров, как Реестр контейнеров Azure, а также общедоступный реестр Docker Hub.

Синтаксис: push

Тип шага push поддерживает коллекцию образов. Синтаксис коллекции YAML поддерживает встроенные и вложенные форматы. Отправка одного образа обычно представляется с помощью встроенного синтаксиса:

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

Для повышения удобочитаемости используйте вложенный синтаксис при отправке нескольких образов:

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

Свойства: push

Тип шага push поддерживает следующие свойства. Сведения об этих свойствах см. в разделе Свойства шага задачи этой статьи.

Примеры: push

Отправка нескольких образов командой 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

Сборка, отправка и запуск

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

Тип шага cmd запускает контейнер.

Синтаксис: cmd

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

Свойства: cmd

Тип шага cmd поддерживает следующие свойства:

Сведения об этих свойствах см. в разделе Свойства шага задачи этой статьи.

Примеры: cmd

Запуск образа hello-world

Эта команда выполняет файл задачи hello-world.yaml, который ссылается на образ hello-world в 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

Запуск образа bash и вывод командой echo hello world

Эта команда выполняет файл задачи bash-echo.yaml, который ссылается на образ bash в 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

Тег для запуска определенного образа bash

Чтобы запустить конкретную версию образа, укажите тег в команде cmd.

Эта команда выполняет файл задачи bash-echo-3.yaml, который ссылается на образ bash:3.0 в 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

Запуск пользовательских образов

Тип шага cmd ссылается на образы с использованием стандартного формата docker run. Предполагается, что образы, которые не начинаются с указания реестра, поступают из docker.io. Предыдущий пример может быть также представлен следующим образом:

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

Применяя стандартное соглашение о ссылках на образы docker run, cmd может запускать образы, находящиеся в любом частном реестре или общедоступном реестре Docker Hub. Если вы ссылаетесь на образы в том же реестре, в котором выполняется задача ACR, не нужно указывать учетные данные реестра.

• Запустите образ из реестра контейнеров Azure. В следующем примере предполагается, что у вас есть реестр с именем myregistry и пользовательский образ myimage:mytag.

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

• Обобщение ссылки на реестр с помощью переменной Run или псевдонима

  Вместо непосредственного указания имени реестра в файле acr-task.yaml можно улучшить его переносимость с помощью переменной Run или псевдонима. Переменная Run.Registry или псевдоним $Registry развертываются во время выполнения как имя реестра, в котором выполняется задача.

  Например, чтобы обобщить предыдущую задачу для работы в любом реестре контейнеров Azure, используйте ссылку на переменную $Registry в имени образа:

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

Доступ к томам secret

С помощью свойства volumes можно указывать тома и содержащиеся на них секреты для шагов build и cmd в задаче. В рамках каждого шага необязательное свойство volumeMounts содержит перечисление томов и соответствующих путей к контейнеру для подключения к контейнеру на этом шаге. Секреты предоставляются в виде файлов по пути подключения для каждого тома.

Выполните задачу и подключите для шага два секрета, один из которых хранится в хранилище ключей, а второй задается в командной строке:

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

Свойства шага задачи

Каждый тип шага поддерживает несколько свойств, подходящих для его типа. В следующей таблице определены все доступные свойства шагов. Не все типы шагов поддерживают все свойства. Чтобы узнать, какие из этих свойств доступны для каждого типа шага, см. разделы справки по типам шагов cmd, build и push.

volumeMount

Объект volumeMount имеет следующие свойства.

Примеры. Свойства шага задачи

Пример: id

Создайте два образа, используя экземпляры образа функционального теста. Каждый шаг идентифицируется уникальным id, на который ссылаются другие шаги задачи в свойстве when.

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"]

Пример: when

Свойство when указывает зависимость шага от других шагов в пределах задачи. Оно поддерживает два значения параметров:

• when: ["-"] — указывает отсутствие зависимости от других шагов. Шаг с указанием when: ["-"] начнет выполняться немедленно и обеспечивает параллельное выполнение шагов.
• when: ["id1", "id2"] — указывает, что шаг зависит от шагов с id id1 и id id2. Этот шаг не будет выполнен до тех пор, пока не будут завершены оба шага id1 и id2.

Если свойство when не указано в шаге, этот шаг зависит от завершения предыдущего шага в файле acr-task.yaml.

Последовательное выполнение шагов без свойства 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

Последовательное выполнение шагов со свойством 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"]

Параллельное создание образов

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: ["-"]

Параллельное создание образов и тестирование зависимостей:

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"]

Переменные run

Служба "Задачи ACR" содержит набор переменных по умолчанию, доступных для шагов задачи при их выполнении. К этим переменным можно получить доступ с использованием формата {{.Run.VariableName}}, где VariableName — одна из следующих переменных:

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

Имена переменных, как правило, соответствуют их предназначению. Ниже приводится подробное описание часто используемых переменных. Начиная с версии YAML v1.1.0, вместо большинства переменных Run можно использовать сокращенный стандартный псевдоним задачи. Например, вместо {{.Run.Registry}} можно использовать псевдоним $Registry.

Run.ID

Каждая команда Run, выполняемая с помощью az acr run или по триггеру задач, созданных с помощью az acr task create, обладает уникальным идентификатором. Идентификатор представляет выполняющуюся в текущий момент команду Run.

Обычно используется для уникальной маркировки образа:

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

Run.SharedVolume

Уникальный идентификатор общего тома, который доступен для всех шагов задачи. Такой том подключается к c:\workspace в Windows или к /workspace в Linux.

Run.Registry

Полное имя сервера реестра. Обычно используется для универсальной ссылки на реестр, в котором выполняется задача.

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

Run.RegistryName

Имя реестра контейнеров. Обычно используется на шагах задачи, не требующих полного имени сервера, таких как шаги cmd, на которых выполняются команды Azure CLI в реестре.

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

Run.Date

Текущее время в формате UTC, когда начался запуск.

Run.Commit

Идентификатор фиксации для задачи, активируемой по фиксации в репозитории GitHub.

Run.Branch

Имя ветви для задачи, активируемой по фиксации в репозитории GitHub.

Aliases

Начиная с версии v1.1.0, служба "Задачи ACR" поддерживает псевдонимы, доступные для шагов задачи при их выполнении. Концепция их применения схожа с псевдонимами (ярлыками команд), которые поддерживаются в bash и других командных оболочках.

С помощью псевдонима можно запустить любую команду или группу команд (в том числе с параметрами и именами файлов), введя всего одно слово.

Служба "Задачи ACR" поддерживает несколько стандартных псевдонимов, а также пользовательские псевдонимы.

Стандартные псевдонимы

Следующие псевдонимы задач можно использовать вместо переменных Run.

В шагах задачи укажите перед псевдонимом директиву $, как показано в следующем примере:

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

Псевдонимы образа

Каждый из следующих псевдонимов указывает на стабильный образ в Microsoft Container Registry (MCR). Вы можете ссылаться на любой из них в разделе cmd файла задачи без использования директивы.

В следующем примере задачи используется несколько псевдонимов для очистки тегов образов старше 7 дней в репозитории samples/hello-world в реестре выполнения:

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

Пользовательский псевдоним

Вы можете определить пользовательский псевдоним в YAML-файле и использовать его, как показано в следующем примере. Псевдоним может содержать только буквы и цифры. По умолчанию в качестве директивы для расширения псевдонима используется символ $.

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

Вы можете задать ссылку на удаленный или локальный YAML-файл для определений пользовательских псевдонимов. В следующем примере задается ссылка на YAML-файл в хранилище BLOB-объектов Azure:

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

Следующие шаги

Обзор многошаговых задач см. в статье Run multi-step build, test, and patch tasks in ACR Tasks (Выполнение многошаговых задач сборки, тестирования и исправления в решении "Задачи ACR").

Сведения об одношаговых сборках см. в статье Автоматизация установки исправлений ОС и платформы с помощью службы "Задачи ACR".