本頁說明如何解決使用 Google Kubernetes Engine (GKE) 時可能遇到的 400、401、403 和 404 錯誤。
問題:驗證和授權錯誤
連線至 GKE 叢集時,您可能會收到 HTTP 狀態碼為 401 (Unauthorized)
的驗證和授權錯誤。如果您嘗試從本機環境在 GKE 叢集中執行 kubectl
指令,就可能會發生這個問題。
這個問題可能是下列原因所致:
gke-gcloud-auth-plugin
驗證外掛程式未正確安裝或設定。- 您沒有連線至叢集 API 伺服器及執行
kubectl
指令的權限。
如要診斷原因,請完成下列各節的步驟:
使用 curl
連線至叢集
如要診斷驗證和授權錯誤的原因,請使用 curl
連線至叢集。使用 curl
會略過 kubectl
指令列工具和 gke-gcloud-auth-plugin
外掛程式。
設定環境變數:
APISERVER=https://$(gcloud container clusters describe CLUSTER_NAME \ --location=COMPUTE_LOCATION --format "value(endpoint)") TOKEN=$(gcloud auth print-access-token)
確認存取權杖是否有效:
curl https://oauth2.googleapis.com/tokeninfo?access_token=$TOKEN
取得有效存取權杖後,這項指令會向 Google 的 OAuth 2.0 伺服器傳送要求,伺服器則會傳回權杖相關資訊。
嘗試連線至 API 伺服器中的核心 API 端點:
# Get cluster CA certificate gcloud container clusters describe CLUSTER_NAME \ --location=COMPUTE_LOCATION \ --format "value(masterAuth.clusterCaCertificate)" | \ base64 -d > /tmp/ca.crt # Make API call with authentication and CA certificate curl -s -X GET "${APISERVER}/api/v1/namespaces" \ --header "Authorization: Bearer $TOKEN" \ --cacert /tmp/ca.crt
如果
curl
指令成功,您會看到命名空間清單。請按照「在 kubeconfig 中設定外掛程式」一節的步驟,檢查外掛程式是否為造成問題的原因。如果
curl
指令失敗,且輸出內容類似下方範例,表示您沒有存取叢集的正確權限:{ "kind": "Status", "apiVersion": "v1", "metadata": {}, "status": "Failure", "message": "Unauthorized", "reason": "Unauthorized", "code": 401 }
如要解決這個問題,請洽詢管理員,取得叢集的正確存取權。
在 kubeconfig 中設定外掛程式的使用方式
如果在連線至叢集時發生驗證和授權錯誤,但可以使用 curl
連線至叢集,請確認您不需要 gke-gcloud-auth-plugin
外掛程式,即可存取叢集。
如要解決這個問題,請設定本機環境,在向叢集驗證時忽略 gke-gcloud-auth-plugin
二進位檔。在執行 1.25 以上版本的 Kubernetes 用戶端中,gke-gcloud-auth-plugin
二進位檔為必要項目,因此您需要使用 1.24 以下版本的 kubectl
指令列工具。
按照下列步驟操作,即可存取叢集,不必使用外掛程式:
使用
curl
安裝 1.24 以下版本的kubectl
指令列工具。以下範例會安裝 1.24 版的工具:curl -LO https://dl.k8s.io/release/v1.24.0/bin/linux/amd64/kubectl
在文字編輯器中開啟 Shell 啟動指令碼檔案。例如,開啟 Bash 殼層的
.bashrc
:vi ~/.bashrc
如果您使用 macOS,請按照這些操作說明,以
~/.bash_profile
取代.bashrc
。在啟動指令碼檔案中新增下列這行文字,然後儲存:
export USE_GKE_GCLOUD_AUTH_PLUGIN=False
執行開機指令碼:
source ~/.bashrc
取得叢集憑證,這會設定
.kube/config
檔案:gcloud container clusters get-credentials CLUSTER_NAME \ --location=COMPUTE_LOCATION
更改下列內容:
CLUSTER_NAME
:叢集名稱。COMPUTE_LOCATION
: Compute Engine 位置。
執行
kubectl
指令。例如:kubectl cluster-info
執行這些指令後,如果收到 401 錯誤或類似的授權錯誤,請確認您具備正確的權限,然後重新執行傳回錯誤的步驟。
錯誤 400:節點集區需要重新建立
嘗試執行會重建控制平面和節點的動作時,可能會發生下列錯誤:
ERROR: (gcloud.container.clusters.update) ResponseError: code=400, message=Node pool "test-pool-1" requires recreation.
舉例來說,如果您完成進行中的憑證輪替,就可能發生這項錯誤。
在後端,節點集區會標示為重新建立,但實際的重新建立作業可能需要一段時間才會開始。因此,由於 GKE 尚未在叢集中重建一或多個節點集區,作業會失敗。
如要解決這個問題,請選擇下列任一解決方案:
- 等待重新建立完成。視現有維護期間和排除時段等因素而定,這項作業可能需要數小時、數天或數週。
手動啟動版本升級,升級至與控制層相同的版本,重新建立受影響的節點集區。
如要開始重建,請執行下列指令:
gcloud container clusters upgrade CLUSTER_NAME \ --node-pool=POOL_NAME
升級完成後,請再次嘗試操作。
錯誤 401:未授權
找出節點服務帳戶缺少重要權限的叢集
如要找出缺少重要權限的節點服務帳戶叢集,請使用 NODE_SA_MISSING_PERMISSIONS
recommender 子類型的 GKE 建議:
- 使用 Google Cloud 控制台。前往「Kubernetes clusters」(Kubernetes 叢集) 頁面,並在特定叢集的「Notifications」(通知) 欄中,查看「Grant critical permissions」(授予重要權限) 建議。
使用 gcloud CLI 或 Recommender API,並指定
NODE_SA_MISSING_PERMISSIONS
推薦子類型。如要查詢建議,請執行下列指令:
gcloud recommender recommendations list \ --recommender=google.container.DiagnosisRecommender \ --location LOCATION \ --project PROJECT_ID \ --format yaml \ --filter="recommenderSubtype:NODE_SA_MISSING_PERMISSIONS"
請注意,建議最多可能需要 24 小時才會顯示。如需詳細操作說明,請參閱這篇文章,瞭解如何查看洞察資料和建議。
如要實作這項建議,請將 roles/container.defaultNodeServiceAccount
角色授予節點的服務帳戶。
您可以執行指令碼,在專案的 Standard 和 Autopilot 叢集中搜尋任何沒有 GKE 必要權限的節點服務帳戶。這個指令碼會使用 gcloud CLI 和 jq
公用程式。如要查看指令碼,請展開下列章節:
查看指令碼
#!/bin/bash
# Set your project ID
project_id=PROJECT_ID
project_number=$(gcloud projects describe "$project_id" --format="value(projectNumber)")
declare -a all_service_accounts
declare -a sa_missing_permissions
# Function to check if a service account has a specific permission
# $1: project_id
# $2: service_account
# $3: permission
service_account_has_permission() {
local project_id="$1"
local service_account="$2"
local permission="$3"
local roles=$(gcloud projects get-iam-policy "$project_id" \
--flatten="bindings[].members" \
--format="table[no-heading](bindings.role)" \
--filter="bindings.members:\"$service_account\"")
for role in $roles; do
if role_has_permission "$role" "$permission"; then
echo "Yes" # Has permission
return
fi
done
echo "No" # Does not have permission
}
# Function to check if a role has the specific permission
# $1: role
# $2: permission
role_has_permission() {
local role="$1"
local permission="$2"
gcloud iam roles describe "$role" --format="json" | \
jq -r ".includedPermissions" | \
grep -q "$permission"
}
# Function to add $1 into the service account array all_service_accounts
# $1: service account
add_service_account() {
local service_account="$1"
all_service_accounts+=( ${service_account} )
}
# Function to add service accounts into the global array all_service_accounts for a Standard GKE cluster
# $1: project_id
# $2: location
# $3: cluster_name
add_service_accounts_for_standard() {
local project_id="$1"
local cluster_location="$2"
local cluster_name="$3"
while read nodepool; do
nodepool_name=$(echo "$nodepool" | awk '{print $1}')
if [[ "$nodepool_name" == "" ]]; then
# skip the empty line which is from running `gcloud container node-pools list` in GCP console
continue
fi
while read nodepool_details; do
service_account=$(echo "$nodepool_details" | awk '{print $1}')
if [[ "$service_account" == "default" ]]; then
service_account="${project_number}-compute@developer.gserviceaccount.com"
fi
if [[ -n "$service_account" ]]; then
printf "%-60s| %-40s| %-40s| %-10s| %-20s\n" $service_account $project_id $cluster_name $cluster_location $nodepool_name
add_service_account "${service_account}"
else
echo "cannot find service account for node pool $project_id\t$cluster_name\t$cluster_location\t$nodepool_details"
fi
done <<< "$(gcloud container node-pools describe "$nodepool_name" --cluster "$cluster_name" --zone "$cluster_location" --project "$project_id" --format="table[no-heading](config.serviceAccount)")"
done <<< "$(gcloud container node-pools list --cluster "$cluster_name" --zone "$cluster_location" --project "$project_id" --format="table[no-heading](name)")"
}
# Function to add service accounts into the global array all_service_accounts for an Autopilot GKE cluster
# Autopilot cluster only has one node service account.
# $1: project_id
# $2: location
# $3: cluster_name
add_service_account_for_autopilot(){
local project_id="$1"
local cluster_location="$2"
local cluster_name="$3"
while read service_account; do
if [[ "$service_account" == "default" ]]; then
service_account="${project_number}-compute@developer.gserviceaccount.com"
fi
if [[ -n "$service_account" ]]; then
printf "%-60s| %-40s| %-40s| %-10s| %-20s\n" $service_account $project_id $cluster_name $cluster_location $nodepool_name
add_service_account "${service_account}"
else
echo "cannot find service account" for cluster "$project_id\t$cluster_name\t$cluster_location\t"
fi
done <<< "$(gcloud container clusters describe "$cluster_name" --location "$cluster_location" --project "$project_id" --format="table[no-heading](autoscaling.autoprovisioningNodePoolDefaults.serviceAccount)")"
}
# Function to check whether the cluster is an Autopilot cluster or not
# $1: project_id
# $2: location
# $3: cluster_name
is_autopilot_cluster() {
local project_id="$1"
local cluster_location="$2"
local cluster_name="$3"
autopilot=$(gcloud container clusters describe "$cluster_name" --location "$cluster_location" --format="table[no-heading](autopilot.enabled)")
echo "$autopilot"
}
echo "--- 1. List all service accounts in all GKE node pools"
printf "%-60s| %-40s| %-40s| %-10s| %-20s\n" "service_account" "project_id" "cluster_name" "cluster_location" "nodepool_name"
while read cluster; do
cluster_name=$(echo "$cluster" | awk '{print $1}')
cluster_location=$(echo "$cluster" | awk '{print $2}')
# how to find a cluster is a Standard cluster or an Autopilot cluster
autopilot=$(is_autopilot_cluster "$project_id" "$cluster_location" "$cluster_name")
if [[ "$autopilot" == "True" ]]; then
add_service_account_for_autopilot "$project_id" "$cluster_location" "$cluster_name"
else
add_service_accounts_for_standard "$project_id" "$cluster_location" "$cluster_name"
fi
done <<< "$(gcloud container clusters list --project "$project_id" --format="value(name,location)")"
echo "--- 2. Check if service accounts have permissions"
unique_service_accounts=($(echo "${all_service_accounts[@]}" | tr ' ' '\n' | sort -u | tr '\n' ' '))
echo "Service accounts: ${unique_service_accounts[@]}"
printf "%-60s| %-40s| %-40s| %-20s\n" "service_account" "has_logging_permission" "has_monitoring_permission" "has_performance_hpa_metric_write_permission"
for sa in "${unique_service_accounts[@]}"; do
logging_permission=$(service_account_has_permission "$project_id" "$sa" "logging.logEntries.create")
time_series_create_permission=$(service_account_has_permission "$project_id" "$sa" "monitoring.timeSeries.create")
metric_descriptors_create_permission=$(service_account_has_permission "$project_id" "$sa" "monitoring.metricDescriptors.create")
if [[ "$time_series_create_permission" == "No" || "$metric_descriptors_create_permission" == "No" ]]; then
monitoring_permission="No"
else
monitoring_permission="Yes"
fi
performance_hpa_metric_write_permission=$(service_account_has_permission "$project_id" "$sa" "autoscaling.sites.writeMetrics")
printf "%-60s| %-40s| %-40s| %-20s\n" $sa $logging_permission $monitoring_permission $performance_hpa_metric_write_permission
if [[ "$logging_permission" == "No" || "$monitoring_permission" == "No" || "$performance_hpa_metric_write_permission" == "No" ]]; then
sa_missing_permissions+=( ${sa} )
fi
done
echo "--- 3. List all service accounts that don't have the above permissions"
if [[ "${#sa_missing_permissions[@]}" -gt 0 ]]; then
printf "Grant roles/container.defaultNodeServiceAccount to the following service accounts: %s\n" "${sa_missing_permissions[@]}"
else
echo "All service accounts have the above permissions"
fi
找出叢集中缺少重要權限的節點服務帳戶
GKE 會使用附加至節點的 IAM 服務帳戶,執行記錄和監控等系統工作。這些節點服務帳戶至少必須具備專案的「Kubernetes Engine 預設節點服務帳戶」(roles/container.defaultNodeServiceAccount
) 角色。根據預設,GKE 會使用專案中自動建立的 Compute Engine 預設服務帳戶做為節點服務帳戶。
如果貴機構強制執行 iam.automaticIamGrantsForDefaultServiceAccounts
機構政策限制,專案中的預設 Compute Engine 服務帳戶可能不會自動取得 GKE 的必要權限。
-
找出節點使用的服務帳戶名稱:
主控台
- 前往「Kubernetes clusters」(Kubernetes 叢集) 頁面:
- 在叢集清單中,按一下要檢查的叢集名稱。
- 視叢集運作模式而定,請執行下列其中一項操作:
- 如為 Autopilot 模式叢集,請在「安全性」部分中,找出「服務帳戶」欄位。
- 如果是 Standard 模式叢集,請執行下列操作:
- 按一下「Nodes」(節點) 分頁標籤。
- 在「節點集區」表格中,按一下節點集區名稱。「節點集區詳細資料」頁面隨即開啟。
- 在「安全性」部分,找到「服務帳戶」欄位。
如果「服務帳戶」欄位中的值為
default
,節點就會使用 Compute Engine 預設服務帳戶。如果這個欄位的值不是default
,節點就會使用自訂服務帳戶。如要將必要角色授予自訂服務帳戶,請參閱「使用最低權限的 IAM 服務帳戶」。gcloud
如果是 Autopilot 模式叢集,請執行下列指令:
gcloud container clusters describe
CLUSTER_NAME
\ --location=LOCATION
\ --flatten=autoscaling.autoprovisioningNodePoolDefaults.serviceAccount如果是標準模式叢集,請執行下列指令:
gcloud container clusters describe
CLUSTER_NAME
\ --location=LOCATION
\ --format="table(nodePools.name,nodePools.config.serviceAccount)"如果輸出為
default
,表示節點使用 Compute Engine 預設服務帳戶。如果輸出不是default
,表示節點使用自訂服務帳戶。如要將必要角色授予自訂服務帳戶,請參閱「使用最低權限的 IAM 服務帳戶」。 -
如要將
roles/container.defaultNodeServiceAccount
角色授予 Compute Engine 預設服務帳戶,請完成下列步驟:主控台
- 前往「歡迎」頁面:
- 在「專案編號」欄位中,按一下 「複製到剪貼簿」。
- 前往「IAM」(身分與存取權管理)IAM 頁面:
- 按一下「授予存取權」 。
- 在「New principals」(新增主體) 欄位中,指定下列值:
將PROJECT_NUMBER-compute@developer.gserviceaccount.com
PROJECT_NUMBER
替換為您複製的專案編號。 - 在「Select a role」(選取角色) 選單中,選取「Kubernetes Engine Default Node Service Account」(Kubernetes Engine 預設節點服務帳戶) 角色。
- 按一下 [儲存]。
gcloud
- 找出 Google Cloud 專案編號:
gcloud projects describe PROJECT_ID \ --format="value(projectNumber)"
將
PROJECT_ID
替換為您的專案 ID。輸出結果會與下列內容相似:
12345678901
- 將
roles/container.defaultNodeServiceAccount
角色指派給 Compute Engine 預設服務帳戶:gcloud projects add-iam-policy-binding PROJECT_ID \ --member="serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com" \ --role="roles/container.defaultNodeServiceAccount"
將
PROJECT_NUMBER
替換為上一步的專案編號。
錯誤 403:權限不足
使用 gcloud container clusters get-credentials
嘗試連線至 GKE 叢集時,如果帳戶沒有 Kubernetes API 伺服器的存取權,就會發生下列錯誤:
ERROR: (gcloud.container.clusters.get-credentials) ResponseError: code=403, message=Required "container.clusters.get" permission(s) for "projects/<your-project>/locations/<region>/clusters/<your-cluster>".
如要解決這個問題,請完成下列步驟:
找出存取權有問題的帳戶:
gcloud auth list
按照「對 Kubernetes API 伺服器進行驗證」一文中的操作說明,授予帳戶必要的存取權。
錯誤 403:重試預算已用盡
嘗試建立 GKE 叢集時,可能會發生下列錯誤:
Error: googleapi: Error 403: Retry budget exhausted: Google Compute Engine:
Required permission 'PERMISSION_NAME' for 'RESOURCE_NAME'.
這則錯誤訊息適用下列變數:
PERMISSION_NAME
:權限名稱,例如compute.regions.get
。RESOURCE_NAME
:您嘗試存取的 Google Cloud資源路徑,例如 Compute Engine 區域。
如果附加至叢集的 IAM 服務帳戶沒有建立叢集的最低必要權限,就會發生這個錯誤。
如要解決這個問題,請按照下列步驟操作:
- 建立或修改 IAM 服務帳戶,使其具備執行 GKE 叢集所需的所有權限。如需操作說明,請參閱「使用最低權限的 IAM 服務帳戶」。
- 使用
--service-account
標記,在叢集建立指令中指定更新後的 IAM 服務帳戶。如需操作說明,請參閱「建立 Autopilot 叢集」。
或者,您也可以省略 --service-account
旗標,讓 GKE 使用專案中的 Compute Engine 預設服務帳戶,該帳戶預設具有必要權限。
錯誤 404:找不到資源
如果呼叫gcloud container
指令時收到錯誤 404 (找不到資源),請重新向 Google Cloud CLI 驗證,解決這個問題:
gcloud auth login
錯誤 400/403:缺少帳戶的編輯權限
如果系統顯示缺少帳戶的編輯權限錯誤 (錯誤 400 或 403),表示下列其中一項已遭刪除或手動編輯:
啟用 Compute Engine 或 GKE API 時, Google Cloud會建立下列服務帳戶和代理程式:
- 專案中的 Compute Engine 預設服務帳戶。GKE 預設會將這個服務帳戶附加至節點,用於記錄和監控等系統工作。
- Google 代管專案中的 Google API 服務代理程式,且具備專案的編輯權限。
- Google 管理的專案中的 Google Kubernetes Engine 服務代理人,且在專案中具有 Kubernetes Engine 服務代理人角色。
如果有人編輯這些權限、移除專案的角色繫結、完全移除服務帳戶,或停用 API,叢集建立和所有管理功能都會失效。
確認 GKE 服務代理的權限
如要確認 Google Kubernetes Engine 服務帳戶是否已獲派專案的 Kubernetes Engine 服務代理人角色,請完成下列步驟:
找出 Google Kubernetes Engine 服務帳戶的名稱。所有服務帳戶都採用下列格式:
service-PROJECT_NUMBER@container-engine-robot.iam.gserviceaccount.com
將
PROJECT_NUMBER
換成您的專案編號。確認 Google Kubernetes Engine 服務帳戶未獲派專案的 Kubernetes Engine 服務代理人角色:
gcloud projects get-iam-policy PROJECT_ID
將
PROJECT_ID
替換為您的專案 ID。
如要修正問題,請檢查是否有人從 Google Kubernetes Engine 服務帳戶中移除了 Kubernetes Engine 服務代理人角色,如果是,請重新新增該角色。否則,請按照下列操作說明重新啟用 Kubernetes Engine API,還原服務帳戶和權限:
控制台
前往 Google Cloud 控制台的「APIs & Services」(API 和服務) 頁面。
選取專案。
點選「啟用 API 和服務」。
搜尋 Kubernetes,然後從搜尋結果中選取 API。
點選「Enable」(啟用)。如果您之前已啟用過 API,必須先停用,然後再重新啟用。API 和相關服務可能需要幾分鐘才能啟用。
gcloud
在 gcloud CLI 中執行下列指令:
PROJECT_NUMBER=$(gcloud projects describe "PROJECT_ID"
--format 'get(projectNumber)')
gcloud projects add-iam-policy-binding PROJECT_ID \
--member "serviceAccount:service-${PROJECT_NUMBER?}@container-engine-robot.iam.gserviceaccount.com" \
--role roles/container.serviceAgent
後續步驟
如果無法在說明文件中找到問題的解決方法,請參閱「取得支援」一文,尋求進一步的協助, 包括下列主題的建議:
- 與 Cloud 客戶服務聯絡,建立支援案件。
- 在 StackOverflow 上提問,並使用
google-kubernetes-engine
標記搜尋類似問題,向社群尋求支援。你也可以加入#kubernetes-engine
Slack 頻道,取得更多社群支援。 - 使用公開問題追蹤工具回報錯誤或提出功能要求。