Локальные агенты Windows

Azure DevOps Services

Чтобы создать и развернуть Windows, Azure и другие решения Visual Studio, вам потребуется по крайней мере один агент Windows. Агенты Windows также могут создавать приложения Java и Android.

Сведения об агентах

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

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

Убедитесь, что компьютер имеет следующие предварительные требования:

• Версия операционной системы
  • Клиентская ОС
    • Windows 7 SP1 ESU
    • Windows 8.1
    • Windows 10
    • Windows 11
  • ОС сервера
    • Windows Server 2012 или более поздней версии
• Программное обеспечение агента устанавливает собственную версию .NET, поэтому нет предварительных условий для .NET.
• PowerShell 3.0 или более поздней версии
• Subversion — если вы создаете из репозитория Subversion, необходимо установить клиент Subversion на компьютере.
• Рекомендуемые средства сборки Visual Studio (2015 или более поздней версии)

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

Спецификации оборудования

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

Подготовка разрешений

Информационная безопасность для локальных агентов

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

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

Агент Azure Pipelines — это программный продукт, предназначенный для выполнения кода, скачиваемого из внешних источников. По сути это может быть мишенью для атак удаленного выполнения кода (RCE).

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

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

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

Выберите пользователя

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

Убедитесь, что у пользователя есть разрешение

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

Является ли пользователь владельцем организации Azure DevOps или администратором TFS или Azure DevOps Server? Остановитесь здесь, у вас есть разрешение.

Иначе:

1. Откройте браузер и перейдите на вкладку пулов агентов для организации Azure Pipelines или сервера Azure DevOps Server или TFS:

   1. Войдите в свою организацию (https://dev.azure.com/{yourorganization}).

   2. Выберите Azure DevOps, параметры организации.

      

   3. Выберите пулы агентов .

      вкладка "Выбор пулов агентов"

   1. Войдите в коллекцию проектов (http://your-server/DefaultCollection).

   2. Выберите Azure DevOps, параметры коллекции.

      

   3. Выберите пулы агентов .

      

2. Выберите пул на правой стороне страницы и нажмите «Безопасность».

3. Если учетная запись пользователя, которую вы собираетесь использовать, не отображается, обратитесь к администратору, чтобы добавить её. Администратор может быть администратором пула агентов, владельцем организации Azure DevOpsили TFS или администратором Azure DevOps Server.

   Если это агент группы развертывания , администратор может быть администратором группы развертывания, владельцем организации Azure DevOpsили TFS или администратором Azure DevOps Server.

   Вы можете добавить пользователя в роль администратора группы развертывания на вкладке Безопасность на странице Группы развертывания в Azure Pipelines.

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

Пайплайны Azure

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

2. В веб-браузере войдите в Azure Pipelines и перейдите на вкладку пулов агентов :

   1. Войдите в свою организацию (https://dev.azure.com/{yourorganization}).

   2. Выберите Azure DevOps, параметры организации.

      

   3. Выберите пулы агентов .

      вкладка "Выбор пулов агентов"

   1. Войдите в коллекцию проектов (http://your-server/DefaultCollection).

   2. Выберите Azure DevOps, параметры коллекции.

      

   3. Выберите пулы агентов .

      

3. Выберите пул по умолчанию, перейдите на вкладку Агенты и выберите Новый агент.

4. В диалоговом окне "Получение агента" выберите Windows.

5. На левой панели выберите архитектуру процессора установленной версии ОС Windows на компьютере. Версия агента x64 предназначена для 64-разрядной версии Windows, а версия x86 предназначена для 32-разрядных Windows. Если вы не уверены, какая версия Windows установлена, следуйте приведенным ниже инструкциям.

6. На правой панели нажмите кнопку "Скачать ".

7. Следуйте инструкциям на странице, чтобы скачать агент.

8. Распакуйте агент в выбранный каталог. Убедитесь, что путь к каталогу не содержит пробелов, так как средства и скрипты не всегда правильно обрабатывают пробелы. Рекомендуемая папка — C:\agents. Извлечение из папки загрузки или других пользовательских папок может привести к проблемам с разрешениями.

Установка агента

1. Запустите окно с повышенными привилегиями (PowerShell) и задайте расположение для распаковки агента.

   cd C:\agents 
   
   

2. Выполните config.cmd. В результате вы получите ряд вопросов для настройки агента.

   .\config.cmd
   
   

URL-адрес сервера

Тип аутентификации для настройки агента

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

Метод проверки подлинности, используемый для регистрации агента, используется только во время регистрации агента. Дополнительные сведения о том, как агенты взаимодействуют с Azure Pipelines после регистрации, см. в статье "Связь с Azure Pipelines" или TFS.

Выбор интерактивного или служебного режима

Рекомендации по запуску агента в интерактивном режиме или в качестве службы см. в разделе Agent: Interactive vs. Service.

Если вы решили запустить в качестве службы (что мы рекомендуем), имя пользователя, от имени которого выполняется служба, должно содержать 20 символов или меньше.

Запустите агента

Запуск в интерактивном режиме

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

.\run.cmd

Чтобы перезапустить агент, нажмите Ctrl+C, чтобы остановить его, а затем запустите run.cmd, чтобы перезапустить агент.

variables:
 AZP_AGENT_CLEANUP_PSMODULES_IN_POWERSHELL: "true"

Выполнить один раз

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

.\run.cmd --once

Агенты в этом режиме принимают только одно задание, а затем корректно завершают работу (полезно для запуска в Docker в таких службах, как Azure Container Instances).

Запуск от имени службы

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

• "Агент Azure Pipelines (имя агента)"
• "Агент VSTS (имя агента)"
• "vstsagent. (имя организации). (имя агента)"

Чтобы перезапустить агент, щелкните правой кнопкой мыши запись и выберите "Перезапустить".

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

Замена агента

Чтобы заменить агента, следуйте шагам загрузки и настройки агента еще раз.

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

Удаление и перенастройка агента

Чтобы удалить агент, выполните следующие действия.

.\config remove

После удаления агента можно снова настроить его.

Настройка без присмотра

Агент можно настроить из скрипта без вмешательства человека. Необходимо передать --unattended и ответы на все вопросы.

Чтобы настроить агент, он должен знать URL-адрес вашей организации или коллекции и учетные данные пользователя, авторизованного для настройки агентов. Все остальные ответы являются необязательными. Любой параметр командной строки можно указать с помощью переменной среды: напишите его имя заглавными буквами и добавьте в начало VSTS_AGENT_INPUT_. Например, VSTS_AGENT_INPUT_PASSWORD вместо указания --password.

Обязательные параметры

• --unattended — настройка агента не будет запрашивать сведения, и все параметры должны быть предоставлены в командной строке.
• --url <url> — URL-адрес сервера. Например, https://dev.azure.com/myorganization или http://my-azure-devops-server:8080/tfs
• --auth <type> — тип проверки подлинности. Допустимые значения:
  • pat (Личный маркер доступа)
  • SP (Service Principal) (Требуется версия агента 3.227.1 или новее)
  • negotiate (Kerberos или NTLM)
  • alt (обычная проверка подлинности)
  • integrated (Учетные данные Windows по умолчанию)

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

• Если вы выбрали --auth pat:
  • --token <token> — указывает личный маркер доступа
  • Вы также можете передать маркер OAuth 2.0 в качестве --token параметра.
• Если вы выбрали --auth negotiate или --auth alt:
  • --userName <userName> — указывает имя пользователя Windows в формате domain\userName или [email protected]
  • --password <password> — указывает пароль
• Если вы выбрали --auth SP:
  • --clientID <clientID> — указывает идентификатор клиента служебного принципала с доступом для регистрации агентов
  • --tenantId <tenantID> — указывает идентификатор арендатора, в котором зарегистрирован служебный принципал.
  • --clientSecret <clientSecret> — указывает Секрет клиента сервисного принципала
  • См. Регистрация агента с использованием учетной записи службы для получения дополнительной информации

Имена пулов и агентов

• --pool <pool> — имя пула для вступления агента
• --agent <agent> — имя агента
• --replace — замените агента в пуле. Если другой агент слушает под тем же именем, у него начнется сбой из-за конфликта.

Настройка агента

• --work <workDirectory> — рабочий каталог, в котором хранятся данные задания. По умолчанию устанавливается в _work в корневом каталоге агента. Рабочий каталог принадлежит заданному агенту и не должен быть предоставлен общий доступ между несколькими агентами.
• --acceptTeeEula — примите условия лицензионного соглашения конечного пользователя Team Explorer Everywhere (только для macOS и Linux)
• --disableloguploads — не отправляйте выходные данные журнала консоли на сервер. Вместо этого вы можете получить их из файловой системы узла агента после завершения задания.

Запуск только для Windows

• --runAsService — настройка агента для запуска в качестве службы Windows (требуется разрешение администратора)
• --runAsAutoLogon — настройте автоматический вход и запустите агент при запуске (требуется разрешение администратора)
• --windowsLogonAccount <account> используется вместе с --runAsService или --runAsAutoLogon, чтобы указать имя пользователя Windows в формате domain\userName или [email protected]
• --windowsLogonPassword <password> — используется с --runAsService или --runAsAutoLogon для указания пароля входа в систему Windows (не требуется для групповых управляемых учетных записей служб и встроенных учетных записей Windows, таких как NT AUTHORITY\NETWORK SERVICE)
• --enableservicesidtypeunrestricted — используется с --runAsService для настройки агента с типом SID службы SERVICE_SID_TYPE_UNRESTRICTED (требуются права администратора)
• --overwriteAutoLogon — используется с --runAsAutoLogon с целью перезаписать существующий автоматический вход на компьютере
• --noRestart — используется с --runAsAutoLogon чтобы предотвратить перезапуск узла после завершения конфигурации агента

Устранение неполадок при настройке агента с помощью параметра runAsAutoLogon

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

Если агент уже настроен на компьютере

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

.\config.cmd remove --auth 'PAT' --token '<token>'

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

<Azure DevOps organization> / <Project> / Settings / Agent pools / <Agent Pool> / Agents

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

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

.\config.cmd --unattended --agent '<agent-name>' --pool '<agent-pool-name>' --url '<azure-dev-ops-organization-url>' --auth 'PAT' --token '<token>' --runAsAutoLogon --windowsLogonAccount '<domain\user-name>' --windowsLogonPassword '<windows-password>'

Укажите имя агента (любое уникальное имя) и проверьте, появился ли этот агент в пуле агентов после перенастройки.

Гораздо лучше распаковывать архив агента (который можно скачать здесь) и выполнить эту команду из новой распаковки папки агента.

Проверьте, правильно ли записан и сохранён ключ реестра Windows

whoami /user Выполните команду, чтобы получить <sid>. Откройте Registry Editor и выполните следующий путь:

Computer\HKEY_USERS\<sid>\SOFTWARE\Microsoft\Windows\CurrentVersion\Run

Проверьте, есть VSTSAgent ли ключ. Удалите этот ключ, если он существует, а затем закройте Registry Editor и настройте агент, выполнив .\config.cmd команду (без args) из папки агента. Прежде чем ответить на вопрос Enter Restart the machine at a later time?, снова откройте Registry Editor и проверьте, появился ли VSTSAgent ключ. Нажмите, Enter чтобы ответить на вопрос, и проверьте, остается ли VSTSAgent ключ на месте после перезапуска компьютера.

Проверьте, правильно ли работают ключи реестра Windows на вашем компьютере

autorun.cmd Создайте файл, содержащий следующую строку: echo "Hello from AutoRun!" Откройте Registry Editor и в указанном выше пути создайте новую пару "ключ-значение" с ключом AutoRun и значением.

C:\windows\system32\cmd.exe /D /S /C start "AutoRun" "D:\path\to\autorun.cmd"

Перезагрузите свой компьютер. У вас возникли проблемы с разделами реестра Windows, если окно консоли не отображается с сообщением Hello from AutoRun! .

Только группа развертывания

• --deploymentGroup — настройте агента как агента группы развертывания
• --deploymentGroupName <name> — используется с --deploymentGroup для указания группы развертывания для присоединения агента.
• --projectName <name> — используется с --deploymentGroup для задания имени проекта
• --addDeploymentGroupTags — используется вместе с --deploymentGroup для указания на то, что теги группы развертывания должны быть добавлены
• --deploymentGroupTags <tags> — используется с --addDeploymentGroupTags для указания разделенного запятыми списка тегов агента группы развертывания, например web, db.

Только среды

• --addvirtualmachineresourcetags — используется для указания того, что теги ресурсов среды должны быть добавлены
• --virtualmachineresourcetags <tags> — используется с --addvirtualmachineresourcetags для указания разделенного запятыми списка тегов агента ресурсов среды, например web, db.

.\config --help всегда перечисляет последние необходимые и необязательные ответы.

Диагностика

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

.\run --diagnostics

Это приведет к выполнению набора диагностики, который может помочь устранить проблему. Функция диагностики доступна начиная с агента версии 2.165.0.

Справка по другим опциям

Чтобы узнать о других вариантах, выполните следующие действия.

.\config --help

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

Возможности

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

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

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

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

Какая версия Git используется моим агентом?

По умолчанию агент Windows использует версию Git, которая входит в состав программного обеспечения агента. Корпорация Майкрософт рекомендует использовать версию Git, которая входит в состав агента, но у вас есть несколько вариантов переопределить это поведение по умолчанию и использовать версию Git, установленную на компьютере агента в пути.

• Задайте переменную конвейера с именем System.PreferGitFromPath на true в ваших конвейерах.
• В локальных агентах можно создать файл с именем ENV в корневом каталоге агента и добавить System.PreferGitFromPath=true строку в файл. Для получения дополнительной информации см. Как установить различные переменные среды для каждого отдельного агента?

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

Syncing repository: PathFilter (Git)
Prepending Path environment variable with directory containing 'git.exe'.
git version
git version 2.26.2.windows.1

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

1. Перейдите на вкладку пулов агентов.

   1. Войдите в свою организацию (https://dev.azure.com/{yourorganization}).

   2. Выберите Azure DevOps, параметры организации.

      

   3. Выберите пулы агентов .

      вкладка "Выбор пулов агентов"

   1. Войдите в коллекцию проектов (http://your-server/DefaultCollection).

   2. Выберите Azure DevOps, параметры коллекции.

      

   3. Выберите пулы агентов .

      

2. Щелкните пул, содержащий агент.

3. Убедитесь, что агент включен.

4. Перейдите на вкладку возможностей:

   1. На вкладке "Пулы агентов" выберите нужный пул агентов.

      

   2. Выберите агентов и выберите нужного агента.

      

   3. Выберите вкладку Возможности.

      

      Примечание.

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

   1. На вкладке пулы агентов выберите нужный пул.

      

   2. Выберите агентов и выберите нужного агента.

      

   3. Выберите вкладку Возможности.

      вкладка "Возможности агента

5. Найдите функцию Agent.Version. Вы можете сравнить это значение с последней опубликованной версией агента. Ознакомьтесь с агентом Azure Pipelines и проверьте страницу на наличие самого высокого номера версии.

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

13.107.6.0/24
13.107.9.0/24
13.107.42.0/24
13.107.43.0/24
150.171.22.0/24 
150.171.23.0/24 
150.171.73.0/24 
150.171.74.0/24 
150.171.75.0/24 
150.171.76.0/24

2620:1ec:4::/48
2620:1ec:a92::/48
2620:1ec:21::/48
2620:1ec:22::/48
2620:1ec:50::/48 
2620:1ec:51::/48 
2603:1061:10::/48

Как запустить агент с самозаверяющим сертификатом?

Запуск агента с самоподписанным сертификатом

Как запустить агент через веб-прокси?

Запустить агент через веб-прокси

Как перезапустить агент

Если агент запущен в интерактивном режиме, ознакомьтесь с инструкциями по перезапуску в интерактивном режиме. Если вы запускаете агент в качестве службы, перезапустите агент, выполнив действия, описанные в разделе "Запуск от имени службы".

MyEnv0=MyEnvValue0
MyEnv1=MyEnvValue1
MyEnv2=MyEnvValue2
MyEnv3=MyEnvValue3
MyEnv4=MyEnvValue4

https://login.microsoftonline.com
https://app.vssps.visualstudio.com 
https://{organization_name}.visualstudio.com
https://{organization_name}.vsrm.visualstudio.com
https://{organization_name}.vstmr.visualstudio.com
https://{organization_name}.pkgs.visualstudio.com
https://{organization_name}.vssps.visualstudio.com

https://dev.azure.com
https://*.dev.azure.com
https://login.microsoftonline.com
https://management.core.windows.net
https://vstsagentpackage.azureedge.net
https://download.agent.dev.azure.com
https://vssps.dev.azure.com

13.107.6.0/24
13.107.9.0/24
13.107.42.0/24
13.107.43.0/24
150.171.22.0/24 
150.171.23.0/24 
150.171.73.0/24 
150.171.74.0/24 
150.171.75.0/24 
150.171.76.0/24

2620:1ec:4::/48
2620:1ec:a92::/48
2620:1ec:21::/48
2620:1ec:22::/48
2620:1ec:50::/48 
2620:1ec:51::/48 
2603:1061:10::/48

Что такое активация параметра SERVICE_SID_TYPE_UNRESTRICTED для службы агента?

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

Enter enable SERVICE_SID_TYPE_UNRESTRICTED for agent service (Y/N) (press enter for N)

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

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