Использование Ansible и Windows

При использовании Ansible для управления Windows многие синтаксические конструкции и правила, применимые для хостов Unix/Linux, также применяются для Windows, но все же существуют некоторые отличия, когда дело доходит до таких компонентов, как разделители путей и задачи, специфичные для операционной системы. Этот документ описывает детали, специфичные для использования Ansible для Windows.

• Примеры использования
  • Установка программного обеспечения
  • Установка обновлений
  • Настройка пользователей и групп
    • Локальные
    • Доменные
  • Выполнение команд
    • Выбор команды или оболочки
    • Правила аргументов
  • Создание и запуск запланированной задачи
• Форматирование путей для Windows
  • Стиль YAML
  • Стиль legacy key=value
• Ограничения
• Разработка модулей для Windows

Примеры использования

Ansible может быть использован для организации множества задач на серверах Windows. Ниже приведены примеры и информация о распространенных задачах.

Установка программного обеспечения

Существует три основных способа использования Ansible для установки программного обеспечения:

• Использование модуля win_chocolatey. Он получает данные программы из стандартного публичного репозитория Chocolatey. Вместо этого можно использовать внутренние репозитории, установив опцию source.
• Использование модуля win_package. Он устанавливает программное обеспечение с помощью MSI или .exe установщиков из локального/сетевого пути или URL.
• Использование модулей win_command или win_shell для ручного запуска установщика.

Модуль win_chocolatey рекомендуется, так как он имеет наиболее полную логику проверки того, установлен ли пакет и обновлен ли он.

Ниже приведены примеры использования всех трех вариантов для установки 7-Zip:

# install/uninstall with chocolatey
- name: ensure 7-Zip is installed via Chocolatey
  win_chocolatey:
    name: 7zip
    state: present

- name: ensure 7-Zip is not installed via Chocolatey
  win_chocolatey:
    name: 7zip
    state: absent

# install/uninstall with win_package
- name: download the 7-Zip package
  win_get_url:
    url: http://www.7-zip.org/a/7z1701-x64.msi
    dest: C:\temp\7z.msi

- name: ensure 7-Zip is installed via win_package
  win_package:
    path: C:\temp\7z.msi
    state: present

- name: ensure 7-Zip is not installed via win_package
  win_package:
    path: C:\temp\7z.msi
    state: absent

# install/uninstall with win_command
- name: download the 7-Zip package
  win_get_url:
    url: http://www.7-zip.org/a/7z1701-x64.msi
    dest: C:\temp\7z.msi

- name: check if 7-Zip is already installed
  win_reg_stat:
    name: HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall\{23170F69-40C1-2702-1701-000001000000}
  register: 7zip_installed

- name: ensure 7-Zip is installed via win_command
  win_command: C:\Windows\System32\msiexec.exe /i C:\temp\7z.msi /qn /norestart
  when: 7zip_installed.exists == False

- name: ensure 7-Zip is uninstalled via win_command
  win_command: C:\Windows\System32\msiexec.exe /x {23170F69-40C1-2702-1701-000001000000} /qn /norestart
  when: 7zip_installed.exists == True

Некоторые установщики, такие как Microsoft Office или SQL Server, требуют делегирования учетных данных или доступа к компонентам, ограниченным WinRM. Лучший способ обойти эти проблемы — использовать become в задаче. С become, Ansible запустит установщик так, как будто он запускался интерактивно на хосте.

Установка обновлений

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

Следующий пример показывает, как использовать win_updates.

- name: install all critical and security updates
  win_updates:
    category_names:
    - CriticalUpdates
    - SecurityUpdates
    state: installed
  register: update_result

- name: reboot host if required
  win_reboot:
  when: update_result.reboot_required

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

- name: download KB3172729 for Server 2012 R2
  win_get_url:
    url: http://download.windowsupdate.com/d/msdownload/update/software/secu/2016/07/windows8.1-kb3172729-x64_e8003822a7ef4705cbb65623b72fd3cec73fe222.msu
    dest: C:\temp\KB3172729.msu

- name: install hotfix
  win_hotfix:
    hotfix_kb: KB3172729
    source: C:\temp\KB3172729.msu
    state: present
  register: hotfix_result

- name: reboot host if required
  win_reboot:
  when: hotfix_result.reboot_required

Настройка пользователей и групп

Ansible может использоваться для создания пользователей и групп Windows как локально, так и в домене.

Локальные

Модули win_user, win_group и win_group_membership управляют локальными пользователями, группами и членством в группах.

Следующий пример демонстрирует создание локальных учетных записей и групп, которые могут получить доступ к папке на том же хосте:

- name: create local group to contain new users
  win_group:
    name: LocalGroup
    description: Allow access to C:\Development folder

- name: create local user
  win_user:
    name: '{{item.name}}'
    password: '{{item.password}}'
    groups: LocalGroup
    update_password: no
    password_never_expired: yes
  with_items:
  - name: User1
    password: Password1
  - name: User2
    password: Password2

- name: create Development folder
  win_file:
    path: C:\Development
    state: directory

- name: set ACL of Development folder
  win_acl:
    path: C:\Development
    rights: FullControl
    state: present
    type: allow
    user: LocalGroup

- name: remove parent inheritance of Development folder
  win_acl_inheritance:
    path: C:\Development
    reorganize: yes
    state: absent

Доменные

Модули win_domain_user и win_domain_group управляют пользователями и группами в домене. Ниже приведен пример, гарантирующий создание набора доменных пользователей:

- name: ensure each account is created
  win_domain_user:
    name: '{{item.name}}'
    upn: '{{item.name}}@MY.DOMAIN.COM'
    password: '{{item.password}}'
    password_never_expires: no
    groups:
    - Test User
    - Application
    company: Ansible
    update_password: on_create
  with_items:
  - name: Test User
    password: Password
  - name: Admin User
    password: SuperSecretPass01
  - name: Dev User
    password: '@fvr3IbFBujSRh!3hBg%wgFucD8^x8W5'

Выполнение команд

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

Модуль raw просто выполняет команду Powershell удаленно. Поскольку raw не имеет обёртки, которую обычно использует Ansible, become, async и переменные окружения не работают.

Модуль script выполняет скрипт с контроллера Ansible на одном или нескольких хостах Windows. Как и raw, script в настоящее время не поддерживает become, async или переменные окружения.

Модуль win_command используется для выполнения команды, которая является исполняемым файлом или пакетным файлом, а модуль win_shell используется для выполнения команд внутри оболочки.

Выбор команды или оболочки

Модули win_shell и win_command могут быть использованы для выполнения команды или команд. Модуль win_shell выполняется в оболочке, такой как PowerShell или cmd, поэтому он имеет доступ к операторам оболочки, таким как <, >, |, ;, &&, и ||. Многострочные команды также могут быть выполнены в win_shell.

Модуль win_command просто запускает процесс вне оболочки. Он все еще может запускать командные оболочки, такие как mkdir или New-Item, передавая командные оболочки исполняемому файлу оболочки, например, cmd.exe или PowerShell.exe.

Вот несколько примеров использования win_command и win_shell:

- name: run a command under PowerShell
  win_shell: Get-Service -Name service | Stop-Service

- name: run a command under cmd
  win_shell: mkdir C:\temp
  args:
    executable: cmd.exe

- name: run a multiple shell commands
  win_shell: |
    New-Item -Path C:\temp -ItemType Directory
    Remove-Item -Path C:\temp -Force -Recurse
    $path_info = Get-Item -Path C:\temp
    $path_info.FullName

- name: run an executable using win_command
  win_command: whoami.exe

- name: run a cmd command
  win_command: cmd.exe /c mkdir C:\temp

- name: run a vbs script
  win_command: cscript.exe script.vbs

Правила аргументов

При выполнении команды через win_command, применяются стандартные правила аргументов Windows:

• Каждый аргумент ограничен пробелом, который может быть пробелом или табуляцией.
• Аргумент может быть заключен в двойные кавычки ". Все внутри этих кавычек интерпретируется как один аргумент, даже если он содержит пробелы.
• Двойная кавычка, предваряемая обратным слэшем \, интерпретируется как просто двойная кавычка " и не как разделитель аргументов.
• Обратные слэши интерпретируются буквально, если они не непосредственно предшествуют двойным кавычкам; например \ == \ и \" == ".
• Если нечетное количество обратных слэшей следует за двойной кавычкой, одно обратное на пару используется в аргументе, а двойная кавычка используется как разделитель строки для аргумента.
• Если нечетное количество обратных слэшей следует за двойной кавычкой, одно обратное на пару используется в аргументе, а двойная кавычка экранируется и становится буквальной двойной кавычкой в аргументе.

Учитывая эти правила, вот несколько примеров цитирования:

- win_command: C:\temp\executable.exe argument1 "argument 2" "C:\path\with space" "double \"quoted\""

argv[0] = C:\temp\executable.exe
argv[1] = argument1
argv[2] = argument 2
argv[3] = C:\path\with space
argv[4] = double "quoted"

- win_command: '"C:\Program Files\Program\program.exe" "escaped \\\" backslash" unqouted-end-backslash\'

argv[0] = C:\Program Files\Program\program.exe
argv[1] = escaped \" backslash
argv[2] = unquoted-end-backslash\

# due to YAML and Ansible parsing '\"' must be written as '{% raw %}\\{% endraw %}"'
- win_command: C:\temp\executable.exe C:\no\space\path "arg with end \ before end quote{% raw %}\\{% endraw %}"

argv[0] = C:\temp\executable.exe
argv[1] = C:\no\space\path
argv[2] = arg with end \ before end quote\"

Дополнительную информацию можно найти на странице экранирования аргументов.

Создание и запуск запланированной задачи

WinRM имеет некоторые ограничения, которые вызывают ошибки при выполнении определенных команд. Один из способов обойти эти ограничения — выполнить команду через запланированную задачу. Запланированная задача — это компонент Windows, который предоставляет возможность запуска исполняемого файла по расписанию и под другой учетной записью.

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

- name: create scheduled task to run a process
  win_scheduled_task:
    name: adhoc-task
    username: SYSTEM
    actions:
    - path: PowerShell.exe
      arguments: |
        Start-Sleep -Seconds 30 # this isn't required, just here as a demonstration
        New-Item -Path C:\temp\test -ItemType Directory
    # remove this action if the task shouldn't be deleted on completion
    - path: cmd.exe
      arguments: /c schtasks.exe /Delete /TN "adhoc-task" /F
    triggers:
    - type: registration

- name: wait for the scheduled task to complete
  win_scheduled_task_stat:
    name: adhoc-task
  register: task_stat
  until: (task_stat.state is defined and task_stat.state.status != "TASK_STATE_RUNNING") or (task_stat.task_exists == False)
  retries: 12
  delay: 10

Форматирование путей для Windows

Windows отличается от традиционной операционной системы POSIX во многих отношениях. Одно из основных изменений — переход от / в качестве разделителя путей к \ . Это может вызвать серьезные проблемы с тем, как написаны плейбуки, так как \ часто используется как символ экранирования в системах POSIX.

Ansible поддерживает два различных синтаксических стиля, каждый из которых по-разному обрабатывает разделители путей в Windows:

Стиль YAML

При использовании синтаксиса YAML для задач правила определяются стандартом YAML:

• При использовании обычной строки (без кавычек) YAML не рассматривает обратный слэш как символ экранирования.
• При использовании одинарных кавычек ', YAML не рассматривает обратный слэш как символ экранирования.
• При использовании двойных кавычек ", обратный слэш рассматривается как символ экранирования и должен быть экранирован другим обратным слэшем.

Спецификация YAML рассматривает следующие последовательности экранирования:

• \0, \\, \", \_, \a, \b, \e, \f, \n, \r, \t, \v, \L, \N и \P – Экранирование одиночного символа
• <TAB>, <SPACE>, <NBSP>, <LNSP>, <PSP> – Специальные символы
• \x.. – Экранирование 2-значного шестнадцатеричного кода
• \u.... – Экранирование 4-значного шестнадцатеричного кода
• \U........ – Экранирование 8-значного шестнадцатеричного кода

Вот несколько примеров записи путей Windows:

GOOD
tempdir: C:\Windows\Temp

WORKS
tempdir: 'C:\Windows\Temp'
tempdir: "C:\\Windows\\Temp"

BAD, BUT SOMETIMES WORKS
tempdir: C:\\Windows\\Temp
tempdir: 'C:\\Windows\\Temp'
tempdir: C:/Windows/Temp

FAILS
tempdir: "C:\Windows\Temp"

---
# example of single quotes when they are required
- name: copy tomcat config
  win_copy:
    src: log4j.xml
    dest: '{{tc_home}}\lib\log4j.xml'

Стиль legacy key=value

Синтаксис legacy key=value используется в командной строке для импровизированных команд или внутри playbooks. Использование этого стиля в playbooks не рекомендуется, потому что обратные слэши необходимо экранировать, что усложняет чтение playbooks. Синтаксис legacy зависит от конкретной реализации Ansible, а кавычки (одинарные и двойные) не влияют на то, как Ansible его анализирует.

Парсер Ansible key=value parse_kv() учитывает следующие escape-последовательности:

• \, ', ", \a, \b, \f, \n, \r, \t и \v – Экранирование одиночного символа
• \x.. – Экранирование 2-значного шестнадцатеричного кода
• \u.... – Экранирование 4-значного шестнадцатеричного кода
• \U........ – Экранирование 8-значного шестнадцатеричного кода
• \N{...} – Экранирование символа по имени Юникод

Это означает, что обратный слэш является escape-символом для некоторых последовательностей, и обычно безопаснее экранировать обратный слэш в этой форме.

Вот несколько примеров использования путей Windows со стилем key=value:

GOOD
tempdir=C:\\Windows\\Temp

WORKS
tempdir='C:\\Windows\\Temp'
tempdir="C:\\Windows\\Temp"

BAD, BUT SOMETIMES WORKS
tempdir=C:\Windows\Temp
tempdir='C:\Windows\Temp'
tempdir="C:\Windows\Temp"
tempdir=C:/Windows/Temp

FAILS
tempdir=C:\Windows\temp
tempdir='C:\Windows\temp'
tempdir="C:\Windows\temp"

Примеры с ошибками не приводят к полному отказу, но подставят \t вместо <TAB> символа, в результате tempdir будет C:\Windows<TAB>emp.

Ограничения

Некоторые вещи, которые вы не можете сделать с Ansible и Windows:

• Обновление PowerShell
• Взаимодействие с слушателями WinRM

Так как WinRM зависит от того, что службы активны и запущены во время обычных операций, вы не можете обновить PowerShell или взаимодействовать с слушателями WinRM с помощью Ansible. Оба этих действия приведут к отказу подключения. Это технически можно избежать, используя async или запланированную задачу, но эти методы хрупкие, если процесс, который он запускает, прерывает основное соединение, которое использует Ansible, и лучше оставить их для процесса начальной загрузки или перед созданием образа.

Разработка модулей Windows

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