Kubernetesクラスターが必要、かつそのクラスターと通信するためにkubectlコマンドラインツールが設定されている必要があります。 このチュートリアルは、コントロールプレーンのホストとして動作していない少なくとも2つのノードを持つクラスターで実行することをおすすめします。 まだクラスターがない場合、minikubeを使って作成するか、 以下のいずれかのKubernetesプレイグラウンドも使用できます:
[カスタムリソース](/docs/concepts/extend-kubernetes/api-extension/custom-resources/)についての基本的な理解が必要です。 作業するKubernetesサーバーは次のバージョン以降のものである必要があります: v1.16.バージョンを確認するには次のコマンドを実行してください: kubectl version.
apiextensions.k8s.io/v1beta1では、versionsの代わりにversionフィールドがありました。
versionフィールドは非推奨でオプションですが、空でない場合はversionsフィールドの最初の項目と一致する必要があります。apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
# 名前は以下のspecフィールドと一致する必要があり、<plural>.<group>の形式である必要があります。
name: crontabs.example.com
spec:
# REST APIに使用するグループ名: /apis/<group>/<version>
group: example.com
# このCustomResourceDefinitionでサポートされるバージョンのリスト
versions:
- name: v1beta1
# 各バージョンはServedフラグで有効/無効を切り替えられます。
served: true
# 1つのバージョンのみをストレージバージョンとしてマークする必要があります。
storage: true
# スキーマは必須です
schema:
openAPIV3Schema:
type: object
properties:
host:
type: string
port:
type: string
- name: v1
served: true
storage: false
schema:
openAPIV3Schema:
type: object
properties:
host:
type: string
port:
type: string
# conversionセクションはKubernetes 1.13+で導入され、デフォルト値はNone変換(strategyサブフィールドがNoneに設定)です。
conversion:
# None変換はすべてのバージョンで同じスキーマを前提とし、カスタムリソースのapiVersionフィールドのみを適切な値に設定します
strategy: None
# NamespacedまたはClusterのいずれか
scope: Namespaced
names:
# URLで使用する複数形の名前: /apis/<group>/<version>/<plural>
plural: crontabs
# CLIでのエイリアスおよび表示に使用する単数形の名前
singular: crontab
# kindは通常、キャメルケースの単数形の型名です。リソースマニフェストでこれを使用します。
kind: CronTab
# shortNamesを使用するとCLIでリソースをより短い文字列で指定できます。
shortNames:
- ct
# apiextensions.k8s.io/v1への移行に伴い、v1.16で非推奨になりました。
apiVersion: apiextensions.k8s.io/v1beta1
kind: CustomResourceDefinition
metadata:
# 名前は以下のspecフィールドと一致する必要があり、<plural>.<group>の形式である必要があります。
name: crontabs.example.com
spec:
# REST APIに使用するグループ名: /apis/<group>/<version>
group: example.com
# このCustomResourceDefinitionでサポートされるバージョンのリスト
versions:
- name: v1beta1
# 各バージョンはServedフラグで有効/無効を切り替えられます。
served: true
# 1つのバージョンのみをストレージバージョンとしてマークする必要があります。
storage: true
- name: v1
served: true
storage: false
validation:
openAPIV3Schema:
type: object
properties:
host:
type: string
port:
type: string
# conversionセクションはKubernetes 1.13+で導入され、デフォルト値はNone変換(strategyサブフィールドがNoneに設定)です。
conversion:
# None変換はすべてのバージョンで同じスキーマを前提とし、
# カスタムリソースのapiVersionフィールドのみを適切な値に設定します。
strategy: None
# NamespacedまたはClusterのいずれか
scope: Namespaced
names:
# URLで使用する複数形の名前: /apis/<group>/<version>/<plural>
plural: crontabs
# CLIでのエイリアスおよび表示に使用する単数形の名前
singular: crontab
# kindは通常、パスカルケースの単数形の型名です。リソースマニフェストでこれを使用します。
kind: CronTab
# shortNamesを使用するとCLIでリソースをより短い文字列で指定できます。
shortNames:
- ct
Kubernetes v1.19 [stable]
apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
name: crontabs.example.com
spec:
group: example.com
names:
plural: crontabs
singular: crontab
kind: CronTab
scope: Namespaced
versions:
- name: v1alpha1
served: true
storage: false
# カスタムリソースのv1alpha1バージョンが非推奨であることを示します。
# このバージョンへのAPIリクエストはサーバーレスポンスに警告ヘッダーを受け取ります。
deprecated: true
# v1alpha1 APIリクエストを行うAPIクライアントに返されるデフォルトの警告を上書きします。
deprecationWarning: "example.com/v1alpha1 CronTab is deprecated; see http://example.com/v1alpha1-v1 for instructions to migrate to example.com/v1 CronTab"
schema: ...
- name: v1beta1
served: true
# カスタムリソースのv1beta1バージョンが非推奨であることを示します。
# このバージョンへのAPIリクエストはサーバーレスポンスに警告ヘッダーを受け取ります。
# このバージョンにはデフォルトの警告メッセージが返されます。
deprecated: true
schema: ...
- name: v1
served: true
storage: true
schema: ...
# apiextensions.k8s.io/v1への移行に伴い、v1.16で非推奨になりました。
apiVersion: apiextensions.k8s.io/v1beta1
kind: CustomResourceDefinition
metadata:
name: crontabs.example.com
spec:
group: example.com
names:
plural: crontabs
singular: crontab
kind: CronTab
scope: Namespaced
validation: ...
versions:
- name: v1alpha1
served: true
storage: false
# カスタムリソースのv1alpha1バージョンが非推奨であることを示します。
# このバージョンへのAPIリクエストはサーバーレスポンスに警告ヘッダーを受け取ります。
deprecated: true
# v1alpha1 APIリクエストを行うAPIクライアントに返されるデフォルトの警告を上書きします。
deprecationWarning: "example.com/v1alpha1 CronTab is deprecated; see http://example.com/v1alpha1-v1 for instructions to migrate to example.com/v1 CronTab"
- name: v1beta1
served: true
# カスタムリソースのv1beta1バージョンが非推奨であることを示します。
# このバージョンへのAPIリクエストはサーバーレスポンスに警告ヘッダーを受け取ります。
# このバージョンにはデフォルトの警告メッセージが返されます。
deprecated: true
- name: v1
served: true
storage: true
Kubernetes v1.16 [stable]
CustomResourceWebhookConversionフィーチャーゲートが有効である必要があります。
ベータ機能として多くのクラスターで自動的に有効化されています。
詳細についてはフィーチャーゲートのドキュメントを参照してください。ClientAuthフィールドを空のままにしており、デフォルトはNoClientCertです。
つまり、Webhookサーバーはクライアント(おそらくAPIサーバー)の身元を認証しません。
相互TLSやその他の方法でクライアントを認証する必要がある場合は、APIサーバーの認証方法を参照してください。apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
# 名前は以下のspecフィールドと一致する必要があり、<plural>.<group>の形式である必要があります。
name: crontabs.example.com
spec:
# REST APIに使用するグループ名: /apis/<group>/<version>
group: example.com
# このCustomResourceDefinitionでサポートされるバージョンのリスト
versions:
- name: v1beta1
# 各バージョンはServedフラグで有効/無効を切り替えられます。
served: true
# 1つのバージョンのみをストレージバージョンとしてマークする必要があります。
storage: true
# トップレベルのスキーマが定義されていない場合、各バージョンが独自のスキーマを定義できます。
schema:
openAPIV3Schema:
type: object
properties:
hostPort:
type: string
- name: v1
served: true
storage: false
schema:
openAPIV3Schema:
type: object
properties:
host:
type: string
port:
type: string
conversion:
# Webhookストラテジーは、カスタムリソース間のあらゆる変換に対して外部Webhookを呼び出すようAPIサーバーに指示します。
strategy: Webhook
# Webhookは、strategyが`Webhook`の場合に必須であり、APIサーバーが呼び出すWebhookエンドポイントを設定します。
webhook:
# conversionReviewVersionsはWebhookが理解/推奨するConversionReviewのバージョンを示します。
# リストの中でAPIサーバーが理解できる最初のバージョンがWebhookに送信されます。
# Webhookは受け取ったのと同じバージョンのConversionReviewオブジェクトで応答する必要があります。
conversionReviewVersions: ["v1","v1beta1"]
clientConfig:
service:
namespace: default
name: example-conversion-webhook-server
path: /crdconvert
caBundle: "Ci0tLS0tQk...<base64-encoded PEM bundle>...tLS0K"
# NamespacedまたはClusterのいずれか
scope: Namespaced
names:
# URLで使用する複数形の名前: /apis/<group>/<version>/<plural>
plural: crontabs
# CLIでのエイリアスおよび表示に使用する単数形の名前
singular: crontab
# kindは通常、キャメルケースの単数形の型名です。リソースマニフェストでこれを使用します。
kind: CronTab
# shortNamesを使用するとCLIでリソースをより短い文字列で指定できます。
shortNames:
- ct
# apiextensions.k8s.io/v1への移行に伴い、v1.16で非推奨になりました。
apiVersion: apiextensions.k8s.io/v1beta1
kind: CustomResourceDefinition
metadata:
# 名前は以下のspecフィールドと一致する必要があり、<plural>.<group>の形式である必要があります。
name: crontabs.example.com
spec:
# REST APIに使用するグループ名: /apis/<group>/<version>
group: example.com
# 以下のOpenAPIスキーマで指定されていないオブジェクトフィールドを除去します。
preserveUnknownFields: false
# このCustomResourceDefinitionでサポートされるバージョンのリスト
versions:
- name: v1beta1
# 各バージョンはServedフラグで有効/無効を切り替えられます。
served: true
# 1つのバージョンのみをストレージバージョンとしてマークする必要があります。
storage: true
# トップレベルのスキーマが定義されていない場合、各バージョンが独自のスキーマを定義できます。
schema:
openAPIV3Schema:
type: object
properties:
hostPort:
type: string
- name: v1
served: true
storage: false
schema:
openAPIV3Schema:
type: object
properties:
host:
type: string
port:
type: string
conversion:
# Webhookストラテジーは、カスタムリソース間のあらゆる変換に対して外部Webhookを呼び出すようAPIサーバーに指示します。
strategy: Webhook
# webhookClientConfigは、strategyが`Webhook`の場合に必須であり、APIサーバーが呼び出すWebhookエンドポイントを設定します。
webhookClientConfig:
service:
namespace: default
name: example-conversion-webhook-server
path: /crdconvert
caBundle: "Ci0tLS0tQk...<base64-encoded PEM bundle>...tLS0K"
# NamespacedまたはClusterのいずれか
scope: Namespaced
names:
# URLで使用する複数形の名前: /apis/<group>/<version>/<plural>
plural: crontabs
# CLIでのエイリアスおよび表示に使用する単数形の名前
singular: crontab
# kindは通常、キャメルケースの単数形の型名です。リソースマニフェストでこれを使用します。
kind: CronTab
# shortNamesを使用するとCLIでリソースをより短い文字列で指定できます。
shortNames:
- ct
apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
...
spec:
...
conversion:
strategy: Webhook
webhook:
clientConfig:
url: "https://my-webhook.example.com:9443/my-webhook-path"
...
# apiextensions.k8s.io/v1への移行に伴い、v1.16で非推奨になりました。
apiVersion: apiextensions.k8s.io/v1beta1
kind: CustomResourceDefinition
...
spec:
...
conversion:
strategy: Webhook
webhookClientConfig:
url: "https://my-webhook.example.com:9443/my-webhook-path"
...
apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
...
spec:
...
conversion:
strategy: Webhook
webhook:
clientConfig:
service:
namespace: my-service-namespace
name: my-service-name
path: /my-path
port: 1234
caBundle: "Ci0tLS0tQk...<base64-encoded PEM bundle>...tLS0K"
...
# apiextensions.k8s.io/v1への移行に伴い、v1.16で非推奨になりました。
apiVersion: apiextensions.k8s.io/v1beta1
kind: CustomResourceDefinition
...
spec:
...
conversion:
strategy: Webhook
webhookClientConfig:
service:
namespace: my-service-namespace
name: my-service-name
path: /my-path
port: 1234
caBundle: "Ci0tLS0tQk...<base64-encoded PEM bundle>...tLS0K"
...
apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
...
spec:
...
conversion:
strategy: Webhook
webhook:
conversionReviewVersions: ["v1", "v1beta1"]
...
conversionReviewVersionsはapiextensions.k8s.io/v1カスタムリソース定義を作成する際の必須フィールドです。
Webhookは現在および1つ前のAPIサーバーが理解できるConversionReviewバージョンを少なくとも1つサポートする必要があります。
# apiextensions.k8s.io/v1への移行に伴い、v1.16で非推奨になりました。
apiVersion: apiextensions.k8s.io/v1beta1
kind: CustomResourceDefinition
...
spec:
...
conversion:
strategy: Webhook
conversionReviewVersions: ["v1", "v1beta1"]
...
conversionReviewVersionsが指定されない場合、apiextensions.k8s.io/v1beta1カスタムリソース定義を作成する際のデフォルトはv1beta1です。
{
"apiVersion": "apiextensions.k8s.io/v1",
"kind": "ConversionReview",
"request": {
# この変換呼び出しを一意に識別するランダムなuid
"uid": "705ab4f5-6393-11e8-b7cc-42010a800002",
# オブジェクトを変換すべきAPIグループとバージョン
"desiredAPIVersion": "example.com/v1",
# 変換するオブジェクトのリスト。
# 1つまたは複数のバージョン、1つまたは複数のオブジェクトを含む場合があります。
"objects": [
{
"kind": "CronTab",
"apiVersion": "example.com/v1beta1",
"metadata": {
"creationTimestamp": "2019-09-04T14:03:02Z",
"name": "local-crontab",
"namespace": "default",
"resourceVersion": "143",
"uid": "3415a7fc-162b-4300-b5da-fd6083580d66"
},
"hostPort": "localhost:1234"
},
{
"kind": "CronTab",
"apiVersion": "example.com/v1beta1",
"metadata": {
"creationTimestamp": "2019-09-03T13:02:01Z",
"name": "remote-crontab",
"resourceVersion": "12893",
"uid": "359a83ec-b575-460d-b553-d859cedde8a0"
},
"hostPort": "example.com:2345"
}
]
}
}
{
# apiextensions.k8s.io/v1への移行に伴い、v1.16で非推奨になりました。
"apiVersion": "apiextensions.k8s.io/v1beta1",
"kind": "ConversionReview",
"request": {
# この変換呼び出しを一意に識別するランダムなuid
"uid": "705ab4f5-6393-11e8-b7cc-42010a800002",
# オブジェクトを変換すべきAPIグループとバージョン
"desiredAPIVersion": "example.com/v1",
# 変換するオブジェクトのリスト。
# 1つまたは複数のバージョンの1つまたは複数のオブジェクトを含む場合があります。
"objects": [
{
"kind": "CronTab",
"apiVersion": "example.com/v1beta1",
"metadata": {
"creationTimestamp": "2019-09-04T14:03:02Z",
"name": "local-crontab",
"namespace": "default",
"resourceVersion": "143",
"uid": "3415a7fc-162b-4300-b5da-fd6083580d66"
},
"hostPort": "localhost:1234"
},
{
"kind": "CronTab",
"apiVersion": "example.com/v1beta1",
"metadata": {
"creationTimestamp": "2019-09-03T13:02:01Z",
"name": "remote-crontab",
"resourceVersion": "12893",
"uid": "359a83ec-b575-460d-b553-d859cedde8a0"
},
"hostPort": "example.com:2345"
}
]
}
}
{
"apiVersion": "apiextensions.k8s.io/v1",
"kind": "ConversionReview",
"response": {
# <request.uid>と一致する必要があります。
"uid": "705ab4f5-6393-11e8-b7cc-42010a800002",
"result": {
"status": "Success"
},
# オブジェクトはrequest.objectsの順序と一致し、apiVersionが<request.desiredAPIVersion>に設定されている必要があります。
# kind、metadata.uid、metadata.name、metadata.namespaceフィールドはWebhookによって変更してはなりません。
# metadata.labelsとmetadata.annotationsフィールドはWebhookによって変更できます。
# Webhookによるmetadataフィールドのその他すべての変更は無視されます。
"convertedObjects": [
{
"kind": "CronTab",
"apiVersion": "example.com/v1",
"metadata": {
"creationTimestamp": "2019-09-04T14:03:02Z",
"name": "local-crontab",
"namespace": "default",
"resourceVersion": "143",
"uid": "3415a7fc-162b-4300-b5da-fd6083580d66"
},
"host": "localhost",
"port": "1234"
},
{
"kind": "CronTab",
"apiVersion": "example.com/v1",
"metadata": {
"creationTimestamp": "2019-09-03T13:02:01Z",
"name": "remote-crontab",
"resourceVersion": "12893",
"uid": "359a83ec-b575-460d-b553-d859cedde8a0"
},
"host": "example.com",
"port": "2345"
}
]
}
}
{
# apiextensions.k8s.io/v1への移行に伴い、v1.16で非推奨になりました。
"apiVersion": "apiextensions.k8s.io/v1beta1",
"kind": "ConversionReview",
"response": {
# <request.uid>と一致する必要があります。
"uid": "705ab4f5-6393-11e8-b7cc-42010a800002",
"result": {
"status": "Failed"
},
# オブジェクトはrequest.objectsの順序と一致し、apiVersionが<request.desiredAPIVersion>に設定されている必要があります。
# kind、metadata.uid、metadata.name、metadata.namespaceフィールドはWebhookによって変更してはなりません。
# metadata.labelsとmetadata.annotationsフィールドはWebhookによって変更できます。
# Webhookによるmetadataフィールドのその他すべての変更は無視されます。
"convertedObjects": [
{
"kind": "CronTab",
"apiVersion": "example.com/v1",
"metadata": {
"creationTimestamp": "2019-09-04T14:03:02Z",
"name": "local-crontab",
"namespace": "default",
"resourceVersion": "143",
"uid": "3415a7fc-162b-4300-b5da-fd6083580d66"
},
"host": "localhost",
"port": "1234"
},
{
"kind": "CronTab",
"apiVersion": "example.com/v1",
"metadata": {
"creationTimestamp": "2019-09-03T13:02:01Z",
"name": "remote-crontab",
"resourceVersion": "12893",
"uid": "359a83ec-b575-460d-b553-d859cedde8a0"
},
"host": "example.com",
"port": "2345"
}
]
}
}
{
"apiVersion": "apiextensions.k8s.io/v1",
"kind": "ConversionReview",
"response": {
"uid": "<value from request.uid>",
"result": {
"status": "Failed",
"message": "hostPort could not be parsed into a separate host and port"
}
}
}
{
# apiextensions.k8s.io/v1への移行に伴い、v1.16で非推奨になりました。
"apiVersion": "apiextensions.k8s.io/v1beta1",
"kind": "ConversionReview",
"response": {
"uid": "<value from request.uid>",
"result": {
"status": "Failed",
"message": "hostPort could not be parsed into a separate host and port"
}
}
}
kubectlを使用してCRDオブジェクトのstatusサブリソースにパッチを当てる方法の例を以下に示します:
kubectl patch customresourcedefinitions <CRD_Name> --subresource='status' --type='merge' -p '{"status":{"storedVersions":["v1"]}}'