API Server:集群的统一入口¶
API Server 是 Kubernetes 控制面的 API 入口,kubectl、Controller、Scheduler 和 Kubelet 通过它读取和更新资源对象。API Server 本身是无状态服务,可以通过部署多个实例提高可用性并分担请求。请求经过身份认证和授权后进入资源处理逻辑,写请求还需经过准入控制和对象校验。etcd 负责持久化保存集群状态,API Server 通过存储层访问这些数据,并通过 Watch 接口向客户端提供对象变更。
用户认证¶
用户认证(Authentication)用于确认 API 请求的调用者身份。API Server 校验证书、令牌等凭据,取得用户名、用户组等身份信息。后续鉴权模块根据这些身份信息和请求内容,判断调用者是否有权执行相应操作。
Kubernetes 中的用户¶
Kubernetes 集群中的用户分为两类:
-
普通用户:通常是使用
kubectl等客户端访问集群的开发者或运维人员。其账号和凭据由集群外部管理,例如由管理员通过证书签发机构(CA)签发客户端证书,或由 OpenID Connect(OIDC)身份提供商管理账号并签发令牌。Kubernetes 没有表示普通用户的UserAPI 对象,无法通过创建这类对象来添加用户。启用客户端证书认证后,API Server 校验证书是否由可信 CA 签发,并从证书的
subject中读取通用名称(Common Name,CN)作为用户名;例如,/CN=bob对应用户bob。认证通过后,RBAC 等鉴权模块再判断bob能否执行请求中的操作,身份管理方式见官方文档 Authenticating: Users in Kubernetes。 -
服务账号(ServiceAccount):为 Pod 中的应用、Controller 和自动化程序提供身份,由 Kubernetes API 管理,使用归属于特定命名空间的
ServiceAccount对象表示。kube-controller-manager中的 ServiceAccount Controller 会为每个处于活动状态的命名空间自动创建名为default的服务账号;具有相应权限的用户也可以通过 API 创建其他服务账号。Pod 通过
spec.serviceAccountName选择同一命名空间中的服务账号。默认情况下,Kubelet 通过 TokenRequest API 申请短期令牌,以投射卷的形式挂载到 Pod 中,并在到期前自动轮换。容器内的进程读取该令牌,以所选服务账号的身份访问 Kubernetes API,凭据的挂载机制见 Service Accounts。
图:普通用户通过客户端证书或 OIDC 令牌,Pod 内的应用通过 ServiceAccount 令牌访问 API Server。
身份认证策略¶
普通用户可通过 X.509 客户端证书、OIDC 令牌、Webhook、身份认证代理或静态令牌文件等方式完成身份认证;服务账号则使用 ServiceAccount Token。Bootstrap Token 用于新节点加入集群时的初始认证,支持 Kubelet 申请客户端证书。
X509 客户证书¶
客户端在 TLS 握手时提交 X.509 证书。API Server 确认证书由可信 CA 签发、处于有效期内且可用于客户端认证后,将证书中的 Common Name(CN)映射为用户名,将 Organization(O)映射为用户组。例如,/CN=myuser/O=developers 对应用户 myuser 和用户组 developers。
API Server 启动参数
--client-ca-file 是 API Server 的启动参数,指定 API Server 信任的客户端证书 CA 文件。文件中可以包含一个或多个 PEM 编码的 CA 证书,API Server 用它们验证客户端提交的证书。在现有的 API Server 启动命令中加入以下参数:
该路径须在 API Server 进程的运行环境中可读。
客户端 kubeconfig
客户端通过 kubeconfig 指定 API Server 地址、可信的服务端 CA 和自己的身份凭据:
certificate-authority:客户端信任的 CA 证书文件,用于验证 API Server 的服务端证书。client-certificate与client-key:客户端证书及对应私钥。客户端在 TLS 握手中提交证书,并使用私钥证明自己持有该证书对应的密钥;API Server 使用--client-ca-file配置的 CA 验证客户端证书。
下面是完整的客户端证书 kubeconfig。将 server 替换为实际 API 地址,并将 ca.crt、签出的 myuser.crt 和对应私钥 myuser.key 放在 kubeconfig 所在目录。字段定义见 kubeconfig (v1)。
apiVersion: v1
kind: Config
clusters:
- name: course
cluster:
server: https://api.example.com:6443
certificate-authority: ca.crt # 用于验证 API Server 服务端证书的 CA 文件
users:
- name: myuser
user:
client-certificate: myuser.crt # 向 API Server 提交的客户端证书
client-key: myuser.key # 与客户端证书对应的私钥
contexts:
- name: myuser
context:
cluster: course
user: myuser
namespace: default
current-context: myuser
客户端证书申请流程
用户在本地生成私钥和证书签名请求(CSR),私钥由自己保管,只将包含公钥和申请身份信息的 CSR 交给管理员。管理员核对身份后,将 CSR 提交到 Kubernetes,并批准对应的 CertificateSigningRequest 对象。kube-controller-manager 中的 Certificate Signer 组件随后使用 CA 私钥签发客户端证书,写入该对象的 status.certificate。用户取得证书后,将它与本地私钥配置到 kubeconfig,用于访问 API Server。
sequenceDiagram
participant user as User
participant admin as Administrator
participant api as API Server
participant signer as kube-controller-manager<br/>Certificate Signer
user ->> user: 1. Create private key and CSR<br/>myuser.key + myuser.csr
Note over user: Keep myuser.key locally
user ->> admin: 2. Send myuser.csr<br/>Public key + identity
activate admin
admin ->> admin: 3. Verify identity
admin ->> api: 4. Create CertificateSigningRequest<br/>and approve it
deactivate admin
signer ->> api: 5. Read approved CSR
api -->> signer: CSR with Approved condition
activate signer
signer ->> signer: 6. Sign certificate<br/>with CA private key
signer ->> api: 7. Write status.certificate
deactivate signer
admin ->> api: 8. Retrieve signed certificate
activate api
api -->> admin: status.certificate
deactivate api
admin -->> user: 9. Deliver myuser.crt
activate user
user ->> user: 10. Configure kubeconfig<br/>myuser.crt + myuser.key
user ->> api: 11. Access API Server<br/>with the issued certificate
deactivate user
签发 myuser 的客户端证书
创建私钥
创建一把私钥。私钥需要妥善保管,任何取得私钥的人都可以冒充该用户。
创建 X.509 证书签名请求
这里生成的是 CSR 文件,与 Kubernetes 中同名的 CertificateSigningRequest API 对象不同;文件内容将填入该 API 对象。
CSR 中的 CN 表示用户名,O 表示用户所属的组。本例只设置 CN,将 myuser 替换为实际需要的用户名:
创建 Kubernetes CertificateSigningRequest
使用以下命令对 CSR 文件进行 Base64 编码,并移除换行符:
创建 CertificateSigningRequest,通过 kubectl 提交到 Kubernetes 集群。下面的命令直接将 myuser.csr 的 Base64 编码填入 request:
cat <<EOF | kubectl apply -f -
apiVersion: certificates.k8s.io/v1
kind: CertificateSigningRequest
metadata:
name: myuser
spec:
request: $(cat myuser.csr | base64 | tr -d "\n")
signerName: kubernetes.io/kube-apiserver-client
expirationSeconds: 86400 # 一天
usages:
- client auth
EOF
也可以将以下内容保存为 myuser.yaml,把 <BASE64_CSR> 替换为前面命令输出的 Base64 编码,再通过 kubectl 提交:
apiVersion: certificates.k8s.io/v1
kind: CertificateSigningRequest
metadata:
name: myuser
spec:
request: <BASE64_CSR>
signerName: kubernetes.io/kube-apiserver-client
expirationSeconds: 86400 # 一天
usages:
- client auth
usages:必须包含client auth。expirationSeconds:申请的证书有效期,单位为秒。可以设为864000(十天)或3600(一小时),最短为600(十分钟)。request:CSR 文件内容的 Base64 编码。
批准 CertificateSigningRequest
使用 kubectl 查找刚创建的 CSR,并手动批准。先列出 CSR:
批准 myuser 的 CSR:
获取证书
查看 CSR 对象,检查签发结果:
签发后的证书以 Base64 编码保存在 .status.certificate 中。确认该字段已有值后,将证书导出为 myuser.crt:
将证书配置到 kubeconfig
将用户凭据加入前面的 x509.kubeconfig.yaml,其中 API 地址和 ca.crt 应已配置好。--embed-certs=true 将客户端证书和私钥内容嵌入 kubeconfig:
kubectl --kubeconfig=x509.kubeconfig.yaml config set-credentials myuser \
--client-key=myuser.key --client-certificate=myuser.crt --embed-certs=true
添加上下文,关联集群与用户。这里的 course 对应前面 kubeconfig 中的集群名称:
kubectl --kubeconfig=x509.kubeconfig.yaml config set-context myuser \
--cluster=course --user=myuser
使用该上下文查询身份:
输出应确认当前用户名为 myuser。
创建 Role 和 RoleBinding
取得证书后,通过 Role 和 RoleBinding 授予用户访问集群资源的权限。以下命令由管理员执行,在 default 命名空间为该用户创建 Role:
kubectl create role developer --namespace=default \
--verb=create --verb=get --verb=list --verb=update --verb=delete --resource=pods
等价的 YAML 配置为:
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
name: developer
namespace: default
rules:
- apiGroups: [""]
resources: ["pods"]
verbs: ["create", "get", "list", "update", "delete"]
创建 RoleBinding,将 Role 绑定给用户 myuser:
kubectl create rolebinding developer-binding-myuser --namespace=default \
--role=developer --user=myuser
等价的 YAML 配置为:
OpenID Connect(OIDC)令牌¶
OpenID Connect(OIDC)在 OAuth 2.0 之上提供用户身份认证,适合接入企业统一登录。用户向身份提供方(IdP)登录后,客户端取得 id_token,将它作为 Bearer Token 提交给 API Server。ID Token 采用 JWT 格式,包含签发者、用户标识、受众和有效期等声明。
下图展示了 OIDC 认证过程中用户登录、令牌传递和 API Server 校验之间的关系。
sequenceDiagram
participant user as User
participant idp as Identity Provider
participant kube as kubectl
participant api as API Server
user ->> idp: 1. Log in to IdP
activate idp
idp -->> user: 2. Provide access_token,<br>id_token, and refresh_token
deactivate idp
activate user
user ->> kube: 3. Call kubectl<br>with --token being the id_token<br>OR add tokens to .kube/config
deactivate user
activate kube
kube ->> api: 4. Authorization: Bearer...
deactivate kube
activate api
api ->> api: 5. Is JWT signature valid?
api ->> api: 6. Has the JWT expired? (iat+exp)
api ->> api: 7. User authorized?
api -->> kube: 8. Authorized: Perform<br>action and return result
deactivate api
activate kube
kube --x user: 9. Return result
deactivate kube
图源: Kubernetes — Authenticating: OpenID Connect tokens.
- 登录到你的身份服务(Identity Provider)。
- 你的身份服务将为你提供
access_token、id_token和refresh_token。 - 在使用
kubectl时,将id_token设置为--token标志值,或者将其直接添加到kubeconfig中。 kubectl将你的id_token放到Authorization请求头中,发送给 API Server。- API Server 确保 JWT 的签名有效。
- 检查确认
id_token尚未过期。如果使用AuthenticationConfiguration配置了 CEL 表达式,则执行声明和/或用户验证。 - 确认用户有权限执行操作。
- 鉴权成功之后,API Server 向
kubectl返回响应。 kubectl向用户提供反馈信息。
API Server 配置
API Server 支持通过 --oidc-* 启动参数或 AuthenticationConfiguration 文件配置 OIDC。两种方式互斥,同时设置会导致 API Server 启动报错。
以下两个示例都信任 https://sso.example.com/realms/platform,要求 ID Token 的 aud 包含 kubernetes,并将邮箱与用户组加上 oidc: 前缀,避免与其他身份来源混淆。身份提供方需要在 ID Token 中发布 email 和 groups 声明。
通过命令行参数配置 OIDC
--oidc-* 参数用于配置单个 OIDC 签发者。将以下参数加入现有的 API Server 启动命令:
--oidc-issuer-url=https://sso.example.com/realms/platform
--oidc-client-id=kubernetes
--oidc-username-claim=email
--oidc-username-prefix=oidc:
--oidc-groups-claim=groups
--oidc-groups-prefix=oidc:
--oidc-issuer-url:指定签发者的 HTTPS 地址,API Server 通过其 OIDC discovery 获取验签公钥信息。--oidc-client-id:填写在 IdP 中注册的 OIDC 应用的 Client ID。API Server 检查 ID Token 的aud是否包含该值;本例使用kubernetes,实际配置时需替换为自己的 Client ID。--oidc-username-claim与--oidc-username-prefix:读取email声明并加上oidc:前缀,例如oidc:alice@example.com。使用email时,若 ID Token 包含email_verified,其值须为布尔值true。--oidc-groups-claim与--oidc-groups-prefix:读取groups字符串数组并为每个组加上oidc:前缀,例如oidc:developers。--oidc-ca-file:身份提供方使用私有 CA 时,指定用于验证其 HTTPS 证书的 CA 文件;省略时使用系统信任的 CA。
完整参数说明见 Using command line arguments。
通过 AuthenticationConfiguration 配置 OIDC
通过 AuthenticationConfiguration 的 jwt 字段配置 API Server 对 ID Token 的校验。文件方式支持多个签发者、CEL 表达式和配置自动重载;本例通过 CEL 要求 email_verified 为 true。字段定义见 kube-apiserver Configuration (v1)。
apiVersion: apiserver.config.k8s.io/v1
kind: AuthenticationConfiguration
jwt:
- issuer:
url: https://sso.example.com/realms/platform
audiences:
- kubernetes
claimValidationRules:
- expression: 'claims.email_verified == true'
message: email must be verified
claimMappings:
username:
claim: email
prefix: 'oidc:'
groups:
claim: groups
prefix: 'oidc:'
将文件放到 API Server 可读取的位置,并在 API Server 启动命令中加入以下参数:
issuer.url:指定签发者地址,其服务需提供可访问的 OIDC discovery 和 JWKS 公钥。该地址须与 ServiceAccount issuer 不同。issuer.certificateAuthority:身份提供方使用私有 CA 时,填写 PEM 编码的 CA 证书内容;省略时使用系统信任的 CA。issuer.audiences:列出 API Server 接受的 OIDC 应用的 Client ID。API Server 检查 ID Token 的aud是否与列表中的至少一个值匹配;本例使用kubernetes,实际配置时需替换为自己的 Client ID。claimValidationRules:使用 CEL 校验声明,本例要求email_verified存在且为布尔值true。claimMappings:将email映射成oidc:alice@example.com,将groups中的developers映射成oidc:developers。
切换到文件方式时,应移除已有的 --oidc-* 启动参数。配置规则见 Authentication configuration from a file。
客户端配置
使用 kubelogin 提供的 kubectl oidc-login 插件,可以自动获取、缓存和刷新 ID Token,省去手动复制令牌以及过期后更新配置的操作。kubeconfig 的 exec 字段保存调用插件的命令和参数;kubectl 需要凭据时,执行该命令,由插件返回 ID Token。
首次使用时,插件打开浏览器,引导用户完成 IdP 登录,并将取得的 ID Token 返回给 kubectl,用于访问 API Server。令牌默认缓存在本机的 ~/.kube/cache/oidc-login/ 目录中,不写入 kubeconfig。后续调用时,插件优先使用缓存中仍有效的 ID Token;过期后尝试使用 Refresh Token 刷新,无法刷新时重新发起登录。
图源:int128/kubelogin: Credential plugin。图中插件负责登录和令牌交换,API Server 负责校验收到的 ID Token。
用户需要一个已在身份提供方注册的 OIDC 客户端。这个例子使用无需客户端密钥的公开客户端,ID 为 kubernetes,启用授权码流程和 PKCE,并登记 http://localhost:18000 回调地址。身份提供方还需要允许请求 email、groups scope,并在 ID Token 中发布对应声明。
通过 kubelogin 登录
已安装 Krew 的客户端,可以用以下命令安装插件:
将以下 kubeconfig 的 API 地址、CA 路径、issuer URL 和客户端 ID 改为实际配置。执行 kubectl 时,Exec 插件发起登录并返回凭据:
apiVersion: v1
kind: Config
clusters:
- name: course
cluster:
server: https://api.example.com:6443
certificate-authority: ca.crt
users:
- name: client
user:
exec:
apiVersion: client.authentication.k8s.io/v1
command: kubectl
args:
- oidc-login
- get-token # 获取 ID Token 并返回给 kubectl
- --oidc-issuer-url=https://sso.example.com/realms/platform # 身份提供方的签发者地址
- --oidc-client-id=kubernetes # 在身份提供方注册的客户端 ID
- --grant-type=authcode # 使用授权码流程完成登录
- --listen-address=127.0.0.1:18000 # 本地接收登录回调的监听地址
- --oidc-extra-scope=email # 请求邮箱相关声明
- --oidc-extra-scope=groups # 请求用户组声明
interactiveMode: Never
contexts:
- name: course
context:
cluster: course
user: client
namespace: default
current-context: course
邮箱为 alice@example.com 的用户应显示为 oidc:alice@example.com。RBAC 绑定也要使用映射后的用户名或组名。插件的配置与身份提供方接入要求见 kubelogin Setup。
服务账号令牌¶
ServiceAccount 为 Pod、Controller 和自动化程序提供访问 Kubernetes API 的身份。客户端通过 TokenRequest API 申请带有有效期和受众(audience)的 Token,并将其放入 Authorization: Bearer ... 请求头中,以对应的服务账号身份访问 API Server。例如,使用 default 命名空间中 pod-reader 的 Token 认证后,用户名为 system:serviceaccount:default:pod-reader。身份与权限的配置见 Service Accounts。
Pod 内使用
Pod 通过 serviceAccountName 选择身份。Kubelet 为该身份申请 Token,并通过投射卷(projected)将 Token 作为文件挂载到容器中,应用读取文件后即可携带 Token 发起请求。Kubelet 会在 Token 到期前更新文件,应用需要重新读取才能使用新 Token。Pod 和 ServiceAccount 都未设置 automountServiceAccountToken 时,默认启用自动挂载。也可以通过 serviceAccountToken 显式指定受众、申请有效期和文件路径。
使用投射 Token 读取 Pod 列表
这个 Pod 使用具有 Pod 列表读取权限的 pod-reader 服务账号,调用 Kubernetes API 并输出 default 命名空间中的 Pod 名称。Python 程序读取自定义投射卷中的 /var/run/api-credentials/token 完成身份认证,并使用默认挂载的 /var/run/secrets/kubernetes.io/serviceaccount/ca.crt 校验 API Server 的证书。
apiVersion: v1
kind: Pod
metadata:
name: api-client
namespace: default
spec:
serviceAccountName: pod-reader # 使用已创建并获授权的服务账号
restartPolicy: Never
containers:
- name: client
image: python:3.13-alpine
command: ["python", "-c"]
args:
- |
import json
import ssl
import urllib.request
from pathlib import Path
token = Path("/var/run/api-credentials/token").read_text().strip()
context = ssl.create_default_context(
cafile="/var/run/secrets/kubernetes.io/serviceaccount/ca.crt"
)
request = urllib.request.Request(
"https://kubernetes.default.svc/api/v1/namespaces/default/pods",
headers={"Authorization": f"Bearer {token}"},
)
with urllib.request.urlopen(request, context=context, timeout=10) as response:
data = json.load(response)
print(json.dumps([item["metadata"]["name"] for item in data["items"]]))
volumeMounts:
- name: credentials
mountPath: /var/run/api-credentials # 程序从此目录读取 Token
readOnly: true
volumes:
- name: credentials
projected: # 将 Token 挂载为容器内的文件
sources:
- serviceAccountToken: # 由 Kubelet 申请 Token,省略 audience 时面向 API Server
path: token # Token 文件相对于挂载目录的路径
expirationSeconds: 3600 # 申请一小时有效期,实际期限由 API Server 决定
集群外使用
具有 serviceaccounts/token 创建权限的调用者可以申请短期 Token,再交给集群外程序使用。这里省略 --audience,申请面向当前 API Server 的 Token;显式指定受众时,应使用该集群接受的值。
# 为 default 命名空间的 pod-reader 申请一小时有效期的 Token
kubectl create token pod-reader -n default --duration=1h
将命令输出填入以下 kubeconfig 的 token 字段,替换 <SERVICEACCOUNT_TOKEN>,并将 server 改为实际 API Server 地址。将用于验证 API Server 的 CA 证书保存为同目录下的 ca.crt。
ServiceAccount 客户端 kubeconfig
apiVersion: v1
kind: Config
clusters:
- name: course
cluster:
server: https://api.example.com:6443
certificate-authority: ca.crt # 用于验证 API Server 服务端证书的 CA 文件
users:
- name: pod-reader
user:
token: '<SERVICEACCOUNT_TOKEN>' # 填入为 pod-reader 申请的 Token
contexts:
- name: pod-reader
context:
cluster: course
user: pod-reader
namespace: default
current-context: pod-reader
使用该配置查询当前身份和 Pod 列表:
# 查询 API Server 识别的当前身份
kubectl --kubeconfig=serviceaccount.kubeconfig.yaml auth whoami
# 以 pod-reader 身份列出 default 命名空间中的 Pod
kubectl --kubeconfig=serviceaccount.kubeconfig.yaml get pods -n default
--duration=1h 是申请值,服务端决定实际期限。这个 kubeconfig 保存 Token 的副本,过期后需要重新申请并更新;集群外没有 kubelet 为它自动轮换。参数说明见 kubectl create token。
Webhook 令牌身份认证¶
Webhook 令牌身份认证通过远程回调验证 Bearer Token,适合接入已有的令牌系统。客户端向 API Server 提交令牌,API Server 将它放入 TokenReview,通过 HTTP POST 发给远程认证服务;服务返回令牌是否有效以及对应的用户身份。
可以在 API Server 的启动命令中通过以下参数配置 Webhook 令牌身份认证:
--authentication-token-webhook-config-file=/etc/kubernetes/auth/token-webhook.kubeconfig.yaml
--authentication-token-webhook-cache-ttl=2m
--authentication-token-webhook-version=v1
--authentication-token-webhook-config-file指向一个配置文件,其中描述如何访问远程的 Webhook 服务。--authentication-token-webhook-cache-ttl用来设定身份认证决定的缓存时间,默认时长为 2 分钟。--authentication-token-webhook-version决定使用authentication.k8s.io/v1beta1还是authentication.k8s.io/v1版本的TokenReview对象与 Webhook 收发信息,默认为v1beta1。
配置文件使用 kubeconfig 格式,格式说明见 Organizing Cluster Access Using kubeconfig Files。在此文件中,clusters 指代远程服务,users 定义 API Server 调用远程 Webhook 服务时使用的客户端凭据。
Webhook 服务连接配置
# Kubernetes API 版本
apiVersion: v1
# API 对象类别
kind: Config
# clusters 指代远程服务
clusters:
- name: name-of-remote-authn-service
cluster:
certificate-authority: /path/to/ca.pem # 用来验证远程服务的 CA
server: https://authn.example.com/authenticate # 要查询的远程服务 URL,生产环境中建议使用 HTTPS
# 当远程 Webhook 服务要求 mTLS 认证时,在 users 中配置 API Server 使用的客户端证书和私钥
users:
- name: name-of-api-server
user:
client-certificate: /path/to/cert.pem # Webhook 插件要使用的证书
client-key: /path/to/key.pem # 与证书匹配的密钥
# kubeconfig 文件需要一个上下文,此上下文用于本 API Server
current-context: webhook
contexts:
- context:
cluster: name-of-remote-authn-service
user: name-of-api-server
name: webhook
当客户端尝试在 API Server 上使用持有者令牌完成身份认证时,身份认证 Webhook 会通过 POST 请求将 JSON 序列化的 TokenReview 对象发送到远程服务,其中包含客户端提交的持有者令牌。客户端请求的令牌格式见 Putting a bearer token in a request。
Webhook API 对象与其他 Kubernetes API 对象一样,受到 The Kubernetes API 中版本兼容规则的约束。实现者应检查请求的 apiVersion 字段,以确保正确反序列化,并且必须以与请求相同版本的 TokenReview 对象进行响应。
API Server 默认发送 authentication.k8s.io/v1beta1 版本的 TokenReview 对象。以下示例使用 authentication.k8s.io/v1,需要在 API Server 的启动参数中设置 --authentication-token-webhook-version=v1。
TokenReview 请求
{
"apiVersion": "authentication.k8s.io/v1",
"kind": "TokenReview",
"spec": {
# 发送到 API Server 的不透明持有者令牌
"token": "014fbff9a07c...",
# 可选:Webhook 认证服务需检查 Token 的有效受众是否与此列表有交集。
# 省略时,服务需按预先配置的 Kubernetes API Server 受众进行检查。
"audiences": ["https://myserver.example.com", "https://myserver.internal.example.com"]
}
}
远程服务填写 status 字段以指示身份认证结果。响应正文的 spec 字段会被忽略,可以省略。远程服务必须使用它收到的相同 TokenReview API 版本返回响应。
TokenReview 成功响应
持有者令牌验证成功时返回:
{
"apiVersion": "authentication.k8s.io/v1",
"kind": "TokenReview",
"status": {
"authenticated": true,
"user": {
# 必需
"username": "janedoe@example.com",
# 可选
"uid": "42",
# 可选的组成员身份
"groups": ["developers", "qa"],
# 认证组件提供的可选附加信息。
# 此字段不可包含机密数据,因为这类数据可能被记录在日志或 API 对象中,
# 并且可能传递给准入 Webhook。
"extra": {
"extrafield1": [
"extravalue1",
"extravalue2"
]
}
},
# 受众感知令牌认证组件可以返回的可选受众列表,
# 包含 spec.audiences 中对此令牌有效的受众。
# 如果省略,则认为该令牌可用于向 Kubernetes API Server 进行身份认证。
"audiences": ["https://myserver.example.com"]
}
}
TokenReview 失败响应
持有者令牌验证失败时返回:
身份认证代理¶
身份认证代理负责验证用户身份,并将请求转发给 API Server。转发时,代理使用自己的客户端证书证明身份,通过 X-Remote-User、X-Remote-Group 等请求头传递用户名和用户组。API Server 验证代理的客户端证书、确认代理可信后,使用这些请求头中的用户信息完成身份认证。
应用场景
身份认证代理的常见应用场景如下:一种是企业登录网关,由网关验证用户身份,再将请求转发给 API Server;另一种是聚合 API,由 API Server 充当代理,向扩展 API Server 发起请求。
- 企业登录网关:企业已有 LDAP、SAML 或 Kerberos 认证系统时,可以由代理对接这些系统,并将认证结果转换成 Kubernetes 使用的用户名和用户组。例如,代理确认 Alice 属于
developers组后,将这个身份传给 API Server,再由 RBAC 判断她是否有权执行请求中的操作。Kubernetes 官方将这些协议列为 External integrations 的适用场景。 - 访问聚合 API:API Server 充当身份认证代理,将请求转发给扩展 API Server,并通过代理证书和请求头传递已经认证的用户身份。例如,执行
kubectl top pods时,指标请求会被转发给 Metrics Server。Metrics Server 作为扩展 API Server,验证代理证书、读取用户身份并进行授权检查。证书与身份头的传递过程见 Configure the Aggregation Layer。
请求流程
下图展示了客户端通过身份认证代理访问 API Server 的请求流程。代理验证客户端凭据或已有登录会话后,将请求和用户身份转发给 API Server。
sequenceDiagram
participant C as Client
participant P as Authentication proxy
participant I as Identity service
participant A as kube-apiserver
C->>P: API request<br/>Client credentials
P->>P: Remove untrusted identity headers
P->>I: Authenticate user
I-->>P: alice@example.com<br/>Group: developers
P->>A: TLS handshake<br/>Proxy client certificate
P->>A: API request<br/>X-Remote-User + X-Remote-Group
A->>A: Verify proxy CA and allowed CN
A->>A: Read user identity<br/>Authorize with RBAC
A->>A: Process request
A-->>P: API response
P-->>C: API response
- 客户端发起请求:客户端访问身份认证代理,提交 API 请求和用于认证的凭据。
- 清除外部身份头:代理移除客户端传入的
X-Remote-User、X-Remote-Group等身份头,防止客户端自行声明用户名或用户组。 - 验证用户身份:代理调用身份服务校验凭据,取得用户名和用户组。图中返回的用户名是
alice@example.com,用户组是developers。 - 转发请求和身份:代理与 API Server 建立 TLS 连接,提交自己的客户端证书,并在转发的请求中通过
X-Remote-User、X-Remote-Group传递已认证的用户身份。 - 验证代理身份:API Server 使用配置的代理 CA 验证客户端证书,并检查证书中的 CN 是否满足允许名称列表的限制。校验通过后,才信任代理设置的身份头。
- 鉴权与请求处理:API Server 从身份头中读取用户名和用户组,由 RBAC 判断该用户是否有权执行请求中的操作;获得授权后继续处理请求。
- 返回响应:API Server 将响应返回给代理,代理再转发给客户端。
API Server 配置
以下配置用于前置身份认证代理,代理客户端证书的 CN 为 auth-proxy。API Server 验证代理证书后,从请求头读取用户身份:
--requestheader-client-ca-file=/etc/kubernetes/pki/auth-proxy-ca.crt
--requestheader-allowed-names=auth-proxy
--requestheader-username-headers=X-Remote-User
--requestheader-group-headers=X-Remote-Group
--requestheader-extra-headers-prefix=X-Remote-Extra-
--requestheader-client-ca-file:指定用于验证代理客户端证书的可信 CA 文件。API Server 验证代理证书后,才会读取身份请求头。--requestheader-allowed-names:限定代理客户端证书中允许的 Common Name(CN)。auth-proxy是本例使用的 CN,配置时须与实际代理证书的 CN 一致。列表为空时,接受可信代理 CA 签发的任意 CN。--requestheader-username-headers:指定用于提取用户名的请求头,本例从X-Remote-User读取用户名。--requestheader-group-headers:指定用于提取用户组的请求头,本例从X-Remote-Group读取用户组;可以重复发送该请求头,传递多个组。--requestheader-extra-headers-prefix:指定附加用户信息请求头的前缀。例如,X-Remote-Extra-Tenant: platform会映射为用户信息中的extra.tenant: ["platform"]。
请求头与用户信息
例如,使用下面的配置指定用户名、用户组和附加信息的请求头:
--requestheader-username-headers=X-Remote-User
--requestheader-group-headers=X-Remote-Group
--requestheader-extra-headers-prefix=X-Remote-Extra-
代理的客户端证书通过校验后,API Server 从以下请求头中读取用户身份:
GET / HTTP/1.1
X-Remote-User: fido
X-Remote-Group: dogs
X-Remote-Group: dachshunds
X-Remote-Extra-Acme.com%2Fproject: some-project
X-Remote-Extra-Scopes: openid
X-Remote-Extra-Scopes: profile
从这些请求头提取出的用户信息如下:
name: fido
groups:
- dogs
- dachshunds
extra:
acme.com/project:
- some-project
scopes:
- openid
- profile
重复的 X-Remote-Group 头提供多个用户组。附加信息头去掉 X-Remote-Extra- 前缀后,键名转为小写并进行百分号解码,因此 Acme.com%2Fproject 对应 acme.com/project;同名头的多个值组成列表。映射规则见 Authenticating reverse proxy。
启动引导令牌¶
新节点加入集群时,Kubelet 尚无自己的客户端证书,可以使用 Bootstrap Token 建立初始身份并申请证书。证书签发后,Kubelet 使用节点证书继续访问 API Server。
API Server 配置
启用 Bootstrap Token 认证后,API Server 读取 kube-system 中类型为 bootstrap.kubernetes.io/token 的 Secret:
kubeadm init 默认创建启动引导令牌,之后可以通过 kubeadm token create 创建新的令牌。kubeadm 自动将每个令牌保存为 kube-system 命名空间中的一个 Secret,名称为 bootstrap-token-<token-id>,类型为 bootstrap.kubernetes.io/token。
启动引导令牌的 Secret 格式
Secret 保存令牌的标识、密钥、用途和过期时间,字段定义见 Bootstrap Token Secret Format:
apiVersion: v1
kind: Secret
metadata:
# 名称必须是 bootstrap-token-<token-id>
name: bootstrap-token-07401b
namespace: kube-system
type: bootstrap.kubernetes.io/token
stringData:
# 可选的用途说明
description: "Bootstrap token for joining nodes."
# 令牌的两部分,均为必填项
token-id: "07401b"
token-secret: "f395accd246ae52d"
# 可选;替换为 RFC3339 格式的 UTC 时间
expiration: "<RFC3339_UTC_TIME>"
usage-bootstrap-authentication: "true"
usage-bootstrap-signing: "true"
# 可选的附加用户组,以逗号分隔
auth-extra-groups: "system:bootstrappers:worker,system:bootstrappers:ingress"
metadata.name、metadata.namespace与type:Secret 名称必须为bootstrap-token-<token-id>,位于kube-system命名空间,类型为bootstrap.kubernetes.io/token,API Server 才能按 Bootstrap Token 读取它。token-id与token-secret:分别为 6 位和 16 位小写字母或数字,用一个英文句点连接。上面的字段组成完整令牌07401b.f395accd246ae52d;token-id用于标识令牌,token-secret是认证所需的密钥。usage-bootstrap-authentication:设为字符串"true"时,允许客户端将完整令牌作为 Bearer Token,向 API Server 进行身份认证。usage-bootstrap-signing:设为字符串"true"时,允许 BootstrapSigner 控制器使用该令牌为kube-public/cluster-infoConfigMap 生成签名,供新节点在发现集群时校验。签名功能需要在 Controller Manager 中启用bootstrapsigner控制器。expiration:可选的绝对过期时间,使用 RFC3339 格式的 UTC 时间;省略时不设置过期时间。令牌过期后不能用于认证,也不再用于生成 ConfigMap 签名。Controller Manager 启用tokencleaner控制器后,会自动删除过期令牌对应的 Secret。auth-extra-groups:指定认证成功后的附加用户组,多个组以逗号分隔,每个组名必须以system:bootstrappers:开头。
客户端使用上述令牌通过认证后,用户名为 system:bootstrap:07401b,属于默认的 system:bootstrappers 组,以及 Secret 中配置的 system:bootstrappers:worker 和 system:bootstrappers:ingress 组。API Server 还会为所有已认证用户添加 system:authenticated 组。这些用户名和用户组供 RBAC 匹配权限规则,节点申请证书还需要相应的授权与审批配置,流程见 TLS bootstrapping。
创建令牌与节点加入
在 kubeadm 控制面节点上创建有效期为 30 分钟的令牌,并输出完整加入命令:
新节点执行返回的命令,其形式如下。--discovery-token-ca-cert-hash 固定所信任的控制面 CA 公钥,节点会用它检查发现的集群:
sudo kubeadm join api.example.com:6443 \
--token '<BOOTSTRAP_TOKEN>' \
--discovery-token-ca-cert-hash 'sha256:<CA_PUBLIC_KEY_HASH>'
令牌过期后不能继续用于新请求认证;它适用于节点引导,日常用户登录应使用用户身份。参数与节点侧配置见 kubeadm token 和 kubeadm join。
静态令牌文件¶
API Server 可以在启动时读取 CSV,将固定 Token 映射为用户名、UID 和用户组。Token 没有内置过期时间,更新文件后需要重启 API Server。
API Server 配置
CSV 不写表头,四列依次是 Token、用户名、UID 和用户组。第一行展示字段占位符,第二行给出具体示例;多个组放在同一个带引号的字段内:
<STATIC_TOKEN>,<USERNAME>,<USER_UID>,"<GROUP_1>,<GROUP_2>"
example-token-alice,alice,alice-001,"developers,platform-readers"
按上述格式填写实际用户记录,将文件挂载到 API Server,并设置:
客户端配置
客户端在 kubeconfig 的 token 字段中填写与 CSV 第一列相同的 Token,替换 <STATIC_TOKEN>;服务端从 CSV 取得用户名和用户组。
静态 Token 客户端 kubeconfig
将 server 改为实际 API Server 地址,并将服务端 CA 证书保存为同目录下的 ca.crt。
apiVersion: v1
kind: Config
clusters:
- name: course
cluster:
server: https://api.example.com:6443
certificate-authority: ca.crt # 用于验证 API Server 服务端证书的 CA 文件
users:
- name: client
user:
token: '<STATIC_TOKEN>' # 与 API Server 使用的 CSV 文件第一列保持一致
contexts:
- name: course
context:
cluster: course
user: client
namespace: default
current-context: course
使用该配置查询当前身份:
匿名请求¶
启用匿名访问时,未提供凭据的请求可以被识别为用户 system:anonymous,所属组为 system:unauthenticated,随后继续进行授权检查。提交无效 Bearer Token 的请求会认证失败,不会因此转成匿名请求。
API Server 配置
AuthenticationConfiguration 可以只允许健康检查路径接受匿名请求。这个配置允许 /livez、/readyz 和 /healthz,其他路径仍要求有效身份:
apiVersion: apiserver.config.k8s.io/v1
kind: AuthenticationConfiguration
anonymous:
enabled: true
conditions:
- path: /livez
- path: /readyz
- path: /healthz
通过 --authentication-config 指定 API Server 要加载的认证配置文件:
客户端请求
客户端只验证 API Server 的服务端证书,不提交 Token 或客户端证书:
kubectl auth whoami 可以检查其他方式认证后的身份。认证失败通常对应 401 Unauthorized;身份已识别但没有相应权限时,授权阶段返回 403 Forbidden。
鉴权¶
鉴权(Authorization)发生在身份认证之后,用来判断当前用户能否执行请求中的操作。例如,用户已经通过证书认证,仍需要相应权限才能读取 Secret 或创建 Deployment。允许匿名访问的集群也会对匿名身份进行鉴权;只有请求获得允许后,才会进入后续处理。
鉴权裁定¶
API Server 把身份和请求属性交给鉴权模块。模块根据策略返回三种结果之一:
- 允许(Allow):当前模块允许请求,立即结束鉴权链。
- 拒绝(Deny):当前模块明确拒绝请求,立即结束鉴权链。
- 无意见(NoOpinion):当前模块没有作出允许或拒绝的裁定,继续检查下一个模块。
多个模块按照配置顺序执行,第一个 Allow 或 Deny 决定结果;如果全部返回 NoOpinion,API Server 拒绝请求并返回 403 Forbidden。例如,在 Node,RBAC 中,普通用户的请求通常由 Node 返回 NoOpinion,再由 RBAC 检查角色绑定。RBAC 找不到允许规则时也返回 NoOpinion,由鉴权链最终拒绝。
鉴权主要判断谁可以对哪些资源执行什么操作。镜像是否来自指定仓库、Pod 能否使用特权模式等依赖对象内容的策略由准入控制处理。鉴权允许写请求后,准入控制仍可以拒绝它。
鉴权中使用的请求属性¶
身份来自认证结果,资源和操作来自请求路径、HTTP 方法等信息。API Server 使用这些属性进行权限匹配:
- 用户(
user):经过认证的用户名,例如alice@example.com或system:serviceaccount:default:pod-reader。 - 用户组(
groups):认证结果中的组名列表,例如developers、system:authenticated。 - 附加信息(
extra):认证模块提供的扩展属性;每个字符串键对应一个字符串值列表。 - 请求类别:区分资源请求与非资源请求。两类请求使用不同的权限规则。
- 请求路径(
path):用于非资源请求,例如/api、/version、/healthz。 - API 请求动词(
verb):API 动词get、list、create、update、patch、watch、proxy、redirect、delete和deletecollection用于资源请求。要确定资源 API 端点的请求动词,请参阅请求动词和鉴权。 - HTTP 请求动词(
verb):HTTP 动词get、post、put和delete用于非资源请求。 - 资源(
resource、name):正在访问的资源的 ID 或名称(仅限资源请求)- 对于使用get、update、patch和delete动词的资源请求,你必须提供资源名称。 - 子资源(
subresource):正在访问的子资源(仅限资源请求)。这可以是标准子资源(例如,status或scale),也可以是用于细粒度授权的合成子资源。 - 命名空间(
namespace):资源所属的命名空间。Node、Namespace 等集群级资源不属于任何命名空间。 - API 组(
apiGroup):例如 Deployment 属于apps,Pod 属于以空字符串""表示的核心 API 组。
RBAC 配置示例
这份 RBAC 配置允许用户 alice 或 developers 组成员读取、修改 default/vllm-demo 的副本数,并通过 GET 访问 /healthz。Role 和 ClusterRole 定义允许的操作,RoleBinding 和 ClusterRoleBinding 将这些权限授予用户或用户组。
# 资源请求:读取或修改 default/vllm-demo 的副本数
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
# 角色名称,供绑定的 roleRef 引用
name: vllm-scale-editor
# 权限适用的命名空间
namespace: default
rules:
# 请求的 API 组
- apiGroups: ["apps"]
# 资源请求:资源为 deployments,子资源为 scale
resources: ["deployments/scale"]
# 限定 Deployment 对象名称
resourceNames: ["vllm-demo"]
# API 请求动词:读取或修改 scale 子资源
verbs: ["get", "patch"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
name: vllm-scale-editors
# 与引用的 Role 位于同一命名空间
namespace: default
subjects:
# 匹配用户名或用户组中的任意一项即可获得权限
- kind: User
name: alice
apiGroup: rbac.authorization.k8s.io
- kind: Group
name: developers
apiGroup: rbac.authorization.k8s.io
roleRef:
kind: Role
name: vllm-scale-editor
apiGroup: rbac.authorization.k8s.io
---
# /healthz 不属于任何命名空间,使用 ClusterRole 和 ClusterRoleBinding 授权
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
name: course-healthz-reader
rules:
# 非资源请求:匹配请求路径
- nonResourceURLs: ["/healthz"]
# HTTP 请求动词:允许 GET 请求,对应的 verb 为 get
verbs: ["get"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
name: course-healthz-readers
# 将权限授予 alice 用户或 developers 组成员
subjects:
- kind: User
name: alice
apiGroup: rbac.authorization.k8s.io
- kind: Group
name: developers
apiGroup: rbac.authorization.k8s.io
# 引用允许 GET 访问 /healthz 的 ClusterRole
roleRef:
kind: ClusterRole
name: course-healthz-reader
apiGroup: rbac.authorization.k8s.io
鉴权方式¶
Kubernetes 支持 RBAC、Node、Webhook、ABAC、AlwaysAllow 和 AlwaysDeny 六种鉴权模式。
RBAC¶
RBAC(Role-Based Access Control,基于角色的访问控制)根据用户在组织中的角色管理资源访问权限。Kubernetes 使用 rbac.authorization.k8s.io API 组实现 RBAC,允许通过 Kubernetes API 动态配置权限策略。
API Server 配置
在 API Server 的启动参数中启用 RBAC 鉴权。使用 kubeadm 部署时,修改 /etc/kubernetes/manifests/kube-apiserver.yaml 中容器的 command 列表:
Role 和 ClusterRole
Role 和 ClusterRole 都包含一组表示权限的规则。权限是累加的,没有“拒绝”规则。两者的定义见 Role and ClusterRole。
- Role:在特定命名空间内定义权限,创建时必须指定所属的命名空间。
- ClusterRole:不属于任何命名空间。它可以定义命名空间内资源的权限,供不同命名空间复用或在所有命名空间中授权;也可以定义 Node 等集群级资源和
/healthz等非资源端点的权限。
下面的 pod-reader Role 在 default 命名空间中定义 Pod 的读取权限。apiGroups: [""] 表示核心 API 组,get、watch 和 list 分别允许读取单个 Pod、监听变化和获取列表:
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
namespace: default
name: pod-reader
rules:
- apiGroups: [""] # 空字符串表示核心 API 组。
resources: ["pods"]
verbs: ["get", "watch", "list"]
下面的 secret-reader ClusterRole 定义 Secret 的读取权限。它不设置 metadata.namespace;这些权限授予单个命名空间还是所有命名空间,取决于使用哪种绑定:
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
name: secret-reader
rules:
- apiGroups: [""]
resources: ["secrets"]
verbs: ["get", "watch", "list"]
RoleBinding 和 ClusterRoleBinding
角色绑定将角色中定义的权限授予用户、用户组或 ServiceAccount。绑定中的 subjects 列出授权对象,roleRef 引用要授予的角色。两类绑定的作用范围见 RoleBinding and ClusterRoleBinding。
- RoleBinding:在特定命名空间内授予权限,可以引用同一命名空间中的 Role,也可以引用 ClusterRole。
- ClusterRoleBinding:在整个集群范围内授予权限,引用的角色必须是 ClusterRole。
下面的 RoleBinding 将 default 中的 pod-reader Role 授予用户 jane,使她可以读取该命名空间中的 Pod。roleRef.name 必须与前面 Role 的 metadata.name 一致:
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
name: read-pods
namespace: default
subjects:
- kind: User
name: jane
apiGroup: rbac.authorization.k8s.io
roleRef:
kind: Role
name: pod-reader
apiGroup: rbac.authorization.k8s.io
RoleBinding 也可以引用 ClusterRole,以便在多个命名空间中复用同一组规则。下面的 RoleBinding 引用 secret-reader,将 Secret 读取权限授予用户 dave,授权范围限定在该绑定所在的 development 命名空间:
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
name: read-secrets
namespace: development
subjects:
- kind: User
name: dave
apiGroup: rbac.authorization.k8s.io
roleRef:
kind: ClusterRole
name: secret-reader
apiGroup: rbac.authorization.k8s.io
下面的 ClusterRoleBinding 引用同一个 secret-reader,将权限授予 manager 组。该组中的用户可以读取所有命名空间中的 Secret:
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
name: read-secrets-global
subjects:
- kind: Group
name: manager
apiGroup: rbac.authorization.k8s.io
roleRef:
kind: ClusterRole
name: secret-reader
apiGroup: rbac.authorization.k8s.io
绑定创建后,roleRef 不能修改。要改为引用其他角色,需要删除原绑定并重新创建;subjects 列表可以更新。
完整示例:ServiceAccount、Role 和 RoleBinding
以下配置为 default 命名空间中的 pod-reader ServiceAccount 授予 Pod 的读取权限。ServiceAccount 提供身份,Role 定义允许的操作,RoleBinding 通过 subjects 指定该 ServiceAccount,并通过 roleRef 引用 Role,将两者关联起来。
apiVersion: v1
kind: ServiceAccount
metadata:
name: pod-reader
namespace: default
---
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
name: pod-reader
namespace: default
rules:
- apiGroups: [""] # 核心 API 组
resources: ["pods"]
verbs: ["get", "watch", "list"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
name: pod-reader-serviceaccount
namespace: default # 授权范围
subjects:
- kind: ServiceAccount
name: pod-reader # 对应 ServiceAccount 的名称
namespace: default # 对应 ServiceAccount 所在的命名空间
roleRef:
apiGroup: rbac.authorization.k8s.io
kind: Role
name: pod-reader # 引用同一命名空间中的 Role
Node¶
Node 是专门面向 Kubelet 的鉴权模式。它根据节点与 Pod、卷、Secret 等对象之间的关联,允许 Kubelet 获取运行本节点 Pod 所需的数据,并执行状态上报等操作。
节点身份
Node 鉴权要求用户名为 system:node:<nodeName>,并且属于 system:nodes 组。<nodeName> 必须与 Kubelet 注册的 Node 名称一致。例如,节点 worker-01 的身份为 system:node:worker-01。
Node 鉴权允许 Kubelet 读取自身 Node、绑定到本节点的 Pod,以及这些 Pod 关联的 Secret、ConfigMap、PVC 和 PV。它还允许 Kubelet 写入事件、更新 Node 和 Pod 状态,通过 CertificateSigningRequest API 申请证书,并创建 TokenReview 和 SubjectAccessReview 进行委托认证与鉴权。具体权限见 Using Node Authorization。
API Server 配置
在 API Server 的启动参数中启用 Node 鉴权和 NodeRestriction 准入插件:
NodeRestriction 在准入阶段检查 Kubelet 对 Node 和 Pod 的修改请求,确保目标是自身 Node 或绑定到本节点的 Pod。它还限制 Kubelet 修改节点标签和污点。
Webhook¶
Webhook 鉴权把权限判断交给外部服务。API Server 将已认证的身份和请求属性封装成 SubjectAccessReview,同步 POST 到配置的 HTTPS 地址,等待服务返回裁定后继续处理。它适合接入企业权限系统;前面的认证 Webhook 使用 TokenReview 校验令牌,鉴权 Webhook 使用 SubjectAccessReview 判断某个身份能否执行操作。
API Server 配置
在 API Server 的启动参数中启用 Webhook 鉴权,指定连接配置文件,并使用 v1 版本的 SubjectAccessReview:
--authorization-mode=Webhook
--authorization-webhook-config-file=/etc/kubernetes/authorization/webhook.kubeconfig.yaml
--authorization-webhook-version=v1
API Server 使用 kubeconfig 保存外部服务地址和 TLS 配置。以下文件中,clusters 指向鉴权服务,users 保存 API Server 调用该服务的客户端证书:
鉴权 Webhook 的连接配置
apiVersion: v1
kind: Config
clusters:
- name: authorization-service
cluster:
server: https://authz.example.com/authorize
certificate-authority: /etc/kubernetes/authorization/webhook-ca.crt
users:
- name: kube-apiserver
user:
client-certificate: /etc/kubernetes/authorization/webhook-client.crt
client-key: /etc/kubernetes/authorization/webhook-client.key
contexts:
- name: authorization-service
context:
cluster: authorization-service
user: kube-apiserver
current-context: authorization-service
https://authz.example.com/authorize 需要替换成实际服务地址,CA 和客户端证书需要由管理员提供。此文件配置的是 API Server 到鉴权服务的连接,用户仍使用自己的 kubeconfig 访问 Kubernetes。
请求与裁定
下面的请求表示 Alice 想在 default 创建 Deployment。示例使用 authorization.k8s.io/v1;其中 groups 是用户组列表,resourceAttributes 描述要执行的资源操作。非资源请求使用 nonResourceAttributes 提供路径与动词,字段定义见 SubjectAccessReview。
SubjectAccessReview 请求与响应
API Server 发送的请求体包含身份和操作,创建请求的 URL 中没有对象名称:
{
"apiVersion": "authorization.k8s.io/v1",
"kind": "SubjectAccessReview",
"spec": {
"user": "alice@example.com",
"groups": ["developers", "system:authenticated"],
"resourceAttributes": {
"namespace": "default",
"verb": "create",
"group": "apps",
"version": "v1",
"resource": "deployments"
}
}
}
外部服务正常完成判断后,在响应体的 status 中返回结果。例如,下面的响应明确拒绝请求,后续 RBAC 不再执行:
{
"apiVersion": "authorization.k8s.io/v1",
"kind": "SubjectAccessReview",
"status": {
"allowed": false,
"denied": true,
"reason": "Deployment creation is restricted by organization policy"
}
}
Webhook 在响应的 status 中返回裁定,字段定义见 SubjectAccessReviewStatus:
allowed:必填。true表示允许请求并结束鉴权链;false表示当前 Webhook 未允许请求。denied:可选,省略时为false。true表示明确拒绝请求并结束鉴权链,此时allowed必须为false。
只返回 allowed: false、省略 denied 时,表示当前 Webhook 无意见,继续由后续鉴权模块处理。
ABAC¶
ABAC(基于属性的访问控制)通过策略文件匹配用户名、用户组、API 组、资源、命名空间等属性。Kubernetes 的 ABAC 实现使用固定字段,匹配到任意一条允许策略就放行;它不提供显式拒绝规则。
策略文件
文件每行是一个独立 JSON 对象。下面的第一条策略允许 Alice 读取 default 中的 Pod,第二条允许她访问 /version:
{"apiVersion":"abac.authorization.kubernetes.io/v1beta1","kind":"Policy","spec":{"user":"alice@example.com","namespace":"default","resource":"pods","apiGroup":"","readonly":true}}
{"apiVersion":"abac.authorization.kubernetes.io/v1beta1","kind":"Policy","spec":{"user":"alice@example.com","nonResourcePath":"/version","readonly":true}}
user、group:与认证结果中的用户名或组名匹配。apiGroup、resource、namespace:匹配资源请求的范围,核心 API 组使用空字符串。nonResourcePath:匹配非资源请求路径,例如/version。readonly: true:资源请求仅允许get、list、watch,非资源请求仅允许get。省略或设为false时不再限制为只读。
API Server 配置
在 API Server 的启动参数中启用 ABAC 鉴权,并指定策略文件:
--authorization-mode=ABAC
--authorization-policy-file=/etc/kubernetes/authorization/abac-policy.jsonl
ABAC 在启动时加载策略文件,修改后需要重启各 API Server。文件格式与匹配规则见 Using ABAC Authorization。
ABAC 与 RBAC
主要区别:ABAC 在策略中直接组合身份条件和权限;RBAC 将权限定义与身份绑定分开管理,操作权限的划分也更细。
以允许 developers 组读取 default 命名空间中的 Pod 为例:
- ABAC:一条策略同时指定用户组
developers、命名空间default、资源pods和只读权限,身份条件与权限放在一起。 - RBAC:先创建
pod-readerRole,定义读取 Pod 的权限,再通过 RoleBinding 授予developers组。其他用户需要相同权限时,可以绑定同一个角色。
| 使用上的区别 | ABAC | RBAC |
|---|---|---|
| 权限组织 | 在策略中直接组合身份条件和权限 | 权限定义与身份绑定分开管理 |
| 操作粒度 | readonly: true 限制为只读;false 不限制操作动词 |
可以分别授予 get、create、patch、delete 等操作 |
| 修改权限 | 修改 API Server 上的策略文件,并重启加载 | 通过 Kubernetes API 更新角色或绑定,无需重启 API Server |
例如,允许用户修改 Deployment,但不授予删除权限时,RBAC 规则可以只配置 verbs: ["patch"],这条规则不会授予 delete 权限。内置 ABAC 的 readonly 无法区分这两种写操作。
AlwaysAllow¶
AlwaysAllow 对进入该模块的请求直接返回 Allow,仅适用于不需要权限限制的隔离测试环境。以下参数使普通鉴权链直接放行:
身份认证和准入控制仍会执行,但所有能通过认证的身份,包括启用匿名认证时的匿名用户,都不再受资源权限限制。
AlwaysDeny¶
AlwaysDeny 对进入该模块的请求直接返回 Deny,用于检查拒绝路径。单独启用时,经过普通鉴权链的请求会被拒绝:
鉴权链配置¶
启动参数 --authorization-mode 可以指定鉴权顺序,例如 --authorization-mode=Node,RBAC,ABAC 表示按 Node → RBAC → ABAC 的顺序执行。
AuthorizationConfiguration 通过 authorizers 列表指定顺序,还支持配置多个 Webhook、匹配条件、超时和失败处理策略。它通过 --authorization-config 加载,不能与 --authorization-mode 同时使用。
下面的配置按 Webhook、Node、RBAC 的顺序组成鉴权链。Webhook 只处理在 default 命名空间中创建 Deployment 的请求,其余请求跳过 Webhook,继续由后续模块鉴权:
Webhook、Node 与 RBAC 鉴权链
apiVersion: apiserver.config.k8s.io/v1
kind: AuthorizationConfiguration
authorizers:
- type: Webhook
name: deployment-policy
webhook:
authorizedTTL: 30s
unauthorizedTTL: 30s
timeout: 3s
subjectAccessReviewVersion: v1
matchConditionSubjectAccessReviewVersion: v1
failurePolicy: Deny
connectionInfo:
type: KubeConfigFile
kubeConfigFile: /etc/kubernetes/authorization/webhook.kubeconfig.yaml
matchConditions:
- expression: has(request.resourceAttributes)
- expression: request.resourceAttributes.namespace == 'default'
- expression: request.resourceAttributes.group == 'apps'
- expression: request.resourceAttributes.resource == 'deployments'
- expression: request.resourceAttributes.verb == 'create'
- type: Node
name: node
- type: RBAC
name: rbac
将鉴权链、连接配置和证书挂载到 API Server 可读取的位置后,设置:
以下参数位于 AuthorizationConfiguration 的 webhook 配置中:
matchConditions:所有条件都满足时才调用 Webhook;任一条件不满足就跳过。这里限定了资源、命名空间和动词。subjectAccessReviewVersion:指定远程服务的消息版本,此处显式使用v1。timeout:等待外部服务的最长时间,此处为 3 秒。failurePolicy: Deny:Webhook 调用失败或超时时拒绝请求。匹配条件判断出错时也会拒绝请求,但只要有一个条件不满足,就直接跳过 Webhook。Webhook 正常返回 NoOpinion 时,继续执行后续鉴权模块。authorizedTTL、unauthorizedTTL:分别缓存允许和非允许结果,此处都为 30 秒。未配置时默认分别为 5 分钟、30 秒;需要关闭缓存时使用cacheAuthorizedRequests: false或cacheUnauthorizedRequests: false。
这个例子把外部服务作为额外限制:策略不满足时返回 Deny,满足时返回 NoOpinion,让 RBAC 继续决定用户是否拥有创建权限。若外部服务直接返回 Allow,后续 RBAC 就不会执行。顺序设为 Node,RBAC,Webhook 时,RBAC 已经允许的请求同样不会再交给 Webhook。
权限检查¶
kubectl auth can-i 查询当前身份是否有某项权限:
# 检查是否能在 default 命名空间中创建 Deployment
kubectl auth can-i create deployments.apps -n default
# 检查是否能读取 default 命名空间中的 Pod 日志
kubectl auth can-i get pods --subresource=log -n default
# 检查是否能访问 /version 非资源端点
kubectl auth can-i get /version
使用 --as alice@example.com 检查该用户的权限时,操作者需要具有模拟该用户身份的权限。检查依赖用户组的策略时,可以通过 --as-group 指定要模拟的组。
准入控制¶
准入控制(Admission Control)位于授权之后、对象持久化之前,用于修改或校验请求中的对象。准入控制分为两类:
- Mutating Admission(修改型准入):可以修改请求对象,也可以根据策略拒绝请求。
- Validating Admission(校验型准入):根据对象内容和策略决定是否放行,不修改请求对象。
GET、LIST 和 WATCH 等读取操作直接绕过准入控制。
Mutating Admission 修改对象后,API Server 先检查资源自身的约束,再执行 Validating Admission 中的集群策略。任一准入插件拒绝请求,当前对象都不会写入 etcd。
准入阶段¶
准入控制分为修改和校验两个阶段。Mutating Admission 先修改或拒绝对象;通过修改阶段的对象再进入 Validating Admission。校验阶段保留对象内容,可以放行、拒绝、告警或记录审计信息;任一拒绝结果都会终止当前请求。
下图展示了请求经过变更准入和验证准入的主要流程。
图:Kubernetes Admission Control
Admission Controller 的执行顺序
一次请求可以匹配多个 Policy 和 Webhook,API Server 先完成变更阶段,再进入验证阶段。同类配置之间没有可配置的优先级,但单个 Policy 内部的规则按列表顺序执行。
- 阶段顺序:变更阶段首轮先执行匹配的
MutatingAdmissionPolicy,再执行 Mutating Webhook;验证阶段先执行ValidatingAdmissionPolicy,再执行 Validating Webhook。 - 多个 Policy 之间:没有可配置的优先级,也不保证彼此的先后顺序。
- 单个 Policy 内部:
MutatingAdmissionPolicy的spec.mutations按列表顺序执行修改;ValidatingAdmissionPolicy的spec.validations也按列表顺序执行校验。 - 多个 Webhook 之间:Mutating Webhook 串行调用,但不保证固定先后顺序;Validating Webhook 并行调用。两者均没有可配置的优先级。
- 重新调用:
MutatingAdmissionPolicy或 Mutating Webhook 配置reinvocationPolicy: IfNeeded后,对象被后续准入逻辑修改时,可能再次执行;Never表示不重新调用。
MutatingAdmissionPolicy¶
Kubernetes 提供 MutatingAdmissionPolicy。它在 API Server 进程内执行 CEL,使用 ApplyConfiguration 或 JSON Patch 修改对象,不需要部署 HTTPS Webhook。具体 API 和补丁类型见 Mutating Admission Policy。
CEL(Common Expression Language,通用表达式语言)用于编写条件判断和数据计算表达式,这里用于读取请求对象的字段并生成需要应用的修改内容。
配置示例:为 Deployment 添加注解
这组配置为 default 命名空间中新建的 Deployment 添加 admission.example.com/managed-by 注解。Policy 定义修改内容,Binding 激活 Policy,并用 namespaceSelector 限定生效范围。
apiVersion: admissionregistration.k8s.io/v1
kind: MutatingAdmissionPolicy
metadata:
name: add-managed-by-annotation.example.com
spec:
failurePolicy: Fail
reinvocationPolicy: Never
matchConstraints:
resourceRules:
# 这条 Policy 只修改新建的 apps/v1 Deployment。
- apiGroups: ["apps"]
apiVersions: ["v1"]
operations: ["CREATE"]
resources: ["deployments"]
mutations:
- patchType: ApplyConfiguration
applyConfiguration:
# ApplyConfiguration 合并目标 annotation,保留对象中已有的其他 annotation。
expression: >-
Object{
metadata: Object.metadata{
annotations: {
"admission.example.com/managed-by": "mutating-admission-policy"
}
}
}
---
apiVersion: admissionregistration.k8s.io/v1
kind: MutatingAdmissionPolicyBinding
metadata:
name: add-managed-by-annotation.example.com
spec:
# Policy 只有被 Binding 引用后才会执行。
policyName: add-managed-by-annotation.example.com
matchResources:
# Kubernetes 自动为 Namespace 添加这个不可变标签。
namespaceSelector:
matchLabels:
kubernetes.io/metadata.name: default
Mutating Webhook¶
MutatingAdmissionWebhook 根据 MutatingWebhookConfiguration 中的资源、操作、命名空间和对象选择器匹配请求,再按顺序调用外部 HTTPS Webhook。API Server 使用 AdmissionReview 发送请求;Webhook 可以返回 JSON Patch 修改对象,也可以拒绝请求。
配置示例:为 Pod 添加标签
这个示例只匹配 default 命名空间的 Pod 创建请求。API Server 调用 /mutate,Webhook 返回 JSON Patch,为 Pod 添加 admission.example.com/managed=true 标签。
配置中的连接信息需要与 Webhook 服务保持一致:
- Service:
clientConfig.service指向admission-demo/admission-webhook,Service 的 443 端口转发到程序监听的 8443 端口。 - CA:应用配置前,把
${CA_BUNDLE}替换为签发服务端证书的 PEM CA 证书经过 base64 编码后的内容。 - 服务端证书:SAN 包含
admission-webhook.admission-demo.svc,API Server 才能校验 Service 的身份。
apiVersion: admissionregistration.k8s.io/v1
kind: MutatingWebhookConfiguration
metadata:
name: pod-labeler.example.com
webhooks:
- name: pod-labeler.example.com
admissionReviewVersions: ["v1"]
sideEffects: None
failurePolicy: Fail
matchPolicy: Equivalent
reinvocationPolicy: IfNeeded
timeoutSeconds: 5
clientConfig:
service:
namespace: admission-demo
name: admission-webhook
path: /mutate
port: 443
# 注册前将占位符替换为 Secret 中的 base64 数据。
caBundle: "${CA_BUNDLE}"
namespaceSelector:
matchLabels:
kubernetes.io/metadata.name: default
rules:
# 只对 Pod CREATE 返回 JSON Patch,不处理后续 UPDATE。
- operations: ["CREATE"]
apiGroups: [""]
apiVersions: ["v1"]
resources: ["pods"]
scope: Namespaced
应用场景:Istio sidecar 自动注入
Istio 的 sidecar 模式会在加入网格的 Pod 中运行一个 istio-proxy 容器。这个容器基于 Envoy,接收重定向后的入站和出站 TCP 流量,并执行服务路由、负载均衡、重试、mTLS 和遥测采集。各 Pod 中的代理从 istiod 获取配置,共同组成 Istio 的数据面。流量重定向规则由 istio-init 或 Istio CNI 写入,具体方式取决于安装配置。详细的组件关系见 Istio Architecture。
自动注入发生在 Pod 的创建阶段。Istio 使用 MutatingWebhookConfiguration 注册 sidecar injector;API Server 根据 namespace 和 Pod label 匹配 Webhook,把 AdmissionReview 发送给 istiod。Webhook 返回的 JSON Patch 会在 PodSpec 中加入 istio-proxy、卷、环境变量和流量重定向所需的配置。直接创建的 Pod,以及由 ReplicaSet、StatefulSet、DaemonSet 或 Job 等控制器创建的 Pod,都按相同规则匹配。
运行下面的示例前,先按照 Install with Istioctl 安装 Istio。命令为 demo namespace 启用自动注入,再创建一个只有 NGINX 容器的 Pod:
kubectl create namespace demo
kubectl label namespace demo istio-injection=enabled --overwrite
kubectl run web \
--namespace demo \
--image nginx:1.27-alpine \
--port 80
kubectl wait \
--namespace demo \
--for=condition=Ready pod/web \
--timeout=120s
注入成功后,原本只有一个应用容器的 Pod 会显示 2/2,容器列表中包含 web 和 istio-proxy:
kubectl get pod web --namespace demo
kubectl get pod web \
--namespace demo \
-o jsonpath='{.spec.containers[*].name}{"\n"}'
Namespace label 只影响之后创建的 Pod。已有 Pod 需要重新创建,才能经过 sidecar injector。注入标签、revision label 和手动注入方式见 Installing the Sidecar。
ValidatingAdmissionPolicy¶
ValidatingAdmissionPolicy 让集群管理员用 CEL 校验提交给 Kubernetes API 的对象,例如要求对象包含指定标签、限制字段取值,或者检查多个字段之间的关系。校验在 API Server 进程内完成,不需要部署外部 Webhook。
Policy 定义匹配资源和 CEL 校验表达式,ValidatingAdmissionPolicyBinding 决定规则的生效范围与处理动作。Deny 拒绝请求,Warn 向客户端返回警告,Audit 为审计事件添加注解。
CEL 表达式可以读取 object、oldObject 和 request.userInfo 等请求信息。校验依赖镜像扫描结果或其他外部系统数据时,可以使用 Validating Webhook。
配置示例:Deployment 副本数规则
这组配置检查 default 命名空间中 Deployment 的创建和更新请求。Policy 使用 CEL 表达式 object.spec.replicas <= 5 限制副本数不超过 5;Binding 将规则应用于 default 命名空间,并通过 Deny 拒绝不符合要求的请求。
apiVersion: admissionregistration.k8s.io/v1
kind: ValidatingAdmissionPolicy
metadata:
name: deployment-replica-limit.example.com
spec:
failurePolicy: Fail
matchConstraints:
resourceRules:
# 创建和修改 Deployment 都需要重新校验副本数。
- apiGroups: ["apps"]
apiVersions: ["v1"]
operations: ["CREATE", "UPDATE"]
resources: ["deployments"]
validations:
# CEL 返回 false 时,Binding 中的 Deny 动作使 API Server 拒绝请求。
- expression: object.spec.replicas <= 5
message: Deployment replicas must not exceed 5
---
apiVersion: admissionregistration.k8s.io/v1
kind: ValidatingAdmissionPolicyBinding
metadata:
name: deployment-replica-limit.example.com
spec:
# Policy 定义校验内容,Binding 决定生效范围和失败动作。
policyName: deployment-replica-limit.example.com
validationActions: [Deny]
matchResources:
# 只校验 default 命名空间中的 Deployment。
namespaceSelector:
matchLabels:
kubernetes.io/metadata.name: default
Validating Webhook¶
ValidatingAdmissionWebhook 根据 ValidatingWebhookConfiguration 匹配请求,并行调用外部 HTTPS Webhook。Webhook 读取修改阶段生成的最终对象、userInfo 和请求信息,再返回允许或拒绝结果;对象修改由前面的 Mutating Admission 完成。
外部服务可以结合镜像仓库、漏洞扫描结果或其他系统状态执行校验。匹配规则、AdmissionReview 格式和 TLS 配置见 Dynamic Admission Control。
配置示例:Pod 安全字段校验
这个示例校验 default 命名空间中 Pod 的创建和更新请求。Webhook 检查 Pod 中容器的 securityContext.privileged 字段,任一容器设置为 true 时拒绝请求,否则允许请求。
apiVersion: admissionregistration.k8s.io/v1
kind: ValidatingWebhookConfiguration
metadata:
name: pod-security.example.com
webhooks:
- name: pod-security.example.com
admissionReviewVersions: ["v1"]
sideEffects: None
failurePolicy: Fail
matchPolicy: Equivalent
timeoutSeconds: 5
clientConfig:
service:
namespace: admission-demo
name: admission-webhook
path: /validate
port: 443
# API Server 使用这个 CA 校验 admission-webhook.admission-demo.svc 的证书。
caBundle: "${CA_BUNDLE}"
namespaceSelector:
matchLabels:
kubernetes.io/metadata.name: default
rules:
- operations: ["CREATE", "UPDATE"]
apiGroups: [""]
apiVersions: ["v1"]
resources: ["pods"]
scope: Namespaced
代码示例:Mutating 与 Validating Webhook
以下是 Mutating Webhook 和 Validating Webhook 的实现示例。Mutating Webhook 为 Pod 设置 admission.example.com/managed=true 标签;Validating Webhook 检查 Pod 中容器的 securityContext.privileged 字段,拒绝启用特权模式的请求。
服务入口
main.go 加载 TLS 证书,将两个路径分别绑定到 mutatePod 和 validatePod,共用 admissionHandler 处理 HTTP 请求。
package main
import (
"log"
"net/http"
"time"
)
func main() {
mux := newServeMux()
server := &http.Server{
Addr: ":8443",
Handler: mux,
ReadHeaderTimeout: 5 * time.Second,
}
log.Println("admission webhook listening on :8443")
// kube-apiserver 只调用 HTTPS Webhook;证书通常由 Secret 挂载到 /tls。
log.Fatal(server.ListenAndServeTLS("/tls/tls.crt", "/tls/tls.key"))
}
func newServeMux() *http.ServeMux {
mux := http.NewServeMux()
// 两个 WebhookConfiguration 使用不同 path,共用同一个 HTTPS 服务。
mux.Handle("/mutate", admissionHandler(mutatePod))
mux.Handle("/validate", admissionHandler(validatePod))
// HTTPS 健康检查不进入 AdmissionReview 解码逻辑。
mux.HandleFunc("/healthz", func(w http.ResponseWriter, _ *http.Request) {
w.WriteHeader(http.StatusOK)
})
return mux
}
公共请求处理
admissionHandler 解码 AdmissionReview,调用对应的处理函数,再补上请求 UID,以 JSON 格式返回响应。allowed() 和 denied() 分别构造允许和拒绝结果,供两个处理函数使用。
package main
import (
"encoding/json"
"fmt"
"log"
"mime"
"net/http"
admissionv1 "k8s.io/api/admission/v1"
metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
)
type admissionFunc func(*admissionv1.AdmissionRequest) admissionv1.AdmissionResponse
func admissionHandler(handle admissionFunc) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
if r.Method != http.MethodPost {
http.Error(w, "only POST is supported", http.StatusMethodNotAllowed)
return
}
mediaType, _, err := mime.ParseMediaType(r.Header.Get("Content-Type"))
if err != nil || mediaType != "application/json" {
http.Error(w, "Content-Type must be application/json", http.StatusUnsupportedMediaType)
return
}
var review admissionv1.AdmissionReview
// 限制请求体大小,避免异常请求占用过多内存。
body := http.MaxBytesReader(w, r.Body, 1<<20)
if err := json.NewDecoder(body).Decode(&review); err != nil {
http.Error(w, fmt.Sprintf("decode AdmissionReview: %v", err), http.StatusBadRequest)
return
}
if review.Request == nil {
http.Error(w, "AdmissionReview.request is required", http.StatusBadRequest)
return
}
// 根据路由注册时传入的函数,执行 mutatePod 或 validatePod。
response := handle(review.Request)
// AdmissionResponse 必须回显 request.uid,API Server 用它匹配请求和响应。
response.UID = review.Request.UID
responseReview := admissionv1.AdmissionReview{
TypeMeta: metav1.TypeMeta{
APIVersion: admissionv1.SchemeGroupVersion.String(),
Kind: "AdmissionReview",
},
Response: &response,
}
// 设置响应头,声明响应体为 JSON。
w.Header().Set("Content-Type", "application/json")
// 将 AdmissionReview 编码为 JSON 并写入响应体,未显式设置状态码时默认返回 HTTP 200。
// 是否允许请求由响应体中的 response.allowed 字段决定。
if err := json.NewEncoder(w).Encode(responseReview); err != nil {
log.Printf("encode AdmissionReview response: %v", err)
}
})
}
// 返回允许结果,不附带对象修改补丁。
func allowed() admissionv1.AdmissionResponse {
return admissionv1.AdmissionResponse{Allowed: true}
}
// 返回拒绝结果,并携带具体原因。
func denied(code int32, message string) admissionv1.AdmissionResponse {
return admissionv1.AdmissionResponse{
Allowed: false,
Result: &metav1.Status{
Code: code,
Message: message,
},
}
}
添加标签
mutatePod 返回 JSON Patch,将 admission.example.com/managed 标签设为字符串 "true";该标签的值已经为 "true" 时,直接允许请求,不再生成补丁。
package main
import (
"encoding/json"
"net/http"
admissionv1 "k8s.io/api/admission/v1"
corev1 "k8s.io/api/core/v1"
)
const managedLabel = "admission.example.com/managed"
type jsonPatchOperation struct {
Operation string `json:"op"`
Path string `json:"path"`
Value any `json:"value,omitempty"`
}
func mutatePod(request *admissionv1.AdmissionRequest) admissionv1.AdmissionResponse {
var pod corev1.Pod
if err := json.Unmarshal(request.Object.Raw, &pod); err != nil {
return denied(http.StatusBadRequest, "decode Pod: "+err.Error())
}
if pod.Labels[managedLabel] == "true" {
// reinvocationPolicy=IfNeeded 可能再次调用 Webhook,重复执行时不再生成补丁。
return allowed()
}
var patch jsonPatchOperation
if pod.Labels == nil {
// JSON Patch 不能向不存在的父路径添加子字段,先创建完整的 labels map。
patch = jsonPatchOperation{
Operation: "add",
Path: "/metadata/labels",
Value: map[string]string{managedLabel: "true"},
}
} else {
// JSON Pointer 用 ~1 表示 label key 中的斜杠。
patch = jsonPatchOperation{
Operation: "add",
Path: "/metadata/labels/admission.example.com~1managed",
Value: "true",
}
}
patchBytes, err := json.Marshal([]jsonPatchOperation{patch})
if err != nil {
return denied(http.StatusInternalServerError, "encode JSON Patch: "+err.Error())
}
patchType := admissionv1.PatchTypeJSONPatch
return admissionv1.AdmissionResponse{
Allowed: true,
PatchType: &patchType,
// Patch 保存原始 JSON 字节;外层 AdmissionReview 编码时会自动转换为 base64。
Patch: patchBytes,
}
}
校验特权模式
validatePod 检查容器的 securityContext.privileged。发现 true 时拒绝请求,并指出具体容器;全部通过时允许请求,保持对象内容不变。
package main
import (
"encoding/json"
"fmt"
"net/http"
admissionv1 "k8s.io/api/admission/v1"
corev1 "k8s.io/api/core/v1"
)
func validatePod(request *admissionv1.AdmissionRequest) admissionv1.AdmissionResponse {
var pod corev1.Pod
if err := json.Unmarshal(request.Object.Raw, &pod); err != nil {
return denied(http.StatusBadRequest, "decode Pod: "+err.Error())
}
for _, container := range pod.Spec.InitContainers {
if isPrivileged(container.SecurityContext) {
return denied(http.StatusForbidden, fmt.Sprintf("init container %q cannot be privileged", container.Name))
}
}
for _, container := range pod.Spec.Containers {
if isPrivileged(container.SecurityContext) {
return denied(http.StatusForbidden, fmt.Sprintf("container %q cannot be privileged", container.Name))
}
}
return allowed()
}
func isPrivileged(context *corev1.SecurityContext) bool {
// 未设置 privileged 与显式设置 false 都符合这条示例策略。
return context != nil && context.Privileged != nil && *context.Privileged
}
内置 Admission Controller¶
内置 Admission Controller 编译在 API Server 中。API Server 通过 --enable-admission-plugins 和 --disable-admission-plugins 管理这些插件。
常见插件包括:
- LimitRanger:根据命名空间中的
LimitRange补充默认资源请求,并校验资源上下限。 - ResourceQuota:检查本次写入是否超过命名空间的资源配额。
- PodSecurity:按照命名空间配置的 Pod Security Standards 执行
enforce、audit和warn。 - ServiceAccount:Pod 未指定
serviceAccountName时填入default,并校验引用的 ServiceAccount。 - NamespaceLifecycle:检查目标命名空间是否存在,拒绝在正在删除的命名空间中创建新对象,并保护
default、kube-system和kube-public命名空间不被删除。 - RuntimeClass:校验 Pod 引用的 RuntimeClass,并应用对应的 Pod 开销与调度约束。
- Priority:根据 Pod 的
priorityClassName查找 PriorityClass,将对应的优先级数值填入 Pod;引用的 PriorityClass 不存在时拒绝创建。 - DefaultTolerationSeconds:Pod 没有对应容忍配置时,为其补充针对
node.kubernetes.io/not-ready和node.kubernetes.io/unreachable污点的默认NoExecute容忍,避免节点短暂异常时立即驱逐 Pod。 - DefaultStorageClass:创建 PVC 时,若未指定
storageClassName,填入集群的默认 StorageClass;显式设置为""时保留空值。 - StorageObjectInUseProtection:为新建的 PVC 和 PV 添加保护性 finalizer,配合对应控制器,延迟删除仍被 Pod 使用的 PVC 或仍与 PVC 绑定的 PV。
- AlwaysPullImages:将新建 Pod 中容器的
imagePullPolicy设为Always,使容器启动前向镜像仓库检查镜像;访问私有镜像时需要有效的拉取凭据。 - NodeRestriction:限制 Kubelet 可以修改的 Node 和 Pod 对象范围。
完整的插件列表及各插件的作用、执行阶段和配置说明见 Admission Control in Kubernetes。
机制选择¶
根据是否需要修改对象、执行校验或调用外部服务,可以选择不同的处理机制:
| 需求 | 处理方式 |
|---|---|
| 命名空间级资源默认值、配额、Pod 安全和节点权限 | 内置 Admission Controller |
| 使用声明式规则修改对象 | MutatingAdmissionPolicy |
| 通过外部服务注入 sidecar 或补充动态配置 | Mutating Webhook |
| 使用声明式规则校验对象 | ValidatingAdmissionPolicy |
| 结合镜像扫描结果或其他外部数据校验对象 | Validating Webhook |
API 版本转换¶
API 升级可能改变字段名称、嵌套结构和默认值,而已有客户端仍可能使用旧版本,etcd 中也可能保留旧存储版本的对象。版本转换让同一资源以不同版本的结构供客户端读写,同时按当前存储版本写入 etcd。
这里以 modelservers.ai.course.example.com CRD 定义的 ModelServer 资源为例。它的 v1beta1 和 v1 都描述模型、副本数和 HTTP 端口,但字段位置不同:
| 语义 | v1beta1 |
v1 |
|---|---|---|
| 模型 | spec.modelRef |
spec.model.name |
| 副本数 | spec.scale.replicas |
spec.replicas |
| HTTP 端口 | spec.http.port |
spec.server.port |
当 CRD 的不同版本需要调整字段结构时,可以通过 Conversion Webhook 完成转换。API Server 将待转换对象和目标版本封装为 ConversionReview 发给 Webhook,再接收转换后的对象,协议格式见 Webhook request and response。
ConversionReview 请求与响应
下面的 CronTab 示例展示版本间的字段转换:将 example.com/v1beta1 的 hostPort 拆分为 example.com/v1 的 host 和 port。
请求
API Server 向 Webhook 发送 POST 请求,Content-Type 为 application/json。request.desiredAPIVersion 指定目标资源版本,request.objects 保存待转换对象:
{
"apiVersion": "apiextensions.k8s.io/v1",
"kind": "ConversionReview",
"request": {
"uid": "705ab4f5-6393-11e8-b7cc-42010a800002",
"desiredAPIVersion": "example.com/v1",
"objects": [
{
"kind": "CronTab",
"apiVersion": "example.com/v1beta1",
"metadata": {
"name": "local-crontab",
"namespace": "default",
"resourceVersion": "143",
"uid": "3415a7fc-162b-4300-b5da-fd6083580d66"
},
"hostPort": "localhost:1234"
}
]
}
}
响应
转换成功后,Webhook 返回 HTTP 200 和 JSON 响应,response.result.status 为 Success。response.uid 与请求中的 request.uid 一致,response.convertedObjects 返回转换后的对象:
{
"apiVersion": "apiextensions.k8s.io/v1",
"kind": "ConversionReview",
"response": {
"uid": "705ab4f5-6393-11e8-b7cc-42010a800002",
"result": {
"status": "Success"
},
"convertedObjects": [
{
"kind": "CronTab",
"apiVersion": "example.com/v1",
"metadata": {
"name": "local-crontab",
"namespace": "default",
"resourceVersion": "143",
"uid": "3415a7fc-162b-4300-b5da-fd6083580d66"
},
"host": "localhost",
"port": "1234"
}
]
}
}
- 协议版本与资源版本:外层
apiVersion: apiextensions.k8s.io/v1是ConversionReview的协议版本;对象中的apiVersion才是资源版本,此处从example.com/v1beta1变为example.com/v1。 - 对象标识与顺序:转换前后的
kind、metadata.uid、metadata.name和metadata.namespace必须保持一致。一次请求可以包含多个对象,响应中的对象数量与排列顺序必须与请求一致。
Hub 与 Spoke¶
一种直接的做法是为每两个版本编写双向转换函数,收到转换请求时,根据源版本和目标版本调用对应函数。只有两个版本时,这种方式比较简单;但每增加一个版本,都需要补齐它与已有各版本之间的双向转换。
controller-runtime 采用 Hub 与 Spoke 模型组织转换逻辑:选定一个版本作为 Hub,其他版本只实现与 Hub 之间的双向转换。
- Hub:各版本共同使用的转换中心,保存转换过程中需要表达的数据。
- Spoke:围绕 Hub 的其他版本,只需实现自身与 Hub 之间的双向转换。两个 Spoke 之间的转换经过 Hub 中转。
图:左侧各版本两两转换,右侧各 Spoke 只与 Hub 转换。图源:Hubs, spokes, and other wheel metaphors。
下图以 v1 为 Hub,展示 v2 与 v3 之间的转换:v2.ConvertTo() 先将对象转成 v1,再由 v3.ConvertFrom() 转成 v3;反向转换使用 v3.ConvertTo() 和 v2.ConvertFrom()。
图:Spoke 通过 ConvertTo() 转入 Hub,通过 ConvertFrom() 从 Hub 转出。图中 v1 同时承担 Hub 和存储版本。图源:Hubs, spokes, and other wheel metaphors。
CRD 在 spec.versions 中列出各个资源版本,通过以下两个字段指定对外提供的版本和存储版本:
served:设为true时,API Server 提供该版本的资源接口,客户端可以使用这个版本发起请求。多个版本可以同时设为true。storage:设为true时,API Server 使用该版本向 etcd 写入对象。一个 CRD 必须且只能有一个版本设为true。
Hub 类型¶
下图展示了 Hub 的三种设计方式。
图:三种 Hub 的设计模式对比。
- 非公开 CRD 版本:将一个 CRD 版本作为 Hub,并设置
served: false和storage: false,供 Webhook 在转换时作为中间类型。这个版本仍列在 CRD 的spec.versions中,但不对外提供资源接口。 - 公开 API 版本:直接选用一个对外提供的 API 版本作为 Hub,其他版本分别与它进行双向转换。图中的
v1既供客户端访问,也作为转换中心和存储版本。这是比较常见的做法。 - Webhook 内部类型:在 Webhook 中定义独立的内部 Go 类型,例如
internal.ModelServer,各个对外版本分别与它完成双向转换。这个类型不列入 CRD 的spec.versions,也没有对应的资源接口。
API 扩展机制¶
Kubernetes 提供两种 API 扩展方式:
- CRD(CustomResourceDefinition,自定义资源定义):用 YAML 声明资源名称、字段和校验规则后,API Server 就能处理这种资源的增删改查与 Watch 请求,并将对象保存到 etcd。用户通常还需要自行实现 Operator,监听自定义资源对象的变化,执行创建或调整工作负载等操作,并回写对象状态。
- API 聚合(API Aggregation):开发并部署独立的扩展 API Server,通过
APIService资源注册它提供的 API 组和版本。客户端仍访问 API Server,聚合层将匹配的 HTTP 请求转发给扩展 API Server,由它执行资源操作、访问数据并返回响应。扩展服务可以使用自己的数据库、内存缓存或其他 API 作为数据来源。
CRD¶
创建 CustomResourceDefinition(CRD)后,API Server 会按照其中的资源名称、API 组、版本和 schema 提供创建、读取、更新、删除及 Watch 接口。通过这些接口创建的对象称为 Custom Resource(CR),由 API Server 保存到 etcd。
资源类型定义
下面的 CRD 定义了 ModelServer 资源,用 spec 声明模型名称和期望副本数,用 status 记录实际副本数和 Pod 标签选择器。它启用 /status 和 /scale 子资源,分别用于状态回写和副本数读写。
apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
# CRD 名称必须为 <plural>.<group>。
name: modelservers.serving.course.example.com
spec:
group: serving.course.example.com # 自定义资源的 API 组。
scope: Namespaced # 每个 ModelServer 对象都属于一个命名空间。
names:
plural: modelservers # API 路径和 kubectl 命令使用的资源复数名。
singular: modelserver # kubectl 可使用的单数别名。
kind: ModelServer # 创建自定义资源时填写的 kind 值。
versions:
- name: v1 # 对象 apiVersion 中的版本号。
served: true # 启用此版本的 API 访问。
# 写入存储使用此版本;所有版本中恰有一个 storage 为 true。
storage: true
# 定义对象字段、校验规则和默认值。
schema:
openAPIV3Schema:
type: object
required: [spec] # 根对象必须包含 spec。
properties:
spec:
type: object
required: [model] # spec 必须包含 model。
properties:
model:
type: object
required: [name] # model 必须包含 name。
properties:
name:
type: string
minLength: 1 # 模型名称至少包含一个字符。
# 期望副本数,取值为 1 到 8。
replicas:
type: integer
format: int32
minimum: 1
maximum: 8
default: 1 # 省略 replicas 时补为 1。
status:
type: object
properties:
# 控制器报告的实际副本数。
replicas:
type: integer
format: int32
minimum: 0
# Pod 标签选择器字符串,例如 app=qwen-demo。
selector:
type: string
subresources:
status: {} # 启用 /status,供控制器独立更新状态。
# 启用 /scale,供 kubectl scale 和 HPA 使用。
scale:
specReplicasPath: .spec.replicas # 映射到 Scale.spec.replicas。
statusReplicasPath: .status.replicas # 映射到 Scale.status.replicas。
labelSelectorPath: .status.selector # 映射到 Scale.status.selector。
# kubectl get 的附加列,从 jsonPath 指定的对象字段取值。
additionalPrinterColumns:
- name: Model
type: string
jsonPath: .spec.model.name
- name: Desired
type: integer
jsonPath: .spec.replicas
- name: Current
type: integer
jsonPath: .status.replicas
字段含义与约束见 Extend the Kubernetes API with CustomResourceDefinitions。
自定义资源对象
注册上述 CRD 后,就可以创建 ModelServer 类型的自定义资源(CR)。下面的 qwen-demo 对象属于 default 命名空间,声明使用 Qwen/Qwen3-0.6B 模型,期望副本数为 1。
apiVersion: serving.course.example.com/v1 # 对应 CRD 中的 API 组与版本。
kind: ModelServer # 对应 CRD 中的 names.kind。
metadata:
name: qwen-demo
namespace: default
labels:
app: qwen-demo
spec:
model:
name: Qwen/Qwen3-0.6B # 模型名称,必须是非空字符串。
replicas: 1 # 期望副本数,取值为 1 到 8。
Operator 监听这类对象的变化,创建或调整工作负载并回写状态,具体机制见 Operator pattern。
API 聚合¶
API 聚合将独立的扩展 API Server 接入 Kubernetes API。Kubernetes API Aggregation Layer 运行在 API Server 进程内,根据 APIService 中的 API 组、版本和后端 Service 转发请求。扩展 API Server 负责处理请求、访问数据,再通过聚合层返回响应。
APIService 为一个 API 组和版本注册服务入口,名称采用 <version>.<group> 格式。对象自身属于 apiregistration.k8s.io/v1 API;它注册的组和版本分别写在 spec.group、spec.version 中,具体资源与操作由后端服务提供。
Metrics Server 通过 APIService 注册 metrics.k8s.io/v1beta1。聚合层将这个 API 组和版本的请求转发到 kube-system/metrics-server Service 的 443 端口:
apiVersion: v1
kind: Service
metadata:
name: metrics-server
namespace: kube-system
spec:
selector:
k8s-app: metrics-server
ports:
- name: https
port: 443
targetPort: https
protocol: TCP
appProtocol: https
---
apiVersion: apiregistration.k8s.io/v1
kind: APIService
metadata:
name: v1beta1.metrics.k8s.io
spec:
group: metrics.k8s.io
version: v1beta1
service:
name: metrics-server
namespace: kube-system
port: 443
insecureSkipTLSVerify: true
groupPriorityMinimum: 100
versionPriority: 100
spec.group与spec.version:让聚合层接管/apis/metrics.k8s.io/v1beta1下的请求。spec.service:指定后端 Service,端口默认是443。Service 通过k8s-app: metrics-server选择 Pod,targetPort: https对应容器的10250端口。groupPriorityMinimum:设置所属 API 组的最低发现优先级。同组有多个APIService时,取这些值中的最大值作为组优先级,数值越大越靠前。versionPriority:设置当前版本在所属 API 组中的发现优先级,数值越大越靠前。
扩展机制对比¶
| 功能 | 作用 | CRD | 聚合 API |
|---|---|---|---|
| 字段校验 | 防止用户写入错误数据,并允许 API 独立于客户端演进;多个客户端无法同步升级时尤其有用。 | 支持。多数规则可通过 OpenAPI v3.0 schema 声明,详见 Validation;Validation ratcheting 允许符合条件的未修改字段保留不满足新校验规则的旧值;其他校验可通过 Validating Webhook 实现。 | 支持,可实现任意校验逻辑。 |
| 默认值 | 为省略的字段补充取值,减少客户端配置,并便于增加新字段。 | 支持。可使用 schema 的 default 关键字,也可使用 Mutating Webhook;从 etcd 读取旧对象时不会执行 Mutating Webhook。 |
支持。 |
| 多版本 API | 通过多个 API 版本访问同一对象,便于逐步调整字段名称和结构;客户端版本可控时,兼容压力较小。 | 支持,可声明多个版本并配置转换 Webhook,详见 Versions in CustomResourceDefinitions。 | 支持。 |
| 自定义存储 | 使用不同性能特征的存储,例如时序数据库,或为敏感数据提供独立的存储与安全隔离。 | 不支持替换自定义资源的底层存储,对象由 API Server 保存到 etcd。 | 支持,可自行选择数据库或其他数据来源。 |
| 自定义业务逻辑 | 在资源操作中执行自定义检查或动作。 | 支持在准入阶段通过 Webhook 执行逻辑;对象保存后的持续协调由 Controller 完成。 | 支持,可定制创建、读取、更新和删除等操作的处理逻辑。 |
| Scale 子资源 | 使 HPA、PodDisruptionBudget 等机制能够获取或调整自定义工作负载的副本数。 | 支持 /scale。 |
支持。 |
| Status 子资源 | 允许用户修改 spec、Controller 修改 status,分别控制写权限;状态更新不递增 metadata.generation。 |
支持 /status。 |
支持。 |
| 其他子资源 | 在常规增删改查之外提供 logs、exec 等操作。 |
不支持任意自定义子资源。 | 支持。 |
| Strategic Merge Patch | 通过字段合并规则修改对象,适合客户端和服务端共同维护的对象;对应 application/strategic-merge-patch+json。 |
不支持。 | 支持。 |
| Protocol Buffers | 允许客户端使用 Protocol Buffers 编码访问资源。 | 不支持。 | 支持。 |
| OpenAPI Schema | 发布可动态获取的资源结构,供工具发现字段和类型,并支持字段校验。 | 支持,基于 CRD 的 OpenAPI v3.0 schema。 | 支持。 |
| 对象名称 | 约束资源实例的名称格式。 | 名称必须符合 DNS 子域名规则。 | 由扩展 API Server 定义名称校验规则。 |
CRD 和聚合 API 并不互斥,可以在同一个项目中配合使用。 项目可以通过 CRD 定义和保存资源对象,再通过聚合 API 提供额外的操作。KubeVirt 和 Karmada 都采用了这种方式:
- KubeVirt:通过 CRD 定义
VirtualMachine、VirtualMachineInstance等资源,保存虚拟机的配置和状态;通过聚合 API 提供控制台、VNC 等访问操作,由virt-api处理连接请求。两者的分工见 KubeVirt: Extending Kubernetes with CRDs for Virtualized Workloads。 - Karmada:通过 PropagationPolicy CRD 定义资源分发策略;通过聚合 API 提供
clusters/proxy子资源,由karmada-aggregated-apiserver将请求转发到成员集群。访问方式见 Aggregated Kubernetes API Endpoint。
核心源码¶
API Server 在启动时构建服务、注册资源路由,并启动 HTTPS 监听。请求到达后,先经过 HTTP 过滤器链,再由路由交给对应的处理函数,调用 REST Storage 完成资源操作并返回结果。
- 初始化和启动:构建配置,组装 CRD、内置资源和聚合 API 服务,启动 HTTPS 监听与后台任务。
- HTTP 过滤器链:在路由分发前完成请求信息解析、超时控制、认证、审计、流控和授权。
- API 路由注册:创建各资源的 REST Storage,按其支持的操作,将 HTTP 方法和资源路径绑定到处理函数。
- 请求处理:Handler 解码创建请求并执行变更准入,通用 Registry 的
Store完成资源校验、验证准入和存储操作,最后由 Handler 返回创建结果。
初始化和启动¶
API Server 启动时构建配置,依次创建 CRD、内置资源和聚合 API 三套服务。服务构建完成后,API Server 注册 OpenAPI、健康检查和就绪检查等所需的 HTTP 路由,随后启动 HTTPS 监听,并通过启动后钩子启动 Informer、控制器等后台任务。
相关代码位置如下:
cmd/kube-apiserver/app/
├── config.go # NewConfig 构建配置,Complete 补全服务配置
└── server.go # Run 启动入口,CreateServerChain 构建服务链
pkg/controlplane/
├── instance.go # 创建内置 API 服务,接收 CRD 服务作为委派目标
└── apiserver/aggregator.go # CreateAggregatorServer 创建最外层聚合服务
staging/src/k8s.io/
├── apiextensions-apiserver/pkg/apiserver/
│ └── apiserver.go # 创建 CRD 服务,安装自定义资源处理入口
├── kube-aggregator/pkg/apiserver/
│ └── apiserver.go # 创建聚合服务,准备聚合 OpenAPI 并启动通用服务
└── apiserver/pkg/
├── server/
│ ├── genericapiserver.go # 准备路由与检查,管理服务启动和关闭
│ ├── secure_serving.go # SecureServingInfo.Serve 启动 HTTPS 服务
│ └── hooks.go # RunPostStartHooks 启动各钩子对应的后台任务
└── util/notfoundhandler/
└── not_found_handler.go # 处理委派链末端仍未匹配路由的请求
服务构建与委派
CreateServerChain 按依赖顺序创建三个服务,每次把已经创建的服务作为下一层的委派目标:
- APIExtensionsServer:安装 CRD API,并处理自定义资源请求;请求在这一层仍未匹配到处理入口时,交给末端处理器,在路由初始化完成后返回
404 Not Found。 - KubeAPIServer:安装 Pod、Deployment 等内置资源 API;将 APIExtensionsServer 作为委派目标。
- APIAggregator:提供 API 聚合服务,根据
APIService配置将聚合 API 请求转发给对应的扩展 API Server;将 KubeAPIServer 作为委派目标,最终返回给进程入口。
服务按 APIExtensionsServer → KubeAPIServer → APIAggregator 的顺序构建。请求的委派方向与服务构建顺序相反:请求从最外层 APIAggregator 进入,需要委派时,依次交给 KubeAPIServer、APIExtensionsServer。
构造函数在创建服务时接收委派目标,并返回服务对象:
func CreateServerChain(config CompletedConfig) (*aggregatorapiserver.APIAggregator, error) {
notFoundHandler := notfoundhandler.New(
config.KubeAPIs.ControlPlane.Generic.Serializer,
genericapifilters.NoMuxAndDiscoveryIncompleteKey,
)
// 先创建委派链最内层的 CRD 服务。
apiExtensionsServer, err := config.ApiExtensions.New(
genericapiserver.NewEmptyDelegateWithCustomHandler(notFoundHandler),
)
...
crdAPIEnabled := config.ApiExtensions.GenericConfig.MergedResourceConfig.ResourceEnabled(
apiextensionsv1.SchemeGroupVersion.WithResource("customresourcedefinitions"),
)
// 内置资源服务把未接管的路径委派给 CRD 服务。
kubeAPIServer, err := config.KubeAPIs.New(apiExtensionsServer.GenericAPIServer)
...
// 聚合服务位于最外层,接收进程的请求入口。
aggregatorServer, err := controlplaneapiserver.CreateAggregatorServer(
config.Aggregator,
kubeAPIServer.ControlPlane.GenericAPIServer,
apiExtensionsServer.Informers.Apiextensions().V1().CustomResourceDefinitions(),
crdAPIEnabled,
apiVersionPriorities,
)
...
return aggregatorServer, nil
}
服务启动与初始化
Run 根据传入的选项构建配置并创建委派链,随后调用 PrepareRun 完成启动准备,再调用 Run 启动服务:
func Run(ctx context.Context, opts options.CompletedOptions) error {
...
config, err := NewConfig(opts)
...
completed, err := config.Complete()
...
server, err := CreateServerChain(completed)
...
// API 安装完成后,准备服务运行所需的路由和检查。
prepared, err := server.PrepareRun()
...
// 运行返回的最外层聚合服务。
return prepared.Run(ctx)
}
server.PrepareRun():准备路由与检查。聚合服务调用通用服务的PrepareRun,先递归准备委派目标,再安装 OpenAPI、healthz、livez和readyz;聚合服务随后准备聚合 OpenAPI。prepared.Run(ctx):调用通用服务的RunWithContext,由它组织服务启动,并在收到停止信号后关闭服务、清理资源。具体的启动工作由NonBlockingRunWithContext完成:先通过SecureServingInfo.Serve启动 HTTPS 服务,再调用RunPostStartHooks,在独立 goroutine 中执行各个钩子,启动 Informer、控制器等后台任务。
HTTP 过滤器链¶
请求进入资源路由前,先经过一组嵌套的 http.Handler,完成请求解析、超时控制、认证、审计、流控和授权。过滤器通过请求上下文传递信息,检查通过后调用下一层,拒绝请求时直接返回响应。
相关代码位置如下:
staging/src/k8s.io/apiserver/pkg/
├── server/
│ ├── config.go # DefaultBuildHandlerChain 由内到外包装过滤器
│ ├── handler.go # 将通过过滤器链的请求交给路由处理入口
│ └── filters/
│ ├── timeout.go # 处理普通请求超时,返回超时响应或中止连接
│ ├── priority-and-fairness.go # 执行 APF 流控,处理排队与拒绝
│ └── maxinflight.go # 未配置 APF 时,限制读请求和写请求的并发
└── endpoints/filters/
├── audit_init.go # 初始化审计上下文,设置请求的 Audit-ID
├── requestinfo.go # 解析资源与操作,将 RequestInfo 写入上下文
├── request_deadline.go # 结合服务端配置和 timeout 参数设置截止时间
├── authentication.go # 校验请求身份,保存用户信息并处理认证失败
├── authn_audit.go # 按审计策略记录认证失败请求
├── audit.go # 记录请求接收、响应完成等阶段的审计事件
├── impersonation/
│ ├── constrained_impersonation.go # 检查受约束的用户模拟,更新请求身份
│ └── impersonation.go # 未启用受约束用户模拟时,处理常规用户模拟
└── authorization.go # 检查当前身份的操作权限,拒绝时返回 403
下图展示了请求依次经过的主要 HTTP 过滤器,以及超时、认证失败、流控拒绝和授权拒绝时的处理分支。
请求执行顺序
WithAuditInit:初始化审计上下文,并设置Audit-ID,用于关联同一次请求在不同处理阶段产生的审计记录。WithRequestInfo:从 HTTP 方法和请求路径中解析操作、API 组、版本、资源、命名空间和对象名称,供后续过滤器使用。WithRequestDeadline:结合服务端超时配置和请求中的timeout参数,为非长时间运行请求设置截止时间。后续认证、排队和资源处理共用这一期限。WithTimeoutForNonLongRunningRequests:处理请求超时。超过期限且尚未发送响应、连接未被接管时,返回504 Gateway Timeout;响应已经开始时,中止连接或 HTTP/2 流。WithAuthentication:校验客户端凭据,将用户信息写入请求上下文。认证失败时进入WithFailedAuthenticationAudit,按审计配置记录失败请求,再返回401 Unauthorized。WithAudit:按审计策略记录请求接收、响应完成等阶段的事件。它包装后续处理过程,也能记录用户模拟、APF 或授权阶段拒绝请求的结果。WithConstrainedImpersonation:请求携带用户模拟信息时,检查调用者是否有权使用目标身份,通过后将模拟身份写入请求上下文,供后续 APF 和授权使用。未携带用户模拟信息时,直接进入下一层。WithPriorityAndFairness:按照请求所属的流和优先级控制并发。请求可能立即执行、进入队列或被拒绝;拒绝时返回429 Too Many Requests。WithAuthorization:根据当前用户和请求操作检查访问权限。授权通过后进入路由分发,拒绝时返回403 Forbidden。apiHandler:根据请求路径选择对应的处理入口,再由资源处理器、代理处理器等执行后续操作。
包装顺序与请求顺序
HTTP 过滤器链由 DefaultBuildHandlerChain 在 apiHandler 外逐层包装而成。构建时从内向外逐层包装,处理请求时从外向内依次执行。
func DefaultBuildHandlerChain(apiHandler http.Handler, c *Config) http.Handler {
// apiHandler 对应图中的路由分发入口,位于过滤器链最内层。
handler := apiHandler
...
// 检查当前用户的操作权限;拒绝时返回 403 Forbidden。
handler = genericapifilters.WithAuthorization(handler, c.Authorization.Authorizer, c.Serializer)
...
if c.FlowControl != nil {
// 取得请求工作量的默认估算配置。
workEstimatorCfg := flowcontrolrequest.DefaultWorkEstimatorConfig()
// 构造工作量估算器,供 APF 估算请求占用的并发席位。
requestWorkEstimator := flowcontrolrequest.NewWorkEstimator(
c.StorageObjectCountTracker.Get, c.FlowControl.GetInterestedWatchCount,
workEstimatorCfg, c.FlowControl.GetMaxSeats,
)
...
// 按流和优先级控制并发,决定放行、排队或返回 429 Too Many Requests。
handler = genericfilters.WithPriorityAndFairness(
handler, c.LongRunningFunc, c.FlowControl,
requestWorkEstimator, c.RequestTimeout/4,
)
...
}
...
if c.FeatureGate.Enabled(genericfeatures.ConstrainedImpersonation) {
// 请求携带用户模拟信息时,检查模拟权限并更新请求上下文中的身份。
handler = impersonation.WithConstrainedImpersonation(
handler, c.Authorization.Authorizer, c.Serializer,
)
...
}
...
// 按审计策略记录请求接收、响应完成等阶段的事件。
handler = genericapifilters.WithAudit(
handler, c.AuditBackend, c.AuditPolicyRuleEvaluator, c.LongRunningFunc,
)
...
// 构造返回 401 Unauthorized 的认证失败处理器。
failedHandler := genericapifilters.Unauthorized(c.Serializer)
// 在失败处理器外添加审计,按配置记录认证失败请求。
failedHandler = genericapifilters.WithFailedAuthenticationAudit(
failedHandler, c.AuditBackend, c.AuditPolicyRuleEvaluator,
)
...
// 校验客户端凭据并保存用户信息;认证失败时调用 failedHandler。
handler = genericapifilters.WithAuthentication(
handler, c.Authentication.Authenticator, failedHandler,
c.Authentication.APIAudiences, c.Authentication.RequestHeaderConfig,
)
...
// 控制非长时间运行请求的超时。
// 超时且未发送响应、连接未被接管时返回 504,否则中止连接或 HTTP/2 流。
handler = genericfilters.WithTimeoutForNonLongRunningRequests(handler, c.LongRunningFunc)
...
// 结合服务端配置和请求的 timeout 参数,设置非长时间运行请求的截止时间。
handler = genericapifilters.WithRequestDeadline(
handler, c.AuditBackend, c.AuditPolicyRuleEvaluator,
c.LongRunningFunc, c.Serializer, c.RequestTimeout,
)
...
// 解析 HTTP 方法和 URL,将资源、命名空间及操作等信息写入上下文。
handler = genericapifilters.WithRequestInfo(handler, c.RequestInfoResolver)
...
// 初始化审计上下文并设置 Audit-ID,关联同一次请求的各阶段审计记录。
handler = genericapifilters.WithAuditInit(handler)
// 返回最外层 Handler,作为请求进入过滤器链的入口。
return handler
}
API 路由注册¶
API Server 在启动时,将资源的操作实现注册为客户端可以调用的 HTTP API。注册过程需要准备资源的 REST Storage,确定请求方法和路径,再将它们与处理函数关联起来。这里以 Deployment 的创建操作为例,说明这三个步骤。
相关代码位置如下:
pkg/
├── controlplane/apiserver/apis.go # InstallAPIs 收集资源提供者并安装 API 组
└── registry/apps/
├── rest/storage_apps.go # 构建 apps 资源 Storage,按版本保存资源映射
└── deployment/storage/storage.go # 创建 Deployment 及其子资源的 REST 实现
staging/src/k8s.io/apiserver/pkg/
├── server/
│ ├── genericapiserver.go # 定义 APIGroupInfo,按组与版本安装资源路由
│ └── handler.go # 创建路由容器,按请求路径分派处理入口
├── endpoints/
│ ├── groupversion.go # InstallREST 组合版本前缀,注册资源与发现路由
│ └── installer.go # 检查 REST 接口,绑定 HTTP 方法、路径与处理函数
└── registry/rest/rest.go # 定义 Creater、Getter 等资源操作接口
下图以 Deployment 的创建操作为例,展示 InstallAPIs 如何调用 NewRESTStorage 构建 REST 实现,再将返回的资源映射交给 InstallAPIGroups 注册 POST 路由。客户端提交创建请求后,路由将请求交给与该 REST 实现关联的处理函数。
准备资源操作¶
API Server 要处理 Deployment 的创建、查询和更新请求,需要先准备这些操作的服务端实现。REST Storage 是提供资源操作的对象;Deployment 的 REST Storage 支持 Create、Get、Update 等方法。后续注册路由时,处理函数会保存这个对象,用它执行对应的资源操作。
deploymentstore.NewStorage 创建 Deployment 的 REST Storage,v1Storage 再将主资源的 Storage 登记到 "deployments" 下:
func (p StorageProvider) v1Storage(
apiResourceConfigSource serverstorage.APIResourceConfigSource,
restOptionsGetter generic.RESTOptionsGetter,
) (map[string]rest.Storage, error) {
storage := map[string]rest.Storage{}
if resource := "deployments"; apiResourceConfigSource.ResourceEnabled(
appsapiv1.SchemeGroupVersion.WithResource(resource),
) {
// 创建 Deployment 主资源及其子资源的 REST Storage。
deploymentStorage, err := deploymentstore.NewStorage(restOptionsGetter)
if err != nil {
return storage, err
}
// 登记主资源的 Storage,供路由注册时查找。
storage[resource] = deploymentStorage.Deployment
...
}
...
return storage, nil
}
NewRESTStorage 将这份资源映射保存到 apps 组的 APIGroupInfo 中,并按版本组织。"v1" 下可以同时登记 Deployment、StatefulSet、DaemonSet 等已启用资源,主资源和子资源各占一个映射项:
APIGroupInfo (apps)
└── VersionedResourcesStorageMap["v1"]
├── "deployments" → deploymentStorage.Deployment
├── "deployments/status" → deploymentStorage.Status
├── "deployments/scale" → deploymentStorage.Scale
├── "statefulsets" → statefulSetStorage.StatefulSet
├── "statefulsets/status" → statefulSetStorage.Status
├── "statefulsets/scale" → statefulSetStorage.Scale
├── "daemonsets" → daemonSetStorage
├── "daemonsets/status" → daemonSetStatusStorage
├── "replicasets" → replicaSetStorage.ReplicaSet
├── "replicasets/status" → replicaSetStorage.Status
├── "replicasets/scale" → replicaSetStorage.Scale
└── "controllerrevisions" → historyStorage
InstallAPIs 取得这份 APIGroupInfo,将它交给 InstallAPIGroups。资源映射把已经创建好的 Storage 对象传给路由注册流程,让后续代码能够找到每个资源对应的操作实现。
确定方法和路径¶
拿到 REST Storage 后,API Server 需要确定客户端通过什么路径、使用什么 HTTP 方法调用它。注册流程按 API 组、版本和资源逐层处理,最终将资源路径和对应的 Storage 交给 registerResourceHandlers:
InstallAPIGroups # 遍历 apps 等 API 组,将各组的 APIGroupInfo 交给 installAPIResources
↓
installAPIResources # 遍历 v1 等版本,将该版本的资源与 Storage 映射交给 InstallREST
↓
InstallREST # 设置 /apis/apps/v1 前缀,调用 APIInstaller.Install,完成后注册 WebService
↓
APIInstaller.Install # 逐项取出 deployments 等资源路径及其 Storage,交给 registerResourceHandlers
↓
registerResourceHandlers # 按 Storage 支持的操作,绑定 HTTP 方法、路径和处理函数,将路由加入 WebService
以 Deployment 的创建操作为例,注册所需的信息包括:
- API 组与版本:
apps/v1对应公共路径前缀/apis/apps/v1。 - 资源名称与作用域:资源名称是
deployments,Deployment 属于命名空间资源,因此路径中包含namespaces/{namespace}。 - 支持的操作:Deployment 的 REST Storage 实现了
rest.Creater,因此可以注册 POST 创建操作。
组合后得到完整的请求入口:
请求路径由资源信息确定,支持的操作由 Storage 实现的接口确定。注册其他操作时也使用相同机制,例如通过 rest.Getter 识别读取单个对象的能力,并注册对应的 GET 路由。
绑定处理函数与注册¶
registerResourceHandlers 根据资源路径和 REST Storage 注册对应的 HTTP 路由。对于创建操作,它调用 restfulCreateResource 构造创建请求的处理函数,让函数保存当前资源的 REST Storage、请求配置和准入接口,再将这个函数绑定到 POST 路由。
对于 Deployment,处理函数绑定的 REST Storage 是前面创建的 deploymentStorage.Deployment。路由根据 HTTP 方法和路径匹配请求,匹配成功后执行这个处理函数。处理函数通过通用创建逻辑,调用该 Storage 的 Create 方法。
下面保留 registerResourceHandlers 中检查创建能力、构造处理函数和添加路由的关键调用:
func (a *APIInstaller) registerResourceHandlers(
path string, storage rest.Storage, ws *restful.WebService,
) (*metav1.APIResource, *storageversion.ResourceInfo, error) {
...
// 检查 Storage 是否实现 rest.Creater 接口,即是否支持创建操作。
// 断言成功时,isCreater 为 true,creater 用于调用该 Storage 的 Create 方法。
// 对于 Deployment,creater 底层仍是前面创建的 deploymentStorage.Deployment。
creater, isCreater := storage.(rest.Creater)
...
// 支持创建时,为资源添加 POST 操作。
actions = appendIf(actions, action{
request.MethodPost, resourcePath, resourceParams, namer, false,
}, isCreater)
...
for _, action := range actions {
...
routes := []*restful.RouteBuilder{}
switch action.Verb {
...
case request.MethodPost:
var handler restful.RouteFunction
if isNamedCreater {
...
} else {
// Deployment 使用此分支,处理函数保存传入的 Storage。
handler = restfulCreateResource(creater, reqScope, admit)
}
...
// 将 HTTP 方法、资源路径与处理函数绑定。
route := ws.POST(action.Path).To(handler)
...
routes = append(routes, route)
...
}
for _, route := range routes {
...
// 将单条路由加入当前版本的 WebService。
ws.Route(route)
}
}
...
}
这里的 WebService 用于汇集同一 API 版本下的路由。APIInstaller.Install 完成各资源的路由构建后,将 WebService 返回给 InstallREST,后者通过 container.Add(ws) 将这些路由注册到服务的路由容器中,供请求到达后匹配:
func (g *APIGroupVersion) InstallREST(
container *restful.Container,
) ([]apidiscoveryv2.APIResourceDiscovery, []*storageversion.ResourceInfo, error) {
...
// 构建当前版本下各资源的路由,返回包含这些路由的 WebService。
apiResources, resourceInfos, ws, registrationErrors := installer.Install()
...
// 将整个 WebService 注册到路由容器。
container.Add(ws)
...
}
请求处理¶
请求通过 HTTP 过滤器链后,路由将它交给对应的资源处理函数。处理函数负责解析请求、调用 REST Storage 提供的资源操作,并将处理结果编码为 HTTP 响应。不同操作使用不同的处理函数;这里以创建 default/vllm-demo Deployment 为例,说明请求如何经过解码、准入和资源创建,最终返回结果。
相关代码位置如下:
pkg/registry/apps/deployment/storage/
└── storage.go # Deployment REST Storage 通过内嵌 Store 提供资源操作
staging/src/k8s.io/apiserver/pkg/
├── endpoints/
│ ├── installer.go # 构造路由处理函数,保存对应的 REST Storage
│ └── handlers/
│ ├── create.go # 解码创建请求,执行变更准入并调用创建接口
│ ├── get.go # 解析读取请求,调用资源的 Get 方法
│ ├── rest.go # 定义 RequestScope,限制请求体大小
│ ├── negotiation/negotiate.go # 根据请求头选择输入和输出格式
│ └── response.go # 转换资源对象并编码 HTTP 响应
├── admission/attributes.go # 保存准入检查需要的对象、用户和操作信息
└── registry/
├── rest/create.go # 构造验证准入回调
└── generic/registry/store.go # 执行资源校验、验证准入和存储操作
路由匹配¶
客户端创建 default/vllm-demo 时,将 Deployment 对象放入请求体,提交到以下路径:
前面的路由注册过程已经将这个 POST 路径关联到创建处理函数。请求匹配路由后,API Server 执行该函数,并使用注册时传入的 Deployment REST Storage。
这个关联保存在 restfulCreateResource 返回的闭包中。注册 Deployment 路由时,参数 r 对应 deploymentStorage.Deployment;返回的函数保留了这份 Storage 对象,请求到达后,将它与本次 HTTP 请求一起交给通用创建逻辑。
func restfulCreateResource(
r rest.Creater, scope handlers.RequestScope, admit admission.Interface,
) restful.RouteFunction {
// 保存当前资源的 Storage、请求配置和准入接口。
return func(req *restful.Request, res *restful.Response) {
// 请求匹配路由后,使用保存的 Storage 处理本次创建请求。
handlers.CreateResource(r, &scope, admit)(
res.ResponseWriter, req.Request,
)
}
}
handlers.CreateResource 通过 createHandler 构造 HTTP 处理函数。它负责创建请求共有的解码、准入和响应处理,具体资源的创建操作仍由传入的 REST Storage 提供。
GET 请求使用对应的读取处理函数。例如,读取 default/vllm-demo 时,GetResource 从路径中取得命名空间和名称,再调用 Storage 的 Get 方法。下面的对象解码和创建准入属于 POST 创建流程。
请求解码¶
创建处理函数收到的是 HTTP 请求,而 REST Storage 的创建方法需要接收资源对象。因此,API Server 需要把请求体中的 JSON、YAML 等数据,解码为服务端可以处理的 Go 对象。
创建 default/vllm-demo 时,请求中的信息分别来自:
- 请求路径:提供目标命名空间
default。创建路径中没有对象名称,vllm-demo来自请求体的metadata.name。 - 请求体:提供 Deployment 的资源内容,包括
apiVersion、kind、metadata和spec。 - 查询参数:提供本次操作的选项。例如,
dryRun=All表示执行服务端 dry-run;这些参数被解析为CreateOptions。
createHandler 根据 Content-Type 选择输入解码器,读取请求体,再完成对象解码和版本转换。以 apps/v1 Deployment 为例,解码器将客户端提交的数据转换为内部类型 *apps.Deployment,供后续准入和资源操作使用。
其中,r.New() 创建用于接收解码结果的空对象,DecoderToVersion 指定转换后的版本,decoder.Decode 执行实际解码:
func createHandler(
r rest.NamedCreater,
scope *RequestScope,
admit admission.Interface,
includeName bool,
) http.HandlerFunc {
return func(w http.ResponseWriter, req *http.Request) {
ctx := req.Context()
...
// 根据 Content-Type 选择 JSON、YAML 等输入格式的解码器。
s, err := negotiation.NegotiateInputSerializer(
req, false, scope.Serializer,
)
...
// 读取请求体,并限制允许读取的最大字节数。
body, err := limitedReadBodyWithRecordMetric(
ctx, req, scope.MaxRequestBodyBytes,
scope.Resource.GroupResource(), requestmetrics.Create,
)
...
// 将 URL 查询参数解析为本次创建操作的选项。
options := &metav1.CreateOptions{}
values := req.URL.Query()
if err := metainternalversionscheme.ParameterCodec.DecodeParameters(
values, scope.MetaGroupVersion, options,
); err != nil {
...
}
...
// 使用路由对应的资源类型补全缺省信息,并准备接收对象。
defaultGVK := scope.Kind
original := r.New()
// 根据 fieldValidation 选择普通或严格解码器。
validationDirective := fieldValidation(options.FieldValidation)
decodeSerializer := s.Serializer
if validationDirective == metav1.FieldValidationWarn ||
validationDirective == metav1.FieldValidationStrict {
decodeSerializer = s.StrictSerializer
}
// 将输入格式解码与 API 版本转换组合起来。
decoder := scope.Serializer.DecoderToVersion(
decodeSerializer, scope.HubGroupVersion,
)
// 将请求体转换为内部对象;Deployment 对应 *apps.Deployment。
obj, gvk, err := decoder.Decode(body, &defaultGVK, original)
...
}
}
解码得到的 obj 就是本次要创建的 Deployment 对象。Handler 随后取得对象名称,检查对象中的命名空间是否与请求路径一致,并清理不应由客户端指定的系统元数据。这些处理完成后,对象才进入创建准入流程。
准入控制¶
准入控制按照集群配置的规则检查创建请求,分为两个阶段:
- Mutating Admission:Handler 直接调用准入链的
Admit,允许插件修改对象,也可以拒绝请求。 - Validating Admission:Handler 将调用准入链
Validate的逻辑封装为回调,交给Store在资源准备与校验后执行,检查对象并决定是否允许请求。
准入插件需要根据对象内容、操作类型和调用者身份判断是否允许请求。admission.NewAttributesRecord 将这些信息组织成准入属性。例如,创建 default/vllm-demo 时,其中包含待创建的 Deployment 对象、CREATE 操作、default 命名空间和发起请求的用户。
Handler 先调用 mutatingAdmission.Admit 执行 Mutating Admission,允许插件修改对象或拒绝请求。通过后,再执行预先定义的 requestFunc(),发起资源创建。
requestFunc 调用 r.Create 时,会先通过 AdmissionToValidateObjectFunc 构造 Validating Admission 回调,再将回调与对象一起传入。对于 Deployment,该回调由 Store 在资源准备与校验完成后、写入存储之前执行。
func createHandler(
r rest.NamedCreater,
scope *RequestScope,
admit admission.Interface,
includeName bool,
) http.HandlerFunc {
return func(w http.ResponseWriter, req *http.Request) {
...
// 组织准入检查所需的信息,包括对象、目标资源、操作和调用者。
admissionAttributes := admission.NewAttributesRecord(
obj, nil, scope.Kind, namespace, name, scope.Resource,
scope.Subresource, admission.Create, options,
dryrun.IsDryRun(options.DryRun), userInfo,
)
// 保存资源创建调用,Handler 在 Mutating Admission 通过后执行 requestFunc()。
requestFunc := func() (runtime.Object, error) {
return r.Create(
ctx, name, obj,
// 构造 Validating Admission 回调,此处只传递函数。
// 由 Store 在资源准备与校验后调用。
rest.AdmissionToValidateObjectFunc(
admit, admissionAttributes, scope,
),
options,
)
}
...
result, err := finisher.FinishRequest(
ctx,
func() (runtime.Object, error) {
...
// 对需要处理 CREATE 请求的 Mutating Admission,直接调用 Admit。
// 插件可以修改对象或拒绝请求;返回错误时终止创建。
if mutatingAdmission, ok := admit.(admission.MutationInterface); ok &&
mutatingAdmission.Handles(admission.Create) {
if err := mutatingAdmission.Admit(
ctx, admissionAttributes, scope,
); err != nil {
return nil, err
}
}
...
// Mutating Admission 通过后,发起资源创建,传入对象和 Validating Admission 回调。
result, err := requestFunc()
...
return result, err
},
)
...
}
}
对于 Deployment,r.Create 最终进入通用 Registry 的 Store.Create。Store 先完成资源准备与校验,再执行传入的 Validating Admission 回调。该回调通过准入链的 Validate 检查处理后的对象;全部检查通过后,Store 才调用底层存储接口保存对象。
资源创建¶
Mutating Admission 通过后,Handler 执行预先定义的 requestFunc()。该函数调用 r.Create,传入待创建的对象、创建选项和 Validating Admission 回调。Deployment 的 REST Storage 内嵌了通用 Registry 提供的 Store,复用其创建逻辑,因此这次调用实际进入 Store.Create。
Deployment 的 REST 类型通过下面的内嵌字段获得 Store 的资源操作方法:
type REST struct {
// 复用通用 Registry 的 Create、Get、Update 等方法。
*genericregistry.Store
}
Store 提供以下主要资源操作方法,这里省略参数和方法体:
// 创建资源对象。
func (e *Store) Create(...) (runtime.Object, error) { ... }
// 按名称读取单个资源对象。
func (e *Store) Get(...) (runtime.Object, error) { ... }
// 列出符合标签、字段等筛选条件的资源对象。
func (e *Store) List(...) (runtime.Object, error) { ... }
// 监听符合筛选条件的资源对象,返回变化事件。
func (e *Store) Watch(...) (watch.Interface, error) { ... }
// 更新资源对象。
func (e *Store) Update(...) (runtime.Object, bool, error) { ... }
// 按名称删除单个资源对象。
func (e *Store) Delete(...) (runtime.Object, bool, error) { ... }
// 删除符合筛选条件的一组资源对象。
func (e *Store) DeleteCollection(...) (runtime.Object, error) { ... }
Store 先按 Deployment 的资源策略完成对象准备与校验,再执行 Validating Admission 回调,全部检查通过后才调用底层存储接口。资源策略检查 Deployment 自身的约束,例如副本数不能为负数;Validating Admission 检查集群配置的规则。创建完成后,Store 将结果返回给 Handler。
Store.Create 将本例的创建请求交给 Store.create。其中,BeforeCreate 执行资源策略,createValidation 接收 Handler 传入的 Validating Admission 回调,e.Storage.Create 调用底层存储:
func (e *Store) Create(
ctx context.Context, obj runtime.Object,
createValidation rest.ValidateObjectFunc, options *metav1.CreateOptions,
) (runtime.Object, error) {
...
// 本例已指定对象名称,进入通用创建流程。
return e.create(ctx, obj, createValidation, options)
}
func (e *Store) create(
ctx context.Context, obj runtime.Object,
createValidation rest.ValidateObjectFunc, options *metav1.CreateOptions,
) (runtime.Object, error) {
...
// 使用当前资源的 Strategy 完成对象准备与校验。
if err := rest.BeforeCreate(e.CreateStrategy, ctx, obj); err != nil {
return nil, err
}
// 本例的 createValidation 是 Handler 传入的 Validating Admission 回调,
// 通过准入链的 Validate 检查对象。
if createValidation != nil {
if err := createValidation(ctx, obj.DeepCopyObject()); err != nil {
return nil, err
}
}
...
out := e.NewFunc()
// 将对象交给存储层:普通请求写入 etcd,dry-run 请求仅返回模拟结果。
if err := e.Storage.Create(
ctx, key, obj, out, ttl, dryrun.IsDryRun(options.DryRun),
); err != nil {
...
return nil, err
}
...
// 返回创建结果,交给 Handler 生成 HTTP 响应。
return out, nil
}
响应返回¶
资源创建调用返回后,Handler 检查结果:失败时通过 scope.err 返回对应的错误响应;成功时使用 201 Created,并将返回的对象转换为请求对应的 API 版本,按协商的格式输出。例如,创建 apps/v1 Deployment 后,可以返回 JSON 格式的 apps/v1 Deployment 对象。
createHandler 中的 result 是资源创建流程返回的对象,outputMediaType 保存协商得到的响应格式:
func createHandler(
r rest.NamedCreater,
scope *RequestScope,
admit admission.Interface,
includeName bool,
) http.HandlerFunc {
return func(w http.ResponseWriter, req *http.Request) {
...
// 创建失败:将错误转换为对应的 HTTP 错误响应。
if err != nil {
...
scope.err(err, w, req)
return
}
// 创建成功:使用 201 Created 作为响应状态码。
code := http.StatusCreated
...
// 将 result 转换为响应所需的 API 版本,
// 按协商的格式编码,并写入 HTTP 响应。
transformResponseObject(
ctx, scope, req, w, code, outputMediaType, result,
)
}
}
普通创建请求返回 201 Created 时,Deployment 已写入 etcd。服务端 dry-run 请求也可以返回 201 Created,但只返回模拟创建的结果,不写入 etcd。
设计模式¶
API Server 源码中有一些值得我们在业务代码中借鉴的设计模式:
- 策略模式:资源创建流程将 Pod、ConfigMap 等资源的处理规则封装为独立策略。通用 Store 通过统一接口调用这些策略,复用创建流程。
- 装饰器模式:HTTP 请求处理链将认证、鉴权等功能封装为独立的 Handler 包装层。每一层保持相同的
http.Handler接口,可以按所需顺序组合。
策略模式¶
问题¶
订单结算需要将商品金额与运费相加,但不同配送方式采用的计费规则不同。例如,固定运费为 10 元,按重量计费为每千克 4 元。商品金额为 100 元、包裹重量为 3 千克时,两种方式的应付总额分别为 110 元和 112 元。
一种直接的实现是在 Checkout.Total(order, shippingMode) 中判断计费方式:fixed 分支取固定运费,weight 分支根据包裹重量计算运费,再统一与商品金额相加。下面的示例通过 switch 选择计费分支,不支持的计费方式返回错误:
package main
import "fmt"
// 金额以元为单位,重量以千克为单位。
type Order struct {
Subtotal int
Weight int
}
type Checkout struct{}
func (Checkout) Total(order Order, shippingMode string) (int, error) {
var shipping int
switch shippingMode {
case "fixed":
// 固定运费为 10 元。
shipping = 10
case "weight":
// 按包裹重量计费,每千克 4 元。
shipping = order.Weight * 4
default:
return 0, fmt.Errorf("unsupported shipping mode: %q", shippingMode)
}
// 两种计费方式共用求和步骤。
return order.Subtotal + shipping, nil
}
func main() {
order := Order{Subtotal: 100, Weight: 3}
checkout := Checkout{}
for _, mode := range []string{"fixed", "weight"} {
total, err := checkout.Total(order, mode)
if err != nil {
panic(err)
}
fmt.Printf("%s total: %d yuan\n", mode, total)
}
}
下图展示两种计费规则集中在同一个结算方法中的结构:
图:结算方法根据计费方式选择运费规则,再计算应付金额。
当业务增加按配送地区计费的规则时,就需要在这个方法中加入 region 分支,读取配送地区并计算对应运费。商品金额与运费相加的步骤保持一致,公共结算方法却需要随着计费规则的增加而修改。下图展示新增地区计费分支后,结算方法内部的变化:
图:地区计费作为新分支加入原有结算方法,公共求和步骤保持一致。
如果后续还要将按重量计费改为首重加续重,也需要修改这个方法中的重量分支。计费规则与公共结算流程写在一起,各项规则的扩展和调整都集中在同一处;当规则需要分别维护时,就需要将运费计算从结算流程中分离。
解决方案¶
策略模式(Strategy)是一种行为型设计模式,将完成同一项任务的不同算法或规则分别封装,通过统一接口供调用方使用。当业务流程相同、其中某一步需要采用不同规则时,可以将这一步抽成策略,由外部选择具体实现。
策略模式通常包含三个部分:
- 上下文(Context):使用策略的业务对象,保存当前策略并向它委托工作。例如,订单结算对象将订单传给运费策略,取得费用后继续结算。
- 策略接口(Strategy):约定这项工作的输入和输出。例如,
Calculate(order)接收订单并返回运费。 - 具体策略(Concrete Strategy):实现不同的规则。例如,固定运费策略返回固定金额,重量计费策略根据包裹重量计算费用。
下图展示订单结算对象、策略接口和具体实现之间的关系,以及使用重量计费策略时的结算流程:
图:Checkout 通过 ShippingStrategy 调用当前运费策略。
组装对象时,调用方选定计费规则并传入订单结算对象;执行结算时,结算对象调用已保存的策略。变化的是计费规则,结算流程依赖的接口保持一致。新增计费方式时,需要实现策略并更新选择或组装代码,使用策略的结算流程可以继续复用。
策略模式示例
固定运费和按重量计费分别实现 ShippingStrategy,Checkout.Total 调用传入的策略计算运费,再与商品金额相加。金额以元为单位,Weight 表示重量,单位为千克。
package main
import "fmt"
// 金额以元为单位,重量以千克为单位。
type Order struct {
Subtotal int
Weight int
}
// 策略接口:接收订单,返回运费。
type ShippingStrategy interface {
Calculate(order Order) int
}
// 固定运费策略。
type FixedShipping struct {
Fee int
}
func (s FixedShipping) Calculate(order Order) int {
return s.Fee
}
// 按重量计费策略。
type WeightShipping struct {
RatePerKG int
}
func (s WeightShipping) Calculate(order Order) int {
return order.Weight * s.RatePerKG
}
// 结算对象保存调用方传入的策略。
type Checkout struct {
Shipping ShippingStrategy
}
func (c Checkout) Total(order Order) int {
// 公共流程通过接口计算运费,再与商品金额相加。
return order.Subtotal + c.Shipping.Calculate(order)
}
func main() {
order := Order{Subtotal: 100, Weight: 3}
// 组装时选择策略,两次结算使用同一个 Total 方法。
fixed := Checkout{Shipping: FixedShipping{Fee: 10}}
weighted := Checkout{Shipping: WeightShipping{RatePerKG: 4}}
fmt.Printf("fixed total: %d yuan\n", fixed.Total(order))
fmt.Printf("weighted total: %d yuan\n", weighted.Total(order))
}
输出结果是:
API Server 示例¶
Pod 和 ConfigMap 的创建都要经过对象准备、字段校验和存储,但各自的资源规则不同。Pod 需要初始化运行状态,检查容器、卷等字段;ConfigMap 则需要检查配置键和数据大小。API Server 将这些规则封装为资源策略,由通用 Store 通过统一接口调用,复用同一套创建流程。
这里的 Store 指 genericregistry.Store,它提供多种资源共用的增删改查流程。RESTCreateStrategy 约定创建策略的方法,Pod 和 ConfigMap 分别实现这些方法。
相关代码位置如下:
pkg/
├── registry/core/
│ ├── pod/
│ │ ├── strategy.go # 实现 Pod 的对象准备与字段校验策略
│ │ └── storage/storage.go # NewStorage 创建 Store,注入 Pod 策略
│ └── configmap/
│ ├── strategy.go # 实现 ConfigMap 的对象准备与字段校验策略
│ └── storage/storage.go # NewREST 创建 Store,注入 ConfigMap 策略
└── apis/core/
├── validation/validation.go # 校验 Pod、ConfigMap 等资源的字段约束
└── helper/qos/qos.go # 读取或计算 Pod 的 QoS 类别
staging/src/k8s.io/apiserver/pkg/
├── registry/
│ ├── rest/create.go # 定义 RESTCreateStrategy,由 BeforeCreate 调用策略
│ └── generic/registry/
│ ├── store.go # 保存资源策略,串联策略调用、验证准入和存储
│ └── dryrun.go # 根据 dry-run 选项决定是否执行存储写入
└── storage/etcd3/store.go # 将资源对象写入 etcd
图:Pod 与 ConfigMap 通过统一策略接口复用创建流程。
策略接口¶
通用 Store 通过 RESTCreateStrategy 调用资源规则。其中,创建前的处理分为两个主要阶段:
PrepareForCreate:在校验前初始化或清理对象字段,例如将 Pod 的初始状态设为Pending。Validate:检查对象是否符合当前资源的字段约束,返回错误列表;列表非空时,创建流程终止。
接口还包含类型识别、名称生成、命名空间判断,以及警告和规范化等行为:
type RESTCreateStrategy interface {
// 识别对象类型;为使用 generateName 的对象生成名称。
runtime.ObjectTyper
names.NameGenerator
// 判断资源是否属于命名空间。
NamespaceScoped() bool
// 用于校验前的字段初始化或清理。
PrepareForCreate(ctx context.Context, obj runtime.Object)
// 检查资源约束,返回错误列表,不修改对象。
Validate(ctx context.Context, obj runtime.Object) field.ErrorList
// 校验通过后生成警告,再规范化对象。
WarningsOnCreate(ctx context.Context, obj runtime.Object) []string
Canonicalize(obj runtime.Object)
}
Store 的 CreateStrategy 字段类型是 rest.RESTCreateStrategy,用于保存当前资源的具体策略,供公共创建流程调用。
type Store struct {
...
// 保存实现了 RESTCreateStrategy 接口的具体资源策略。
CreateStrategy rest.RESTCreateStrategy
...
}
Pod 策略¶
Pod 使用 podStrategy 实现创建规则,包级变量 Strategy 保存其实例。PrepareForCreate 先通过类型断言 pod := obj.(*api.Pod) 取得 Pod 指针,再将 generation 设为 1,表示期望配置的初始版本。随后重建 status,将 phase 设为 Pending,填入用于资源管理和驱逐决策的 qosClass,其余状态字段清空。
完成对象准备后,Validate 根据 Pod 的 spec 和元数据生成校验选项,再调用 ValidatePodCreate 检查资源约束。这两个方法都由 podStrategy 提供:
type podStrategy struct {
runtime.ObjectTyper
names.NameGenerator
}
var Strategy = podStrategy{legacyscheme.Scheme, names.SimpleNameGenerator}
func (podStrategy) PrepareForCreate(ctx context.Context, obj runtime.Object) {
// 从通用接口中取得 Pod 指针,后续修改作用于同一对象。
pod := obj.(*api.Pod)
// 初始化期望状态版本。
pod.Generation = 1
// 重建服务端维护的初始状态。
pod.Status = api.PodStatus{
Phase: api.PodPending,
QOSClass: qos.GetPodQOS(pod),
}
podutil.DropDisabledPodFields(pod, nil)
// 省略调度门控、亲和性、拓扑分布约束和 AppArmor 兼容处理。
...
}
func (podStrategy) Validate(ctx context.Context, obj runtime.Object) field.ErrorList {
pod := obj.(*api.Pod)
opts := podutil.GetValidationOptionsFromPodSpecAndMeta(&pod.Spec, nil, &pod.ObjectMeta, nil)
opts.ResourceIsPod = true
return corevalidation.ValidatePodCreate(pod, opts)
}
ConfigMap 策略¶
ConfigMap 通过同一个接口接入创建流程,具体规则由 ConfigMap 包中的 strategy 类型实现。其 PrepareForCreate 先取得 *api.ConfigMap,再调用 dropDisabledFields。dropDisabledFields 在所引用版本中是空函数,因此这个版本的 PrepareForCreate 不修改对象。
之后,公共创建流程调用 Validate,由它调用 ValidateConfigMap,检查配置键是否合法、data 与 binaryData 是否包含同名键,以及数据值的总字节数是否超过 1 MiB:
type strategy struct {
runtime.ObjectTyper
names.NameGenerator
}
var Strategy = strategy{legacyscheme.Scheme, names.SimpleNameGenerator}
// 编译时检查 Strategy 是否满足创建策略接口。
var _ rest.RESTCreateStrategy = Strategy
func (strategy) PrepareForCreate(ctx context.Context, obj runtime.Object) {
configMap := obj.(*api.ConfigMap)
dropDisabledFields(configMap, nil)
}
func dropDisabledFields(configMap *api.ConfigMap, oldConfigMap *api.ConfigMap) {
}
func (strategy) Validate(ctx context.Context, obj runtime.Object) field.ErrorList {
cfg := obj.(*api.ConfigMap)
return validation.ValidateConfigMap(cfg)
}
策略注入¶
API Server 在初始化资源存储时,为 Pod 和 ConfigMap 分别创建独立的 Store 实例,再将各自的策略赋给 CreateStrategy 字段。
Pod 的 NewStorage 创建 Store,并将 Pod 的策略 registrypod.Strategy 保存到 CreateStrategy 字段:
func NewStorage(
optsGetter generic.RESTOptionsGetter,
k client.ConnectionInfoGetter,
proxyTransport http.RoundTripper,
podDisruptionBudgetClient policyclient.PodDisruptionBudgetsGetter,
authorizer authorizer.Authorizer,
) (PodStorage, error) {
// 创建 Store,配置 Pod 对象类型及对应的资源策略。
store := &genericregistry.Store{
NewFunc: func() runtime.Object { return &api.Pod{} },
CreateStrategy: registrypod.Strategy,
// 省略其他 Store 字段。
...
}
// 省略底层存储初始化、错误处理和子资源配置。
...
// 将 Store 包装为 Pod 的 REST 实现。
return PodStorage{
Pod: &REST{store, proxyTransport},
// 省略子资源的 REST 实现。
...
}, nil
}
ConfigMap 的 NewREST 创建独立的 Store,将 configmap.Strategy 保存到自己的 CreateStrategy 字段:
func NewREST(optsGetter generic.RESTOptionsGetter) (*REST, error) {
store := &genericregistry.Store{
NewFunc: func() runtime.Object { return &api.ConfigMap{} },
CreateStrategy: configmap.Strategy,
// 省略其他 Store 字段。
...
}
// 省略底层存储初始化和错误处理。
...
return &REST{store}, nil
}
两个实例共用 genericregistry.Store 的创建逻辑,CreateStrategy 中保存的具体值各不相同。请求进入对应资源的 Store 后,就会使用初始化时选定的策略。
公共创建流程¶
创建请求由 Store.Create 转交给 Store.create 处理,e 表示当前资源的 Store 实例。Store.create 先将 e.CreateStrategy 传给 rest.BeforeCreate 完成对象准备和校验,再按需执行 Handler 传入的验证准入回调,最后调用 e.Storage.Create 将对象交给存储层:
func (e *Store) create(
ctx context.Context, obj runtime.Object,
createValidation rest.ValidateObjectFunc, options *metav1.CreateOptions,
) (runtime.Object, error) {
// 省略系统元数据初始化和创建前钩子。
...
// Store 的策略字段在这里传给 BeforeCreate 的 strategy 参数。
if err := rest.BeforeCreate(e.CreateStrategy, ctx, obj); err != nil {
return nil, err
}
// 资源准备和校验通过后,执行 Handler 传入的验证准入回调。
if createValidation != nil {
if err := createValidation(ctx, obj.DeepCopyObject()); err != nil {
return nil, err
}
}
// 省略对象名称、存储键与 TTL 的计算。
...
// 创建接收结果的对象,调用底层存储。
out := e.NewFunc()
if err := e.Storage.Create(ctx, key, obj, out, ttl, dryrun.IsDryRun(options.DryRun)); err != nil {
// 省略错误转换与重名对象检查。
...
return nil, err
}
// 省略创建完成回调、创建后钩子与响应对象修饰。
...
return out, nil
}
BeforeCreate 的 strategy 参数接收的就是 e.CreateStrategy:Pod Store 传入 registrypod.Strategy,ConfigMap Store 传入 configmap.Strategy。函数先通过接口调用当前策略的 PrepareForCreate 和 Validate,再执行所有资源共用的元数据校验、警告生成和规范化。任一校验返回错误,函数都会提前返回:
func BeforeCreate(strategy RESTCreateStrategy, ctx context.Context, obj runtime.Object) error {
// 省略系统元数据、名称和命名空间检查。
...
// 调用当前资源的准备与校验方法。
strategy.PrepareForCreate(ctx, obj)
if errs := strategy.Validate(ctx, obj); len(errs) > 0 {
return errors.NewInvalid(kind.GroupKind(), objectMeta.GetName(), errs)
}
// 执行所有资源共用的元数据校验。
if errs := genericvalidation.ValidateObjectMetaAccessor(
objectMeta, strategy.NamespaceScoped(), validatePathSegment,
field.NewPath("metadata"),
); len(errs) > 0 {
return errors.NewInvalid(kind.GroupKind(), objectMeta.GetName(), errs)
}
for _, w := range strategy.WarningsOnCreate(ctx, obj) {
warning.AddWarning(ctx, "", w)
}
strategy.Canonicalize(obj)
return nil
}
装饰器模式¶
问题¶
一个通知库最初只提供邮件通知:应用调用 Notifier 的发送方法,将重要事件通知给指定的收件人。随着需求增加,用户希望通过 SMS、Facebook 或 Slack 接收消息,通知库便需要支持更多渠道。
一种实现方式是继承 Notifier,为 SMS、Facebook 和 Slack 分别创建子类,各自增加对应渠道的发送逻辑。调用方根据需要选择通知类:
图:每种通知渠道对应一个子类。来源:Decorator。
当用户要求同时使用多个渠道时,例如将一条重要告警同时发送到 SMS 和 Slack,单独的渠道子类就无法直接满足组合需求。如果继续通过继承实现,就需要增加 SMS + Slack、SMS + Facebook 等组合类型。新增一种渠道时,还要为它与已有渠道的不同组合继续创建子类,类的数量随组合不断增加。
图:通知渠道的组合越多,需要维护的子类也越多。来源:Decorator。
解决方案¶
装饰器模式(Decorator)是一种结构型设计模式,通过包装已有对象为它增加行为,同时保持对外接口一致。保留邮件通知的基础实现,将 SMS、Facebook 和 Slack 分别封装为装饰器,再按需要逐层包装,就能组合多个通知渠道。
每个装饰器保存一个内部通知器,先调用它完成已有的发送操作,再通过自己的渠道发送同一条消息。装饰器与内部通知器实现相同接口,因此可以继续包装另一层装饰器。调用方通过选择包装层组合渠道,仍然调用同一个 Send 方法发送消息。
原图中的 Notifier 是邮件通知基类。下面的 Go 示例用 Notifier 接口约定发送操作,由 EmailNotifier 实现邮件通知,各角色分别是:
- 组件接口(Component):
Notifier声明Send(message),基础通知器和装饰器都实现这个接口。 - 具体组件(Concrete Component):
EmailNotifier提供基础的邮件通知功能。 - 装饰器(Decorator):
SMSDecorator、FacebookDecorator和SlackDecorator通过Next Notifier字段保存内部通知器,调用它的Send后,再通过自己的渠道发送同一条消息。内部通知器可以是邮件通知器,也可以是另一层装饰器。
下图展示通知器接口、各渠道的实现,以及逐层包装后的调用关系:
图:通知装饰器通过同一接口组合多个发送渠道。
组装时,从 EmailNotifier 开始,依次包装 SMS、Facebook 和 Slack 装饰器。调用最外层的 Send 后,各层先通过 Next.Send 调用内部通知器;邮件发送完成后,调用逐层返回,继续发送 SMS、Facebook 和 Slack 通知。更换通知组合时,调整包装层即可,现有渠道的实现可以继续复用。
装饰器模式示例
EmailNotifier 实现邮件通知,三个装饰器分别增加 SMS、Facebook 和 Slack 通知。示例用终端输出模拟各渠道的发送操作。
package main
import "fmt"
// 基础对象与装饰器共同实现消息发送接口。
type Notifier interface {
Send(message string)
}
// 基础通知器用终端打印模拟邮件发送。
type EmailNotifier struct{}
func (EmailNotifier) Send(message string) {
fmt.Printf("email: %s\n", message)
}
// 每个装饰器先委托给内部对象,再用打印模拟新增渠道的发送。
type SMSDecorator struct {
Next Notifier
}
func (n SMSDecorator) Send(message string) {
n.Next.Send(message)
fmt.Printf("sms: %s\n", message)
}
type FacebookDecorator struct {
Next Notifier
}
func (n FacebookDecorator) Send(message string) {
n.Next.Send(message)
fmt.Printf("facebook: %s\n", message)
}
type SlackDecorator struct {
Next Notifier
}
func (n SlackDecorator) Send(message string) {
n.Next.Send(message)
fmt.Printf("slack: %s\n", message)
}
func main() {
var notifier Notifier = EmailNotifier{}
notifier = SMSDecorator{Next: notifier}
notifier = FacebookDecorator{Next: notifier}
notifier = SlackDecorator{Next: notifier}
// 从最外层调用,邮件发送后沿调用栈依次增加其他渠道。
notifier.Send("Hello, everyone!")
}
输出结果是:
API Server 示例¶
HTTP 请求到达资源处理函数前,需要经过认证和鉴权等检查。API Server 将这些检查封装为独立的 Handler 包装层,每层接收并返回 http.Handler,通过同一接口组合成请求处理链。认证层校验凭据并写入用户身份,鉴权层检查操作权限,通过检查后才调用内层 Handler。
这里的 http.Handler 是组件接口,资源处理 Handler 提供基础功能,认证、鉴权等过滤器增加检查行为。
相关代码位置如下:
staging/src/k8s.io/apiserver/pkg/
├── server/
│ └── config.go # 组装 Handler 处理链,确定各层的嵌套关系
└── endpoints/
├── filters/
│ ├── authentication.go # 包装认证逻辑,认证通过后调用内层 Handler
│ └── authorization.go # 包装鉴权逻辑,允许请求时调用内层 Handler
└── request/context.go # 将用户身份写入请求上下文,供后续处理读取
图:认证与鉴权通过 Handler 接口逐层包装、向内委托。
Handler 接口¶
API Server 使用 http.Handler 接口组织过滤器链,每一层都通过 ServeHTTP 方法处理请求。ServeHTTP 读取客户端请求,并通过 http.ResponseWriter 写回 HTTP 响应。编写过滤器时,可以将处理逻辑写成函数,再转换为 http.HandlerFunc 类型。这个类型提供了 ServeHTTP 方法,因此处理函数也能通过统一的 http.Handler 接口加入过滤器链。
HandlerFunc 是一个函数类型,同时实现了 ServeHTTP 方法。请求到达时,调用它的 ServeHTTP,就会通过 f(w, r) 执行对应的处理函数。类型转换本身不会执行处理逻辑,函数体在收到请求后才运行。
type Handler interface {
ServeHTTP(ResponseWriter, *Request)
}
type HandlerFunc func(ResponseWriter, *Request)
func (f HandlerFunc) ServeHTTP(w ResponseWriter, r *Request) {
f(w, r)
}
认证包装¶
认证层需要在资源处理之前确认请求身份。它调用认证器检查凭据,认证通过后将用户写入请求上下文,再调用内层 Handler;认证失败或发生错误时,交给失败处理器返回响应。
WithAuthentication 将内层 Handler 和认证配置传给 withAuthentication。后者返回 http.HandlerFunc,闭包保存的 handler 是内层处理器,auth 是认证器,failed 是失败处理器:
func withAuthentication(
handler http.Handler,
auth authenticator.Request,
failed http.Handler,
apiAuds authenticator.Audiences,
requestHeaderConfig *authenticatorfactory.RequestHeaderConfig,
metrics authenticationRecordMetricsFunc,
) http.Handler {
// 省略认证器检查和代理身份请求头配置。
...
return http.HandlerFunc(func(w http.ResponseWriter, req *http.Request) {
// 省略受众设置和计时。
...
resp, ok, err := auth.AuthenticateRequest(req)
// 省略认证耗时和指标记录。
...
if err != nil || !ok {
// 省略错误日志。
...
failed.ServeHTTP(w, req)
return
}
// 省略受众校验、认证头清理和连接处理。
...
// 保存认证得到的用户,再委托内层 Handler。
req = req.WithContext(genericapirequest.WithUser(req.Context(), resp.User))
handler.ServeHTTP(w, req)
})
}
这里的 WithUser 将用户放入请求上下文。req.WithContext 返回携带该上下文的新请求,内层 Handler 通过这个请求读取用户身份。
鉴权包装¶
鉴权层需要根据当前用户和请求属性判断是否允许操作。它从请求上下文读取用户、动词和资源等信息,交给鉴权器判断;得到允许结果后调用内层 Handler,其余情况返回错误响应。
WithAuthorization 调用内部的 withAuthorization 创建这一层。与认证包装相同,返回的闭包保存内层 handler,在检查通过时通过 ServeHTTP 委托调用:
func withAuthorization(
handler http.Handler,
a authorizer.Authorizer,
s runtime.NegotiatedSerializer,
metrics recordAuthorizationMetricsFunc,
) http.Handler {
// 省略鉴权器检查。
...
return http.HandlerFunc(func(w http.ResponseWriter, req *http.Request) {
ctx := req.Context()
// 省略开始计时。
...
attributes, err := GetAuthorizerAttributes(ctx)
if err != nil {
responsewriters.InternalError(w, req, err)
return
}
authorized, reason, err := a.Authorize(ctx, attributes)
// 省略鉴权耗时和指标记录。
...
if authorized == authorizer.DecisionAllow {
// 省略允许请求的审计注解。
...
handler.ServeHTTP(w, req)
return
}
if err != nil {
// 省略错误的审计注解。
...
responsewriters.InternalError(w, req, err)
return
}
// 省略拒绝日志和审计注解。
...
responsewriters.Forbidden(attributes, w, req, reason, s)
})
}
GetAuthorizerAttributes 负责从上下文组装鉴权属性。当前层通过时,handler.ServeHTTP 将请求继续传入;未获允许或获取鉴权属性失败时,包装层返回错误响应,不调用内层 Handler。
处理链组装¶
API Server 启动时,调用 DefaultBuildHandlerChain,将认证、鉴权等过滤器与资源处理 Handler 组装成请求处理链。请求到达后,依次经过这些过滤器,通过检查后进入资源处理逻辑。
组装时,先用鉴权层包装 apiHandler,再用认证层包装当前处理链;每次赋值都将 handler 更新为新的外层 Handler。
func DefaultBuildHandlerChain(apiHandler http.Handler, c *Config) http.Handler {
// 从资源处理 Handler 开始,由内向外逐层包装。
handler := apiHandler
// 省略请求统计包装。
...
// 包装鉴权 Handler:处理请求时检查权限,允许后调用内层 Handler。
handler = genericapifilters.WithAuthorization(
handler, c.Authorization.Authorizer, c.Serializer,
)
// 省略流控、身份模拟和审计等过滤器。
...
// 认证失败时,由这个 Handler 返回 401 Unauthorized。
failedHandler := genericapifilters.Unauthorized(c.Serializer)
// 省略失败请求审计和追踪配置。
...
// 包装认证 Handler:校验凭据并写入用户身份,通过后调用内层 Handler。
// 认证层后包装、位于外侧,因此请求先认证、再鉴权。
handler = genericapifilters.WithAuthentication(
handler, c.Authentication.Authenticator, failedHandler,
c.Authentication.APIAudiences, c.Authentication.RequestHeaderConfig,
)
// 省略超时、请求信息等外层过滤器。
...
return handler
}
后包装的 Handler 位于外层,请求先经过它。每个包装函数都保存传入的内层 Handler,因此外部变量 handler 更新后,已有的内层处理链仍然保留。
请求执行¶
请求先经过认证层,认证通过后将用户身份写入请求上下文,再进入鉴权层;鉴权允许后,最终调用资源处理 apiHandler。省略其他过滤器时,成功请求的调用顺序如下:
authnHandler.ServeHTTP(w, req) # 进入认证层
auth.AuthenticateRequest(req) # 校验凭据
WithUser → req.WithContext # 将用户身份放入请求上下文
handler.ServeHTTP(w, req) # 通过内层处理链进入鉴权层
a.Authorize(ctx, attributes) # 检查用户权限
handler.ServeHTTP(w, req) # 通过内层处理链进入资源处理 apiHandler
包装层可以在委托之前检查请求,也可以在内层调用返回后记录结果。认证或鉴权拒绝请求时,当前层写入错误响应并直接返回,资源处理 Handler 就不会执行。
HTTP 处理链示例
APIHandler 提供基础响应,WithAuthentication 和 WithAuthorization 分别增加认证、鉴权检查。固定令牌 demo-token 对应用户 alice,已认证用户只允许 GET;请求通过 httptest 在进程内执行。
package main
import (
"context"
"fmt"
"net/http"
"net/http/httptest"
"strings"
)
type User struct {
Name string
}
type userKey struct{}
// 认证装饰器保存内层 Handler,认证通过后传递用户身份并委托请求。
func WithAuthentication(handler http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, req *http.Request) {
// 演示简化:固定令牌代表用户 alice,省略真实认证器及令牌校验。
if req.Header.Get("Authorization") != "Bearer demo-token" {
fmt.Println("authn: rejected")
http.Error(w, "Unauthorized", http.StatusUnauthorized)
return
}
user := User{Name: "alice"}
fmt.Printf("authn: authenticated %s\n", user.Name)
req.Header.Del("Authorization")
ctx := context.WithValue(req.Context(), userKey{}, user)
handler.ServeHTTP(w, req.WithContext(ctx))
})
}
// 鉴权装饰器通过检查后调用内层 Handler,拒绝时直接返回响应。
func WithAuthorization(handler http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, req *http.Request) {
// 认证层必须先写入用户;顺序错误属于组装错误。
user := req.Context().Value(userKey{}).(User)
// 演示简化:已认证用户只能执行 GET。
if req.Method != http.MethodGet {
fmt.Printf("authz: denied %s %s\n", user.Name, req.Method)
http.Error(w, "Forbidden", http.StatusForbidden)
return
}
fmt.Printf("authz: allowed %s %s\n", user.Name, req.Method)
handler.ServeHTTP(w, req)
})
}
// 基础业务处理函数读取用户身份并生成响应。
func APIHandler(w http.ResponseWriter, req *http.Request) {
user := req.Context().Value(userKey{}).(User)
fmt.Println("handler: serving request")
fmt.Fprintf(w, "Hello, %s!\n", user.Name)
}
func main() {
var handler http.Handler = http.HandlerFunc(APIHandler)
// 后包装的认证层位于外侧,请求依次进入认证、授权、业务处理。
handler = WithAuthorization(handler)
handler = WithAuthentication(handler)
requests := []struct {
name string
method string
token string
}{
{"authenticated GET", http.MethodGet, "demo-token"},
{"unauthenticated GET", http.MethodGet, ""},
{"authenticated POST", http.MethodPost, "demo-token"},
}
for _, request := range requests {
fmt.Printf("\n%s\n", request.name)
req := httptest.NewRequest(request.method, "http://example.com/pods", nil)
if request.token != "" {
req.Header.Set("Authorization", "Bearer "+request.token)
}
// 直接调用处理链并记录响应,无需启动监听端口。
response := httptest.NewRecorder()
handler.ServeHTTP(response, req)
fmt.Printf("response: %d %s\n", response.Code, strings.TrimSpace(response.Body.String()))
}
}
输出结果是:
相关资料¶
- Kubernetes Components
- The Kubernetes API
- Kubernetes API Concepts
- Kubernetes API Reference Docs
- Controlling Access to the Kubernetes API
- Authenticating
- Service Accounts
- kubeconfig (v1)
- kube-apiserver Configuration (v1)
- Organizing Cluster Access Using kubeconfig Files
- Installing
- kubectl create token
- Authenticating with Bootstrap Tokens
- TLS bootstrapping
- kubeadm token
- kubeadm join
- Configure the Aggregation Layer
- Authorization
- Using RBAC Authorization
- Using Node Authorization
- Using ABAC Authorization
- SubjectAccessReview
- Admission Control in Kubernetes
- Dynamic Admission Control
- Mutating Admission Policy
- Validating Admission Policy
- Install the Istio CNI node agent
- Architecture
- Install with Istioctl
- Installing the Sidecar
- ValidatingPolicy
- Custom Resources
- Extend the Kubernetes API with CustomResourceDefinitions
- Versions in CustomResourceDefinitions
- Hubs, spokes, and other wheel metaphors
- Implementing conversion
- Operator pattern
- Kubernetes API Aggregation Layer
- KubeVirt: Extending Kubernetes with CRDs for Virtualized Workloads
- Aggregated Kubernetes API Endpoint
- Strategy
- Decorator
- http package
















