Использование 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 through Chocolatey
  win_chocolatey:
    name: 7zip
    state: present

- name: Ensure 7-Zip is not installed through 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 through win_package
  win_package:
    path: C:\temp\7z.msi
    state: present

- name: Ensure 7-Zip is not installed through 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 through 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 through 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 как локально, так и в домене.

- 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: false
    password_never_expires: true
  loop:
  - 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: true
    state: absent

- name: Ensure each account is created
  win_domain_user:
    name: '{{ item.name }}'
    upn: '{{ item.name }}@MY.DOMAIN.COM'
    password: '{{ item.password }}'
    password_never_expires: false
    groups:
    - Test User
    - Application
    company: Ansible
    update_password: on_create
  loop:
  - 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 — для выполнения команд в оболочке.

- 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 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: 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" unquoted-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

Синтаксис 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"

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

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

Устаревший синтаксис key=value

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

Парсер Ansible для синтаксиса key=value parse_kv() обрабатывает следующие последовательности экранирования:

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

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

Ниже приведены примеры использования путей 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.