k0sctl: Deploy Kubernetes cluster trong 2 phút mà không muốn tin

Nếu bạn đã từng phải setup một Kubernetes cluster từ đầu dù là dùng kubeadm, RKE, hay tự viết Ansible playbook thì chắc bạn biết cái cảm giác ngồi debug tại sao node worker không join được vào cluster lúc 11 giờ đêm. Mình đã ở đó, và mình không muốn quay lại.

k0sctl là câu trả lời mà mình ước gì biết sớm hơn.

k0s và k0sctl đừng nhầm hai cái này

Trước tiên cần phân biệt rõ: k0s là một Kubernetes distribution gọn nhẹ, single binary, không cần external etcd hay load balancer phức tạp. Còn k0sctl là cái tool CLI để bootstrap và quản lý các cluster chạy k0s.

Nói đơn giản hơn: k0s là cái engine, k0sctl là cái remote control. Bạn dùng k0sctl để SSH vào các máy, cài k0s, config cluster, rồi join các node lại với nhau tất cả hoàn toàn tự động.

Cái output mà README của project show ra nói lên tất cả:

1INFO ==> Running phase: Connect to hosts
2INFO ==> Running phase: Detect host operating systems
3INFO [ssh] 10.0.0.1:22: is running Ubuntu 20.10
4INFO [ssh] 10.0.0.2:22: is running Ubuntu 20.10
5INFO ==> Running phase: Download k0s binaries on hosts
6INFO ==> Running phase: Configure k0s
7INFO ==> Running phase: Initialize the k0s cluster
8INFO [ssh] 10.0.0.1:22: installing k0s controller
9INFO ==> Running phase: Install workers
10INFO [ssh] 10.0.0.2:22: installing k0s worker
11INFO [ssh] 10.0.0.2:22: waiting for node to become ready
12INFO ==> Finished in 2m2s
13INFO k0s cluster version 1.22.3+k0s.0 is now installed

2 phút 2 giây. Từ máy trần đến cluster hoạt động. Mình đã test cái này và vẫn thấy hơi khó tin.

Cài k0sctl về máy

k0sctl support đủ mọi platform, và cộng đồng đã đóng gói cho hầu hết package manager phổ biến:

Mình dùng macOS nên chỉ cần brew install là xong. Nếu bạn dùng Linux server không có package manager nào ở trên, thì download binary từ releases page về, chmod +x rồi bỏ vào /usr/local/bin là ổn.

Lưu ý nhỏ: binary chưa được sign, nên trên macOS bạn cần right-click → Open lần đầu để bypass Gatekeeper. Hơi bất tiện nhưng chấp nhận được với một tool open source.

File config trái tim của k0sctl

k0sctl hoạt động dựa trên một file YAML config mô tả cluster của bạn. Cấu trúc khá straightforward:

1apiVersion: k0sctl.k0sproject.io/v1beta1
2kind: Cluster
3metadata:
4  name: my-cluster
5spec:
6  hosts:
7    - ssh:
8        address: 10.0.0.1
9        user: ubuntu
10        port: 22
11        keyPath: ~/.ssh/id_rsa
12      role: controller
13    - ssh:
14        address: 10.0.0.2
15        user: ubuntu
16        port: 22
17        keyPath: ~/.ssh/id_rsa
18      role: worker
19    - ssh:
20        address: 10.0.0.3
21        user: ubuntu
22        port: 22
23        keyPath: ~/.ssh/id_rsa
24      role: worker
25  k0s:
26    version: 1.29.2+k0s.0
27    config:
28      apiVersion: k0s.k0sproject.io/v1beta1
29      kind: ClusterConfig
30      metadata:
31        name: my-cluster
32      spec:
33        network:
34          provider: calico

Mỗi host trong spec.hosts có một role có thể là controller, worker, hoặc controller+worker (cho single-node setup). k0sctl sẽ SSH vào từng máy theo đúng thứ tự, cài binary k0s, config, rồi wire chúng lại với nhau.

Cái mình thích nhất là phần k0s.config bạn có thể nhúng thẳng k0s ClusterConfig vào đây. Muốn đổi CNI từ kube-router sang Calico? Sửa một dòng. Muốn thêm feature gate? Thêm vào spec. Không cần SSH vào từng máy tay.

Deploy cluster lần đầu

Sau khi có file config, deploy chỉ là:

1k0sctl apply --config k0sctl.yaml

k0sctl sẽ tự detect xem host đang chạy OS gì, download đúng version k0s binary, install, configure, rồi join các node. Idempotent hoàn toàn chạy lại lần nữa nó sẽ chỉ reconcile những gì thay đổi, không cài lại từ đầu.

Sau khi xong, lấy kubeconfig về local:

1k0sctl kubeconfig --config k0sctl.yaml > ~/.kube/config

Rồi verify:

1kubectl get nodes
2# NAME       STATUS   ROLES    AGE   VERSION
3# node-1     Ready    <none>   2m    v1.29.2+k0s
4# node-2     Ready    <none>   1m    v1.29.2+k0s

Done. Cluster đang chạy.

Thêm node mới không cần downtime

Đây là phần mình thấy k0sctl shine nhất so với làm tay. Muốn scale thêm worker? Chỉ cần thêm entry vào file config:

1- ssh:
2        address: 10.0.0.4
3        user: ubuntu
4        port: 22
5        keyPath: ~/.ssh/id_rsa
6      role: worker

Rồi chạy lại k0sctl apply. Tool sẽ tự detect node nào là mới, cài k0s lên đó, generate join token, rồi join vào cluster. Các node cũ không bị touch.

Theo kinh nghiệm của mình, cái workflow này cực kỳ hữu ích khi làm việc với Terraform. Bạn provision VM bằng Terraform, output IP ra, rồi feed vào k0sctl config. Trong repo có sẵn ví dụ Terraform trong thư mục examples/ anh em nên xem qua.

Upgrade cluster

Upgrade Kubernetes version thường là cái mà ops team sợ nhất. Với k0sctl, quy trình là:

1. Sửa k0s.version trong config file
2. Chạy k0sctl apply
3. Ngồi uống cà phê

1k0s:
2    version: 1.30.1+k0s.0  # đổi từ 1.29.2

k0sctl sẽ upgrade controller trước, sau đó drain và upgrade từng worker node theo thứ tự. Rolling upgrade, không downtime cho workload nếu bạn có đủ replica.

Mình đã dùng cái này để upgrade một cluster production từ 1.27 lên 1.29 và nó smooth hơn mình tưởng nhiều. Dĩ nhiên vẫn nên test trên staging trước đừng liều.

Backup và reset

k0sctl cũng có một số lệnh utility hữu ích:

1# Backup etcd data
2k0sctl backup --config k0sctl.yaml
3
4# Reset cluster (xóa sạch k0s trên tất cả hosts)
5k0sctl reset --config k0sctl.yaml

k0sctl reset thực sự hữu ích khi bạn cần tear down cluster test environment. Nó sẽ stop k0s service, xóa binary, xóa data sạch sẽ để bạn có thể apply lại từ đầu.

So sánh với các tool tương tự

k3sup là cái gần nhất với k0sctl về độ đơn giản, nhưng nó dành cho k3s. Nếu team bạn đang dùng k0s (hoặc đang cân nhắc), k0sctl là lựa chọn tự nhiên nhất.

Mình thấy cái này hay ở chỗ: k0sctl không cần bạn cài bất cứ thứ gì trên các node trước không cần pre-installed agent, không cần Ansible, không cần Python. Chỉ cần SSH access là đủ. Tool sẽ tự lo phần còn lại.

Một vài gotcha cần biết

Anh em lưu ý một số điểm khi dùng:

SSH key phải accessible từ máy bạn chạy k0sctl. Nếu bạn chạy trong CI/CD pipeline, nhớ mount hoặc inject SSH key đúng cách. k0sctl không hỗ trợ password authentication chỉ dùng key.

Firewall giữa các node. k0s cần một số port được mở giữa controller và worker (6443, 8132, 8133, 10250...). Nếu cluster không form được, đây thường là nguyên nhân đầu tiên cần check.

Binary chưa được sign như đã đề cập. Nếu bạn đang setup pipeline tự động trên macOS build agent, cần handle cái này riêng.

HA controller setup hoàn toàn được support bạn chỉ cần thêm nhiều host với role: controller và k0sctl sẽ setup etcd cluster tự động. Tuy nhiên bạn vẫn cần một external load balancer phía trước các controller nếu muốn HA thực sự.

1hosts:
2    - ssh:
3        address: 10.0.0.1
4      role: controller
5    - ssh:
6        address: 10.0.0.2
7      role: controller
8    - ssh:
9        address: 10.0.0.3
10      role: controller

Dùng trong CI/CD

Một use case mình hay thấy là dùng k0sctl trong pipeline để spin up ephemeral cluster cho integration test:

1# Trong GitHub Actions hoặc GitLab CI
2- name: Bootstrap test cluster
3  run: |
4    k0sctl apply --config ci-cluster.yaml --no-wait
5    k0sctl kubeconfig --config ci-cluster.yaml > /tmp/kubeconfig
6    export KUBECONFIG=/tmp/kubeconfig
7    kubectl wait --for=condition=Ready nodes --all --timeout=120s
8
9- name: Run integration tests
10  run: make test-integration
11  env:
12    KUBECONFIG: /tmp/kubeconfig
13
14- name: Teardown cluster
15  if: always()
16  run: k0sctl reset --config ci-cluster.yaml

k0sctl cũng có thể chạy trong container nếu bạn không muốn install binary trực tiếp lên CI runner check Dockerfile trong repo.

Nhìn chung, k0sctl giải quyết đúng cái pain point mà mình và nhiều team đã gặp: làm sao để setup và maintain Kubernetes cluster on-premise hoặc trên bare metal mà không phải viết hàng trăm dòng Ansible hay ngồi SSH tay vào từng máy. Nếu bạn đang dùng k0s hoặc đang tìm một Kubernetes distribution nhẹ để self-host, đây là cái tool bạn nên thêm vào toolbox ngay.