这是本节的多页打印视图。 点击此处打印.

返回本页常规视图.

admissionregistration

注册和管理 Kubernetes 的 动态准入控制 Webhook,允许用户在不修改 API Server 代码的情况下扩展准入控制逻辑。

1 - 概述

AdmissionRegistration API

介绍

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

主要分为两类:

  1. MutatingAdmissionWebhook
    • 用于 修改 API 请求对象(如自动注入 Sidecar 容器)
  2. ValidatingAdmissionWebhook
    • 用于 验证 API 请求对象(如检查资源是否符合安全策略)

核心类型

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

  1. MutatingWebhookConfiguration
    • 用于注册多个 修改型 Webhook
    • 每个 Webhook 指定:
      • 触发规则(匹配哪些 API 请求)
      • 调用的 Webhook 服务地址
      • 失败策略(如拒绝请求或忽略错误)
  2. 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"    // 失败时拒绝请求
)

工作原理

  1. API Server 接收请求(如创建 Pod)
  2. 检查匹配的 Webhook 规则
    • 通过 rules 字段过滤
  3. 调用 Webhook 服务
    • 发送 AdmissionReview 请求
  4. 处理响应
    • 根据 allowedpatch 字段决定是否允许请求

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
}