Исправление ошибки федеративного токена в конвейере MLOps Azure DevOps

Ошибка “неизвестные аргументы: --federated-token” обычно возникает из-за того, что ваша версия Azure CLI не поддерживает параметр аутентификации с использованием федерированного токена или из-за неправильно настроенных параметров федерации идентификации рабочей нагрузки (Workload Identity Federation) в Azure DevOps. Хотя обновление версии Azure CLI может помочь, полное решение требует правильной настройки федерации идентификации рабочей нагрузки и подключений к службам в Azure DevOps, что было успешно реализовано многими пользователями с использованием репозитория Microsoft/MLOpsPython.

Содержание

• Понимание ошибки федерированного токена
• Основные причины и решения
• Пошаговая реализация исправления
• Успешная настройка конвейера MLOps end-to-end
• Проверка и тестирование
• Лучшие практики и устранение неполадок

Понимание ошибки федерированного токена

Ошибка “неизвестные аргументы: --federated-token” возникает, когда команды Azure CLI в вашем конвейере пытаются использовать параметр --federated-token, но либо:

1. Ваша версия Azure CLI устарела и не поддерживает этот параметр
2. Аутентификация с использованием федерированного токена неправильно настроена в подключении к службе Azure DevOps
3. Есть несоответствие между URL-адресом издателя или субъектом федерации в ваших учетных данных федерированной идентичности

Согласно документации Microsoft Azure DevOps, эта ошибка указывает на то, что “ваши учетные данные федерированной идентичности неправильно настроены или клиент Microsoft Entra блокирует OpenID Connect (OIDC)”.

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

Основные причины и решения

Основные причины

1. Устаревшая версия Azure CLI

• Параметр --federated-token был введен в версиях Azure CLI 2.30.0 и более поздних
• Если среда вашего конвейера имеет более старую версию, она не распознает этот аргумент

2. Неправильно настроенная федерация идентификации рабочей нагрузки

• Подключение к службе в Azure DevOps может быть неправильно настроено с использованием федерации идентификации рабочей нагрузки
• URL-адрес издателя может не соответствовать ожидаемому формату (должен начинаться с https://login.microsoftonline.com/)

3. Проблемы с субъектом-службой

• Субъект-служба может быть просрочен, отозван или иметь недостаточные разрешения
• Учетные данные федерированной идентичности могут быть неправильно связаны с субъектом-службой

Немедленные решения

Обновление Azure CLI

# В вашем конвейере добавьте этот шаг перед задачами Azure CLI
- task: AzureCLI@2
  displayName: 'Обновление Azure CLI'
  inputs:
    azureSubscription: 'ваше-подключение-к-службе'
    scriptType: bash
    scriptLocation: inlineScript
    inlineScript: |
      az upgrade
      az --version

Настройка федерации идентификации рабочей нагрузки
Как рекомендуется в Microsoft Q&A, вам нужно:

• Изменить ваше подключение к Azure Resource Manager в разделе “Параметры проекта” → “Подключения к службам”
• Переключить его на федерацию идентификации рабочей нагрузки (вручную)

Пошаговая реализация исправления

Шаг 1: Обновление Azure CLI в среде конвейера

Добавьте следующую задачу в ваш конвейер перед любыми операциями Azure CLI:

- task: AzureCLI@2
  displayName: 'Обновление Azure CLI'
  inputs:
    azureSubscription: 'имя-вашего-подключения-к-службе'
    scriptType: bash
    scriptLocation: inlineScript
    inlineScript: |
      echo "Обновление Azure CLI..."
      az upgrade --yes
      az --version

Шаг 2: Настройка федерации идентификации рабочей нагрузки в Azure DevOps

1. Перейдите в ваш проект Azure DevOps
2. Перейдите в Параметры проекта → Подключения к службам
3. Выберите существующее подключение к Azure Resource Manager
4. Нажмите Изменить
5. В разделе Метод аутентификации выберите Федерация идентификации рабочей нагрузки
6. Убедитесь, что URL-адрес издателя начинается с https://login.microsoftonline.com/
7. Нажмите Сохранить, чтобы применить изменения

Важно: Как указано в руководстве по устранению неполадок Azure, “если вы видите сообщение, указывающее на то, что не найдено соответствующей записи федерированной идентичности, либо URL-адрес издателя, либо субъект федерации не совпадают.”

Шаг 3: Обновление YAML-конфигурации конвейера для использования федерированного токена

Измените задачи Azure CLI для правильной обработки аутентификации с использованием федерированного токена:

- task: AzureCLI@2
  displayName: 'Вход в Azure с использованием федерированного токена'
  inputs:
    azureSubscription: 'ваше-подключение-к-федерированной-идентичности'
    scriptType: bash
    scriptLocation: inlineScript
    inlineScript: |
      az login --debug --federated-token "$(cat $AZURE_FEDERATED_TOKEN_FILE)" --service-principal -u $AZURE_CLIENT_ID -t $AZURE_TENANT_ID
    addSpnToEnvironment: true

Этот подход, как показано в решении на Stack Overflow, правильно обрабатывает файл федерированного токена и переменные среды.

Успешная настройка конвейера MLOps end-to-end

Процесс полной настройки

На основе успешных реализаций, задокументированных в репозитории Microsoft MLOps и различных руководствах, вот полный процесс настройки:

1. Настройка репозитория

• Клонируйте репозиторий Microsoft/MLOpsPython:
  bash

  git clone https://github.com/microsoft/MLOpsPython.git
  cd MLOpsPython
  

2. Настройка проекта Azure DevOps

• Создайте новый проект Azure DevOps или подключите существующий репозиторий
• Убедитесь, что у вас есть необходимые разрешения для подписки Azure

3. Настройка субъекта-службы и федерированной идентичности

# Создайте субъект-службу в Azure
az ad sp create-for-rbac --name "mlops-sp" --role contributor --scopes /subscriptions/ваш-id-подписки

# Запишите следующие значения:
# ID приложения (клиента)
# ID каталога (клиента)
# Секрет клиента (для первоначальной настройки)

4. Настройка федерации идентификации рабочей нагрузки
Как описано в руководстве Firefly Academy, федерированная идентичность “устраняет эти проблемы, используя OpenID Connect (OIDC).”

5. Настройка конвейера
Репозиторий Microsoft/MLOpsPython предоставляет предварительно созданные шаблоны конвейеров, которые вы можете настроить. Ключевым является обеспечение того, чтобы все задачи Azure CLI использовали обновленную версию и правильную аутентификацию с использованием федерированного токена.

Пример реализации в реальных условиях

Согласно опыту пользователей, задокументированному в Microsoft Q&A, успешная реализация включает:

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

Проверка и тестирование

Шаги проверки конвейера

1. Тестирование версии Azure CLI

az --version
# Должно показать версию 2.30.0 или выше

2. Тестирование аутентификации с использованием федерированного токена

- task: AzureCLI@2
  displayName: 'Тестирование аутентификации с использованием федерированного токена'
  inputs:
    azureSubscription: 'ваше-подключение-к-федерированной-идентичности'
    scriptType: bash
    scriptLocation: inlineScript
    inlineScript: |
      az account show
      echo "Аутентификация с использованием федерированного токена выполнена успешно"

3. Запуск конвейера end-to-end

• Запустите полный запуск конвейера из шаблона Microsoft/MLOpsPython
• Мониторьте ошибку федерированного токена
• Убедитесь, что все шаги интеграции Azure ML и DevOps успешно завершены

Общие проверки валидации

• Убедитесь, что ваша организация Azure DevOps имеет необходимые разрешения для федерации идентификации рабочей нагрузки
• Проверьте, что субъект-служба имеет правильные роли и разрешения
• Убедитесь, что учетные данные федерированной идентичности правильно связаны с субъектом-службой
• Подтвердите, что переменные среды конвейера правильно установлены

Лучшие практики и устранение неполадок

Лучшие практики для успешного конвейера MLOps

1. Управление версиями

• Регулярно обновляйте Azure CLI до последней стабильной версии
• Используйте согласованные версии во всех средах конвейера
• Регулярно обновляйте расширения и задачи Azure DevOps

2. Настройка безопасности

• Используйте федерацию идентификации рабочей нагрузки вместо сохраненных учетных данных
• Реализуйте правильную RBAC для субъектов-служб
• Регулярно вращайте и проверяйте учетные данные федерированной идентичности

3. Оптимизация конвейера

• Используйте параллельную обработку где возможно
• Реализуйте правильное ведение журналов и мониторинг
• Настройте автоматическое тестирование для изменений конвейера

Устранение продолжающихся проблем

Если вы продолжаете испытывать проблемы с федерированным токеном:

1. Режим отладки

- task: AzureCLI@2
  displayName: 'Отладка входа в Azure CLI'
  inputs:
    azureSubscription: 'ваше-подключение-к-службе'
    scriptType: bash
    scriptLocation: inlineScript
    inlineScript: |
      az login --debug --federated-token "$(cat $AZURE_FEDERATED_TOKEN_FILE)" --service-principal -u $AZURE_CLIENT_ID -t $AZURE_TENANT_ID

2. Проверка переменных среды

echo "AZURE_FEDERATED_TOKEN_FILE: $AZURE_FEDERATED_TOKEN_FILE"
echo "AZURE_CLIENT_ID: $AZURE_CLIENT_ID"
echo "AZURE_TENANT_ID: $AZURE_TENANT_ID"

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

Заключение

Ошибка “неизвестные аргументы: --federated-token” в конвейерах Microsoft/MLOpsPython может быть успешно устранена путем систематического подхода:

1. Обновите Azure CLI до версии 2.30.0 или выше для поддержки аутентификации с использованием федерированного токена
2. Правильно настройте федерацию идентификации рабочей нагрузки в подключениях к службам Azure DevOps
3. Обновите YAML-конфигурацию конвейера для использования правильного синтаксиса аутентификации с использованием федерированного токена
4. Проверьте все конфигурации через шаги тестирования и отладки

Многие пользователи успешно реализовали полные конвейеры MLOps end-to-end с использованием репозитория Microsoft/MLOpsPython, следуя этим шагам настройки. Ключевым является обеспечение совместимости всех задач Azure CLI с методом аутентификации с использованием федерированного токена и правильной настройки федерации идентификации рабочей нагрузки в Azure DevOps.

Для долгосрочного успеха регулярно обновляйте инструменты CLI и следите за документацией Microsoft на предмет любых изменений в требованиях к федерированной аутентификации. Репозиторий Microsoft MLOpsPython обеспечивает отличную основу, которая при правильной настройке может предоставлять надежные конвейеры CI/CD для рабочих процессов машинного обучения.

Источники

1. Microsoft Azure DevOps - Getting unrecognized arguments: federated-token in MLOpsPython pipeline
2. Microsoft Learn - AZURE_FEDERATED_TOKEN not injected in pipeline using Workload Identity Federation
3. Microsoft Learn - Troubleshoot workload identity service connections
4. Microsoft Azure DevOps Documentation - Workload Identity Federation troubleshooting
5. Azure Workload Identity Documentation - Troubleshooting
6. Microsoft MLOpsPython GitHub Repository - End-to-end MLOps pipeline implementation
7. Firefly Academy - Integrating Federated Identity Credentials with Azure DevOps
8. Microsoft Q&A - Workload Identity Federation successful implementation
9. Stack Overflow - Azure Pipelines logging in using Workload Identity Federation
10. MLOps Python Tutorial - End to end MLOps implementation