Triển Khai ASP.NET Core Lên Kubernetes với Helm: Chặng Đường Tiếp Theo trong Lộ Trình .NET

Compose trên một VM là đủ cho tới khi bạn cần ba replica, deploy không downtime và tự scale theo tải. Lúc đó bạn cần một scheduler — và Kubernetes không tặng kèm sự đơn giản. Bài này dựng Deployment, Service, Ingress, probe, HPA và graceful shutdown cho một API .NET 10, rồi đóng gói bằng Helm 3 để cấu hình theo môi trường mà không copy-paste YAML.

Cập nhật 2026

  • kubectl 1.34/1.35 là mốc hiện hành; autoscaling/v2 là API duy nhất còn dùng cho HPA (các bản v2beta đã bị gỡ).
  • Helm 3 với chart apiVersion: v2. Output của helm create vẫn là scaffold, không phải chart production-ready — nó tạo ServiceAccount, HPA, Ingress, test hook mà app của bạn có thể không cần.
  • Ingress vẫn là chuẩn thực tế, nhưng Gateway API là hướng kế tiếp; đừng dựng thêm lớp trừu tượng riêng quanh Ingress nếu chưa có nhiều team.
  • .NET 10: HostOptions.ShutdownTimeout và health check tags là hai thứ phải khớp với terminationGracePeriodSeconds, nếu không rolling update vẫn rớt request.

Mô hình: trạng thái mong muốn, không phải lệnh

Bạn không “chạy container” trên Kubernetes. Bạn khai báo trạng thái mong muốn, control loop so sánh với trạng thái thực và tự điều chỉnh. Hệ quả thực dụng: mọi thứ bạn muốn tồn tại phải nằm trong manifest, vì thứ sửa bằng kubectl exec sẽ bị ghi đè ở lần reconcile sau.

  • Pod: một hoặc nhiều container dùng chung network namespace. Với .NET, gần như luôn là một container.
  • Deployment: quản lý ReplicaSet, giữ số Pod mong muốn và thực hiện rolling update. Đơn vị bạn làm việc hàng ngày.
  • Service: địa chỉ ổn định + load balancing tới các Pod khớp selector. Chỉ Pod ready mới được đưa vào endpoint.
  • Ingress: routing HTTP từ ngoài vào Service, cần một ingress controller (nginx, Traefik, Envoy Gateway).

Điểm nối giữa .NET và Kubernetes là readiness. Nếu app báo ready quá sớm, traffic vào Pod chưa nạp xong cấu hình; nếu báo ready quá muộn, rollout kẹt. Đây là lý do health check phải tách hai khái niệm, không phải một endpoint /health dùng cho cả hai.

Health check đúng vai trong ASP.NET Core

// File: Shop.Api/Program.cs
builder.Services.AddHealthChecks()
    .AddCheck("self", () => HealthCheckResult.Healthy(), tags: ["live"])
    .AddDbContextCheck<ShopDbContext>("db", tags: ["ready"]);

builder.Services.Configure<HostOptions>(
    o => o.ShutdownTimeout = TimeSpan.FromSeconds(25));

var app = builder.Build();

app.MapHealthChecks("/health/live", new HealthCheckOptions
{
    Predicate = r => r.Tags.Contains("live")
});
app.MapHealthChecks("/health/ready", new HealthCheckOptions
{
    Predicate = r => r.Tags.Contains("ready")
});

AddDbContextCheck nằm trong package Microsoft.Extensions.Diagnostics.HealthChecks.EntityFrameworkCore. Hai endpoint có chi phí rất khác nhau, và điều đó quyết định probe nào được gọi bao lâu một lần:

  • liveness phải rẻ và không phụ thuộc dependency ngoài. Nếu liveness kiểm tra database, một sự cố DB làm toàn bộ Pod bị restart — biến sự cố hạ tầng thành vòng restart.
  • readiness được phép kiểm tra DB, cache, migration đã chạy. Nó chỉ rút Pod khỏi endpoint, không restart.
  • startupProbe bảo vệ app khởi động chậm (migration, warm-up): trong lúc startup probe chưa pass, liveness bị hoãn. Nhờ vậy không cần initialDelaySeconds đoán mò.

Deployment: phần lớn sự cố nằm ở đây

apiVersion: apps/v1
kind: Deployment
metadata:
  name: shop-api
spec:
  replicas: 3
  revisionHistoryLimit: 5
  minReadySeconds: 10
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 1
      maxUnavailable: 0
  selector:
    matchLabels:
      app: shop-api
  template:
    metadata:
      labels:
        app: shop-api
    spec:
      terminationGracePeriodSeconds: 40
      securityContext:
        runAsNonRoot: true
        seccompProfile:
          type: RuntimeDefault
      containers:
        - name: api
          image: ghcr.io/evotek/shop-api@sha256:0000000000000000000000000000000000000000000000000000000000000000
          ports:
            - containerPort: 8080
          envFrom:
            - configMapRef:
                name: shop-api-config
            - secretRef:
                name: shop-api-secrets
          resources:
            requests:
              cpu: "250m"
              memory: "256Mi"
            limits:
              memory: "512Mi"
          startupProbe:
            httpGet:
              path: /health/live
              port: 8080
            periodSeconds: 2
            failureThreshold: 30
          readinessProbe:
            httpGet:
              path: /health/ready
              port: 8080
            periodSeconds: 5
            failureThreshold: 2
          livenessProbe:
            httpGet:
              path: /health/live
              port: 8080
            periodSeconds: 15
            failureThreshold: 3
          lifecycle:
            preStop:
              exec:
                command: ["sleep", "8"]
          securityContext:
            allowPrivilegeEscalation: false
            readOnlyRootFilesystem: true
            capabilities:
              drop: ["ALL"]

Những quyết định trong file này, và lý do:

  • maxUnavailable: 0, maxSurge: 1: Pod mới phải ready trước khi Pod cũ bị bỏ. Đây là điều kiện cần của zero downtime, không phải điều kiện đủ.
  • requests không kèm CPU limit: CPU limit cứng gây throttling và làm latency tăng đúng lúc tải cao. Đặt request đúng, giới hạn memory, và để node tự chia CPU. Nếu compliance bắt buộc CPU limit, đặt nó cao hơn request ít nhất 2 lần.
  • memory limit = 2× request: .NET đọc cgroup limit để cấu hình GC, nên limit memory là tín hiệu thật cho runtime; đừng đặt sát request hoặc OOM sẽ đến trước khi scale kịp.
  • readOnlyRootFilesystem: true: nhiều app .NET ghi temp file vào /tmp; nếu vậy phải mount emptyDir cho /tmp, không thì app chết với lỗi quyền ghi.
  • image pin theo digest: tag có thể bị ghi đè, digest thì không. Đây là điểm mà rollback dựa vào.

Service, Ingress và HPA

apiVersion: v1
kind: Service
metadata:
  name: shop-api
spec:
  type: ClusterIP
  selector:
    app: shop-api
  ports:
    - name: http
      port: 80
      targetPort: 8080
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: shop-api
  annotations:
    nginx.ingress.kubernetes.io/proxy-body-size: "10m"
spec:
  ingressClassName: nginx
  tls:
    - hosts: ["api.example.com"]
      secretName: shop-api-tls
  rules:
    - host: api.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: shop-api
                port:
                  number: 80

Ingress không có ý nghĩa nếu cluster chưa cài controller; ingressClassName phải khớp tên controller. Với HPA, scale theo CPU là mặc định nhưng thường sai: API .NET bị giới hạn bởi I/O và connection pool trước khi CPU đầy. Nếu có metrics request/giây, dùng custom metrics hoặc KEDA; nếu không, CPU 70% vẫn là điểm bắt đầu hợp lý.

apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: shop-api
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: shop-api
  minReplicas: 3
  maxReplicas: 20
  metrics:
    - type: Resource
      resource:
        name: cpu
        target:
          type: Utilization
          averageUtilization: 70
  behavior:
    scaleDown:
      stabilizationWindowSeconds: 300
      policies:
        - type: Percent
          value: 50
          periodSeconds: 60

minReplicas: 3 không phải con số may mắn: hai replica đủ cho một Pod bảo trì, ba replica cho phép mất một Pod trong lúc rollout mà vẫn còn hai. Cửa sổ scaleDown 300 giây tránh việc scale lên xuống theo từng đợt spike — scale down sớm rồi phải scale up lại còn tệ hơn không scale.

Zero downtime: SIGTERM là hợp đồng, không phải lời khuyên

Khi xoá Pod, Kubernetes gửi SIGTERM tới PID 1, chờ tối đa terminationGracePeriodSeconds, rồi SIGKILL. Trong container .NET, dotnet Shop.Api.dll là PID 1 và console lifetime xử lý SIGTERM thành graceful shutdown. Bốn thứ phải khớp:

  1. ShutdownTimeout ngắn hơn terminationGracePeriodSeconds — 25 so với 40 ở trên. Nếu ngược lại, app bị SIGKILL giữa lúc drain.
  2. preStop ngủ một khoảng ngắn để endpoint propagation kịp xảy ra ở cả kube-proxy và ingress controller. Nhưng sleep không tồn tại trong image chiseled; khi đó dựa vào khoảng trễ tự nhiên và readiness, và kiểm tra lại bằng test tải thật.
  3. Request dài phải có giới hạn thời gian. Graceful shutdown không cứu được một request treo 5 phút.
  4. Client phải retry được — zero downtime phía server vẫn có thể là một lỗi 502 với client không retry.

Thêm PodDisruptionBudget để việc drain node không lấy đi quá nhiều Pod cùng lúc:

apiVersion: policy/v1
kind: PodDisruptionBudget
metadata:
  name: shop-api
spec:
  minAvailable: 2
  selector:
    matchLabels:
      app: shop-api

ConfigMap và Secret: hai thứ khác nhau về bản chất

ConfigMap cho cấu hình không nhạy cảm; Secret cho phần còn lại. Nhưng Secret chỉ là base64, không mã hoá — ai đọc được namespace hoặc etcd là đọc được nội dung. Vì vậy:

  • Bật encryption at rest cho etcd (hầu hết managed cluster làm sẵn, tự dựng thì phải kiểm tra).
  • Dùng External Secrets Operator, SOPS, hoặc secret manager của cloud thay vì commit YAML Secret vào git.
  • envFrom tiện nhưng làm secret thành biến môi trường, hiện trong kubectl describe pod và trong crash dump. Với chuỗi kết nối, mount thành file và đọc qua AddKeyPerFile sạch hơn.
  • Đổi Secret không tự restart Pod. Nếu app chỉ đọc cấu hình lúc khởi động, phải rollout — và đó là hành vi bạn nên biết trước khi xoay mật khẩu.

Helm: đóng gói để không copy YAML giữa môi trường

charts/shop-api/
├── Chart.yaml          # apiVersion: v2, version, appVersion
├── values.yaml         # mặc định
├── values.staging.yaml
├── values.production.yaml
└── templates/
    ├── _helpers.tpl
    ├── deployment.yaml
    ├── service.yaml
    ├── ingress.yaml
    ├── hpa.yaml
    ├── configmap.yaml
    └── NOTES.txt

Chart là template + values; helm template render ra YAML, helm install gửi YAML đó cho API server và lưu release. Toàn bộ giá trị của Helm nằm ở chỗ: cùng một template, nhiều môi trường, và lịch sử release để rollback.

helm lint ./charts/shop-api -f values.production.yaml

helm template shop-api ./charts/shop-api \
  -f values.production.yaml \
  --set image.digest=sha256:abc123 | kubectl diff -f -

helm upgrade --install shop-api ./charts/shop-api \
  --namespace shop --create-namespace \
  -f values.production.yaml \
  --set image.tag=1.0.0 \
  --atomic --timeout 5m --history-max 10

--atomic tự rollback nếu release fail và ngầm bật --wait: Helm chờ resource ready rồi mới coi là thành công, nên pipeline CD không báo xanh cho một rollout kẹt. helm template | kubectl diff -f - là bước rẻ nhất để thấy thay đổi thật trước khi chạm cluster — đáng đưa vào PR check.

Quy ước values: values.yaml chứa mặc định an toàn, overlay theo môi trường chỉ khai báo phần khác biệt. Trong CI, --set chỉ dùng cho tag/digest image; mọi cấu hình khác phải nằm trong file đã review, nếu không lịch sử deploy không còn tái lập được.

Tiêu chí Raw manifest + Kustomize Helm chart
Cấu hình theo môi trường Overlay patch Values + template
Đóng gói, chia sẻ Repo YAML Package, repo, version
Vòng đời, rollback Phụ thuộc CI Release history, helm rollback
Điều kiện, vòng lặp trong template Không có Go template (cũng là rủi ro)

Helm không miễn phí: Go template khó đọc, lỗi render chỉ hiện lúc helm template, và chart do team khác viết thường có values không ai hiểu. Nếu bạn chỉ có một app và hai môi trường, Kustomize + kubectl apply là lựa chọn ít lớp hơn.

StatefulSet cho database: thường là câu trả lời sai

Chạy Postgres trong cluster của chính bạn nghĩa là bạn nhận thêm việc: backup, PITR, failover, nâng cấp major version. Managed database (RDS, Azure SQL, Cloud SQL) rẻ hơn về người. Nếu buộc phải chạy trong cluster, dùng StatefulSet với volumeClaimTemplates, headless Service (clusterIP: None) và một operator (ví dụ CloudNativePG cho Postgres) thay vì tự viết YAML.

apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: postgres
spec:
  serviceName: postgres
  replicas: 1
  selector:
    matchLabels:
      app: postgres
  template:
    metadata:
      labels:
        app: postgres
    spec:
      containers:
        - name: postgres
          image: postgres:17
          volumeMounts:
            - name: data
              mountPath: /var/lib/postgresql/data
  volumeClaimTemplates:
    - metadata:
        name: data
      spec:
        accessModes: ["ReadWriteOnce"]
        resources:
          requests:
            storage: 20Gi

Ba điều cấm: HPA trên StatefulSet (mỗi replica là một writer, scale không có nghĩa), rolling update mặc định trên database một writer (dùng updateStrategy: OnDelete và nâng cấp có kế hoạch), và coi PVC là backup. PVC nằm cùng cluster, cùng account; xoá namespace là xoá dữ liệu.

Khi nào Compose là đủ

  • Một VM, một instance, deploy chấp nhận downtime vài chục giây: Compose + digest image + restart policy. Rẻ hơn nhiều so với cluster.
  • Cần zero downtime, nhiều replica, autoscale, hoặc nhiều team chia namespace: Kubernetes có lý do tồn tại.
  • Chỉ cần orchestration local cho dev: Aspire AppHost hoặc Compose, không phải cluster.

Cạm bẫy hay gặp

  • Readiness trùng liveness: cùng một endpoint, kiểm tra DB, nên mất DB là mất toàn bộ Pod.
  • Không đặt resources.requests: Pod bị xếp loại BestEffort và là ứng viên đầu tiên bị evict khi node áp lực.
  • Probe trỏ sai port: 80 thay vì 8080, hoặc targetPort không khớp containerPort.
  • ShutdownTimeout dài hơn grace period: SIGKILL giữa lúc đang xử lý request.
  • latest + imagePullPolicy: Always: không biết Pod đang chạy bản nào.
  • Helm chart tự viết lại toàn bộ: mỗi lần đổi một field phải sửa template; dùng helm create rồi xoá phần không dùng, đừng viết từ đầu.

Nhìn tới 2027

.NET 11 GA tháng 11/2026 không đổi cách triển khai; thay đổi thật nằm ở hạ tầng — Gateway API dần thay Ingress cho routing phức tạp, và các cluster managed tiếp tục đẩy người dùng khỏi việc tự vận hành control plane. Với app .NET, phần còn lại vẫn là ba thứ: probe đúng, tắt đúng, và image bất biến.

Checklist trước khi rollout đầu tiên

  • Ba probe tách vai; liveness không chạm DB.
  • maxUnavailable: 0, resources.requests đặt cho mọi container.
  • ShutdownTimeout < terminationGracePeriodSeconds.
  • Image pin digest; Secret không nằm trong git.
  • PDB tồn tại trước khi bật cluster autoscaler.
  • helm template | kubectl diff chạy trong PR, không chỉ trong pipeline deploy.

Đọc tiếp trong series: