Ресурсы в конвейерах YAML

Azure DevOps Services | Azure DevOps Server 2022 — Azure DevOps Server 2019

В этой статье рассматриваются ресурсы для конвейеров YAML. Ресурс — это всё, что используется конвейером и находится вне его. После определения ресурса его можно использовать в любом месте конвейера.

Ресурсы обеспечивают полную трассируемость для служб, которые использует ваш конвейер, включая версию, артефакты, связанные коммиты и рабочие элементы. Вы можете полностью автоматизировать рабочие процессы DevOps, подписавшись на триггерные события на ваших ресурсах.

Схема ресурсов

Ресурсы на языке YAML представляют собой источники конвейеров, сборок, репозиториев, контейнеров, пакетов и веб-перехватчиков. Полные сведения о схеме см. в определении ресурсов в справочнике по схеме YAML для Azure Pipelines.

Когда ресурс активирует конвейер, будут заданы следующие переменные:

resources.triggeringAlias
resources.triggeringCategory

Переменная Build.Reason должна быть ResourceTrigger для получения этих значений. Значения пусты, если ресурс не инициировал выполнение конвейера.

Определение ресурсов пайплайнов

Если у вас есть конвейер, который создает артефакты, можно использовать артефакты, определив pipelines ресурс. Только Azure Pipelines могут использовать ресурс pipelines. Триггеры для рабочих процессов непрерывного развертывания (CD) можно установить в конвейерном ресурсе.

В определении ресурса pipeline это уникальное значение, которое вы можете использовать для ссылки на ресурс конвейера в дальнейшем в вашем конвейере. source — это название конвейера, который создал артефакт. Чтобы узнать полную информацию о схеме, посмотрите определение resources.pipelines.pipeline.

Вы используете метку, определенную pipeline, чтобы ссылаться на ресурс конвейера из других частей вашего конвейера, например, при использовании переменных ресурса конвейера или скачивании артефактов. Альтернативный способ скачивания артефактов конвейера см. в разделе "Скачать артефакты".

Примеры определений ресурсов конвейера

В следующем примере используются артефакты из конвейера в рамках одного проекта.

resources:
  pipelines:
  - pipeline: SmartHotel-resource # identifier to use in pipeline resource variables
    source: SmartHotel-CI # name of the pipeline that produces the artifacts

Чтобы использовать конвейер из другого проекта, укажите имя проекта и имя источника. В следующем примере используется branch для разрешения версии по умолчанию, когда конвейер активируется вручную или запланирован. Входные данные для ветки не могут содержать подстановочные символы.

resources:
  pipelines:
  - pipeline: SmartHotel
    project: DevOpsProject
    source: SmartHotel-CI
    branch: releases/M142

В следующем примере показан ресурс конвейера с простым триггером.

resources:
  pipelines:
  - pipeline: SmartHotel
    project: DevOpsProject
    source: SmartHotel-CI
    trigger: true

В следующем примере показан ресурс trigger конвейера с условиями для ветки.

resources:
  pipelines:
  - pipeline: SmartHotel
    project: DevOpsProject
    source: SmartHotel-CI
    trigger:
      branches:
      - releases/*
      - resources.triggeringAlias

В следующем примере используются stages фильтры для оценки условий триггера для конвейеров CD. Оператор AND используется на этапах. При успешном завершении всех указанных этапов конвейер CD активируется.

resources:
  pipelines:
  - pipeline: MyCIAlias  
    project: Fabrikam  
    source: Farbrikam-CI  
    trigger:    
      stages:
      - PreProduction
      - Production

В следующем примере используются tags фильтры для оценки версий по умолчанию и триггеров. Теги используют AND оператор.

Элементы tags устанавливаются в конвейере непрерывной интеграции (CI) или непрерывной доставки (CD). Эти теги отличаются от тегов, заданных в ветвях в репозитории Git.

resources:
  pipelines:
  - pipeline: MyCIAlias
    project: Fabrikam
    source: Farbrikam-CI
    tags: 
    - Production 
    trigger:
      tags:
      - Production
      - Signed

Оценка версий артефактов конвейеров

Версия артефакта в конвейере ресурсов зависит от способа запуска этого конвейера.

Ручной или запланированный триггер

Если запуск конвейера активируется вручную или планируется, значения свойств version, branch, и tags определяют версию артефакта. Входное branch значение не может иметь подстановочные знаки. Свойства tags используют AND оператор.

В следующем pipeline определении ресурсов используются свойства branch и tags для определения версии по умолчанию при запуске конвейера вручную или по расписанию. При ручном запуске конвейера версия артефактов конвейера MyCIAlias соответствует последней сборке, выполненной на ветви main, которая содержит теги Production и PrepProduction.

resources:
  pipelines:
  - pipeline: MyCIAlias
    project: Fabrikam
    source: Farbrikam-CI
    branch: main
    tags:
    - Production
    - PreProduction

Триггер завершения конвейера ресурсов

Когда конвейер запускается вследствие завершения одного из конвейеров ресурсов, версия артефактов — это версия конвейера, запускающего процесс. Значения свойств version, branch и tags игнорируются.

Следующий конвейер выполняется каждый раз, когда задействован конвейер ресурсов:

• Выполняется в одной из releases ветвей или в main ветке
• Помечен тегами Verified и Signed
• Завершает этапы Production и PreProduction

resources:
  pipelines:
  - pipeline: SmartHotel
    project: DevOpsProject
    source: SmartHotel-CI
    trigger:
      branches:
        include:
        - releases/*
        - main
        exclude:
        - topic/*
      tags: 
      - Verified
      - Signed
      stages:
      - Production
      - PreProduction
      

Скачивание артефакта конвейера

Шаг download загружает артефакты, связанные с текущим запуском или с другим ресурсом в рамках конвейера.

Все артефакты из текущего конвейера и все его pipeline ресурсы автоматически скачиваются и становятся доступными в начале каждого задания развертывания. Это поведение можно переопределить, задав downloadnoneили указав другой идентификатор ресурса конвейера.

Артефакты стандартных задач не загружаются автоматически. Используйте download явно при необходимости.

Артефакты из pipeline ресурса загружаются в папку $(PIPELINE.WORKSPACE)/<pipeline-identifier>/<artifact-identifier>. Дополнительные сведения см. в статье "Публикация и скачивание артефактов конвейера".

Необязательное artifact свойство задает имена артефактов. Если это не указано, скачиваются все доступные артефакты. Необязательное patterns свойство определяет шаблоны, представляющие файлы для включения. Полные сведения о схеме см. в определении steps.download.

- job: deploy_windows_x86_agent
  steps:
  - download: SmartHotel
    artifact: WebTier1
    patterns: '**/*.zip'

resources:
  pipelines:
  - pipeline: myresourcevars
    source: mypipeline
    trigger: true 

steps:
- script: |
    echo $(resources.pipeline.myresourcevars.pipelineID)
    echo $(resources.pipeline.myresourcevars.runName)
    echo $(resources.pipeline.myresourcevars.runID)
    echo $(resources.pipeline.myresourcevars.runURI)
    echo $(resources.pipeline.myresourcevars.sourceBranch)
    echo $(resources.pipeline.myresourcevars.sourceCommit)
    echo $(resources.pipeline.myresourcevars.sourceProvider)
    echo $(resources.pipeline.myresourcevars.requestedFor)
    echo $(resources.pipeline.myresourcevars.requestedForID)

Формирует определение ресурса

Если у вас есть внешняя система сборки CI, которая создает результаты сборки, вы можете использовать их, используя builds ресурсы. build Ресурс может быть из любой внешней системы CI, например Jenkins, TeamCity или CircleCI.

Категория builds расширяема. Вы можете написать расширение для использования артефактов из службы сборки и ввести новый тип службы в составе builds.

build В определении version по умолчанию используется последняя успешная сборка. Параметр trigger не включен по умолчанию и должен быть явно задан. Для получения полной информации о схеме см. раздел resources.builds.build definition.

В следующем примере Jenkins является ресурсом type.

resources:
  builds:
  - build: Spaceworkz
    type: Jenkins
    connection: MyJenkinsServer 
    source: SpaceworkzProj   # name of the Jenkins source project
    trigger: true

Задача downloadBuild

build Артефакты ресурсов не загружаются автоматически в заданиях/deploy-jobs. Чтобы использовать артефакты из ресурса build в ваших заданиях, необходимо явно добавить задачу downloadBuild. Вы можете настроить поведение загрузки для каждого развертывания или задания.

Эта задача автоматически переходит в соответствующую задачу загрузки для типа ресурса, определяемого build средой выполнения. Артефакты из build ресурса скачиваются в $(PIPELINE. WORKSPACE)/<build-identifier>/ folder.

В определении вы указываете downloadBuild ресурс для загрузки артефактов. Свойство artifact, которое является необязательным, определяет артефакты для скачивания. Если это не указано, скачиваются все артефакты, связанные с ресурсом.

Необязательное patterns свойство определяет минималистичный путь или список минималистичных путей для скачивания. Если пусто, скачивается весь артефакт. Например, следующий фрагмент кода скачивает только файлы *.zip .

- job: deploy_windows_x86_agent
  steps:
  - downloadBuild: Spaceworkz
    patterns: '**/*.zip'

Полные сведения о схеме см. в определении steps.downloadBuild.

Определение ресурса репозитория

Ключевое repository слово позволяет указать внешний репозиторий. Этот ресурс можно использовать, если в вашем конвейере находятся шаблоны в другом репозитории или вы хотите использовать много-репозитарийный вывод с репозиторием, для которого требуется подключение к службе. Необходимо сообщить системе об этих репозиториях.

Например:

resources:
  repositories:
  - repository: common
    type: github
    name: Contoso/CommonTools
    endpoint: MyContosoServiceConnection

Для получения полной информации о схеме см. определение resources.repositories.repository.

Типы ресурсов репозитория

Azure Pipelines поддерживает следующие значения для типа репозитория: git, , githubgithubenterpriseи bitbucket.

• Тип git относится к репозиториям Azure Repos Git.
• Репозитории GitHub Enterprise требуют подключения службы GitHub Enterprise для авторизации.
• Bitbucket Cloud repos требует подключения к облачной службе Bitbucket для авторизации.

Переменные ресурсов репозитория

resources.repositories.<Alias>.name
resources.repositories.<Alias>.ref
resources.repositories.<Alias>.type
resources.repositories.<Alias>.id
resources.repositories.<Alias>.url

resources:
  repositories:
    - repository: common
      type: git
      ref: main
      name: Repo

variables:
  ref: $[ resources.repositories.common.ref ]
  name: $[ resources.repositories.common.name ]
  id: $[ resources.repositories.common.id ]
  type: $[ resources.repositories.common.type ]
  url: $[ resources.repositories.common.url ]

steps:
- bash: |
    echo "name = $(name)"
    echo "ref = $(ref)"
    echo "id = $(id)"
    echo "type = $(type)"
    echo "url = $(url)"

resources.repositories.<Alias>.name
resources.repositories.<Alias>.ref
resources.repositories.<Alias>.type
resources.repositories.<Alias>.id
resources.repositories.<Alias>.url
resources.repositories.<Alias>.version

resources:
  repositories:
    - repository: common
      type: git
      ref: main
      name: Repo

variables:
  ref: $[ resources.repositories.common.ref ]
  name: $[ resources.repositories.common.name ]
  id: $[ resources.repositories.common.id ]
  type: $[ resources.repositories.common.type ]
  url: $[ resources.repositories.common.url ]
  version: $[ resources.repositories.common.version ]

steps:
- bash: |
    echo "name = $(name)"
    echo "ref = $(ref)"
    echo "id = $(id)"
    echo "type = $(type)"
    echo "url = $(url)"
    echo "version = $(version)"

Ключевое слово "checkout" для репозиториев

Репозитории из ресурса repository не синхронизируются автоматически в ваших задачах. Используйте ключевое слово checkout, чтобы получить репозиторий, определённый как часть ресурса repository. Полные сведения о схеме см. в определении steps.checkout.

Для получения дополнительной информации см. Обзор нескольких репозиториев в вашем конвейере.

Определение ресурсов контейнеров

Если вам нужно использовать образы контейнеров в составе конвейеров CI/CD, можно использовать containers ресурсы. container Ресурс может быть общедоступным или частным реестром Docker или экземпляром реестра контейнеров Azure.

Вы можете использовать универсальный образ ресурса контейнера в составе задания или использовать ресурс для контейнерных заданий. Если конвейеру требуется поддержка одной или нескольких служб, необходимо создать и подключиться к контейнерам служб. Тома можно использовать для обмена данными между службами.

Если вам нужно использовать образы из реестра Docker в рамках конвейера, можно определить универсальный ресурс контейнера. Не требуется ключевое слово type. Например:

resources:         
  containers:
  - container: smartHotel 
    endpoint: myDockerRegistry
    image: smartHotelApp 

Полные сведения о схеме см. в определении resources.containers.container.

тип ресурса Реестр контейнеров Azure

Чтобы воспользоваться образами из Реестра контейнеров Azure, используйте тип ресурса контейнера первого класса acr. Этот ресурс можно использовать как часть ваших заданий и для активации автоматических триггеров конвейера.

Вам необходимы разрешения участника или владельца для использования автоматических триггеров конвейера в реестре контейнеров Azure. Для получения дополнительной информации см. раздел Роли и разрешения в Реестре контейнеров Azure.

Чтобы использовать ресурс типа acr, необходимо указать значения azureSubscription, resourceGroup и repository для реестра контейнеров Azure. Например:

resources:         
  containers:
  - container: petStore      
    type: acr  
    azureSubscription: ContosoConnection
    resourceGroup: ContosoGroup
    registry: petStoreRegistry
    repository: myPets
    trigger: 
      tags:
        include: 
        - production* 

Переменные ресурсов контейнера

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

Переменные ресурсов контейнеров работают с Docker и Azure Container Registry. Нельзя использовать переменные ресурсов контейнера для контейнеров локальных образов. Переменная location применяется только к типу acr ресурсов контейнера.

В следующем примере имеется подключение службы Azure Resource Manager с именем arm-connection. Дополнительные сведения см. в реестрах контейнеров Azure, репозиториях и образах.

resources:
  containers:
  - container: mycontainer
    type: ACR
    azureSubscription: arm-connection
    resourceGroup: rg-storage-eastus
    registry: mycontainerregistry
    repository: hello-world
    trigger:
      tags:
      - latest

steps:
- script: echo |
    echo $(resources.container.mycontainer.type)
    echo $(resources.container.mycontainer.registry)
    echo $(resources.container.mycontainer.repository)
    echo $(resources.container.mycontainer.tag)
    echo $(resources.container.mycontainer.digest)
    echo $(resources.container.mycontainer.URI)
    echo $(resources.container.mycontainer.location)

resources:
  packages:
    - package: contoso
      type: npm
      connection: pat-contoso
      name: myname/contoso 
      version: 7.130.88 
      trigger: true

pool:
  vmImage: 'ubuntu-latest'

steps:
- getPackage: contoso

resources:
  webhooks:
    - webhook: WebHook
      connection: IncomingWH

steps:  
- script: echo ${{ parameters.WebHook.resource.message.title }}

{
    "resource": {
        "message": {
            "title": "Hello, world!",
            "subtitle": "I'm using WebHooks!"
        }
    }
}

resources:
  webhooks:
    - webhook: MyWebhookTrigger          
      connection: MyWebhookConnection    
      filters:
        - path: repositoryName      
          value: maven-releases     
        - path: action
          value: CREATED
steps:
- task: PowerShell@2
  inputs:
    targetType: 'inline'
    script: |
      Write-Host ${{ parameters.MyWebhookTrigger.repositoryName}}
      Write-Host ${{ parameters.MyWebhookTrigger.component.group}}

Инструмент ручного выбора версий для ресурсов

При ручном запуске конвейера YAML CD Azure Pipelines автоматически вычисляет версии по умолчанию для ресурсов, определенных в конвейере, на основе предоставленных входных данных. Однако Azure Pipelines рассматривает только успешно завершенные запуски CI при оценке версии по умолчанию для запланированных триггеров или если вы не выберете версию вручную.

Вы можете использовать средство выбора версий ресурсов, чтобы вручную выбрать другую версию при создании запуска. Средство выбора версий ресурса поддерживается для конвейера, сборки, репозитория, контейнера и пакетных ресурсов.

Для ресурсов конвейера можно просмотреть все доступные запуски во всех ветвях, выполнить поиск по номеру конвейера или ветви и выбрать выполнение, которое выполнено успешно, завершилось сбоем или выполняется. Эта гибкость гарантирует, что вы можете запустить конвейер CD, если вы уверены, что выполнение создало все необходимые артефакты. Вам не нужно ждать завершения запуска CI или повторно запускать его из-за сбоя, не связанного с этапом.

Чтобы использовать средство выбора версий ресурсов, в области "Запуск конвейера " выберите "Ресурсы", а затем выберите ресурс и выберите определенную версию из списка доступных версий.

Для ресурсов, где вы не можете получить доступные версии, такие как пакеты GitHub, средство выбора версий предоставляет текстовое поле, чтобы ввести версию для выбора запуска.

Авторизация ресурсов в конвейерах YAML

Ресурсы должны быть авторизованы, прежде чем их можно будет использовать в конвейерах. Владельцы ресурсов управляют пользователями и конвейерами, которые могут получить доступ к своим ресурсам. Существует несколько способов авторизации конвейера YAML для использования ресурсов.

• Используйте интерфейс администрирования ресурсов для авторизации всех конвейеров для доступа к ресурсу. Например, группы переменных и безопасные файлы управляются на странице библиотеки в разделе "Конвейеры", а пулы агентов и подключения служб управляются в параметрах проекта. Эта авторизация удобна, если вам не нужно ограничивать доступ к ресурсам, например для тестовых ресурсов.

• При создании конвейера все ресурсы, на которые ссылается YAML-файл, автоматически авторизуются для использования конвейером, если у вас есть роль Пользователя для этих ресурсов.

• Если вы добавляете ресурс в файл YAML, а сборка завершается ошибкой, например Could not find a <resource> with name <resource-name>. The <resource> does not exist or has not been authorized for use., вы увидите возможность авторизации ресурсов в неудачной сборке.

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

• Убедитесь, что роли безопасности пула агентов для проекта верны.

Проверки утверждения ресурсов

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

Установка обязательного утверждения шаблона гарантирует использование вашего ресурса только в определённых условиях и, таким образом, повышает безопасность. Дополнительные сведения о повышении безопасности конвейера с помощью шаблонов см. в статье "Использование шаблонов для безопасности".

Возможность трассировки

Azure Pipelines обеспечивает полную трассировку любого ресурса, потребляемого на уровне конвейера или задания на развертывание.

Трассировка конвейера

Azure Pipelines отображает следующие сведения для каждого запуска конвейера:

• Если ресурс активировал конвейер, то это тот же самый ресурс, который активировал конвейер.
• Версия ресурса и используемые артефакты.
• Коммиты, связанные с каждым ресурсом.
• Рабочие элементы, связанные с каждым ресурсом.

Трассируемость среды

При каждом развертывании конвейера в среде можно просмотреть список используемых ресурсов. В представлении содержатся ресурсы, используемые в рамках выполнения заданий по развертыванию, а также связанные с ними фиксации и рабочие элементы.

Информация о связанных потоках CD в потоках CI

Чтобы обеспечить сквозную отслеживаемость, можно отслеживать, какие конвейеры CD потребляют определенный конвейер CI через ресурс pipelines. Если другие конвейеры используют конвейер CI, вы увидите вкладку «Связанные конвейеры» в представлении «Запуск». В представлении показаны все запуски конвейера CD YAML, использовавшие ваш конвейер CI и артефакты из него.

Проблемы с триггером ресурсов

Триггеры ресурсов могут не выполняться, так как:

• Источник предоставленного подключения к службе недопустим, в триггере возникают синтаксические ошибки или триггер не настроен.
• Условия триггера не совпадают с заданными.

Чтобы узнать, почему триггеры конвейера не удалось выполнить, выберите пункт меню "Проблемы триггера " на странице определения конвейера. Проблемы с триггерами доступны только для нерепозитарных ресурсов.

На странице проблем триггера сообщения об ошибках и предупреждениях описывают, почему триггер не сработал.

Вопросы и ответы

Когда следует использовать ресурсы пайплайнов, функцию быстрой загрузки или задачу «Скачать артефакты пайплайнов»?

Использование ресурса pipelines — это способ использования артефактов из CI-конвейера и настройки автоматических триггеров. Ресурс позволяет полностью контролировать процесс, предоставляя информацию об используемой версии, артефактах, фиксациях и рабочих элементах. При определении ресурса конвейера связанные артефакты автоматически загружаются в заданиях развертывания.

С помощью download ярлыка можно скачать артефакты в заданиях сборки или переопределить поведение загрузки в заданиях развертывания. Дополнительные сведения см. в определении steps.download.

Задача Download Pipeline Artifacts не обеспечивает возможность трассировки или триггеры, но иногда имеет смысл использовать эту задачу напрямую. Например, у вас может быть задача скрипта, хранящаяся в другом шаблоне и требующая скачивания артефактов из сборки. Или, возможно, вы не захотите добавлять ресурс конвейера в шаблон. Чтобы избежать зависимостей, вы можете использовать задачу "Загрузка артефактов конвейера" для передачи всей информации о сборке в задачу.

Как активировать запуск потока, когда мой образ Docker Hub обновляется?

Триггер ресурса контейнера недоступен для конвейеров Docker Hub для YAML, поэтому необходимо настроить классический конвейер выпуска.

1. Создайте новое подключение к службе Docker Hub.
2. Создайте классический конвейер выпуска и добавьте артефакт Docker Hub. Задайте подключение службы и выберите пространство имен, репозиторий, версию и псевдоним источника.
3. Выберите триггер и переключите триггер непрерывного развертывания, чтобы включить. Каждый push Docker, выполняемый в выбранный репозиторий, создает релиз.
4. Создайте новый этап и задание. Добавьте две задачи: вход в Docker и Bash.
   • Задача Docker имеет действие login и выполняет вход на Docker Hub.
   • Задача Bash выполняется docker pull <hub-user>/<repo-name>[:<tag>].

Как проверить и диагностировать проблемы вебхука?

1. Создайте подключение к службе.

2. Укажите подключение к службе и задайте название веб-перехватчика в разделе webhooks.

   resources:
     webhooks:
       - webhook: MyWebhookTriggerAlias
         connection: MyServiceConnection
   

3. Запустите свой конвейер. Веб-перехватчик создается в Azure в качестве распределенной задачи для вашей организации.

4. Выполните API вызов, используя корректный JSON в теле запроса POST к https://dev.azure.com/<organization>/_apis/public/distributedtask/webhooks/<webhook-name>?api-version=<apiversion>. Если вы получите ответ с кодом состояния 200, это означает, что ваш веб-перехватчик готов к обработке в вашем конвейере.

Если вы получаете ответ на код состояния 500 с ошибкойCannot find webhook for the given webHookId ..., код может находиться в ветви, которая не ветвь по умолчанию. Чтобы устранить эту проблему, выполните следующие действия:

1. Выберите "Изменить" на странице конвейера.
2. В меню "Дополнительные действия" выберите "Триггеры".
3. Выберите вкладку YAML и выберите " Получить источники".
4. В разделе "Ветвь по умолчанию для ручных и запланированных сборок", обновите свою функциональную ветвь.
5. Нажмите Сохранить и поместить в очередь.
6. После успешного выполнения этого конвейера выполните вызов API, передавая допустимый JSON в теле запроса на POST. Теперь вы должны получить ответ на код состояния 200.

Связанный контент

• Сведения о ресурсах для Azure Pipelines
• Определение переменных
• Добавление и использование групп переменных
• Создание среды и выбор ее в качестве целевой
• Использование редактора конвейера YAML
• Справочник по схемам YAML