資深專家深度剖析Kubernetes API Server第3章（共3章）

在本系列的前兩部分中我們介紹了API Server的總體流程，以及API對象如何存儲到etcd中。在本文中我們將探討如何擴展API資源。

在一開始的時候，擴展API資源的唯一方法是擴展相關API源代碼，集成為你所需的資源。或者，推動一個全新的類型為新的核心對象API合入社區代碼。但是，這樣就會導致核心API資源類型的不斷增加，直至API過載。為了避免這種API資源的無限制擴展，在 Kubernetes 中提供兩種擴展核心API的方法：

1.使用自定義資源定義（CRDs），最開始的時候被稱為第三方資源（TPRs）。通過CRD你能夠簡單而靈活的方式定義自己的資源對象類型，并讓API server處理整個生命周期。

2.使用與主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://

上面的kind主要是用來描述對象的類型，而resource 資源是與HTTP路徑相關的。大多數情況下這兩個是匹配的；但是在某些特定情況下在相同的API HTTP路徑下可能返回不通的kind（比如Status 錯誤對象會返回另一種kind）。

值得注意的是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

{

    "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的發展現狀如下所示：

1.在Kubernetes 1.7版本中CRDs開始取代ThirdPartyResources (TPRs) ，并且TPRs 將會在Kubernetes 1.8被刪除。

2.將TPRs遷移到CRDs實例可以參考文檔 migration 。

3.支持一個CRD中只有單個version版本，當然，一個群組中可能有多個version版本。

4.CRDs提供一個API方案，在用戶角度看它與Kubernetes原生的API資源基本沒有區別

5.CRDs是多版本多分支穩定的基礎。關于CRD資源的JSON-Schema的格式有效性校驗可以參考文檔 CRD validation proposal 。相關資源回收可以參考文檔Garbage collection。

接下去我們來看一下一些CRDs的局限：

1.CRD不提供版本轉換功能，也就是說，每個CRD只能有一個版本（預計不會在近期或中期內看到支持CRD版本轉換）。

2.在Kubernetes1.7當中，目前并沒有對于CRD的相關校驗validation。

3.沒有快速，實時的準入（admission）機制（但是可以支持webhooks 形式的初始化及準入）。

4.在Kubernetes1.7中你不能定義子資源（sub-resources），比如scale或者status，不過目前有在這方面 proposal 的討論。

5.CRD目前不支持默認值配置，即不支持為特定的字段配默認值（在Kubernetes1.7后續的版本中可能會支持）。

為了解決上述的問題，并且靈活的擴展 Kubernetes ，你可以運行一個與主API Server并行的用戶API Servers。我們將在本博文的以后部分中詳細介紹如何編寫UAS，并編寫一個custom controller完整使用CRD 。