admissionregistration
注册和管理 Kubernetes 的 动态准入控制 Webhook,允许用户在不修改 API Server 代码的情况下扩展准入控制逻辑。
- 1: 概述
- 2: types.go
- 3: register.go
1 - 概述
AdmissionRegistration API
介绍
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 调用(推荐)
- 直接指定 URL(如
(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字段决定是否允许请求
- 根据
2 - types.go
AdmissionRegistration API 类型
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"
)
3 - register.go
AdmissionRegistration API 类型注册
注册类型
// 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
}