未经书面许可，。请勿转载

Custom Modules
Until now we have been working solely with the tools provided to us by Ansible.
This does afford us a lot of power, and make many things possible. However, if you
have something particularly complex or if you find yourself using the script module
a lot, you will probably want to learn how to extend Ansible.
In this chapter you will learn the following topics:
?	 How to write modules in Bash scripting or Python
?	 Using custom modules that you have developed
?	 Writing a script to use an external data source as an inventory
Often when you approach something complex in Ansible, you write a script module.
The issue with script modules is that you can't process their output, or trigger
handlers based on their output easily. So, although the script module works in some
cases, using a module can be better.
Use a module instead of writing a script when:
?	 You don't want to run the script every single time
?	 You need to process the output
?	 Your script needs to make facts
?	 You need to send complex variables as arguments

第五章 自己定义模块

此前我们一直使用Ansible自带的模块，这已经给我们提供了非常多非常强的‘自带的电池’。可是假设你有一些特殊又复杂的任务，你可能会希望学习一下怎样扩展Anisble。本章你将学习到下面主题：

• 在python或则bash中编写模块
• 使用你开发的自己定义模块
• 写一个脚本来利用外部数据源作为设备清单库inventory

当使用Anisble的方法很复杂的时候，你可能会编写一个脚本模块。脚本模块的缺点是你不能输出他们的运行过程，或则依据他们的输出来出发Handler程序。所以有些时候能够使用脚本模块。有些时候还是使用自带模块会更好！

下面场景不是非常适合脚本模块：

• 不要在每次执行的时候都用脚本
• 当须要使用输出结果的时候
• 你的脚本须要fact的时候
• 当须要传递过于复杂的变量作为參数的时候

If you want to start writing modules, you should check ( )out the Ansible repository.
If you want your module to work with a particular version, you should also switch
to that version to ensure compatibility. The following commands will set you up to
develop modules for Ansible 1.3.0. Checking out the Ansible code gives you access
to a handy script that we will use later to test our modules. We will also make this
script executable in anticipation of its use later in the chapter.
$ git clone (https://github.com/ansible/ansible.git)
$ cd ansible
$ git checkout v1.3.0
$ chmod +x hacking/test-module

在開始写模块之前。你最好检查一下Ansble的版本号库。假设你希望你的模块在一个特殊的版本号中执行，你须要切换到对应的版本号去开发。

以下的命令能够让你升级到Ansible1.3.0的开发模块。通过Anisble代码能够找到一个简单的脚本来測试我们的模块。

给这个脚本赋于可执行权限。方便后面的章节使用

$ git clone (https://github.com/ansible/ansible.git)
$ cd ansible
$ git checkout v1.3.0
$ chmod +x hacking/test-module

Writing a module in Bash
Ansible allows you to write modules in any language that you prefer. Although
most modules in Ansible work with JSON, you are allowed to use shortcuts if you
don't have any JSON parsing facilities available. Ansible will hand you arguments
in their original key value forms, if they were provided in that format. If complex
arguments are provided, you will receive JSON-encoded data. You could parse this
using something like jsawk ( https://github.com/micha/jsawk ) or jq ( http://
stedolan.github.io/jq/ ), but only if they are installed on your remote machine.

Ansible doesn't yet have a module that lets you change the hostname of a system
with the hostname command. So let's write one. We will start just printing the
current hostname and then expand the script from there. Here is what that simple
module looks like:
#!/bin/bash
HOSTNAME="$(hostname)"
echo "hostname=${HOSTNAME}"

在bash中编写模块

Ansible同意你使用你喜欢的不论什么语言来编写模块。尽管大部分模块使用JSON，可是假设你没有不论什么JSON解析器的话你还是能够使用简短格式。

假设你的參数格式是KEY VALUS形式，Ansible能够处理他们。假设是更加复杂的參数，你会受到JSON编码的数据，你能够使用JSAWK或则JQ来解析。但你要确保你的远程受管主机也安装了他们。

Anisble如今还没有能够改变系统主机名的模块，让我们就从这開始吧！先写一个简单的脚本来显示主机。后面我们再来扩张它。代码例如以下：

#!/bin/bash
HOSTNAME="$(hostname)"
echo "hostname=${HOSTNAME}"

If you have written Bash scripts before, this should seem extremely basic. Essentially
what we are doing is grabbing the hostname and printing it out in a key value form.
Now that we have written the first cut of the module, we should test it out.
To test the Ansible modules, we use the script that we ran the chmod command on
earlier. This command simply runs your module, records the output, and returns
it to you. It also shows how Ansible interpreted the output of the module. The
command that we will use looks like the following:
ansible/hacking/test-module -m ./hostname

假设你之前有写过bash脚本。你会发现这是非常基础的。我们仅仅是获取主机名然后用KEY VALUS的格式打印出来而已。

如今我们已经完毕了模块的第一个部分。让我们来測试下。

要測试模块的话，我们仅仅须要使用之前赋权的检測脚本。

这个命令运行你的模块，记录输出。返回给你。它还展示了Anisble怎样解释模块的输出。命令例如以下：

ansible/hacking/test-module -m ./hostname

The output of the previous command should look like this:
* module boilerplate substitution not requested in module, line
numbers will be unaltered
***********************************
RAW OUTPUT
hostname=admin01.int.example.com
***********************************
PARSED OUTPUT
{
"hostname": "admin01.int.example.com"
}
Ignore the notice at the top, it does not apply to modules built with bash. You can see
the raw output that our script sent, which looks exactly the way we expected. The
test script also gives you the parsed output. In our example, we are using the short
output format and we can see here that Ansible is correctly interpreting it into the
JSON that it normally accepts from modules.

输出类似以下：

* module boilerplate substitution not requested in module, line
numbers will be unaltered
***********************************
RAW OUTPUT
hostname=admin01.int.example.com
***********************************
PARSED OUTPUT
{
"hostname": "admin01.int.example.com"
}

忽略顶部的提示，能够看到我们写的脚本的raw 输出。跟我们估计的一样。

測试脚本还解析了我们的输出，在我们的样例中。我们使用简短格式的输出，可是Ansible将他解析成跟其它模块一样的JSON格式的输出。

Let's expand out the module to allow setting the hostname . We should write it so
that it doesn't make any changes unless it is required, and lets Ansible know whether
changes were made or not. This is actually pretty simple for the small command that
we are writing. The new script should look something like this:
#!/bin/bash
set -e
# This is potentially dangerous
source ${1}
OLDHOSTNAME="$(hostname)"
CHANGED="False"
if [ ! -z "$hostname" -a "${hostname}x" != "${OLDHOSTNAME}x" ];
then
hostname $hostname
OLDHOSTNAME="$hostname"
CHANGED="True"
fi
echo "hostname=${OLDHOSTNAME} changed=${CHANGED}"
exit 0

如今，让我们来扩展我们的模块来设置主机名。代码例如以下：

#!/bin/bash
set -e
# This is potentially dangerous
source ${1}
OLDHOSTNAME="$(hostname)"
CHANGED="False"
if [ ! -z "$hostname" -a "${hostname}x" != "${OLDHOSTNAME}x" ];
then
hostname $hostname
OLDHOSTNAME="$hostname"
CHANGED="True"
fi
echo "hostname=${OLDHOSTNAME} changed=${CHANGED}"
exit 0

The previous script works like this:
1.	 We set Bash's exit on error mode, so that we don't have to deal with errors
from hostname. Bash will automatically exit on failure with its exit code. This
will signal Ansible that something went wrong.
2.	 We source the argument file. This file is passed from Ansible as the first
argument to the script. It contains the arguments that were sent to our
module. Because we are sourcing the file, this could be used to run arbitrary
commands; however, Ansible can already do this, so it's not that much of a
security issue.
3.	 We collect the old hostname and default CHANGED to False . This allows us to
see if our module needs to perform any changes.
4.	 We check if we were sent a new hostname to set, and check if that hostname
is different from the one that is currently set.
5.	 If both those tests are true, we try to change the hostname, and set CHANGED
to True .
6.	 Finally, we output the results and exit. This includes the current hostname
and whether we made changes or not.

上面的脚本运行了以下的操作：

1. 我们设定bash在遇到错误的时候退出，所以我们不想要处理来至hostname的错误。bash会自己主动退出，并输出退出代码，能够让Ansible知道错误发生了。
2. 我们source參数文件。它作为这个脚本的第一个參数，我们能够用其它的命令来source。可是既然Ansible能够做到，就能够为我们降低很多安全隐患。
3. 我们获取原来的hostname并设置CHANGED为faulse，这能够让我们的模块决定是否须要运行更改操作
4. 我们检查是否有新的hostname被设置。而且和旧的hostname不一样
5. 假设2个条件（changed參数和hostname是否反复）都为真，就设置CHANGED參数为True
6. 最后输出结果，然后退出。

   输出结果包括机器名是否已经被改变。

Changing the hostname on a Unix machine requires root privileges. So while testing
this script, you need to make sure to run it as the root user. Let's test this script using
sudo to see if it works. This is the command you will use:
sudo ansible/hacking/test-module -m ./hostname -a
'hostname=test.example.com'
If test.example.com is not the current hostname of the machine, you should get the
following as the output:
* module boilerplate substitution not requested in module, line
numbers will be unaltered
***********************************
RAW OUTPUT
hostname=test.example.com changed=True
***********************************
PARSED OUTPUT
{
"changed": true,
"hostname": "test.example.com"
}

在unix机器上改动hostname须要root权限。所以測试后脚本的时候。我们须要使用root用户来执行。測试命令例如以下：

sudo ansible/hacking/test-module -m ./hostname -a  ‘hostname=test.example.com‘  

假设当前主机名不是test.example.com，你将得到例如以下输出：

* module boilerplate substitution not requested in module, line
numbers will be unaltered
***********************************
RAW OUTPUT
hostname=test.example.com changed=True
***********************************
PARSED OUTPUT
{
"changed": true,
"hostname": "test.example.com"
}

As you can see, our output is being parsed correctly, and the module claims that
changes have been made to the system. You can check this yourself with the
hostname command. Now, run the module for the second time with the same
hostname. You should see an output that looks like this:
* module boilerplate substitution not requested in module, line
numbers will be unaltered
***********************************
RAW OUTPUT
hostname=test.example.com changed=False
***********************************
PARSED OUTPUT
{
"changed": false,
"hostname": "test.example.com"
}
Again, we see that the output was parsed correctly. This time, however, the module
claims to not have made any changes, which is what we expect. You can also check
this with the hostname command.

我们的输出被解析的非常好，而且模块也使得改变被应用到系统上。你能够用hostname来检查。

如今，使用相同的hostname再执行一次脚本，输出例如以下：

* module boilerplate substitution not requested in module, line
numbers will be unaltered
***********************************
RAW OUTPUT
hostname=test.example.com changed=False
***********************************
PARSED OUTPUT
{
"changed": false,
"hostname": "test.example.com"
}

输出是需要解决的非常好，但是模块没有做，不管什么样的变化。您可以使用hostname再检查一遍