Red Hat Training

A Red Hat training course is available for OpenShift Container Platform

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

20.1. Kubernetes カスタムリソース定義

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

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

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

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

CRD へのアクセスをユーザーに付与する場合、クラスターロールの集計により、管理、編集、または表示のデフォルトクラスターロールを持つユーザーにアクセスを付与します。また、クラスターロールの集計により、カスタムポリシールールをこれらのクラスターロールに挿入することができます。この動作は、これがビルトインリソースであるかのように新規リソースをクラスターの RBAC ポリシーに統合します。

注記

クラスター管理者のみが CRD を作成できますが、読み取りと書き込みのパーミッションがある場合には、CRD からオブジェクトを作成できます。

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

カスタムオブジェクトを作成するには、まずカスタムリソース定義 (CRD) を作成する必要があります。

注記

クラスター管理者のみが CRD を作成できます。

手順

CRD を作成するには、以下を実行します。

  1. 以下の例のようなフィールドを含む YAML ファイルを作成します。

    Example YAML file for a Custom Resource Definition

    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 グループは複数バージョンで存在させることができます。たとえば、v1alphav1betav1 などが使用されます。
    5
    カスタムオブジェクトがクラスター (Cluster) の 1 つのプロジェクト (Namespaced) またはすべてのプロジェクトで利用可能であるかどうかを指定します。
    6
    URL で使用される複数形の名前を指定します。plural フィールドは API URL のリソースと同じになります。
    7
    CLI および表示用にエイリアスとして使用される単数形の名前を指定します。
    8
    作成できるオブジェクトの種類を指定します。タイプは CamelCase にすることができます。
    9
    CLI でリソースに一致する短い文字列を指定します。
    注記

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

  2. オブジェクトを作成します。

    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 フィールドに基づいています。

20.3. カスタムリソース定義のクラスターロールの作成

クラスタースコープのカスタムリソース定義 (CRD) の作成後に、これに対してパーミッションを付与できます。管理、編集および表示のデフォルトクラスターロールを使用する場合、これらのルールにクラスターロールの集計を利用できます。

重要

これらのロールのいずれかにパーミッションを付与する際は、明示的に付与する必要があります。より多くのパーミッションを持つロールはより少ないパーミッションを持つロールからルールを継承しません。ルールをあるロールに割り当てる場合、寄り多くのパーミッションを持つロールにもその動詞を割り当てる必要もあります。たとえば、「get crontabs」パーミッションを表示ロールに付与する場合、これを編集および管理ロールにも付与する必要があります。管理または編集ロールは通常、プロジェクトテンプレートでプロジェクトを作成したユーザーに割り当てられます。

前提条件

  • CRD を作成します。

手順

  1. CRD のクラスターロール定義ファイルを作成します。クラスターロール定義は、各クラスターロールに適用されるルールが含まれる YAML ファイルです。OpenShift Container Platform Controller はデフォルトクラスターロールに指定するルールを追加します。

    Example YAML file for a cluster role definition

    apiVersion: rbac.authorization.k8s.io/v1 1
    kind: ClusterRole
    items:
      - metadata:
          name: aggregate-cron-tabs-admin-edit 2
          labels:
            rbac.authorization.k8s.io/aggregate-to-admin: "true" 3
            rbac.authorization.k8s.io/aggregate-to-edit: "true" 4
        rules:
          - apiGroups: ["stable.example.com"] 5
            resources: ["crontabs"] 6
            verbs: ["get", "list", "watch", "create",
                    "update", "patch", "delete", "deletecollection"] 7
      - metadata:
          name: aggregate-cron-tabs-view 8
          labels:
            # Add these permissions to the "view" default role.
            rbac.authorization.k8s.io/aggregate-to-view: "true" 9
            rbac.authorization.k8s.io/aggregate-to-cluster-reader: "true" 10
        rules:
          - apiGroups: ["stable.example.com"] 11
            resources: ["crontabs"] 12
            verbs: ["get", "list", "watch"] 13

    1
    apiextensions.k8s.io/v1beta1 API を使用します。
    2 8
    定義の名前を指定します。
    3
    パーミッションを管理のデフォルトロールに付与するためにこのラベルを指定します。
    4
    パーミッションを編集のデフォルトロールに付与するためにこのラベルを指定します。
    5 11
    CRD のグループ名を指定します
    6 12
    これらのルールが適用される CRD の複数形の名前を指定します。
    7 13
    ロールに付与されるパーミッションを表す動詞を指定します。たとえば、admin および edit ロールに読み取りおよび書き込みパーミッションを適用し、view ロールに読み取りパーミッションのみを適用します。
    9
    パーミッションを view のデフォルトロールに付与するためにこのラベルを指定します。
    10
    パーミッションを cluster-reader のデフォルトロールに付与するためにこのラベルを指定します。
  2. クラスターロールを作成します。

    oc create -f <file-name>.yaml

20.4. CRD からのカスタムオブジェクトの作成

カスタムリソース定義 (CRD) オブジェクトの作成後に、その仕様を使用するカスタムオブジェクトを作成できます。

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

前提条件

  • CRD を作成します。

手順

  1. カスタムオブジェクトの YAML 定義を作成します。以下の定義例では、cronSpecimage のカスタムフィールドが CronTab タイプのカスタムオブジェクトに設定されます。このタイプは、カスタムリソース定義オブジェクトの spec.kind フィールドから取得します。

    Example YAML file for a custom object

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

    1
    カスタムリソース定義からグループ名および API バージョン (名前/バージョン) を指定します。
    2
    カスタムリソース定義のタイプを指定します。
    3
    オブジェクトの名前を指定します。
    4
    オブジェクトのファイナライザーを指定します。ファイナライザーは、コントローラーがオブジェクトの削除前に完了する必要のある条件を実装できるようにします。
    5
    オブジェクトのタイプに固有の条件を指定します。
  2. オブジェクトファイルの作成後に、オブジェクトを作成します。

    oc create -f <file-name>.yaml

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

オブジェクトを作成した後には、カスタムリソースを管理できます。

前提条件

  • カスタムリソース定義 (CRD) を作成します。
  • CRD からオブジェクトを作成します。

手順

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

    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
  2. カスタムリソースの未加工の YAML データも確認することができます。

    oc get <kind> -o yaml
    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
    1 2
    オブジェクトの作成に使用した YAML からのカスタムデータが表示されます。