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: 5986 ansible_connection: winrm # The following is necessary for Python 2.7.9+ (or any older Python that has backported SSLContext, eg, Python 2.7.5 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
orhttps
) 。 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
orvalidate
)。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 100
傳遞-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。