From 4b883eb10078304cf97eee18001b53323ddb94b7 Mon Sep 17 00:00:00 2001 From: ystkfujii Date: Wed, 8 Mar 2023 02:52:38 +0900 Subject: [PATCH 1/2] Clarify API version stability and guidelines --- .../docs/concepts/overview/kubernetes-api.md | 16 ++++++++++--- content/ja/docs/reference/using-api/_index.md | 23 ++++++++++--------- 2 files changed, 25 insertions(+), 14 deletions(-) diff --git a/content/ja/docs/concepts/overview/kubernetes-api.md b/content/ja/docs/concepts/overview/kubernetes-api.md index 5b6388a306..4fb0b6ec5a 100644 --- a/content/ja/docs/concepts/overview/kubernetes-api.md +++ b/content/ja/docs/concepts/overview/kubernetes-api.md @@ -145,7 +145,9 @@ APIの発展や拡張を簡易に行えるようにするため、Kubernetesは[ APIリソースは、APIグループ、リソースタイプ、ネームスペース（namespacedリソースのための）、名前によって区別されます。APIサーバーは、APIバージョン間の変換を透過的に処理します。すべてのバージョンの違いは、実際のところ同じ永続データとして表現されます。APIサーバーは、同じ基本的なデータを複数のAPIバージョンで提供することができます。 -例えば、同じリソースで`v1`と`v1beta1`の2つのバージョンが有ることを考えてみます。`v1beta1`バージョンのAPIを利用しオブジェクトを最初に作成したとして、`v1beta1`もしくは`v1`どちらのAPIバージョンを利用してもオブジェクトのread、update、deleteができます。 +例えば、同じリソースで`v1`と`v1beta1`の2つのバージョンが有ることを考えてみます。 +`v1beta1`バージョンのAPIを利用しオブジェクトを最初に作成したとして、`v1beta1`バージョンが非推奨となり削除されるまで、`v1beta1`もしくは`v1`どちらのAPIバージョンを利用してもオブジェクトのread、update、deleteができます。 +その時点では `v1` APIを使用してオブジェクトの修正やアクセスを継続することが可能です。 ## APIの変更 @@ -156,10 +158,18 @@ Kubernetesプロジェクトは、既存のクライアントとの互換性を 基本的に、新しいAPIリソースと新しいリソースフィールドは追加することができます。 リソースまたはフィールドを削除するには、[API非推奨ポリシー](/docs/reference/using-api/deprecation-policy/)に従ってください。 -Kubernetesは、公式のKubernetes APIが一度一般提供（GA）に達した場合、通常は`v1`APIバージョンです、互換性を維持することを強い責任があります。さらに、Kubernetesは _beta_ についても可能な限り互換性を維持し続けます。ベータAPIを採用した場合、その機能が安定版になったあとでも、APIを利用してクラスタを操作し続けることができます。 +Kubernetesは、公式のKubernetes APIが一度一般提供（GA）に達した場合、通常は`v1`APIバージョンです、互換性を維持することを強い責任があります。 +さらに、Kubernetesは、公式Kubernetes APIの _beta_ APIバージョン経由で永続化されたデータとの互換性を維持します。 +そして、機能が安定したときにGA APIバージョン経由でデータを変換してアクセスできることを保証します。 + +beta APIを採用した場合、APIが卒業(Graduate)したら、後続のbetaまたはstable APIに移行する必要があります。 +これを行うのに最適な時期は、オブジェクトが両方のAPIバージョンから同時にアクセスできるbeta APIが非推奨期間です。 +beta APIが非推奨期間を終えて提供されなくなったら、代替APIバージョンを使用する必要があります。 {{< note >}} -Kubernetesは、 _alpha_ APIバージョンについても互換性の維持に注力しますが、いくつかの事情により不可である場合もあります。アルファAPIバージョンを使っている場合、クラスタのアップグレードやAPIが変更された場合に備えて、Kubernetesのリリースノートを確認してください。 +Kubernetesは、 _alpha_ APIバージョンについても互換性の維持に注力しますが、いくつかの事情により不可である場合もあります。 +alpha APIバージョンを使っている場合、クラスターをアップグレードする時にKubernetesのリリースノートを確認してください。 +アップグレードのために既存のalphaオブジェクトをすべて削除する必要がある互換性の無い方法でAPIが変更される場合があります。 {{< /note >}} APIバージョンレベルの定義に関する詳細は[APIバージョンのリファレンス](/docs/reference/using-api/#api-versioning)を参照してください。 diff --git a/content/ja/docs/reference/using-api/_index.md b/content/ja/docs/reference/using-api/_index.md index 543b78b2c8..caad234abb 100644 --- a/content/ja/docs/reference/using-api/_index.md +++ b/content/ja/docs/reference/using-api/_index.md @@ -14,7 +14,7 @@ card: このセクションでは、Kubernetes APIのリファレンス情報を提供します。 REST APIはKubernetesの基本的な構造です。 -すべての操作とコンポーネント間のと通信、および外部ユーザーのコマンドは、REST API呼び出しでありAPIサーバーが処理します。 +すべての操作とコンポーネント間の通信、および外部ユーザーのコマンドは、REST API呼び出しでありAPIサーバーが処理します。 その結果、Kubernetesプラットフォーム内のすべてのものは、APIオブジェクトとして扱われ、[API](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/)に対応するエントリーがあります。 @@ -38,30 +38,31 @@ APIのバージョンが異なると、安定性やサポートのレベルも 各レベルの概要は以下の通りです: - Alpha: - - バージョン名に「alpha」が含まれています（例：「v1alpha1」）。 + - バージョン名に`alpha`が含まれています（例：`v1alpha1`）。 + - 組み込みのalpha APIバージョンはデフォルトで無効化されており、使用するためには`kube-apiserver`の設定で明示的に有効にする必要があります。 - バグが含まれている可能性があります。 機能を有効にするとバグが露呈する可能性があります。 - 機能がデフォルトで無効になっている可能性があります。 - - ある機能のサポートは、予告なしにいつでも中止される可能性があります。 + - alpha APIのサポートは、予告なしにいつでも中止される可能性があります。 - 後にリリースされるソフトウェアで、互換性のない方法で予告なく変更される可能性があります。 - バグのリスクが高く、長期的なサポートが得られないため、短期間のテストクラスターのみでの使用を推奨します。 - Beta: - バージョン名には `beta` が含まれています(例：`v2beta3`)。 + - 組み込みのbeta APIバージョンはデフォルトで無効化されており、使用するためには`kube-apiserver`の設定で明示的に有効にする必要があります。 + (**例外として**Kubernetes 1.22以前に導入されたAPIのbetaバージョンはデフォルトで有効化されています) + - 組み込みのbeta APIバージョンは、導入から非推奨となるまでが9ヶ月または3マイナーリリース（どちらかの長い期間）、そして非推奨から削除まで9ヶ月または3マイナーリリース（どちらかの長い期間）の最大存続期間を持ちます。 - ソフトウェアは十分にテストされています。 機能を有効にすることは安全であると考えられています。 - 機能はデフォルトで有効になっています。 - 機能のサポートが打ち切られることはありませんが、詳細は変更される可能性があります。 - - オブジェクトのスキーマやセマンティクスは、その後のベータ版や安定版のリリースで互換性のない方法で変更される可能性があります。 + - オブジェクトのスキーマやセマンティクスは、その後のベータ版や安定版のAPIバージョンで互換性のない方法で変更される可能性があります。 このような場合には、移行手順が提供されます。 - スキーマの変更に伴い、APIオブジェクトの削除、編集、再作成が必要になる場合があります。 - 編集作業は単純ではないかもしれません。 + 後続のbetaまたはstable APIバージョンに適応することはAPIオブジェクトの編集や再作成が必要になる場合があり、単純ではないかもしれません。 移行に伴い、その機能に依存しているアプリケーションのダウンタイムが必要になる場合があります。 - 本番環境での使用は推奨しません。 - 後続のリリース は、互換性のない変更を導入する可能性があります。 - 独立してアップグレード可能な複数のクラスターがある場合、この制限を緩和できる可能性があります。 + 後続のリリースは、互換性のない変更を導入する可能性があります。 + beta APIが非推奨となり提供されなくなった際には、後続のbetaまたはstable APIバージョンに移行するためにbeta APIバージョンを使用する必要があります。 {{< note >}} ベータ版の機能をお試しいただき、ご意見をお寄せください。 @@ -70,7 +71,7 @@ APIのバージョンが異なると、安定性やサポートのレベルも - Stable: - バージョン名は `vX` であり、`X` は整数である。 - - 安定版の機能は、リリースされたソフトウェアの中で、その後の多くのバージョンに登場します。 + - stable APIバージョンはKubernetesのメジャーバージョン内の全てのリリースで利用可能であり、stable APIを削除したKubernetesのメジャーバージョンリビジョンの計画は現在ありません。 ## APIグループ From 58cf159471acd8fedaa652a7c559edcdb91a6e46 Mon Sep 17 00:00:00 2001 From: Yoshitaka Fujii <76274657+ystkfujii@users.noreply.github.com> Date: Thu, 16 Mar 2023 00:48:51 +0900 Subject: [PATCH 2/2] Apply suggestions from code review Co-authored-by: Toshiaki Inukai <82919057+t-inu@users.noreply.github.com> --- content/ja/docs/concepts/overview/kubernetes-api.md | 8 ++++---- content/ja/docs/reference/using-api/_index.md | 8 ++++---- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/content/ja/docs/concepts/overview/kubernetes-api.md b/content/ja/docs/concepts/overview/kubernetes-api.md index 4fb0b6ec5a..982331d2f1 100644 --- a/content/ja/docs/concepts/overview/kubernetes-api.md +++ b/content/ja/docs/concepts/overview/kubernetes-api.md @@ -147,7 +147,7 @@ APIリソースは、APIグループ、リソースタイプ、ネームスペ 例えば、同じリソースで`v1`と`v1beta1`の2つのバージョンが有ることを考えてみます。 `v1beta1`バージョンのAPIを利用しオブジェクトを最初に作成したとして、`v1beta1`バージョンが非推奨となり削除されるまで、`v1beta1`もしくは`v1`どちらのAPIバージョンを利用してもオブジェクトのread、update、deleteができます。 -その時点では `v1` APIを使用してオブジェクトの修正やアクセスを継続することが可能です。 +その時点では、`v1` APIを使用してオブジェクトの修正やアクセスを継続することが可能です。 ## APIの変更 @@ -158,18 +158,18 @@ Kubernetesプロジェクトは、既存のクライアントとの互換性を 基本的に、新しいAPIリソースと新しいリソースフィールドは追加することができます。 リソースまたはフィールドを削除するには、[API非推奨ポリシー](/docs/reference/using-api/deprecation-policy/)に従ってください。 -Kubernetesは、公式のKubernetes APIが一度一般提供（GA）に達した場合、通常は`v1`APIバージョンです、互換性を維持することを強い責任があります。 +Kubernetesは、通常はAPIバージョン`v1`として、公式のKubernetes APIが一度一般提供(GA)に達した場合、互換性を維持することを強く確約します。 さらに、Kubernetesは、公式Kubernetes APIの _beta_ APIバージョン経由で永続化されたデータとの互換性を維持します。 そして、機能が安定したときにGA APIバージョン経由でデータを変換してアクセスできることを保証します。 beta APIを採用した場合、APIが卒業(Graduate)したら、後続のbetaまたはstable APIに移行する必要があります。 -これを行うのに最適な時期は、オブジェクトが両方のAPIバージョンから同時にアクセスできるbeta APIが非推奨期間です。 +これを行うのに最適な時期は、オブジェクトが両方のAPIバージョンから同時にアクセスできるbeta APIの非推奨期間中です。 beta APIが非推奨期間を終えて提供されなくなったら、代替APIバージョンを使用する必要があります。 {{< note >}} Kubernetesは、 _alpha_ APIバージョンについても互換性の維持に注力しますが、いくつかの事情により不可である場合もあります。 alpha APIバージョンを使っている場合、クラスターをアップグレードする時にKubernetesのリリースノートを確認してください。 -アップグレードのために既存のalphaオブジェクトをすべて削除する必要がある互換性の無い方法でAPIが変更される場合があります。 +APIが互換性のない方法で変更された場合は、アップグレードをする前に既存のalphaオブジェクトをすべて削除する必要があります。 {{< /note >}} APIバージョンレベルの定義に関する詳細は[APIバージョンのリファレンス](/docs/reference/using-api/#api-versioning)を参照してください。 diff --git a/content/ja/docs/reference/using-api/_index.md b/content/ja/docs/reference/using-api/_index.md index caad234abb..dd2a237834 100644 --- a/content/ja/docs/reference/using-api/_index.md +++ b/content/ja/docs/reference/using-api/_index.md @@ -38,7 +38,7 @@ APIのバージョンが異なると、安定性やサポートのレベルも 各レベルの概要は以下の通りです: - Alpha: - - バージョン名に`alpha`が含まれています（例：`v1alpha1`）。 + - バージョン名に`alpha`が含まれています(例：`v1alpha1`)。 - 組み込みのalpha APIバージョンはデフォルトで無効化されており、使用するためには`kube-apiserver`の設定で明示的に有効にする必要があります。 - バグが含まれている可能性があります。 機能を有効にするとバグが露呈する可能性があります。 @@ -50,7 +50,7 @@ APIのバージョンが異なると、安定性やサポートのレベルも - バージョン名には `beta` が含まれています(例：`v2beta3`)。 - 組み込みのbeta APIバージョンはデフォルトで無効化されており、使用するためには`kube-apiserver`の設定で明示的に有効にする必要があります。 (**例外として**Kubernetes 1.22以前に導入されたAPIのbetaバージョンはデフォルトで有効化されています) - - 組み込みのbeta APIバージョンは、導入から非推奨となるまでが9ヶ月または3マイナーリリース（どちらかの長い期間）、そして非推奨から削除まで9ヶ月または3マイナーリリース（どちらかの長い期間）の最大存続期間を持ちます。 + - 組み込みのbeta APIバージョンは、導入から非推奨となるまでが9ヶ月または3マイナーリリース(どちらかの長い期間)、そして非推奨から削除まで9ヶ月または3マイナーリリース(どちらかの長い期間)の最大存続期間を持ちます。 - ソフトウェアは十分にテストされています。 機能を有効にすることは安全であると考えられています。 - 機能のサポートが打ち切られることはありませんが、詳細は変更される可能性があります。 @@ -62,7 +62,7 @@ APIのバージョンが異なると、安定性やサポートのレベルも - 本番環境での使用は推奨しません。 後続のリリースは、互換性のない変更を導入する可能性があります。 - beta APIが非推奨となり提供されなくなった際には、後続のbetaまたはstable APIバージョンに移行するためにbeta APIバージョンを使用する必要があります。 + beta APIを使用する場合、そのbeta APIが非推奨となり提供されなくなった際には、後続のbetaまたはstable APIバージョンに移行する必要があります。 {{< note >}} ベータ版の機能をお試しいただき、ご意見をお寄せください。 @@ -71,7 +71,7 @@ APIのバージョンが異なると、安定性やサポートのレベルも - Stable: - バージョン名は `vX` であり、`X` は整数である。 - - stable APIバージョンはKubernetesのメジャーバージョン内の全てのリリースで利用可能であり、stable APIを削除したKubernetesのメジャーバージョンリビジョンの計画は現在ありません。 + - stable APIバージョンはKubernetesのメジャーバージョン内の全てのリリースで利用可能であり、stable APIを削除するようなKubernetesのメジャーバージョンの修正は、現在計画されていません。 ## APIグループ