Bin E-Commerce

PLATFORM OPERATIONS

CI/CD và vận hành production

Mục lục trang
Tổng quan hệ thống

Release journey

Một thay đổi đi qua hệ thống như thế nào?

CI bảo vệ chất lượng, registry giữ artifact bất biến, SSM tạo đường vào production và K3s giữ workload đúng trạng thái mong muốn.

Một release đi qua

4 lớp kiểm soát trước khi phục vụ traffic

SourceQualityArtifactRuntime
Release bất biến
Quyền rõ ràng
Có evidence

Luồng tổng quát

Từ source change đến runtime evidence

6 chặng
  1. 01

    Pull Request

    Detect affected services đọc Git diff để xác định service, frontend hoặc hạ tầng cần được kiểm tra.

  2. 02

    CI quality gate

    Lint, type-check, unit test, build, Docker healthcheck và kubeconform chặn lỗi trước artifact.

  3. 03

    Build image + SBOM

    Buildx tạo image theo full SHA; GHCR, Trivy, SBOM và release manifest tạo bằng chứng supply chain.

  4. 04

    Production approval

    GitHub Environment yêu cầu reviewer approve trước khi workflow nhận AWS credential ngắn hạn.

  5. 05

    AWS OIDC → SSM → K3s

    SSM gửi script tới EC2 Online; script kiểm tra Kafka, đổi image bị ảnh hưởng và chờ readiness rollout.

  6. 06

    Observe và rollback

    Prometheus/Grafana, Alloy/Loki và diagnostics xác nhận release; lỗi thì rollback Deployment đã đổi.

Điểm kiểm soát: release chỉ được coi là thành công khi image đúng SHA, Pod Ready và metrics/logs không cho thấy regression rõ ràng.

Tài liệu chi tiết

Đọc theo thứ tự: flow tạo release, công nghệ đứng sau pipeline và các service nhận tác động khi deploy.

1Quy trình CI/CDTách từng flow thực tế để thấy source, artifact, quyền deploy, runtime verification và các boundary không được gộp nhầm.
1.1Luồng hoạt độngMột thay đổi đi từ source đến production qua các flow độc lập: kiểm tra, đóng gói, deploy, quan sát và phục hồi.
1.1.1Luồng CI · kiểm tra sourceCI chạy trên Pull Request và main để xác định phạm vi thay đổi, kiểm tra đúng workload và không chạm production.
  1. Bước01

    Pull Request

    Khi Pull Request được mở hoặc cập nhật, workflow so sánh base commit với head commit. Script đọc danh sách file thay đổi để nhận diện service, frontend, packages/common hoặc manifest hạ tầng đang bị tác động; kết quả này chỉ dùng để chọn job, chưa build image và chưa deploy production.

  2. Bước02

    Xác định service bị ảnh hưởng

    Từ kết quả Git diff, script tạo matrix gồm các service và loại kiểm tra cần chạy. Service độc lập chỉ chạy job của service đó; thay đổi common package, lockfile, root config, workflow hoặc deploy script sẽ mở rộng matrix để không bỏ sót dependency liên quan.

  3. Bước03

    Quality gates theo workload

    Mỗi workload chạy bộ kiểm tra riêng: Node.js/Web có lint, type-check, unit test và build; AI có Ruff, mypy và pytest; Kubernetes render Kustomize rồi validate bằng kubeconform. Chỉ khi các job bắt buộc đều pass, release mới được chuyển sang Build Images.

Bước04

Từ source đến quyết định release

Quality gate hợp nhất

Mục đích

Biết chính xác thay đổi cần kiểm tra

CI không chạy toàn bộ repository cho một thay đổi nhỏ. Việc xác định đúng phạm vi ảnh hưởng giúp phản hồi nhanh hơn, đồng thời vẫn kiểm tra đủ các service có khả năng bị ảnh hưởng.

Dữ liệu đầu vào

Diff, cấu hình và phạm vi ảnh hưởng

Pipeline dùng Git diff, submodule pointer, package/lockfile, root configuration và workflow cùng kết quả detect affected services để chọn đúng nhóm Node.js, Web, AI hoặc Kubernetes.

Điều kiện pass

Tất cả job bắt buộc đều xanh

Node.js và Web phải pass lint, type-check, unit test và build. AI phải pass Ruff, mypy và pytest. Manifest phải render thành công và pass kubeconform strict trước khi release được chuyển sang bước build image.

Đánh đổi & kiểm soát

Tối ưu thời gian nhưng vẫn an toàn

Chạy theo matrix giúp CI nhanh hơn. Để tránh bỏ sót dependency, thay đổi ở common package, lockfile, workflow hoặc deploy script được xem là diện rộng. CI dừng trước GHCR, production secret và lệnh deploy.

PASS·Tất cả job bắt buộc pass; release được phép chuyển sang Build Images.

FAIL·Có job fail; dừng pipeline, đọc log, sửa source rồi chạy lại quality gate.

1.1.2Luồng Build image · tạo release bất biếnSau khi CI trên main pass, Build Images cố định đúng release SHA, build các backend image cần thiết, kiểm tra bảo mật rồi ghi lại quan hệ giữa source, image và digest để production có thể truy nguyên.
  1. Bước01

    Resolve SHA

    Workflow checkout đúng commit đã pass CI trên main và detect lại danh sách workload từ chính commit đó, tránh build nhầm branch hoặc working tree.

  2. Bước02

    Build và push

    Docker Buildx dùng đúng Dockerfile và build context của từng service, tạo image gắn full commit SHA rồi push lên GHCR; frontend vẫn được ghi nhận là Vercel.

  3. Bước03

    Scan và SBOM

    Trivy quét lỗ hổng HIGH/CRITICAL, còn SBOM SPDX ghi lại dependency bên trong image để kiểm tra supply chain và truy nguyên khi có sự cố.

Bước04

Từ image đến release record

Publish release manifest

Mục đích

Khóa artifact để deploy đúng bản đã kiểm tra

Release không dùng tag latest vì tag này có thể trỏ sang nội dung khác. Full commit SHA và digest giúp production luôn chạy đúng image đã được CI build và security scan.

Artifact được tạo

Image, digest, SBOM và kết quả scan

Mỗi service có image reference, digest, kết quả Trivy và SBOM SPDX. Các artifact này được upload cùng release để reviewer và người vận hành có thể đối chiếu sau này.

Điều kiện publish

Build, push và scan đều thành công

Manifest chỉ được tạo sau khi image build thành công, push lên GHCR hoàn tất và policy bảo mật không chặn release. Nếu một service fail, mapping release không được coi là hoàn chỉnh.

Truy nguyên & kiểm soát

Đối chiếu được source với workload đang chạy

Manifest nối release SHA với service, tag và digest. Khi deploy, rollback hoặc điều tra lỗi, đội vận hành dùng record này để xác minh cluster đang chạy đúng artifact đã được phê duyệt.

PASS·Release manifest sẵn sàng cho production approval.

FAIL·Dừng build release, giữ lại bằng chứng lỗi và không deploy image chưa được xác nhận.

1.1.3Luồng Deploy Production · approval và SSMDeploy Production nhận đúng release SHA, yêu cầu reviewer approve rồi dùng OIDC và SSM thay cho SSH trực tiếp vào EC2.
  1. Bước01

    Resolve release

    Chọn đúng release SHA, image reference và danh sách workload cần đưa lên production.

  2. Bước02

    Production approval

    GitHub Environment yêu cầu reviewer xác nhận trước khi workflow được phép chạm vào access boundary production.

  3. Bước03

    OIDC và STS

    GitHub Actions đổi identity thành AWS credential ngắn hạn theo trust policy, không lưu SSH key hoặc access key dài hạn.

Bước04

Từ approval đến production entrypoint

SSM thực thi release đã được phê duyệt

Mục đích

Đưa đúng release vào đúng node

Workflow không SSH trực tiếp vào EC2. Nó dùng release SHA và image reference đã xác định để node production tự thực thi script deploy trong repository.

Quyền truy cập

Approval và credential ngắn hạn

Reviewer chặn release ở GitHub Environment. Sau khi được approve, OIDC cấp AWS STS credential ngắn hạn đúng trust policy của workflow.

Điều kiện thực thi

Node phải Online trong SSM

Workflow kiểm tra PingStatus Online, truyền release metadata và các manifest cần thiết qua AWS-RunShellScript, sau đó poll stdout và stderr.

Đánh đổi & kiểm soát

Không để credential dài hạn trong repository

SSM tạo audit cho command, còn file tạm và secret được giới hạn trong phạm vi cần thiết rồi dọn sau deploy. Trang public không hiển thị account, instance hoặc token thật.

PASS·SSM nhận lệnh và chuyển release vào bước K3s rollout.

FAIL·Dừng trước cluster; kiểm tra approval, OIDC, SSM node và metadata release.

1.1.4Luồng rollout · smoke test và rollbackK3s rollout tuần tự theo dependency, kiểm tra readiness và smoke test; nếu lỗi thì rollback application đã chạm.
  1. Bước01

    Preflight

    Chờ Kafka broker Ready, kiểm tra topic/leader và render Kustomize trước khi thay image application.

  2. Bước02

    Rollout tuần tự

    Đổi image theo dependency order; mỗi Deployment phải pass rollout status trước khi script chuyển sang service kế tiếp.

  3. Bước03

    Smoke test

    Kiểm tra health endpoint, Keycloak discovery và HTTPS để xác nhận runtime hoạt động sau khi Pod đã Ready.

Bước04

Từ rollout đến trạng thái runtime

Chỉ hoàn tất release khi workload thật sự sẵn sàng

Mục đích

Đảm bảo dependency sẵn sàng trước application

Kafka và manifest phải sẵn sàng trước consumer/producer. Rollout tuần tự giúp phát hiện service lỗi ở đúng bước thay vì làm toàn bộ release thất bại khó truy vết.

Thứ tự kiểm tra

Preflight → rollout → smoke test

Script kiểm tra Kafka, đổi image theo service order, chờ readiness rồi mới kiểm tra health endpoint, OIDC discovery và HTTPS. Pod Running một mình chưa đủ để coi là thành công.

Điều kiện pass

Readiness và dependency đều ổn định

Từng Deployment phải pass rollout status trong timeout; các endpoint chính phải phản hồi hợp lệ và không xuất hiện lỗi mới ở consumer hoặc downstream service.

Đánh đổi & kiểm soát

Chậm hơn nhưng rollback có phạm vi rõ

Rollout tuần tự lâu hơn chạy đồng thời nhưng giới hạn blast radius. Khi lỗi, workflow lưu evidence, rollback application đã chạm và không tự ý rollback database migration.

PASS·Các Deployment pass, smoke test hợp lệ và release được bàn giao.

FAIL·Dừng rollout, in diagnostics và rollback workload đã thay đổi.

1.1.5Luồng Deploy Observability · metrics và logsObservability được deploy bằng workflow manual riêng để không restart monitoring theo mỗi application release.
  1. Bước01

    Manual dispatch

    Người vận hành chủ động chạy workflow observability riêng; production Environment vẫn yêu cầu approval trước khi thực thi.

  2. Bước02

    Transfer manifest

    Workflow đóng gói YAML và script, truyền payload an toàn qua SSM rồi dọn file tạm sau khi command kết thúc.

  3. Bước03

    Apply và rollout

    K3s apply namespace, ConfigMap, Service và Deployment/DaemonSet cho Prometheus, Grafana, Loki và Alloy.

Bước04

Từ manifest đến màn hình vận hành

Observability sẵn sàng để theo dõi application

Mục đích

Tách monitoring khỏi application release

Observability thay đổi chậm hơn backend nên có workflow manual và audit riêng. Application deploy không cần restart Prometheus, Grafana, Loki hoặc Alloy theo mỗi image build.

Thành phần triển khai

Metrics, logs và giao diện truy vấn

Prometheus thu metrics, Loki lưu logs, Alloy chuyển container logs và Grafana làm giao diện truy vấn. Các workload nằm trong namespace observability riêng.

Điều kiện pass

Workload Ready và datasource hoạt động

Manifest apply thành công, Deployment/DaemonSet pass rollout, Grafana nhìn thấy Prometheus và Loki làm datasource để người vận hành có thể kiểm tra dữ liệu.

Đánh đổi & kiểm soát

Ổn định hơn nhưng cần dispatch có chủ đích

Workflow riêng giảm restart không cần thiết nhưng yêu cầu người vận hành chọn đúng release và approval. Public showcase chỉ mô tả kiến trúc, không hiển thị endpoint hoặc credential thật.

PASS·Stack observability Ready và Grafana truy vấn được metrics/logs.

FAIL·Dừng rollout, kiểm tra manifest, datasource, PVC và logs của monitoring workload.

1.1.6Luồng Frontend · VercelWeb được kiểm tra trong CI nhưng deploy bằng Vercel, tách khỏi image backend và K3s application namespace.
  1. Bước01

    Web quality gate

    Khi web bị ảnh hưởng, CI chạy lint, type-check, unit test và Next.js build trước khi branch main được tiếp tục.

  2. Bước02

    Vercel build

    Vercel nhận source từ branch main, build frontend bằng environment production riêng và quản lý deployment ở boundary độc lập.

  3. Bước03

    Không vào K3s

    Frontend không tạo backend image, không gửi qua GHCR và không nằm trong rollout application trên EC2/K3s.

Bước04

Boundary frontend và backend

Frontend deploy độc lập với K3s

Mục đích

Tách vòng đời giao diện khỏi backend

Frontend có thể build và phát hành qua Vercel mà không cần đóng gói thành image hoặc chờ application namespace rollout xong.

Dữ liệu đầu vào

Source web và environment phù hợp

CI kiểm tra source web; Vercel nhận branch main và dùng environment frontend đã cấu hình. Trang public không mô tả hoặc hiển thị giá trị secret.

Điều kiện pass

Build Next.js và smoke test hợp lệ

Web phải pass quality gate, Vercel build thành công và frontend HTTPS phản hồi được sau khi phát hành.

Đánh đổi & kiểm soát

Boundary độc lập, rollback độc lập

Frontend smoke fail không tự động rollback backend K3s. Hai boundary được kiểm tra và khôi phục theo quy trình riêng để tránh rollback nhầm workload.

PASS·Frontend được Vercel build và truy cập được qua HTTPS.

FAIL·Dừng ở frontend boundary; không rollback application K3s tự động.

1.1.7Luồng bootstrap Data Infrastructure · Kafka và KeycloakKafka và Keycloak là hạ tầng data/identity được bootstrap có chủ đích, không bị apply lại trong mỗi application deploy.
  1. Bước01

    Review manifest

    Data infrastructure chỉ apply hoặc upgrade sau khi review manifest, compatibility và kế hoạch backup phù hợp.

  2. Bước02

    Kafka và Keycloak Ready

    Kiểm tra broker, topic leader và OIDC provider sẵn sàng trước khi consumer, API hoặc workflow rollout cần đến chúng.

  3. Bước03

    Không gộp application deploy

    Application rollout chỉ preflight dependency; không tự ý apply Kafka, Keycloak hoặc runtime secret trong mỗi release.

Bước04

Boundary data và identity infrastructure

Dependency nền tảng được bootstrap có chủ đích

Mục đích

Ổn định dependency trước application

Kafka và Keycloak có vòng đời riêng. Tách bootstrap giúp application release chỉ kiểm tra dependency đã sẵn sàng thay vì thay đổi hạ tầng dữ liệu trong mỗi lần deploy.

Dữ liệu cần kiểm tra

Broker, topic, leader và OIDC

Kafka cần broker Ready và topic/leader hoạt động; Keycloak cần OIDC discovery phản hồi để các service xác thực được identity và token.

Điều kiện pass

Dependency phản hồi trước rollout

Preflight xác nhận Kafka broker, topic và Keycloak discovery trước khi rollout consumer hoặc API. Nếu dependency chưa sẵn sàng, application không nên tiếp tục đổi image.

Đánh đổi & kiểm soát

Không tự động thay đổi data layer

Tách workflow giảm rủi ro apply nhầm hạ tầng nhưng yêu cầu operator quản lý manifest, backup và compatibility riêng. Runtime secret không được đưa vào tài liệu public.

PASS·Kafka/Keycloak Ready và application có thể chạy preflight.

FAIL·Dừng application rollout; xử lý dependency trước, không xóa dữ liệu tự động.

1.2Công nghệ CI/CD và vận hànhCác công nghệ biến commit thành artifact bất biến, đưa release vào K3s và cung cấp metrics để kiểm tra production.
  • GitHub ActionsCI workflow
  • Docker BuildxBuild image
  • AWS OIDC + SSMSecure deploy access
  • K3sKubernetes runtime
  • Kubernetes + KustomizeManifest & overlay
  • PrometheusMetrics
  • GrafanaDashboards

Artifact và logs: GHCR lưu image theo commit SHA; Trivy và SBOM kiểm tra supply chain; Loki và Alloy tập trung log container để Grafana Explore tra cứu.

2Kiến trúc production và quản lý K3sRelease được approve đi qua quyền truy cập ngắn hạn, SSM và EC2 trước khi trở thành workload được K3s quản lý.
2.1K3s giải quyết những bài toán gì?Các card dưới đây mô tả đúng những gì manifest, workflow và runbook hiện tại đang xử lý; phần giới hạn hoặc hạng mục sẽ triển khai thêm được ghi ngay trong nội dung.
01 · Self-healing

Container crash không làm service dừng vĩnh viễn

Application đang chạy bằng Deployment có replica và probe. Khi Pod hoặc process lỗi, controller của K3s sẽ tạo Pod thay thế theo template. Đây là self-healing ở mức workload; single-node EC2 chưa có HAkhi chính node bị hỏng.

02 · Desired state

Giữ đúng số replica và image mong muốn

Manifest và script deploy đã khai báo replica, image, cấu hình và Pod template. Release dùng full commit SHA, sau đó kiểm tra rollout. Autoscaling/HPA chưa triển khai; số replica hiện được điều chỉnh chủ động.

03 · Service discovery

Service không phụ thuộc IP Pod

Các service application và data đã có Service + DNS nội bộ, ví dụ workload gọi Kafka/Keycloak qua tên Service trong cluster. Selector trỏ đến Pod phù hợp, nên Pod thay mới không làm downstream phải biết IP mới.

04 · Safe rollout

Release mới không nhận traffic quá sớm

Các Deployment đã khai báo readiness/liveness probe; script deploy chờ rollout status trước khi kết thúc release. Nếu revision mới lỗi, workflow có chẩn đoán và rollback image application. Đây chưa phải cam kết zero downtime vì workload hiện chủ yếu 1 replica.

05 · Boundary

Tách application, data và observability

Repository đã tách namespace và manifest cho application, data và observability; observability cũng có script deploy riêng. Tuy nhiên, NetworkPolicy, quota và RBAC phân tách chặt chưa triển khai đầy đủ, nên namespace hiện chủ yếu là boundary quản lý và chẩn đoán.

06 · Operations

Có một cách chuẩn để debug workload

Runbook đã có luồng chuẩn bằng kubectl, Events, logs, probes và script chẩn đoán; Prometheus, Grafana, Loki và Alloy cũng đã có manifest. Alert routing ra kênh ngoài và distributed tracing chưa triển khai, nên phần quan sát hiện tập trung vào metrics, logs và readiness.

2.2Artifact và quyền deployRelease được khóa từ commit đã CI pass đến image digest và approval; production luôn biết chính xác artifact nào được phép chạy.

Khái niệm cốt lõi

Artifact và quyền deploy là gì?

Artifact là gì?

Artifact là sản phẩm đã được CI kiểm tra và đóng gói để chạy, ở đây gồm Docker image, tag SHA, digest và release manifest. Production pull đúng artifact này thay vì build lại từ source hoặc dùng tag có thể bị đổi.

Quyền deploy là gì?

Đây là điều kiện để một workflow được phép đưa artifact vào production. Workflow phải gắn với release SHA, qua GitHub Environment approval rồi mới gửi lệnh deploy; Pull Request chưa được approve không tự chạy production.

Nói ngắn gọn: CI tạo và kiểm tra artifact, còn approval quyết định artifact nào được phép chạy. Commit SHA/digest giúp truy nguyên source và rollback về đúng phiên bản khi có sự cố.

Commit → release

Từ commit SHA đến release manifest

Mỗi bước bàn giao một evidence rõ ràng để production biết chính xác source và artifact nào đang được triển khai.

  1. Bước01

    Full commit SHA

    Workflow chốt full 40-character SHA của commit đã CI pass và checkout đúng commit đó. Nhờ vậy Build Images không build nhầm working tree hoặc tag latest.

  2. Bước02

    Docker image

    Build Images đóng gói đúng service bị ảnh hưởng, tạo image reproducible và gắn tag bằng full commit SHA để có thể truy ngược về source.

  3. Bước03

    GHCR + digest

    GHCR lưu image cùng digest bất biến. Node production pull đúng artifact đã scan thay vì tự build lại hoặc nhận một tag có thể bị đổi.

  4. Bước04

    Release manifest

    Manifest ghi mapping giữa service, image tag, digest và release SHA. Đây là bằng chứng để biết release đang chạy thành phần nào.

  5. Bước05

    Production approval

    Deploy Production chỉ tiếp tục sau khi reviewer kiểm tra release SHA và approve GitHub Environment production; Pull Request không tự deploy.

2.3AWS OIDC và SSMWorkflow không SSH trực tiếp vào EC2: OIDC tạo identity, STS cấp quyền ngắn hạn và SSM chuyển lệnh deploy đến node production.

Khái niệm cốt lõi

AWS OIDC và SSM dùng để làm gì?

OIDC và STS: cấp quyền tạm thời

GitHub Actions dùng OIDC để chứng minh workflow đến từ repository và environment hợp lệ. AWS STS kiểm tra identity đó rồi cấp credential ngắn hạn theo IAM role, thay vì lưu AWS access key dài hạn trong GitHub Secrets.

SSM: gửi lệnh đến EC2

AWS Systems Manager kiểm tra node có đang Online không, sau đó gửi script deploy đến EC2 qua SSM Run Command. EC2 không cần mở SSH public và workflow có thể theo dõi trạng thái lệnh từ xa.

Nói ngắn gọn: OIDC/STS trả lời “workflow này có được cấp quyền không?”, còn SSM trả lời “gửi script đến node production bằng cách nào?”. Hai lớp này giúp tách quyền AWS khỏi việc thực thi workload trên EC2/K3s.

GitHub Actions → EC2

Đường vào production có kiểm soát

Mỗi node trong flow có một trách nhiệm riêng: cấp quyền, kiểm tra node và thực thi script deploy.

  1. Bước01

    GitHub Actions

    Điều phối release sau khi CI và Build Images thành công; workflow giữ release SHA, danh sách service và manifest làm đầu vào deploy.

  2. Bước02

    GitHub OIDC

    Cung cấp identity có thể xác minh cho workflow; repository không cần lưu AWS access key dài hạn trong GitHub Secrets.

  3. Bước03

    AWS STS

    Đổi OIDC token thành credential AWS ngắn hạn theo IAM role. Credential chỉ dùng trong thời gian workflow và đúng quyền được cấp.

  4. Bước04

    SSM Online check

    Kiểm tra instance production đang Online trong Systems Manager trước khi gửi lệnh; nếu node offline, workflow dừng trước bước deploy.

  5. Bước05

    AWS-RunShellScript

    SSM truyền script, release metadata và image reference đã kiểm tra đến EC2 để node tự chạy K3s rollout theo đúng thứ tự.

2.4Quản lý workload trên K3sK3s là runtime điều phối container trên EC2: từ node health, Pod diagnostics đến rollout, rollback và runtime debug.

Đọc trước khi quản trị

K3s là gì và hoạt động như thế nào?

K3s là bản Kubernetes gọn nhẹ dùng để điều phối container trên node EC2. Bạn khai báo trạng thái mong muốn bằng manifest; K3s liên tục so sánh trạng thái thật với trạng thái đó rồi tạo, thay thế hoặc route workload cho phù hợp.

Hiểu đơn giản bằng một ví dụ

EC2 là máy chủ, K3s là người điều phối, Deployment là bản mô tả cần chạy bao nhiêu phiên bản, Pod là nơi chạy container và Service là địa chỉ ổn định để các workload gọi nhau.

Vòng lặp tự phục hồi

Khi một container hoặc Pod lỗi, controller phát hiện desired state bị thiếu và yêu cầu tạo Pod thay thế. Pod mới chỉ nhận traffic sau khi readiness probe thành công.

01 · Node

EC2 Ubuntu

Máy thật hoặc máy ảo cung cấp CPU, memory, disk và network. Với mô hình hiện tại, production chạy trên single-node nên node hỏng có thể ảnh hưởng toàn bộ workload.

02 · Cluster

K3s control plane

Lớp điều phối nhận manifest, theo dõi resource và ra quyết định scheduling, rollout, restart hoặc thay thế Pod.

03 · Runtime

containerd

Runtime thực sự pull image và chạy container trên node. Docker chủ yếu được dùng để build image ở CI/local, không phải lớp điều phối production.

04 · Boundary

Namespace

Nhóm resource theo trách nhiệm như application, data và observability để lệnh kiểm tra, manifest và quyền quản trị dễ khoanh vùng hơn.

05 · Desired state

Deployment và ReplicaSet

Deployment lưu image, replica và Pod template; ReplicaSet duy trì đúng số Pod theo cấu hình và tạo revision khi release thay đổi.

06 · Workload

Pod và Container

Pod là đơn vị được schedule; container bên trong chạy API hoặc worker. Pod Running chỉ cho biết process đang chạy, chưa chắc đã sẵn sàng nhận traffic.

07 · Networking

Service và Endpoint

Service cung cấp DNS nội bộ và selector đến Pod phù hợp, giúp workload gọi nhau qua tên ổn định thay vì lưu Pod IP.

08 · Health gate

Readiness, liveness và startup

Readiness quyết định có nhận traffic hay không; liveness phát hiện process treo; startup cho ứng dụng cần thời gian khởi động lâu.

09 · Change

Rollout và rollback

Rollout đưa revision mới vào theo từng bước; rollback quay về revision application trước khi release mới không đạt health hoặc smoke test.

2.4.1K3s quản lý container như thế nào?EC2 cung cấp máy chủ; K3s duy trì trạng thái mong muốn của Deployment, Pod, Container và Service.

EC2 → K3s → workload

Từ node đến container ready

EC2 cung cấp máy chủ; K3s control plane điều phối containerd, workload và Service. Chỉ Pod vượt qua readiness mới được nhận traffic.

  1. Bước01

    EC2 Ubuntu

    Cung cấp CPU, memory, disk và network để K3s có nơi chạy workload production.

  2. Bước02

    K3s control plane

    Điều phối desired state, scheduling và controller reconciliation trên node single-node.

  3. Bước03

    containerd runtime

    K3s dùng containerd để pull image, tạo container và quản lý process; Docker chỉ là công cụ build image ở CI/local.

  4. Bước04

    Namespace

    Phân tách application, data, observability và system boundary để quản lý quyền và diagnostics.

  5. Bước05

    Deployment → ReplicaSet

    Deployment giữ replica, image version và Pod template; ReplicaSet bảo đảm đủ số Pod theo desired state.

  6. Bước06

    Pod → Container

    Pod là đơn vị được schedule; bên trong Pod, container chạy application hoặc worker với probe và resource limit.

  7. Bước07

    Service endpoint

    Cung cấp DNS nội bộ, chọn Pod bằng selector và chỉ route traffic đến Pod đã pass readiness.

2.4.2Kiểm tra node và clusterBắt đầu từ trạng thái K3s và node trước khi kiểm tra Pod hoặc service cụ thể.

01 · Node health

Kiểm tra K3s service và node

Xác nhận K3s đang chạy và node có thể schedule workload.

sudo systemctl status k3s
sudo k3s kubectl version
sudo k3s kubectl cluster-info
sudo k3s kubectl get nodes -o wide
sudo k3s kubectl describe node <node-name>

Kết quả cần đọc

Node cần có trạng thái Ready; đọc Conditions, taint, capacity và allocatable khi có lỗi scheduling.

02 · Cluster inventory

Xem namespace và resource tổng quát

Có cái nhìn nhanh về workload đang tồn tại trên cluster.

sudo k3s kubectl get namespaces
sudo k3s kubectl get pods --all-namespaces -o wide
sudo k3s kubectl get deployments -A
sudo k3s kubectl get services -A
sudo k3s kubectl get ingress -A

Kết quả cần đọc

Dùng output để xác định namespace, Pod, Deployment hoặc Ingress đang có vấn đề trước khi đi sâu hơn.

2.4.3Kiểm tra namespace và workloadĐi theo thứ tự Deployment → ReplicaSet → Pod → Container → Service endpoint để tìm đúng lớp đang lỗi.

01 · Workload detail

Kiểm tra một service cụ thể

Xác định image, replica, condition và Pod thuộc về Deployment.

sudo k3s kubectl get deployment <deployment-name> \
  -n <namespace> -o wide

sudo k3s kubectl get pods \
  -n <namespace> \
  -l app.kubernetes.io/name=<service-name> \
  -o wide

sudo k3s kubectl get service <service-name> \
  -n <namespace>

Kết quả cần đọc

Đối chiếu desired replicas, available replicas, Pod IP, image SHA và selector của Service.

02 · Resource detail

Describe Deployment và Pod

Đọc condition, probe, scheduling message, image pull và các event gắn với workload.

sudo k3s kubectl describe deployment <deployment-name> \
  -n <namespace>

sudo k3s kubectl describe pod <pod-name> \
  -n <namespace>

Kết quả cần đọc

Tập trung vào Events ở cuối output, readiness/liveness probe, container state và image reference.

2.4.4Đọc logs và chẩn đoán lỗiLogs cho biết process chết vì lý do gì; Events cho biết Kubernetes đã làm gì trước và sau lỗi đó.

01 · Container logs

Đọc logs hiện tại và logs trước khi crash

Bắt đầu bằng log gần đây, sau đó đọc instance trước nếu Pod restart.

sudo k3s kubectl logs <pod-name> \
  -n <namespace> \
  --since=10m

sudo k3s kubectl logs <pod-name> \
  -n <namespace> \
  -c <container-name> \
  --tail=200

sudo k3s kubectl logs <pod-name> \
  -n <namespace> \
  -c <container-name> \
  --previous

Kết quả cần đọc

--since giới hạn thời gian, --tail giới hạn số dòng, còn --previous đọc container instance trước khi crash.

02 · Container shell

Exec vào container để kiểm tra sâu

Kiểm tra filesystem, process và network khi logs chưa đủ thông tin.

sudo k3s kubectl exec -it <pod-name> \
  -n <namespace> \
  -c <container-name> \
  -- sh

Kết quả cần đọc

Chỉ kiểm tra runtime cần thiết; không in environment có secret và không sửa dữ liệu production trực tiếp trong container.

03 · Events

Đọc event theo thời gian

Tìm nguyên nhân scheduling, image pull, mount, probe hoặc eviction.

sudo k3s kubectl get events \
  -n <namespace> \
  --sort-by=.lastTimestamp

sudo k3s kubectl get events \
  --all-namespaces \
  --sort-by=.lastTimestamp

Kết quả cần đọc

Event mới nhất thường giúp phân biệt lỗi image, thiếu resource, PVC, probe hoặc dependency.

CrashLoopBackOff

logs --previous → describe Pod → kiểm tra ConfigMap, Secret và dependency.

ImagePullBackOff

Kiểm tra image SHA → ghcr-pull-secret → quyền pull image.

Running nhưng NotReady

Kiểm tra readiness probe → health endpoint → Kafka, database hoặc downstream.

Pending

Kiểm tra node resource → PVC → scheduling events.

2.4.5Rollout và release workloadMỗi thay đổi image phải gắn với commit SHA, được theo dõi rollout và xác nhận readiness sau khi apply.

01 · Rollout status

Theo dõi Deployment sau thay đổi

Xác nhận ReplicaSet mới đã tạo đủ Pod và Pod mới đã Available.

sudo k3s kubectl rollout status \
  deployment/<deployment-name> \
  -n <namespace> \
  --timeout=180s

sudo k3s kubectl rollout history \
  deployment/<deployment-name> \
  -n <namespace>

sudo k3s kubectl wait \
  --for=condition=available \
  deployment/<deployment-name> \
  -n <namespace> \
  --timeout=180s

Kết quả cần đọc

Rollout chỉ thành công khi Deployment Available và readiness của Pod đạt yêu cầu.

02 · Image và replica

Đổi image hoặc scale workload

Dùng image full commit SHA hoặc digest; không dùng latest trong production.

sudo k3s kubectl set image \
  deployment/<deployment-name> \
  <container-name>=<registry>/<image>:<full-commit-sha> \
  -n <namespace>

sudo k3s kubectl scale deployment/<deployment-name> \
  --replicas=<replica-count> \
  -n <namespace>

Kết quả cần đọc

Sau khi set image hoặc scale, luôn chạy rollout status và kiểm tra Pod mới.

03 · Restart có kiểm soát

Restart Deployment

Tạo rollout mới khi cần reload image, config hoặc xử lý process bị treo.

sudo k3s kubectl rollout restart \
  deployment/<deployment-name> \
  -n <namespace>

sudo k3s kubectl rollout status \
  deployment/<deployment-name> \
  -n <namespace> \
  --timeout=180s

Kết quả cần đọc

Restart không thay đổi image; cần kiểm tra nguyên nhân trước nếu workload đang CrashLoopBackOff.

2.4.6Apply manifest và KustomizeRender manifest trước để phát hiện lỗi YAML, reference hoặc overlay; sau đó mới apply đúng boundary.

01 · Render

Kiểm tra manifest trước khi apply

Xem output Kustomize và phát hiện lỗi trước khi thay đổi cluster.

sudo k3s kubectl kustomize \
  --load-restrictor LoadRestrictionsNone \
  <manifest-path>

Kết quả cần đọc

Manifest phải render thành công; application và observability dùng path/boundary riêng.

02 · Apply

Apply overlay vào cluster

Áp dụng manifest đã review vào namespace hoặc overlay tương ứng.

sudo k3s kubectl apply -k <manifest-path>

sudo k3s kubectl get deployments -n <namespace>
sudo k3s kubectl get pods -n <namespace>
sudo k3s kubectl get events -n <namespace> \
  --sort-by=.lastTimestamp

Kết quả cần đọc

Không apply toàn bộ data infrastructure trong application rollout; kiểm tra rollout ngay sau apply.

2.4.7Rollback workloadRollback application image khi rollout không đạt; database migration không được rollback tự động.

Recovery · Application

Quay về revision trước

Dùng khi Pod mới crash, readiness fail hoặc smoke test không đạt.

sudo k3s kubectl rollout undo \
  deployment/<deployment-name> \
  -n <namespace>

sudo k3s kubectl rollout status \
  deployment/<deployment-name> \
  -n <namespace> \
  --timeout=180s

sudo k3s kubectl describe deployment <deployment-name> \
  -n <namespace>

Kết quả cần đọc

Sau rollback cần kiểm tra Pod readiness, health endpoint, logs và dependency chính.

Cảnh báo

Rollback image không hoàn tác database migration. Migration phải tương thích ngược với release trước.

2.4.8Container runtime nâng caoChỉ dùng crictl khi cần kiểm tra containerd hoặc container đã biến mất khỏi Pod view.

Debug nâng cao · containerd

Kiểm tra container runtime của K3s

Đối chiếu container ID, image local và runtime logs khi kubectl không còn đủ thông tin.

sudo k3s crictl ps
sudo k3s crictl ps -a
sudo k3s crictl images
sudo k3s crictl logs <container-id>
sudo k3s crictl inspect <container-id>

Kết quả cần đọc

Ưu tiên kubectl logs, describe và events; crictl chỉ dành cho sự cố containerd hoặc container lifecycle.

2.4.9Thay đổi và xóa resourceCác lệnh quản trị đầy đủ được đặt riêng để người đọc nhận diện rõ thao tác có thể làm thay đổi hoặc mất dữ liệu.

Danger zone · destructive actions

Xóa resource bằng placeholder

Chỉ dùng sau khi đã xác định chính xác resource, namespace và hậu quả của thao tác.

sudo k3s kubectl delete pod <pod-name> -n <namespace>
sudo k3s kubectl delete deployment <deployment-name> -n <namespace>
sudo k3s kubectl delete job <job-name> -n <namespace>
sudo k3s kubectl delete secret <secret-name> -n <namespace>
sudo k3s kubectl delete pvc <pvc-name> -n <namespace>
sudo k3s kubectl delete namespace <namespace>

Kết quả cần đọc

Sau thao tác phải kiểm tra resource, events và dependency liên quan; không dùng lệnh xóa như bước debug đầu tiên.

Cảnh báo

delete PVC, Secret hoặc Namespace có thể làm mất dữ liệu hoặc khiến workload không khởi động. Không xóa Secret để xử lý CrashLoopBackOff.

2.5Namespace và boundaryMỗi namespace gom một nhóm workload có cùng trách nhiệm để deploy, kiểm tra và phân quyền rõ hơn; namespace không tự biến single-node thành HA hay thay thế NetworkPolicy.

01 · Application

Nhận request và chạy business workload

02 · Data

Cung cấp dependency nội bộ

03 · Observability

Thu metrics và logs để kiểm tra

04 · System

Thành phần nền của K3s

Namespace giúp người vận hành khoanh vùng lệnh get, logs, events và rollout đúng nhóm workload. Đây là boundary quản lý trong cluster; muốn cô lập network hoặc quyền truy cập chặt hơn vẫn cần cấu hình NetworkPolicy và RBAC riêng.

Namespace

bin-ecommerce-app

Vai trò

Chạy request path và các service/worker phục vụ nghiệp vụ commerce.

Workload hiện tại

API Gateway, backend services, AI service và AI workers được khai báo bằng Deployment/Service.

Boundary cần nhớ

Application gọi dependency qua Service DNS; không đặt Kafka, Keycloak hoặc stack monitoring vào đây.

Namespace

bin-ecommerce-data

Vai trò

Cung cấp dependency stateful hoặc identity mà application cần dùng trong cluster.

Workload hiện tại

Kafka chạy bằng StatefulSet; Keycloak chạy bằng Deployment và Service.

Boundary cần nhớ

Application kết nối qua DNS như kafka.bin-ecommerce-data.svc.cluster.local; database managed bên ngoài không được gọi là workload ở namespace này.

Namespace

bin-ecommerce-observability

Vai trò

Thu thập metrics/logs và cung cấp dashboard để kiểm tra node, Pod và rollout.

Workload hiện tại

Prometheus, Grafana, Loki, kube-state-metrics, Node Exporter và Alloy có manifest riêng.

Boundary cần nhớ

Stack được deploy bằng workflow/script observability riêng; Prometheus và Loki không mở public trực tiếp.

Namespace

kube-system

Vai trò

Dành cho thành phần nền do K3s và cluster sử dụng để vận hành workload.

Workload hiện tại

Không phải nơi đặt API, worker hoặc data dependency của business application.

Boundary cần nhớ

Không apply manifest application vào đây; khi debug cần phân biệt lỗi system component với lỗi workload.

2.6Traefik và TLSTraffic public đi qua Vercel và Traefik trước khi đến API Gateway; các dependency nội bộ không được public trực tiếp.

Khái niệm cốt lõi

Traefik và TLS là gì?

Traefik làm gì?

Traefik là Ingress Controller của K3s. Nó đọc rule Ingress, nhận request từ Internet, kiểm tra host/path rồi chuyển request đến Service đúng, thay vì public từng Pod hoặc từng service nội bộ.

TLS làm gì?

TLS mã hóa kết nối HTTPS và xác nhận domain đang truy cập. Trong manifest hiện tại, cert-manager dùng ACME HTTP-01 để tạo và gia hạn TLS certificate/Secret cho Ingress đã cấu hình.

Nói ngắn gọn: Traefik quyết định request đi vào đâu, còn TLS bảo vệ kết nối trên đường đi. Hai phần này không thay thế authentication hoặc authorization của API Gateway.

Public traffic

Từ client đến application Pod

Traefik nhận HTTPS và chuyển request đến Service; Service chỉ route đến Pod đã vượt qua readiness.

  1. Bước01

    Client + Vercel

    Vercel phục vụ frontend và gọi backend qua public HTTPS endpoint; frontend không chạy như workload trong K3s.

  2. Bước02

    Traefik Ingress

    Nhận HTTPS, route host/path và chuyển traffic đến API Gateway thay vì public từng service nội bộ.

  3. Bước03

    cert-manager

    Quản lý vòng đời TLS certificate cho Ingress được cấu hình và hỗ trợ gia hạn trước khi hết hạn.

  4. Bước04

    API Gateway Service

    Là cửa vào public duy nhất của backend, xác thực request và route đến downstream service phù hợp.

  5. Bước05

    Application Pod

    Chỉ xử lý request khi Pod Ready và các dependency chính đã sẵn sàng; Pod Running đơn thuần chưa đủ.