Разблокировать переменные Azure DevOps для автоматизации

Учебники

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

Если вы когда-либо задавали себе вопросы вроде:

  • Как использовать переменные конвейера сборки Azure DevOps в сценарии PowerShell?
  • Как передавать переменные между сборками и выпусками?
  • Как различаются предопределенные, пользовательские и секретные переменные?
  • Как работают группы переменных?

… то вы везунчик! В этой статье мы ответим на каждый из этих вопросов и многие другие.

К концу этой статьи вы поймете, как работают переменные сборки Azure DevOps в конвейерах Azure Pipelines!

Что такое переменные конвейера Azure DevOps?

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

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

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

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

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

Переменные среды

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

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

Окружение конвейера

Когда вы определяете или считываете переменные сборки из YAML-определения сборки, это называется окружением конвейера. Например, ниже вы можете увидеть раздел variables, определенный в YAML-определении сборки, устанавливающий переменную с именем foo равной bar. В этом контексте переменная определяется в окружении конвейера

variables:
  foo: 'bar'

Окружение скрипта

Вы также можете работать с переменными из кода, определенного в самом YAML-определении или в скриптах. Если у вас еще нет созданного скрипта, вы можете определить и считывать переменные внутри YAML-определения, как показано ниже. Вы узнаете синтаксис работы с этими переменными в этом контексте позже.

steps:
 - bash: ## Здесь устанавливаются и получаются переменные

Вы также можете оставаться в окружении скрипта, добавив этот же синтаксис в сценарий Bash и выполнить его. Это то же самое общее понятие.

Переменные окружения

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

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

variables:
  foo: 'bar'
  • Пакет – %FOO%
  • PowerShell – $env:FOO
  • Сценарий Bash – $FOO

Фазы выполнения конвейера

Когда конвейер “запускается”, он не просто “запускается”. Как и этапы, которые он содержит, конвейер также проходит через различные фазы при выполнении. Из-за отсутствия официального термина в документации Microsoft я называю это “фазами выполнения”.

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

Время Очереди

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

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

Run Pipeline Azure DevOps option

Компиляция

Наконец, когда конвейер обрабатывает файл YAML и переходит к шагам, которые требуют выполнения сценария, конвейер находится в фазе “компиляции”. В этом контексте агент выполняет код, определенный в сценарных шагах.

Время выполнения

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

Расширение переменных

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

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

Как вы узнали выше, конвейер охватывает различные “фазы” во время выполнения. Вам, вероятно, придется быть в курсе этих фаз, особенно при устранении неполадок в расширении переменных.

Ниже приведен пример. Концепция этих “фаз” тесно связана с переменными окружения.

steps:
  # Устанавливает FOO как "some value" в сценарии и следующих
  - bash: |
      FOO="runtime value"
      echo "##vso[task.setvariable variable=FOO]$FOO"

  # Используя синтаксис $() во время "компиляции", конвейер раскрывает переменную
  - bash: |
      echo "$(FOO)"

  # Используя переменную среды в контексте сценария во время "выполнения", bash раскрывает переменную
  - bash: |
      echo "$FOO"

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

jobs:
- job: build
  variables:
  - foo: bar 
  steps:
    - bash: |
        echo $(foo)            # This will be bar
        echo '##vso[task.setvariable variable=foo]baz'
        echo $(foo)            # This will also be bar, $(foo) expands before the step
    - bash: echo $(foo)        # Это будет baz. Переменная разворачивается прямо перед шагом

Синтаксис переменных

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

Переменные конвейера

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

Макро-синтаксис

Самый распространенный синтаксис, который вы найдете, это макро-синтаксис. Макро-синтаксис ссылается на значение переменной в форме $(foo). Круглые скобки представляют выражение, которое вычисляется во время выполнения.

Когда Azure Pipelines обрабатывает переменную, определенную как макро-выражение, она заменяет выражение содержимым переменной. При определении переменных с макро-синтаксисом они следуют шаблону <имя переменной>: $(<значение переменной>), например, foo: $(bar).

Если вы попытаетесь ссылаться на переменную с макро-синтаксисом и значение не существует, переменная просто не будет существовать. Это поведение немного отличается в зависимости от типа синтаксиса.

Синтаксис выражения шаблона

Другой вид синтаксиса переменных называется шаблонным выражением. Определение переменных конвейера в этом виде имеет следующий формат: ${{ variables.foo }} : ${{ variables.bar }}. Как видите, это немного длиннее, чем синтаксис макросов.

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

Переменные шаблонного выражения обрабатываются на этапе компиляции, а затем перезаписываются (если определены) во время выполнения.

Синтаксис выполнения во время выполнения

Как тип синтаксиса, предложенные переменные выполнения во время выполнения расширяются только во время выполнения. Эти типы переменных представлены в формате $[variables.foo]. Как и переменные синтаксиса шаблонного выражения, эти типы переменных вернут пустую строку, если не будут заменены.

Как и с синтаксисом макросов, синтаксис выполнения во время выполнения требует имени переменной слева от определения, например, foo: $[variables.bar].

Переменные сценария

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

Команды журналирования

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

Установка переменной с именем foo со значением bar с использованием синтаксиса команд журналирования будет выглядеть следующим образом.

"##vso[task.setvariable variable=foo;]bar"

I could not find a way to get the value of variables using logging commands. If this exists, let me know!

Переменные среды

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

Например, если переменная конвейера с именем [foo.bar](<http://foo.bar>) была определена, вы можете ссылаться на эту переменную с помощью метода ссылки на нативные переменные среды сценария, такого как $env:FOO_BAR в PowerShell или $FOO_BAR в Bash.

Мы рассмотрели больше о переменных среды в разделе Среда сценария выше.

Область видимости переменных

A pipeline has various stages, tasks and jobs running. Many areas have predefined variable scopes. A scope is namespace where when a variable is defined, its value can be referenced.

По существу, есть три разных области видимости переменных в иерархии. Они определены на уровне:

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

Переменные, определенные на “нижних” уровнях, таких как задание, перекрывают ту же переменную, определенную на уровне этапа и корневого уровня, например. Переменные, определенные на уровне этапа, перекрывают переменные, определенные на “корневом” уровне, но будут перекрыты переменными, определенными на уровне задания.

Ниже вы можете увидеть пример определения сборки YAML, в котором используется каждая область.

variables:
  global_variable: value  # это глобальная переменная, доступная всем этапам и заданиям

stages:
- stage: Build
  variables:
    stage_variable1: value3 # доступна в этапе Build и всех заданиях
  jobs:
  - job: BuildJob
    variables:
      job_variable1: value1    # это доступно только в BuildJob
    steps:
    - bash: echo $(stage_variable1) ## работает
    - bash: echo $(global_variable) ## работает
    - bash: echo $(job_variable1) ## работает

Приоритет переменных

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

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

  1. Переменная, установленная на уровне задания (установленная в файле YAML)
  2. Переменная, установленная на уровне этапа (установленная в файле YAML)
  3. Переменная, установленная на уровне конвейера (глобальная) (установленная в файле YAML)
  4. Переменная, установленная во время постановки в очередь
  5. Переменная конвейера, установленная в пользовательском интерфейсе настройки конвейера

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

variables:
  foo: 'global variable'

stages:
- stage: build
  variables:
   - name: foo
     value: 'defined at stage level'

  jobs:
  - job: compile
    variables:
    - name: foo
      value: 'defined at job level'
    steps:
      - bash: echo $(foo) # Это будет 'определено на уровне задания'

Типы переменных

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

Существует четыре общих типа переменных – предопределенные или системные переменные, пользовательские переменные, переменные вывода и секретные переменные. Давайте рассмотрим каждый из них и поймем каждый тип переменной.

Предопределенные переменные

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

Конвейер Azure состоит из множества компонентов, от агента программного обеспечения, выполняющего сборку, до заданий, запускаемых при выполнении развертывания, и другой различной информации. Чтобы представить все эти области, предопределенные переменные неформально разделены на пять отдельных категорий:

  • Агент
  • Сборка
  • Конвейер
  • Рабочее место для развертывания
  • Система

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

Переменные, определенные пользователем

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

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

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

Выходные переменные

A build definition contains one or more tasks. Sometimes a task sends a variable out to be made available to downstream steps and jobs within the same stage. These types of variables are called output variables.

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

Примечание: Выходные переменные ограничены конкретным этапом. Не ожидайте, что выходная переменная будет доступна как на этапе “сборки”, так и на этапе “тестирования”, например.

Секретные переменные

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

A secret variable is a standard variable that’s encrypted. Secret variables typically contain sensitive information like API keys, passwords, etc. These variables are encrypted at rest with a 2048-bit RSA key and are available on the agent for all tasks and scripts to use.

– НЕ определяйте секретные переменные внутри ваших файлов YAML
– НЕ возвращайте секреты в качестве выходных переменных или информации для ведения журнала

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

Секретные значения маскируются в журналах, но не полностью. Поэтому важно не включать их в файл YAML. Также следует знать, что не следует включать в “структурированные” данные в качестве секрета. Если, например, { "foo": "bar" } установлено как секрет, bar не будет скрыто в журналах.

Секреты не автоматически расшифровываются и не сопоставляются с переменными среды. Если вы определяете секретную переменную, не ожидайте, что она будет доступна через $env:FOO в сценарии PowerShell, например.

Группы переменных

И, наконец, мы подходим к группам переменных. Группы переменных, как вы можете ожидать, представляют собой “группы” переменных, на которые можно ссылаться как на одну. Основная цель группы переменных – сохранять значения, которые вы хотите сделать доступными для нескольких конвейеров.

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

Используйте группу переменных для хранения значений, которые вы хотите контролировать и делать доступными в нескольких конвейерах. Вы также можете использовать группы переменных для хранения секретов и других значений, которые могут потребоваться в файле YAML-конвейера. Группы переменных определяются и управляются на странице Библиотека под Конвейерами, как показано ниже.

Viewing variable groups

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

variables:
- group: group1

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

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

Например, если вы определили группу переменных с именем group1 с переменной с именем foo внутри, вы можете ссылаться на переменную foo как на любую другую, например, $(foo).

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

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

Summary

Теперь у вас должно быть крепкое понимание переменных Azure Pipelines. Вы узнали практически все концепции, связанные с переменными, в этой статье! Теперь отправляйтесь туда, применяйте это знание в своих трубах Azure DevOps и автоматизируйте все!

Source:
https://adamtheautomator.com/azure-devops-variables/