Cuando se usa Ansible para administrar Windows, muchas de las sintaxis y reglas que se aplican a los hosts Unix / Linux también se aplican a Windows, pero aún existen algunas diferencias cuando se trata de componentes como separadores de ruta y tareas específicas del sistema operativo. Este documento cubre detalles específicos sobre el uso de Ansible para Windows.

  • Casos de uso

    • Instalación de software
    • Instalando actualizaciones

    • Configurar usuarios y grupos

      • Local
      • Dominio

    • Ejecución de comandos

      • Elegir comando o shell
      • Reglas de argumentos
    • Crear y ejecutar una tarea programada

  • Formato de ruta para Windows

    • Estilo YAML
    • Estilo de clave = valor heredado
  • Limitaciones
  • Desarrollo de módulos de Windows

Casos de uso

Ansible se puede utilizar para organizar una multitud de tareas en los servidores de Windows. A continuación, se muestran algunos ejemplos e información sobre tareas comunes.

Instalación de software

Hay tres formas principales en las que Ansible se puede utilizar para instalar software:

  • Utilizando el win_chocolatey módulo. Esto obtiene los datos del programa del público predeterminado Chocolatey repositorio. En su lugar, se pueden utilizar repositorios internos configurando el source opción.
  • Utilizando el win_package módulo. Esto instala el software mediante un instalador MSI o .exe desde una ruta de red o local o URL.
  • Utilizando el win_command o win_shell módulo para ejecutar un instalador manualmente.

los win_chocolatey Se recomienda el módulo ya que tiene la lógica más completa para verificar si un paquete ya se ha instalado y está actualizado.

A continuación, se muestran algunos ejemplos del uso de las tres opciones para instalar 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:temp7z.msi

-name: Ensure 7-Zip is installed via win_package
  win_package:path: C:temp7z.msi
    state: present

-name: Ensure 7-Zip is not installed via win_package
  win_package:path: C:temp7z.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:temp7z.msi

-name: Check if 7-Zip is already installed
  win_reg_stat:name: HKLM:SOFTWAREMicrosoftWindowsCurrentVersionUninstall23170F69-40C1-2702-1701-000001000000register: 7zip_installed

-name: Ensure 7-Zip is installed via win_command
  win_command: C:WindowsSystem32msiexec.exe /i C:temp7z.msi /qn /norestart
  when: 7zip_installed.exists == false

-name: Ensure 7-Zip is uninstalled via win_command
  win_command: C:WindowsSystem32msiexec.exe /x 23170F69-40C1-2702-1701-000001000000 /qn /norestart
  when: 7zip_installed.exists == true

Algunos instaladores como Microsoft Office o SQL Server requieren la delegación de credenciales o el acceso a componentes restringidos por WinRM. El mejor método para evitar estos problemas es utilizar become con la tarea. Con become, Ansible ejecutará el instalador como si se ejecutara de forma interactiva en el host.

Nota

Muchos instaladores no devuelven correctamente la información de error a través de WinRM. En estos casos, si se ha verificado que la instalación funciona localmente, el método recomendado es usar Become.

Nota

Algunos instaladores reinician los servicios WinRM o HTTP, o hacen que no estén disponibles temporalmente, lo que hace que Ansible asuma que el sistema no está disponible.

Instalando actualizaciones

los win_updates y win_hotfix Los módulos se pueden utilizar para instalar actualizaciones o revisiones en un host. El módulo win_updates se utiliza para instalar varias actualizaciones por categoría, mientras que win_hotfix se puede utilizar para instalar una única actualización o un archivo de revisión que se haya descargado localmente.

Nota

los win_hotfix El módulo tiene el requisito de que estén presentes los cmdlets de DISM PowerShell. Estos cmdlets solo se agregaron de forma predeterminada en Windows Server 2012 y versiones posteriores y deben instalarse en hosts de Windows más antiguos.

El siguiente ejemplo muestra cómo win_updates puede ser usado:

-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

El siguiente ejemplo muestra cómo win_hotfix se puede utilizar para instalar una única actualización o revisión:

-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:tempKB3172729.msu

-name: Install hotfix
  win_hotfix:hotfix_kb: KB3172729
    source: C:tempKB3172729.msu
    state: present
  register: hotfix_result

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

Configurar usuarios y grupos

Ansible se puede utilizar para crear usuarios y grupos de Windows tanto localmente como en un dominio.

Local

Los modulos win_user, win_group y win_group_membership administrar usuarios, grupos y membresías de grupos de Windows localmente.

El siguiente es un ejemplo de creación de cuentas y grupos locales que pueden acceder a una carpeta en el mismo host:

-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_expires: yes
  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: yes
    state: absent

Dominio

Los modulos win_domain_user y win_domain_group gestiona usuarios y grupos en un dominio. El siguiente es un ejemplo de cómo garantizar que se cree un lote de usuarios de dominio:

-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
  loop:-name: Test User
    password: Password
  -name: Admin User
    password: SuperSecretPass01
  -name: Dev User
    password:'@fvr3IbFBujSRh!3hBg%wgFucD8^x8W5'

Ejecución de comandos

En los casos en los que no hay un módulo apropiado disponible para una tarea, se puede ejecutar un comando o script usando el win_shell, win_command, raw, y script módulos.

los raw módulo simplemente ejecuta un comando de Powershell de forma remota. Ya que raw no tiene ninguno de los envoltorios que Ansible usa normalmente, become, async y las variables de entorno no funcionan.

los script El módulo ejecuta un script desde el controlador Ansible en uno o más hosts de Windows. Igual que raw, script actualmente no es compatible become, asynco variables de entorno.

los win_command El módulo se utiliza para ejecutar un comando que es un archivo ejecutable o por lotes, mientras que el win_shell El módulo se usa para ejecutar comandos dentro de un shell.

Elegir comando o shell

los win_shell y win_command Los módulos se pueden usar para ejecutar un comando o comandos. los win_shell El módulo se ejecuta dentro de un proceso similar a un shell como PowerShell o cmd, por lo que tiene acceso a operadores de shell como <, >, |, ;, &&, y ||. Los comandos de varias líneas también se pueden ejecutar en win_shell.

los win_command módulo simplemente ejecuta un proceso fuera de un shell. Todavía puede ejecutar un comando de shell como mkdir o New-Item pasando los comandos de shell a un ejecutable de shell como cmd.exe o PowerShell.exe.

Aquí hay algunos ejemplos de uso win_command y 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

Nota

Algunos comandos como mkdir, del, y copy solo existen en el shell CMD. Para ejecutarlos con win_command deben tener el prefijo cmd.exe /c.

Reglas de argumentos

Al ejecutar un comando a través win_command, se aplican las reglas de argumentos estándar de Windows:

  • Cada argumento está delimitado por un espacio en blanco, que puede ser un espacio o una pestaña.
  • Un argumento puede estar entre comillas dobles ". Todo lo que esté dentro de estas comillas se interpreta como un solo argumento, incluso si contiene espacios en blanco.
  • Una comilla doble precedida por una barra invertida se interpreta como una comilla doble " y no como delimitador de argumentos.
  • Las barras invertidas se interpretan literalmente a menos que precedan inmediatamente a las comillas dobles; por ejemplo == y " == "
  • Si un número par de barras invertidas va seguido de una comilla doble, se usa una barra invertida en el argumento para cada par y la comilla doble se usa como un delimitador de cadena para el argumento.
  • Si un número impar de barras invertidas va seguido de una comilla doble, se usa una barra invertida en el argumento para cada par, y la comilla doble se escapa y se convierte en una comilla doble literal en el argumento.

Con esas reglas en mente, aquí hay algunos ejemplos de citas:

-win_command: C:tempexecutable.exe argument1 "argument 2" "C:pathwith space" "double "quoted""

argv[0] = C:tempexecutable.exe
argv[1] = argument1
argv[2] = argument 2
argv[3] = C:pathwith space
argv[4] = double "quoted"

-win_command: '"C:Program FilesProgramprogram.exe" "escaped \" backslash" unquoted-end-backslash'

argv[0] = C:Program FilesProgramprogram.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:tempexecutable.exe C:nospacepath "arg with end  before end quote% raw %\% endraw %"

argv[0] = C:tempexecutable.exe
argv[1] = C:nospacepath
argv[2] = arg with end  before end quote"

Para más información, ver escapando de argumentos.

Crear y ejecutar una tarea programada

WinRM tiene algunas restricciones que causan errores al ejecutar ciertos comandos. Una forma de eludir estas restricciones es ejecutar un comando a través de una tarea programada. Una tarea programada es un componente de Windows que brinda la capacidad de ejecutar un ejecutable en una programación y con una cuenta diferente.

La versión 2.5 de Ansible agregó módulos que facilitan el trabajo con tareas programadas en Windows. El siguiente es un ejemplo de ejecución de un script como una tarea programada que se borra después de ejecutarse:

-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:temptest -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:12delay:10

Nota

Los módulos utilizados en el ejemplo anterior se actualizaron / agregaron en Ansible versión 2.5.

Formato de ruta para Windows

Windows se diferencia de un sistema operativo POSIX tradicional en muchos aspectos. Uno de los principales cambios es el cambio de / como el separador de ruta para . Esto puede causar problemas importantes con la forma en que se escriben los libros de jugadas, ya que se utiliza a menudo como carácter de escape en los sistemas POSIX.

Ansible permite dos estilos diferentes de sintaxis; cada uno trata con los separadores de ruta para Windows de manera diferente:

Estilo YAML

Cuando se usa la sintaxis YAML para tareas, las reglas están bien definidas por el estándar YAML:

  • Cuando se usa una cadena normal (sin comillas), YAML no considerará la barra invertida como un carácter de escape.
  • Al usar comillas simples ', YAML no considerará la barra invertida como un carácter de escape.
  • Al usar comillas dobles ", la barra invertida se considera un carácter de escape y debe escaparse con otra barra invertida.

Nota

Solo debe citar cadenas cuando sea absolutamente necesario o requerido por YAML, y luego use comillas simples.

La especificación YAML considera lo siguiente secuencias de escape:

  • , \, ", _, a, b, e, f, n, r, t, v, L, N y P - Escape de un solo personaje
  • , , , , - Caracteres especiales
  • x.. - Escape hexadecimal de 2 dígitos
  • u.... - Escape hexadecimal de 4 dígitos
  • U........ - Escape hexadecimal de 8 dígitos

A continuación, se muestran algunos ejemplos sobre cómo escribir rutas de Windows:

# GOODtempdir: C:WindowsTemp

# WORKStempdir:'C:WindowsTemp'tempdir:"C:\Windows\Temp"# BAD, BUT SOMETIMES WORKStempdir: C:\Windows\Temp
tempdir:'C:\Windows\Temp'tempdir: C:/Windows/Temp

Este es un ejemplo que fallará:

# FAILS
tempdir: "C:WindowsTemp"

Este ejemplo muestra el uso de comillas simples cuando son necesarias:

---
- name: Copy tomcat config
  win_copy:
    src: log4j.xml
    dest: 'tc_homeliblog4j.xml'

Estilo de clave = valor heredado

El legado key=value La sintaxis se usa en la línea de comandos para comandos ad hoc o dentro de los libros de jugadas. Se desaconseja el uso de este estilo en los libros de jugadas porque los caracteres de barra invertida deben escaparse, lo que hace que los libros de jugadas sean más difíciles de leer. La sintaxis heredada depende de la implementación específica en Ansible, y las citas (tanto simples como dobles) no tienen ningún efecto sobre cómo es analizado por Ansible.

El analizador Ansible key = value parse_kv () considera las siguientes secuencias de escape:

  • , ', ", a, b, f, n, r, t y v - Escape de un solo personaje
  • x.. - Escape hexadecimal de 2 dígitos
  • u.... - Escape hexadecimal de 4 dígitos
  • U........ - Escape hexadecimal de 8 dígitos
  • N... - Carácter Unicode por nombre

Esto significa que la barra invertida es un carácter de escape para algunas secuencias y, por lo general, es más seguro escapar de una barra invertida cuando está en esta forma.

A continuación, se muestran algunos ejemplos del uso de rutas de Windows con el estilo clave = valor:

# GOOD
tempdir=C:\Windows\Temp

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

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

# FAILS
tempdir=C:Windowstemp
tempdir='C:Windowstemp'
tempdir="C:Windowstemp"

Los ejemplos fallidos no fallan rotundamente, sino que sustituirán t con el personaje que resulta en tempdir ser C:Windowsemp.

Limitaciones

Algunas cosas que no puedes hacer con Ansible y Windows son:

  • Actualizar PowerShell
  • Interactuar con los oyentes de WinRM

Debido a que WinRM depende de que los servicios estén en línea y se ejecuten durante las operaciones normales, no puede actualizar PowerShell ni interactuar con los oyentes de WinRM con Ansible. Ambas acciones harán que la conexión falle. Esto se puede evitar técnicamente utilizando async o una tarea programada, pero esos métodos son frágiles si el proceso que ejecuta rompe la conexión subyacente que utiliza Ansible, y es mejor dejarlo para el proceso de arranque o antes de que se cree una imagen.

Desarrollo de módulos de Windows

Debido a que los módulos de Ansible para Windows están escritos en PowerShell, las guías de desarrollo para los módulos de Windows difieren sustancialmente de las de los módulos estándar estándar. Por favor mira Tutorial de desarrollo de módulos de Windows para más información.

Ver también

Introducción a los libros de jugadas

Introducción a los libros de jugadas

Consejos y trucos

Consejos y trucos para libros de jugadas

Lista de módulos de Windows

Lista de módulos específicos de Windows, todos implementados en PowerShell

Lista de correo de usuarios

¿Tengo una pregunta? ¡Pasa por el grupo de google!

irc.freenode.net

#ansible canal de chat de IRC