2.7. CRD

2.7.1. カスタムリソース定義による Kubernetes API の拡張

Operator は Kubernetes の拡張メカニズムであるカスタムリソース定義 (CRD) を使用するため、Operator によって管理されるカスタムオブジェクトは、組み込み済みのネイティブ Kubernetes オブジェクトのように表示され、機能します。以下では、CRD を作成し、管理することで、クラスター管理者が OpenShift Container Platform クラスターをどのように拡張できるかについて説明します。

2.7.1.1. カスタムリソース定義

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

カスタムリソース定義 (CRD) オブジェクトは、クラスター内に新規の固有オブジェクト kind を定義し、Kubernetes API サーバーにそのライフサイクル全体を処理させます。

カスタムリソース (CR) オブジェクトは、クラスター管理者によってクラスターに追加された CRD から作成され、すべてのクラスターユーザーが新規リソースタイプをプロジェクトに追加できるようにします。

クラスター管理者が新規 CRD をクラスターに追加する際に、Kubernetes API サーバーは、クラスター全体または単一プロジェクト (namespace) によってアクセスできる新規の RESTful リソースパスを作成することによって応答し、指定された CR を提供し始めます。

CRD へのアクセスを他のユーザーに付与する必要のあるクラスター管理者は、クラスターロールの集計を使用して adminedit、または view のデフォルトクラスターロールを持つユーザーにアクセスを付与できます。また、クラスターロールの集計により、カスタムポリシールールをこれらのクラスターロールに挿入することができます。この動作は、新規リソースを組み込み型のインリソースであるかのようにクラスターの RBAC ポリシーに統合します。

Operator はとりわけ CRD を必要な RBAC ポリシーおよび他のソフトウェア固有のロジックでパッケージ化することで CRD を利用します。またクラスター管理者は、Operator のライフサイクル外にあるクラスターに CRD を手動で追加でき、これらをすべてのユーザーに利用可能にすることができます。

注記

クラスター管理者のみが CRD を作成できる一方で、開発者は CRD への読み取りおよび書き込みパーミッションがある場合には、既存の CRD から CR を作成することができます。

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

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

前提条件

  • cluster-admin ユーザー権限を使用した OpenShift Container Platform クラスターへのアクセス

手順

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

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

    CRD の YAML ファイルの例

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

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

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

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

    $ oc create -f <file_name>.yaml

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

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

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

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

    このエンドポイント URL を使用して CR を作成し、管理できます。オブジェクト kind は、作成した CRD オブジェクトの spec.kind フィールドに基づいています。

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

クラスター管理者は、既存のクラスタースコープのカスタムリソース定義 (CRD) にパーミッションを付与できます。adminedit、および view のデフォルトクラスターロールを使用する場合、これらのルールについてクラスターロールの集計を利用できます。

重要

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

前提条件

  • CRD を作成します。

手順

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

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

    kind: ClusterRole
    apiVersion: rbac.authorization.k8s.io/v1 1
    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
    ---
    kind: ClusterRole
    apiVersion: rbac.authorization.k8s.io/v1
    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
    rbac.authorization.k8s.io/v1 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

2.7.1.4. ファイルからのカスタムリソースの作成

カスタムリソース定義 (CRD) がクラスターに追加された後に、カスタムリソース (CR) は CR 仕様を使用するファイルを使って CLI で作成できます。

前提条件

  • CRD がクラスター管理者によってクラスターに追加されている。

手順

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

    CR の YAML ファイルサンプル

    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
    CRD からグループ名および API バージョン (name/version) を指定します。
    2
    CRD にタイプを指定します。
    3
    オブジェクトの名前を指定します。
    4
    オブジェクトの ファイナライザー を指定します (ある場合)。ファイナライザーは、コントローラーがオブジェクトの削除前に完了する必要のある条件を実装できるようにします。
    5
    オブジェクトのタイプに固有の条件を指定します。
  2. ファイルの作成後に、オブジェクトを作成します。

    $ oc create -f <file_name>.yaml

2.7.1.5. カスタムリソースの検査

CLI を使用してクラスターに存在するカスタムリソース (CR) オブジェクトを検査できます。

前提条件

  • CR オブジェクトがアクセスできる namespace にあること。

手順

  1. CR の特定の kind についての情報を取得するには、以下を実行します。

    $ 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. CR の未加工の 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 からのカスタムデータが表示されます。

2.7.2. カスタムリソース定義からのリソースの管理

以下では、開発者がカスタムリソース定義 (CRD) にあるカスタムリソース (CR) をどのように管理できるかについて説明します。

2.7.2.1. カスタムリソース定義

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

カスタムリソース定義 (CRD) オブジェクトは、クラスター内に新規の固有オブジェクト kind を定義し、Kubernetes API サーバーにそのライフサイクル全体を処理させます。

カスタムリソース (CR) オブジェクトは、クラスター管理者によってクラスターに追加された CRD から作成され、すべてのクラスターユーザーが新規リソースタイプをプロジェクトに追加できるようにします。

Operator はとりわけ CRD を必要な RBAC ポリシーおよび他のソフトウェア固有のロジックでパッケージ化することで CRD を利用します。またクラスター管理者は、Operator のライフサイクル外にあるクラスターに CRD を手動で追加でき、これらをすべてのユーザーに利用可能にすることができます。

注記

クラスター管理者のみが CRD を作成できる一方で、開発者は CRD への読み取りおよび書き込みパーミッションがある場合には、既存の CRD から CR を作成することができます。

2.7.2.2. ファイルからのカスタムリソースの作成

カスタムリソース定義 (CRD) がクラスターに追加された後に、カスタムリソース (CR) は CR 仕様を使用するファイルを使って CLI で作成できます。

前提条件

  • CRD がクラスター管理者によってクラスターに追加されている。

手順

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

    CR の YAML ファイルサンプル

    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
    CRD からグループ名および API バージョン (name/version) を指定します。
    2
    CRD にタイプを指定します。
    3
    オブジェクトの名前を指定します。
    4
    オブジェクトの ファイナライザー を指定します (ある場合)。ファイナライザーは、コントローラーがオブジェクトの削除前に完了する必要のある条件を実装できるようにします。
    5
    オブジェクトのタイプに固有の条件を指定します。
  2. ファイルの作成後に、オブジェクトを作成します。

    $ oc create -f <file_name>.yaml

2.7.2.3. カスタムリソースの検査

CLI を使用してクラスターに存在するカスタムリソース (CR) オブジェクトを検査できます。

前提条件

  • CR オブジェクトがアクセスできる namespace にあること。

手順

  1. CR の特定の kind についての情報を取得するには、以下を実行します。

    $ 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. CR の未加工の 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 からのカスタムデータが表示されます。