【Ansible 文档】【译文】Windows 支持

see also：List of Windows Modules

Windows Support Windows 支持

Windows: How Does It Work Windows：如何工作

正如已经知道的，Ansible默认使用SSH管理Linux/unix。

自从1.7版本开始，Ansible同样包含了对Windows机器管理的支持。这是用本地的powershell远程，而不是SSH。

Ansible仍然在Linux控制机上运行，并且使用“winrm” Python模块来与远端主机通信。尽管不被微软或者Ansible支持，Linux控制机可以是一个Windows subsystem for linux（WSL） bash shell 支持。

远端主机无需额外的软件安装，Ansible仍然保留了agentless的架构，以维持它在linux/Unix上的流行度。

注意，这里需要你对Ansible有一个基本的了解，如果你对写一个linux的playbook还不了解，也许你应该先去了解以下。

Installing on the Control Machine 控制机上的安装

在一台linux控制机上执行：

pip install "pywinrm>=0.2.2"

你也可以使用Windows控制机，但是这需要使用 Windows Subsystem for Linux (WSL) bash shell。

注意：

　　使用a Windows Subsystem for Linux (WSL) bash shell 运行Ansible不是项目的目标，不支持这个特性是因为它限制了技术、特性和我们在主项目中使用的代码。

　　Windows Subsystem for Linux (Beta) 不被微软或Ansible支持，并且不应该在生产环境上使用

如果你想要实验 Windows Subsystem for Linux (WSL)，首先启用Windows Subsystem for Linux，按照these instructions。这需要重启

Ansible也可以运行在cygwin，但是安装太麻烦，且功能性还不能确定是否有用。

综上，最好是在linux主机上运行控制机。

Authentication Options 认证选项

当连接到一个Windows主机，有许多认证选项可以使用。选项和特性如下表：

Option	Local Accounts	Active Directory Accounts	Credential Delegation
Basic	Yes	No	No
Certificate	Yes	No	No
Kerberos	No	Yes	Yes
NTLM	Yes	Yes	No
CredSSP	Yes	Yes	Yes

　　

你可以指定你希望使用的哪一个认证选项，通过设置 ansible_winrm_transport 变量。

Certificate

certificate 认证是类似于SSH，一个certificate被分配给本地用户并且代替输入密码的方式，认证一个证书来替代。

Kerberos

当使用一个活动账户来的NTLM，kerberos 是一个更好的选项。但是这需要控制机一点额外的设置。需要在控制主上安装 “python-kerberos” 模块，及它依赖的the MIT krb5模块。Ansible控制机同样要求恰当的配置电脑账户，在活动目录中。

Installing python-kerberos dependencies

# 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

Installing python-kerberos

一旦你安装了依赖，你可以通过pip来安装python-kerberos

pip install pywinrm[kerberos]

在OS X和许多linux发行版，Kerberos 默认已经安装了。如果你的控制机还没有完成，你需要完成它。

《kerberos不懂，翻译困难，暂时不做了，如果需要的自行查看文档》

《对于我来说，我用basic就可以了，直接使用本地账户，哪来那么多事儿》

CredSSP

credSSP 认证可以被用来认证域账户和本地账户。它允许账户代理

Inventory 主机清单

Ansible的Windows支持依赖一些标准变量来指出 远程主机的  username, password, and connection type (windows)。

这些变量可以很容易的在inventory中设置。在Ansible中，这被用来代替SSH-Keys或者密码输入。

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

在 group_vars/windows.yml,定义如下 inventory 变量：

# 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:
ansible_connection: winrm
# The following is necessary for Python 2.7.+ (or any older Python that has backported SSLContext, eg, Python 2.7. 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 包含 @ (e.g. username@realm)， Ansible会先尝试Kerberos认证。这将使用你已经在控制机上认证到Kerberos 的用户信息，而不是ansible_user 。如果这失败了，要么是因为你没有在管理机上签署(signed into)Kerberos，要么是因为远程主机上对应的域帐户不可用，接着 Ansible 将返回原始(“plain”)username/password的认证方式。

当你使用playbook时，不要忘记指定--ask-vault-pass来解锁文件。

使用如下命令来测试你的配置，尝试连接你的 Windows 节点。注意：这不是ICMP ping，只是利用 Windows 远程工具来检测 Ansible 的信道是否正常：

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

如果你还没有准备好你的系统，这不会工作的。如何配置Windows机器的powershell远程，而且如果必要，需要升级到powershell3以上，这在后续描述。

你可以稍后再执行该命令，以确保一切都能正常工作。

自从Ansible2.0开始，下面自定义的inventory变量同样支持winrm连接的额外配置。

• ansible_winrm_scheme: 指定用于WinRM连接的连接模式 (http or https) 。 Ansible 默认使用https，除非端口是5985。
• ansible_winrm_path: 指定可选的路径到WinRM端点。 Ansible 默认使用 /wsman 。
• ansible_winrm_realm: 指定用于 Kerberos authentication 的 realm 。如果用户名包含 @， Ansible 默认会使用用户名@后的部分。
• ansible_winrm_transport: 指定一个或者多个协议，以逗号分隔。默认地， Ansible 将使用 kerberos，plaintext 如果 kerberos 模块被安装了，并且一个realm已经定义，否则将使用 plaintext。
• ansible_winrm_server_cert_validation: 指定服务器认证验证模式 (ignore or validate)。Ansible 在Python 2.7.9之后版本默认会验，对于Windows自签名证书来说，这将会导致证书验证错误。除非合法证书已经配置在WinRM监听器，否则应该被设置为ignore。
• ansible_winrm_kerberos_delegation: 当使用kerberos时，设为 true 来启用远端主机上的命令代理。
• ansible_winrm_operation_timeout_sec: 增加WinRM操作的超时，默认20。
• ansible_winrm_read_timeout_sec: 增加WinRM读取超时，如果你正在经历读取超时错误，默认30。例如 间歇性的网络问题。
• ansible_winrm_*: 任何被winrm.Protocol 提供支持的额外的关键字参数。

Windows System Prep Windows 系统前期准备

为了可以Ansible管理你的Windows机器，你必须启用并配置PowerShell远程。

为了自动化设置WinRM，你可以在远端机器上执行 examples/scripts/ConfigureRemotingForAnsible.ps1脚本，以管理员权限打开PowerShell控制台执行脚本。

这个例子脚本接收一些参数，管理员可以选择稍微修改默认的配置，在某些情况下，这是合适的。

传递 -CertValidityDays 选项来自定义产生的证书过期日期：

powershell.exe -File ConfigureRemotingForAnsible.ps1 -CertValidityDays 

传递-EnableCredSSP 选项来启用CerdSSP作为认证选项：

powershell.exe -File ConfigureRemotingForAnsible.ps1 -EnableCredSSP

传递 -ForceNewSSLCert 开关强制使用一个新的SSL证书，该证书被用来绑定到已经存在的winrm listenner。

powershell.exe -File ConfigureRemotingForAnsible.ps1 -ForceNewSSLCert

传递 -SkipNetworkProfileCheck 开关来配置winrm来监听PUBLIC zone interfaces（没有这个选项的话，如果有任何设备在PUBLIC zone，脚本会失败）

powershell.exe -File ConfigureRemotingForAnsible.ps1 -SkipNetworkProfileCheck

为了故障排除，ConfigureRemotingForAnsible.ps1 将写入每个变化到Windows EventLog。（useful when run unattendedly）

额外的选项 -verbose 可以用来展示更多的信息到屏幕上，关于正在执行什么。

注意：

　　在Window 7和Window2008 R2机器，因为Windows 管理框架的BUG，有必要安装热修复补丁，http://support.microsoft.com/kb/2842230来避免内存和堆栈异常。新安装的Windows 2008 R2系统没有升级到最新版本的均存在这个问题。

　　Windows 8.1 and Server 2012 R2 不受影响是因为他们自身默认使用的是 Windows Management Framework 4.0。

　　PS 阿里云机器不会有这样的问题。

Getting to PowerShell 3.0 or higher 获取PowerShell 3.0或者更高版本

PowerShell 3.0 or higher对于大部分Windows模块都是需要的，并且也需要运行上面的脚本。注意，PowerShell 3.0仅支持 Windows 7SP1以及Windows Server 2008 SP1，以及后续版本

找到 Ansible 的checkout版本，复制  examples/scripts/upgrade_to_ps3.ps1 版本到远程主机，并且以管理员权限在PowerShell 控制台运行。就可以运行 PowerShell 3 并可以通过上面介绍的 win_ping 技术来测试连通性。

What modules are available 什么模块是可用的

大部分Ansible core中的模块是为了组合Linux/Unix机器和任意web服务而写的，尽管仍然有各种不同的Windows专用模块。

“windows” subcategory of the Ansible module index 可以查看Windows Ansible模块索引

此外，下面的core模块/action-plugins同样可以在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 (also: win_template)
• wait_for_connection

通过代理到localhost，一些模块可以在目标主机为windows机器的playbook中使用，这取决于你想要获得什么。例如assemble 被用来在你的Ansible主机上创建一个文件，然后发送到你的windows目的主机，使用win_copy。

很多时候，没有必要使用或者写一个Ansible模块。特别的，script模块可以被用来运行任意的PowerShell脚本，允许熟悉PowerShell的Windows管理员以非常原生的方式做任何事情。就像如下的 playbook:

- 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

Developers: Supported modules and how it works 开发者：支持模块以及工作原理

开发Ansible模块在 later section of the documentation描述，这关注点在于linux/unix。如果要写windows模块该怎么办？

对于windows来说，Ansible模块主要用PowerShell来实现，在继续之前，掠过linux/unix开发章节。windows模块

core和extras库中的windows模块在windows子目录中。自定义模块可以直接放到Ansible的library/中或者那些在ansible.cfg中添加的目录。文档存在一个.py文件中，使用相同的名字。例如，如果一个模块名为win_ping，那么就会嵌入文档在win_ping.py文件中，并且实际的PowerShell代码存在一个win_ping.ps1文件中。看一看源码，这样会更清晰。

Modules （ps1文件），应该如下开始：

#!powershell
# <license>

# WANT_JSON
# POWERSHELL_COMMON

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

上面的魔法是必要的，告诉Ansible混入一些common code，并且也知道如何输出模块输出（push modules out ）。common code 包含一些好的围绕hash数据结构非封装看，并且发出JSON结果，以及一些有用的结果。常规 Ansible 有着重复利用 Python 代码的理念 - 这点 Windows 也是等同的。

你在 windows/ 目录中看到的模块仅是一个开始，附加模块已经被 git push 到 github上了。

提醒:控制机必须是Linux系统

Windows 控制机不是这个项目的目标. Ansible 不会开发这个功能,因为受限于技术,产品和我们未来主要项目使用的代码. 一台Linux控制机是必须的,可以用来管理 Windows 机器. Cygwin 也是不被支持的,所以请不要要求 Ansible 基于 Cygwin 来运行.

Windows Facts windows facts

如linux/unix一样，facts也可以用于收集windows facts，其包含如操作系统版本这样的东西。为了查看一个windows主机的变量，运行下面的命令：

ansible winhost.example.com -m setup

注意，这个命令的调用方式和 Linux/Unix 是一样的。

Windows Playbook Examples windows playbook举例

这里有一个推送和运行一个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> 模块，对应和linux/Unix操作系统的shell和command模块

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

运行普通的DOS命令像del，move，或者copy，这些在远程服务器中的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"

你也可以通过PowerShell写一个与DOS命令等价的、更加具有可读性的playbook。例如，上面的例子你也可以如下操作：

- 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 or win_shell 总是会报告 “changed”，并且，你有责任来确保PowerShell可以按照预期恰当地处理幂等性（上面的move例子隐含就不会是幂等的），因此可能会使用到模块或者写一个模块。

以下是一个如何使用“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 Contributions windows贡献

Ansible中的windows支持仍然是比较新的，欢迎贡献。无论是新的模块、现有模块的调整、文档、或者其他的什么。如果你愿意参与，请访问（stop by）Ansible开发邮件列表，say hi。

Developing Modules

List of Windows Modules