·

Kubernetes MCP với Claude Code CLI and VS Code

Cài đặt Kubernetes MCP trong Claude Code CLI and VS Code để AI agent có thể kiểm tra và quản lý cluster, pod và deployment ngay trong trình soạn thảo.

Nếu bạn đã từng ngồi kubectl describe pod rồi kubectl logs -f, rồi lại kubectl get events --sort-by='.lastTimestamp' cho cùng một pod bị crash lúc 2 giờ sáng, bạn sẽ hiểu tại sao mình bắt đầu gắn Kubernetes MCP (Model Context Protocol — chuẩn giao tiếp cho phép AI agent gọi trực tiếp các tool bên ngoài) vào Claude Code CLI. Thay vì gõ hàng chục lệnh kubectl để lắp ghép bức tranh toàn cảnh, bạn mô tả triệu chứng bằng tiếng Việt (hoặc tiếng Anh), Claude Code tự chạy các tool đọc log, đọc event, đọc resource limit, rồi đưa ra chẩn đoán kèm bằng chứng cụ thể.

Bài này tập trung vào workflow thực chiến với Claude Code CLI và VS Code (thông qua Claude Code extension) khi làm việc với Kubernetes MCP server. Tôi sẽ đi từ bước cài đặt, cấu hình mcpServers, cho tới cách viết prompt để AI agent tự triage các lỗi phổ biến nhất — CrashLoopBackOff, ImagePullBackOff, Pending — và cách yêu cầu AI generate manifest hay Helm values một cách an toàn, không tự ý apply vào production.

Cài đặt và kết nối Kubernetes MCP vào Claude Code

Trước khi làm gì khác, bạn cần một MCP server hiểu Kubernetes API. Phổ biến nhất hiện nay là server dạng mcp-server-kubernetes (có nhiều bản, tôi dùng bản chạy qua npx cho gọn, không cần cài global). Điều kiện cần: máy bạn đã có kubectl cấu hình đúng kubeconfig (file chứa thông tin xác thực và địa chỉ cluster) và context đang point tới cluster bạn muốn debug.

Kiểm tra context hiện tại trước khi làm bất cứ điều gì với AI:

kubectl config current-context
kubectl config get-contexts

Đây là bước tôi luôn nhắc học viên: đừng để AI agent chạy tool trên nhầm cluster production khi bạn nghĩ nó đang ở staging. Nếu cần, đổi qua context an toàn trước:

kubectl config use-context staging-cluster

Tiếp theo, đăng ký MCP server với Claude Code. Cách nhanh nhất là dùng CLI command của Claude Code (không cần sửa tay file JSON):

claude mcp add kubernetes -- npx -y mcp-server-kubernetes

Nếu bạn muốn cấu hình thủ công (ví dụ để commit config vào repo team dùng chung), thêm vào file .mcp.json ở root project hoặc file config global của Claude Code:

{
  "mcpServers": {
    "kubernetes": {
      "command": "npx",
      "args": ["-y", "mcp-server-kubernetes"],
      "env": {
        "KUBECONFIG": "/Users/you/.kube/config"
      }
    }
  }
}

Chú ý key env.KUBECONFIG — nếu bạn quản lý nhiều cluster (dev, staging, prod) bằng nhiều file kubeconfig riêng, hãy point rõ ràng vào file bạn muốn AI truy cập, đừng để nó fallback theo biến môi trường mặc định có thể đổi tùy lúc.

Sau khi thêm, verify server đã kết nối bằng:

claude mcp list

Trong Claude Code CLI, gõ /mcp sẽ show danh sách server đang active kèm trạng thái connection. Nếu server báo lỗi, thường do npx chưa cache được package lần đầu (chạy thử npx -y mcp-server-kubernetes --version ngoài Claude Code để xem log lỗi thật).

Với VS Code, cách làm tương tự nhưng qua UI: mở Claude Code extension, vào phần MCP Servers trong settings panel, add server với đúng command/args như trên. VS Code extension dùng chung file .mcp.json cấp project nên nếu bạn đã config CLI, VS Code sẽ tự nhận diện khi mở cùng workspace — rất tiện cho team, chỉ cần commit .mcp.json (bỏ phần path kubeconfig cá nhân ra biến môi trường) vào git.

Một điểm quan trọng về quyền hạn: MCP server Kubernetes sẽ có đúng permission mà kubeconfig của bạn có. Nếu bạn dùng service account có RBAC (Role-Based Access Control — cơ chế phân quyền theo vai trò của Kubernetes) giới hạn read-only, AI agent cũng chỉ đọc được, không thể sửa. Đây là setup tôi khuyên dùng khi mới làm quen: tạo riêng một ClusterRole chỉ có quyền get, list, watch cho pods, events, deployments, rồi bind cho service account dùng riêng cho AI debugging session.

Mẹo: Trước khi giao MCP server production cho AI, tạo riêng một kubeconfig context với RBAC read-only, và luôn kubectl config current-context xác nhận lại trước khi mở session Claude Code — tránh trường hợp AI vô tình chạy đúng tool nhưng nhầm cluster.

Triage CrashLoopBackOff, ImagePullBackOff và Pending pods bằng AI

Đây là phần giá trị nhất của việc gắn MCP vào workflow debug. Ba trạng thái lỗi pod phổ biến nhất — CrashLoopBackOff (container liên tục crash và restart), ImagePullBackOff (không pull được image), Pending (pod chưa được schedule) — đều có nguyên nhân gốc rất khác nhau, và cách một senior engineer debug chúng là đọc đúng nguồn thông tin theo đúng thứ tự. AI agent với MCP tool có thể làm chuỗi thao tác đó nhanh hơn, miễn là bạn prompt đúng.

Debug CrashLoopBackOff

Prompt tôi thường dùng:

Pod "payment-api-7d9f8b6c5-x2k4p" trong namespace "production" đang ở trạng thái
CrashLoopBackOff. Hãy:
1. Lấy pod status và restart count
2. Đọc log của container hiện tại VÀ log của lần chạy trước (previous container),
   vì log hiện tại có thể chỉ show vài dòng trước khi crash
3. Kiểm tra resource limits/requests của container này
4. Đưa ra chẩn đoán nguyên nhân crash kèm dòng log cụ thể làm bằng chứng
Không sửa gì trên cluster, chỉ đọc và báo cáo.

Câu "log của lần chạy trước" (--previous trong kubectl logs) rất quan trọng — đây là lỗi tôi thấy nhiều bạn junior bỏ qua khi debug thủ công. Container vừa crash restart thường log hiện tại trống hoặc chỉ có vài dòng startup, còn nguyên nhân crash thật nằm ở log của lần chạy ngay trước đó. AI agent có MCP tool đọc log sẽ tự biết gọi cả hai nếu bạn nhắc rõ trong prompt, hoặc bạn có thể để nó tự quyết định flow debug nếu system prompt/CLAUDE.md của bạn đã định nghĩa quy trình chuẩn.

Debug ImagePullBackOff

Lỗi này gần như luôn nằm ở 3 nguyên nhân: sai tag/tên image, thiếu imagePullSecrets, hoặc registry private không cho phép truy cập. Prompt mẫu:

Pod "worker-3" namespace "staging" bị ImagePullBackOff. Hãy đọc events của pod
này (kubectl events, không phải log vì container chưa từng chạy được), lấy
đúng dòng error message pull image, kiểm tra spec.containers[].image đang set
giá trị gì, và kiểm tra pod có imagePullSecrets tương ứng registry đó chưa.
Kết luận nguyên nhân cụ thể, đừng đoán chung.

Đây là lúc events quan trọng hơn log — vì pod chưa từng start container nên log không tồn tại, mọi thông tin nằm ở events (Failed to pull image, unauthorized, manifest not found...). Tôi luôn nhắc AI phân biệt rõ "đọc log" và "đọc events" trong prompt, vì nhiều bạn hay nhầm hai khái niệm này, dẫn tới AI cũng bị dẫn sai hướng nếu prompt mơ hồ.

Debug Pending pods

Pending nghĩa là scheduler chưa gán được pod vào node nào. Nguyên nhân thường là thiếu resource (CPU/memory) trên node, node selector/affinity không khớp, hoặc taint/toleration không hợp lệ. Prompt mẫu:

Pod "ml-training-job-0" namespace "ml" đang Pending hơn 10 phút. Hãy đọc
events để lấy dòng FailedScheduling, so sánh resource requests của pod với
resource available (allocatable) của các node hiện có, kiểm tra nodeSelector/
affinity/tolerations của pod. Giải thích cụ thể node nào bị loại và vì sao.

Với case này, AI cần gọi thêm tool describe node để lấy allocatable resources — nếu MCP server bạn dùng có expose tool đó, AI sẽ tự chain nhiều lệnh lại. Nếu không, bạn có thể prompt rõ hơn: "hãy liệt kê capacity và resource đã được request trên từng node hiện tại".

Mẹo: Luôn thêm câu "không sửa gì trên cluster, chỉ đọc và báo cáo" vào cuối prompt debug — MCP server Kubernetes hiện đại thường có tool viết (patch, delete, scale), và bạn không muốn AI agent tự ý restart hay xóa pod khi bạn chỉ đang muốn xem chẩn đoán.

Đọc events, logs và resource limits từ terminal Claude Code

Một trong những lợi ích lớn nhất của việc dùng Claude Code CLI (so với dùng dashboard như Lens hay k9s) là bạn giữ được toàn bộ session trong một luồng hội thoại — AI đọc data, tổng hợp, và bạn hỏi tiếp câu follow-up mà không phải tự copy-paste output giữa nhiều terminal tab.

Khi Claude Code gọi tool MCP để đọc log, nó show ra terminal output y như bạn chạy kubectl logs, kèm theo phần tóm tắt/diễn giải của AI ngay sau đó. Ví dụ workflow thực tế: bạn hỏi

So sánh resource requests/limits hiện tại của deployment "checkout-service"
với actual usage trung bình 1 giờ qua (nếu có metrics-server), và cho biết
limit có đang quá thấp gây OOMKilled không.

AI sẽ gọi tool đọc deployment spec (lấy resources.requests và resources.limits), sau đó nếu MCP server có tích hợp với metrics API (qua kubectl top pod hoặc Prometheus adapter), nó lấy usage thực tế để so sánh. Nếu container có exit code 137 trong log/events, đó là dấu hiệu OOMKilled (bị kill vì vượt memory limit) — AI cần chỉ ra chính xác dòng đó, không chỉ nói chung "có thể do memory".

Với resource limits, tôi hay yêu cầu AI trình bày dưới dạng bảng so sánh giữa các container trong cùng pod, vì đây là chỗ dễ phát sinh lỗi:

Với pod "api-gateway-6f7d9c-abc12", liệt kê bảng: tên container, requests.cpu,
requests.memory, limits.cpu, limits.memory, và trạng thái hiện tại (Running/
Terminated + reason). Đánh dấu container nào không set limits.memory (đây là
rủi ro OOM ảnh hưởng node khác).

Việc không set limits.memory là một anti-pattern phổ biến — container đó có thể chiếm hết memory node và ảnh hưởng pod khác cùng node (node-level eviction). AI với MCP tool đọc spec rất nhanh có thể quét toàn bộ namespace tìm các container thiếu limit:

Quét toàn bộ pods trong namespace "production", liệt kê container nào
KHÔNG có limits.memory hoặc limits.cpu được set. Ưu tiên sort theo
namespace rồi deployment name.

Đây là kiểu audit task mà nếu làm tay bằng kubectl get pods -o json | jq ... sẽ mất khá nhiều thời gian viết jq query, còn AI agent với MCP tool đọc trực tiếp structured data thì trả kết quả gần như ngay lập tức, và bạn vẫn kiểm tra lại được vì terminal show rõ tool call nào đã chạy.

Mẹo: Khi hỏi AI về resource usage, luôn hỏi kèm "cho biết bạn lấy số liệu từ tool nào, thời điểm nào" — vì metrics từ metrics-server có độ trễ và window quan sát khác nhau, tránh để AI báo cáo số liệu như tuyệt đối chính xác real-time.

Generate và review manifest, Helm values với AI

Đây là phần dễ gây rủi ro nhất nếu dùng sai cách — AI rất giỏi generate YAML manifest hay Helm values trông "đẹp và hợp lệ", nhưng manifest hợp lệ về syntax không đồng nghĩa đúng về mặt vận hành (ví dụ thiếu PodDisruptionBudget, thiếu readinessProbe, hay set replicas không phù hợp).

Quy trình tôi áp dụng: luôn để AI generate ra file trước, không apply trực tiếp, rồi review bằng kubectl diff hoặc helm diff trước khi apply thật.

Prompt generate Deployment manifest mới dựa trên pattern hiện có trong cluster:

Dựa trên deployment "user-service" hiện tại trong namespace "production" (đọc
spec hiện tại làm tham khảo), hãy tạo manifest YAML mới cho service
"notification-service" với image "registry.internal/notification-service:1.2.0",
2 replicas, có readinessProbe và livenessProbe trên path "/healthz" port 8080,
resource requests 250m CPU/256Mi memory, limits 500m CPU/512Mi memory.
Xuất ra file, KHÔNG apply.

Chỉ định rõ "xuất ra file, không apply" là bắt buộc — nhiều MCP server có tool apply hoặc create, và nếu bạn không giới hạn, AI có thể tự tin apply luôn vì nghĩ đó là điều bạn muốn. Sau khi có file, tôi luôn review bằng:

kubectl diff -f notification-service-deployment.yaml

hoặc yêu cầu AI tự chạy diff này và giải thích từng thay đổi trước khi bạn quyết định apply.

Với Helm, workflow tương tự nhưng ở tầng values.yaml. Ví dụ prompt điều chỉnh values cho một upgrade:

Đọc values.yaml hiện tại của Helm release "redis-cache" trong namespace "cache".
Tôi muốn tăng memory limit từ 512Mi lên 1Gi và bật persistence (persistence.enabled
= true, size 8Gi). Generate values override file mới, và chạy
"helm diff upgrade redis-cache bitnami/redis -f values-override.yaml" để tôi xem
trước thay đổi thật sẽ áp dụng, không chạy helm upgrade.

helm diff (plugin cần cài riêng: helm plugin install https://github.com/databus23/helm-diff) là công cụ tôi luôn khuyên dùng chung với AI-generated values — nó show chính xác resource nào sẽ đổi, tránh trường hợp một thay đổi nhỏ trong values kéo theo restart toàn bộ StatefulSet ngoài dự tính.

Một use case khác rất thực tế: nhờ AI review lại manifest cũ có tuân theo best practice không.

Review manifest deployment "legacy-worker" trong namespace "batch". Kiểm tra
các điểm: có set resource limits chưa, có readinessProbe/livenessProbe chưa,
securityContext có chạy container as non-root chưa, có set
"imagePullPolicy: Always" trên image tag cố định (dấu hiệu anti-pattern) không.
Liệt kê issue theo mức độ ưu tiên, không tự sửa.

Đây là dạng prompt tôi hay dùng khi onboard một service cũ chưa từng được review kỹ, AI với MCP tool đọc trực tiếp spec thật trên cluster (không phải suy đoán từ file trong repo, vốn có thể đã lệch so với thực tế đang chạy) cho ra kết quả đáng tin hơn nhiều.

Mẹo: Luôn tách rõ hai bước "generate/review" và "apply" thành hai lượt yêu cầu riêng với AI — đừng bao giờ dùng một prompt vừa generate vừa apply cho manifest production, dù MCP server có hỗ trợ tool đó.

Tips

Ngoài các mẹo đã nêu ở từng phần, có vài nguyên tắc chung tôi tích lũy được sau nhiều lần dùng Kubernetes MCP với Claude Code trong công việc thật:

  • Luôn bắt đầu session bằng việc xác nhận context/cluster/namespace, đừng tin AI "tự biết" bạn đang muốn debug ở đâu.
  • Tách biệt rõ ràng permission cho session debug (read-only) và session thực hiện thay đổi (có quyền write), dùng hai context Kubernetes riêng nếu cần.
  • Với log dài, luôn giới hạn AI đọc theo --tail hoặc theo khoảng thời gian cụ thể, tránh AI đọc toàn bộ log khổng lồ làm tốn context window (giới hạn lượng thông tin AI xử lý được trong một lượt) một cách không cần thiết.
  • Với VS Code, tận dụng khả năng vừa xem code repo (Helm chart, manifest trong Git) vừa chat với AI đọc trạng thái cluster thật cùng lúc — đây là lợi thế lớn so với việc tách rời hai công cụ, vì bạn phát hiện ngay chỗ lệch giữa code trong repo và thực tế đang chạy trên cluster (config drift).
  • Định kỳ review lại RBAC của service account gắn với MCP server — quyền hạn nên thu hẹp dần theo thời gian, không nên giữ quyền rộng "cho tiện" sau khi giai đoạn thử nghiệm ban đầu đã qua.

Mẹo: Lưu lại các prompt debug hiệu quả nhất của bạn thành một file snippet trong repo (ví dụ docs/ai-debug-prompts.md), để cả team dùng lại pattern prompt đã được kiểm chứng thay vì mỗi người tự mò từ đầu.

Tiếp Kubernetes MCP với OpenCode