Cobbler API 介绍

本文英文源网站为：https://fedorahosted.org/cobbler/wiki/CobblerApi

为了方便控制cobbler 应用程序，Cobbler提供了一个基于Python 语言的API接口。

注意，Cobbler是GPL(通用语言)，若是你的应用不是GPL，而且想把它分发到公司、家等等的外面，建议你最好使用CobblerXmlrpc接口来替代它。

在2.0版本中，不推荐使用BootAPI接口来链接Cobbler，由于它采用一个可能不太安全的方式来直接修改配置存储文件，而且这个修改可能对cobbler服务不起做用。至少到了2.2的版本中CobblerXmlrpm才会被被使用。

引用：http://marc.info/?l=cobbler-devel&m=127428454504458&w=2

API的状态是不可改变的，能够经过查看https://fedorahosted.org/pipermail/cobbler/2011-November/006863.html来获取为何不可改变的缘由和详细状况。

公共API的构成

在检出的Cobbler源码中，"api.py" 中的方法是公共的API方法，除非他们方法名称如下划线开头，按照Python公约，凡是如下划线开头的均为私有方法。

若是你想在cobbler中让"iterm object"的功能工做，你也能够根据详细的对象类型在"item_*.py"调用方法。

你不该该在除了这两种状况之外再调用方法/函数。

Pydoc（python文档）

pydoc是一个有用的读取文档的工具。你能够运行下面的类来查看Python API中有用的公共方法。

pydoc cobbler.api
pydoc cobbler.item_distro
pydoc cobbler.item_profile
pydoc cobbler.item_system
pydoc cobbler.item_image
pydoc cobbler.item_repo

基本：

每一个Cobbler AP脚本都须要一个API来操控启动，因此老是这样作：

#!/usr/bin/python
import cobbler.api as capi

handle = capi.BootAPI()

这个boot API被咱们称做“单例模式”，那就意味着在你本身的线程中任什么时候候均可以调用它，而不须要把它传过来。实现上述功能只须要一些小成本（这取决于你的cobbler配置的大小），你只须要在第一次使用它的时候加载。

运行对象

这是一个贯穿全部的cobbler分发的例子。其余的对象类型（包括发行版/distros，配置/profiles，系统/systems，repos，images，网络等）的工做方式彻底相同。

#!/usr/bin/python
import cobbler.api as capi
handle = capi.BootAPI()
for x in handle.distros():
   print x.name

修改对象

下面的例子将在"example.org"下根据系统名称获取全部的机器，将它们分配给一个新的安装文件，并触发PXE网络引导标识，当它们的电源下次启动时将从新自动安装（或者升级，这种状况依赖于ks文件的配置状况）。

#!/usr/bin/python

import cobbler.api as capi

handle = capi.BootAPI()
systems = handle.find_system(name="*",return_list=True)
for s in systems:
   print "assigning system for reinstallation: %s" % s.name 
   s.netboot_enabled = True
   handle.add_system(s)

请注意，若是咱们最后不调用“add_system”方法，这些更改将不会被应用。

继续修改一个对象

当改变对象的值，确保你调用一个以“set_”开头的方法，来确保你的输入是有效的而且接下来的操做是正确的。

不像更冗长的语言（java），咱们不使用“get_”方法（译者注：俺就是java码农[\哭]）。

例如，改变内核选项，咱们将使用“obj.set_kernel_options(value)”，但从一个对象获得选项来处理它只是“obj.kernel_options”。

同步

若是cobbler 的ManageDhcp或ManageDns已经做用了，那么根据MAC改变的任何信息，系统的IP地址、主机名称也应该随之发生变化。

handle.sync()

在调整完全部的对象后，从新生成DHCP/DNS配置文件并重启服务。

搜索

若是咱们要查找符合特定标准的对象，例如主机名称包含肯定后缀的系统。

很容易作到：

#!/usr/bin/python
import cobbler.api as capi
handle = capi.BootAPI()
for x in handle.find_system(hostname="*.example.org",return_list=True):
   print x.name

支持来自fnmatch的通配符。

移除对象

这里有个如何删除名称为"foo"的系统对象的例子：

#!/usr/bin/python
import cobbler.api as capi
handle = capi.BootAPI()
handle.remove_system("foo")

同步库

不管是具体的同步某一个库仍是同步全部的库，经过API同步（即下载镜像或更新）是合理的。

handle.reposync(name="F10-updates-i386", tries=1)
handle.reposync(tries=3)

这个变量会重试 关闭/开启 mirrors.

导入新的安装树

也能够从API中经过CLL命令来执行cobbler 的导入。例如

handle.import_tree("/mnt/dvd/image","RHEL-5",arch="i386")

注意：官方文档在此处并无传入cobbler的loggler对象，通过实践发现，若是不传入cobbler的logger对象，执行这个导入镜像的方法会在日志中打印出错误，而且不能导入成功，该方法正确的传参为：

import clogger
logger = clogger.Logger("/var/log/cobbler/cobbler.log")
handle.import_tree("/mnt/dvd/image","RHEL-5",arch="i386",logger=logger)

此方法导入完成后，须要调用cobbler的sync方法来同步。

在api.py 文件中记录了更多的标签

从其余的Cobbler服务中拷贝

在ReplicateMaster有描述，示例以下：

handle.replicate(cobbler_master="centralcobbler.example.org",sync_all=True)

虽然是一个完整的复制，可是在api.py中仍是记录了其余的标签。

电源管理

若是你在一个cobbler 系统记录中有一个电源管理的详细信息，你能够按照以下操做电源状态：

sys = handle.find_system(name="foo")
handle.power_on(sys)
# OR
handle.power_off(sys)
# OR
handle.reboot(sys)

查看电源管理的详细信息：https://fedorahosted.org/cobbler/wiki/PowerManagement

开始一个新的部署

部署功能能够经过触发API接口来使用koan请求安装一个新的虚拟机。

sys1 = handle.find_system(name="myhost")
sys2 = handle.find_system(name="myguest")
handle.manage_deployment(sys2, virt_host=sys1, method="func", operation="install")
# OR
handle.manage_deployment(sys2, virt_host=sys1, method="ssh", operation="install")

注意，咱们也可使用这个API接口来控制远程设备的状态！

handle.manage_deployment(sys2, method="ssh", operation="start")
handle.manage_deployment(sys2, method="ssh", operation="restart")
handle.manage_deployment(sys2, method="ssh", operation="shutdown")
handle.manage_deployment(sys2, method="ssh", operation="unplug")  # a less friendly shutdown
handle.manage_deployment(sys2, method="ssh", operation="uninstall")

注意，一旦咱们仅仅经过客户机安装了VM，咱们就能够不用知道哪一个主机在跑，之后cobbler会帮咱们持续跟踪。

其它操做

可能在这里没有列出Cobbler的全部功能，可是能够经过Python API来获取全部的功能。

查看针对Cobbler的文档(pydoc)来获取什么是合理的，还能够经过(若是你喜欢的话)Cobbler源码来感觉它，这很容易就能够获取到，若是没有获取到，请咨询咱们。

pydoc cobbler.api

返回值

总的来讲，Cobbler API不返回对象则不反回有意义的返回值，好比整数。相反，CobblerExceptions 是提示错误信息的，这样就能够防止在操做上进行繁琐的错误检查，在哪里很容易就会忘记减产返回值得状态。

下篇，将翻译https://fedorahosted.org/cobbler/wiki/CobblerXmlrpc

以及：https://fedorahosted.org/cobbler/wiki/CobblerTriggers