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