Kubernetes学习笔记 – admissionregistration

Source: 概述

Wed, 14 May 2025 00:00:00 +0000

介绍

AdmissionRegistration API 核心功能：用于注册和管理 Kubernetes 的动态准入控制 Webhook，允许用户在不修改 API Server 代码的情况下扩展准入控制逻辑。

主要分为两类：

MutatingAdmissionWebhook
- 用于修改 API 请求对象（如自动注入 Sidecar 容器）
ValidatingAdmissionWebhook
- 用于验证 API 请求对象（如检查资源是否符合安全策略）

核心类型

在 admissionregistration.k8s.io/v1 中定义了以下关键资源：

MutatingWebhookConfiguration
- 用于注册多个 修改型 Webhook。
- 每个 Webhook 指定：
  - 触发规则（匹配哪些 API 请求）
  - 调用的 Webhook 服务地址
  - 失败策略（如拒绝请求或忽略错误）
ValidatingWebhookConfiguration
- 用于注册多个 验证型 Webhook。
- 结构与 MutatingWebhookConfiguration 类似，但 Webhook 不能修改对象。

核心 API 方法

AdmissionRegistration API 通过标准的 Kubernetes REST 接口提供以下操作：

HTTP 方法	路径	功能
`GET`	`/apis/admissionregistration.k8s.io/v1/mutatingwebhookconfigurations`	列出所有 MutatingWebhookConfiguration
`POST`	同上	创建新的 MutatingWebhookConfiguration
`PUT`	`/apis/admissionregistration.k8s.io/v1/mutatingwebhookconfigurations/{name}`	更新指定配置
`DELETE`	同上	删除配置
`GET`	`/apis/admissionregistration.k8s.io/v1/validatingwebhookconfigurations`	列出所有 ValidatingWebhookConfiguration
`POST`	同上	创建新的 ValidatingWebhookConfiguration

关键字段解析

(1) `WebhookClientConfig`

type WebhookClientConfig struct {
    URL      *string           `json:"url,omitempty"`      // Webhook 服务 URL（直接调用）
    Service  *ServiceReference `json:"service,omitempty"`  // 通过 Service 调用
    CABundle []byte            `json:"caBundle,omitempty"`  // CA 证书（用于 TLS 验证）
}

支持两种调用方式：
- 直接指定 URL（如 https://webhook.example.com:443/admit）
- 通过 Kubernetes Service 调用（推荐）

(2) RuleWithOperations

type RuleWithOperations struct {
    Operations []OperationType `json:"operations"`  // 操作类型：CREATE, UPDATE, DELETE, *
    Rule       Rule            `json:"rule"`        // 资源匹配规则
}

示例：匹配所有 Pod 的 CREATE/UPDATE 操作：

rules:
- operations: ["CREATE", "UPDATE"]
  apiGroups: [""]
  apiVersions: ["v1"]
  resources: ["pods"]

(3) FailurePolicy

type FailurePolicyType string
const (
    Ignore FailurePolicyType = "Ignore"  // 失败时忽略（继续请求）
    Fail   FailurePolicyType = "Fail"    // 失败时拒绝请求
)

工作原理

API Server 接收请求（如创建 Pod）
检查匹配的 Webhook 规则
- 通过 rules 字段过滤
调用 Webhook 服务
- 发送 AdmissionReview 请求
处理响应
- 根据 allowed 和 patch 字段决定是否允许请求

Source: types.go

Wed, 14 May 2025 00:00:00 +0000

WebhookClientConfig

AdmissionReview 描述了准入审查请求/应答。


// WebhookClientConfig contains the information to make a TLS
// connection with the webhook
type WebhookClientConfig struct {
	// `url` gives the location of the webhook, in standard URL form
	// (`scheme://host:port/path`). Exactly one of `url` or `service`
	// must be specified.
	//
	// The `host` should not refer to a service running in the cluster; use
	// the `service` field instead. The host might be resolved via external
	// DNS in some apiservers (e.g., `kube-apiserver` cannot resolve
	// in-cluster DNS as that would be a layering violation). `host` may
	// also be an IP address.
	//
	// Please note that using `localhost` or `127.0.0.1` as a `host` is
	// risky unless you take great care to run this webhook on all hosts
	// which run an apiserver which might need to make calls to this
	// webhook. Such installs are likely to be non-portable, i.e., not easy
	// to turn up in a new cluster.
	//
	// The scheme must be "https"; the URL must begin with "https://".
	//
	// A path is optional, and if present may be any string permissible in
	// a URL. You may use the path to pass an arbitrary string to the
	// webhook, for example, a cluster identifier.
	//
	// Attempting to use a user or basic auth e.g. "user:password@" is not
	// allowed. Fragments ("#...") and query parameters ("?...") are not
	// allowed, either.
	//
	// +optional
	URL *string `json:"url,omitempty" protobuf:"bytes,3,opt,name=url"`

	// `service` is a reference to the service for this webhook. Either
	// `service` or `url` must be specified.
	//
	// If the webhook is running within the cluster, then you should use `service`.
	//
	// +optional
	Service *ServiceReference `json:"service,omitempty" protobuf:"bytes,1,opt,name=service"`

	// `caBundle` is a PEM encoded CA bundle which will be used to validate the webhook's server certificate.
	// If unspecified, system trust roots on the apiserver are used.
	// +optional
	CABundle []byte `json:"caBundle,omitempty" protobuf:"bytes,2,opt,name=caBundle"`
}

RuleWithOperations

// RuleWithOperations is a tuple of Operations and Resources. It is recommended to make
// sure that all the tuple expansions are valid.
type RuleWithOperations struct {
	// Operations is the operations the admission hook cares about - CREATE, UPDATE, DELETE, CONNECT or *
	// for all of those operations and any future admission operations that are added.
	// If '*' is present, the length of the slice must be one.
	// Required.
	// +listType=atomic
	Operations []OperationType `json:"operations,omitempty" protobuf:"bytes,1,rep,name=operations,casttype=OperationType"`
	// Rule is embedded, it describes other criteria of the rule, like
	// APIGroups, APIVersions, Resources, etc.
	Rule `json:",inline" protobuf:"bytes,2,opt,name=rule"`
}

OperationType

// OperationType specifies an operation for a request.
// +enum
type OperationType string

// The constants should be kept in sync with those defined in k8s.io/kubernetes/pkg/admission/interface.go.
const (
	OperationAll OperationType = "*"
	Create       OperationType = "CREATE"
	Update       OperationType = "UPDATE"
	Delete       OperationType = "DELETE"
	Connect      OperationType = "CONNECT"
)

FailurePolicyType

// FailurePolicyType specifies a failure policy that defines how unrecognized errors from the admission endpoint are handled.
// +enum
type FailurePolicyType string

const (
	// Ignore means that an error calling the webhook is ignored.
	Ignore FailurePolicyType = "Ignore"
	// Fail means that an error calling the webhook causes the admission to fail.
	Fail FailurePolicyType = "Fail"
)

Source: register.go

Wed, 14 May 2025 00:00:00 +0000

注册类型

// Adds the list of known types to the given scheme.
func addKnownTypes(scheme *runtime.Scheme) error {
	scheme.AddKnownTypes(SchemeGroupVersion,
		&ValidatingWebhookConfiguration{},
		&ValidatingWebhookConfigurationList{},
		&MutatingWebhookConfiguration{},
		&MutatingWebhookConfigurationList{},
		&ValidatingAdmissionPolicy{},
		&ValidatingAdmissionPolicyList{},
		&ValidatingAdmissionPolicyBinding{},
		&ValidatingAdmissionPolicyBindingList{},
	)
	metav1.AddToGroupVersion(scheme, SchemeGroupVersion)
	return nil
}

Kubernetes学习笔记 – admissionregistration

Source: 概述

介绍

核心类型

核心 API 方法

关键字段解析

(1) WebhookClientConfig

工作原理

Source: types.go

WebhookClientConfig

RuleWithOperations

OperationType

FailurePolicyType

Source: register.go

(1) `WebhookClientConfig`