解決calico-apiserver認(rèn)證失敗問(wèn)題

更新時(shí)間：2025年09月24日 09:16:36 作者：CN-FuWei

文章解決Calico APIServer狀態(tài)異常和命名空間刪除報(bào)錯(cuò)問(wèn)題,指出需在三臺(tái)Master節(jié)點(diǎn)修改kube-apiserver的--requestheader-allowed-names參數(shù),允許aggregator CN,此參數(shù)控制聚合層代理連接的客戶端證書(shū)CN白名單

一、問(wèn)題現(xiàn)象

現(xiàn)象一：calico-apiserver狀態(tài)為False

# kubectl get apiservices.apiregistration.k8s.io
v3.projectcalico.org                calico-apiserver/calico-api   False (FailedDiscoveryCheck)   3d23h

# kubectl describe apiservices.apiregistration.k8s.io v3.projectcalico.org
...
Status:
  Conditions:
    Last Transition Time:  2025-08-21T08:35:54Z
    Message:               failing or missing response from https://172.19.226.198:5443/apis/projectcalico.org/v3: bad status from https://172.19.226.198:5443/apis/projectcalico.org/v3: 401
    Reason:                FailedDiscoveryCheck
    Status:                False
    Type:                  Available
Events:                    <none>

現(xiàn)象二：刪除命名空間報(bào)錯(cuò)

# kubectl describe ns mysql-test
Name:         mysql-test
Labels:       kubernetes.io/metadata.name=mysql-test
Annotations:  <none>
Status:       Terminating
Conditions:
  Type                                         Status  LastTransitionTime               Reason                  Message
  ----                                         ------  ------------------               ------                  -------
  NamespaceDeletionDiscoveryFailure            True    Sat, 23 Aug 2025 20:26:51 +0800  DiscoveryFailed         Discovery failed for some groups, 1 failing: unable to retrieve the complete list of server APIs: projectcalico.org/v3: stale GroupVersion discovery: projectcalico.org/v3
  NamespaceDeletionGroupVersionParsingFailure  False   Sat, 23 Aug 2025 20:26:51 +0800  ParsedGroupVersions     All legacy kube types successfully parsed
  NamespaceDeletionContentFailure              False   Sat, 23 Aug 2025 20:26:51 +0800  ContentDeleted          All content successfully deleted, may be waiting on finalization
  NamespaceContentRemaining                    False   Sat, 23 Aug 2025 20:26:52 +0800  ContentRemoved          All content successfully removed
  NamespaceFinalizersRemaining                 False   Sat, 23 Aug 2025 20:26:52 +0800  ContentHasNoFinalizers  All content-preserving finalizers finished

二、排查過(guò)程

# kubectl logs -n calico-apiserver calico-apiserver-xxx --timestamps
calico-apiserver Unable to authenticate the request" error="[x509: subject with cn=front-proxy-client is not in the allowed list, verifying certificate x509: certificate signed by unknown authority

三、解決方案

三臺(tái)master節(jié)點(diǎn)修改kube-apiserver配置：

#二進(jìn)制部署：
vim /usr/lib/systemd/system/kube-apiserver.service
#kubeadm部署：
vim /etc/kubernetes/manifests/kube-apiserver.yaml
---
#新增白名單
--requestheader-allowed-names=aggregator,front-proxy-client

檢查配置是否生效：

kubectl -n kube-system get cm extension-apiserver-authentication -o yaml|grep "requestheader-allowed-names"

四、問(wèn)題分析

工作流程：

簡(jiǎn)單來(lái)說(shuō)：

修改 --requestheader-allowed-names 參數(shù)是為了允許 Kubernetes 聚合層（API Server Aggregator）安全地代理你的請(qǐng)求到后續(xù)部署的擴(kuò)展 API Server，而 aggregator 這個(gè) CN（Common Name）正是這些擴(kuò)展 API Server 的客戶端證書(shū)必須包含的標(biāo)識(shí)。

例子：metrics.k8s.io (由 metrics-server 提供)、custom.metrics.k8s.io (由 Prometheus Adapter 提供)、v3.projectcalico.org (由 Calico API Server 提供)。
好處：用戶可以使用統(tǒng)一的 kubectl 工具和相同的認(rèn)證/授權(quán)機(jī)制來(lái)訪問(wèn)這些擴(kuò)展功能。
作用：這是一個(gè)安全白名單。它指定了在代理請(qǐng)求的 TLS 連接中，客戶端證書(shū)的 Common Name (CN) 字段必須是什么，主 API Server 才會(huì)接受并信任這個(gè)連接。
為什么是 aggregator：在二進(jìn)制部署中，我們通常為聚合層功能專門創(chuàng)建一個(gè)客戶端證書(shū)，這個(gè)證書(shū)的 CN（Common Name）字段通常就設(shè)置為 aggregator。因此，我們需要在 --requestheader-allowed-names 參數(shù)中明確允許這個(gè) CN。
如果不設(shè)置或設(shè)置錯(cuò)誤：即使客戶端證書(shū)由正確的 CA 簽發(fā)，但如果 CN 不在這個(gè)白名單中，主 API Server 也會(huì)拒絕代理連接，你會(huì)看到 403 Forbidden 錯(cuò)誤。