第5章 ValidatingAdmissionPolicy [admissionregistration.k8s.io/v1]

auditAnnotations

array

auditAnnotations には、API リクエストの監査イベント用の監査アノテーションを生成するために使用する CEL 式を含めます。validations と auditAnnotations の両方を空にすることはできません。validations または auditAnnotations のどちらかが少なくとも必要です。

auditAnnotations[]

object

AuditAnnotation は、API リクエストの監査アノテーションを生成する方法を表します。

failurePolicy

string

failurePolicy は、アドミッションポリシーの失敗を処理する方法を定義します。失敗は、CEL 式の解析エラー、型チェックエラー、ランタイムエラー、および無効な、または誤った設定のポリシー定義またはバインディングによって発生する可能性があります。

存在しない Kind を spec.paramKind が参照している場合、ポリシーは無効です。存在しないリソースを spec.paramRef.name が参照している場合、バインディングは無効です。

failurePolicy は、false と評価される検証の処理方法は定義しません。

failurePolicy が Fail に設定されている場合、ValidatingAdmissionPolicyBinding の validationActions によって失敗の適用方法が定義されます。

許可される値は、Ignore または Fail です。デフォルトは Fail です。

使用可能な列挙値: - "Fail" は、Webhook 呼び出しエラーにより受付が失敗することを意味します。- "Ignore" は、Webhook を呼び出すエラーが無視されることを意味します。

matchConditions

array

MatchConditions は、リクエストを検証するために満たす必要がある条件のリストです。matchConditions は、ルール、namespaceSelector、および objectSelector ですでに一致しているリクエストをフィルター処理します。matchConditions の空のリストは、すべてのリクエストに一致します。最大 64 個の一致条件が使用できます。

パラメーターオブジェクトが提供されている場合は、検証式と同じ方法で params ハンドルを介してそのパラメーターオブジェクトにアクセスできます。

正確な一致ロジック (処理順序) は次のとおりです。1. いずれかの matchCondition が FALSE と評価された場合、ポリシーはスキップされます。2. すべての matchConditions が TRUE と評価された場合、ポリシーは評価されます。3. いずれかの matchCondition がエラーと評価された場合 (ただし、FALSE と評価されたものがない場合): - failurePolicy=Fail の場合、リクエストは拒否されます。- failurePolicy=Ignore の場合、ポリシーはスキップされます。

matchConditions[]

object

MatchCondition は、リクエストが Webhook に送信されるために満たされる必要がある条件を表します。

matchConstraints

object

MatchResources は、一致基準を満たしているかどうかに基づいて、オブジェクトに対してアドミッションコントロールポリシーを実行するかどうかを決定します。除外ルールは包含ルールよりも優先されます (リソースが両方に一致する場合は除外されます)。

paramKind

object

ParamKind は、グループの種類とバージョンのタプルです。

validations

array

Validations には、検証を適用するために使用する CEL 式を含めます。Validations と AuditAnnotations の両方を空にすることはできません。Validations または AuditAnnotations のどちらかが少なくとも必要です。

validations[]

object

Validation は、検証を適用するために使用する CEL 式を指定します。

variables

array

Variables には、他の式を構成するのに使用できる変数の定義を含めます。各変数は名前付き CEL 式として定義します。ここで定義した変数は、MatchConditions を除くポリシーの他の式の variables で使用できます。MatchConditions は、ポリシーの他の部分よりも先に評価されるため、除外されます。

変数の式は、リスト内の前に定義された他の変数を参照できますが、後続の変数を参照することはできません。したがって、変数は出現順および非循環的に並べる必要があります。

variables[]

object

変数は、構成に使用する変数の定義です。変数は名前付きの式として定義します。

key

string

key は監査アノテーションキーを指定します。ValidatingAdmissionPolicy の監査アノテーションキーは一意である必要があります。キーは、長さが 63 バイト以内の修飾名 ([A-Za-z0-9][-A-Za-z0-9_.]*) である必要があります。

キーは、ValidatingAdmissionPolicy のリソース名と組み合わされて、監査アノテーションキー "{ValidatingAdmissionPolicy name}/{key}" を構成します。

アドミッション Webhook がこの ValidatingAdmissionPolicy と同じリソース名と同じ監査アノテーションキーを使用する場合、アノテーションキーは同一になります。この場合、キーを使用して書き込まれた最初のアノテーションが監査イベントに含まれ、同じキーを持つ後続のアノテーションがすべて破棄されます。

必須。

valueExpression

string

valueExpression は、監査アノテーション値を生成するために CEL によって評価される式を表します。式は文字列または null 値のいずれかに評価される必要があります。式が文字列に評価された場合、監査アノテーションは文字列値に含まれます。式が null または空の文字列に評価された場合、監査アノテーションは省略されます。valueExpression は 5kb 以下の長さにする必要があります。valueExpression の結果の長さが 10kb を超える場合、10kb に切り捨てられます。

複数の ValidatingAdmissionPolicyBinding リソースが API リクエストと一致する場合、各バインディングに対して valueExpression が評価されます。valueExpression によって生成される一意の値は、すべてコンマ区切りのリストに結合されます。

必須。

expression

string

expression は、CEL によって評価される式を表します。ブール値に対して評価する必要があります。CEL 式は、CEL 変数として整理された AdmissionRequest および Authorizer の内容にアクセスできます。

'object' - 受信リクエストのオブジェクト。DELETE 要求の値は null です。'oldObject' - 既存のオブジェクト。CREATE リクエストの場合、値は null です。'request' - 受付リクエストの属性 (/pkg/apis/admission/types.go#AdmissionRequest)。'authorizer' - CEL オーソライザー。リクエストのプリンシパル (ユーザーまたはサービスアカウント) の承認チェックを実行するために使用される場合があります。https://pkg.go.dev/k8s.io/apiserver/pkg/cel/library#Authz 'authorizer.requestResource' ('authorizer' から構築され、リクエストリソースで設定された CEL ResourceCheck) を参照してください。CEL に関するドキュメント: https://kubernetes.io/docs/reference/using-api/cel/

必須。

name

string

Name はこの一致条件の識別子であり、MatchConditions の戦略的なマージに使用されるほか、ログ記録用の識別子としても使用されます。適切な名前は、関連する式を説明するものでなければなりません。name は、英数字、'-'、''、または '.' で構成される修飾名で、先頭と末尾が英数字である必要があります (例: 'MyName'、'my.name'、'123-abc'。検証に使用される正規表現は '([A-Za-z0-9][-A-Za-z0-9.]*)?[A-Za-z0-9]')。必要に応じて、DNS サブドメイン接頭辞および '/' を指定します (例: 'example.com/MyName')。

必須。

excludeResourceRules

array

ExcludeResourceRules は、ValidatingAdmissionPolicy で考慮しないリソース/サブリソースに対する操作を表します。除外ルールは包含ルールよりも優先されます (リソースが両方に一致する場合は除外されます)。

excludeResourceRules[]

object

NamedRuleWithOperations は、ResourceNames を持つ操作とリソースのタプルです。

matchPolicy

string

matchPolicy は、"MatchResources" リストを使用して受信リクエストを照合する方法を定義します。許可される値は "Exact" または "Equivalent" です。

- Exact: 指定されたルールにリクエストが完全に一致する場合にのみ、リクエストを一致させます。たとえば、apps/v1、apps/v1beta1、extensions/v1beta1 を介してデプロイメントを変更できても、"rules" に含まれているのが apiGroups:["apps"], apiVersions:["v1"], resources: ["deployments"] だけである場合、apps/v1beta1 または extensions/v1beta1 へのリクエストは ValidatingAdmissionPolicy に送信されません。

- Equivalent: 別の API グループまたはバージョンを介してでも、ルールにリストされているリソースを変更する場合に、リクエストを一致させます。たとえば、apps/v1、apps/v1beta1、extensions/v1beta1 を介してデプロイメントを変更でき、"rules" に含まれているのが apiGroups:["apps"], apiVersions:["v1"], resources: ["deployments"] だけである場合、apps/v1beta1 または extensions/v1beta1 へのリクエストは、apps/v1 に変換され、ValidatingAdmissionPolicy に送信されます。

デフォルトは "Equivalent" です。

使用可能な列挙値: - "Equivalent" は、ルールにリストされているリソースを別の API グループまたはバージョン経由で変更する場合、リクエストが Webhook に送信される必要があることを意味します。- "Exact" は、リクエストが特定のルールに正確に一致する場合にのみ Webhook に送信されることを意味します。

namespaceSelector

LabelSelector

NamespaceSelector は、オブジェクトの namespace がセレクターと一致するかどうかに基づいて、オブジェクトに対してアドミッションコントロールポリシーを実行するかどうかを決定します。オブジェクト自体が namespace である場合、object.metadata.labels に対して照合が実行されます。オブジェクトがクラスタースコープの別のリソースである場合、ポリシーはスキップされません。

たとえば、"0" または "1" の "runlevel" に関連付けられていない namespace のオブジェクトに対して Webhook を実行するには、"namespaceSelector": { "matchExpressions": [ { "key": "runlevel", "operator": "NotIn", "values": [ "0", "1" ] } ] } のようにセレクターを設定します。

代わりに、"prod" または "staging" の "environment" に関連付けられている namespace のオブジェクトに対してのみポリシーを実行する場合は、"namespaceSelector": { "matchExpressions": [ { "key": "environment", "operator": "In", "values": [ "prod", "staging" ] } ] } のようにセレクターを設定します。

ラベルセレクターのその他の例は、https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/ を参照してください。

デフォルトは空の LabelSelector で、すべてに一致します。

objectSelector

LabelSelector

ObjectSelector は、オブジェクトに一致するラベルがあるかどうかに基づいて検証を実行するかどうかを決定します。objectSelector は、cel 検証に送信される oldObject と newObject の両方に対して評価され、いずれかのオブジェクトがセレクターに一致する場合、一致すると見なされます。null オブジェクト (create の場合は oldObject、delete の場合は newObject) またはラベルを持つことができないオブジェクト (DeploymentRollback または PodProxyOptions オブジェクトなど) は一致するとは見なされません。エンドユーザーはラベルを設定することでアドミッション Webhook をスキップできるため、Webhook がオプトインの場合にのみオブジェクトセレクターを使用してください。デフォルトは空の LabelSelector で、すべてに一致します。

resourceRules

array

ResourceRules は、ValidatingAdmissionPolicy で照合する、リソース/サブリソースに対する操作を表します。ポリシーは、操作が いずれか のルールに一致する場合、その操作を考慮します。

resourceRules[]

object

NamedRuleWithOperations は、ResourceNames を持つ操作とリソースのタプルです。

apiGroups

array (string)

APIGroups は、リソースが属する API グループです。'' はすべてのグループです。もしも '' が存在する場合、スライスの長さは 1 でなければなりません。必須。

apiVersions

array (string)

APIVersions は、リソースが属する API バージョンです。'' はすべてのバージョンです。もしも '' が存在する場合、スライスの長さは 1 でなければなりません。必須。

operations

array (string)

操作は、アドミッションフックが気にする操作です - これらすべての操作および追加される将来のアドミッション操作に対して、CREATE、UPDATE、DELETE、CONNECT、または*。'*' が存在する場合、スライスの長さは 1 でなければなりません。必須。

resourceNames

array (string)

ResourceNames は、ルールが適用される名前のオプションのホワイトリストです。空のセットは、すべてが許可されていることを意味します。

resources

array (string)

リソースは、このルールが適用されるリソースのリストです。

例: 'Pod' は Pod を意味します。'pods/log' は、Pod のログサブリソースを意味します。'' はすべてのリソースを意味しますが、サブリソースは意味しません。'pods/' は、Pod のすべてのサブリソースを意味します。'/scale' は、すべてのスケールサブリソースを意味します。'/*' は、すべてのリソースとそのサブリソースを意味します。

ワイルドカードが存在する場合、検証ルールはリソースが互いに重複しないことを保証します。

囲んでいるオブジェクトによっては、サブリソースが許可されない場合があります。必須。

scope

string

scope は、このルールのスコープを指定します。有効な値は、"Cluster"、"Namespaced"、および "" "クラスター" とは、クラスタースコープのリソースのみがこのルールに一致することを意味します。名前空間 API オブジェクトはクラスタースコープです。"Namespaced" は、名前空間付きのリソースのみがこのルールに一致することを意味します。"" は、スコープの制限がないことを意味します。サブリソースは、親リソースのスコープと一致します。デフォルトは "*" です。

apiGroups

array (string)

APIGroups は、リソースが属する API グループです。'' はすべてのグループです。もしも '' が存在する場合、スライスの長さは 1 でなければなりません。必須。

apiVersions

array (string)

APIVersions は、リソースが属する API バージョンです。'' はすべてのバージョンです。もしも '' が存在する場合、スライスの長さは 1 でなければなりません。必須。

operations

array (string)

操作は、アドミッションフックが気にする操作です - これらすべての操作および追加される将来のアドミッション操作に対して、CREATE、UPDATE、DELETE、CONNECT、または*。'*' が存在する場合、スライスの長さは 1 でなければなりません。必須。

resourceNames

array (string)

ResourceNames は、ルールが適用される名前のオプションのホワイトリストです。空のセットは、すべてが許可されていることを意味します。

resources

array (string)

リソースは、このルールが適用されるリソースのリストです。

例: 'Pod' は Pod を意味します。'pods/log' は、Pod のログサブリソースを意味します。'' はすべてのリソースを意味しますが、サブリソースは意味しません。'pods/' は、Pod のすべてのサブリソースを意味します。'/scale' は、すべてのスケールサブリソースを意味します。'/*' は、すべてのリソースとそのサブリソースを意味します。

ワイルドカードが存在する場合、検証ルールはリソースが互いに重複しないことを保証します。

囲んでいるオブジェクトによっては、サブリソースが許可されない場合があります。必須。

scope

string

scope は、このルールのスコープを指定します。有効な値は、"Cluster"、"Namespaced"、および "" "クラスター" とは、クラスタースコープのリソースのみがこのルールに一致することを意味します。名前空間 API オブジェクトはクラスタースコープです。"Namespaced" は、名前空間付きのリソースのみがこのルールに一致することを意味します。"" は、スコープの制限がないことを意味します。サブリソースは、親リソースのスコープと一致します。デフォルトは "*" です。

apiVersion

string

APIVersion は、リソースが属する API グループのバージョンです。形式は "グループ/バージョン" です。必須。

kind

string

Kind は、リソースが属する API の種類です。必須。

expression

string

Expression は、CEL によって評価される式を表します。https://github.com/google/cel-spec を参照してください。CEL 式は、以下に示す CEL 変数に整理された API リクエスト/レスポンスの内容と、その他の便利な変数にアクセスできます。

- 'object' - 受信リクエストのオブジェクト。DELETE リクエストの場合、値は null です。- 'oldObject' - 既存のオブジェクト。CREATE リクエストの場合、値は null です。- 'request' - API リクエストの属性 ([ref](/pkg/apis/admission/types.go#AdmissionRequest))。- 'params' - 評価対象のポリシーバインディングによって参照されるパラメーターリソース。ポリシーに ParamKind がある場合にのみ入力されます。- 'namespaceObject' - 受信オブジェクトが属する namespace オブジェクト。クラスタースコープのリソースの場合、値は null です。- 'variables' - 複合変数のマップ (変数名から遅延評価される値へのマップ)。たとえば、'foo' という名前の変数に、'variables.foo' としてアクセスできます。- 'authorizer' - CEL オーソライザー。リクエストのプリンシパル (ユーザーまたはサービスアカウント) の承認チェックを実行するために使用される場合があります。https://pkg.go.dev/k8s.io/apiserver/pkg/cel/library#Authz - 'authorizer.requestResource' ('authorizer' から構築され、リクエストリソースで設定された CEL ResourceCheck) を参照してください。

apiVersion、kind、metadata.name、および metadata.generateName は、常にオブジェクトのルートからアクセスできます。その他のメタデータプロパティーにはアクセスできません。

[a-zA-Z_.-/][a-zA-Z0-9_.-/]* 形式のプロパティー名にのみアクセスできます。アクセス可能なプロパティー名は、式でアクセスされるときに、次のルールに従ってエスケープされます。- '' は 'underscores' にエスケープされます。- '.' は 'dot' にエスケープされます。- '-' は 'dash' にエスケープされます。- '/' は 'slash' にエスケープされます。- CEL RESERVED キーワードに完全一致するプロパティー名は '{keyword}' にエスケープされます。キーワードは、"true"、"false"、"null"、"in"、"as"、"break"、"const"、"continue"、"else"、"for"、"function"、"if"、"import"、"let"、"loop"、"package"、"namespace"、"return" です。例: - "namespace" という名前のプロパティーにアクセスする式: {"Expression": "object.namespace > 0"} - "x-prop" という名前のプロパティーにアクセスする式: {"Expression": "object.xdashprop > 0"} - "redactd" という名前のプロパティーにアクセスする式: {"Expression": "object.redactunderscoresd > 0"}

リストタイプが 'set' または 'map' である配列が等値の場合、要素の順序は無視されます (つまり [1, 2] == [2, 1])。x-kubernetes-list-type による配列の連結では、リストタイプのセマンティクスを使用します。- 'set': X + Y は、X の全要素の配列位置が保存され、Yの交差のない要素が追加される連結を実施し、部分的な順序を維持します。- 'map': X + Y は、X のすべての鍵の配列位置が保持されますが、X and Y の鍵セットが交差する場合は、これらの値は Y の値により上書きされます。鍵が交差していない Y の要素が追加され、部分的な順序が保持されます。必須。

message

string

message は、検証が失敗したときに表示されるメッセージを表します。式に改行が含まれている場合、メッセージは必須です。メッセージに改行を含めることはできません。設定されていない場合、メッセージは "failed rule: {Rule}" になります。例: "spec.host に一致するホストを含む URL である必要があります"。式に改行が含まれている場合、メッセージは必須です。メッセージに改行を含めることはできません。設定されていない場合、メッセージは "failed Expression: {Expression}" になります。

messageExpression

string

messageExpression は、このルールが失敗した場合に返される検証失敗メッセージを評価する CEL 式を宣言します。messageExpression は失敗メッセージとして使用されるため、文字列として評価される必要があります。検証時に message と messageExpression の両方が存在する場合、検証が失敗したときに messageExpression が使用されます。messageExpression の結果としてランタイムエラーが発生した場合、そのランタイムエラーがログに記録され、messageExpression フィールドが設定されていない場合と同様に検証失敗メッセージが生成されます。messageExpression が空の文字列、スペースのみの文字列、または改行を含む文字列に評価された場合も、messageExpression フィールドが設定されていない場合と同様に検証失敗メッセージが生成され、messageExpression が空の文字列/スペースのみの文字列/改行を含む文字列を生成したことがログに記録されます。messageExpression は、'authorizer' と 'authorizer.requestResource' を除く、expression と同じ変数すべてにアクセスできます。例: "object.x は最大値 ("string (params.max)") より小さくする必要があります"

reason

string

reason は、この検証が失敗した理由を機械可読形式で表します。これがリスト内の失敗した最初の検証である場合、この理由と対応する HTTP レスポンスコードが、クライアントへの HTTP レスポンスで使用されます。現在サポートされている理由は、"Unauthorized"、"Forbidden"、"Invalid"、"RequestEntityTooLarge" です。設定されていない場合は、クライアントへの応答に StatusReasonInvalid が使用されます。

expression

string

Expression は、変数の値として評価される式です。CEL 式は、検証の CEL 式と同じ識別子にアクセスできます。

name

string

Name は変数の名前です。名前は、有効な CEL 識別子であり、すべての変数の中で一意である必要があります。変数には、variables を介して他の式でアクセスできます。たとえば、名前が "foo" 変数は、variables.foo として使用できます。

conditions

array (条件)

conditions は、ポリシーの現在の状態に関する最新の利用可能な観測値を表します。

observedGeneration

integer

コントローラーによって監視される世代。

typeChecking

object

TypeChecking には ValidatingAdmissionPolicy 内の式の型チェックの結果が格納されます。

expressionWarnings

array

各式の型チェックの警告。

expressionWarnings[]

object

ExpressionWarning は特定の式を対象とした警告情報です。

fieldRef

string

式を参照するフィールドへのパス。たとえば、検証の最初の項目である式への参照は、"spec.validations[0].expression" です。

warning

string

人間が判読できる形式の型チェック情報の内容。警告の各行には、式のチェック対象の型と、コンパイラーからの型チェックエラーが含まれています。