My Awesome Project

Appearance

Chapter 55: Kubernetes API Machinery Deep Dive ​

Giới Thiệu ​

Phần lớn tài liệu vận hành Kubernetes dừng lại ở mức "control plane có API server, scheduler, controller-manager, etcd". Điều đó đúng nhưng chưa đủ để debug những sự cố khó nhất trong production: tại sao một kubectl apply báo 409 Conflict dù không ai đụng vào resource cùng lúc, tại sao một controller "bỏ lỡ" một sự kiện update, tại sao request bị 429 dù cluster còn CPU rảnh, hay tại sao một CRD version mới lại làm vỡ toàn bộ webhook conversion.

Những câu hỏi đó không nằm ở tầng "component nào tồn tại" mà nằm ở tầng API machinery — cơ chế bên trong quyết định cách một request đi từ client tới etcd và quay lại thành một sự kiện watch ở phía controller. Đây là lớp kiến thức nằm giữa "biết Kubernetes có gì" và "biết Kubernetes vận hành như thế nào ở mức instruction".

Vì sao chương này quan trọng ở production:

  • API server không phải một hộp đen CRUD. Nó là một pipeline nhiều giai đoạn (authentication → authorization → admission → schema conversion → storage) với state được phân tán giữa watch cache trong bộ nhớ API server và MVCC store trong etcd. Hiểu sai một giai đoạn nào cũng dẫn tới misconfiguration nguy hiểm (ví dụ đặt AlwaysAllow sai vị trí trong chain authorization).
  • Toàn bộ hệ sinh thái controller của Kubernetes (kube-controller-manager, kubelet, mọi Operator viết bằng controller-runtime) đứng trên một giả định duy nhất: watch là nguồn sự thật đáng tin cậy, list-watch protocol không mất sự kiện, và local cache của informer phản ánh đúng state đã quan sát được. Khi giả định này bị vi phạm (watch cache bị evict, resourceVersion quá cũ, informer resync sai chu kỳ), toàn bộ hệ thống reconciliation phía trên nó suy luận sai về state thực tế.
  • APF (API Priority and Fairness) quyết định request nào được thực thi khi cluster bị quá tải — hiểu sai cơ chế seat/queue sẽ khiến bạn tune sai limit và vô tình bóp nghẹt chính controller quan trọng nhất.
  • CRD là cơ chế mở rộng API, không phải "config file có schema". Hiểu đúng cách CRD tạo REST handler động, cách structural schema và conversion webhook hoạt động là điều kiện tiên quyết để thiết kế Operator ổn định qua nhiều version.

Tài liệu này đào sâu vào internal model của từng cơ chế — data flow, control flow, state nằm ở đâu, và tại sao Kubernetes được thiết kế theo cách này thay vì cách khác — thay vì liệt kê thao tác kubectl.

Điều Kiện Tiên Quyết ​

  • Chapter 5: GKE Control Plane Internals — kiến trúc control plane, etcd vs Spanner, khái niệm cơ bản về watch caching, informer pattern, reconciliation loop, APF và admission pipeline. Chương 55 giả định bạn đã nắm bức tranh tổng quan ở Chapter 5 và đào sâu thêm một tầng vào cơ chế client-side (client-go, controller-runtime) cũng như các chi tiết giao thức mà Chapter 5 chưa khai thác hết.
  • Kinh nghiệm viết hoặc vận hành ít nhất một Kubernetes controller/Operator.
  • Hiểu cơ bản về Raft consensus và distributed systems (quorum, leader election, linearizability).

Cấu Trúc Tài Liệu ​

Phần 1: Request Pipeline & Kiểm Soát Truy Cập ​

  1. API Server Request Pipeline: Authentication → Authorization → Admission → Storage — Toàn bộ hành trình một request đi qua authenticator chain, authorizer union, admission hai pha (mutating/validating), object conversion, và ghi xuống storage layer.

Phần 2: Cơ Chế Lan Truyền State — Watch, Informer, Controller ​

  1. Watch Mechanism: Lan Truyền State Hiệu Quả Không Cần Polling — Giao thức list-watch, ngữ nghĩa resourceVersion, watch bookmark, chunking, và lỗi 410 Gone khi watch cache bị evict.
  2. Informer Pattern: List-Watch, Local Cache, Resync — Kiến trúc Reflector, DeltaFIFO, Indexer/ThreadSafeStore, SharedInformerFactory bên trong client-go, và vì sao mọi controller đọc từ cache thay vì gọi API server trực tiếp.
  3. Controller-Runtime Framework: Reconciliation Loop Patterns — Manager, Controller, Reconciler interface, Source/EventHandler/Predicate, split-client (cache read / direct write), rate-limited workqueue và exponential backoff.

Phần 3: Kiểm Soát Tải & Nhất Quán Dữ Liệu ​

  1. API Priority and Fairness: Flow Schema, Priority Level, Seat & Queue — Cơ chế phân loại request thành flow, tính seat, shuffle sharding vào hàng đợi, và fairness algorithm khi cluster quá tải.
  2. Etcd Consistency: Linearizability, MVCC & Watch Caching — Raft consensus, mô hình revision MVCC, linearizable read vs serializable read, và cách watch cache của API server xếp chồng lên watch stream của etcd.
  3. Resource Versioning: Optimistic Locking & Conflict Resolution — resourceVersion như một optimistic concurrency token, 409 Conflict, các loại patch (JSON Patch, Merge Patch, Strategic Merge Patch), và Server-Side Apply field ownership.

Phần 4: Mở Rộng API ​

  1. Custom Resource Definitions: Cơ Chế Mở Rộng API Server — Cách CRD sinh REST handler động, structural schema, versioning và conversion webhook, subresource status/scale, so sánh với aggregated API server.

Mục Tiêu Học Tập ​

Sau khi hoàn thành chương này, bạn sẽ:

  1. Truy vết chính xác một request từ kubectl tới khi nó được ghi vào etcd và phát sinh watch event, biết chỗ nào có thể fail và fail như thế nào.
  2. Debug watch/informer đúng root cause — phân biệt được giữa lỗi do relist storm, watch cache eviction, và resync interval bị cấu hình sai.
  3. Thiết kế controller ổn định dựa trên đúng mental model của controller-runtime: khi nào nên trust cache, khi nào phải đọc trực tiếp, và cách requeue đúng cách.
  4. Tune APF đúng cách cho workload cụ thể, tránh vô tình đói tài nguyên của controller hệ thống.
  5. Suy luận đúng về consistency guarantee mà etcd và API server cung cấp, tránh giả định sai về linearizability trong logic controller.
  6. Thiết kế CRD an toàn qua nhiều version với conversion webhook và structural schema đúng chuẩn.

Điều Không Nằm Trong Scope ​

  • Cú pháp YAML/CLI cơ bản của Role, RoleBinding — xem Chapter 56.
  • Kiến trúc GKE control plane managed vs self-managed, SLA, credential rotation — đã covered ở Chapter 5.
  • Admission policy CEL chi tiết cho ValidatingAdmissionPolicy — đã covered ở Chapter 5, mục 10.
  • Debugging methodology theo từng layer (pod/service/node) — xem Chapter 53.

Tham Khảo Chính Thức ​