深度剖析Kubernetes API Server三部曲 - part 3
在一開始的時候,擴展API資源的唯一方法是擴展相關API源代碼,集成為你所需的資源。或者,推動一個全新的類型為新的核心對象API合入社區代碼。但是,這樣就會導致核心API資源類型的不斷增加,直至API過載。為了避免這種API資源的無限制擴展,在Kubernetes中提供兩種擴展核心API的方法:
- 使用自定義資源定義(CRDs),最開始的時候被稱為第三方資源(TPRs)。通過CRD你能夠簡單而靈活的方式定義自己的資源對象類型,並讓API server處理整個生命周期。
- 使用與主API Servers 並行運行的用戶API Servers(UAS)。這種方式,可能更多的設計代碼開發,可能需要你投入較多的時間及精力。當然,這種方式也能夠讓你對API資源有更細致,全面的了解。
在本文中,我們主要對CRD相關定義以及使用進行探討。
CRDs的聲明及創建
在本系列文章第一部分所提到過的,每個API資源根據Group群組分類,每個對象都有一個對應的版本號與HTTP路徑相關聯。現在如果想要實現一個CRD,首先需要的是就是命名一個新的API Group群組,這個API群組不能與已經存在的群組重復。在你自己新建的API群組中,你可以擁有任意數量的資源,並且它們可以與其他群組中的資源具有相同的名稱。下面我們來列舉一個實際的例子:
在之前我們有介紹過,每個版本的由API群組管理的Kubernetes資源是跟HTTP路徑相關的。CRD類似於面向對象編程中一個類的定義,而實際使用的CR可以看做為它的一組實例。首先我們對例子中的一些字段作說明,第一行中的CRD apiVersion在kube-apiserver 1.7 之後都是這樣定義的。從第5行之後我們定義了spec 的相關字段。在第6行spec.group是定義了你創建的CRD的API群組(在本例子中定義為了example.com)。第7行定義了CRD對象的版本。每個資源只有一個固定版本,但在API群組中還是能有多個不同版本的資源。第8行的spec.names有兩個必填項:kind,按照慣例第一個字母大寫,plural,按照慣例全為小寫,這個字段與最終生成的HTTP路徑相關,比如在本例子中,最終的HTTP路徑為https://<server/apis/example.com/v1/namespaces/default/databases。還有一個可選的singular字段,默認為小寫類型值,可以在kubectl的上下文中使用。此外,在spec.names中還有許多可選字段,這些字段將會由API Server自動生成並填充。
值得註意的是resource 資源(在本例中是databases)和group群組(本例中是example.com)必須與metadata.name 字段匹配(本例為第四行databases. example.com)。
現在我們根據上面的YAML文件來創建一個CRD:
$ kubectl create -f databases-crd.yaml
customresourcedefinition "databases.example.com" created
由於這個創建過程是異步進行的,所以你必須檢查一下你創建的CRD的狀態,確認你創建的CRD沒有與其它資源沖突,並且API Server已經調用相關處理函數完成創建。你可以在腳本或代碼中通過輪詢完成這個過程。最後我們能得到以下狀態:
$ kubectl get crd databases.example.com -o yaml
apiVersion: apiextensions.k8s.io/v1beta1
kind: CustomResourceDefinition
metadata:
creationTimestamp: 2017-08-09T09:21:43Z
name: databases.example.com
resourceVersion: "792"
selfLink: /apis/apiextensions.k8s.io/v1beta1/customresourcedefinitions/databases.example.com
uid: 28c94a05-7ce4-11e7-888c-42010a9a0fd5
spec:
group: example.com
names:
kind: Database
listKind: DatabaseList
plural: databases
singular: database
scope: Namespaced
version: v1
status:
acceptedNames:
kind: Database
listKind: DatabaseList
plural: databases
singular: database
conditions:- lastTransitionTime: null
message: no conflicts found
reason: NoConflicts
status: "True"
type: NamesAccepted - lastTransitionTime: 2017-08-09T09:21:43Z
message: the initial names have been accepted
reason: InitialNamesAccepted
status: "True"
type: Established
以上,我們可以看到通過kubectl可以看到我們之前創建的CRD,並且顯示出了CRD的一些狀態信息。
CRDs的使用
在通過kubectl proxy將Kubernetes API 開啟本地代理後,查看我們剛才創建的CRD:
$ http 127.0.0.1:8001/apis/example.com
HTTP/1.1 200 OK
Content-Length: 223
Content-Type: application/json
Date: Wed, 09 Aug 2017 09:25:44 GMT
- lastTransitionTime: null
{
"apiVersion": "v1",
"kind": "APIGroup",
"name": "example.com",
"preferredVersion": {
"groupVersion": "example.com/v1",
"version": "v1"
},
"serverAddressByClientCIDRs": null,
"versions": [
{
"groupVersion": "example.com/v1",
"version": "v1"
}
]
}
請註意,在默認情況下十分鐘內,kubectl是查看存儲在~/.kube/cache/discovery目錄的緩存。所以,可能會需要10分鐘後你才能看到你新創建的CRD資源。但是,當沒有緩存時,kubectl發現不了所需的資源時,那麽會重新緩存它。
接下來,我們來看一個CRD實例:
$ cat wordpress-database.yaml
apiVersion: example.com/v1
kind: Database
metadata:
name: wordpress
spec:
user: wp
password: secret
encoding: unicode
$ kubectl create -f wordpress-databases.yaml
database "wordpress" created
$ kubectl get databases.example.com
NAME KIND
wordpress Database.v1.example.com
想要通過API來監控資源的創建與更新,你可以通過對某個resourceVersion(我們通過curl來實例對指定版本的database做監控)之後的修改做監控watch。
$ http 127.0.0.1:8001/apis/example.com/v1/namespaces/default/databases
HTTP/1.1 200 OK
Content-Length: 593
Content-Type: application/json
Date: Wed, 09 Aug 2017 09:38:49 GMT
{
"apiVersion": "example.com/v1",
"items": [
{
"apiVersion": "example.com/v1",
"kind": "Database",
"metadata": {
"clusterName": "",
"creationTimestamp": "2017-08-09T09:38:30Z",
"deletionGracePeriodSeconds": null,
"deletionTimestamp": null,
"name": "wordpress",
"namespace": "default",
"resourceVersion": "2154",
"selfLink": "/apis/example.com/v1/namespaces/default/databases/wordpress",
"uid": "8101a7af-7ce6-11e7-888c-42010a9a0fd5"
},
"spec": {
"encoding": "unicode",
"password": "secret",
"user": "wp"
}
}
],
"kind": "DatabaseList",
"metadata": {
"resourceVersion": "2179",
"selfLink": "/apis/example.com/v1/namespaces/default/databases"
}
}
我們可以對/apis/example.com/v1/namespaces/default/databases/wordpressCRD的HTTP路徑通過curl命令對的"resourceVersion": "2154"進行監控watch:
$ curl -f 127.0.0.1:8001/apis/example.com/v1/namespaces/default/databases?watch=true&resourceVersion=2154
現在我們新開一個shell對話窗口,刪除wordpress CRD資源,我們可以查看剛才的監控watch窗口是否接收到了這個消息:
$ kubectl delete databases.example.com/wordpress
請註意:我們能夠使用kubectl delete database wordpress刪除CRD資源,是因為之前在Kubernetes沒有定義有database 資源。此外,database 是我們CRD中的spec.name.singular字段,從英語語法派生而來。
我們可以看到之前監控watch CRD databases從API Server處返回的更新狀態:
{"type":"DELETED","object":{"apiVersion":"example.com/v1","kind":"Database","metadata":{"clusterName":"","creationTimestamp":"2017-0[0/515]
:38:30Z","deletionGracePeriodSeconds":null,"deletionTimestamp":null,"name":"wordpress","namespace":"default","resourceVersion":"2154","selfLink":"/apis/example.com/v1/namespaces/
default/databases/wordpress","uid":"8101a7af-7ce6-11e7-888c-42010a9a0fd5"},"spec":{"encoding":"unicode","password":"secret","user":"wp"}}}
上述shell會話的運行及輸出結果如下圖所示:
最後,讓我們看一下CRD database 的各個數據是如何存儲在etcd中的。下面是我們直接通過HTTP API進入etcd訪問得到的數據:
$ curl -s localhost:2379/v2/keys/registry/example.com/databases/default | jq .
{
"action": "get",
"node": {
"key": "/registry/example.com/databases/default",
"dir": true,
"nodes": [
{
"key": "/registry/example.com/databases/default/wordpress",
"value": "{\"apiVersion\":\"example.com/v1\",\"kind\":\"Database\",\"metadata\":{\"clusterName\":\"\",\"creationTimestamp\":\"2017-08-09T14:53:40Z\",\"deletionGracePeriodSeconds\":null,\"deletionTimestamp\":null,\"name\":\"wordpress\",\"namespace\":\"default\",\"selfLink\":\"\",\"uid\":\"8837f788-7d12-11e7-9d28-080027390640\"},\"spec\":{\"encoding\":\"unicode\",\"password\":\"secret\",\"user\":\"wp\"}}\n",
"modifiedIndex": 670,
"createdIndex": 670
}
],
"modifiedIndex": 670,
"createdIndex": 670
}
}
從上面可以看到,CRD數據在etcd中最終以一個未解析的的狀態存在。現在將CRD刪除,所有的CRD實例也會跟著刪除,這是一個級聯刪除操作。
目前CRDs的使用現狀,局限及將來的展望
CRDs的發展現狀如下所示:
- 在Kubernetes 1.7版本中CRDs開始取代ThirdPartyResources (TPRs) ,並且TPRs 將會在Kubernetes 1.8被刪除。
- 將TPRs遷移到CRDs實例可以參考文檔migration。
- 支持一個CRD中只有單個version 版本,當然,一個群組中可能有多個version版本。
- CRDs提供一個API方案,在用戶角度看它與Kubernetes原生的API資源基本沒有區別
- CRDs是多版本多分支穩定的基礎。關於CRD資源的JSON-Schema的格式有效性校驗可以參考文檔CRD validation proposal。相關資源回收可以參考文檔Garbage collection。
接下去我們來看一下一些CRDs的局限: - CRD不提供版本轉換功能,也就是說,每個CRD只能有一個版本(預計不會在近期或中期內看到支持CRD版本轉換)。
- 在Kubernetes1.7當中,目前並沒有對於CRD的相關校驗validation。
- 沒有快速,實時的準入(admission )機制(但是可以支持webhooks 形式的初始化及準入)。
- 在Kubernetes1.7中你不能定義子資源(sub-resources),比如scale或者status,不過目前有在這方面proposal 的討論。
- CRD目前不支持默認值配置,即不支持為特定的字段配默認值(在Kubernetes1.7後續的版本中可能會支持)。
為了解決上述的問題,並且靈活的擴展Kubernetes,你可以運行一個與主API Server並行的用戶API Servers。我們將在本博文的以後部分中詳細介紹如何編寫UAS,並編寫一個custom controller 完整使用CRD 。https://www.huaweicloud.com/product/cce.html
深度剖析Kubernetes API Server三部曲 - part 3