224 lines
24 KiB
Markdown
224 lines
24 KiB
Markdown
---
|
||
title: カスタムリソース
|
||
content_template: templates/concept
|
||
weight: 20
|
||
---
|
||
|
||
{{% capture overview %}}
|
||
|
||
*カスタムリソース* はKubernetes APIの拡張です。このページでは、いつKubernetesのクラスターにカスタムリソースを追加するべきなのか、そしていつスタンドアローンのサービスを利用するべきなのかを議論します。カスタムリソースを追加する2つの方法と、それらの選択方法について説明します。
|
||
|
||
{{% /capture %}}
|
||
|
||
{{% capture body %}}
|
||
|
||
## カスタムリソース
|
||
|
||
*リソース* は、[Kubernetes API](/docs/reference/using-api/api-overview/)のエンドポイントで、特定の[APIオブジェクト](/ja/docs/concepts/overview/working-with-objects/kubernetes-objects/)のコレクションを保持します。例えば、ビルトインの *Pods* リソースは、Podオブジェクトのコレクションを包含しています。
|
||
|
||
*カスタムリソース* は、Kubernetes APIの拡張で、デフォルトのKubernetesインストールでは、必ずしも利用できるとは限りません。つまりそれは、特定のKubernetesインストールのカスタマイズを表します。しかし、今現在、多数のKubernetesのコア機能は、カスタムリソースを用いて作られており、Kubernetesをモジュール化しています。
|
||
|
||
カスタムリソースは、稼働しているクラスターに動的に登録され、現れたり、消えたりし、クラスター管理者はクラスター自体とは無関係にカスタムリソースを更新できます。一度、カスタムリソースがインストールされると、ユーザーは[kubectl](/docs/user-guide/kubectl-overview/)を使い、ビルトインのリソースである *Pods* と同じように、オブジェクトを作成、アクセスすることが可能です。
|
||
|
||
## カスタムコントローラー
|
||
|
||
カスタムリソースそれ自身は、単純に構造化データを格納、取り出す機能を提供します。カスタムリソースを *カスタムコントローラー* と組み合わせることで、カスタムリソースは真の _宣言的API_ を提供します。
|
||
|
||
[宣言的API](/ja/docs/concepts/overview/working-with-objects/kubernetes-objects/#kubernetesオブジェクトを理解する)は、リソースのあるべき状態を _宣言_ または指定することを可能にし、Kubernetesオブジェクトの現在の状態を、あるべき状態に同期し続けるように動きます。
|
||
コントローラーは、構造化データをユーザーが指定したあるべき状態と解釈し、その状態を管理し続けます。
|
||
|
||
稼働しているクラスターのライフサイクルとは無関係に、カスタムコントローラーをデプロイ、更新することが可能です。カスタムコントローラーはあらゆるリソースと連携できますが、カスタムリソースと組み合わせると特に効果を発揮します。[オペレーターパターン](https://coreos.com/blog/introducing-operators.html)は、カスタムリソースとカスタムコントローラーの組み合わせです。カスタムコントローラーにより、特定アプリケーションのドメイン知識を、Kubernetes APIの拡張に変換することができます。
|
||
|
||
## カスタムリソースをクラスターに追加するべきか？
|
||
|
||
新しいAPIを作る場合、[APIをKubernetesクラスターAPIにアグリゲート(集約)する](/ja/docs/concepts/api-extension/apiserver-aggregation/)か、もしくはAPIをスタンドアローンで動かすかを検討します。
|
||
|
||
| APIアグリゲーションを使う場合: | スタンドアローンAPIを使う場合: |
|
||
| ------------------------------ | ---------------------------- |
|
||
| APIが[宣言的](#宣言的API) | APIが[宣言的](#宣言的API)モデルに適さない |
|
||
| 新しいリソースを`kubectl`を使い読み込み、書き込みしたい| `kubectl`のサポートは必要ない |
|
||
| 新しいリソースをダッシュボードのような、Kubernetes UIで他のビルトインリソースと同じように管理したい | Kubernetes UIのサポートは必要ない |
|
||
| 新しいAPIを開発している | APIを提供し、適切に機能するプログラムが既に存在している |
|
||
| APIグループ、名前空間というような、RESTリソースパスに割り当てられた、Kubernetesのフォーマット仕様の制限を許容できる([API概要](/ja/docs/concepts/overview/kubernetes-api/)を参照) | 既に定義済みのREST APIと互換性を持っていなければならない |
|
||
| リソースはクラスターごとか、クラスター内の名前空間に自然に分けることができる | クラスター、または名前空間による分割がリソース管理に適さない。特定のリソースパスに基づいて管理したい |
|
||
| [Kubernetes APIサポート機能](#一般的な機能)を再利用したい | これらの機能は必要ない |
|
||
|
||
### 宣言的API
|
||
|
||
宣言的APIは、通常、下記に該当します:
|
||
|
||
- APIは、比較的少数の、比較的小さなオブジェクト(リソース)で構成されている
|
||
- オブジェクトは、アプリケーションの設定、インフラストラクチャーを定義する
|
||
- オブジェクトは、比較的更新頻度が低い
|
||
- 人は、オブジェクトの情報をよく読み書きする
|
||
- オブジェクトに対する主要な手続きは、CRUD(作成、読み込み、更新、削除)になる
|
||
- 複数オブジェクトをまたいだトランザクションは必要ない: APIは今現在の状態ではなく、あるべき状態を表現する
|
||
|
||
命令的APIは、宣言的ではありません。
|
||
APIが宣言的ではない兆候として、次のものがあります:
|
||
|
||
- クライアントから"これを実行"と命令がきて、完了の返答を同期的に受け取る
|
||
- クライアントから"これを実行"と命令がきて、処理IDを取得する。そして処理が完了したかどうかを、処理IDを利用して別途問い合わせる
|
||
- リモートプロシージャコール(RPC)という言葉が飛び交っている
|
||
- 直接、大量のデータを格納している(例、1オブジェクトあたり数kBより大きい、または数千オブジェクトより多い)
|
||
- 高帯域アクセス(持続的に毎秒数十リクエスト)が必要
|
||
- エンドユーザーのデータ(画像、PII、その他)を格納している、またはアプリケーションが処理する大量のデータを格納している
|
||
- オブジェクトに対する処理が、CRUDではない
|
||
- APIをオブジェクトとして簡単に表現できない
|
||
- 停止している処理を処理ID、もしくは処理オブジェクトで表現することを選択している
|
||
|
||
## ConfigMapとカスタムリソースのどちらを使うべきか?
|
||
|
||
下記のいずれかに該当する場合は、ConfigMapを使ってください:
|
||
|
||
* `mysql.cnf`、`pom.xml`のような、十分に文書化された設定ファイルフォーマットが既に存在している
|
||
* 単一キーのConfigMapに、設定ファイルの内容の全てを格納している
|
||
* 設定ファイルの主な用途は、クラスター上のPodで実行されているプログラムがファイルを読み込み、それ自体を構成することである
|
||
* ファイルの利用者は、Kubernetes APIよりも、Pod内のファイルまたはPod内の環境変数を介して利用することを好む
|
||
* ファイルが更新されたときに、Deploymentなどを介してローリングアップデートを行いたい
|
||
|
||
{{< note >}}
|
||
センシティブなデータには、ConfigMapに類似していますがよりセキュアな[secret](/docs/concepts/configuration/secret/)を使ってください
|
||
{{< /note >}}
|
||
|
||
下記のほとんどに該当する場合、カスタムリソース(CRD、またはアグリゲートAPI)を使ってください:
|
||
|
||
* 新しいリソースを作成、更新するために、Kubernetesのクライアントライブラリー、CLIを使いたい
|
||
* kubectlのトップレベルサポートが欲しい(例、`kubectl get my-object object-name`)
|
||
* 新しい自動化の仕組みを作り、新しいオブジェクトの更新をウォッチしたい、その更新を契機に他のオブジェクトのCRUDを実行したい、またはその逆を行いたい
|
||
* オブジェクトの更新を取り扱う、自動化の仕組みを書きたい
|
||
* `.spec`、`.status`、`.metadata`というような、Kubernetes APIの慣習を使いたい
|
||
* オブジェクトは、制御されたリソースコレクションの抽象化、または他のリソースのサマリーとしたい
|
||
|
||
## カスタムリソースを追加する
|
||
|
||
Kubernetesは、クラスターへカスタムリソースを追加する2つの方法を提供しています:
|
||
|
||
- CRDはシンプルで、プログラミングなしに作成可能
|
||
- [APIアグリゲーション](/ja/docs/concepts/extend-kubernetes/api-extension/apiserver-aggregation/)は、プログラミングが必要だが、データがどのように格納され、APIバージョン間でどのように変換されるかというような、より詳細なAPIの振る舞いを制御できる
|
||
|
||
Kubernetesは、さまざまなユーザーのニーズを満たすためにこれら2つのオプションを提供しており、使いやすさや柔軟性が損なわれることはありません。
|
||
|
||
アグリゲートAPIは、プロキシーとして機能するプライマリAPIサーバーの背後にある、下位のAPIServerです。このような配置は[APIアグリゲーション](/ja/docs/concepts/extend-kubernetes/api-extension/apiserver-aggregation/) (AA)と呼ばれています。ユーザーにとっては、単にAPIサーバーが拡張されているように見えます。
|
||
|
||
CRDでは、APIサーバーの追加なしに、ユーザーが新しい種類のリソースを作成できます。CRDを使うには、APIアグリゲーションを理解する必要はありません。
|
||
|
||
どのようにインストールされたかに関わらず、新しいリソースはカスタムリソースとして参照され、ビルトインのKubernetesリソース(Podなど)とは区別されます。
|
||
|
||
## CustomResourceDefinition
|
||
|
||
[CustomResourceDefinition](/docs/tasks/access-kubernetes-api/custom-resources/custom-resource-definitions/)APIリソースは、カスタムリソースを定義します。CRDオブジェクトを定義することで、指定した名前、スキーマで新しいカスタムリソースが作成されます。Kubernetes APIは、作成したカスタムリソースのストレージを提供、および処理します。
|
||
|
||
これはカスタムリソースを処理するために、独自のAPIサーバーを書くことから解放してくれますが、一般的な性質として[APIサーバーアグリゲーション](#APIサーバーアグリゲーション)と比べると、柔軟性に欠けます。
|
||
|
||
新しいカスタムリソースをどのように登録するか、新しいリソースタイプとの連携、そしてコントローラーを使いイベントを処理する方法例について、[カスタムコントローラー例](https://github.com/kubernetes/sample-controller)を参照してください。
|
||
|
||
## APIサーバーアグリゲーション
|
||
|
||
通常、Kubernetes APIの各リソースは、RESTリクエストとオブジェクトの永続的なストレージを管理するためのコードが必要です。メインのKubernetes APIサーバーは *Pod* や *Service* のようなビルトインのリソースを処理し、また[CRD](#customresourcedefinition)を通じて、同じ方法でカスタムリソースも管理できます。
|
||
|
||
[アグリゲーションレイヤー](/ja/docs/concepts/extend-kubernetes/api-extension/apiserver-aggregation/)は、独自のスタンドアローンAPIサーバーを書き、デプロイすることで、カスタムリソースに特化した実装の提供を可能にします。メインのAPIサーバーが、処理したいカスタムリソースへのリクエストを委譲することで、他のクライアントからも利用できるようにします。
|
||
|
||
## カスタムリソースの追加方法を選択する
|
||
|
||
CRDは簡単に使えます。アグリゲートAPIはより柔軟です。ニーズに最も合う方法を選択してください。
|
||
|
||
通常、CRDは下記の場合に適しています:
|
||
|
||
* 少数のフィールドしか必要ない
|
||
* そのリソースは社内のみで利用している、または小さいオープンソースプロジェクトの一部で利用している(商用プロダクトではない)
|
||
|
||
### 使いやすさの比較
|
||
|
||
CRDは、アグリゲートAPIと比べ、簡単に作れます。
|
||
|
||
| CRD | アグリゲートAPI |
|
||
| -------------------------- | --------------- |
|
||
| プログラミングが不要で、ユーザーはCRDコントローラーとしてどの言語でも選択可能 | Go言語でプログラミングし、バイナリとイメージの作成が必要。ユーザーはCRDコントローラーとしてどの言語でも選択可能 |
|
||
| 追加のサービスは不要。カスタムリソースはAPIサーバーで処理される | 追加のサービス作成が必要で、障害が発生する可能性がある |
|
||
| CRDが作成されると、継続的なサポートは無い。バグ修正は通常のKubernetesマスターのアップグレードで行われる | 定期的にアップストリームからバグ修正の取り込み、リビルド、そしてアグリゲートAPIサーバーの更新が必要かもしれない |
|
||
| 複数バージョンのAPI管理は不要。例えば、あるリソースを操作するクライアントを管理していた場合、APIのアップグレードと一緒に更新される | 複数バージョンのAPIを管理しなければならない。例えば、世界中に共有されている拡張機能を開発している場合 |
|
||
|
||
### 高度な機能、柔軟性
|
||
|
||
アグリゲートAPIは、例えばストレージレイヤーのカスタマイズのような、より高度なAPI機能と他の機能のカスタマイズを可能にします。
|
||
|
||
| 機能 | 詳細 | CRD | アグリゲートAPI |
|
||
| ---- | ---- | --- | --------------- |
|
||
| バリデーション | エラーを予防し、クライアントと無関係にAPIを発達させることができるようになる。これらの機能は多数のクライアントがおり、同時に全てを更新できないときに最も効果を発揮する | はい、ほとんどのバリデーションは[OpenAPI v3.0 validation](/docs/tasks/access-kubernetes-api/extend-api-custom-resource-definitions/#validation)で、CRDに指定できる。その他のバリデーションは[Webhookのバリデーション](/docs/reference/access-authn-authz/admission-controllers/#validatingadmissionwebhook-alpha-in-1-8-beta-in-1-9)によりサポートされている | はい、任意のバリデーションが可能 |
|
||
| デフォルト設定 | 上記を参照 | はい、[OpenAPI v3.0 validation](/docs/tasks/access-kubernetes-api/extend-api-custom-resource-definitions/#defaulting)の`default`キーワード(1.16でベータ)、または[Mutating Webhook](/docs/reference/access-authn-authz/admission-controllers/#mutatingadmissionwebhook-beta-in-1-9)を通じて可能 | はい |
|
||
| 複数バージョニング | 同じオブジェクトを、違うAPIバージョンで利用可能にする。フィールドの名前を変更するなどのAPIの変更を簡単に行うのに役立つ。クライアントのバージョンを管理する場合、重要性は下がる | [はい](/docs/tasks/access-kubernetes-api/custom-resources/custom-resource-definition-versioning) | はい |
|
||
| カスタムストレージ | 異なる性能のストレージが必要な場合(例えば、キーバリューストアの代わりに時系列データベース)または、セキュリティの分離(例えば、機密情報の暗号化、その他)| いいえ | はい |
|
||
| カスタムビジネスロジック | オブジェクトが作成、読み込み、更新、また削除されるときに任意のチェック、アクションを実行する| はい、[Webhooks](/docs/reference/access-authn-authz/extensible-admission-controllers/#admission-webhooks)を利用 | はい |
|
||
| サブリソースのスケール | HorizontalPodAutoscalerやPodDisruptionBudgetなどのシステムが、新しいリソースと連携できるようにする | [はい](/docs/tasks/access-kubernetes-api/extend-api-custom-resource-definitions/#scale-subresource) | はい |
|
||
| サブリソースの状態 | <ul><li>より詳細なアクセスコントロール: ユーザーがspecセクションに書き込み、コントローラーがstatusセクションに書き込む</li><li>カスタムリソースのデータ変換時にオブジェクトの世代を上げられるようにする(リソースがspecと、statusでセクションが分離している必要がある)</li></ul> | [はい](/docs/tasks/access-kubernetes-api/extend-api-custom-resource-definitions/#status-subresource) | はい |
|
||
| その他のサブリソース | "logs"や"exec"のような、CRUD以外の処理の追加 | いいえ | はい |
|
||
| strategic-merge-patch |`Content-Type: application/strategic-merge-patch+json`で、PATCHをサポートする新しいエンドポイント。ローカル、サーバー、どちらでも更新されうるオブジェクトに有用。さらなる情報は["APIオブジェクトをkubectl patchで決まった場所で更新"](/docs/tasks/run-application/update-api-object-kubectl-patch/)を参照 | いいえ | はい |
|
||
| プロトコルバッファ | プロトコルバッファを使用するクライアントをサポートする新しいリソース | いいえ | はい |
|
||
| OpenAPIスキーマ | サーバーから動的に取得できる型のOpenAPI(スワッガー)スキーマはあるか、許可されたフィールドのみが設定されるようにすることで、ユーザーはフィールド名のスペルミスから保護されているか、型は強制されているか(言い換えると、「文字列」フィールドに「int」を入れさせない) | はい、[OpenAPI v3.0 validation](/docs/tasks/access-kubernetes-api/extend-api-custom-resource-definitions/#validation) スキーマがベース(1.16でGA) | はい |
|
||
|
||
### 一般的な機能
|
||
|
||
CRD、またはアグリゲートAPI、どちらを使ってカスタムリソースを作った場合でも、Kubernetesプラットフォーム外でAPIを実装するのに比べ、多数の機能が提供されます:
|
||
|
||
| 機能 | 何を実現するか |
|
||
| ---- | -------------- |
|
||
| CRUD | 新しいエンドポイントが、HTTP、`kubectl`を通じて、基本的なCRUD処理をサポート |
|
||
| Watch | 新しいエンドポイントが、HTTPを通じて、KubernetesのWatch処理をサポート |
|
||
| Discovery | kubectlやダッシュボードのようなクライアントが、自動的にリソースの一覧表示、個別表示、フィールドの編集処理を提供 |
|
||
| json-patch | 新しいエンドポイントが`Content-Type: application/json-patch+json`を用いたPATCHをサポート |
|
||
| merge-patch | 新しいエンドポイントが`Content-Type: application/merge-patch+json`を用いたPATCHをサポート |
|
||
| HTTPS | 新しいエンドポイントがHTTPSを利用 |
|
||
| ビルトイン認証 | 拡張機能へのアクセスに認証のため、コアAPIサーバー(アグリゲーションレイヤー)を利用 |
|
||
| ビルトイン認可 | 拡張機能へのアクセスにコアAPIサーバーで使われている認可メカニズムを再利用(例、RBAC) |
|
||
| ファイナライザー | 外部リソースの削除が終わるまで、拡張リソースの削除をブロック |
|
||
| Admission Webhooks | 拡張リソースの作成/更新/削除処理時に、デフォルト値の設定、バリデーションを実施 |
|
||
| UI/CLI 表示 | kubectl、ダッシュボードで拡張リソースを表示 |
|
||
| 未設定 vs 空設定 | クライアントは、フィールドの未設定とゼロ値を区別することができる |
|
||
| クライアントライブラリーの生成 | Kubernetesは、一般的なクライアントライブラリーと、タイプ固有のクライアントライブラリーを生成するツールを提供 |
|
||
| ラベルとアノテーション | ツールがコアリソースとカスタムリソースの編集方法を知っているオブジェクト間で、共通のメタデータを提供 |
|
||
|
||
## カスタムリソースのインストール準備
|
||
|
||
クラスターにカスタムリソースを追加する前に、いくつか認識しておくべき事項があります。
|
||
|
||
### サードパーティのコードと新しい障害点
|
||
|
||
CRDを作成しても、勝手に新しい障害点が追加されてしまうことはありませんが（たとえば、サードパーティのコードをAPIサーバーで実行することによって）、パッケージ（たとえば、チャート）またはその他のインストールバンドルには、多くの場合、CRDと新しいカスタムリソースのビジネスロジックを実装するサードパーティコードが入ったDeploymentが含まれます。
|
||
|
||
アグリゲートAPIサーバーのインストールすると、常に新しいDeploymentが付いてきます。
|
||
|
||
### ストレージ
|
||
|
||
カスタムリソースは、ConfigMapと同じ方法でストレージの容量を消費します。多数のカスタムリソースを作成すると、APIサーバーのストレージ容量を超えてしまうかもしれません。
|
||
|
||
アグリゲートAPIサーバーも、メインのAPIサーバーと同じストレージを利用するかもしれません。その場合、同じ問題が発生しえます。
|
||
|
||
### 認証、認可、そして監査
|
||
|
||
CRDでは、APIサーバーのビルトインリソースと同じ認証、認可、そして監査ロギングの仕組みを利用します。
|
||
|
||
もしRBACを使っている場合、ほとんどのRBACのロールは新しいリソースへのアクセスを許可しません。(クラスター管理者ロール、もしくはワイルドカードで作成されたロールを除く)新しいリソースには、明示的にアクセスを許可する必要があります。多くの場合、CRDおよびアグリゲートAPIには、追加するタイプの新しいロール定義がバンドルされています。
|
||
|
||
アグリゲートAPIサーバーでは、APIサーバーのビルトインリソースと同じ認証、認可、そして監査の仕組みを使う場合と使わない場合があります。
|
||
|
||
## カスタムリソースへのアクセス
|
||
|
||
Kubernetesの[クライアントライブラリー](/docs/reference/using-api/client-libraries/)を使い、カスタムリソースにアクセスすることが可能です。全てのクライアントライブラリーがカスタムリソースをサポートしているわけでは無いですが、GoとPythonのライブラリーはサポートしています。
|
||
|
||
カスタムリソースは、下記のような方法で操作できます:
|
||
|
||
- kubectl
|
||
- kubernetesの動的クライアント
|
||
- 自作のRESTクライアント
|
||
- [Kubernetesクライアント生成ツール](https://github.com/kubernetes/code-generator)を使い生成したクライアント(生成は高度な作業ですが、一部のプロジェクトは、CRDまたはAAとともにクライアントを提供する場合があります)
|
||
|
||
{{% /capture %}}
|
||
|
||
{{% capture whatsnext %}}
|
||
|
||
* [Kubernetes APIをアグリゲーションレイヤーで拡張する方法](/ja/docs/concepts/extend-kubernetes/api-extension/apiserver-aggregation/)について学ぶ
|
||
* [Kubernetes APIをCustomResourceDefinitionで拡張する方法](/docs/tasks/access-kubernetes-api/custom-resources/custom-resource-definitions/)について学ぶ
|
||
|
||
{{% /capture %}}
|