本頁面由 Cloud Translation API 翻譯而成。

排解 4xx 錯誤

自動駕駛標準

本頁說明如何解決使用 Google Kubernetes Engine (GKE) 時可能遇到的 400、401、403 和 404 錯誤。

問題：驗證和授權錯誤

連線至 GKE 叢集時，您可能會收到 HTTP 狀態碼為 401 (Unauthorized) 的驗證和授權錯誤。如果您嘗試從本機環境在 GKE 叢集中執行 kubectl 指令，就可能會發生這個問題。

這個問題可能是下列原因所致：

gke-gcloud-auth-plugin 驗證外掛程式未正確安裝或設定。
您沒有連線至叢集 API 伺服器及執行 kubectl 指令的權限。

如要診斷原因，請完成下列各節的步驟：

使用 curl 連線至叢集
在 kubeconfig 中設定外掛程式

使用 `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 的必要權限。

找出節點使用的服務帳戶名稱：
主控台
1. 前往「Kubernetes clusters」(Kubernetes 叢集) 頁面：
  前往 Kubernetes 叢集
2. 在叢集清單中，按一下要檢查的叢集名稱。
3. 視叢集運作模式而定，請執行下列其中一項操作：
  
  如為 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 預設服務帳戶，請完成下列步驟：
主控台
1. 前往「歡迎」頁面：
  前往「歡迎」
2. 在「專案編號」欄位中，按一下「複製到剪貼簿」。
3. 前往「IAM」(身分與存取權管理)IAM 頁面：
  前往「身分與存取權管理」頁面
4. 按一下「授予存取權」。
5. 在「New principals」(新增主體) 欄位中，指定下列值：
  PROJECT_NUMBER-compute@developer.gserviceaccount.com
  將 PROJECT_NUMBER 替換為您複製的專案編號。
6. 在「Select a role」(選取角色) 選單中，選取「Kubernetes Engine Default Node Service Account」(Kubernetes Engine 預設節點服務帳戶) 角色。
7. 按一下 [儲存]。
gcloud
1. 找出 Google Cloud 專案編號：
  gcloud projects describe PROJECT_ID \ --format="value(projectNumber)"
  
  將 PROJECT_ID 替換為您的專案 ID。
  
  輸出結果會與下列內容相似：
  
  12345678901
2. 將 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 與服務」頁面
選取專案。
點選「啟用 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 頻道，取得更多社群支援。
- 使用公開問題追蹤工具回報錯誤或提出功能要求。

排解 4xx 錯誤 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

問題：驗證和授權錯誤

使用 curl 連線至叢集

在 kubeconfig 中設定外掛程式的使用方式

錯誤 400：節點集區需要重新建立

錯誤 401：未授權

找出節點服務帳戶缺少重要權限的叢集

找出叢集中缺少重要權限的節點服務帳戶

主控台

gcloud

主控台

gcloud

錯誤 403：權限不足

錯誤 403：重試預算已用盡

錯誤 404：找不到資源

錯誤 400/403：缺少帳戶的編輯權限

確認 GKE 服務代理的權限

控制台

gcloud

後續步驟

排解 4xx 錯誤

使用 `curl` 連線至叢集