Red Hat Training

A Red Hat training course is available for OpenShift Container Platform

第19章 カスタムリソースによる Kubernetes API の拡張

Kubernetes API では、リソースは特定の種類の API オブジェクトのコレクションを保管するエンドポイントです。たとえば、ビルトインされた Pod リソースには Pod オブジェクトのコレクションが含まれます。

カスタムリソースは、Kubernetes API を拡張するか、またはプロジェクトまたはクラスターに独自の API を導入することを可能にするオブジェクトです。

カスタムリソース定義 (CRD) ファイルは、独自のオブジェクトの種類を定義し、API サーバーがライフサイクル全体を処理できるようにします。CRD をクラスターにデプロイすると、Kubernetes API サーバーは指定されたカスタムリソースを提供し始めます。

新規のカスタムリソース定義 (CRD) の作成時に、Kubernetes API サーバーは、クラスター全体または単一プロジェクト (namespace) でアクセスできる新規 RESTful リソースパスを作成することによって応答します。既存のビルトインオブジェクトの場合のように、プロジェクトを削除すると、そのプロジェクトのすべてのカスタムオブジェクトが削除されます。

19.1. カスタムリソース定義の作成

CRD を作成するには、YAML ファイルを開き、以下の例のようにフィールドに入力します。

カスタムリソース定義の YAML ファイルサンプル

apiVersion: apiextensions.k8s.io/v1beta1 1
kind: CustomResourceDefinition
metadata:
  name: crontabs.stable.example.com 2
spec:
  group: stable.example.com 3
  version: v1 4
  scope: Namespaced 5
  names:
    plural: crontabs 6
    singular: crontab 7
    kind: CronTab 8
    shortNames:
    - ct 9

1
apiextensions.k8s.io/v1beta1 API を使用します。
2
定義の名前を指定します。これは group および plural フィールドの値を使用する <plural-name><group> 形式である必要があります。
3
API のグループ名を指定します。API グループは、論理的に関連付けられるオブジェクトのコレクションです。たとえば、Job または ScheduledJob などのすべてのバッチオブジェクトはバッチ API グループ (batch.api.example.com など) である可能性があります。組織の完全修飾ドメイン名を使用することが奨励されます。
4
URL で使用されるバージョン名を指定します。それぞれの API グループは複数バージョンで存在させることができます。たとえば、v1alphavibetav1 などが使用されます。
5
カスタムオブジェクトがクラスター (Cluster) の 1 つのプロジェクト (Namespaced) またはすべてのプロジェクトで利用可能であるかどうかを指定します。
6
URL で使用される複数形の名前を指定します。plural フィールドは API URL のリソースと同じになります。
7
CLI および表示用にエイリアスとして使用される単数形の名前を指定します。
8
作成できるオブジェクトの種類を指定します。タイプは CamelCase にすることができます。
9
CLI でリソースに一致する短い文字列を指定します。
注記

デフォルトで、カスタムリソース定義のスコープはクラスターに設定され、すべてのプロジェクトで利用可能です。

定義ファイルの設定後にオブジェクトを定義します。

oc create -f <file-name>.yaml

新規の RESTful API エンドポイントは以下のように作成されます。

/apis/<spec:group>/<spec:version>/<scope>/*/<names-plural>/...

たとえば、サンプルファイルを使用すると、以下のエンドポイントが作成されます。

/apis/stable.example.com/v1/namespaces/*/crontabs/...

次にこのエンドポイント URL はカスタムオブジェクトを作成し、管理するために使用できます。オブジェクトの種類は、作成したカスタムリソース定義オブジェクトの spec.kind フィールドに基づくものです。

19.2. カスタムオブジェクトの作成

カスタムリソース定義オブジェクトの作成後に、カスタムオブジェクトを作成することができます。

カスタムオブジェクトにはカスタムフィールドを含めることができます。これらのフィールドには任意の JSON を含めることができます。

以下の例では、cronSpec および image カスタムフィールドが CronTab という種類のカスタムオブジェクトに設定されます。CronTab という種類は、上記で作成したカスタムリソース定義オブジェクトの spec.kind フィールドから取られています。

カスタムオブジェクトの YAML ファイルサンプル

apiVersion: "stable.example.com/v1" 1
kind: CronTab 2
metadata:
  name: my-new-cron-object 3
spec: 4
  cronSpec: "* * * * /5"
  image: my-awesome-cron-image

1
カスタムリソース定義からグループ名および API バージョン (名前/バージョン) を指定します。
2
カスタムリソース定義のタイプを指定します。
3
オブジェクトの名前を指定します。
4
オブジェクトのタイプに固有の条件を指定します。

オブジェクトファイルの設定後に、オブジェクトを作成します。

oc create -f <file-name>.yaml

19.3. カスタムオブジェクトの管理

次に、カスタムリソースを管理することができます。

特定の種類のカスタムリソースについての情報を取得するには、以下を入力します。

oc get <kind>

以下に例を示します。

oc get crontab

NAME                 KIND
my-new-cron-object   CronTab.v1.stable.example.com

リソース名では大文字と小文字が区別されず、CRD で定義される単数形または複数形のいずれか、および任意の短縮名を指定できることに注意してください。以下は例になります。

oc get crontabs
oc get crontab
oc get ct

未加工 JSON データを表示することもできます。

oc get <kind> -o yaml

これを作成するために使用した YAML のカスタム <1> cronSpec および <2> image フィールドが含まれることを確認できるはずです。

oc get ct -o yaml

apiVersion: v1
items:
- apiVersion: stable.example.com/v1
  kind: CronTab
  metadata:
    clusterName: ""
    creationTimestamp: 2017-05-31T12:56:35Z
    deletionGracePeriodSeconds: null
    deletionTimestamp: null
    name: my-new-cron-object
    namespace: default
    resourceVersion: "285"
    selfLink: /apis/stable.example.com/v1/namespaces/default/crontabs/my-new-cron-object
    uid: 9423255b-4600-11e7-af6a-28d2447dc82b
  spec:
    cronSpec: '* * * * /5' 1
    image: my-awesome-cron-image 2

19.4. ファイナライザー

カスタムオブジェクトは ファイナライザー をサポートします。これにより、コントローラーはオブジェクトの削除前に満たしている必要のある条件を実装できます。

以下のようにファイナライザーをカスタムオブジェクトに追加できます。

apiVersion: "stable.example.com/v1"
kind: CronTab
metadata:
  finalizers:
  - finalizer.stable.example.com

ファイナライザーが設定されたオブジェクトでの最初の削除要求により、オブジェクトの削除ではなく metadata.deletionTimestamp フィールドの値が設定されます。これによりコントローラーがトリガーされ、コントローラーはオブジェクトによる対象ファイナライザーの実行を監視します。

次に、各コントローラーは一覧からファイナライザーを削除し、削除要求を再び発行します。この要求により、ファイナライザーの一覧が空である (つまり、すべてのファイナライザーが実行済みである) 場合にのみオブジェクトが削除されます。