Поддержка Windows

• Windows: Как это работает
• Установка на управляющей машине
• Использование управляющей машины Windows
• Параметры аутентификации
  • Сертификат
  • Kerberos
    • Установка зависимостей python-kerberos
    • Установка python-kerberos
    • Настройка Kerberos
    • Тестирование подключения Kerberos
    • Автоматическое управление билетами Kerberos
    • Устранение неполадок подключений Kerberos
  • CredSSP
    • Установка requests-credssp
    • CredSSP и TLS 1.2
  • Делегирование учетных данных
• Инвентаризация
• Подготовка системы Windows
• Получение доступа к PowerShell 3.0 или выше
• Какие модули доступны
• Разработчики: Поддерживаемые модули и принцип работы
• Факты о Windows
• Примеры playbook для Windows
• Вклад в поддержку Windows

Windows: Как это работает

Как вы уже могли прочитать, Ansible по умолчанию управляет машинами Linux/Unix с помощью SSH.

Начиная с версии 1.7, Ansible также поддерживает управление машинами Windows. Это использует родной механизм удаленного вызова PowerShell, а не SSH.

Ansible по-прежнему будет выполняться с управляющей машины Linux и использует модуль Python «winrm» для взаимодействия с удаленными хостами. Хотя это не поддерживается Microsoft или Ansible, эта машина Linux может быть оболочкой bash Windows Subsystem for Linux (WSL).

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

Обратите внимание, что ожидается, что у вас есть базовые знания Ansible перед изучением этого раздела, поэтому, если вы еще не написали playbook для Linux, возможно, стоит сначала изучить этот раздел.

Установка на управляющей машине

На управляющей машине Linux:

pip install "pywinrm>=0.2.2"

Использование управляющей машины Windows

Для управления хостами Windows требуется управляющая машина Linux. Эта машина Linux может быть оболочкой bash Windows Subsystem for Linux (WSL).

Если вы хотите поэкспериментировать с Windows Subsystem for Linux (WSL), сначала включите Windows Subsystem for Linux, следуя этим инструкциям здесь. Это требует перезагрузки.

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

sudo apt-get update
sudo apt-get install python-pip git libffi-dev libssl-dev -y
pip install ansible pywinrm

# this step is only necessary for Windows builds earlier than 16188, and must be repeated each time bash is launched,
# unless bash is launched as ``bash --login``
# see https://github.com/Microsoft/BashOnWindows/issues/2148 and
# https://github.com/Microsoft/BashOnWindows/issues/816#issuecomment-301216901 for details
source ~/.profile

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

Если вы хотите запустить Ansible из исходного кода в целях разработки, просто удалите установленную версию с помощью pip (что оставит все необходимые зависимости), затем клонируйте исходный код Ansible и выполните скрипт hacking, чтобы настроить его на запуск из исходного кода:

pip uninstall ansible -y
git clone https://github.com/ansible/ansible.git
source ansible/hacking/env-setup

Параметры аутентификации

При подключении к хосту Windows можно использовать различные параметры аутентификации. Доступные параметры и поддерживаемые функции:

Вы можете указать желаемый параметр аутентификации, установив его в переменную ansible_winrm_transport.

Сертификат

Аутентификация с помощью сертификата аналогична SSH, где сертификат присваивается локальному пользователю, и вместо использования пароля для аутентификации используется сертификат.

Kerberos

Kerberos предпочтительнее NTLM при использовании учетной записи Active Directory, но для настройки на управляющей машине Ansible требуется несколько дополнительных шагов. Вам нужно установить модуль «python-kerberos» на управляющей машине Ansible (и зависимости библиотеки MIT krb5). Управляющая машина Ansible также должна иметь правильно настроенную компьютерную учетную запись в Active Directory.

Установка зависимостей python-kerberos

# Via Yum
yum -y install python-devel krb5-devel krb5-libs krb5-workstation

# Via Apt (Ubuntu)
sudo apt-get install python-dev libkrb5-dev krb5-user

# Via Portage (Gentoo)
emerge -av app-crypt/mit-krb5
emerge -av dev-python/setuptools

# Via pkg (FreeBSD)
sudo pkg install security/krb5

# Via OpenCSW (Solaris)
pkgadd -d http://get.opencsw.org/now
/opt/csw/bin/pkgutil -U
/opt/csw/bin/pkgutil -y -i libkrb5_3

# Via Pacman (Arch Linux)
pacman -S krb5

Установка python-kerberos

После установки необходимых зависимостей, оболочку python-kerberos можно установить через pip:

pip install pywinrm[kerberos]

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

Настройка Kerberos

Отредактируйте файл /etc/krb5.conf (который должен быть установлен в результате установки вышеуказанных пакетов) и добавьте следующую информацию для каждого домена, к которому необходимо подключиться:

В разделе, начинающемся с

[realms]

добавьте полное имя домена и полные доменные имена ваших первичных и вторичных контроллеров домена Active Directory. Это должно выглядеть примерно так:

[realms]

 MY.DOMAIN.COM = {
  kdc = domain-controller1.my.domain.com
  kdc = domain-controller2.my.domain.com
 }

а в разделе [domain_realm] добавьте строку, подобную следующей, для каждого домена, к которому нужно получить доступ:

[domain_realm]
    .my.domain.com = MY.DOMAIN.COM

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

Тестирование подключения Kerberos

Если вы установили krb5-workstation (yum) или krb5-user (apt-get), вы можете использовать следующую команду, чтобы проверить, можете ли вы авторизоваться на контроллере домена.

kinit user@MY.DOMAIN.COM

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

Чтобы увидеть полученные билеты, используйте команду klist

klist

Автоматическое управление билетами Kerberos

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

Чтобы отключить автоматическое управление билетами (например, чтобы использовать существующий билет SSO или вызвать kinit вручную для заполнения кэша учетных данных по умолчанию), задайте ansible_winrm_kinit_mode=manual в инвентаризации.

Для автоматического управления билетами требуется стандартный kinit двоичный файл в пути системной переменной среды на управляющей машине. Чтобы указать другое расположение или имя двоичного файла, задайте переменную инвентаризации ansible_winrm_kinit_cmd с полным путем к двоичному файлу MIT krbv5, kinit совместимым с ним.

Устранение неполадок подключений Kerberos

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

Убедитесь, что прямой и обратный DNS-поиски работают правильно в вашем домене.

Для проверки выполните ping хоста Windows, который вы хотите контролировать, по имени, а затем используйте полученный IP-адрес с nslookup. При использовании nslookup с IP-адресом вы должны получить то же имя из DNS.

Если вы получаете другие имена хостов, чем имя, которое вы изначально выполнили ping, обратитесь к администратору Active Directory и попросите проверить, включена ли функция DNS Scavenging, и DNS и DHCP обновляют друг друга.

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

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

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

kinit -C user@MY.DOMAIN.COM
klist

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

CredSSP

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

Установка requests-credssp

Для установки credssp вы можете использовать pip для установки библиотеки requests-credssp:

pip install pywinrm[credssp]

CredSSP и TLS 1.2

CredSSP требует, чтобы на удаленном хосте была настроена TLS 1.2, иначе подключение будет прервано. TLS 1.2 устанавливается по умолчанию начиная с сервера 2012 и Windows 8. Для серверов 2008, 2008 R2 и Windows 7 вы можете добавить поддержку TLS 1.2 следующим образом:

• Установка обновления TLS 1.2 от Microsoft здесь
• Добавление ключей реестра TLS 1.2, как показано на этой странице

Делегирование учетных данных

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

Инвентаризация

Поддержка Windows в Ansible опирается на несколько стандартных переменных для указания имени пользователя, пароля и типа подключения (Windows) удаленных хостов. Эти переменные проще всего настроить в инвентаризации. Она используется вместо SSH-ключей или паролей, обычно передаваемых в Ansible:

[windows]
winserver1.example.com
winserver2.example.com

В group_vars/windows.yml, определите следующие переменные инвентаризации:

# it is suggested that these be encrypted with ansible-vault:
# ansible-vault edit group_vars/windows.yml

ansible_user: Administrator
ansible_password: SecretPasswordGoesHere
ansible_port: 5986
ansible_connection: winrm
# The following is necessary for Python 2.7.9+ (or any older Python that has backported SSLContext, eg, Python 2.7.5 on RHEL7) when using default WinRM self-signed certificates:
ansible_winrm_server_cert_validation: ignore

Обратите внимание на старые стили переменных (ansible_ssh_*): ansible_ssh_password не существует, должна быть ansible_ssh_pass.

Хотя Ansible в основном ориентирован на SSH, управление Windows не будет происходить через SSH (пока).

Если вы установили модуль kerberos и ansible_user содержит @ (например, username@realm), Ansible сначала попытается выполнить аутентификацию Kerberos. Этот метод использует пользователя, с которым вы аутентифицированы в Kerberos на управляющей машине, а не ansible_user. Если это не удастся, либо потому, что вы не вошли в Kerberos на управляющей машине, либо потому, что соответствующая учетная запись домена на удаленном хосте недоступна, Ansible переключится на аутентификацию по имени пользователя/паролю.

При использовании вашей книги задач не забудьте указать --ask-vault-pass, чтобы предоставить пароль для разблокировки файла.

Протестируйте свою конфигурацию, попытавшись связаться с вашими узлами Windows. Обратите внимание, что это не ICMP-пинг, а проверка канала связи Ansible, использующего удаленный доступ Windows:

ansible windows [-i inventory] -m win_ping --ask-vault-pass

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

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

Начиная с версии 2.0, поддерживаются следующие пользовательские переменные инвентаризации для дополнительной настройки подключений WinRM

• ansible_winrm_scheme: Укажите схему подключения (http или https) для использования при подключении WinRM. Ansible использует https по умолчанию, если порт не равен 5985.
• ansible_winrm_path: Укажите альтернативный путь к точке входа WinRM. Ansible использует /wsman по умолчанию.
• ansible_winrm_realm: Укажите домен для использования в аутентификации Kerberos. Если имя пользователя содержит @, Ansible будет использовать часть имени пользователя после @ по умолчанию.
• ansible_winrm_transport: Укажите один или несколько транспортов в виде списка, разделенного запятыми. По умолчанию Ansible использует kerberos,plaintext, если модуль kerberos установлен и определен домен, в противном случае plaintext.
• ansible_winrm_server_cert_validation: Укажите режим проверки сертификата сервера (ignore или validate). Ansible по умолчанию использует validate в Python 2.7.9 и выше, что приведет к ошибкам проверки сертификатов при проверке самозаверяющих сертификатов Windows. Если на слушателях WinRM не настроены проверяемые сертификаты, это значение должно быть установлено в ignore.
• ansible_winrm_kerberos_delegation: Установите в true, чтобы включить делегирование команд на удаленном хосте при использовании Kerberos.
• ansible_winrm_operation_timeout_sec: Увеличьте значение по умолчанию для таймаута операций WinRM (по умолчанию: 20).
• ansible_winrm_read_timeout_sec: Увеличьте таймаут чтения WinRM, если вы сталкиваетесь с ошибками таймаута чтения (по умолчанию: 30), например, при периодических проблемах с сетью.
• ansible_winrm_*: Можно предоставить любые дополнительные ключевые параметры, поддерживаемые winrm.Protocol.

Подготовка системы Windows

Для управления вашими машинами Windows Ansible необходимо включить и настроить удаленный доступ PowerShell.

Чтобы автоматизировать настройку WinRM, вы можете запустить скрипт examples/scripts/ConfigureRemotingForAnsible.ps1 на удаленной машине в консоли PowerShell от имени администратора.

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

Передайте параметр -CertValidityDays для настройки даты истечения срока действия сгенерированного сертификата:

powershell.exe -File ConfigureRemotingForAnsible.ps1 -CertValidityDays 100

Передайте параметр -EnableCredSSP для включения CredSSP в качестве варианта аутентификации:

powershell.exe -File ConfigureRemotingForAnsible.ps1 -EnableCredSSP

Передайте параметр -ForceNewSSLCert для принудительной привязки нового SSL-сертификата к уже существующему слушателю winrm. (Избегает ошибок SSL winrm на подготовленных Windows-изображениях после изменения CN):

powershell.exe -File ConfigureRemotingForAnsible.ps1 -ForceNewSSLCert

Передайте параметр -SkipNetworkProfileCheck для настройки winrm на прослушивание интерфейсов зоны PUBLIC. (Без этого параметра скрипт завершится неудачно, если какой-либо сетевой интерфейс на устройстве находится в зоне PUBLIC):

powershell.exe -File ConfigureRemotingForAnsible.ps1 -SkipNetworkProfileCheck

Для отладки ConfigureRemotingForAnsible.ps1 записывает каждое изменение в журнал событий Windows (полезно при запуске без участия пользователя). Дополнительно можно использовать параметр -Verbose, чтобы получить больше информации о выполняемых действиях.

Переход к PowerShell 3.0 или выше

Для большинства предоставленных модулей Ansible для Windows и для выполнения вышеуказанного скрипта требуется PowerShell 3.0 или выше. Обратите внимание, что PowerShell 3.0 поддерживается только в Windows 7 SP1, Windows Server 2008 SP1 и более поздних версиях Windows.

Взяв копию Ansible, скопируйте скрипт examples/scripts/upgrade_to_ps3.ps1 на удаленный хост и запустите консоль PowerShell от имени администратора. Теперь вы будете работать с PowerShell 3 и сможете повторить попытки подключения, используя метод win_ping.

Какие модули доступны

Большинство модулей Ansible в основном предназначены для Linux/Unix-машин и произвольных веб-служб, но есть и различные модули, предназначенные только для Windows. Они перечислены в «windows» подкатегории индекса модулей Ansible.

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

• add_host
• assert
• async_status
• debug
• fail
• fetch
• group_by
• include
• include_role
• include_vars
• meta
• pause
• raw
• script
• set_fact
• set_stats
• setup
• slurp
• template (также: win_template)
• wait_for_connection

Некоторые модули могут использоваться в задачах, нацеленных на Windows, делегируя задачи на localhost, в зависимости от того, чего вы пытаетесь достичь. Например, assemble может использоваться для создания файла на вашем контроллере ansible, который затем отправляется на ваши Windows-цели с помощью win_copy.

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

- hosts: windows
  tasks:
    - script: foo.ps1 --argument --other-argument

Также модуль win_shell позволяет запускать фрагменты PowerShell в строку:

- hosts: windows
  tasks:
    - name: Remove Appx packages (and their hindering file assocations)
      win_shell: |
        Get-AppxPackage -name "Microsoft.ZuneMusic" | Remove-AppxPackage
        Get-AppxPackage -name "Microsoft.ZuneVideo" | Remove-AppxPackage

Разработчики: Поддерживаемые модули и принцип работы

Разработка модулей Ansible рассматривается в последующем разделе документации с упором на Linux/Unix. А что если вы хотите написать модули для Windows Ansible?

Для Windows модули Ansible реализованы в PowerShell. Ознакомьтесь с главами по разработке модулей для Linux/Unix, прежде чем продолжить. Модули Windows в основных и дополнительных репозиториях находятся в подкаталоге windows/. Пользовательские модули можно поместить непосредственно в каталоги Ansible library/ или в каталоги, добавленные в ansible.cfg. Документация хранится в файле .py с тем же именем. Например, если модуль называется win_ping, встроенная документация будет в файле win_ping.py, а сам код PowerShell — в файле win_ping.ps1. Посмотрите исходники, и это станет понятнее.

Модули (файлы ps1) должны начинаться следующим образом:

#!powershell
# <license>

# WANT_JSON
# POWERSHELL_COMMON

# code goes here, reading in stdin as JSON and outputting JSON

Эта магия необходима, чтобы Ansible мог подключать общий код и понимать, как выводить модули. Общий код содержит удобные оболочки для работы со структурами данных типа «хеш» и вывода результатов в формате JSON, а также, возможно, несколько других полезных функций. В обычном Ansible есть такая же концепция повторного использования кода Python — это просто аналог для Windows.

Модули, которые вы видите в windows/, — это только начало. Дополнительные модули могут быть представлены как запросы на добавление в репозиторий на GitHub.

Сведения о фактах Windows

Так же, как и для Linux/Unix, для хостов Windows можно собирать факты, которые вернут, например, версию операционной системы. Чтобы увидеть какие переменные доступны для хоста Windows, выполните следующее:

ansible winhost.example.com -m setup

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

Примеры Playbook для Windows

Вот пример отправки и запуска скрипта PowerShell:

- name: test script module
  hosts: windows
  tasks:
    - name: run test script
      script: files/test_script.ps1

Запуск отдельных команд использует модуль win_command <https://docs.ansible.com/ansible/win_command_module.html> или win_shell <https://docs.ansible.com/ansible/win_shell_module.html>, а не модуль shell или command, как это обычно делается в операционных системах Linux/Unix:

- name: test raw module
  hosts: windows
  tasks:
    - name: run ipconfig
      win_command: ipconfig
      register: ipconfig
    - debug: var=ipconfig

Запуск общих команд DOS, таких как del, move, или copy, вряд ли будет работать на удаленном сервере Windows с использованием Powershell, но они могут работать, если префикс команд будет CMD /C и команда будет заключена в двойные кавычки, как в этом примере:

- name: another raw module example
  hosts: windows
  tasks:
     - name: Move file on remote Windows Server from one location to another
       win_command: CMD /C "MOVE /Y C:\teststuff\myfile.conf C:\builds\smtp.conf"

Для более читаемого playbook можно использовать эквиваленты команд DOS в PowerShell. Например, чтобы добиться такого же эффекта, как в примере выше, можно использовать:

- name: another raw module example demonstrating powershell one liner
  hosts: windows
  tasks:
     - name: Move file on remote Windows Server from one location to another
       win_command: Powershell.exe "Move-Item C:\teststuff\myfile.conf C:\builds\smtp.conf"

Помните, что использование win_command или win_shell всегда будет сообщать changed, и вам нужно будет гарантировать, что PowerShell должным образом обработает идемпотентность (приведенные примеры перемещения по своей природе не идемпотентны), поэтому по возможности используйте (или напишите) модуль.

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

- name: test stat module
  hosts: windows
  tasks:
    - name: test stat module on file
      win_stat: path="C:/Windows/win.ini"
      register: stat_file

    - debug: var=stat_file

    - name: check stat_file result
      assert:
          that:
             - "stat_file.stat.exists"
             - "not stat_file.stat.isdir"
             - "stat_file.stat.size > 0"
             - "stat_file.stat.md5"

Вклад в Windows

Поддержка Windows в Ansible все еще относительно нова, и вклад в нее весьма приветствуется, будь то новые модули, изменения в существующих модулях, документация или что-то еще. Если вы хотите принять участие и поздороваться, посетите список рассылки ansible-devel.