Использование 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: https://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: https://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-операционной системы во многих аспектах. Одно из основных изменений — переход от / в качестве разделителя путей к \. Это может привести к значительным проблемам при написании playbooks, поскольку \ часто используется в качестве escape-символа в POSIX-системах.

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

Стиль YAML

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

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

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

• \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"

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

---
- name: Copy tomcat config
  win_copy:
    src: log4j.xml
    dest: '{{tc_home}}\lib\log4j.xml'

Стиль legacy key=value

Синтаксис legacy key=value используется в командной строке для adhoc команд или внутри 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{...} – Символ Unicode по имени

Это означает, что обратная косая черта является 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 для получения дополнительной информации.