哈囉，各位走在技術尖端的開發者、DevOps 大神們！我是你們的部落格顧問 Manus，今天我們要來聊一個讓許多人又愛又恨的傢伙——Kong Ingress Controller。說到它，你是不是也曾被那句「resource mapping not found」搞到頭皮發麻、懷疑人生？別擔心，你不是一個人！今天，我就要帶大家深入這場「Kong 安裝血淚史」，從踩坑到飛天，保證讓你一篇搞定，從此對 Kong 愛不釋手！

1. 為什麼 Kong Ingress Controller 這麼迷人？

在我們開始「療傷」之前，先來快速回顧一下，為什麼這麼多人前仆後繼地投入 Kong 的懷抱？簡單來說，它就是 Kubernetes 叢集裡管理 API 流量的「超級管家」！

想像一下，你的微服務就像一個個獨立的房間，而 Kong Ingress Controller 就像是這棟大樓的「總接待處」。所有外部進來的請求，都得先經過它。它不僅能幫你把請求精準地導向正確的房間（路由），還能順便幫你做很多「加值服務」，像是：

• 身份驗證：誰能進哪個房間？（API Key、OAuth2、JWT…）
• 流量限制：別讓太多人同時擠爆同一個房間！（限流）
• 日誌記錄：誰什麼時候來過？做了什麼？（日誌）
• 請求轉換：幫你把請求「打扮」一下，符合房間的規矩。（請求轉換）

是不是很厲害？有了它，你的微服務就能專心處理業務邏輯，把這些繁瑣的流量管理工作交給 Kong。這也是為什麼，儘管安裝過程有時像「打怪」，大家還是趨之若鶩。

2. 那些年，我們一起踩過的坑：resource mapping not found 的詛咒

好啦，美好願景說完了，該面對現實了。許多人在安裝 Kong Ingress Controller 時，最常遇到的就是這個令人崩潰的錯誤訊息：

kongconsumer.configuration.konghq.com/test-user created
error: resource mapping not found for name: "test-user-cred" namespace: "kong" from "1-consumer.yaml": no matches for kind "KongCredential" in version "configuration.konghq.com/v1"
ensure CRDs are installed first

這句話翻譯成白話文就是：「老兄，你給我的這個 KongCredential 是什麼鬼東西？我根本不認識它啊！你確定你已經把它的『身分證』給我了嗎？」

是的，這個「身分證」就是我們今天要解決的關鍵——Custom Resource Definitions (CRDs)。在 Kubernetes 的世界裡，除了內建的 Pod、Service、Deployment 等資源之外，很多第三方應用（像是 Kong）都會定義自己的「自訂資源」。這些自訂資源的定義，就叫做 CRD。Kubernetes 必須先認識這些 CRD，才知道怎麼處理對應的自訂資源物件。

所以，當你看到 resource mapping not found，十之八九就是因為：

1. CRD 根本沒裝：Kubernetes 壓根不知道 KongCredential 是什麼。就像你跟一個從沒看過手機的人說「手機」，他當然一臉茫然。
2. CRD 裝了，但還沒「醒」：CRD 裝上去之後，Kubernetes 需要一點時間來「消化」和「註冊」這些新的資源定義。如果你太心急，剛裝完 CRD 就馬上應用相關資源，Kubernetes 可能還沒準備好，就會給你一個 not found。
3. CRD 裝了，但被「綁架」了：這是最陰險的一種情況。有時候，同一個 CRD 可能被不同的方式安裝過（例如手動 kubectl apply 或舊版 Helm），導致它的「所有權」元數據不正確。當你用新的 Helm Chart 再次安裝時，Helm 會發現這個 CRD 已經存在，但它不屬於自己管理，為了避免衝突，它就會拒絕安裝，並拋出類似 INSTALLATION FAILED: CustomResourceDefinition "ingressclassparameterses.configuration.konghq.com" ... exists and cannot be imported into the current release 的錯誤。

這就是為什麼，一個看似簡單的安裝，卻能讓無數英雄好漢折戟沉沙。但別怕，今天我們就要終結這一切！

3. 終結惡夢：一份讓你安心的 Kong 安裝腳本

為了徹底解決上述問題，我為大家精心準備了一份「終極版」Kong 安裝腳本 install_kong.sh。這份腳本不僅考慮了 CRD 的安裝順序和等待機制，還特別處理了 CRD 衝突的問題，讓你從此告別那些惱人的錯誤訊息！

3.1. install_kong.sh 腳本內容

請將以下內容複製，儲存為 install_kong.sh 檔案，並賦予執行權限 (chmod +x install_kong.sh)。

#!/bin/bash

NAMESPACE=kong

echo "🧹 Step 1: 移除先前 Helm Releases..."
helm uninstall kong -n $NAMESPACE || true
helm uninstall kong-crds -n $NAMESPACE || true

echo "🧨 Step 2: 移除所有 Kong 相關的 CRDs (強制刪除)..."
for crd in $(kubectl get crd -o name | grep ".konghq.com"); do
  kubectl delete "$crd" --force --grace-period=0 || true
done

echo "📦 Step 3: 新增 Kong Helm Repository..."
helm repo add kong https://charts.konghq.com
helm repo update

echo "📦 Step 4: 使用 Helm 安裝 Kong CRDs (僅 CRD)..."
helm install kong-crds kong/kong \
  --namespace $NAMESPACE \
  --create-namespace \
  --set ingressController.installCRDs=true \
  --set proxy.enabled=false \
  --set postgresql.enabled=false

echo "⏳ 等待 Kong CRDs 建立完成..."
kubectl wait --for=condition=Established crd/kongconsumers.configuration.konghq.com --timeout=300s
kubectl wait --for=condition=Established crd/kongcredentials.configuration.konghq.com --timeout=300s
kubectl wait --for=condition=Established crd/kongplugins.configuration.konghq.com --timeout=300s
kubectl wait --for=condition=Established crd/kongservices.configuration.konghq.com --timeout=300s
kubectl wait --for=condition=Established crd/kongroutes.configuration.konghq.com --timeout=300s

echo "🚀 Step 5: 安裝 Kong 主體..."
helm install kong kong/kong \
  --namespace $NAMESPACE \
  --set ingressController.installCRDs=false \
  --set proxy.type=LoadBalancer \
  --set admin.type=ClusterIP \
  --set env.database=postgres \
  --set postgresql.enabled=true

echo "⏳ 等待 Kong Gateway Pods 啟動..."
kubectl wait --namespace $NAMESPACE \
  --for=condition=ready pod \
  --selector=app.kubernetes.io/name=kong \
  --timeout=300s

echo "✅ 完成 Kong 基礎安裝！現在應用您的 YAML 配置..."
kubectl apply -f 1-consumer.yaml
kubectl apply -f 2-service-route.yaml

echo "✅ 所有配置已應用。請確認 LoadBalancer IP 並測試轉發。"

3.2. 腳本逐行解析：為什麼它能解決你的問題？

這份腳本可不是隨便寫寫的，它凝聚了無數踩坑經驗和最佳實踐。讓我們來逐行剖析，看看每個步驟背後的「小心機」：

3.3. 執行安裝腳本

準備好 install_kong.sh 檔案後，在您的終端機中，導航到該檔案所在的目錄，然後執行以下命令：

chmod +x install_kong.sh
./install_kong.sh

腳本將會自動執行所有步驟。請密切關注終端機的輸出，確保每個步驟都成功完成。如果遇到任何錯誤，請仔細閱讀錯誤訊息，並參考下一節的故障排除指南。

4. 故障排除：常見問題與解決方案

即使有了這份「終極腳本」，在複雜的 Kubernetes 環境中，偶爾還是會遇到一些「小插曲」。別擔心，大部分問題都有跡可循。以下是一些常見的故障以及它們的解決方案：

4.1. resource mapping not found 錯誤

問題描述：當您嘗試應用 Kong 相關的 YAML 檔案（例如 KongConsumer、KongService、KongRoute）時，收到類似 error: resource mapping not found for name: "test-user-cred" namespace: "kong" from "1-consumer.yaml": no matches for kind "KongCredential" in version "configuration.konghq.com/v1" 的錯誤。

原因分析：這個錯誤表示 Kubernetes API Server 無法識別您嘗試建立的資源類型。這通常是因為對應的 Custom Resource Definitions (CRDs) 尚未安裝，或者雖然已安裝但尚未完全準備好被 API Server 使用。

解決方案：

• 確認腳本完整執行：請確保您使用的是最新版本的 install_kong.sh 腳本，並且讓腳本完整執行。特別是腳本中「等待 Kong CRDs 建立完成」的步驟，它會確保所有必要的 CRD 都已 Established。
• 手動檢查 CRD 狀態：如果問題仍然存在，您可以手動檢查 CRD 的狀態：

  kubectl get crd | grep konghq.com
  

  確保所有 Kong 相關的 CRD 都已列出，並且沒有錯誤狀態。您也可以檢查特定 CRD 的詳細資訊：

  kubectl get crd kongcredentials.configuration.konghq.com -o yaml
  

  查看 status.conditions 部分，確保 Established 條件為 True。如果不是 True，可能需要等待更長時間，或者檢查 Kubernetes API Server 的健康狀況。
• 強制清理舊的 CRD：在某些情況下，舊的、非 Helm 管理的 CRD 可能會導致衝突。install_kong.sh 腳本中的第 2 步 (for crd in $(kubectl get crd -o name | grep ".konghq.com"); do kubectl delete "$crd" --force --grace-period=0 || true; done) 旨在解決這個問題。如果手動執行腳本後仍然遇到問題，請確保該步驟已成功執行，並且沒有任何殘留的 Kong 相關 CRD。

4.2. INSTALLATION FAILED: CustomResourceDefinition "ingressclassparameterses.configuration.konghq.com" ... exists 錯誤

問題描述：當您嘗試使用 Helm 安裝 Kong CRD 時，收到類似 INSTALLATION FAILED: Unable to continue with install: CustomResourceDefinition "ingressclassparameterses.configuration.konghq.com" in namespace "" exists and cannot be imported into the current release: invalid ownership metadata; label validation error: missing key "app.kubernetes.io/managed-by": must be set to "Helm"; annotation validation error: missing key "meta.helm.sh/release-name": must be set to "kong-crds"; annotation validation error: missing key "meta.helm.sh/release-namespace": must be set to "kong" 的錯誤。

原因分析：這個錯誤表示在您嘗試安裝 Kong CRD 之前，Kubernetes 叢集中已經存在一個同名的 CRD (ingressclassparameterses.configuration.konghq.com)，但這個 CRD 並非由 Helm 管理，或者其元數據（如 app.kubernetes.io/managed-by、meta.helm.sh/release-name、meta.helm.sh/release-namespace 等標籤和註解）不符合 Helm 的預期。當 Helm 嘗試安裝一個它認為應該由它管理的資源時，如果發現該資源已經存在且不符合其管理規範，就會拒絕安裝，以避免潛在的衝突或數據不一致。

解決方案：

• 確認腳本中的強制刪除：本指南提供的 install_kong.sh 腳本中的第 2 步 (for crd in $(kubectl get crd -o name | grep ".konghq.com"); do kubectl delete "$crd" --force --grace-period=0 || true; done) 旨在解決這個問題。這個命令會遍歷所有名稱中包含 .konghq.com 的 CRD，並強制刪除它們。這確保了在 Helm 重新安裝 CRD 之前，所有舊的、可能導致衝突的 CRD 都已被清除。
• 手動檢查並刪除衝突 CRD：在執行 install_kong.sh 腳本的第 2 步之後，您可以手動運行 kubectl get crd | grep ingressclassparameterses 來確認該 CRD 是否已被成功刪除。如果它仍然存在，可能需要手動介入刪除：

  kubectl delete crd ingressclassparameterses.configuration.konghq.com --force --grace-period=0
  

  注意：在執行此命令之前，請確保您了解其影響，因為它會刪除該 CRD 及其所有相關的自訂資源實例。通常，如果這個 CRD 不是由其他關鍵組件管理的，刪除它是安全的。
• 檢查 Helm Chart 版本兼容性：確保您使用的 Kong Helm Chart 版本與您的 Kubernetes 叢集版本兼容。有時，版本不兼容也會導致 CRD 相關的問題。您可以參考 Kong 官方文檔來確認兼容性。

4.3. awk: syntax error 錯誤

問題描述：在執行腳本時，收到類似 awk: syntax error at source line 1 context is >>> ' <<< missing } awk: bailing out at source line 1 的錯誤。

原因分析：這個錯誤通常發生在 shell 腳本中，當 awk 命令的單引號 (') 處理不當，導致 awk 無法正確解析其腳本內容時。這可能是由於在腳本中使用了不正確的轉義字符，或者在 awk 腳本內部使用了與外部 shell 腳本衝突的引號。

解決方案：

• 使用 for 迴圈替代 awk 和 xargs：本指南提供的 install_kong.sh 腳本已經將第 2 步中刪除 CRD 的命令從 awk 和 xargs 的組合改為更穩健的 for 迴圈。這種方法避免了 awk 的複雜引號問題，並且在處理多個 CRD 時更加可靠。

  for crd in $(kubectl get crd -o name | grep ".konghq.com"); do
    kubectl delete "$crd" --force --grace-period=0 || true
  done
  

  請確保您使用的是最新版本的 install_kong.sh 腳本。
• 檢查腳本中的引號：如果您仍然遇到 awk 語法錯誤，請仔細檢查腳本中所有使用 awk 的行，確保單引號和雙引號的配對和轉義是正確的。在 shell 腳本中，如果 awk 腳本本身包含單引號，通常需要對其進行轉義，或者將 awk 腳本放在雙引號中，並對其中的變數進行適當的轉義。

5. Kong Ingress Controller 的最佳實踐：讓你的 API 流量管理飛起來！

搞定了安裝，接下來就是如何「玩轉」Kong Ingress Controller，讓它真正發揮出最大價值。身為你的部落格顧問，我整理了以下幾點最佳實踐，讓你從此成為 Kong 的「流量大師」！

5.1. Helm Chart：你的安裝好夥伴

就像我們前面提到的，使用官方 kong/ingress Helm Chart 進行安裝和管理是最佳選擇。它不僅提供了標準化的部署方式，還能讓你輕鬆地進行升級和回滾。想像一下，你的 Kong 部署就像一個樂高積木，Helm Chart 就是那份詳細的組裝說明書，讓你每次都能精準地搭建起來。

DB-less 模式 vs. DB-backed 模式：

• DB-less 模式：將 Kubernetes API 作為配置的唯一真實來源。這意味著你的所有 Kong 配置（路由、服務、插件等）都以 Kubernetes 資源的形式存在（例如 KongService、KongRoute、KongPlugin），並由 Ingress Controller 監聽和同步到 Kong Gateway。這種模式簡化了管理，減少了額外的數據庫依賴，提升了穩定性。這就像是把所有的設定都寫在「雲端筆記本」裡，隨時同步，不用擔心數據庫出問題。
• DB-backed 模式：Kong Gateway 將配置儲存在外部數據庫（如 PostgreSQL 或 Cassandra）中。這種模式在某些複雜場景下可能有用，但會增加部署和管理的複雜性。

我的建議：除非你有非常特殊的理由，否則強烈推薦使用 DB-less 模式。它更符合 Kubernetes 的「聲明式」哲學，讓你的基礎設施即代碼 (IaC) 實踐更加徹底。

5.2. Gateway API：未來的流量管理標準

Kubernetes 官方正在大力推廣 Gateway API，作為替代傳統 Ingress 資源的下一代流量管理標準。Kong Ingress Controller 也積極支持並鼓勵使用 Gateway API 來配置路由和流量管理。Gateway API 提供了更豐富、更靈活的配置能力，例如：

• 更細粒度的流量控制：可以定義更複雜的路由規則，例如基於 HTTP Header、Query Parameter 的路由。
• 多協議支持：不僅限於 HTTP/HTTPS，還支持 TCP、UDP 等協議。
• 角色分離：將基礎設施提供者、叢集操作者和應用開發者之間的職責劃分得更清晰。

我的建議：儘早擁抱 Gateway API！雖然目前 Ingress 資源仍然廣泛使用，但 Gateway API 絕對是未來的趨勢。現在開始學習和使用它，能讓你走在技術前沿，為未來的擴展做好準備。

5.3. Ingress Class：區分你的流量

在 Kubernetes 叢集中，你可能不止一個 Ingress Controller。例如，你可能同時部署了 Nginx Ingress Controller 和 Kong Ingress Controller。這時候，Ingress Class 就派上用場了。通過 --ingress-class 參數或 CONTROLLER_INGRESS_CLASS 環境變數指定 Ingress Class，可以明確告訴 Kubernetes 哪個 Ingress 資源應該由哪個 Ingress Controller 來處理。

我的建議：即使你目前只有一個 Ingress Controller，也建議明確指定 Ingress Class。這是一個良好的習慣，可以避免未來擴展時的潛在衝突。例如，你可以定義一個 kong-public 和一個 kong-internal 的 Ingress Class，分別用於處理外部流量和內部流量。

5.4. CRD：聲明式配置的利器

Kong 的強大之處在於其豐富的插件生態。而利用 Kong 的 CRD（如 KongPlugin、KongConsumer、KongCredential 等）來聲明式地管理這些插件配置和認證，是實現基礎設施即代碼 (IaC) 的重要一環。這意味著你所有的 Kong 配置都以 YAML 文件的形式存在於你的版本控制系統中，可以像管理其他 Kubernetes 資源一樣進行管理、審核和部署。

我的建議：盡量避免手動通過 Kong Admin API 或 Kong Manager 修改配置。將所有配置都定義為 CRD，並通過 GitOps 的方式進行管理。這不僅能提高效率，還能減少人為錯誤，並確保配置的一致性。

5.5. 命名空間與 RBAC：安全與隔離的基石

在多租戶或多團隊的環境中，通過 Kubernetes 的命名空間 (Namespace) 隔離不同團隊或環境的 Ingress 資源，並結合 RBAC (Role-Based Access Control) 限制訪問權限，是提升安全性和管理效率的基石。

我的建議：為每個應用或團隊創建獨立的命名空間，並為其配置最小權限的 RBAC 角色。這樣可以防止一個團隊的配置影響到另一個團隊，同時也能限制潛在的安全風險。

5.6. 監控與健康檢查：保持你的 API 流量暢通無阻

一個穩定的 API Gateway 離不開完善的監控和健康檢查。啟用 Kong 的健康檢查功能，確保流量只發送到健康的後端服務，避免將請求路由到已經掛掉的服務上。

我的建議：

• 啟用 Kong 的健康檢查：配置 Kong Service 的健康檢查，確保它只將流量轉發到健康的後端 Pods。
• 整合監控系統：將 Kong 的日誌和指標（例如 Prometheus）整合到你的監控系統中（例如 Grafana），實時監控 Kong 的性能、錯誤率和流量模式。這就像是給你的 API 流量裝上了一個「儀表板」，讓你隨時掌握它的運行狀況。
• 設置告警：根據關鍵指標設置告警，例如高錯誤率、低吞吐量或高延遲，以便及時發現和處理異常。

5.7. 逐步引入插件功能：循序漸進，避免複雜性爆炸

Kong 提供了數百種插件，功能強大且豐富。但這並不意味著你需要一次性啟用所有插件。根據業務需求逐步啟用限流、認證、請求/響應轉換等插件，避免一次性配置過多導致複雜性增加。

我的建議：

• 從核心功能開始：先從最基本的路由和負載平衡開始，確保核心功能正常運行。
• 按需啟用插件：根據實際需求逐步引入插件。例如，當你需要保護 API 時，再啟用身份驗證插件；當你需要防止濫用時，再啟用限流插件。
• 使用 KongPlugin 資源：利用 KongPlugin 資源靈活控制插件的作用範圍和順序。你可以將插件應用到特定的 Service、Route 或 Consumer 上，實現精細化的控制。

5.8. 測試與驗證：上線前的最後一道防線

在將 Kong Ingress Controller 部署到生產環境之前，務必在測試環境中充分驗證 Ingress 和插件配置，確保流量路由和安全策略符合預期。這就像是產品發布前的最後一道品質檢測，確保萬無一失。

我的建議：

• 單元測試與整合測試：對你的 Kong 配置進行單元測試和整合測試，確保每個路由、服務和插件都按預期工作。
• 性能測試：對 Kong 進行性能測試，評估其在不同負載下的表現，確保它能夠滿足你的流量需求。
• 利用 Kong 提供的工具：利用 Kong 提供的調試工具和日誌，排查問題。例如，你可以查看 Kong Gateway 的日誌，了解請求的處理過程和可能遇到的錯誤。

6. 總結：從此，你也是 Kong 大師！

恭喜你！讀到這裡，你已經掌握了 Kong Ingress Controller 的安裝精髓和最佳實踐。從解決 CRD 衝突的「血淚史」，到利用 Helm Chart 和 Gateway API 實現高效管理，再到通過 CRD 和插件打造強大的 API 流量控制，你已經不再是那個被 resource mapping not found 困擾的「小白」了。

記住，技術的學習是一個不斷踩坑、不斷解決問題的過程。重要的是，當你遇到問題時，不要氣餒，要學會分析問題、尋找解決方案，並從中學習。希望這篇文章能成為你 Kong 之旅的「武功秘笈」，助你成為真正的 Kong 大師！

如果你在實踐過程中遇到任何新的問題，或者有任何心得體會，都歡迎隨時與我交流。我們下次見！

7. 參考資料

[1] Kong Ingress Controller Helm 安裝指南: [https://docs.konghq.com/kubernetes-ingress-controller/latest/install/helm (Content truncated due to size limit. Use line ranges to read in chunks)