Cài đặt Helm và dựng lab Kubernetes local với kind/OrbStack

Hướng dẫn Helm

(1) Helm là gì? Vì sao Kubernetes vẫn cần Helm?

(2) Cài đặt Helm và dựng lab Kubernetes local với kind/OrbStack

(3) Cấu trúc Helm Chart: Chart.yaml, values.yaml, templates và thành phần quan trọng

(4) Templates, Values, Functions và Debugging: Làm chủ Go templating trong Helm

(5) Deploy ứng dụng từ public repository: Bitnami, Artifact Hub và best practices

(6) Tự đóng gói ứng dụng Node.js cơ bản thành Helm chart

(7) NodeJS Full-Stack trong Helm phần 1: Kiến trúc chart cho React/Next.js + Express

(8) NodeJS Full-Stack trong Helm phần 2: Thêm PostgreSQL + Redis dependencies

(9) NodeJS Full-Stack trong Helm phần 3: Nginx reverse proxy + production ingress

(10) Multi-environment deployment với Helm: Dev, Staging, Production

(11) Umbrella chart vs microservices strategy: Khi nào dùng cách nào

(12) 13 Best Practices for using Helm

Ở bài Helm là gì? Vì sao Kubernetes cần Helm, mình đã đi qua lý do vì sao Helm xuất hiện và nó giúp Kubernetes bớt cảnh YAML chồng YAML như thế nào. Sang phần này, mình chuyển hẳn sang lab để bạn có thể tự thực hiện gõ lệnh, cài chart và xem kết quả ngay trên máy Mac của mình.

Lab trong bài được verify trực tiếp trên macOS với Docker context desktop-linux, kubectl v1.35.3, kind v0.31.0, helm v4.1.3, helm@3 v3.20.1 và cluster kind dùng image kindest/node:v1.35.0.

Một điểm nên chốt ngay từ đầu: Helm 4 đã có mặt, nhưng nếu mục tiêu của bạn là học Helm để đi vào hệ sinh thái hiện tại thì Helm 3 vẫn là lựa chọn hợp lý hơn. Phần lớn chart, tài liệu và kinh nghiệm ngoài thực tế lúc này vẫn xoay quanh Helm 3.

Nếu bạn chưa quen với container runtime trên máy, có thể xem thêm bài Docker là gì? Tại sao nên dùng Docker trên VPS để nắm nhanh vai trò của Docker trước khi dựng lab.

Requirements và overview môi trường lab

Để dựng lab mượt trên macOS, bạn không cần máy quá mạnh. Nhưng nếu RAM quá chật, cụm kind vẫn có thể tạo được rồi sau đó mọi thứ ì ạch, pod lên chậm và rất dễ tạo cảm giác Helm bị lỗi oan.

Cấu hình tối thiểu nên có

• CPU từ 2 core trở lên
• Tối thiểu 4 GB RAM dành cho Docker Desktop hoặc OrbStack
• Ít nhất 10 GB dung lượng trống
• macOS đã cài Homebrew

Trong lab này, bạn sẽ đi theo từng bước chuẩn bị container runtime, cài kubectl, kind, helm, tạo cluster local, thêm chart repository rồi cài chart đầu tiên. Sau đó mình kiểm tra release, values, history và thử verify service bằng port-forward.

Cài đặt Docker Desktop hoặc OrbStack

kind cần một container runtime để tạo node Kubernetes. Trên macOS, hai lựa chọn phổ biến nhất là Docker Desktop và OrbStack.

Khi nào chọn Docker Desktop?

• Bạn muốn đi theo setup quen thuộc, tài liệu nhiều
• Bạn ưu tiên độ tương thích cao với đa số tutorial
• Bạn không ngại dùng nhiều tài nguyên hơn một chút

brew install --cask docker

Sau khi cài, mở Docker Desktop và chờ ứng dụng khởi động hoàn toàn rồi kiểm tra lại:

docker --version
docker context show
docker ps

Khi nào chọn OrbStack?

• Bạn muốn nhẹ hơn Docker Desktop
• Bạn thích tốc độ khởi động nhanh
• Bạn muốn trải nghiệm macOS gọn gàng hơn

brew install --cask orbstack

Tiếp theo, mở OrbStack rồi chạy lại các lệnh kiểm tra:

docker --version
docker context ls
docker ps

Chỗ cần nhớ là rất đơn giản: trước khi chạm vào kind hay Helm, lệnh docker ps phải chạy bình thường. Nếu còn lỗi daemon hoặc context, sửa xong chỗ này rồi mới đi tiếp.

Nếu sau này bạn muốn chuyển lab từ local lên máy chủ riêng để test lâu dài hơn, có thể tham khảo bài Thuê VPS: hướng dẫn từ A-Z cho người mới. Local lab rất tiện để học, còn VPS hợp hơn khi bạn cần môi trường chạy 24/7.

Cài đặt kubectl, kind, helm

1. Cài kubectl

brew install kubectl
kubectl version --client=true --output=yaml | head

Trong lab, client version là v1.35.3.

2. Cài kind

brew install kind
kind version

Lab ghi nhận kind v0.31.0.

3. Cài Helm bản mới nhất

brew install helm
helm version --short

Bản mặc định trên máy lab là v4.1.3+gc94d381.

4. Cài thêm Helm 3 để học và làm lab

brew install helm@3
/opt/homebrew/opt/helm@3/bin/helm version --short

Bản Helm 3 trong lab là v3.20.1+ga2369ca. Với serie này, mình dùng Helm 3 để tránh lệch so với hệ sinh thái hiện tại.

alias helm3=/opt/homebrew/opt/helm@3/bin/helm

Nếu muốn alias tồn tại lâu dài, bạn có thể thêm vào ~/.zshrc:

export PATH="/opt/homebrew/opt/helm@3/bin:$PATH"

Trong bối cảnh Kubernetes thực tế, việc giữ rõ Helm 3 và Helm 4 ngay từ đầu giúp bạn tránh kiểu đọc một tài liệu, gõ lệnh ở terminal khác version rồi lại tự nghi ngờ bản thân. Chuyện này xảy ra thường xuyên hơn mình tưởng.

Tạo cluster Kubernetes local với kind

Sau khi có runtime và các CLI cần thiết, bước tiếp theo là dựng cluster local. Mình không chạy kind create cluster kiểu trần trụi mà dùng file config nhỏ để pin version node rõ ràng hơn.

Tạo file kind-config.yaml:

kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
name: helm-local-lab
nodes:
  - role: control-plane
    image: kindest/node:v1.35.0

Tạo cluster:

kind create cluster --config kind-config.yaml --wait 120s

Trong lab, cluster được tạo thành công với context kind-helm-local-lab.

Nếu muốn kiểm tra context hiện tại, chạy:

kubectl config current-context

Verify cluster hoạt động

Bước này đáng làm hơn vẻ ngoài của nó. Nếu chưa verify cluster mà đã vội helm install, lúc có lỗi bạn rất khó biết đang vướng ở cluster, network, image hay bản thân chart.

Kiểm tra node:

kubectl get nodes -o wide

Kết quả lab cho thấy node helm-local-lab-control-plane ở trạng thái Ready và chạy Kubernetes v1.35.0.

Kiểm tra các namespace cơ bản:

kubectl get ns

• default
• kube-system
• kube-public
• kube-node-lease
• local-path-storage

Nếu node chưa lên Ready, chưa nên cài chart vội. Hãy quay lại kiểm tra runtime, RAM hoặc xóa cluster rồi tạo lại từ đầu.

Trong môi trường server thật, việc đọc trạng thái node và service vẫn quan trọng y hệt. Nếu bạn quen với Docker nhưng chưa quen cách cài trên máy chủ, bài Cài đặt Docker và Docker Compose trên VPS Ubuntu sẽ khá hữu ích làm bước đệm.

Cài đặt chart đầu tiên với Helm

Đây là phần thú vị nhất của buổi lab: thêm repository, xem values rồi cài chart thật.

Bước 1: thêm repository

helm3 repo add bitnami https://charts.bitnami.com/bitnami
helm3 repo update
helm3 search repo bitnami/nginx | head

Trong lab, chart bitnami/nginx xuất hiện với chart version 22.6.10 và app version 1.29.7.

Bước 2: xem values của chart

helm3 show values bitnami/nginx | sed -n '1,40p'

Đây là thói quen rất đáng giữ. Chỉ cần liếc nhanh là bạn đã biết chart cho chỉnh gì, service type mặc định ra sao và bố cục values được tổ chức như thế nào.

Bước 3: cài chart

helm3 install web-demo bitnami/nginx \
  --namespace demo --create-namespace \
  --set service.type=ClusterIP \
  --set replicaCount=2

Ở đây mình dùng release name web-demo, namespace demo, giữ ClusterIP cho gọn và đặt replicaCount=2 để lát nữa test upgrade dễ nhìn hơn.

Kiểm tra tài nguyên vừa tạo:

kubectl get all -n demo
helm3 list -A

Điểm hay là bạn chưa cần tự viết một file YAML nào mà vẫn có release NGINX được quản lý trọn vẹn bởi Helm.

Test các lệnh Helm cơ bản

Sau khi cài xong chart đầu tiên, đây là nhóm lệnh nên gõ đi gõ lại cho quen tay. Chúng là bộ tối thiểu để đọc một release mà không bị mù thông tin.

1. Xem release đang có

helm3 list -A

2. Xem trạng thái release

helm3 status web-demo -n demo

Lệnh này cho bạn biết release name, namespace, revision hiện tại và notes của chart. Khi mới học Helm, chỉ riêng việc đọc status cho quen cũng đã giúp đỡ rất nhiều lúc troubleshoot.

3. Xem values đã dùng

helm3 get values web-demo -n demo

Trong lab, Helm trả về đúng phần override đã áp vào release:

replicaCount: 3
service:
  type: ClusterIP

4. Nâng cấp release

helm3 upgrade web-demo bitnami/nginx \
  --namespace demo \
  --set service.type=ClusterIP \
  --set replicaCount=3

Sau đó kiểm tra lại deployment, pods và history:

kubectl get deploy,pods -n demo
helm3 history web-demo -n demo

Ở đây Helm cho thấy rất rõ revision 1 là Install complete và revision 2 là Upgrade complete. Cái hay của Helm nằm ở đây: bạn theo dõi thay đổi ở cấp release thay vì đoán từng object YAML đã bị sửa lúc nào.

5. Verify ứng dụng phản hồi

Khi pod đã lên Running, bạn có thể test nhanh bằng port-forward:

kubectl port-forward -n demo svc/web-demo-nginx 8089:80

Mở terminal khác rồi gọi thử bằng curl:

curl -I http://127.0.0.1:8089

Khi lab ổn, bạn sẽ thấy response HTTP trả về từ NGINX. Đây là một bước verify nhỏ nhưng rất đáng giá, vì nó xác nhận release không chỉ cài xong trên giấy mà service thật sự phản hồi được.

Troubleshooting các lỗi thường gặp

Lúc mới học Helm, phần tốn thời gian nhất thường không phải là câu lệnh cài chart. Phần tốn thời gian là xác định lỗi đang nằm ở đâu.

1. Cannot connect to the Docker daemon

Triệu chứng thường gặp:

docker ps
Cannot connect to the Docker daemon...

Nguyên nhân hay gặp gồm Docker Desktop hoặc OrbStack chưa chạy, Docker context đang sai, hoặc engine vừa mở nhưng chưa sẵn sàng.

Cách kiểm tra nhanh:

docker context ls
docker context show
docker ps

2. kind create cluster chạy lâu hoặc fail giữa chừng

Nguyên nhân phổ biến nhất là thiếu tài nguyên. Với Mac RAM thấp, cluster có thể tạo được rồi sau đó kéo image rất chậm.

kind delete cluster --name helm-local-lab
kind create cluster --config kind-config.yaml --wait 120s

Nếu gặp tình huống này, hãy tăng RAM cho Docker Desktop hoặc OrbStack lên khoảng 6 GB hoặc hơn và đóng bớt container không liên quan.

3. kubectl đang trỏ sai context

Khi bạn có nhiều cluster local lẫn remote, chuyện cài nhầm vào cluster khác là hoàn toàn có thể xảy ra.

kubectl config current-context
kubectl config get-contexts

Trong lab này, context đúng phải là kind-helm-local-lab.

4. helm install xong nhưng pod vẫn Pending hoặc Init

Đây là case rất thật trong lab. Ngay sau khi cài chart, kubectl get all -n demo có thể cho thấy pod còn ở trạng thái Init:0/1 hoặc Pending, và khi đó port-forward sẽ báo pod chưa chạy.

kubectl get pods -n demo
kubectl describe pod -n demo <pod-name>
kubectl get events -n demo --sort-by=.metadata.creationTimestamp | tail -n 30

Điểm cần hiểu đúng là: điều này chưa chắc là lỗi Helm. Helm có thể đã tạo release thành công, nhưng workload phía dưới vẫn đang pull image hoặc chờ tài nguyên.

5. Helm 3 và Helm 4 bị lẫn lộn

Triệu chứng dễ gặp là bạn đang đọc tài liệu Helm 3 nhưng terminal lại gọi Helm 4 mặc định.

helm version --short
/opt/homebrew/opt/helm@3/bin/helm version --short

Nếu học theo serie này, cứ dùng alias helm3 cho gọn. Buổi tối mà trộn lẫn version thì rất dễ lú, nói thật.

💡 Nếu bạn định dựng một lab Kubernetes lâu dài hơn local machine, nên tách nó lên VPS riêng để chủ động tài nguyên và dễ giữ môi trường ổn định qua nhiều buổi học.

Kết luận

Sau bài này, bạn đã có một lab local đủ tốt để học Helm nghiêm túc trên macOS: có runtime bằng Docker Desktop hoặc OrbStack, có kubectl, kind, helm, có cluster kind chạy Kubernetes v1.35.0, có chart đầu tiên được cài bằng Helm và có workflow để kiểm tra release, values, history lẫn service thực tế.

Điểm quan trọng nhất là bạn đã thấy Helm không đứng riêng lẻ. Helm giúp cài release nhanh hơn, nhưng khi có sự cố bạn vẫn phải đọc pod status, event và context của cluster. Nói cách khác, học Helm tốt luôn đi cùng với việc đọc Kubernetes tốt.

Sang bài 3, mình sẽ đi sâu hơn vào cấu trúc của một Helm chart như Chart.yaml, values.yaml, thư mục templates/, helper template và cách đọc chart mà không bị ngợp.

Nếu bạn muốn môi trường thực hành ổn định hơn local machine, có thể tham khảo các giải pháp VPS để dựng lab Kubernetes hoặc CI riêng. Nhưng với giai đoạn học Helm cơ bản, một cluster local bằng kind như trong bài vẫn là quá đủ để bắt đầu.

Bài tiếp theo: phân tích cấu trúc Helm chart, cách đọc values.yaml và bắt đầu template hóa thay vì chỉ cài chart có sẵn.