第4章 ClusterExtension [olm.operatorframework.io/v1]

install

object

install は、プリフライトチェック設定などの ClusterExtension のインストールオプションを設定するために使用されるオプションフィールドです。

namespace

string

namespace は Kubernetes namespace への参照です。これは、提供された ServiceAccount が存在する必要がある namespace です。また、拡張機能の namespace スコープのリソースがクラスターに適用されるデフォルトの namespace も指定します。一部の拡張機能には、他の namespace に適用される namespace スコープのリソースが含まれている場合があります。この namespace は存在している必要があります。

namespace は必須かつ変更不可能で、[RFC 1123] で定義されている DNS ラベル標準に従います。小文字の英数字またはハイフン (-) のみを含み、先頭と末尾は英数字で、63 文字以内である必要があります。

[RFC 1123]: https://tools.ietf.org/html/rfc1123

serviceAccount

object

serviceAccount は、拡張機能の管理に必要なクラスターとのすべてのやり取りを実行するために使用される ServiceAccount への参照です。これらのやり取りを実行するには、ServiceAccount に必要なパーミッションを設定する必要があります。ServiceAccount は、spec で参照される namespace に存在する必要があります。serviceAccount は必須です。

source

object

source は必須フィールドで、この ClusterExtension のコンテンツのインストールソースを選択します。選択は、sourceType を設定することによって実行されます。

現在実装されている sourceType は Catalog のみであり、sourcetype を "Catalog" に設定するには、catalog フィールドも定義する必要があります。

以下は、source 定義の最小限の例 (yaml 形式) です。

source: sourceType: Catalog catalog: packageName: example-package

preflight

object

preflight は、packageName フィールドで指定されたパッケージのコンテンツをインストールまたはアップグレードする前に実行されるチェックを設定するために使用できるオプションフィールドです。

指定すると、インストール/アップグレードアクションのデフォルトの preflight 設定が置き換えられます。指定しない場合は、デフォルトの設定が使用されます。

crdUpgradeSafety

object

crdUpgradeSafety は、インストールされたコンテンツのアップグレード前に実行される CRD Upgrade Safety のプリフライトチェックを設定するために使用されます。

CRD Upgrade Safety のプリフライトチェックは、データ損失など、CRD をアップグレードする際に意図しない結果が生じることから保護するためのものです。

enforcement

string

enforcement は必須フィールドであり、CRD Upgrade Safety のプリフライトチェックの状態を設定するために使用されます。

許可される値は "None" または "Strict" です。デフォルト値は "Strict" です。

"None" に設定すると、アップグレード操作の実行時に CRD Upgrade Safety のプリフライトチェックがスキップされます。データ損失などの予期しない結果が発生する可能性があるため、注意して使用する必要があります。

"Strict" に設定すると、アップグレード操作の実行時に CRD Upgrade Safety のプリフライトチェックが実行されます。

name

string

name は、packageName フィールドで指定されたパッケージのコンテンツのインストールと管理に使用される ServiceAccount の名前への必須かつ変更不可能な参照です。

この ServiceAccount は installNamespace に存在する必要があります。

name は [RFC 1123] で定義されている DNS サブドメイン標準に従います。小文字の英数字、ハイフン (-)、またはピリオド (.) のみを含み、先頭と末尾は英数字で、長さは 253 文字以下にする必要があります。

有効な値の例: - some-serviceaccount - 123-serviceaccount - 1-serviceaccount-2 - someserviceaccount - some.serviceaccount

無効な値の例: - -some-serviceaccount - some-serviceaccount-

[RFC 1123]: https://tools.ietf.org/html/rfc1123

catalog

object

catalog は、カタログから情報を取得する方法を設定するために使用されます。このフィールドは、sourceType が "Catalog" の場合に必須であり、それ以外の場合は禁止されます。

sourceType

string

sourceType は、インストールソースのタイプへの必須の参照です。

許可される値は "Catalog" です。

このフィールドを "Catalog" に設定すると、インストールする適切なコンテンツバンドルを決定するための情報が、クラスター上に存在する ClusterCatalog リソースから取得されます。Catalog sourceType を使用する場合は、カタログフィールドも設定する必要があります。

channels

array (string)

channels は、packageName フィールドで指定されたパッケージに属するチャネルセットへのオプションの参照です。

"channel" とは、パッケージ作成者が定義した拡張機能の更新ストリームです。

リスト内の各チャネルは、[RFC 1123] で定義されている DNS サブドメイン標準に従う必要があります。小文字の英数字、ハイフン (-)、またはピリオド (.) のみを含み、先頭と末尾は英数字で、長さは 253 文字以下にする必要があります。指定可能なチャネルは 256 以下です。

指定すると、インストール可能なバンドルのセットと自動アップグレードパスを制約するために使用されます。この制約は、version フィールドとの AND 演算になります。例: - 指定されたチャネルが "foo" に設定され、指定されたバージョンが ">=1.0.0, <1.5.0" に設定されている場合、"foo" チャネルに存在し、かつバージョン範囲の比較を満たすバンドルのみが、インストール可能と見なされます。自動アップグレードは、選択されたチャネルによって定義されたアップグレードエッジに制約されます。

指定しない場合は、すべてのチャネルにわたるアップグレードエッジを使用して、有効な自動アップグレードパスが識別されます。

有効な値の例: - 1.1.x - alpha - stable - stable-v1 - v1-stable - dev-preview - preview - community

無効な値の例: - -some-channel - some-channel- - thisisareallylongchannelnamethatisgreaterthanthemaximumlength - original_40 - --default-channel

[RFC 1123]: https://tools.ietf.org/html/rfc1123

packageName

string

packageName は、インストールするパッケージの名前への参照であり、カタログからコンテンツをフィルタリングするために使用されます。

packageName は必須かつ変更不可能で、[RFC 1123] で定義されている DNS サブドメイン標準に従います。小文字の英数字、ハイフン (-)、またはピリオド (.) のみを含み、先頭と末尾は英数字で、長さは 253 文字以下にする必要があります。

有効な値の例: - some-package - 123-package - 1-package-2 - somepackage

無効な値の例: - -some-package - some-package- - thisisareallylongpackagenamethatisgreaterthanthemaximumlength - some.package

[RFC 1123]: https://tools.ietf.org/html/rfc1123

selector

object

selector はオプションのフィールドで、バンドル選択プロセスで使用される ClusterCatalog のセットをフィルタリングするために使用できます。

指定しない場合は、バンドル選択プロセスですべての ClusterCatalog が使用されます。

upgradeConstraintPolicy

string

upgradeConstraintPolicy はオプションのフィールドで、カタログで定義されたアップグレードパスが、packageName フィールドで参照されるパッケージに適用されるかどうかを制御します。

許可される値は、"CatalogProvided"、"SelfCertified、または省略できます。

このフィールドが "CatalogProvided" に設定されている場合、パッケージ作成者によって指定されたアップグレード制約が満たされた場合にのみ自動アップグレードが実行されます。

このフィールドが "SelfCertified" に設定されている場合、パッケージ作成者が指定したアップグレード制約は無視されます。これにより、パッケージの任意のバージョンへのアップグレードとダウングレードが可能になります。これは、データ損失など、未知の潜在的に悲惨な結果につながる可能性があるため、危険な操作と見なされています。このオプションを使用する場合、ユーザーが変更を独自に検証していることが前提となります。

このフィールドを省略した場合、デフォルト値は "CatalogProvided" です。

version

string

version はオプションの semver 制約 (特定のバージョンまたはバージョンの範囲) です。指定しない場合は、利用可能な最新バージョンがインストールされます。

許容されるバージョン範囲は 64 文字以内です。バージョン範囲は、コンマまたはスペースで区切られた値と、比較文字列と呼ばれる 1 つ以上の比較 Operator で構成されます。OR Operator (||) を使用して、追加の比較文字列を追加できます。

# 範囲の比較

バージョン範囲を指定するには、">=3.0, <3.6" のような比較文字列を使用できます。範囲を指定すると、その範囲内で自動更新が行われます。この例の比較文字列は、「3.0.0 以上 3.6.0 未満の任意のバージョンをインストールする」という意味です。また、最初のインストール後にバージョン範囲内でアップグレードが利用可能になった場合は、それらのアップグレードが自動的に実行されるという意図も示されています。

# 固定バージョン

インストールする正確なバージョンを指定するには、特定のバージョンに「固定」するバージョン範囲を使用できます。特定のバージョンに固定すると、自動更新は行われません。固定されたバージョン範囲の例は "0.6.0" です。これは、「バージョン 0.6.0 のみをインストールし、このバージョンからはアップグレードしないこと」を意味します。

# 基本的な比較 Operator

基本的な比較 Operator とその意味: "=" は同等 (特定の Operator にエイリアスされていない)、"!=" は同等ではない。"<" はより小さい。">" はより大きい。">=" は以上。"⇐" は以下。

# ワイルドカードの比較

すべての比較演算では、"x"、"X"、および "" 文字をワイルドカード文字として使用できます。ワイルドカード文字の使用例: "1.2.x"、"1.2.X"、および "1.2." は、">=1.2.0, < 1.3.0" と同等です。">= 1.2.x"、">= 1.2.X"、および ">= 1.2." は、">= 1.2.0" と同等です。"⇐ 2.x"、"⇐ 2.X"、および "⇐ 2." は、"< 3" と同等です。"x"、"X"、および "*" は、">= 0.0.0" と同等です。

# パッチリリースの比較

マイナーバージョンから次のメジャーバージョンまでを指定する場合は、"~" 文字を使用してパッチの比較を実行できます。例: "~1.2.3" は ">=1.2.3, <1.3.0" と同等です。"~1" および "~1.x" は ">=1, <2" と同等です。"~2.3" は ">=2.3、<2.4" と同等です。"~1.2.x" は ">=1.2.0, <1.3.0" と同等です。

# メジャーリリースの比較

stable 1.0.0 バージョンが公開された後、メジャーリリースの比較を行うには、"^" 文字を使用できます。stable バージョンが公開されていない場合は、// マイナーバージョンが安定性レベルを定義します。例: "^1.2.3" は ">=1.2.3, <2.0.0" と同等です。"^1.2.x" は ">=1.2.0, <2.0.0" と同等です。"^2.3" は ">=2.3, <3" と同等です。"^2.x" は ">=2.0.0, <3" と同等です。"^0.2.3" は ">=0.2.3, <0.3.0" と同等です。"^0.2"は ">=0.2.0, <0.3.0" と同等です。"^0.0.3" は ">=0.0.3, <0.0.4" と同等です。"^0.0" は ">=0.0.0, <0.1.0" と同等です。"^0" は ">=0.0.0, <1.0.0" と同等です。

# OR 比較。バージョン範囲内で OR 演算を表すには、"||" 文字を使用できます。一部の例: - ">=1.2.3, <2.0.0 || >3.0.0" - "^0 || ^3 || ^5"

semver の詳細は、https://semver.org/ を参照してください。

matchExpressions

array

matchExpressions はラベルセレクターの要件のリストです。要件は AND で結合されます。

matchExpressions[]

object

ラベルセレクター要件は、値、キー、およびキーと値を関連付ける Operator を含むセレクターです。

matchLabels

object (string)

matchLabels は、{key,value} ペアのマップです。matchLabels マップの 1 つの {key,value} は matchExpressions の要素と同じで、キーフィールドには "key"、演算子には "In"、値配列には "value" のみが含まれます。要件は AND で結合されます。

key

string

key は、セレクターの適用先のラベルキーです。

operator

string

operator はキーと値のセットの関係を表します。有効な演算子は In、NotIn、Exists、および DoesNotExist です。

values

array (string)

values は文字列値の配列です。operator が In または NotIn の場合には、values 配列を空白にできません。operator が Exists または DoesNotExist の場合には、values 配列は空白でなければなりません。この配列は、ストラテジーに基づいたマージパッチの適用中に置き換えられます。

conditions

array

すべての spec.source バリエーションに適用される状態タイプのセットは、Installed と Progressing です。

Installed 状態は、この ClusterExtension に対してバンドルがインストールされているかどうかを表します。Installed が True で、Reason が Succeeded の場合、バンドルは正常にインストールされています。Installed が False で Reason が Failed の場合、バンドルはインストールに失敗しました。

Progressing 条件は、ClusterExtension が新しい状態に向かって進んでいるかどうかを表します。Progressing が True で Reason が Succeeded の場合、ClusterExtension は新しい状態に向けて進行中です。Progressing が True で、Reason が Retrying の場合、ClusterExtension でエラーが発生しましたが、これは後続の調整試行で解決できる可能性があります。Progressing が False で Reason が Blocked の場合、ClusterExtension でエラーが発生し、回復には手動による介入が必要です。

ClusterExtension がカタログから取得される場合、非推奨条件も伝えられることがあります。これらは、パッケージ所有者がユーザーを特定のパッケージ、チャネル、またはバンドルから遠ざけるように指示するものです。リクエストされたバンドルバージョンがカタログ内で非推奨とマークされている場合、BundleDeprecated が設定されます。リクエストされたチャネルがカタログ内で非推奨とマークされている場合、ChannelDeprecated が設定されます。リクエストされたパッケージがカタログ内で非推奨とマークされている場合、PackageDeprecated が設定されます。Deprecated は、非推奨の条件のいずれかが存在する場合に存在するロールアップ条件です。

conditions[]

object

condition には、この API Resource の現在の状態のある側面の詳細が含まれます。

install

object

install は、この ClusterExtension の現在のインストールステータスを表します。

lastTransitionTime

string

lastTransitionTime は、ある状態から別の状態に最後に遷移した時間です。これは、基本的な条件が変更された時点となります。不明な場合には、API フィールドが変更された時点を使用することも可能です。

message

string

message は、遷移の詳細を示す人が判読できるメッセージです。空の文字列の場合もあります。

observedGeneration

integer

observedGeneration は、それをベースに条件が設定された .metadata.generation を表します。たとえば、.metadata.generation が現在 12 で、.status.conditions[x].observedGeneration が 9 の場合、インスタンスの現在の状態に対して条件が古くなっています。

reason

string

reason には、条件の最後の遷移の理由を示すプログラムによる識別子が含まれます。特定の条件タイプのプロデューサーは、このフィールドの期待値と意味、および値が保証された API と見なされるかどうかを定義できます。値は CamelCase 文字列である必要があります。このフィールドには空白を指定できません。

status

string

条件のステータス、True、False、Unknown のいずれか。

type

string

CamelCase または foo.example.com/CamelCase の条件のタイプ。

bundle

object

bundle は必須フィールドで、バンドルの識別属性を表します。

"bundle" とは、パッケージをインストールするためにクラスターに適用する必要があるリソースを表す、バージョン管理されたコンテンツのセットです。

name

string

name は必須であり、[RFC 1123] で定義されている DNS サブドメイン標準に従います。小文字の英数字、ハイフン (-)、またはピリオド (.) のみを含み、先頭と末尾は英数字で、長さは 253 文字以下にする必要があります。

version

string

version は必須フィールドであり、このバンドルが表すバージョンへの参照です。version は、https://semver.org/ で定義されているセマンティックバージョン管理標準に従います。