Antony 筆記：技術原理與實務經驗 – Antony 筆記：技術原理與實務經驗

Install a kubeadm Kubernetes cluster with Cilium, disabling kube-proxy

Tue, 30 Jun 2026 09:58:18 +0800

Ubuntu 24.04

1. 每一台節點都要做環境準備

$ sudo nano /etc/netplan/50-cloud-init.yaml
network:
version: 2
ethernets:
ens18:
dhcp4: false
addresses:
- 192.168.11.72/24
nameservers:
addresses:
- 192.168.11.11
routes:
- to: 0.0.0.0/0
via: 192.168.11.254
$ sudo nano /etc/systemd/timesyncd.conf
...
[Time]
NTP=192.168.11.11
...
$ sudo systemctl restart systemd-timesyncd
$ timedatectl show-timesync --all
$ sudo timedatectl set-timezone Asia/Taipei
$ timedatectl
Local time: Sun 2025-06-29 15:44:28 CST
Universal time: Sun 2025-06-29 07:44:28 UTC
RTC time: Sun 2025-06-29 07:44:28
Time zone: Asia/Taipei (CST, +0800)
System clock synchronized: yes
NTP service: active
RTC in local TZ: no
$ sudo swapoff -a
$ sudo sed -i '/swap/s/^/#/' /etc/fstab
$ cat <<EOF | sudo tee /etc/sysctl.d/k8s.conf
net.ipv4.ip_forward = 1
EOF
$ sudo sysctl --system
$ sudo mkdir -p /opt/cni/bin && \
curl -sL "$(curl -sL https://api.github.com/repos/containernetworking/plugins/releases/latest | \
jq -r '.assets[].browser_download_url' | grep 'linux-amd64.*.tgz$')" -o ~/cni-plugins.tgz && \
sudo tar xf ~/cni-plugins.tgz -C /opt/cni/bin
$ wget https://github.com/opencontainers/runc/releases/download/v1.3.0/runc.amd64 && \
sudo install -m 755 runc.amd64 /usr/local/sbin/runc
$ wget https://github.com/containerd/containerd/releases/download/v2.1.3/containerd-2.1.3-linux-amd64.tar.gz && \
sudo tar Cxzvf /usr/local containerd-2.1.3-linux-amd64.tar.gz && \
wget https://raw.githubusercontent.com/containerd/containerd/main/containerd.service && \
sudo mkdir -p /usr/local/lib/systemd/system && \
sudo mv containerd.service /usr/local/lib/systemd/system/containerd.service
$ sudo mkdir /etc/containerd
$ sudo containerd config default | sudo tee /etc/containerd/config.toml
$ sudo nano /etc/containerd/config.toml
......
[plugins.'io.containerd.cri.v1.runtime'.containerd.runtimes.runc.options]
SystemdCgroup = true #add
$ sudo systemctl daemon-reload
$ sudo systemctl enable --now containerd
$ sudo systemctl is-active containerd.service
active
$ sudo apt-get update; sudo apt-get upgrade -y
$ sudo apt-get install -y apt-transport-https ca-certificates curl gpg
$ K8S_VERSION='v1.33'
$ curl -fsSL https://pkgs.k8s.io/core:/stable:/${K8S_VERSION}/deb/Release.key | sudo gpg --dearmor -o /etc/apt/keyrings/kubernetes-apt-keyring.gpg && \
echo "deb [signed-by=/etc/apt/keyrings/kubernetes-apt-keyring.gpg] https://pkgs.k8s.io/core:/stable:/${K8S_VERSION}/deb/ /" | sudo tee /etc/apt/sources.list.d/kubernetes.list
# Worker node 可不用裝 kubectl
$ sudo apt-get update; sudo apt-get install -y kubelet kubeadm kubectl
$ sudo apt-mark hold kubelet kubeadm kubectl

裝 K8s

mkdir ~/k8s; cd ~/k8s
nano ~/k8s/init-config.yaml

檔案內容 :

apiVersion: kubeadm.k8s.io/v1beta3
kind: InitConfiguration
localAPIEndpoint:
advertiseAddress: 192.168.11.71 # change from Master node IP
bindPort: 6443
nodeRegistration:
criSocket: unix:///run/containerd/containerd.sock # change from containerd Unix Socket
imagePullPolicy: IfNotPresent
name: c1 # change from Master node hsotname
taints: null
---
apiVersion: kubeadm.k8s.io/v1beta3
kind: ClusterConfiguration
kubernetesVersion: 1.33.2
controlPlaneEndpoint: 192.168.11.71:6443
apiServer:
timeoutForControlPlane: 4m0s
#certSANs:
# - 10.10.7.33 # 加入 kube-vip 的 VIP 作為 TLS SAN
certificatesDir: /etc/kubernetes/pki
clusterName: topgun # set your clusterName
controllerManager:
extraArgs:
bind-address: "0.0.0.0"
secure-port: "10257"
scheduler:
extraArgs:
bind-address: "0.0.0.0"
secure-port: "10259"
etcd:
local:
dataDir: /var/lib/etcd
extraArgs:
listen-metrics-urls: "http://0.0.0.0:2381"
dns: {}
imageRepository: registry.k8s.io
networking:
dnsDomain: cluster.local # DNS domain used by Kubernetes Services.
podSubnet: 10.244.0.0/16 # the subnet used by Pods.
serviceSubnet: 10.96.0.0/16 # subnet used by Kubernetes Services.
---
apiVersion: kubelet.config.k8s.io/v1beta1
kind: KubeletConfiguration
maxPods: 110
shutdownGracePeriod: 30s
shutdownGracePeriodCriticalPods: 10s
systemReserved:
memory: "1Gi"
kubeReserved:
memory: "2Gi"

初始化 K8s

sudo kubeadm init --skip-phases=addon/kube-proxy --upload-certs --config=k8s/init-config.yaml

Join worker node

sudo kubeadm join 192.168.11.71:6443 --token 7pr0b4.79tdi8egs81l4i9g --discovery-token-ca-cert-hash sha256:c6bed66cc0c7f8616a4f920ccc62121b782c37475888a6cc9831ced22fde474f

設定 kubeconfig

mkdir -p $HOME/.kube; sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config; sudo chown $(id -u):$(id -g) $HOME/.kube/config

裝 Cilium

# Install the Cilium CLI
CILIUM_CLI_VERSION=$(curl -s https://raw.githubusercontent.com/cilium/cilium-cli/main/stable.txt)
CLI_ARCH=amd64
if [ "$(uname -m)" = "aarch64" ]; then CLI_ARCH=arm64; fi
curl -L --fail --remote-name-all https://github.com/cilium/cilium-cli/releases/download/${CILIUM_CLI_VERSION}/cilium-linux-${CLI_ARCH}.tar.gz{,.sha256sum}
sha256sum --check cilium-linux-${CLI_ARCH}.tar.gz.sha256sum
sudo tar xzvfC cilium-linux-${CLI_ARCH}.tar.gz /usr/local/bin
rm cilium-linux-${CLI_ARCH}.tar.gz{,.sha256sum}
API_SERVER_IP=192.168.11.71
API_SERVER_PORT=6443
curl -fsSL https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash
helm repo add cilium https://helm.cilium.io/
helm install cilium cilium/cilium \
--namespace kube-system \
--set kubeProxyReplacement=true \
--set k8sServiceHost=${API_SERVER_IP} \
--set k8sServicePort=${API_SERVER_PORT} \
--set bpf.masquerade=true \
--set ipam.mode=kubernetes \
--set ipv4NativeRoutingCIDR=10.244.0.0/16 \
--set bpf.datapathMode=netkit
helm upgrade cilium cilium/cilium \
--namespace=kube-system \
--set kubeProxyReplacement=true \
--set k8sServiceHost=${API_SERVER_IP} \
--set k8sServicePort=${API_SERVER_PORT} \
--set hubble.ui.enabled=true \
--set hubble.relay.enabled=true \
--set hubble.ui.frontend.server.ipv6.enabled=false \
--set hubble.ui.service.type=NodePort \
--set bpf.datapathMode=netkit
helm upgrade cilium cilium/cilium --version 1.17.6 \
--namespace kube-system \
--reuse-values \
--set ingressController.enabled=true \
--set ingressController.loadbalancerMode=dedicated
kubectl -n kube-system rollout restart deployment/cilium-operator
kubectl -n kube-system rollout restart ds/cilium

Validate the Installation

$ kubectl -n kube-system get pods
NAME READY STATUS RESTARTS AGE
cilium-28kw8 1/1 Running 1 (117m ago) 124m
cilium-envoy-c5nxh 1/1 Running 1 (117m ago) 124m
cilium-envoy-phwpp 1/1 Running 0 117m
cilium-envoy-sb7c2 1/1 Running 0 117m
cilium-m5mvp 1/1 Running 0 116m
cilium-operator-c64699c6b-2kgr5 1/1 Running 0 117m
cilium-operator-c64699c6b-4sg5r 0/1 Completed 0 124m
cilium-operator-c64699c6b-ft9x8 0/1 Completed 0 124m
cilium-operator-c64699c6b-zflrv 1/1 Running 0 117m
cilium-r6x55 1/1 Running 0 117m
coredns-674b8bbfcf-bzk8x 1/1 Running 1 (117m ago) 131m
coredns-674b8bbfcf-tf5fh 1/1 Running 1 (117m ago) 131m
etcd-c1 1/1 Running 1 (117m ago) 131m
hubble-relay-67cfb6bcbd-hx9t8 1/1 Running 0 117m
hubble-ui-85bc4bfc56-57g8f 2/2 Running 0 96m
kube-apiserver-c1 1/1 Running 1 (117m ago) 131m
kube-controller-manager-c1 1/1 Running 1 (117m ago) 131m
kube-scheduler-c1 1/1 Running 1 (117m ago) 131m

$ cilium status
/¯¯\
/¯¯\__/¯¯\ Cilium: OK
\__/¯¯\__/ Operator: OK
/¯¯\__/¯¯\ Envoy DaemonSet: OK
\__/¯¯\__/ Hubble Relay: OK
\__/ ClusterMesh: disabled
DaemonSet cilium Desired: 3, Ready: 3/3, Available: 3/3
DaemonSet cilium-envoy Desired: 3, Ready: 3/3, Available: 3/3
Deployment cilium-operator Desired: 2, Ready: 2/2, Available: 2/2
Deployment hubble-relay Desired: 1, Ready: 1/1, Available: 1/1
Deployment hubble-ui Desired: 1, Ready: 1/1, Available: 1/1
Containers: cilium Running: 3
cilium-envoy Running: 3
cilium-operator Running: 2, Succeeded: 2
clustermesh-apiserver
hubble-relay Running: 1
hubble-ui Running: 1
Cluster Pods: 8/8 managed by Cilium
Helm chart version: 1.18.0-dev
Image versions cilium quay.io/cilium/cilium-ci:latest: 3
cilium-envoy quay.io/cilium/cilium-envoy:v1.34.1-1750869463-42c7e8cf0f93ea19c9cb7e4d0ad2a339b3f81ad2@sha256:892cab92ffaf8499be90bd227bf07181e4b460ecd97750032ea7e91710a8acce: 3
cilium-operator quay.io/cilium/operator-generic-ci:latest: 4
hubble-relay quay.io/cilium/hubble-relay-ci:latest: 1
hubble-ui quay.io/cilium/hubble-ui-backend:v0.13.2@sha256:a034b7e98e6ea796ed26df8f4e71f83fc16465a19d166eff67a03b822c0bfa15: 1
hubble-ui quay.io/cilium/hubble-ui:v0.13.2@sha256:9e37c1296b802830834cc87342a9182ccbb71ffebb711971e849221bd9d59392: 1

跨叢集 CoreDNS AXFR 同步與 PodCIDR 路由設定紀錄

Mon, 29 Jun 2026 03:28:06 +0800

# us-tkcdc-01
$ kubectl get nodes -o wide
NAME STATUS ROLES AGE VERSION INTERNAL-IP EXTERNAL-IP OS-IMAGE KERNEL-VERSION CONTAINER-RUNTIME
tkdt-control-plane Ready control-plane 19h v1.34.3 172.22.16.1 <none> Debian GNU/Linux 12 (bookworm) 6.8.0-124-generic containerd://2.2.0
tkdt-master1 Ready <none> 19h v1.34.3 172.22.16.2 <none> Debian GNU/Linux 12 (bookworm) 6.8.0-124-generic containerd://2.2.0
tkdt-worker1 Ready <none> 19h v1.34.3 172.22.16.3 <none> Debian GNU/Linux 12 (bookworm) 6.8.0-124-generic containerd://2.2.0
tkdt-worker2 Ready <none> 19h v1.34.3 172.22.16.4 <none> Debian GNU/Linux 12 (bookworm) 6.8.0-124-generic containerd://2.2.0
tkdt-worker3 Ready <none> 19h v1.34.3 172.22.16.5 <none> Debian GNU/Linux 12 (bookworm) 6.8.0-124-generic containerd://2.2.0
$ kubectl describe nodes | grep -i podcidr
PodCIDR: 10.244.16.0/25
PodCIDRs: 10.244.16.0/25
PodCIDR: 10.244.16.128/25
PodCIDRs: 10.244.16.128/25
PodCIDR: 10.244.17.0/25
PodCIDRs: 10.244.17.0/25
PodCIDR: 10.244.17.128/25
PodCIDRs: 10.244.17.128/25
PodCIDR: 10.244.18.0/25
PodCIDRs: 10.244.18.0/25
$ kubectl -n kube-system get cm kubeadm-config -o yaml | grep serviceSubnet
serviceSubnet: 10.98.16.0/24
sudo route add -net 172.22.26.0 netmask 255.255.255.128 gw 192.168.11.102
sudo route add -net 10.244.17.0 netmask 255.255.255.128 gw 172.22.16.3
sudo route add -net 10.244.17.128 netmask 255.255.255.128 gw 172.22.16.4
sudo route add -net 10.244.18.0 netmask 255.255.255.128 gw 172.22.16.5
sudo route add -net 10.244.25.0 netmask 255.255.255.128 gw 192.168.11.102
sudo route add -net 10.244.25.128 netmask 255.255.255.128 gw 192.168.11.102
sudo route add -net 10.244.26.0 netmask 255.255.255.128 gw 192.168.11.102
sudo route add -net 10.98.16.0 netmask 255.255.255.0 gw 172.22.16.5
sudo route add -net 10.98.24.0 netmask 255.255.255.0 gw 192.168.11.102
kubectl apply -f - <<'EOF'
apiVersion: v1
kind: Service
metadata:
name: nginx-tkdt
labels:
app: nginx-tkdt
spec:
clusterIP: None
selector:
app: nginx-tkdt
ports:
- port: 80
name: web
---
apiVersion: apps/v1
kind: StatefulSet
metadata:
name: nginx-tkdt
spec:
serviceName: nginx-tkdt
replicas: 2
selector:
matchLabels:
app: nginx-tkdt
template:
metadata:
labels:
app: nginx-tkdt
spec:
containers:
- name: nginx-tkdt
image: nginx
ports:
- containerPort: 80
name: web
EOF
$ kubectl get pods -o wide
NAME READY STATUS RESTARTS AGE IP NODE NOMINATED NODE READINESS GATES
nginx-tkdt-0 1/1 Running 0 36s 10.244.17.5 tkdt-worker1 <none> <none>
nginx-tkdt-1 1/1 Running 0 33s 10.244.18.6 tkdt-worker3 <none> <none>
$ kubectl get svc nginx-tkdt
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
nginx-tkdt ClusterIP None <none> 80/TCP 44s
$ curl -sI http://10.244.17.5 | head -n 1
HTTP/1.1 200 OK
$ curl -sI http://10.244.26.5 | head -n 1
HTTP/1.1 200 OK
$ dig @10.98.16.10 nginx-tkdt-0.nginx-tkdt.default.svc.tkdt.k8s +short
10.244.17.5
$ dig @10.98.16.10 nginx-tkdt-1.nginx-tkdt.default.svc.tkdt.k8s +short
10.244.18.6
$ dig @10.98.24.10 nginx-tkndt-0.nginx-tkndt.default.svc.tkndt.k8s +short
10.244.26.5
$ dig @10.98.24.10 nginx-tkndt-1.nginx-tkndt.default.svc.tkndt.k8s +short
10.244.25.5
$ kubectl -n kube-system edit cm coredns
transfer tkdt.k8s { # 其他人可以跟我用 AXFR 同步
to * # 來源 IP 問題，先開放給所有人
}
secondary tkndt.k8s { # 我向 tkndt 同步的 domain
transfer from 10.98.24.10 # tkndt 的 coredns svc ip
}
$ kubectl -n kube-system rollout restart deployment coredns
$ kubectl -n kube-system get pods -l k8s-app=kube-dns
NAME READY STATUS RESTARTS AGE
coredns-7d597fb798-5zx2n 1/1 Running 0 16s
coredns-7d597fb798-7xmg7 1/1 Running 0 16s
$ dig @10.98.16.10 nginx-tkndt-0.nginx-tkndt.default.svc.tkndt.k8s +short
10.244.26.5
$ dig @10.98.16.10 nginx-tkndt-1.nginx-tkndt.default.svc.tkndt.k8s +short
10.244.25.5
$ kubectl exec nginx-tkdt-0 -- curl -sI nginx-tkndt-0.nginx-tkndt.default.svc.tkndt.k8s | head -n 1
HTTP/1.1 200 OK
$ kubectl exec nginx-tkdt-0 -- curl -sI nginx-tkndt-1.nginx-tkndt.default.svc.tkndt.k8s | head -n 1
HTTP/1.1 200 OK
==========================================================================
# us-tkcdc-02
$ kubectl get nodes -o wide
NAME STATUS ROLES AGE VERSION INTERNAL-IP EXTERNAL-IP OS-IMAGE KERNEL-VERSION CONTAINER-RUNTIME
tkndt-control-plane Ready control-plane 18h v1.34.3 172.22.26.1 <none> Debian GNU/Linux 12 (bookworm) 6.8.0-124-generic containerd://2.2.0
tkndt-master1 Ready <none> 18h v1.34.3 172.22.26.2 <none> Debian GNU/Linux 12 (bookworm) 6.8.0-124-generic containerd://2.2.0
tkndt-worker1 Ready <none> 18h v1.34.3 172.22.26.3 <none> Debian GNU/Linux 12 (bookworm) 6.8.0-124-generic containerd://2.2.0
tkndt-worker2 Ready <none> 18h v1.34.3 172.22.26.4 <none> Debian GNU/Linux 12 (bookworm) 6.8.0-124-generic containerd://2.2.0
tkndt-worker3 Ready <none> 18h v1.34.3 172.22.26.5 <none> Debian GNU/Linux 12 (bookworm) 6.8.0-124-generic containerd://2.2.0
$ kubectl describe nodes | grep -i podcidr
PodCIDR: 10.244.24.0/25
PodCIDRs: 10.244.24.0/25
PodCIDR: 10.244.24.128/25
PodCIDRs: 10.244.24.128/25
PodCIDR: 10.244.25.0/25
PodCIDRs: 10.244.25.0/25
PodCIDR: 10.244.25.128/25
PodCIDRs: 10.244.25.128/25
PodCIDR: 10.244.26.0/25
PodCIDRs: 10.244.26.0/25
$ kubectl -n kube-system get cm kubeadm-config -o yaml | grep serviceSubnet
serviceSubnet: 10.98.24.0/24
sudo route add -net 172.22.16.0 netmask 255.255.255.128 gw 192.168.11.101
sudo route add -net 10.244.25.0 netmask 255.255.255.128 gw 172.22.26.3
sudo route add -net 10.244.25.128 netmask 255.255.255.128 gw 172.22.26.4
sudo route add -net 10.244.26.0 netmask 255.255.255.128 gw 172.22.26.5
sudo route add -net 10.244.17.0 netmask 255.255.255.128 gw 192.168.11.101
sudo route add -net 10.244.17.128 netmask 255.255.255.128 gw 192.168.11.101
sudo route add -net 10.244.18.0 netmask 255.255.255.128 gw 192.168.11.101
sudo route add -net 10.98.16.0 netmask 255.255.255.0 gw 192.168.11.101
sudo route add -net 10.98.24.0 netmask 255.255.255.0 gw 172.22.26.5
kubectl apply -f - <<'EOF'
apiVersion: v1
kind: Service
metadata:
name: nginx-tkndt
labels:
app: nginx-tkndt
spec:
clusterIP: None
selector:
app: nginx-tkndt
ports:
- port: 80
name: web
---
apiVersion: apps/v1
kind: StatefulSet
metadata:
name: nginx-tkndt
spec:
serviceName: nginx-tkndt
replicas: 2
selector:
matchLabels:
app: nginx-tkndt
template:
metadata:
labels:
app: nginx-tkndt
spec:
containers:
- name: nginx-tkndt
image: nginx
ports:
- containerPort: 80
name: web
EOF
$ kubectl get pods -o wide
NAME READY STATUS RESTARTS AGE IP NODE NOMINATED NODE READINESS GATES
nginx-tkndt-0 1/1 Running 0 29s 10.244.26.5 tkndt-worker3 <none> <none>
nginx-tkndt-1 1/1 Running 0 23s 10.244.25.5 tkndt-worker1 <none> <none>
$ kubectl get svc nginx-tkndt
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
nginx-tkndt ClusterIP None <none> 80/TCP 90s
$ curl -sI http://10.244.17.5 | head -n 1
HTTP/1.1 200 OK
$ curl -sI http://10.244.26.5 | head -n 1
HTTP/1.1 200 OK
$ dig @10.98.24.10 nginx-tkndt-0.nginx-tkndt.default.svc.tkndt.k8s +short
10.244.26.5
$ dig @10.98.24.10 nginx-tkndt-1.nginx-tkndt.default.svc.tkndt.k8s +short
10.244.25.5
$ dig @10.98.16.10 nginx-tkdt-0.nginx-tkdt.default.svc.tkdt.k8s +short
10.244.17.5
$ dig @10.98.16.10 nginx-tkdt-1.nginx-tkdt.default.svc.tkdt.k8s +short
10.244.18.6
$ kubectl -n kube-system edit cm coredns
transfer tkndt.k8s { # 其他人可以跟我用 AXFR 同步
to * # 來源 IP 問題，先開放給所有人
}
secondary tkdt.k8s { # 我向 tkndt 同步的 domain
transfer from 10.98.16.10 # tkndt 的 coredns svc ip
}
$ kubectl -n kube-system rollout restart deployment coredns
$ kubectl -n kube-system get pods -l k8s-app=kube-dns
NAME READY STATUS RESTARTS AGE
coredns-7446d9745d-5pjh7 1/1 Running 0 11s
coredns-7446d9745d-5pxtj 1/1 Running 0 11s
$ $ dig @10.98.24.10 nginx-tkdt-0.nginx-tkdt.default.svc.tkdt.k8s +short
10.244.17.5
$ dig @10.98.24.10 nginx-tkdt-1.nginx-tkdt.default.svc.tkdt.k8s +short
10.244.18.6
$ kubectl exec nginx-tkndt-0 -- curl -sI nginx-tkdt-0.nginx-tkdt.default.svc.tkdt.k8s | head -n 1
HTTP/1.1 200 OK
$ kubectl exec nginx-tkndt-0 -- curl -sI nginx-tkdt-1.nginx-tkdt.default.svc.tkdt.k8s | head -n 1
HTTP/1.1 200 OK

Claude Code Best Practice

Mon, 01 Jun 2026 03:25:26 +0800

AGENTS.md (全域)

$ nano ~/.claude/AGENTS.md
# 全域偏好
- 回覆使用繁體中文
$ echo @AGENTS.md > ~/.claude/CLAUDE.md

洞悉 Cilium 如何傳遞 K8s Pod 網路封包

Fri, 08 May 2026 06:59:56 +0800

1. Preface

本篇文章會在 CNI 使用 Cilium 的 Kubernetes 環境驗證，pod 跟 pod 之間互相溝通時，在同節點或在不同節點，網路的封包會如何傳遞，並搭配 tcpdump + wireshark 分析封包。

2. 環境資訊

K8s 節點及版本資訊

kubectl get nodes -o wide

執行結果：

NAME STATUS ROLES AGE VERSION INTERNAL-IP EXTERNAL-IP OS-IMAGE KERNEL-VERSION CONTAINER-RUNTIME
kubeadm-c1.bbg.com Ready control-plane 27d v1.34.1 172.20.6.11 <none> Ubuntu 24.04.3 LTS 6.8.0-85-generic containerd://2.1.4
kubeadm-c2.bbg.com Ready control-plane 27d v1.34.1 172.20.6.12 <none> Ubuntu 24.04.3 LTS 6.8.0-85-generic containerd://2.1.4
kubeadm-c3.bbg.com Ready control-plane 26d v1.34.1 172.20.6.13 <none> Ubuntu 24.04.3 LTS 6.8.0-85-generic containerd://2.1.4
kubeadm-w1.bbg.com Ready worker 26d v1.34.1 172.20.6.14 <none> Ubuntu 24.04.3 LTS 6.8.0-85-generic containerd://2.1.4
kubeadm-w2.bbg.com Ready worker 26d v1.34.1 172.20.6.15 <none> Ubuntu 24.04.3 LTS 6.8.0-85-generic containerd://2.1.4
kubeadm-w3.bbg.com Ready worker 26d v1.34.1 172.20.6.16 <none> Ubuntu 24.04.3 LTS 6.8.0-85-generic containerd://2.1.4

cilium 設定資訊

helm -n kube-system get values cilium

執行結果：

USER-SUPPLIED VALUES: # 忽略此行
bpf:
masquerade: true
hubble:
relay:
enabled: true
ui:
enabled: true
service:
type: NodePort
ipam:
mode: kubernetes
ipv4NativeRoutingCIDR: 10.244.0.0/16
k8sServiceHost: 127.0.0.1
k8sServicePort: 6443
kubeProxyReplacement: true

確認 cilium 版本、routing 模式和 device mode

kubectl -n kube-system exec ds/cilium -- cilium-dbg status | grep -iE "^cilium:|^routing|^device mode"

執行結果：

Cilium: Ok 1.18.2 (v1.18.2-5bd307a8)
Routing: Network: Tunnel [vxlan] Host: BPF
Device Mode: veth

本篇文章測試環境 routing-mode 為 tunnel，tunnel-protocol 使用 vxlan，沒有特別 tunning。

建立 NGINX pods

kubectl create deploy nginx --image=docker.io/library/nginx:latest --replicas=2

建立 Client pods，replicas 設成 2，並指定跑在 worker node

echo 'apiVersion: apps/v1
kind: Deployment
metadata:
labels:
app: client
name: client
spec:
replicas: 2
selector:
matchLabels:
app: client
template:
metadata:
labels:
app: client
spec:
nodeSelector:
node-role.kubernetes.io/worker: ""
containers:
- image: quay.io/cooloo9871/debug.alp
name: debug-alp
securityContext:
privileged: true' | kubectl apply -f -

檢視 pods 各至在哪一個節點

kubectl get pods -o wide

執行結果類似以下螢幕輸出：

NAME STATUS NODE
client-65766844b7-72zg2 Running kubeadm-w1.bbg.com
client-65766844b7-c4w29 Running kubeadm-w2.bbg.com
nginx-66686b6766-6vd9x Running kubeadm-w2.bbg.com
nginx-66686b6766-s25sh Running kubeadm-w3.bbg.com

3. 檢視單一 Pod 的網路架構

查看 client pod 的 ip address 和 subnet mask

kubectl exec -it client-65766844b7-c4w29 -- ip a

執行結果：

...以上省略
34: eth0@if35: <BROADCAST,MULTICAST,UP,LOWER_UP,M-DOWN> mtu 1500 qdisc noqueue state UP
link/ether d6:c4:d2:00:8c:2e brd ff:ff:ff:ff:ff:ff
inet 10.244.7.250/32 scope global eth0
valid_lft forever preferred_lft forever
inet6 fe80::d4c4:d2ff:fe00:8c2e/64 scope link
valid_lft forever preferred_lft forever

得知 subnet mask 為 /32，所以 pod 要上網一定會走 Default Gateway

查看 client Pod 的 Default Gateway

kubectl exec -it client-65766844b7-c4w29 -- ip r

執行結果：

default via 10.244.7.247 dev eth0
10.244.7.247 dev eth0 scope link

確認 Default Gateway 的值為 10.244.7.247

查看 client Pod 裡的 Neighbour Table
```
kubectl exec -it client-65766844b7-c4w29 -- ip n
```
執行結果：
```
10.244.7.247 dev eth0 lladdr 1e:49:e0:67:ec:e7 used 0/0/0 probes 4 STALE
```
得知 Default Gateway 10.244.7.247 對應的 Mac Address 為 1e:49:e0:67:ec:e7

到 pod 所在的節點查找 pod 內看到 Default Gateway 對應在主機是哪張網卡

ip a s | grep -A 3 -B 2 10.244.7.247

執行結果：

4: cilium_host@cilium_net: <BROADCAST,MULTICAST,NOARP,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default qlen 1000
link/ether ba:af:34:f7:09:12 brd ff:ff:ff:ff:ff:ff
inet 10.244.7.247/32 scope global cilium_host
valid_lft forever preferred_lft forever
inet6 fe80::b8af:34ff:fef7:912/64 scope link
valid_lft forever preferred_lft forever

發現 10.244.7.247 這張網卡對應的 Mac Address 竟然是 ba:af:34:f7:09:12 而不是在 client pod 裡面看到的 1e:49:e0:67:ec:e7

繼續在 pod 所在的節點查找 1e:49:e0:67:ec:e7 是哪張網卡

ip a s | grep -A 3 -B 1 '1e:49:e0:67:ec:e7'

執行結果：

35: lxc7904b406cec6@if34: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default qlen 1000
link/ether 1e:49:e0:67:ec:e7 brd ff:ff:ff:ff:ff:ff link-netns cni-a59f663a-3aed-32da-7743-287142c3ccda
inet6 fe80::1c49:e0ff:fe67:ece7/64 scope link
valid_lft forever preferred_lft forever

由網卡名稱可以得知是 veth pair，並且另一端連接在 cni-a59f663a-3aed-32da-7743-287142c3ccda Linux Network Namespace

進入這個 Linux Network Namespace 查看網卡資訊

sudo ip netns exec cni-a59f663a-3aed-32da-7743-287142c3ccda ip a

執行結果：

1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN group default qlen 1000
link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
inet 127.0.0.1/8 scope host lo
valid_lft forever preferred_lft forever
inet6 ::1/128 scope host
valid_lft forever preferred_lft forever
34: eth0@if35: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default
link/ether d6:c4:d2:00:8c:2e brd ff:ff:ff:ff:ff:ff link-netnsid 0
inet 10.244.7.250/32 scope global eth0
valid_lft forever preferred_lft forever
inet6 fe80::d4c4:d2ff:fe00:8c2e/64 scope link
valid_lft forever preferred_lft forever

確認 client pod eth0 在主機側的網卡名稱是 lxc7904b406cec6

確認初始狀態下 pod 內部 arp cache
```
kubectl exec -it client-65766844b7-c4w29 -- arp -a
```
執行結果
得知 pod 在初始狀態下 arp cache 應為空

小結論

Client Pod eth0 網卡對應在 host 主機這側的網卡是 lxc7904b406cec6
在 Client Pod 內部 Neighbour Table 紀錄 Default Gateway 的 IP 是在 host 主機 cilium_host 網卡的 ip，但是 Mac Address 卻是 pod 在 host 主機側網卡的 mac address
pod 在初始狀態下無任何 arp cache
網路架構如下圖

4. 檢視同一台節點內 Pods 之間網路封包如何傳遞

查詢 nginx pod 網卡資訊，在 pod 所在的節點執行以下命令

pod_name="nginx-66686b6766-6vd9x"
sudo ip netns exec $(sudo ip netns identify $(sudo crictl inspect $(sudo crictl ps -a | grep ${pod_name} | cut -d " " -f 1) | jq -r '.info.pid // .status.pid')) ip a s eth0

執行結果：

32: eth0@if33: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default
link/ether 9a:08:1c:60:8e:77 brd ff:ff:ff:ff:ff:ff link-netnsid 0
inet 10.244.7.203/32 scope global eth0
valid_lft forever preferred_lft forever
inet6 fe80::9808:1cff:fe60:8e77/64 scope link
valid_lft forever preferred_lft forever

得知 nginx pod 網卡資訊：

名稱為 eth0

ip address 為 10.244.7.203/32

mac address 為 9a:08:1c:60:8e:77

找到 nginx pod 在主機側的網卡，在 pod 所在的節點執行以下命令

pod_name="nginx-66686b6766-6vd9x"
ip a s | grep -A 3 ^$(sudo ip netns exec $(sudo ip netns identify $(sudo crictl inspect $(sudo crictl ps -a | grep ${pod_name} | cut -d " " -f 1) | jq -r '.info.pid // .status.pid')) ip a s eth0 | head -n 1 | cut -d ":" -f 2 | tail -c 3)

執行結果：

33: lxcdad8b6341b55@if32: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default qlen 1000
link/ether 2a:e0:31:24:98:d1 brd ff:ff:ff:ff:ff:ff link-netns cni-90146bc6-03b3-1ff1-72c8-61b61819bb95
inet6 fe80::28e0:31ff:fe24:98d1/64 scope link
valid_lft forever preferred_lft forever

得知 nginx pod 在主機側網卡資訊：

名稱為 lxcdad8b6341b55

mac address 為 2a:e0:31:24:98:d1

額外開啟 4 個終端機，分別都 ssh 到 client 和 nginx pod 所在的同一台節點上，並依序執行以下 4 個收集封包的動作
1. 在 client pod 主機側的網卡上，透過 tcpdump 命令收集 ARP 或 ICMP 封包
```
sudo tcpdump -n -i lxc7904b406cec6 arp or icmp -vvv -w client-pod-host.pcap
```
2. 在 nginx pod 主機側的網卡上，透過 tcpdump 命令收集 ARP 或 ICMP 封包
```
sudo tcpdump -n -i lxcdad8b6341b55 arp or icmp -vvv -w nginx-pod-host.pcap
```
3. 在 client pod Container 側的網卡上，透過 tcpdump 命令收集 ARP 或 ICMP 封包
```
sudo ip netns exec cni-a59f663a-3aed-32da-7743-287142c3ccda tcpdump -n -i eth0 arp or icmp -vvv -w client-pod.pcap
```
4. 在 nginx pod Container 側的網卡上，透過 tcpdump 命令收集 ARP 或 ICMP 封包
```
sudo ip netns exec cni-90146bc6-03b3-1ff1-72c8-61b61819bb95 tcpdump -n -i eth0 arp or icmp -vvv -w nginx-pod.pcap
```

切換到可執行 kubectl 主機的終端機，進到 client pod 去 ping nginx pod

kubectl exec -it client-65766844b7-c4w29 -- ping -c 1 10.244.7.203

執行結果：

PING 10.244.7.203 (10.244.7.203): 56 data bytes
64 bytes from 10.244.7.203: seq=0 ttl=63 time=0.198 ms
--- 10.244.7.203 ping statistics ---
1 packets transmitted, 1 packets received, 0% packet loss
round-trip min/avg/max = 0.198/0.198/0.198 ms

小總結

client Pod 去 ping 同一節點的 nginx pod，因 subnet mask 為 /32，網路封包一定往 Default Gateway 10.244.7.247 送，由於初始化 pod 內部 arp cache 為空，故觸發 arp 通訊協定來去得到 Default Gateway 的 mac address。封包詳細資訊：
由 arp 通訊協定得知 Default Gateway 的 mac address 為 1e:49:e0:67:ec:e7，這 mac address 對應的網卡是 client pod 在主機側的網卡 lxc7904b406cec6。封包詳細資訊：
更詳細的運作流程：
1. client Pod 以廣播的方式發送 arp request 封包
2. arp request 被在主機側的網卡收到，此時 cilium bpf cil_from_container 程式會立刻接手
3. 經過一連串判斷，會用自己的 MAC address 假裝自己是 gateway 來回復這個 arp request，詳情請看 shiun 大佬的源碼分析
  
  cil_from_container 在做什麼？簡單一句話來解釋就是：「cil_from_container 是 application container 網路的出口警衛，專門檢查所有從 app container 送出的網路封包，並決定它們的下一步該怎麼走。」
4. client pod 收到被偽造 Mac address 的 arp reply
此時 icmp echo request 封包從 pod 內發送到在主機側的 lxc7904b406cec6 網卡封包詳細資訊：
立刻又被 Cilium 掛在該網卡上的 BPF 程式 cil_from_container 接住，並作出以下判斷
- 如果目標 pod 是同一個 Node → 找到目標 pod 在主機側的網卡 → 然後將封包送進 Container 側的網卡
  - 更詳細運作流程：
    1. 拿到封包後，把目的 MAC Address 和來源的 MAC Address 的換掉，確保能送到正確的 Pod
    2. 直接送達：它不把包裹交給大樓的收發室 (Linux Network Stack)，而是直接搭電梯（tail_call_policy）衝到收件 Pod 的門口（在主機側的網卡），把包裹交給門口的警衛 (Ingress BPF 程式) 做安全檢查 (Policy Enforcement)
  - 以下是從 client pod 在主機側網卡收到的 icmp echo request 封包資訊 (為更換 mac address 前) 封包詳細資訊：遺憾的是沒收到更換完 mac address 的 icmp echo request 封包
- 如果目標 pod 是跨 Node → 會轉交 cilium_vxlan / ens33 網卡
很明顯此次的目標 pod 跟來源 pod 是在同一個 node，經過 cilium bpf 程式一番查找得知要傳給目標 pod 在主機側的網卡，所以 icmp echo request 封包會發送到 nginx pod 在主機側的網卡 lxcdad8b6341b55
Nginx pod 在主機側的網卡收到 icmp echo request 封包後，cilium bpf 程式 cil_from_container 立馬接手，執行 nginx Pod 的 Ingress Policy 檢查。
檢查沒問題後，BPF 對 kernel 說：「我檢查完了，這封包沒問題，你接手處理吧！」。
此時封包會送進 nginx pod 的 Linux Network Namspace，由於之前已經修改了目的地和來源的 mac address，封包會被正確路由到 nginx Pod 在 Container 側的網卡。封包詳細資訊：
nginx pod 收到 icmp echo request 封包後，會需要回傳 icmp echo reply 的網路封包，同樣會因為 subnet mask 為 /32，網路封包一定往 Default Gateway 10.244.7.247 送，由於初始化 pod 內部 arp cache 為空，故又觸發 arp 通訊協定來去得到 Default Gateway 的 mac address(實際上會得到的是 nginx pod 在主機側網卡的 mac address) (arp 詳細運作流程不再重複描述)
透過 arp 通訊協定得知 nginx 在主機側網卡 mac 位址後，icmp echo reply 封包會發送至 nginx pod 在主機側的網卡封包詳細資訊：
icmp echo reply 封包傳送到在 nginx pod 主機側的網卡後，又又又被 cilium bpf 程式 cil_from_container 接手，並作出以下判斷 :
1. 目標 pod 是同一個 Node
2. 把目的 MAC Address 和來源的 MAC Address 的換掉，確保能送回 client pod
3. 直接將網路封包送達 client pod 在主機側的網卡
client pod 在主機側的網卡收到 icmp echo reply 封包後，cilium bpf 程式 cil_from_container 接手，執行 client Pod 的 Ingress Policy 檢查，確認沒問題後最後傳回給 client pod 在 container 側的網卡。封包詳細資訊：

補充說明

安裝 cilium 後，會在主機的 os 裡面，看到 cilium_host, cilium_net, 和 cilium_vxlan 這 3 個網路介面，目前根據上面的驗證結果可得知在同節點內 pod 跟 pod 之間互相溝通，並不會經過這 3 張網卡。

如果想驗證，可在 pods 之間互 ping 之前，執行以下收集封包的命令

收集 cilium_host 網路介面的封包

sudo tcpdump -n -i cilium_host arp or icmp -vvv -w cilium_host.pcap

收集 cilium_net 網路介面的封包

sudo tcpdump -n -i cilium_net arp or icmp -vvv -w cilium_net.pcap

收集 cilium_vxlan 網路介面的封包

sudo tcpdump -n -i cilium_net arp or icmp -vvv -w cilium_vxlan

收集結果會看到 icmp 封包，但 icmp 封包內要傳遞的 data 一定會跟 pod 之間互 ping 的 data 不一樣

所以可以確定在同節點內 pod 跟 pod 之間互相溝通，並不會經過 cilium_host, cilium_net, 和 cilium_vxlan 這 3 張網卡。

5. 參考文章

CNI 運作原理：理解 Container Network Interface 如何讓跨主機的 Pod 通訊

Fri, 08 May 2026 05:29:18 +0800

TL;DR

當 worker-1 上的 Pod A ping worker-2 上的 Pod B：

Pod 內 eth0（/32 IP、169.254.1.1 link-local default gateway）→ 透過 Calico CNI 建的 veth pair 出到 host netns
Host netns 的 routing 表把對端 podCIDR 指向 flannel.1（VXLAN device，VNI 1）
Linux kernel 用 ip neigh + bridge fdb 查到對端 underlay IP，做 VXLAN encap（UDP port 8472）
封包經 node container 的 eth0 → host bridge podman1 → 對端 node 的 eth0 → 對端 flannel.1 做 VXLAN decap → veth → Pod B eth0

Calico 負責建 veth、設 proxy_arp；Flannel 負責跨 node 的 host route 與 VXLAN fdb；kernel 負責真正的 encap/decap。

不熟悉 veth pair / encap / overlay / fdb / VXLAN 等術語的讀者，建議先翻 Appendix B 術語表一次再讀正文。

TL;DR
0. 前提條件
1. Kubernetes networking model 三條公約
2. Canal 架構快速理解
3. 環境探勘（Podman 特有步驟）
4. 部署 demo workload
5. 第一層觀察：Pod 內看到什麼
6. 第二層觀察：node container 內看到什麼
7. 第三層觀察：抓真正的 VXLAN 封包
8. Packet flow 圖
9. 常見驗證 checklist
10. 收尾
Appendix A. 指令速查表
Appendix B. 術語表
References

目標

在一個 1 master + 2 workers 的 Kubernetes cluster（用 Podman 建立、運作方式類似 kind），CNI 採用 Canal 的情境下，回答一個具體問題：

當 worker-1 上的 Pod A ping worker-2 上的 Pod B，封包到底走了哪些 interface、被誰 encap、又被誰 decap？

讀完本文後，應能在自己的 cluster 上用 kubectl、podman exec、ip、tcpdump 等工具，把整條 datapath 親眼看一遍。

適合對象：已熟悉 Pod / Deployment / Service 的使用者，但對 overlay network、VXLAN、CNI plugin chain 仍是黑盒子。

驗證環境：cluster tk8s（v1.35.0、container runtime containerd 2.2.0、node image quay.io/cloudwalker/taroko:v1.35.0、3 node：tk8s-control-plane / tk8s-worker1 / tk8s-worker2）。其他環境若 IP/CIDR 不同，照樣換值即可。

0. 前提條件

這節重點：確認 cluster 是 1m2w、INTERNAL-IP 落在 Podman bridge 上、Canal 已安裝（每 node 一個 canal pod，內含 calico-node + kube-flannel 兩個 container）。

(1) 看 cluster 拓樸：

kubectl get node -o wide

NAME STATUS ROLES AGE VERSION INTERNAL-IP ...
tk8s-control-plane Ready control-plane 2d v1.35.0 172.22.0.1 ...
tk8s-worker1 Ready taroko-worker 2d v1.35.0 172.22.0.2 ... ← 等等 demo Pod A 落腳點
tk8s-worker2 Ready taroko-gateway 2d v1.35.0 172.22.0.3 ... ← Pod B 落腳點

(2) 看 Canal 是否安裝、每個 canal pod 由哪些 container 組成：

kubectl get pods -n kube-system -l k8s-app=canal -o wide
kubectl get pods -n kube-system -l k8s-app=canal \
 -o jsonpath='{.items[0].spec.containers[*].name}'; echo

NAME READY STATUS RESTARTS AGE IP NODE
canal-4wvhj 2/2 Running 0 2d 172.22.0.1 tk8s-control-plane
canal-qsnqh 2/2 Running 0 2d 172.22.0.3 tk8s-worker2
canal-vjcm9 2/2 Running 0 2d 172.22.0.2 tk8s-worker1
calico-node kube-flannel ← 兩個 container：calico-node 跑 Felix、kube-flannel 跑 flanneld

找不到 canal pod 時，改用 kubectl get pods -n kube-system | grep -E 'canal|calico|flannel' 比對；不同 manifest 的 label 命名可能不同。

1. Kubernetes networking model 三條公約

這節重點：K8s 不規定怎麼做，只規定三件事必須成立；CNI plugin 的工作就是把它變成現實。

依 kubernetes.io 的規範：

#	公約	通俗說法
1	每個 Pod 拿到一個 cluster 內 routable 的 IP	不用 port forwarding、不會 port 衝突
2	Pod-to-Pod 通訊不經 NAT	Pod A 看到自己的 IP，跟 Pod B 看到 Pod A 的 IP，必須一致
3	Node agent（kubelet 等）能直連該 node 上的 Pod	host 和 Pod 之間沒有牆

CNI plugin 的職責：

IPAM：給每個 Pod 配 IP
Plumbing：在 host 與 Pod 之間建立 veth
Forwarding：設好 routing / encap，讓跨 node 的 Pod 互通

2. Canal 架構快速理解

這節重點：Canal = Flannel（負責 networking）+ Calico（負責 NetworkPolicy）。Calico 在這個組合下跑 policy-only mode、不跑 BGP。

角色	實作者	跑在哪裡
CNI plugin（建立 veth、配 IP）	Calico CNI	node 上的 `/opt/cni/bin/calico` binary
Overlay backend（跨 node 封裝）	Flannel VXLAN	canal pod 的 `kube-flannel` container
NetworkPolicy 執行	Calico Felix	canal pod 的 `calico-node` container
Routing protocol（BGP）	不啟用	`CALICO_NETWORKING_BACKEND=none`

本文只示範 datapath 連通；NetworkPolicy 不在範圍內。

3. 環境探勘（Podman 特有步驟）

這節重點：node 是 host 上的 Podman container；node 的 eth0 = host 的 podman1 bridge 上的 veth。之後抓 underlay 封包就要看這座 bridge。

本 cluster 的 Podman 跑在 rootful 模式，所以指令要加 sudo。

(1) 列出 node container：

sudo podman ps --format '{{.Names}}\t{{.Image}}\t{{.Status}}'

tk8s-control-plane quay.io/cloudwalker/taroko:v1.35.0 Up 2 days
tk8s-worker1 quay.io/cloudwalker/taroko:v1.35.0 Up 2 days
tk8s-worker2 quay.io/cloudwalker/taroko:v1.35.0 Up 2 days

(2) 找 nodes 共用的 Podman network：

sudo podman network ls
sudo podman network inspect tk8s

NETWORK ID NAME DRIVER
2f259bab93aa podman bridge ← 預設、未使用
2543f305ded9 tk8s bridge ← cluster 真正用的

[{
 "name": "tk8s",
 "driver": "bridge",
 "network_interface": "podman1", ← 對應 host 上的 bridge 名稱
 "subnets": [{
 "subnet": "172.22.0.0/24",
 "gateway": "172.22.0.254"
 }]
 // ... 其他欄位省略
}]

結論（記住這三件事，後面都會用到）：

Podman network tk8s ↔ host bridge podman1
三個 node 都掛在 podman1 上、IP 落在 172.22.0.0/24
node 內 eth0 = 接到 podman1 的 veth；node 的 INTERNAL-IP 就是它在 bridge 上的 IP

4. 部署 demo workload

這節重點：用 podAntiAffinity 強制兩個 nicolaka/netshoot Pod 各落到一台 worker；確認每 node 的 podCIDR 是 /25 切片；設好 $POD_A / $POD_B 等變數方便後續所有指令引用。

(1) 部署並等 Ready：

kubectl apply -f docs/manifests/cni-demo.yaml
kubectl wait --for=condition=Ready pod -l app=cni-demo --timeout=60s
kubectl get pod -l app=cni-demo -o wide

deployment.apps/cni-demo created
pod/cni-demo-548d4c6cbc-bgjqk condition met
pod/cni-demo-548d4c6cbc-lmk44 condition met
NAME READY STATUS IP NODE
cni-demo-548d4c6cbc-bgjqk 1/1 Running 10.244.0.153 tk8s-worker1 ← Pod A
cni-demo-548d4c6cbc-lmk44 1/1 Running 10.244.1.22 tk8s-worker2 ← Pod B

Pod 名稱與 IP 每次部署都會變動；只要結構一致（兩個 replica、各落在不同 worker、IP 在各自 podCIDR 內）即正確。

(2) 看 podCIDR 切片（cluster pod CIDR 10.244.0.0/16 被切成 /25 分給每個 node）：

kubectl get node -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.spec.podCIDR}{"\n"}{end}'

tk8s-control-plane 10.244.0.0/25
tk8s-worker1 10.244.0.128/25 ← Pod A 來自這個區段
tk8s-worker2 10.244.1.0/25 ← Pod B 來自這個區段

(3) 設定 shell 變數（後面所有節都會用到）：

POD_A=$(kubectl get pod -l app=cni-demo --field-selector spec.nodeName=tk8s-worker1 -o jsonpath='{.items[0].metadata.name}')
POD_B=$(kubectl get pod -l app=cni-demo --field-selector spec.nodeName=tk8s-worker2 -o jsonpath='{.items[0].metadata.name}')
POD_A_IP=$(kubectl get pod $POD_A -o jsonpath='{.status.podIP}')
POD_B_IP=$(kubectl get pod $POD_B -o jsonpath='{.status.podIP}')
echo "POD_A=$POD_A ($POD_A_IP @ tk8s-worker1)"
echo "POD_B=$POD_B ($POD_B_IP @ tk8s-worker2)"

POD_A=cni-demo-548d4c6cbc-bgjqk (10.244.0.153 @ tk8s-worker1)
POD_B=cni-demo-548d4c6cbc-lmk44 (10.244.1.22 @ tk8s-worker2)

5. 第一層觀察：Pod 內看到什麼

這節重點：Pod 內只有 eth0、IP 是 /32、default gateway 是 dummy 的 169.254.1.1。Pod 不知道 overlay、不知道對端 node。

kubectl exec $POD_A -- ip a show eth0
kubectl exec $POD_A -- ip route
kubectl exec $POD_A -- ping -c 3 $POD_B_IP

2: eth0@if29: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 ... ← MTU 1500（Calico 預設）
link/ether 32:90:8e:80:e6:7a ...
inet 10.244.0.153/32 scope global eth0 ← 注意是 /32
default via 169.254.1.1 dev eth0 ← link-local dummy gateway
169.254.1.1 dev eth0 scope link
PING 10.244.1.22 (10.244.1.22) 56(84) bytes of data.
64 bytes from 10.244.1.22: icmp_seq=1 ttl=62 time=0.614 ms ← ttl 從 64 掉到 62
64 bytes from 10.244.1.22: icmp_seq=2 ttl=62 time=0.370 ms
64 bytes from 10.244.1.22: icmp_seq=3 ttl=62 time=0.399 ms
--- 10.244.1.22 ping statistics ---
3 packets transmitted, 3 received, 0% packet loss, time 2084ms

為什麼會這樣？

/32 mask：Pod 把 host 視為 point-to-point 對端，沒有 subnet 概念
169.254.1.1 是 Calico CNI 寫死的 dummy next hop（Calico CNI 原始碼：gw := net.IPv4(169, 254, 1, 1)）；host-side veth 上設定 proxy_arp=1，所以 ARP 永遠回應 host MAC，然後封包就到 host netns 了
ttl 從 64 → 62 = 兩端 flannel.1 各 decrement 一次（VXLAN device 跨 layer-3 forwarding）
MTU 1500 vs 後面會看到的 flannel.1 MTU 1450 → § 8 MTU mismatch 小提醒

6. 第二層觀察：node container 內看到什麼

這節重點：node netns 上有三類 interface（eth0、flannel.1、caliXXXX veth）；routing / fdb / neigh 三張表加起來決定封包要怎麼走。

本節指令都用 sudo podman exec tk8s-worker1 <cmd> 從 host 跑；想拿 shell 互動的話，改用 sudo podman exec -it tk8s-worker1 bash。

6.1 Interface 全貌

sudo podman exec tk8s-worker1 ip -br a

lo UNKNOWN 127.0.0.1/8 ::1/128
eth0@if5 UP 172.22.0.2/24 ... ← 接到 host podman1 的 veth
flannel.1 UNKNOWN 10.244.0.128/32 ... ← VXLAN device，IP 為 podCIDR 首 IP
cali96e9f6c0c5f@if2 UP ... ┐
cali431d010c6bb@if2 UP ... │
cali6c6a1f0801c@if2 UP ... ├ Calico CNI 為各本機 Pod 建的 veth
cali55122502246@if2 UP ... │
caliaf66b54b075@if2 UP ... │
cali58f769715fe@if2 UP ... ┘ ← 這條對應到 demo Pod A

確認 VXLAN 參數：

sudo podman exec tk8s-worker1 ip -d link show flannel.1

5: flannel.1: ... mtu 1450 ...
link/ether e6:16:30:64:14:d3 ...
vxlan id 1 ← VNI 1
local 172.22.0.2 ← encap 後外層 src IP
dev eth0 ← 從 eth0 寄出
dstport 8472 ← Flannel VXLAN UDP port
nolearning ...

定位 Pod A 對應的 host-side veth（用 ifindex 對照）：

POD_A_IFLINK=$(kubectl exec $POD_A -- cat /sys/class/net/eth0/iflink)
echo "POD_A_IFLINK=$POD_A_IFLINK"
sudo podman exec tk8s-worker1 sh -c "ip link | grep -A1 \"^${POD_A_IFLINK}:\""

POD_A_IFLINK=29
29: cali58f769715fe@if2: ... mtu 1500 ...
link/ether ee:ee:ee:ee:ee:ee ...
link-netns cni-d3b2a847-5b76-c640-8ffa-0e3952643e1b ← 對端 netns（Pod 的 netns）

ifindex 與 caliXXXX hash 每個 Pod 都不同；29 / cali58f769715fe 只是這次的值。三類 interface 角色一覽：

Interface 角色

eth0 underlay 進出口；連到 host bridge podman1

flannel.1 VXLAN device（VNI 1、dstport 8472、IP 為 podCIDR 首 IP）

caliXXXX 每個本機 Pod 一條 veth（host 端）

Interface	角色
`eth0`	underlay 進出口；連到 host bridge `podman1`
`flannel.1`	VXLAN device（VNI 1、dstport 8472、IP 為 podCIDR 首 IP）
`caliXXXX`	每個本機 Pod 一條 veth（host 端）

6.2 Routing 表

sudo podman exec tk8s-worker1 ip route

default via 172.22.0.254 dev eth0 proto static metric 100 ← (a) 對外 default
10.244.0.0/25 via 10.244.0.0 dev flannel.1 onlink ← (c) 跨 node：到 control-plane podCIDR
10.244.0.130 dev cali96e9f6c0c5f scope link ┐
10.244.0.131 dev cali431d010c6bb scope link │
10.244.0.132 dev cali6c6a1f0801c scope link │
10.244.0.136 dev cali55122502246 scope link ├ (b) 本機 Pod：每個 /32 走對應 cali veth
10.244.0.138 dev caliaf66b54b075 scope link │
10.244.0.153 dev cali58f769715fe scope link ┘ ← demo Pod A
10.244.1.0/25 via 10.244.1.0 dev flannel.1 onlink ← (c) 跨 node：到 worker2 podCIDR ★
172.22.0.0/24 dev eth0 proto kernel scope link src 172.22.0.2 ← (d) host underlay subnet

封包送往 Pod B（10.244.1.22）時，命中第 (c) ★ 條規則：

next-hop 是 10.244.1.0 —— 正好是對端 worker2 上 flannel.1 的 IP
onlink 告訴 kernel：「直接視為同一鏈路」，不必再對 next-hop 做 ARP
出 device 是本機 flannel.1 —— 等於告訴 kernel「這條要做 VXLAN encap」

類型	範例	由誰寫的
(a) 對外 default	`default via 172.22.0.254 dev eth0`	node 啟動時 DHCP/Podman
(b) 本機 Pod /32	`10.244.0.153 dev cali58f769715fe`	Calico CNI 每建一個 Pod 寫一條
(c) 跨 node Pod CIDR	`10.244.1.0/25 via 10.244.1.0 dev flannel.1 onlink`	Flannel daemon
(d) host underlay	`172.22.0.0/24 dev eth0`	kernel 自動

6.3 VXLAN forwarding database 與 neighbor

sudo podman exec tk8s-worker1 bridge fdb show dev flannel.1
sudo podman exec tk8s-worker1 ip neigh show dev flannel.1

# bridge fdb show dev flannel.1 ← 對端 flannel.1 MAC → 對端 underlay IP
d2:41:35:4c:5e:90 dst 172.22.0.3 self permanent ← worker2
d6:e5:aa:e1:8a:0e dst 172.22.0.1 self permanent ← control-plane
# ip neigh show dev flannel.1 ← 對端 flannel.1 IP → 對端 flannel.1 MAC
10.244.1.0 lladdr d2:41:35:4c:5e:90 PERMANENT ← worker2
10.244.0.0 lladdr d6:e5:aa:e1:8a:0e PERMANENT ← control-plane

kernel 對 Pod B 做 VXLAN encap 的四步查表：

Step 1 ip route 10.244.1.22 命中 10.244.1.0/25 via 10.244.1.0 dev flannel.1 onlink
Step 2 ip neigh 10.244.1.0 → MAC d2:41:35:4c:5e:90
Step 3 bridge fdb MAC d2:41:35:4c:5e:90 → underlay dst 172.22.0.3
Step 4 build VXLAN packet outer = UDP 172.22.0.2:?? → 172.22.0.3:8472, VNI 1
inner = original ICMP (10.244.0.153 → 10.244.1.22)
送出 device = eth0

這兩張表是 Flannel daemon 透過 Kubernetes API 蒐集各 node 的 flannel.alpha.coreos.com/* annotation 後，主動寫到 kernel 的（PERMANENT 條目）—— 完全不需要 multicast、不需要 BGP。

6.4 Calico Felix 的痕跡

即使沒有 NetworkPolicy，Felix 也會建立基礎 chain 結構。本文不展開、只示範它存在。

sudo podman exec tk8s-worker1 iptables -t filter -L | grep -i cali | head

cali-INPUT ... /* cali:Cz_u1IQiXIMmKD4c */ ┐
cali-FORWARD ... /* cali:wUHhoiAYhphO9Mso */ ├ Felix 的三個 hook chain
cali-OUTPUT ... /* cali:tVnHkvAo15HuiPy0 */ ┘
ACCEPT ... /* Policy explicitly accepted packet. */ mark match 0x10000/0x10000
MARK ... MARK or 0x10000
MARK ... MARK and 0xffe5ffff
cali-from-hep-forward ... ← host endpoint forward dispatcher
cali-from-wl-dispatch ... ← workload (Pod) ingress dispatcher
cali-to-wl-dispatch ... ← workload (Pod) egress dispatcher

7. 第三層觀察：抓真正的 VXLAN 封包

這節重點：在 host 對 podman1 bridge 抓 UDP 8472，能同時看到外層 underlay 與內層 Pod-to-Pod ICMP。

本 cluster 的 node image 沒裝 tcpdump（sudo podman exec tk8s-worker1 which tcpdump 回 missing），所以直接在 host 抓最快。

開兩個 terminal：

# Terminal 1：host 上對 podman1 抓 UDP 8472（用 host filter 收緊噪音）
sudo tcpdump -i podman1 -nn -c 8 \
 'udp port 8472 and host 172.22.0.2 and host 172.22.0.3'

# Terminal 2：發 ping
kubectl exec $POD_A -- ping -c 4 $POD_B_IP

listening on podman1, link-type EN10MB (Ethernet), snapshot length 262144 bytes
11:40:13.754197 IP 172.22.0.2.60047 > 172.22.0.3.8472: OTV, flags [I] (0x08), overlay 0, instance 1
IP 10.244.0.153 > 10.244.1.22: ICMP echo request, id 9, seq 1, length 64
11:40:13.754358 IP 172.22.0.3.60047 > 172.22.0.2.8472: OTV, flags [I] (0x08), overlay 0, instance 1
IP 10.244.1.22 > 10.244.0.153: ICMP echo reply, id 9, seq 1, length 64
... (其餘略)

逐欄對照：

欄位	意義
`IP 172.22.0.2.60047 > 172.22.0.3.8472`	外層：兩個 worker 在 podman1 上的 IP；dst port 8472 = Flannel VXLAN
`OTV, flags [I] (0x08)`	tcpdump 預設把 UDP 8472 顯示為 OTV（同 port、格式相容）；要強制顯示 VXLAN 加 `-T vxlan`
`instance 1`	即 VNI 1（與 `ip -d link show flannel.1` 的 `vxlan id 1` 一致）
內層 `IP 10.244.0.153 > 10.244.1.22: ICMP echo request`	原始 Pod-to-Pod ICMP，被 VXLAN 包在裡面

8. Packet flow 圖

這節重點：把前面三節學到的 interface / route / fdb / encap 串成一張圖。

worker-1 (Podman container, 172.22.0.2) worker-2 (Podman container, 172.22.0.3)
+-------------------------------+ +-------------------------------+
| Pod A netns | | Pod B netns |
| +------+ | | +------+ |
| | eth0 | 10.244.0.153/32 | | 10.244.1.22/32| eth0 | |
| | mtu | 1500 | | 1500| mtu | |
| +--+---+ | | +---+--+ |
| | (veth pair) | | (veth pair) | |
| +--+--------------+ | | +--------------+--+ |
| | cali58f769715fe | ← Calico | | Calico → | caliYYYYYYYYY | |
| | proxy_arp=1 | CNI | | CNI | proxy_arp=1 | |
| +-------+---------+ 建立 | | 建立 +---------+------+ |
| | | | | |
| [host route, 在 node netns] | | [host route, 在 node netns] |
| 10.244.1.0/25 via 10.244.1.0 | | 10.244.0.128/25 via ... |
| dev flannel.1 onlink | | dev flannel.1 onlink |
| | | | | |
| +-------v-----+ | | +-----v-------+ |
| | flannel.1 | VXLAN encap | | VXLAN decap | flannel.1 | |
| | id 1 | (in-kernel) | | (in-kernel) | id 1 | |
| | 10.244.0.128| MTU 1450 | | MTU 1450 | 10.244.1.0 | |
| +-------+-----+ | | +-----+-------+ |
| | | | | |
| +-------v-----+ UDP 8472 | | UDP 8472 +--v-------+ |
| | eth0 | src 172.22.0.2 | dst 172.22.0.3 | eth0 | |
| | (veth) | | | | (veth) | |
| +-------+-----+ | | +----+-----+ |
+----------|--------------------+ +----------------------|-------+
| |
| +------------------------------+ |
+--------->| host bridge: podman1 |<---------------+
| (Podman network "tk8s") |
| subnet 172.22.0.0/24 |
+------------------------------+
(L2 forwarding；這裡看到的是 underlay UDP 封包)

各步驟責任歸屬：

Calico CNI：建立 Pod 的 veth pair、設定 host-side caliXXXX、加上 proxy_arp=1、寫 <pod-ip>/32 dev caliXXXX scope link host route
Flannel daemon（canal/kube-flannel container）：管理 flannel.1 的存在、寫入跨 node 的 host route 與 VXLAN fdb / neigh
Linux kernel：實際做 VXLAN encap/decap、ARP 與 routing；fdb / neigh 查表
host 的 podman1 bridge：純 L2 forwarding，把 underlay UDP 在 nodes 之間搬

MTU mismatch 小提醒

Pod eth0 MTU = 1500（Calico CNI 預設）
flannel.1 MTU = 1450（VXLAN header 50 bytes）
podman1 bridge MTU = 1500

意思是：Pod 直接送一個 1500 byte 的 packet，到了 flannel.1 因 MTU 較小，要嘛被分片、要嘛觸發 ICMP「Fragmentation Needed」回去做 PMTUD。本 demo 用 ping（小 packet）看不到問題；做大量 TCP 流量時會用 PMTUD 收斂到 1450。如要徹底避免這個 mismatch，可以在 Calico install spec 顯式把 mtu 設成 1450。

9. 常見驗證 checklist

這節重點：ping 不通時按以下順序排查（依 Flannel troubleshooting 文件）。

#	檢查項	指令	健康時應看到
1	node 互通	`sudo podman exec tk8s-worker1 ping -c 2 172.22.0.3`	`0% packet loss`
2	podCIDR 已設	`kubectl get node tk8s-worker1 -o jsonpath='{.spec.podCIDR}'`	`10.244.0.128/25`
3	flannel subnet	見 9.3	`FLANNEL_SUBNET` 與 podCIDR 一致
4	VXLAN checksum offload bug	見 9.4	（只在懷疑時才下）

9.1 node 互通

sudo podman exec tk8s-worker1 ping -c 2 172.22.0.3

PING 172.22.0.3 (172.22.0.3) 56(84) bytes of data.
64 bytes from 172.22.0.3: icmp_seq=1 ttl=64 time=0.308 ms
64 bytes from 172.22.0.3: icmp_seq=2 ttl=64 time=0.236 ms
--- 172.22.0.3 ping statistics ---
2 packets transmitted, 2 received, 0% packet loss, time 1032ms

9.2 podCIDR 是否設置

kubectl get node tk8s-worker1 -o jsonpath='{.spec.podCIDR}'; echo

10.244.0.128/25

9.3 flannel 寫好的 subnet

/run/flannel/subnet.env 在 canal pod 的 kube-flannel container 內，不在 node container 的 host 檔案系統。

CANAL_POD=$(kubectl get pod -n kube-system -l k8s-app=canal \
 --field-selector spec.nodeName=tk8s-worker1 \
 -o jsonpath='{.items[0].metadata.name}')
kubectl exec -n kube-system $CANAL_POD -c kube-flannel -- cat /run/flannel/subnet.env

FLANNEL_NETWORK=10.244.0.0/16
FLANNEL_SUBNET=10.244.0.129/25 ← 與 podCIDR 10.244.0.128/25 對應（差別在 .128 vs .129：podCIDR 用 network address，flannel 用第一個 host IP）
FLANNEL_MTU=1450
FLANNEL_IPMASQ=true

9.4 VXLAN checksum offload（只在懷疑時才下）

抓得到 underlay UDP 8472 卻看不到 inner packet 時，可能是 VXLAN checksum offload bug：

sudo podman exec tk8s-worker1 ethtool -K flannel.1 tx-checksum-ip-generic off

Actual changes:
tx-checksum-ip-generic: off
tx-tcp-segmentation: off [not requested]
tx-tcp-ecn-segmentation: off [not requested]
tx-tcp-mangleid-segmentation: off [not requested]
tx-tcp6-segmentation: off [not requested]

本 cluster 無此問題；上面只是示範指令在這個環境跑得起來。如不需要，請用 ... on 改回。

10. 收尾

kubectl delete -f docs/manifests/cni-demo.yaml

deployment.apps "cni-demo" deleted from default namespace

Appendix A. 指令速查表

依「想看什麼」反查：

想看什麼	在哪裡跑	指令
Pod IP / MTU / MAC	`kubectl exec`	`ip a show eth0`
Pod default route	`kubectl exec`	`ip route`
Pod-to-Pod 連通	`kubectl exec`	`ping <pod B IP>`
node 上所有 interface	node container	`ip -br a`
flannel.1 的 VXLAN 參數	node container	`ip -d link show flannel.1`
Pod A 對應的 host-side veth	node container	`ip link \| grep -A1 ^<iflink>:`
node 的 routing 表	node container	`ip route`
對端 flannel.1 IP→MAC	node container	`ip neigh show dev flannel.1`
對端 MAC→underlay IP	node container	`bridge fdb show dev flannel.1`
Felix iptables 痕跡	node container	`iptables -t filter -L \| grep cali`
underlay VXLAN 封包	host	`tcpdump -i podman1 -nn 'udp port 8472'`
flannel 的 subnet.env	canal pod (`kube-flannel` container)	`cat /run/flannel/subnet.env`
Podman bridge / network	host	`sudo podman network inspect tk8s`
node container 列表	host	`sudo podman ps`

Appendix B. 術語表

B.1 Linux kernel networking

network namespace（netns） kernel 提供的隔離機制；每個 netns 有自己獨立的一套 interface、routing table、iptables、socket。每個 Pod 跑在自己的 netns 裡，看不到 host 與其他 Pod 的網路狀態。Node 本身（不論是真機還是 Podman container）也是一個 netns。

veth pair（virtual Ethernet pair） kernel 提供的成對 virtual interface，行為像「一條虛擬網線」：從一端送進去的封包會從另一端原樣出現。常用法是把一端放在 Pod netns、另一端放在 host netns，當作 Pod 與 host 之間的連線。Calico CNI 對每個 Pod 建一條：host 端 = caliXXXXXXXXXX（host netns）、pod 端 = eth0（Pod netns）。

bridge（Linux bridge） kernel 內建的 software switch，把多個 interface 聚成一個 L2 廣播域、做 MAC learning 與 forwarding。本文裡 host 上的 podman1 就是一個 bridge，連著三個 node container 的 veth。

MAC address L2 layer 的 6-byte 位址；同一個 L2 廣播域內用 ARP 由 IP 查到 MAC。

ARP（Address Resolution Protocol）/ neighbor table IPv4 用 ARP 廣播「誰有這個 IP？」來解析 IP→MAC；kernel 把結果快取在 neighbor table，用 ip neigh 看。

proxy ARP Host 收到 ARP request 時，雖然該 IP 不是自己也回應「我來」，引導對方把封包送過來、再由自己 forward。Calico 在每條 host-side veth 上設 /proc/sys/net/ipv4/conf/<veth>/proxy_arp = 1，所以 Pod 對 dummy gateway 169.254.1.1 發 ARP 永遠收到 host MAC，封包就被導進 host netns 處理。

routing table / next-hop kernel 決定「封包該從哪個 interface 出、下一跳給誰」的查表結構；用 ip route 看。Next-hop 是命中該條後送往的下一個 IP：對端在同一鏈路時 = 目的 IP；跨 layer-3 時 = gateway。

onlink（route flag） 強制 kernel 把 next-hop 視為「同一鏈路」、不再去 ARP 解析它。Flannel 寫的跨 node 路由 10.244.1.0/25 via 10.244.1.0 dev flannel.1 onlink 用這個 flag——對端 flannel.1 的 IP 雖然不在自己 subnet 內，但因為走 VXLAN，下一跳由 fdb / neigh 表處理而非 ARP。

TTL（Time To Live） IPv4 header 的 8-bit 計數器，每經過一個 router 減 1，到 0 就丟掉並回 ICMP Time Exceeded。送出端通常從 64 起算；本文 ping 看到 ttl=62 表示中間經過兩跳（兩端 flannel.1 各一次）。

MTU（Maximum Transmission Unit）/ PMTUD Interface 一次能送的最大 L3 封包大小。乙太網典型 1500 byte；VXLAN 因要加 50 byte header（IP 20 + UDP 8 + VXLAN 8 + 內層 Ethernet 14），inner MTU 通常 = underlay MTU − 50。當 sender 送了超過 path 上某段 MTU 的封包，DF flag 為 1 時 router 會丟封包並回 ICMP “Fragmentation Needed”，sender 據此調整——這個過程叫 Path MTU Discovery (PMTUD)。

B.2 Encapsulation 與 overlay 網路

encapsulation（encap）/ decapsulation（decap） encap 就是「把一個完整的封包當成 payload，包進另一個封包裡」，外層 header 的 src/dst 是傳輸路徑用的位址，內層才是原始封包；decap 就是反向取出內層。VXLAN 是其中一種 encap：把整個 L2 frame 包進 UDP。

underlay network / overlay network Underlay 是底下「真的能 routable / switchable 的網路」；overlay 是邏輯上跑在 underlay 上的虛擬網路。本文中：

underlay = host bridge podman1 + 三個 node 的 172.22.0.0/24
overlay = 10.244.0.0/16 的 Pod IP 空間，靠 VXLAN 在 underlay 上重建

Pod 不知道 overlay 是「假的」；underlay 不知道 Pod 的存在。中間靠 flannel.1 做翻譯。

VXLAN（Virtual Extensible LAN） RFC 7348 定義的 overlay 協定，把 L2 frame 包進 UDP（標準 port 4789；Flannel 為了相容歷史用 8472）。Linux kernel 支援，建一條 flannel.1 這種 VXLAN device 即可：對它送的封包會自動 encap、收到的會自動 decap。

VNI（VXLAN Network Identifier） 24-bit ID，類似 VLAN tag 但容量大得多；不同 VNI 的封包互相不可見。Flannel 預設 VNI = 1。

fdb（forwarding database） Bridge / VXLAN device 的 MAC→出口對應表。一般 bridge 是 MAC→bridge port；VXLAN device 是 MAC→underlay IP（kernel 知道要把這個 MAC 的封包 encap 後送去哪個 underlay endpoint）。本文 bridge fdb show dev flannel.1 看到的 dst 172.22.0.3 就是「對端 flannel.1 的 MAC 對應到對端 node 的 underlay IP」。

B.3 Kubernetes / CNI 元件

CNI（Container Network Interface） CNI spec：kubelet 每次起 / 停一個 Pod 時，按 spec 呼叫指定的 binary（如 /opt/cni/bin/calico），由它負責建 veth、配 IP、寫 host route。

IPAM（IP Address Management） 配 Pod IP 的子系統。CNI plugin 可以自己做 IPAM，也可以呼叫獨立 IPAM plugin。Calico 在 Canal 模式中自己做 IPAM。

podCIDR Node 物件 .spec.podCIDR，給每個 node 預先切好的 Pod IP 段。本 cluster 是 cluster pod CIDR 10.244.0.0/16 → 每 node 切 /25。

NetworkPolicy K8s API 物件，宣告「哪些 Pod 可以連到哪些 Pod / port」。執行靠 CNI 端的 controller，例如 Calico Felix 把它翻成 iptables / eBPF rules。本文不示範。

Calico Felix Calico 的 per-node agent，負責 program iptables / eBPF rules（執行 NetworkPolicy）以及維護 endpoint state。

Flannel daemon（flanneld） Per-node agent，watch K8s API 收集各 node 的 podCIDR、flannel.alpha.coreos.com/* annotation，然後在本機建 flannel.1 VXLAN device、寫 host route、寫 VXLAN fdb / neigh entry。

Calico CNI plugin 被 kubelet 呼叫的 binary（不是常駐 daemon），負責 Pod 啟動時建 veth pair、配 Pod IP、寫 host-side <pod-ip>/32 dev caliXXXX 路由、設 proxy_arp。

Canal 把 Calico（policy）+ Flannel（networking）兩個 project 的 manifest 包成一份 install。Calico 在這個組合下跑 policy-only mode（CALICO_NETWORKING_BACKEND=none），所以 Calico 的 BIRD（BGP daemon）不啟用、改由 Flannel 的 VXLAN 負責跨 node 連線。

BGP（Border Gateway Protocol） Internet 的 routing protocol，Calico 預設用它讓各 node 互相 announce 自己的 podCIDR、不需要 overlay encap。Canal 模式下 BGP 停用、改用 Flannel VXLAN，所以本文看不到 BGP 相關痕跡。

References

技術細節皆引自下列官方來源（依 CLAUDE.md 規範要求）：

Kubernetes networking model：https://kubernetes.io/docs/concepts/cluster-administration/networking/
Canal（Calico + Flannel）：https://docs.tigera.io/calico/latest/getting-started/kubernetes/flannel/install-for-flannel
Calico architecture（Felix 等元件職責）：https://docs.tigera.io/calico/latest/reference/architecture/overview
Flannel backends（VXLAN VNI、UDP 8472）：https://github.com/flannel-io/flannel/blob/master/Documentation/backends.md
Flannel troubleshooting：https://github.com/flannel-io/flannel/blob/master/Documentation/troubleshooting.md
Calico CNI dataplane source（169.254.1.1 gateway、proxy_arp）：https://github.com/projectcalico/calico/blob/master/cni-plugin/pkg/dataplane/linux/dataplane_linux.go

資安事件報告 - 內部跳板伺服器遭加密貨幣挖礦惡意程式入侵

Wed, 06 May 2026 08:09:20 +0800

1. 事件概要

內部跳板與開發伺服器遭未授權入侵。經鑑識確認，本事件為典型的 加密貨幣資源劫持 (Cryptojacking)，攻擊者透過對外暴露的 SSH 服務進行長期的密碼暴力破解，成功取得系統 root 權限。

攻擊者入侵後展現出高度的隱蔽技巧：

降權躲避查緝：取得 root 後，刻意切換至一般使用者 A 的身分，於 /var/tmp/ 目錄下執行挖礦程式，以避免在系統資源監控（如 top）中出現 root 執行高耗能程序的突兀現象。
雙軌營利模式：同時運行傳統的 XMRig 惡意挖礦（挖掘 Monero）與合法的 Vortix Cloud DePIN 算力出租節點（vortix-agent），多管齊下榨取伺服器算力。
深度潛伏：部署了 sshdd.so (利用 LD_PRELOAD 機制的 Userland Rootkit) 來隱藏實體檔案，並建立 systemd 幽靈帳號與 sudoers 免密碼提權後門，確保能長期掌控系統。

本事件未發現明確的資料外洩 (Data Exfiltration) 傳輸行為。初始調查中 /var/tmp/syst3md.1~8 出現的 2025 年 11 月 檔案時間戳記，經查證為攻擊者使用 wget 或 curl 下載工具時，保留了中繼伺服器上原始檔案之 Last-Modified 時間所致（Time-stomping 假象），實際入侵時間確認為 2026 年 2 月 15 日。

2. 受影響範圍評估

確診受害主機： 內部跳板與開發伺服器（主機名稱與 IP 已匿名化）
初始感染源 (Patient Zero)： 該伺服器本身（因 SSH 對外開放且密碼遭暴力破解），已排除終端使用者 A 之個人電腦遭惡意程式感染的風險。
橫向移動風險評估： 雖然攻擊者主要目標為挖礦，但因其曾掌握 root 權限長達 80 餘天，伺服器上曾存放之使用者 B 的 SSH 私鑰、GitLab 密碼及各類環境變數 Token 均需視為「已遭曝露」。內網 K8s/RKE2 節點（30+ 台主機）具有潛在橫向感染風險，需全面清查。

3. 攻擊時間軸 (Timeline)

發生時間	攻擊階段	關鍵事件與動作描述
2026-01 至 02 月	初始存取 (Initial Access)	系統遭來自多個海外 IP (如 121.64.89.228) 之持續性 SSH 暴力破解攻擊，導致 `btmp` 錯誤登入日誌暴增至 258MB。
2026-02-15 13:06	破城與持久化	攻擊者成功猜中 `root`（或具 sudo 權限帳號）密碼。登入後上傳 Launcher (`/usr/bin/log`)。
2026-02-15 13:07	佈署後門	植入 Rootkit (`sshdd.so`)；建立幽靈帳號 `systemd` (UID 1003) 並修改 `/etc/sudoers` 賦予免密碼提權能力。
2026-02-15 13:08	降權執行挖礦	啟用 `/etc/ld.so.preload` 隱藏行蹤；切換為使用者 A 身份，下載並執行 XMRig 礦工 (`syst3md` / `/var/log/log`)。(註：此時下載的檔案帶有 2025-11-19 之原始 HTTP 標頭時間)。
2026-03-02	工具更新	攻擊者下載 `mOymN.gz` (6MB 工具包)。
2026-03-28	部署 DePIN 獲利	攻擊者上傳 `vortix-agent` (15.7MB) 並執行，開始利用 Vortix Cloud 進行算力出租獲利。
2026-04-18	持續活動	下載器腳本 `cli` 進行最後一次更新。
2026-05-06	偵測與應變	管理員發現異常 (LD_PRELOAD 攔截)，展開鑑識，確認入侵路徑並進行緊急止血。

4. 威脅指標 (IoCs)

4.1 惡意檔案與 Hash (SHA256)

Rootkit (/usr/local/lib/sshdd.so): acb2e78d748e9a22e80c386a58f6377f683fce556bc64da2bd6d82b2a9207e3c
Launcher (/usr/bin/log): c8e59338f471e255a40e13ef810db7db98ce018e417211ca0bdf90ef8cdd3894
XMRig Miner (/var/log/log & /var/tmp/syst3md.1): dcf343df280816c4856ee164b9b4b14906a09b1fd4bfab604ee9370529ed61d1
Vortix CLI (/var/tmp/cli): c21fa4c1d6ed5342e49ef0561cc566a2cbe06a83f6298374fe9cb4f8027b6911
Vortix Agent (/var/tmp/vortix-agent): c6b67c7ffc11c67eea889b8e0eef6891123123388297e0deaa490837a7b06833
Tool Archive (/var/tmp/mOymN.gz): ac15860162f216d03e374d07f7eeb42944e4b0f08e78ea2468f3df9cbdb860cf

4.2 系統入侵跡證

檔案隱藏機制： /etc/ld.so.preload (內容包含 /usr/local/lib/sshdd.so)
持久化服務： /etc/systemd/system/log.service
Cron 後門： /etc/cron.hourly/0 (權限 5777，大小 0 bytes)
提權後門帳號：
- /etc/passwd 中存在偽裝帳號 systemd:x:1003:1003:...
- /etc/sudoers 中存在越權設定 systemd ALL=(ALL) NOPASSWD:ALL

4.3 網路與通訊 (Network/C2)

77.221.157.206:6196 (Rootkit 內建 C2)
141.95.72.59 (Rootkit 內建 C2)
139.99.125.38 (Rootkit 內建 C2)
139.99.123.196 (Rootkit 內建 C2)
141.94.96.71:3333 (活動礦池)
94.26.106.195 (HTTP Staging Server，提供 cli 等惡意程式下載)
pool.supportxmr.com:9000 (合法 Monero 礦池，遭濫用)

4.4 攻擊者 Vortix DePIN 識別標記 (Tokens)

uUbGvGz7zAMgGtHsTo8EOi1krvj+OPi7SF5UMeoCJnU=
jUliaNLclI34oUpjC7ewra/HjEuw+UgYa7jrpxMBC3k=

5. 攻擊手法分析 (MITRE ATT&CK Mapping)

階段策略	技術編號	技術名稱	具體行為對應
Initial Access	T1110.001	Password Guessing	針對伺服器對外 SSH 服務進行密集密碼暴力破解。
Execution	T1059.004	Unix Shell	利用 Bash 執行 `wget`/`curl` 下載腳本與執行檔。
Privilege Escalation	T1548.003	Sudo and Sudo Caching	建立 `systemd` 帳號並於 `/etc/sudoers` 寫入 `NOPASSWD:ALL` 後門。
Defense Evasion	T1070.006	Timestomp	利用 `wget` 預設行為保留伺服器端舊時間戳記，造成調查干擾。
Defense Evasion	T1548.002	Bypass User Account Control	取得 `root` 後刻意切換為使用者 A 身份執行耗能程式，規避直覺查緝。
Defense Evasion	T1574.006	Dynamic Linker Hijacking	植入 `sshdd.so` 劫持 `LD_PRELOAD`，攔截目錄與檔案讀取 API。
Persistence	T1546.004	Unix shell Configuration	利用 Systemd (`log.service`) 與 Cron (`/etc/cron.hourly/0`) 進行駐留。
Impact	T1496	Resource Hijacking	同時執行 XMRig 與 Vortix Agent，劫持運算力進行雙重加密貨幣獲利。

6. 處置與防護建議

6.1 立即止血 (Containment)

強制中止惡意程序： 中止 /var/log/log、/usr/bin/log、cli、vortix-agent 等程序，並全面停用 log.service。
根除 Rootkit 與實體檔案： 刪除 /etc/ld.so.preload 解除系統攔截，清理 /var/tmp/ 下之所有惡意工具與備份。
封堵後門帳號： 於 /etc/passwd、/etc/shadow 刪除 systemd 偽裝帳號，並修改 /etc/sudoers 移除越權規則。
網路封鎖： 於上層防火牆 (Firewall/Security Group) 設定阻擋已知之 C2 節點、礦池 IP 及 Staging Server。

6.2 系統重建與憑證輪替 (Eradication & Recovery)

作業系統重裝： 由於伺服器曾遭 Rootkit 高度掌控逾 80 天，強烈建議從乾淨的 ISO 映像檔重新安裝作業系統，僅可遷移純資料檔案（如設定檔、資料庫 dump），切勿直接複製執行檔或系統腳本。
全面撤銷與輪替憑證：
- 強制重設所有伺服器本機帳號密碼。
- 撤銷伺服器上使用者 A、使用者 B 等所有使用者的 SSH 私鑰，並重新核發。
- 重設所有可能於伺服器上曝露之第三方憑證（如 GitLab Admin、K8s Secret 等）。

6.3 長期安全強化 (Post-Incident)

阻斷暴力破解根源 (最高優先級)： 修改 /etc/ssh/sshd_config，設定 PasswordAuthentication no，全面強制僅能使用 SSH 金鑰登入。
存取來源限制： 透過防火牆限制 SSH 服務僅允許信任的來源 IP（如公司 VPN 網段）連線。
橫向掃描與威脅通報：
- 使用本報告之 IoC 腳本，清查使用者 B 曾登入過之內網 K8s 節點。
- （選用）附上攻擊者 Token 向 abuse@vortix.cloud 提出檢舉，阻斷攻擊者利用合法 DePIN 平台之洗錢管道。

Gemini CLI `/init` 異常延遲重現步驟

Tue, 05 May 2026 02:08:38 +0800

背景

原始 session 中,執行 /init 後 Gemini CLI 花了約 1 小時 25 分鐘才完成 GEMINI.md 的產出。從 log 抽出的 tool call 時間戳顯示有兩個明顯卡點:

卡點 1:/init 送出 → 第一個 tool call,等了 約 45 分鐘
卡點 2:list 根目錄 → list openspec/specs 子目錄,等了 約 31 分鐘

本文件目的是讓問題可被重現,以利後續判斷成因或回報 bug。

環境前置條件

重現前需準備與原情境一致的環境:

Gemini CLI 版本:0.40.1(stable,2026 年 4 月底發布)
OpenSpec 版本:1.3.1(2026 年 4 月下旬發布,latest 為當下最新)
Node.js / npm 已安裝(openspec 需要 Node.js 20.19.0 或更新)
OS:Linux
使用者 preference:永遠使用繁體中文回應

若要重新驗證版本:

Gemini CLI:gemini /about 或 gemini --version

OpenSpec:openspec --version

若要強制升級到當下最新 stable:

Gemini CLI:npm install -g @google/gemini-cli@latest

OpenSpec:npm install -g @fission-ai/openspec@latest

一鍵建立 workspace

mkdir -p ~/k8s/workload/graceful-shutdown
sudo npm install -g @fission-ai/openspec
cd ~/k8s/workload/graceful-shutdown
openspec init --tools gemini

openspec init --tools gemini 會自動產出以下結構,內含 .gemini/commands/opsx/ 的 4 個 toml 指令、.gemini/skills/openspec-*/ 的 4 個 SKILL.md,以及 openspec/changes/archive/ 與 openspec/specs/ 兩個空目錄:

graceful-shutdown/
├── .gemini/
│ ├── commands/opsx/
│ │ ├── apply.toml
│ │ ├── archive.toml
│ │ ├── explore.toml
│ │ └── propose.toml
│ └── skills/
│ ├── openspec-apply-change/SKILL.md
│ ├── openspec-archive-change/SKILL.md
│ ├── openspec-explore/SKILL.md
│ └── openspec-propose/SKILL.md
└── openspec/
├── changes/archive/
└── specs/

啟動 CLI(建議開啟 debug log + YOLO 模式)

cd ~/k8s/workload/graceful-shutdown
script -q /tmp/gemini-repro.log -c 'gemini --debug --yolo'

--debug 在卡住時可以從 log 看出是 retry、thinking、還是在等 API。

--yolo 會自動同意所有 tool 呼叫的確認對話,避免重現過程被 plan / write_file / shell 的確認 prompt 打斷,確保延遲現象來自 Gemini 本身而非「等使用者按 yes」。

script 指令會保留 TTY 讓互動模式正常運作,同時把整個 terminal session 錄到指定檔案。結束時按 Ctrl+D 或輸入 exit。

替代方案:若不需要 log 檔,直接 gemini --debug --yolo 即可。互動模式的 log 也會自動寫到 ~/.gemini/ 底下,可在 CLI 內輸入 /about 或 /bug 查詢確切路徑。

重現步驟

Step 1 — 完整需求

輸入:

/plan 我想搭配 openspec 的流程開發一套 go 語言寫的 http server,這網站要能夠接住 sigint 和 sigterm 的訊號,並執行 graceful shutdown,這網站最終要部署在 K8s 上,並且 CNI 是 cilium 還有啟用 kubeproxy replacement,pod 狀態為 Terminating 的時候,要執行 prestop hook sleep 2s,不要寫在 source code 裡面

預期行為:Gemini 進入 Plan Mode,使用 openspec-propose skill 並輸出計畫摘要。

Step 2 — 確認 plan(第一次)

輸入:

好

執行結果：

✦ I have drafted the detailed implementation plan. Please review it below:
1 # Implementation Plan: Graceful Shutdown Go HTTP Server
2
3 ## Background & Motivation
4 The objective is to build a Go-based HTTP server capable of performing a graceful shutdown when receiving `SIGINT` or `SIGTERM` signals. The application
will be deployed on a Kubernetes cluster utilizing the Cilium CNI with kube-proxy replacement. To ensure zero downtime during pod termination, a `preStop`
hook sleeping for 2 seconds must be configured at the deployment level rather than being hardcoded in the application logic. The development process will be
guided by the `openspec` workflow.
5
6 ## Scope & Impact
7 - **Go Application**: Create a basic HTTP server in Go that listens for termination signals and shuts down gracefully using context timeouts.
8 - **Dockerization**: Create a `Dockerfile` to containerize the Go application.
9 - **Kubernetes Manifests**: Create a Deployment and Service manifest. The Deployment must include a `lifecycle.preStop` hook to execute `sleep 2`.
10 - **Process**: Utilize `openspec-propose` to generate standard artifacts (`proposal.md`, `design.md`, `tasks.md`).
11
12 ## Proposed Solution
13 1. **OpenSpec Setup**: Use the `openspec` CLI to scaffold a new change (`graceful-shutdown-go-server`) and generate the required artifacts.
14 2. **Implementation**:
15 - Write `main.go` using `net/http` and `os/signal`.
16 - Create a minimal `Dockerfile` (e.g., multi-stage build starting from `golang:alpine`).
17 - Define `deployment.yaml` with the `preStop` hook (`command: ["/bin/sh", "-c", "sleep 2"]`).
18 3. **Verification**: Confirm the application builds, the Docker image can be created, and the Kubernetes manifests are structurally correct and contain the
requested hooks.
19
20 ## Alternatives Considered
21 - *Hardcoding sleep in Go*: Rejected as per the requirement to handle the delay externally via Kubernetes lifecycle hooks to keep the application code
focused on application-level shutdown logic rather than orchestration-specific workarounds.
22
23 ## Phased Implementation Plan
24 - **Phase 1: OpenSpec Artifacts**: Exit Plan Mode, create the `openspec` change, and let the `openspec-propose` skill generate the documentation artifacts.
25 - **Phase 2: Code Implementation**: Write the Go source code and Dockerfile.
26 - **Phase 3: Kubernetes Manifests**: Write the Deployment and Service configurations, ensuring the `preStop` hook is correctly defined.
27
28 ## Verification
29 - Code review of the Go server to ensure signal handling and context usage.
30 - Verification of the `deployment.yaml` to confirm the presence of the `preStop` hook.
31
32 ## Migration & Rollback
33 - N/A (New deployment).
Does this detailed plan look correct to you? If so, I will proceed to formally submit it for approval so we can begin execution.

Step 4 — 要求繁中

請注意永遠必須要使用繁體中文

執行結果：

✦ 接下來，我將讀取該變更的狀態，以確定需要產生哪些產出物。
╭────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ ✓ Shell openspec status --change "graceful-shutdown-go-server" --json │
│ │
│ ... first 32 lines hidden (Ctrl+O to show) ... │
│ "status": "blocked", │
│ "missingDeps": [ │
│ "design", │
│ "specs" │
│ ] │
│ } │
│ ] │
│ } │
│ Process Group PGID: 5697 │
╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
✦ 根據狀態，我需要先建立 proposal。我會先獲取 proposal 的指令與模板。
╭────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ ✓ Shell openspec instructions proposal --change "graceful-shutdown-go-server" --json │
│ │
│ ... first 7 lines hidden (Ctrl+O to show) ... │
│ "instruction": "Create the proposal document that establishes WHY this change is needed.\n\nSections:\n- **Why**: 1-2 sentences on the problem or │
│ opportunity. What problem does this solve? Why now?\n- **What Changes**: Bullet list of changes. Be specific about new capabilities, modifications, or │
│ removals. Mark breaking changes with **BREAKING**.\n- **Capabilities**: Identify which specs will be created or modified:\n - **New Capabilities**: List │
│ capabilities being introduced. Each becomes a new `specs/<name>/spec.md`. Use kebab-case names (e.g., `user-auth`, `data-export`).\n - **Modified │
│ Capabilities**: List existing capabilities whose REQUIREMENTS are changing. Only include if spec-level behavior changes (not just implementation details). │
│ Each needs a delta spec file. Check `openspec/specs/` for existing spec names. Leave empty if no requirement changes.\n- **Impact**: Affected code, APIs, │
│ dependencies, or systems.\n\nIMPORTANT: The Capabilities section is critical. It creates the contract between\nproposal and specs phases. Research │
│ existing specs before filling this in.\nEach capability listed here will need a corresponding spec file.\n\nKeep it concise (1-2 pages). Focus on the │
│ \"why\" not the \"how\" -\nimplementation details belong in design.md.\n\nThis is the foundation - specs, design, and tasks all build on this.\n", │
╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
✦ 我現在來撰寫 proposal.md。
✓ WriteFile proposal.md → Accepted (+24, -0)
1 ## Why
2
3 為了確保部署在 Kubernetes (使用 Cilium CNI 且啟用 kube-proxy replacement) 上的 Go HTTP 伺服器在 Pod 終止過程中不會遺失請求，我們需要實作 Graceful
Shutdown 機制，並搭配 Kubernetes 的 `preStop` hook。這樣可以確保在 Pod 進入 Terminating 狀態後，仍有緩衝時間處理剩餘請求。
4
5 ## What Changes
6
7 - 實作 Go 語言的 HTTP 伺服器，支援監聽 `SIGINT` 與 `SIGTERM` 訊號。
8 - 呼叫 `http.Server.Shutdown()` 方法以優雅地關閉連線。
9 - 提供 `Dockerfile` 用於容器化部署。
10 - 提供 Kubernetes Deployment 與 Service 清單 (Manifests)。
11 - 在 Deployment 中加入 `lifecycle.preStop` hook 執行 `sleep 2`。
12
13 ## Capabilities
14
15 ### New Capabilities
16 - `graceful-shutdown-server`: 提供一個具備訊號監聽與優雅關閉能力的 HTTP 伺服器，並包含 K8s 部署設定。
17
18 ### Modified Capabilities
19 <!-- 無 -->
20
21 ## Impact
22
23 - **應用程式**: 新增 `main.go` 處理伺服器啟動與關閉邏輯。
24 - **基礎設施**: 新增 K8s Deployment 與 Service 設定，影響 Pod 的生命週期管理。
✦ proposal.md 已建立。現在我再次檢查狀態，並獲取 design 的指令。
╭────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ ✓ Shell openspec status --change "graceful-shutdown-go-server" --json │
│ │
│ ... first 26 lines hidden (Ctrl+O to show) ... │
│ "status": "blocked", │
│ "missingDeps": [ │
│ "design", │
│ "specs" │
│ ] │
│ } │
│ ] │
│ } │
│ Process Group PGID: 5768 │
╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
✦ 我將先獲取 design 的指令。
╭────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ ✓ Shell openspec instructions design --change "graceful-shutdown-go-server" --json │
│ │
│ ... first 13 lines hidden (Ctrl+O to show) ... │
│ "path": "proposal.md", │
│ "description": "Initial proposal document outlining the change" │
│ } │
│ ], │
│ "unlocks": [ │
│ "tasks" │
│ ] │
│ } │
│ Process Group PGID: 5803 │
╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
✦ 現在我來撰寫 design.md。
✓ WriteFile design.md → Accepted (+28, -0)
1 ## Context
2
3 目前需要一個能夠在 Kubernetes 環境中安全退場的 Go 伺服器。由於 Kubernetes 的 Service 負載平衡與 Pod 終止是非同步進行的，若不設定 `preStop` hook 與
Graceful Shutdown，可能會在 Pod 關閉期間漏掉部分請求。
4
5 ## Goals / Non-Goals
6
7 **Goals:**
8 - 實作訊號處理邏輯以支援優雅關閉。
9 - 配置 K8s 生命週期鉤子 (`preStop`)。
10 - 確保程式碼簡潔且符合 Go 最佳實踐。
11
12 **Non-Goals:**
13 - 實作複雜的業務邏輯。
14 - 設定進階的 Cilium 網路政策（僅關注 shutdown 流程）。
15
16 ## Decisions
17
18 - **訊號處理**: 使用 `os/signal` 監聽 `SIGINT` (Ctrl+C) 與 `SIGTERM` (K8s 終止訊號)。
19 - **優雅關閉**: 使用 `http.Server.Shutdown()` 並設定 5-10 秒的超時 context，確保進行中的請求有時間完成。
20 - **Kubernetes 整合**:
21 - 在 Deployment 中加入 `lifecycle.preStop.exec` 執行 `sleep 2`。
22 - 理由：這讓 Cilium CNI 有足夠的時間從 eBPF 表中移除該 Pod 的 IP，避免新的請求進來，而此時應用程式已進入關閉流程。
23 - **容器化**: 使用多階段建置 (multi-stage build) 以縮小映像檔體積並提高安全性。
24
25 ## Risks / Trade-offs
26
27 - **[Risk]**: `preStop` hook 時間過短。 → **Mitigation**: 預設 2 秒符合一般 Cilium 環境下 kube-proxy replacement 的收斂速度。
28 - **[Risk]**: 應用程式關閉時間超過 `terminationGracePeriodSeconds`。 → **Mitigation**: 確保 Go 的 `Shutdown` context timeout 小於 K8s 的預設 30 秒。
✦ design.md 已完成。現在我需要建立 specs。根據 proposal，我定義了一個新能力 graceful-shutdown-server。
我將獲取 specs 的指令。
╭────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ ✓ Shell openspec instructions specs --change "graceful-shutdown-go-server" --json │
│ │
│ ... first 13 lines hidden (Ctrl+O to show) ... │
│ "path": "proposal.md", │
│ "description": "Initial proposal document outlining the change" │
│ } │
│ ], │
│ "unlocks": [ │
│ "tasks" │
│ ] │
│ } │
│ Process Group PGID: 5850 │
╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
✦ 我將建立 openspec/changes/graceful-shutdown-go-server/specs/graceful-shutdown-server/spec.md。
✓ WriteFile spec.md → Accepted (+22, -0)
1 ## ADDED Requirements
2
3 ### Requirement: 訊號監聽 (Signal Handling)
4 伺服器必須監聽 `os.Interrupt` (SIGINT) 與 `syscall.SIGTERM` 訊號。
5
6 #### Scenario: 接收到終止訊號
7 - **WHEN** 伺服器接收到 SIGTERM 訊號
8 - **THEN** 伺服器啟動關閉程序並停止接受新請求
9
10 ### Requirement: 優雅關閉 (Graceful Shutdown)
11 伺服器必須在關閉前等待現有連線處理完畢，並設定超時機制。
12
13 #### Scenario: 關閉程序執行
14 - **WHEN** 呼叫 Shutdown 方法
15 - **THEN** 伺服器等待所有作用中請求完成，或直到達到 10 秒超時為止
16
17 ### Requirement: Kubernetes PreStop Hook
18 部署清單必須包含 PreStop 鉤子以延遲應用程式關閉。
19
20 #### Scenario: Pod 進入 Terminating 狀態
21 - **WHEN** Kubernetes 將 Pod 標記為 Terminating
22 - **THEN** PreStop 鉤子執行 `sleep 2`，延遲傳送 SIGTERM 訊號給容器
✦ 現在 proposal, design, specs 都已完成。最後我需要建立 tasks。
我將獲取 tasks 的指令。
╭────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ ✓ Shell openspec instructions tasks --change "graceful-shutdown-go-server" --json │
│ │
│ ... first 17 lines hidden (Ctrl+O to show) ... │
│ "id": "design", │
│ "done": true, │
│ "path": "design.md", │
│ "description": "Technical design document with implementation details" │
│ } │
│ ], │
│ "unlocks": [] │
│ } │
│ Process Group PGID: 5894 │
╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
✦ 我將建立 tasks.md。
✓ WriteFile tasks.md → Accepted (+17, -0)
1 ## 1. 專案初始化與 Go 伺服器實作
2
3 - [ ] 1.1 初始化 Go 專案 (`go mod init`)
4 - [ ] 1.2 在 `main.go` 中實作基礎 HTTP 伺服器
5 - [ ] 1.3 實作訊號監聽邏輯 (`SIGINT`, `SIGTERM`)
6 - [ ] 1.4 實作優雅關閉邏輯 (`http.Server.Shutdown`)
7
8 ## 2. 容器化
9
10 - [ ] 2.1 撰寫多階段建置的 `Dockerfile`
11 - [ ] 2.2 測試本地映像檔建置
12
13 ## 3. Kubernetes 部署清單
14
15 - [ ] 3.1 撰寫 Service 清單
16 - [ ] 3.2 撰寫 Deployment 清單，並加入 `lifecycle.preStop` hook 與 `sleep 2`
17 - [ ] 3.3 驗證 Manifests 語法正確性
✦ 所有產出物均已建立。我將檢查最終狀態。
╭────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ ✓ Shell openspec status --change "graceful-shutdown-go-server" │
│ │
│ ... first 2 lines hidden (Ctrl+O to show) ... │
│ Progress: 4/4 artifacts complete │
│ │
│ [x] proposal │
│ [x] design │
│ [x] specs │
│ [x] tasks │
│ │
│ All artifacts complete! │
│ Process Group PGID: 5950 │
╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
✦ 所有 OpenSpec 產出物已準備就緒！
- 變更名稱: graceful-shutdown-go-server
- 位置: openspec/changes/graceful-shutdown-go-server/
- 已建立產出物:
- proposal.md: 概述為何需要此變更。
- design.md: 詳述技術決策（訊號處理、K8s Hook、多階段建置）。
- specs/graceful-shutdown-server/spec.md: 定義功能需求與測試情境。
- tasks.md: 實作檢查清單。
準備好開始實作了！
您可以輸入 /opsx:apply 或直接要求我開始執行任務。

Step 5 — 觸發 `/init`(關鍵卡點 1)

這是第一個延遲發生的位置。

在 CLI 輸入:

/init

Gemini CLI 會將其展開為內建的長 prompt(以「You are an AI agent that brings the power of Gemini directly into the terminal…」開頭),要求模型分析當前目錄並產生 GEMINI.md。

預期觀察:模型可能長時間停留在「Thinking…」狀態而未呼叫任何工具。原 session 此處等了約 45 分鐘。

建議在此設定計時器,若超過 5 分鐘無任何輸出,記錄當下時間。

Step 6 — Tool 執行間卡頓(關鍵卡點 2)

不需輸入任何內容,此為自動發生。

當 Gemini 終於開始動作後,會先 list_directory .,然後嘗試 list_directory openspec/specs。

預期觀察:這兩個 list_directory 呼叫之間可能再次出現長時間靜默。原 session 此處等了約 31 分鐘。

Step 7 — 驗證 CLI 是否還活著

若你想確認 CLI 是否真的卡住而非完成,可在另一個視窗或等到回到 prompt 後輸入:

hello?

觀察重點與紀錄

建議用一個簡單表格記錄每次重現的結果:

步驟	開始時間	結束時間	耗時	備註
Step 1-4(openspec 流程)
Step 5(`/init` 送出 → 第一個 tool call)				卡點 1
Step 6(list root → list specs)				卡點 2
Step 5-6 總和(`/init` → 寫完 GEMINI.md)

對照組建議(強烈建議跑)

為了確認延遲是否與 openspec 流程或累積 context 有關,建議再做以下對照:

對照組 A:空目錄獨立 `/init`

開新空目錄 mkdir /tmp/clean-test && cd /tmp/clean-test
啟動 gemini --debug
直接執行 /init
記錄完成時間

若 A 在數分鐘內完成,而原情境需 1 小時,可確認延遲與「已有檔案的目錄 + 累積 context」相關。

對照組 B:同目錄但全新 session

在原本的 graceful-shutdown 目錄(已含 openspec 產物)
開新 session(關閉舊的、重開 gemini)
直接執行 /init,跳過 Step 1-4
記錄完成時間

若 B 比原情境快很多,可確認延遲與「同 session 內累積的 context」相關。

蒐集的資訊(回報 bug 時附上)

執行 /about 取得:

CLI Version
Git Commit
Model(特別注意是不是 Auto / preview 模型)
Auth Method
Tier(免費/付費)

並一併附上 /tmp/gemini-repro.log 的 debug log。

啟動 log 已透露的線索

第一次嘗試啟動時,雖然指令寫法錯誤導致 CLI 立即退出,但啟動階段的 debug log 已透露幾個與本案延遲可能相關的訊息,值得在後續分析時納入考量:

Ripgrep is not available. Falling back to GrepTool. 此版本未安裝 ripgrep,搜尋將使用較慢的內建 GrepTool。/init 需要掃描整個專案目錄,這雖不至於造成小時級延遲,但會放大整體耗時。 v0.40 開始已將 ripgrep bundle 進 SEA 版本,以 npm 安裝可能未包含,可考慮另外安裝 ripgrep 套件。
Experiment flag 45773134 = 300、45773135 = 600 數值單位推測為秒,對應 5 分鐘和 10 分鐘,符合常見的 timeout / retry backoff 閾值。若後續 debug log 出現的延遲區間是 5/10 分鐘的倍數,很可能就是這兩個 flag 控制的 retry 行為。
Experiment flag 45740200 的官方公告 原文(節錄):「We are adding more robust detection of policy-violating use cases and changing how we prioritize traffic. This may result in higher capacity-related errors during periods of high traffic.」說明 Google 近期正在調整 traffic 優先順序,確實可能讓 capacity-related error 增加。這與「卡點期間其實是 backend 排隊或被節流」的推測相符。公告連結:https://goo.gle/geminicli-updates

已知相關 issues(供參考)

以下三個 issue 與本案症狀高度相符,截至 v0.40.1(本文件撰寫時的最新 stable)仍為 open,在 v0.39 ~ v0.40 的 changelog 中均未見對應 fix:

google-gemini/gemini-cli#22141 — Gemini CLI becomes extremely slow (1+ HOURS) / stuck during small code-edit tasks
google-gemini/gemini-cli#17442 — CLI Agent Intermittent Long Loading Times/Hangs During Tool Execution
google-gemini/gemini-cli#26126 — Stuck at “Thinking”

另一個與 /init 直接相關但症狀不同的 issue(僅供參考):

google-gemini/gemini-cli#6984 — /init command hangs at “Concluding the Process”

Ubuntu XFCE 安裝繁體中文輸入法 & 設定左 Shift 切換中英文

Mon, 04 May 2026 12:46:10 +0800

環境

作業系統:Ubuntu Desktop
桌面環境:XFCE
連線方式:透過 RDP 連入(xrdp)
輸入法框架:IBus
目標:使用 Chewing(新酷音)輸入繁體中文,並用單按左 Shift 切換中英文

本文件適用於已使用 IBus 框架的 XFCE 環境。如果你的桌面是 GNOME,設定方式會不同;GNOME Shell 不接受純 modifier 鍵當切換熱鍵。

步驟一:確認環境

1-1 確認桌面環境

echo $XDG_CURRENT_DESKTOP
echo $DESKTOP_SESSION

預期輸出:

XFCE
xfce

1-2 確認目前的輸入法框架

echo $GTK_IM_MODULE $QT_IM_MODULE $XMODIFIERS

預期輸出:

ibus ibus @im=ibus

1-3 確認 IBus daemon 正常運作

ps aux | grep ibus-daemon

預期輸出(關鍵在 --xim 參數要存在):

bigred 5010 0.1 0.0 457360 8652 ? Ssl 20:33 0:00 /usr/bin/ibus-daemon --daemonize --xim

步驟二:確認 / 安裝中文輸入法引擎

2-1 確認系統有 Chewing 引擎

ibus list-engine | grep -i -E "chewing|pinyin|bopomofo|rime|cangjie"

預期輸出(看到 chewing - Chewing 即代表已安裝):

language: Pinyin
chewing - Chewing
language: Tatar, Crimean
xkb:ua:crh_f:crh - Crimean Tatar (Turkish F)
...

2-2 若沒有 Chewing,執行以下指令安裝

sudo apt update
sudo apt install ibus-chewing
ibus restart

步驟三:確認輸入法清單包含 English 與 Chewing

gsettings get org.freedesktop.ibus.general preload-engines

預期輸出:

['xkb:us::eng', 'chewing']

如果清單不對,用以下指令設定:

gsettings set org.freedesktop.ibus.general preload-engines "['xkb:us::eng', 'chewing']"

步驟四:設定環境變數(關鍵步驟)⭐

這是讓設定能穩定生效的關鍵。即使目前 echo $GTK_IM_MODULE 顯示為 ibus,也要把它寫入 ~/.xprofile,確保 XFCE session 啟動時一定會載入。

4-1 檢查目前狀態

cat ~/.xprofile 2>/dev/null
cat ~/.profile 2>/dev/null | grep -E "GTK_IM_MODULE|QT_IM_MODULE|XMODIFIERS"

如果兩個指令都沒輸出,代表環境變數沒寫在使用者層級的設定檔。雖然系統可能有臨時注入,但不夠穩定,要明確寫入。

4-2 寫入 ~/.xprofile

cat > ~/.xprofile << 'EOF'
export GTK_IM_MODULE=ibus
export QT_IM_MODULE=ibus
export XMODIFIERS=@im=ibus
EOF

4-3 確認檔案內容

cat ~/.xprofile

預期輸出:

export GTK_IM_MODULE=ibus
export QT_IM_MODULE=ibus
export XMODIFIERS=@im=ibus

步驟五:設定左 Shift 為切換熱鍵

5-1 開啟 IBus 設定

ibus-setup

5-2 設定 Next input method 為 Shift_L

在 General 分頁:

找到 Keyboard Shortcuts 區塊的 Next input method 欄位
點右側的 ... 按鈕開啟設定視窗
刪除清單裡所有現有的快捷鍵(例如 <Shift>space)
在 Key code 欄位手動輸入:
```
Shift_L
```
Modifiers 區的所有勾選都不要勾(Shift / Ctrl / Alt / Super 全部不勾)
點 Add,再點 OK

設定完成後主畫面的 Next input method 欄位應顯示為:

Shift_L

注意:Modifiers 一個都不能勾。如果勾了 <Shift> 變成 modifier 用,或是寫成組合鍵(例如 <Control>Shift_L),都會導致切換行為異常。

5-3 重啟 IBus

ibus restart

步驟六:測試

開啟任一支援文字輸入的應用程式(文字編輯器、瀏覽器網址列等),按下左 Shift 鍵,應該會看到:

右上角(或工作列上)的 IBus 圖示在 EN 與中文圖示之間切換
切到中文模式後,可正常用注音輸入繁體中文
Shift + 字母鍵(如 Shift+a) 仍然正常輸出大寫字母,不會誤觸切換

完整指令速查

整個流程可以濃縮成以下幾步:

# 1. 確認環境
echo $XDG_CURRENT_DESKTOP # 應為 XFCE
echo $GTK_IM_MODULE $QT_IM_MODULE $XMODIFIERS # 應為 ibus ibus @im=ibus
ps aux | grep ibus-daemon # 確認有 --xim

# 2. 確認引擎
ibus list-engine | grep -i chewing # 應看到 chewing - Chewing
gsettings get org.freedesktop.ibus.general preload-engines # 應為 ['xkb:us::eng', 'chewing']

# 3. 寫入環境變數(關鍵)
cat > ~/.xprofile << 'EOF'
export GTK_IM_MODULE=ibus
export QT_IM_MODULE=ibus
export XMODIFIERS=@im=ibus
EOF

# 4. 開設定 → Next input method 設成 Shift_L (Modifiers 全不勾)
ibus-setup

# 5. 重啟 IBus
ibus restart

故障排除

症狀	可能原因	解法
按 Shift 完全沒反應	環境變數未生效	確認 `~/.xprofile` 已寫入,登出再登入 RDP session
按任何鍵都會觸發切換	Modifiers 勾選了 `<Shift>`,或 IBus 把 Shift_L 當 modifier 處理	重新進 ibus-setup,確認 Modifiers 完全沒勾
切換到中文後切不回英文	快捷鍵設成 `<Control>Shift_L` 等 modifier 組合,IBus 對這類組合切換不穩定	改回單獨 `Shift_L`,或改用 `<Shift>space`、`<Super>space`
螢幕中央跳出選單但右上角不變	IBus 與桌面環境通訊不同步	重啟 IBus(`ibus restart`),必要時重新登入 session
Shift+字母變成切換而不是大寫	同上(modifier 處理錯誤)	重新檢查 ibus-setup 的設定

備註:為什麼 XFCE 可以這樣設,GNOME 不行

GNOME Shell 會強制攔截輸入法熱鍵,並要求快捷鍵至少包含一個非 modifier 鍵,因此單按 Shift 在 GNOME 上做不到。
XFCE 不會攔截熱鍵,IBus 可以完整接管,所以單按 Shift_L 切換才有機會穩定運作。
如果一定要在 GNOME 上實現單按 Shift 切換,需要改用 Fcitx5 框架(它自己接管熱鍵處理,可繞過 GNOME 的限制)。

在 Alpine Linux 上修復 Gemini CLI Segfault

Mon, 04 May 2026 10:10:44 +0800

環境:Alpine Linux 3.23、x86_64、Node.js(apk 套件版) 症狀:Gemini CLI 在互動模式下 thinking 後直接退出,看似當機卻沒錯誤訊息解法:11 行 C code 的 LD_PRELOAD shim,補上 musl 缺少的 2 個 glibc 符號

TL;DR(只想看解法的請從這裡開始)

如果你已經確認是同樣問題,直接跳到完整修復步驟。

如果想了解問題定位過程,請從症狀開始讀。

症狀

在 Alpine Linux 上用 apk add nodejs npm 裝好 Node 後,用 npm 安裝 Gemini CLI:

npm install -g @google/gemini-cli

啟動互動模式並嘗試讓 Gemini 執行 shell 指令:

gemini

輸入任何會觸發 shell tool 的 prompt,例如:

請執行 shell 指令: openspec new change test

Gemini 顯示「Thinking…」幾秒後,直接退回 shell prompt,沒有任何錯誤訊息。

更詭異的:

gemini -p "echo hello"(headless 模式)不會 crash,但會出現 Tool "run_shell_command" not found 警告
互動模式才 crash,且每次都 crash

除錯過程

Step 1:啟用 core dump

Gemini crash 時什麼錯誤訊息都沒有,所以第一步是讓系統在 crash 時把記憶體狀態完整保存下來,後續才能分析。

# 允許 core dump 沒有大小限制
ulimit -c unlimited

# 設定 core dump 寫到 /tmp,檔名包含程序名跟 PID
sudo sysctl -w kernel.core_pattern=/tmp/core.%e.%p

注意:ulimit -c 只在當前 shell 有效。如果開新 terminal 要重設一次。

Step 2:重現 crash 並確認 core dump 有產生

gemini

進去後輸入會觸發 crash 的 prompt(任何要跑 shell 的都行):

請執行 shell 指令: ls

等它 thinking 後直接退出,然後檢查:

$ ls -la /tmp/core.* 2>/dev/null
-rw------- 1 bigred bigred 877506560 May 4 17:22 /tmp/core.MainThread.12320

看到一個 877 MB 的 core dump,程序名為 MainThread(Node.js 22+ 對 main thread 的命名)。

這個 core dump 確認了兩件事:

Crash 是真的 SIGSEGV(系統有寫 core dump,代表是異常終止)
記憶體用量正常(877 MB 對 Node 程式不算大,排除記憶體不足)

Step 3:從 core dump 找出載入的 native modules

.node 檔案是 Node.js 的 native binding(C++ 編譯的模組)。crash 多半發生在這類模組,所以先列出 crash 當下載入了哪些:

$ readelf -n /tmp/core.MainThread.12320 2>/dev/null | grep "\.node$"
.../node_modules/@github/keytar/build/Release/keytar.node
.../node_modules/@lydell/node-pty-linux-x64/pty.node

兩個嫌疑犯:

keytar.node(處理系統 keychain)
pty.node(處理 PTY,讓 Gemini 能跑 shell 指令)

Step 4:檢查 .node 檔案的符號解析

$ ldd /opt/node-musl/lib/node_modules/@google/gemini-cli/node_modules/@github/keytar/build/Release/keytar.node
 /lib/ld-musl-x86_64.so.1 (0x7feffb852000)
 libsecret-1.so.0 => /usr/lib/libsecret-1.so.0
 libglib-2.0.so.0 => /usr/lib/libglib-2.0.so.0
 ...
 # 沒有 "symbol not found" → keytar 沒問題

$ ldd /opt/node-musl/lib/node_modules/@google/gemini-cli/node_modules/@lydell/node-pty-linux-x64/pty.node
 /lib/ld-musl-x86_64.so.1 (0x7fd30e512000)
 libutil.so.1 => /lib/ld-musl-x86_64.so.1
 ...
Error relocating .../pty.node: napi_call_threadsafe_function: symbol not found
Error relocating .../pty.node: napi_get_cb_info: symbol not found
Error relocating .../pty.node: napi_create_object: symbol not found
Error relocating .../pty.node: __asprintf_chk: symbol not found
Error relocating .../pty.node: fcntl64: symbol not found
... (40+ 個 symbol not found)

找到嫌疑犯:pty.node 有 40 多個 symbol 解析失敗。

Step 5:辨識真正的「致命」符號

過濾掉 N-API 相關的(那些是 ldd 假警報,實際 dlopen 時會從 node binary 解析):

$ ldd .../pty.node 2>&1 | grep "symbol not found" | grep -v napi_
__asprintf_chk
fcntl64

只缺這兩個 glibc 符號:

__asprintf_chk:glibc _FORTIFY_SOURCE 提供的硬化版 asprintf
fcntl64:glibc 32-bit 系統用的 64-bit file offset 版 fcntl(x86_64 上等同 fcntl)

兩者 musl libc 都沒提供。

Step 6:確認 gcompat 也沒提供這兩個符號

$ sudo apk info gcompat | head -3
gcompat-1.1.0-r4 description:
GNU C Library compatibility layer for musl

$ nm -D /usr/lib/libgcompat.so.0 | grep -E "asprintf|fcntl"
# (空)

連最新版 gcompat(已是最新 1.1.0-r4)都沒實作這兩個。

Step 7:確認 N-API 那 40 多個是假警報

驗證 Node binary 真的有 export N-API 符號:

$ nm -D /opt/node-musl/bin/node | grep napi_call_threadsafe_function
0000000000d24590 T napi_call_threadsafe_function

Node binary 確實 export 了 N-API 符號(T 代表 exported)。

ldd 顯示 napi_* not found 的原因是:.node 檔案不是設計來直接執行的,ldd 的 NEEDED libraries 列表裡沒有 node binary,所以找不到 N-API 符號。真正執行時是 dlopen 從 node main process 動態解析,不會出問題。

根因分析

用一個比喻說明

想像 Linux 系統就像一個工具箱出租店,租客(程式)上門時可以借各種工具來完成工作。

不同 Linux 發行版的工具箱規格不同:

Ubuntu / Debian / RHEL 用「glibc 工具箱」—— 工具齊全、型號繁多、體積大
Alpine 用「musl 工具箱」—— 精簡輕量、只放最常用的工具

Gemini CLI 裡有一個關鍵零件叫 pty.node(讓它能控制終端機),這個零件原本是給 Ubuntu 的 glibc 工具箱用的,它預期能借到 42 種特定工具:

其中 40 種(N-API 工具)是「Gemini 自己帶來的」—— 不是跟工具箱借,所以沒問題 ✓
剩下 2 種(__asprintf_chk、fcntl64)只有 glibc 工具箱才有,Alpine 的 musl 工具箱沒放這兩個 ✗
連 Alpine 的「相容套件箱」(gcompat,號稱能模擬 glibc)也沒提供這兩個 ✗

結果:pty.node 載入到一半發現借不到工具,而 Gemini 對這個錯誤沒有處理好,整個程式直接當機(SIGSEGV)。

我們的修復就是自己做一個小工具盒(11 行 C code 的 shim),補上這兩個 musl 沒有的工具,讓 pty.node 能正常載入。

關鍵概念對照表

我用的詞	實際技術名詞	簡單解釋
工具箱	C 標準函式庫(libc)	Linux 系統最底層的函式庫,所有程式都會用到
glibc 工具箱	glibc(GNU C Library)	Ubuntu / Debian / RHEL 等主流發行版用的 libc,功能多
musl 工具箱	musl libc	Alpine 用的 libc,功能精簡、體積小
相容套件箱	gcompat	Alpine 提供的 glibc 相容層,但實作不完整
工具	動態連結符號(symbol)	程式執行時需要從 libc 借用的函式名稱
關鍵零件	native binding(`.node` 檔)	用 C++ 編譯的 Node 模組,直接跟系統打交道
自製小工具盒	LD_PRELOAD shim	在程式啟動前先載入,補上缺失的函式

為什麼 headless 模式不會 crash,互動模式才會?

因為只有互動模式才會打開終端機。

互動模式:Gemini 要給你聊天介面、要能執行 shell 指令、要能即時顯示輸出 → 必須載入 pty.node → 借不到工具 → 當機
Headless 模式(gemini -p "..."):純文字進、純文字出,不需要終端機 → 完全不載入 pty.node → 沒事

這也解釋了為什麼之前那麼難找原因:headless 跟互動只差一個小開關,但內部走的路徑天差地別。

那 N-API 那 40 個錯誤訊息是什麼?

那是 ldd 工具的「假警報」。

ldd 是設計來檢查「直接執行的程式」會借哪些工具,但 pty.node 不是直接執行,而是被 Node 用另一種機制(dlopen)動態載入。Node 載入時會把 N-API 那 40 個工具直接遞給 pty.node,所以實際上不會缺。

但 ldd 不知道有這層機制,看到 pty.node 沒明確標註「這 40 個工具會跟 Node 借」,就誤報成「缺 40 個符號」。

所以實際上只缺 2 個 glibc 符號,不是 42 個。這也是為什麼修復這麼簡單——只要補 2 個就好。

完整修復步驟

整個流程約 10 分鐘。

前置:確認你的環境符合條件

$ cat /etc/alpine-release
3.23.3

$ uname -m
x86_64

# 確認你的 Node 是 musl 編譯
$ ldd $(which node) | head -1
 /lib/ld-musl-x86_64.so.1 (...)

如果你不是 Alpine,或不是 musl Node,這篇修復可能不適用。

Step 1:換一個 Node.js binary(可選但推薦)

Alpine 的 apk add nodejs 是 Node 24,這個版本對某些 N-API 套件相容性差。換成 unofficial-builds 的 Node 22 LTS musl prebuild:

# 下載
NODE_VERSION=v22.11.0
cd /tmp
wget https://unofficial-builds.nodejs.org/download/release/${NODE_VERSION}/node-${NODE_VERSION}-linux-x64-musl.tar.xz

# 解壓到 /opt
sudo mkdir -p /opt/node-musl
sudo tar -xJf node-${NODE_VERSION}-linux-x64-musl.tar.xz -C /opt/node-musl --strip-components=1

# 確認 libstdc++ 已裝(unofficial musl Node 需要這個)
sudo apk add libstdc++

# 切到新 Node
export PATH=/opt/node-musl/bin:$PATH

# 永久化
echo 'export PATH=/opt/node-musl/bin:$PATH' >> ~/.bashrc

驗證:

$ which node
/opt/node-musl/bin/node

$ node --version
v22.11.0

$ node -e "console.log('N-API:', process.versions.napi)"
N-API: 9

Step 2:用新 Node 安裝 Gemini CLI

/opt/node-musl/bin/npm install -g @google/gemini-cli

預期輸出:

added 86 packages in 21s

Step 3:確認 pty.node 缺哪些符號

ldd /opt/node-musl/lib/node_modules/@google/gemini-cli/node_modules/@lydell/node-pty-linux-x64/pty.node 2>&1 \
 | grep "symbol not found" \
 | grep -v napi_

預期輸出(只有兩個):

Error relocating .../pty.node: __asprintf_chk: symbol not found
Error relocating .../pty.node: fcntl64: symbol not found

如果你看到的不只這兩個,代表你的環境跟我不同,後續 shim 可能要再加幾個函式。

Step 4:安裝 build toolchain

sudo apk add build-base

預期看到:

(1/3) Installing fortify-headers (...)
(2/3) Installing patch (...)
(3/3) Installing build-base (...)

Step 5:撰寫並編譯 LD_PRELOAD shim

建立 shim 目錄:

sudo mkdir -p /opt/glibc-shim

寫 shim 程式:

sudo tee /opt/glibc-shim/shim.c > /dev/null <<'EOF'
#define _GNU_SOURCE
#include <stdio.h>
#include <stdarg.h>
#include <stdlib.h>
#include <fcntl.h>

/*
 * __asprintf_chk: glibc _FORTIFY_SOURCE 提供的 hardened asprintf
 * musl 沒有對應實作,直接 forward 到 vasprintf
 * (功能等價,只是不做 buffer overflow check,對 PTY 操作沒影響)
 */
int __asprintf_chk(char **strp, int flag, const char *fmt, ...) {
 va_list ap;
 int ret;
 va_start(ap, fmt);
 ret = vasprintf(strp, fmt, ap);
 va_end(ap);
 return ret;
}

/*
 * fcntl64: glibc 32-bit 系統用的 64-bit file offset 版 fcntl
 * x86_64 上 fcntl 行為等同 fcntl64,musl 只提供 fcntl
 */
int fcntl64(int fd, int cmd, ...) {
 va_list ap;
 void *arg;
 va_start(ap, cmd);
 arg = va_arg(ap, void *);
 va_end(ap);
 return fcntl(fd, cmd, arg);
}
EOF

編譯:

sudo gcc -shared -fPIC -O2 \
 -o /opt/glibc-shim/libglibc-shim.so \
 /opt/glibc-shim/shim.c

驗證 shim 提供了正確符號:

$ nm -D /opt/glibc-shim/libglibc-shim.so | grep -E "asprintf_chk|fcntl64"
0000000000001160 T __asprintf_chk
0000000000001210 T fcntl64

驗證 LD_PRELOAD 後 pty.node 不再缺符號:

$ LD_PRELOAD=/opt/glibc-shim/libglibc-shim.so \
 ldd /opt/node-musl/lib/node_modules/@google/gemini-cli/node_modules/@lydell/node-pty-linux-x64/pty.node 2>&1 \
 | grep "symbol not found" | grep -v napi_
# (空白,代表所有非 napi 符號都解決了)

Step 6:用 wrapper script 永久化 LD_PRELOAD

不要每次都手打 LD_PRELOAD=...。把原本的 gemini symlink 換成一個 wrapper:

# 備份原本的 symlink
sudo mv /opt/node-musl/bin/gemini /opt/node-musl/bin/gemini.real

# 寫 wrapper
sudo tee /opt/node-musl/bin/gemini > /dev/null <<'EOF'
#!/bin/sh
# Gemini CLI launcher with glibc shim for Alpine/musl
# Required because @lydell/node-pty-linux-x64/pty.node references
# glibc-only symbols (__asprintf_chk, fcntl64) that musl/gcompat lacks.
export LD_PRELOAD=/opt/glibc-shim/libglibc-shim.so
exec /opt/node-musl/bin/node \
 /opt/node-musl/lib/node_modules/@google/gemini-cli/bundle/gemini.js "$@"
EOF
sudo chmod +x /opt/node-musl/bin/gemini

Step 7:驗證修復

gemini --version

進互動模式測試:

gemini

進 Gemini CLI 後,輸入會觸發 shell 的 prompt:

請執行 shell 指令: ls

預期看到 Gemini 真的執行 ls 並回傳結果,而不是 thinking 後 crash 退出。

結果驗證範例

實際執行 Gemini 互動模式的成功輸出:

> 請執行 shell 指令: openspec new change test-with-shim
Creating New OpenSpec Change: Executing the requested openspec command.
✓ Shell openspec new change test-with-shim
✔ Created change 'test-with-shim' at openspec/changes/test-with-shim/
✓ ReadFolder openspec/changes/test-with-shim/ → Found 1 item(s).
✓ ReadFile openspec/.../.openspec.yaml
✓ Shell which openspec
/opt/node-musl/bin/openspec
✦ 已成功執行指令 openspec new change test-with-shim。

已知限制

Headless 模式仍有問題

gemini -p "..." 在 headless 模式下,即使套用此 shim,仍會看到:

Error executing tool run_shell_command: Tool "run_shell_command" not found.

這是不同問題,跟 musl/segfault 無關。Gemini CLI 在 headless 模式刻意限制工具白名單(見 Gemini CLI Issue #5382)。

workaround:用互動模式即可,本修復解決的就是互動模式問題。

Node 版本選擇

本文用 Node 22.11.0。理論上 Node 20.x 也可以(都有 unofficial musl prebuild)。Node 24 沒實測過,如果你想用 Node 24,記得驗證 N-API 9+ 支援。

Gemini CLI 升級後可能要重做

每次 npm install -g @google/gemini-cli@latest 後,如果 Gemini 換了 PTY 的相依套件,可能需要重新檢查缺失符號清單(回到 Step 3),補進 shim.c 重編。

參考資料

致謝

整個除錯過程靠 strace、core dump、ldd、readelf、nm 一步步收斂問題範圍,從「Gemini 莫名 crash」收斂到「2 個 glibc 符號缺失」。最終解法只有 11 行 C code,但沒有前面的系統性除錯,做不出來。

工程除錯的價值不在解法本身,而在「定位問題的能力」。

驗證 kubelet `serializeImagePulls` 行為差異

Wed, 29 Apr 2026 08:17:38 +0800

透過實際部署多個 Pod,觀察 kubelet 在 serializeImagePulls=true 與 false 兩種設定下的 image 拉取行為差異。

背景知識

兩個層級的序列化

Kubernetes 的 image pull 序列化行為其實有兩個層級:

跨 Pod 層級:由 serializeImagePulls 控制,決定不同 Pod 之間的 image 拉取是序列還是平行
Pod 內部層級:kubelet 永遠會逐一處理同一個 Pod 內的 container,這個行為不受 serializeImagePulls 影響

⚠️ 重要:測試時若用「單一 Pod 多 container」,無論 serializeImagePulls 設成什麼,都會看到序列行為。必須用「多 Pod 同時部署」才能觀察到差異。

參數版本支援

Kubernetes 1.27+:maxParallelImagePulls 為 Alpha
Kubernetes 1.28+:升為 Beta
Kubernetes 1.32+:加入 e2e 測試

前置準備

1. 選定測試用的 worker node

kubectl get nodes

本次測試使用節點:tk8s-worker2

2. 備份 kubelet 設定檔

SSH 到目標 worker node:

sudo cp /var/lib/kubelet/config.yaml /var/lib/kubelet/config.yaml.bak

3. 準備測試用 YAML

建立檔案 multi-pod-test.yaml:

apiVersion: v1
kind: Pod
metadata:
 name: pull-test-1
spec:
 nodeName: tk8s-worker2
 containers:
 - name: c
 image: nginx:1.25
 imagePullPolicy: Always
 command: ["sleep", "3600"]
---
apiVersion: v1
kind: Pod
metadata:
 name: pull-test-2
spec:
 nodeName: tk8s-worker2
 containers:
 - name: c
 image: redis:7.2
 imagePullPolicy: Always
 command: ["sleep", "3600"]
---
apiVersion: v1
kind: Pod
metadata:
 name: pull-test-3
spec:
 nodeName: tk8s-worker2
 containers:
 - name: c
 image: mysql:8.0
 imagePullPolicy: Always
 command: ["sleep", "3600"]
---
apiVersion: v1
kind: Pod
metadata:
 name: pull-test-4
spec:
 nodeName: tk8s-worker2
 containers:
 - name: c
 image: postgres:16
 imagePullPolicy: Always
 command: ["sleep", "3600"]

第一階段:測試 `serializeImagePulls=false`(平行拉取)

步驟 1:修改 kubelet 設定為 false

在 worker node 上編輯設定檔:

sudo vi /var/lib/kubelet/config.yaml

加入或修改以下欄位:

serializeImagePulls: false
maxParallelImagePulls: 5

步驟 2:重啟 kubelet

sudo systemctl restart kubelet
sudo systemctl status kubelet

確認狀態為 active (running)。

步驟 3:驗證設定生效

kubectl get --raw "/api/v1/nodes/tk8s-worker2/proxy/configz" \
 | jq '.kubeletconfig | {serializeImagePulls, maxParallelImagePulls}'

預期輸出:

{
 "serializeImagePulls": false,
 "maxParallelImagePulls": 5
}

步驟 4:清除節點上的舊 image

在 worker node 上執行:

sudo crictl rmi nginx:1.25 redis:7.2 mysql:8.0 postgres:16

步驟 5:開啟 events 監看視窗

另開一個 terminal:

kubectl get events --watch

步驟 6:部署 Pod 進行測試

kubectl apply -f multi-pod-test.yaml

步驟 7:實際執行結果

0s Normal Pulling pod/pull-test-1 Pulling image "nginx:1.25"
0s Normal Pulling pod/pull-test-2 Pulling image "redis:7.2"
0s Normal Pulling pod/pull-test-3 Pulling image "mysql:8.0"
0s Normal Pulling pod/pull-test-4 Pulling image "postgres:16"
0s Normal Pulled pod/pull-test-2 Successfully pulled image "redis:7.2" in 3.559s (3.559s including waiting). Image size: 44645040 bytes.
0s Normal Created pod/pull-test-2 Container created
0s Normal Started pod/pull-test-2 Container started
0s Normal Pulled pod/pull-test-3 Successfully pulled image "mysql:8.0" in 3.792s (3.792s including waiting). Image size: 233592821 bytes.
0s Normal Created pod/pull-test-3 Container created
0s Normal Started pod/pull-test-3 Container started
0s Normal Pulled pod/pull-test-4 Successfully pulled image "postgres:16" in 4.077s (4.077s including waiting). Image size: 160157788 bytes.
0s Normal Created pod/pull-test-4 Container created
0s Normal Started pod/pull-test-4 Container started
0s Normal Pulled pod/pull-test-1 Successfully pulled image "nginx:1.25" in 5.568s (5.568s including waiting). Image size: 71005258 bytes.
0s Normal Created pod/pull-test-1 Container created
0s Normal Started pod/pull-test-1 Container started

步驟 8:結果判讀(平行拉取的證據)

Image	pull time	including waiting	等待時間
redis:7.2	3.559s	3.559s	0s ✅
mysql:8.0	3.792s	3.792s	0s ✅
postgres:16	4.077s	4.077s	0s ✅
nginx:1.25	5.568s	5.568s	0s ✅

判讀重點:

✅ 四個 Pulling 事件同時發生(時間戳同為 0s)
✅ 每個 image 的 pull time = including waiting,代表沒有任何排隊等待
✅ 完成順序與啟動順序不同(redis 第一個拉完,但 nginx 第一個啟動)
✅ 總時間 ≈ 最慢 image 的時間(~5.5 秒)

步驟 9:清理測試環境

kubectl delete -f multi-pod-test.yaml

第二階段:測試 `serializeImagePulls=true`(序列拉取)

步驟 10:修改 kubelet 設定為 true

SSH 到 worker node,編輯設定檔:

sudo vi /var/lib/kubelet/config.yaml

修改為:

serializeImagePulls: true

⚠️ 注意:設為 true 時必須移除或註解 maxParallelImagePulls 那一行,否則 kubelet 會啟動失敗。

步驟 11:重啟 kubelet

sudo systemctl restart kubelet
sudo systemctl status kubelet

步驟 12:驗證設定生效

kubectl get --raw "/api/v1/nodes/tk8s-worker2/proxy/configz" \
 | jq '.kubeletconfig.serializeImagePulls'

預期輸出:

true

步驟 13:清除節點上的 image

在 worker node 上執行:

sudo crictl rmi nginx:1.25 redis:7.2 mysql:8.0 postgres:16

步驟 14:重新部署 Pod 並監看 events

kubectl get events --watch

另開 terminal:

kubectl apply -f multi-pod-test.yaml

步驟 15:實際執行結果

0s Normal Pulling pod/pull-test-3 Pulling image "mysql:8.0"
0s Normal Pulling pod/pull-test-1 Pulling image "nginx:1.25"
0s Normal Pulling pod/pull-test-2 Pulling image "redis:7.2"
0s Normal Pulling pod/pull-test-4 Pulling image "postgres:16"
0s Normal Pulled pod/pull-test-3 Successfully pulled image "mysql:8.0" in 3.858s (3.858s including waiting). Image size: 233592821 bytes.
0s Normal Created pod/pull-test-3 Container created
0s Normal Started pod/pull-test-3 Container started
0s Normal Pulled pod/pull-test-1 Successfully pulled image "nginx:1.25" in 4.783s (8.629s including waiting). Image size: 71005258 bytes.
0s Normal Created pod/pull-test-1 Container created
0s Normal Started pod/pull-test-1 Container started
0s Normal Pulled pod/pull-test-2 Successfully pulled image "redis:7.2" in 3.565s (12.188s including waiting). Image size: 44645040 bytes.
0s Normal Created pod/pull-test-2 Container created
0s Normal Started pod/pull-test-2 Container started
0s Normal Pulled pod/pull-test-4 Successfully pulled image "postgres:16" in 3.585s (15.751s including waiting). Image size: 160157788 bytes.
0s Normal Created pod/pull-test-4 Container created
0s Normal Started pod/pull-test-4 Container started

步驟 16:結果判讀(序列拉取的證據)

順序	Image	pull time	including waiting	等待時間
1	mysql:8.0	3.858s	3.858s	0s
2	nginx:1.25	4.783s	8.629s	3.846s ⏳
3	redis:7.2	3.565s	12.188s	8.623s ⏳
4	postgres:16	3.585s	15.751s	12.166s ⏳

判讀重點:

⚠️ 雖然四個 Pulling 事件看起來也是同一秒(這是事件精度只到秒的觀察陷阱),但底層只有一個真的在下載
✅ including waiting 時間遞增(0s → 3.8s → 8.6s → 12.2s),代表後面的 image 都在排隊
✅ 等待時間 ≈ 前面所有 image 的 pull time 累加
✅ 總時間 ≈ 所有 image 拉取時間總和(~15.7 秒)

步驟 17:清理測試環境

kubectl delete -f multi-pod-test.yaml

第三階段:對照分析

兩種模式並列比較

觀察項目	`serializeImagePulls=false`	`serializeImagePulls=true`
各 image 等待時間	0s, 0s, 0s, 0s	0s, 3.8s, 8.6s, 12.2s
`pull time` vs `including waiting`	兩者相同	`including waiting` 大於 `pull time`
完成順序	取決於 image 大小與網速	接近啟動順序
最後一個完成時間	~5.5 秒	~15.7 秒
總耗時特徵	≈ 最慢 image 時間	≈ 所有 image 時間總和
效能差異	基準	慢約 2.85 倍

視覺化對照

serializeImagePulls=false(平行):

時間軸: 0s ─────────── 5.5s
mysql [████████] ← 同時下載
nginx [██████████]
redis [████████]
postgres [██████████]

serializeImagePulls=true(序列):

時間軸: 0s ─────────────────────── 15.7s
mysql [████] ← 先下載
nginx [█████] ← 等 mysql 完
redis [████] ← 再等
postgres [████] ← 最後

🎯 最關鍵的單一判斷依據

看 Pulled 事件訊息中的 including waiting 數字:

in X (X including waiting) → 平行拉取(沒排隊)
in X (Y including waiting) 且 Y > X → 序列拉取(有排隊)

這個欄位就是 Kubernetes 為了幫使用者判斷序列化行為而特別設計的觀察點。

還原步驟

步驟 18:還原 kubelet 設定

sudo cp /var/lib/kubelet/config.yaml.bak /var/lib/kubelet/config.yaml
sudo systemctl restart kubelet
sudo systemctl status kubelet

步驟 19:確認還原成功

kubectl get --raw "/api/v1/nodes/tk8s-worker2/proxy/configz" \
 | jq '.kubeletconfig.serializeImagePulls'

注意事項

1. 測試節點選擇

選一台非生產關鍵的 worker node。重啟 kubelet 期間該節點上的 Pod 會短暫斷線。

2. kubeadm 叢集警告

本機修改的 /var/lib/kubelet/config.yaml 在執行 kubeadm upgrade 時可能會被覆蓋。正式長期套用建議改 kube-system 命名空間下的 kubelet-config ConfigMap(但會影響全部節點)。

3. Image 必須不存在於節點

每次測試前都要 crictl rmi,否則 kubelet 會跳過 pull 階段直接顯示 Container image already present,觀察不到差異。

4. `maxParallelImagePulls` 限制規則

需要 Kubernetes 1.27+ 才支援
設為 ≥ 2 時,必須搭配 serializeImagePulls: false
若 serializeImagePulls: true,則 maxParallelImagePulls 必須設為 1 或不設定
違反規則 kubelet 會啟動失敗

5. Pod 內 container 不受影響

kubelet 永遠逐一處理同一個 Pod 內的多個 container 的 image 拉取,這是固定設計,與 serializeImagePulls 設定無關。所以驗證時務必使用「多 Pod 同時部署」的方式。

參考資料

Kubernetes kube-controller-manager 設定參數深度解析

Thu, 23 Apr 2026 13:43:54 +0800

從 node-cidr-mask-size 與 terminated-pod-gc-threshold 出發,了解 PodGC Controller 的運作原理,並透過 Kind 本機環境實作驗證。

文件資訊

項目	內容
文件主題	kube-controller-manager `extraArgs` 參數解析與 PodGC 實作驗證
建立日期	2026-04-23
適用版本	Kubernetes(以 master 分支原始碼為準)
驗證環境	Kind 本機叢集
主要參考	kubernetes/pkg/controller/podgc

一、背景:設定檔的用途

本文件所討論的設定檔片段:

controllerManager:
 extraArgs:
 - name: node-cidr-mask-size  # set pod cidr per node
 value: "25"
 # Garbage Collection
 # Max number of terminated pods to keep before cleaning up
 - name: terminated-pod-gc-threshold
 value: "500"

這是 Kubernetes kubeadm ClusterConfiguration 中,用來傳遞額外參數給 kube-controller-manager 的設定片段。extraArgs 裡面的每一項,最終會被轉換成 kube-controller-manager 啟動時的命令列參數(例如 --node-cidr-mask-size=25)。

kube-controller-manager 是 Kubernetes 控制平面的核心元件之一,內部包含了許多 controller(如 Node Controller、Replication Controller、Garbage Collector 等),負責維持叢集的「期望狀態」。

二、參數解析

2.1 `node-cidr-mask-size: "25"`

字面意義

設定「每個 Node 分配到的 Pod CIDR 子網路遮罩大小」為 /25。

運作原理

當您在叢集建立時設定了整個叢集的 Pod 網段(--cluster-cidr,例如 10.244.0.0/16),kube-controller-manager 會從這個大網段中,切出一小塊子網段分配給每個加入叢集的 Node,這塊子網段就是該 Node 上所有 Pod 的 IP 來源。

node-cidr-mask-size=25 代表每個 Node 會拿到一個 /25 的子網段。

實際影響(以 `/25` 為例)

每個 Node 可分配的 IP 數量:2^(32-25) = 128 個 IP
扣除網路位址、廣播位址等保留 IP,每個 Node 實際可跑約 126 個 Pod
若叢集的 cluster-cidr 是 /16(共 65,536 個 IP),理論上可切出 2^(25-16) = 512 個 Node 的配額

與預設值的差異

Kubernetes 預設值是 /24(每個 Node 可跑約 254 個 Pod)。設成 /25 代表:

✅ 節省 IP 位址:在有限的 cluster-cidr 下可容納更多 Node
⚠️ 限制單一 Node 的 Pod 密度:每個 Node 最多只能跑約 126 個 Pod(仍高於 kubelet 預設的 max-pods=110,所以實務上通常夠用)

什麼情境會這樣設定?

Pod IP 網段資源有限(例如 VPC 內可用的 CIDR 不大)
叢集 Node 數量多、但每個 Node 的 Pod 密度不高
希望在有限網段內擴充 Node 規模

2.2 `terminated-pod-gc-threshold: "500"`

字面意義

當叢集中「已終止(terminated)狀態的 Pod」數量超過 500 個時,Garbage Collector 會開始自動清理這些 Pod。

運作原理

當 Pod 執行完畢(Succeeded 或 Failed),它們不會立刻從 etcd 中刪除,而是會保留下來供使用者查詢記錄(例如 kubectl get pods 時看到 Completed 狀態的 Pod)。這些 Pod 雖然不再消耗運算資源,但仍會佔用:

etcd 儲存空間
API Server 的查詢效能

這個參數控制「保留多少個已終止 Pod 才開始清理」。

實際影響(設為 500)

當已終止 Pod 數量 ≤ 500:不會觸發清理,全部保留
當已終止 Pod 數量 > 500:從最舊的開始刪除,直到數量回到 500 以下

與預設值的差異

Kubernetes 預設值是 12500,設成 500 代表:

✅ 更積極地清理,減輕 etcd 負擔、加快 API Server 回應速度
✅ 適合有大量 Job / CronJob 產生短命 Pod 的叢集
⚠️ 可保留的歷史記錄變少,若需要排查較早的失敗 Pod 可能已被刪除(建議搭配 Log 收集系統,如 Loki、ELK)

什麼情境會這樣設定?

叢集會跑大量 Batch Job / CronJob
etcd 效能是瓶頸、或想降低 etcd 儲存壓力
已有完善的 log / event 外部保存機制,不需依賴 API Server 保留 Pod 記錄

2.3 兩個參數的整體設計意圖

關注點	對應參數	設計思路
IP 資源效率	`node-cidr-mask-size=25`	用比較小的 Pod CIDR 讓叢集能容納更多 Node
控制平面效能	`terminated-pod-gc-threshold=500`	積極清理終止 Pod,減輕 etcd / API Server 壓力

兩者都指向同一個方向:這是一個偏向中大型、但希望控制資源使用效率的叢集。

2.4 設定時的注意事項

node-cidr-mask-size 必須與 cluster-cidr、kubelet --max-pods 三者一起通盤考量,避免出現 Node 配額超過 IP 可用量,或 Pod 配額超過網段容量的狀況。
terminated-pod-gc-threshold 不能設太低(例如幾十個),否則剛跑完的 Job 馬上被清掉,會讓 debug 非常困難。500 是一個相對平衡的數字。
修改 controllerManager.extraArgs 後,需要重啟 kube-controller-manager Pod 才會生效(若是 kubeadm 叢集,修改 /etc/kubernetes/manifests/kube-controller-manager.yaml 會自動重啟)。

三、原理:PodGC Controller 如何認定「terminated Pod」

3.1 原始碼位置

Kubernetes 的 PodGC Controller 位於:

kubernetes/pkg/controller/podgc/gc_controller.go

3.2 原始碼層面的 terminated 定義

根據 Kubernetes 官方 pkg/controller/podgc 套件的 doc.go 描述:

PodGCController… If the number of pods in terminated phases (right now either Failed or Succeeded) surpasses a configurable threshold, the controller will delete pods in terminated state until the system reaches the allowed threshold again. The PodGCController prioritizes pods to delete by sorting by creation timestamp and deleting the oldest objects first.

這段話給了我們三個關鍵定義:

判定依據	說明
1. Pod 的 `status.phase`	必須是 `Failed` 或 `Succeeded`
2. 判斷時機	當 terminated Pod 總數 > threshold 才觸發清理
3. 刪除順序	依照 `creationTimestamp` 排序,最舊的先刪

在 gc_controller.go 中也能看到這個判定邏輯的核心程式碼片段:

if phase := pod.Status.Phase; phase != v1.PodPending &&
 phase != v1.PodRunning &&
 phase != v1.PodUnknown {
 // 這個 Pod 屬於 terminated,納入 GC 候選名單
}

這段程式碼使用反向列舉的方式定義 terminated:只要不是 Pending / Running / Unknown,就是 terminated。在 Kubernetes 的 Pod phase 定義中,剩下的就是 Succeeded 和 Failed 兩種。

3.3 用 kubectl 判斷 Pod 是否為 terminated

對應到 kubectl,可以用 status.phase 做 field selector 過濾:

# 查詢所有 Succeeded 的 Pod
kubectl get pods --all-namespaces --field-selector=status.phase=Succeeded

# 查詢所有 Failed 的 Pod
kubectl get pods --all-namespaces --field-selector=status.phase=Failed

# 同時查詢兩者(field-selector 不支援 OR,需要用 jq 輔助)
kubectl get pods --all-namespaces -o json | \
 jq '.items[] | select(.status.phase=="Succeeded" or .status.phase=="Failed") | .metadata.name'

# 快速統計 terminated Pod 數量
kubectl get pods --all-namespaces -o json | \
 jq '[.items[] | select(.status.phase=="Succeeded" or .status.phase=="Failed")] | length'

⚠️ 常見誤解澄清 kubectl get pods 看到的 Completed 不是 phase 值,而是 STATUS 欄位的顯示字串。真正的 phase 是 Succeeded。同理 Error 對應的是 Failed。驗證時一定要用 status.phase 當條件,不要用 STATUS 欄位的字串。

3.4 值得注意的原始碼細節

細節 1:GC 只會把超出的部分刪掉,不會歸零

根據 GitHub Issue #71421 的討論,PodGC 的設計行為是:

The current behavior seems to allow the terminated Pod amount fluctuate above and under the threshold, instead of clean up completely when threshold is met.

實例:假設 threshold = 500,當 terminated Pod 達到 600 時,GC 會刪掉 100 個(600 - 500),讓數量回到 500,而不是全部清光。這個設計是刻意的。

細節 2:threshold ≤ 0 代表停用 GC

when set terminated-pod-gc-threshold <= 0, the terminated pod garbage collector is disabled.

細節 3:GC 檢查週期

原始碼中有個常數 gcCheckPeriod,預設是 20 秒。也就是 PodGC Controller 每 20 秒會檢查一次是否需要清理。

四、驗證實驗:用 Kind 驗證 `terminated-pod-gc-threshold`

4.1 實驗設計

項目	設定值	設計目的
叢集	Kind 本機叢集	快速建置、可改 controller-manager 參數
threshold	500(接近真實情境)	驗證實際設定檔的值
Job 數量	600 個(超過 threshold 100 個)	驗證超量時的清理行為
觀察點 1	Job 全部完成瞬間的 terminated Pod 數量	應該是 600
觀察點 2	GC 週期後(等 30~60 秒)	應該被砍到 500 左右
觀察點 3	被保留的 Pod creationTimestamp	應該是較新的 500 個(舊的被刪)

4.2 完整實驗步驟

Step 1: 建立 Kind 叢集並掛入自訂的 controller-manager 參數

建立 kind-config.yaml:

kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
name: podgc-test
nodes:
 - role: control-plane
 kubeadmConfigPatches:
 - |
 kind: ClusterConfiguration
 controllerManager:
 extraArgs:
 terminated-pod-gc-threshold: "500"
 - role: worker
 - role: worker

建立叢集:

kind create cluster --config kind-config.yaml

Step 2: 驗證參數有正確套用到 kube-controller-manager

# 進入 control-plane 容器查看 manifest
docker exec podgc-test-control-plane \
 cat /etc/kubernetes/manifests/kube-controller-manager.yaml \
 | grep terminated-pod-gc-threshold

# 應該看到: --terminated-pod-gc-threshold=500

另一個驗證方式是看 controller-manager Pod 的 command:

kubectl -n kube-system get pod -l component=kube-controller-manager \
 -o jsonpath='{.items[0].spec.containers[0].command}' | tr ',' '\n' | grep terminated

Step 3: 建立 600 個會立即完成的 Job

準備腳本 create-jobs.sh:

#!/bin/bash
set -e

NAMESPACE="podgc-test"
kubectl create namespace $NAMESPACE --dry-run=client -o yaml | kubectl apply -f -

for i in $(seq 1 600); do
 cat <<EOF | kubectl apply -f - >/dev/null
apiVersion: batch/v1
kind: Job
metadata:
 name: quickjob-$(printf "%03d" $i)
 namespace: $NAMESPACE
spec:
 ttlSecondsAfterFinished: 99999 # 避免 Job controller 自己先清掉 Pod,干擾實驗
 backoffLimit: 0
 template:
 spec:
 restartPolicy: Never
 containers:
 - name: c
 image: busybox:1.36
 command: ["sh", "-c", "echo done"]
EOF
 # 每 50 個稍微喘一下,避免 API Server 過載
 if (( i % 50 == 0 )); then
 echo "Created $i jobs..."
 sleep 2
 fi
done

echo "All 600 jobs submitted."

⚠️ 關鍵設計:ttlSecondsAfterFinished 設得很大,是為了排除 Job Controller 的 TTL 機制(那是另一個清理機制),確保清理行為只由 PodGC 觸發,這樣實驗才乾淨。

執行:

chmod +x create-jobs.sh
./create-jobs.sh

Step 4: 持續觀察 terminated Pod 數量變化

開啟另一個終端機,跑一個監控腳本 watch-gc.sh:

#!/bin/bash
NAMESPACE="podgc-test"

while true; do
 TS=$(date '+%H:%M:%S')
 TOTAL=$(kubectl get pods -n $NAMESPACE -o json 2>/dev/null | \
 jq '[.items[] | select(.status.phase=="Succeeded" or .status.phase=="Failed")] | length')
 RUNNING=$(kubectl get pods -n $NAMESPACE -o json 2>/dev/null | \
 jq '[.items[] | select(.status.phase=="Running" or .status.phase=="Pending")] | length')
 echo "[$TS] terminated=$TOTAL active=$RUNNING"
 sleep 5
done

執行:

chmod +x watch-gc.sh
./watch-gc.sh

Step 5: 預期觀察結果

您會看到類似以下的輸出序列:

[14:30:05] terminated=0 active=120 # Job 開始跑
[14:30:10] terminated=45 active=200
[14:30:20] terminated=180 active=300
[14:30:30] terminated=420 active=180
[14:30:40] terminated=590 active=10 # 接近高峰
[14:30:45] terminated=600 active=0 # 全部完成
[14:30:50] terminated=600 active=0
[14:30:55] terminated=600 active=0
[14:31:05] terminated=500 active=0 # ← GC 觸發!砍掉 100 個
[14:31:10] terminated=500 active=0 # 穩定在 threshold

驗證點:

✅ 高峰值達到 600 → 證明 Pod 確實累積
✅ GC 觸發後剩 500(而非 0) → 驗證「只砍超出部分」的設計
✅ GC 觸發延遲 15~20 秒 → 對應原始碼中的 gcCheckPeriod = 20s

Step 6: 驗證「刪除順序是從最舊開始」

# 看留下來的 Pod 中,最早的 creationTimestamp 是什麼時候
kubectl get pods -n podgc-test \
 --field-selector=status.phase=Succeeded \
 --sort-by=.metadata.creationTimestamp \
 -o custom-columns=NAME:.metadata.name,CREATED:.metadata.creationTimestamp \
 | head -5

# 對照實驗:最早的 100 個 Pod(quickjob-001 ~ quickjob-100)應該都不見了
kubectl get pod quickjob-001 -n podgc-test 2>&1 | grep -i "not found"
kubectl get pod quickjob-600 -n podgc-test # 應該還在

如果 quickjob-001 找不到、quickjob-600 還在,就印證了原始碼中的排序刪除邏輯:最舊的優先刪除。

Step 7: 查看 controller-manager 的 log 做最後驗證

kubectl -n kube-system logs -l component=kube-controller-manager \
 --tail=200 | grep -i "podgc\|garbage"

會看到類似:

I0423 14:31:05.123456 podgc_controller.go:xxx] "PodGC is force deleting Pod" pod="podgc-test/quickjob-001"
I0423 14:31:05.234567 podgc_controller.go:xxx] "PodGC is force deleting Pod" pod="podgc-test/quickjob-002"
...

這直接證明 PodGC Controller 確實在依照您設定的 threshold 工作。

4.3 實驗清理

kind delete cluster --name podgc-test

五、整體驗證流程總結

原始碼層面定義 terminated
└─ status.phase ∈ {Succeeded, Failed}
│
▼
kubectl 指令層面驗證
└─ --field-selector=status.phase=Succeeded/Failed
│
▼
實驗層面驗證(Kind + 600 Jobs + threshold=500)
├─ 驗證點 1: 達到 600 → 證明 Pod 有累積
├─ 驗證點 2: 砍到剩 500 → 證明 threshold 精準生效
├─ 驗證點 3: 留下的是新的 → 證明 oldest-first 排序
└─ 驗證點 4: controller-manager log 有 GC 紀錄 → 直接證據

六、參考資料

類型	連結
PodGC 原始碼	https://github.com/kubernetes/kubernetes/blob/master/pkg/controller/podgc/gc_controller.go
PodGC 套件說明	https://github.com/kubernetes/kubernetes/blob/master/pkg/controller/podgc/doc.go
PodGC 行為討論 Issue	https://github.com/kubernetes/kubernetes/issues/71421
Enhancement Proposal	https://github.com/kubernetes/enhancements/issues/2890
Pod Lifecycle 官方文件	https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle/
kubeadm ClusterConfiguration	https://kubernetes.io/docs/reference/config-api/kubeadm-config.v1beta4/
Kind 官方文件	https://kind.sigs.k8s.io/

本文件由 Claude 整理自對話紀錄,供學習與參考使用。

Cilium Gateway API

Mon, 20 Apr 2026 02:44:58 +0800

適用環境： RKE2 bare-metal / VM + 外部 F5 / Nginx L4 LB Envoy 模式： Standalone DaemonSet（Cilium 1.16+ 預設） 目標： 讓 Cilium Gateway API 透過 hostNetwork 直接在 worker node 上監聽 80/443，由外部 LB 分流

架構總覽

流量路徑說明：

外部 Client 發出請求
F5 / Nginx (L4 LB) 將流量分發到 3 台標記為 role=gateway 的 worker node IP
每台 worker node 上的 Cilium Envoy 以 hostNetwork 模式監聽 80/443
Cilium 的 eBPF 透過 TPROXY 機制將封包透明轉發給 Envoy
Gateway API 的 HTTPRoute 根據 host / path 規則路由到對應的後端 K8s Service

前置條件

Cilium 版本 >= 1.16（hostNetwork 模式自 1.16 起支援）
Gateway API CRDs 已安裝
kubeProxyReplacement 已啟用
至少 3 台 worker node 可供對外使用

Step 0：事前確認與備份

確認 Cilium 版本：

cilium version
helm list -n kube-system | grep cilium

匯出目前的 Helm values 備份（重要，萬一需要 rollback）：

helm get values cilium -n kube-system -o yaml > cilium-backup-values.yaml

Step 1：為 Worker Node 打上 Label

選擇要對外的 3 台 worker node，為它們打上 role=gateway label：

kubectl label node <worker-node-1> role=gateway
kubectl label node <worker-node-2> role=gateway
kubectl label node <worker-node-3> role=gateway

驗證 label 是否正確：

kubectl get nodes -l role=gateway

預期輸出：

NAME STATUS ROLES AGE VERSION
worker-node-1 Ready <none> 30d v1.xx.x
worker-node-2 Ready <none> 30d v1.xx.x
worker-node-3 Ready <none> 30d v1.xx.x

Step 2：準備 Helm Values 檔案

建立 cilium-gateway-hostnetwork-values.yaml：

# ── Gateway API 設定 ──────────────────────────────────────────
gatewayAPI:
 enabled: true
 hostNetwork:
 enabled: true
 # 只在有 role=gateway label 的 node 上暴露 listener
 # 如果要所有 node 都暴露，移除 nodes 區塊即可
 nodes:
 matchLabels:
 role: gateway

# ── Envoy (Standalone DaemonSet 模式) ────────────────────────
envoy:
 enabled: true
 securityContext:
 capabilities:
 # 允許 Envoy bind 80/443 等 privileged port
 keepCapNetBindService: true
 envoy:
 - NET_ADMIN
 - PERFMON
 - BPF
 - NET_BIND_SERVICE

# ── 基礎設定（通常已在現有 values 中，僅供確認）──────────────
kubeProxyReplacement: true

重點說明：

gatewayAPI.hostNetwork.enabled: true：啟用後會自動停用 LoadBalancer type Service，兩者互斥（Cilium 不再為 Gateway 建立 LoadBalancer type Service，改為直接在 host network 上監聽。）
gatewayAPI.hostNetwork.nodes.matchLabels：控制只在指定 node 上暴露 listener
NET_BIND_SERVICE capability：允許 Envoy bind 80/443 等 1024 以下的 privileged port

Step 3：執行 Helm Upgrade

helm upgrade cilium cilium/cilium \
 --namespace kube-system \
 --reuse-values \
 -f cilium-gateway-hostnetwork-values.yaml

注意： --reuse-values 會保留現有的所有設定，只覆蓋 values 檔案中指定的項目。

Step 4：重啟 Cilium 元件

Helm upgrade 後需重啟相關元件使設定生效：

kubectl -n kube-system rollout restart deployment/cilium-operator
kubectl -n kube-system rollout restart daemonset/cilium
kubectl -n kube-system rollout restart daemonset/cilium-envoy

等待所有 Pod 就緒：

kubectl -n kube-system rollout status deployment/cilium-operator --timeout=120s
kubectl -n kube-system rollout status daemonset/cilium --timeout=120s
kubectl -n kube-system rollout status daemonset/cilium-envoy --timeout=120s

確認 Cilium 整體狀態正常：

cilium status

Step 5：安裝 Gateway API CRDs

kubectl apply -f https://raw.githubusercontent.com/kubernetes-sigs/gateway-api/v1.4.1/config/crd/standard/gateway.networking.k8s.io_gatewayclasses.yaml
kubectl apply -f https://raw.githubusercontent.com/kubernetes-sigs/gateway-api/v1.4.1/config/crd/standard/gateway.networking.k8s.io_gateways.yaml
kubectl apply -f https://raw.githubusercontent.com/kubernetes-sigs/gateway-api/v1.4.1/config/crd/standard/gateway.networking.k8s.io_httproutes.yaml
kubectl apply -f https://raw.githubusercontent.com/kubernetes-sigs/gateway-api/v1.4.1/config/crd/standard/gateway.networking.k8s.io_referencegrants.yaml
kubectl apply -f https://raw.githubusercontent.com/kubernetes-sigs/gateway-api/v1.4.1/config/crd/standard/gateway.networking.k8s.io_grpcroutes.yaml

確認 GatewayClass 已存在：

kubectl get gatewayclass

執行結果:

NAME CONTROLLER ACCEPTED AGE
cilium io.cilium/gateway-controller True 3m52s

Step 6：部署 Demo App

kubectl apply -f https://raw.githubusercontent.com/istio/istio/release-1.11/samples/bookinfo/platform/kube/bookinfo.yaml

檢視 Pods

$ kubectl get pods

執行結果:

NAME READY STATUS RESTARTS AGE
details-v1-75c85494bb-b76bs 1/1 Running 0 36s
productpage-v1-7c9bf9c988-f7cpf 1/1 Running 0 36s
ratings-v1-6456c55c66-7fczr 1/1 Running 0 36s
reviews-v1-545b8ff7c8-4fdxk 1/1 Running 0 36s
reviews-v2-5f6c87ccdb-68ws8 1/1 Running 0 36s
reviews-v3-74fb78c454-2s6ng 1/1 Running 0 36s

Step 7：Deploy the Cilium Gateway

⚠️ 關於 spec.addresses 欄位： 由於 Issue #42786 的緣故，hostNetwork 模式下此欄位不會生效也不會被填入 Gateway status。以下 YAML 中保留此欄位僅作為「此 Gateway 實際對外的 node IP」的文件化註記，Cilium 並不會使用它來分配位址。

cat <<'EOF' | kubectl apply -f -
---
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
name: my-gateway
spec:
gatewayClassName: cilium
addresses:
- type: IPAddress
value: "192.168.11.173"
- type: IPAddress
value: "192.168.11.174"
- type: IPAddress
value: "192.168.11.175"
listeners:
- protocol: HTTP
port: 80
name: web-gw
allowedRoutes:
namespaces:
from: Same
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
name: http-app-1
spec:
parentRefs:
- name: my-gateway
namespace: default
rules:
- matches:
- path:
type: PathPrefix
value: /details
backendRefs:
- name: details
port: 9080
- matches:
- headers:
- type: Exact
name: magic
value: foo
queryParams:
- type: Exact
name: great
value: example
path:
type: PathPrefix
value: /
method: GET
backendRefs:
- name: productpage
port: 9080
EOF

Step 8：驗證端到端連通

⚠️ 驗證方法變更： 由於 Issue #42786，Gateway 層的 Programmed 條件會永遠是 False，因此不能用它來判定部署成功。請改用以下方法驗證。

8.1 檢查 Gateway 與 Listener 狀態（預期輸出已修正）

kubectl get gateway my-gateway
kubectl describe gateway my-gateway

預期輸出（受 Issue #42786 影響）：

NAME CLASS ADDRESS PROGRAMMED AGE
my-gateway cilium False 1m

在 kubectl describe gateway 的輸出中，請確認以下條件皆為 True（這些才是部署成功的實際指標）：

層級	Condition Type	預期 Status	預期 Reason
Gateway	`Accepted`	True	`Accepted`
Listener	`Accepted`	True	`Accepted`
Listener	`ResolvedRefs`	True	`ResolvedRefs`
Gateway	`Programmed`	False（Known Issue，忽略）	`AddressNotAssigned`
Listener	`Programmed`	False（Known Issue，忽略）	`Pending`

只要上表中 Accepted 與 ResolvedRefs 為 True，即代表 Gateway 設定被成功接受與解析，可以進入下一步實際連通驗證。

8.2 確認 Envoy 已在 Gateway node 上監聽

SSH 到任一 gateway node，確認 Envoy 有在監聽 80 port：

ss -tlnp | grep ':80'

應該可以看到 cilium-envoy 程序正在監聽 0.0.0.0:80。

8.3 從外部實測 HTTP 連通性（最重要的驗證）

從外部用 3 台 gateway node 的 IP 分別測試：

curl -H "Host: app.example.com" http://<worker-node-1-ip>/details/1
curl -H "Host: app.example.com" http://<worker-node-2-ip>/details/1
curl -H "Host: app.example.com" http://<worker-node-3-ip>/details/1

只要能成功取得 HTTP 回應，代表整個路徑是通的 —— Gateway status 顯示 Programmed: False 純粹是 Issue #42786 的顯示問題，不影響流量。

8.4 建議作法：用 listener 條件代替 gateway 條件作為自動化等待點

若有 CI/CD 需要「等待 Gateway 就緒」，請使用以下替代方式之一：

方式 A：等待 Listener Accepted（不受 Issue #42786 影響）

kubectl wait --for=jsonpath='{.status.listeners[0].conditions[?(@.type=="Accepted")].status}'=True \
 gateway/my-gateway --timeout=60s

方式 B：直接 curl 實測

until curl -sf -H "Host: app.example.com" http://<worker-node-1-ip>/details/1 > /dev/null; do
 sleep 2
done
echo "Gateway is serving traffic"

⚠️ 請勿使用：

# 這個會永遠 timeout，因為 Programmed 條件受 Issue #42786 影響
kubectl wait --for=condition=Programmed gateway/my-gateway --timeout=60s

F5 / Nginx LB 設定

在外部 L4 LB 上設定 pool members，指向 3 台 gateway node：

Protocol	Pool Members
HTTP	`<worker-node-1-ip>:80`, `<worker-node-2-ip>:80`, `<worker-node-3-ip>:80`
HTTPS	`<worker-node-1-ip>:443`, `<worker-node-2-ip>:443`, `<worker-node-3-ip>:443`

Health Check 建議：

TCP monitor（最簡單）：對 port 80 / 443 做 TCP 連線檢查
HTTP monitor（更精確）：HTTP GET /，回傳 404 也算健康（Envoy 在沒有匹配 route 時的預設行為）

💡 提示： F5/Nginx 的 pool member 設定不會從 Gateway status.addresses 讀取。所以 Issue #42786 不影響此設定流程，你仍然是手動指定 3 台 gateway node 的 IP。

注意事項

hostNetwork 與 LoadBalancer 互斥： 啟用 hostNetwork 後，Cilium 不會再為 Gateway 建立 LoadBalancer type Service
Port 衝突風險： 確保 80/443 在 gateway node 上沒有被其他程式佔用（例如原本的 Ingress-Nginx）
移除舊 Ingress-Nginx： 如果要完全切換，記得先停用 RKE2 內建的 Ingress-Nginx，避免 port 衝突
Gateway listener port 唯一性： 每個 Gateway 資源的 listener port 在所有 node 上必須唯一

Rollback 方式： 如需還原，使用備份的 values 重新 upgrade 即可：

helm upgrade cilium cilium/cilium \
 --namespace kube-system \
 -f cilium-backup-values.yaml

Gateway status 顯示問題（Issue #42786）： 在 hostNetwork 模式下 Gateway 永遠顯示 Programmed: False / AddressNotAssigned，此為已知的 upstream issue（截至 2026-04-20 仍為 Open 狀態，尚無關聯修復 PR）。此現象僅影響 status 顯示，不影響實際流量。驗證部署是否成功請以 Listener 的 Accepted/ResolvedRefs 條件與實際 curl 測試為準，詳見 Step 8。

⚠️ 已知問題（Known Issue）— 必讀

Upstream Issue： cilium/cilium#42786 — Gateway API with Host Network: Gateway stays PROGRAMMED: False 最後確認時間： 2026-04-20

症狀

kubectl get gateway 的 ADDRESS 欄空白、PROGRAMMED 欄顯示 False（Reason: AddressNotAssigned）。Listener 層的 Programmed 同樣為 False（Reason: Pending）。

Issue 現狀（截至 2026-04-20）

GitHub Issue 仍為 Open 狀態，無關聯修復 PR，Cilium v1.19.x 亦未修復。詳細追蹤資訊請見文末附錄。

影響範圍與根因

回報者 @dke 在 issue 中明確指出：

“Not a regression, but wanted to state that I can get a working gateway-api if I don’t use host network mode, but rather a setup with, for example, cilium and bgp based load balancers.”

也就是說：

這不是 regression（不是新版本把舊版本弄壞的問題）
這是 hostNetwork 模式特有的行為——一旦改用 Cilium + BGP LoadBalancer（有真正的 Service 可供 LB-IPAM 指派 IP）就會恢復正常
根因是 Cilium 的 spec.addresses 實作與 LB-IPAM 強耦合，而 hostNetwork 模式會停用 LoadBalancer Service，導致 status.addresses 沒有 IP 來源可以填入

此問題不影響的部分 ✅

實際流量 routing 完全正常：Envoy 仍會在 host 的 80/443 port 監聽，F5 → node IP → Envoy → backend 的路徑運作如預期
Listener 的 Accepted 與 ResolvedRefs 都會是 True：代表 Gateway / HTTPRoute 的設定本身是有效、可接受的
HTTPRoute 功能正常：path 比對、header 比對、backend 轉發都會生效

此問題會影響的部分 ❌

kubectl get gateway 的 ADDRESS 欄永遠是空白
Gateway 層的 Programmed 條件永遠是 False
不可使用 kubectl wait --for=condition=programmed gateway/<name> 作為 CI/CD 或部署自動化的等待條件

etcd 寫入一筆資料後，Leader 和 Follower 做了哪些事？

Mon, 13 Apr 2026 08:58:06 +0800

前置準備

1. 建立 tkha HA 叢集

本實驗需要一個 3 control-plane 的 etcd HA 叢集。如果還沒建立，先用 tk 工具建立：

~/tk/bin/kto tkha

kto 會建立叢集並初始化第一個 control-plane（tkha-control-plane），但不會自動加入另外兩個 control-plane。

2. 加入另外兩個 Control-plane 節點

確認三個 control-plane 是否都已加入叢集：

sudo podman exec tkha-control-plane etcdctl member list -w table

如果只有 1 個 member，需要手動加入另外兩個：

# 產生 certificate key 和 join 指令
CERT_KEY=$(sudo podman exec tkha-control-plane bash -c \
 'kubeadm init phase upload-certs --upload-certs' 2>/dev/null | tail -1 | tr -d '\r')

JOIN_CMD=$(sudo podman exec tkha-control-plane bash -c \
 'kubeadm token create --print-join-command' | tr -d '\r')

IGNORE='--ignore-preflight-errors=SystemVerification'

# 加入第二個 control-plane
sudo podman exec tkha-control-plane1 bash -c \
 "$JOIN_CMD --control-plane --certificate-key $CERT_KEY $IGNORE"

# 等待加入完成
sleep 30

# 加入第三個 control-plane
sudo podman exec tkha-control-plane2 bash -c \
 "$JOIN_CMD --control-plane --certificate-key $CERT_KEY $IGNORE"

# 等待加入完成
sleep 30

加入後再次確認，應該看到 3 個 member：

sudo podman exec tkha-control-plane etcdctl member list -w table

3. 安裝 host 上的工具

# tcpdump — 抓取網路封包
which tcpdump || sudo apk add tcpdump

# etcd-dump-logs — 解析 etcd WAL 檔案（需要 Go 環境）
which etcd-dump-logs || {
 go install go.etcd.io/etcd/tools/etcd-dump-logs@latest
 sudo cp $(go env GOPATH)/bin/etcd-dump-logs /usr/local/bin/
}

容器內的 etcdctl、crictl、sed 是 tkha 叢集自帶的，不需要額外安裝。

實驗環境

項目	值
叢集	tkha（3 control-plane HA）
etcd 版本	3.6.5
Leader	172.22.64.1（tkha-control-plane）
Follower	172.22.64.2、172.22.64.3
Heartbeat 間隔	250ms
Election Timeout	2500ms

先搞懂這些術語

Leader / Follower
- 原文：At any given time, one server is the leader and the others are followers. The leader handles all client requests.
- 白話：老大和跟班。叢集中只有一個老大（Leader），其他都是跟班（Follower）。所有寫入都必須先經過老大，由老大負責分發給跟班。
AppendEntries
- 原文：AppendEntries RPCs are initiated by the leader to replicate log entries and to provide a form of heartbeat.
- 白話：老大把「要做的事」抄送給跟班的動作。像是老大寫了一張便條紙，影印後發給每個跟班說：「照著做，做完回報。」
WAL（Write Ahead Log）
- 原文：The write ahead log is a persistent ordered record of every change made to etcd’s data.
- 白話：「先寫日記再做事」的日記本。不管是老大還是跟班，收到一筆操作後都要先寫進這本日記。這樣即使突然當機，重開機後看日記就能恢復。
fsync
- 原文：fsync() transfers all modified in-core data of the file to the disk device, ensuring that all changed data is physically written to disk.
- 白話：把資料真正刷到磁碟上。一般寫檔案只是寫到記憶體的快取，斷電就沒了。fsync 強制把快取刷到磁碟，確保斷電也不丟。這是整個流程中最花時間的地方之一。
ACK（Acknowledgement）
- 原文：A response from a follower indicating that it has successfully written the entry to its log.
- 白話：跟班回報「收到，我已經記在日記裡了」。老大要等到夠多跟班回報 ACK 才算寫入成功。
Quorum
- 原文：The minimum number of members that must agree for a change to be committed. For a cluster of N members, quorum is (N/2)+1.
- 白話：多數決。超過半數的節點都寫好日記了，才算數。3 個節點需要 2 個同意（老大自己算 1 個，只要再有 1 個跟班 ACK 就夠了）。
Commit
- 原文：A log entry is committed once the leader that created the entry has replicated it on a majority of the servers.
- 白話：老大確認多數決通過後，把這筆操作正式生效——寫入真正的資料庫（BoltDB），而不只是日記。
RAFT INDEX
- 原文：Each log entry stores a state machine command along with the term number and log index. The log index is an integer that identifies its position in the log.
- 白話：每筆操作的全域流水號。老大和跟班共用同一組編號，同一個 index 在所有節點上代表的是同一筆操作。
RAFT TERM
- 原文：Each term begins with an election. Terms act as a logical clock in Raft and allow servers to detect obsolete information.
- 白話：老大的「任期編號」。每次選出新老大，term 就加 1。可以把它想成「第幾屆」。

結果：完整寫入流程

當 Client 執行 etcdctl put /hello world 時，etcd 內部會經過以下 7 個步驟，Client 才會收到 “OK”：

步驟	誰做的	做了什麼	影響因素
(1)	Client	發送 put 請求給 Leader（port 2379）	—
(2)	Leader	寫入自己的 WAL，fsync 到磁碟	:floppy_disk: 磁碟延遲
(3)	Leader	發送 AppendEntries 給 Follower（port 2380）	:globe_with_meridians: 網路延遲
(4)	Follower	寫入自己的 WAL，fsync 到磁碟	:floppy_disk: 磁碟延遲
(5)	Follower	回覆 ACK 給 Leader	:globe_with_meridians: 網路延遲
(6)	Leader	確認 Quorum（2/3），commit，回覆 Client “OK”	:floppy_disk: 磁碟延遲
(7)	Leader	非同步通知 Follower commit（Client 已收到 OK）	—

時序圖：

 Client Leader (172.22.64.1) Follower (172.22.64.2)
| | |
| (1) put /hello world | |
| --------------------------> | |
| (port 2379) | |
| | |
| (2) Leader 寫入自己的 WAL |
| (fsync 到磁碟) |
| | |
| | (3) AppendEntries |
| | ----------------------------> |
| | (port 2380, 639 bytes) |
| | |
| | (4) Follower 寫入 WAL
| | (fsync 到磁碟)
| | |
| | (5) ACK |
| | <---------------------------- |
| | (port 2380, 75 bytes) |
| | (間隔 2.040ms) |
| | |
| (6) Quorum 達成 (2/3) |
| Leader commit |
| | |
| "OK" | |
| <-------------------------- | |
| | |
| | (7) 通知 commit（非同步） |
| | ----------------------------> |
| | Follower commit
| | |

Client 收到 “OK” 的時間點是在步驟 (6)，不是 (7)。Follower commit 是非同步的，不影響 Client 感受到的延遲。

以下用 5 個實驗，一步一步驗證上述流程是對的。

驗證 1：辨識誰是 Leader

對應步驟 (1)：Client 要把 put 請求送給 Leader，所以我們先確認誰是 Leader。

執行命令：

sudo podman exec tkha-control-plane etcdctl \
 --endpoints=https://172.22.64.1:2379,https://172.22.64.2:2379,https://172.22.64.3:2379 \
 endpoint status -w table

執行結果（節錄關鍵欄位）：

+--------------------------+------------------+---------+-----------+-----------+
| ENDPOINT | ID | VERSION | IS LEADER | RAFT TERM |
+--------------------------+------------------+---------+-----------+-----------+
| https://172.22.64.1:2379 | f49dafb8a84b142e | 3.6.5 | true | 2 |
| https://172.22.64.2:2379 | bc789b7376e525b5 | 3.6.5 | false | 2 |
| https://172.22.64.3:2379 | b8399ab2942e1696 | 3.6.5 | false | 2 |
+--------------------------+------------------+---------+-----------+-----------+

實際輸出會包含更多欄位（DB SIZE、QUOTA 等），以上只列出關鍵欄位。

這證明了什麼？

172.22.64.1 是 Leader（IS LEADER = true）
三個節點的 RAFT TERM 都是 2，代表目前是「第 2 屆」Leader

驗證 2：開啟 Follower 的 debug log

為了在後面的驗證中看到 Follower 收到 AppendEntries 的日誌，需要先開啟 debug log。這個步驟必須在寫入資料之前完成。

執行命令：

sudo podman exec tkha-control-plane1 bash -c '
 sed -i "/- etcd$/a\\ - --log-level=debug" /etc/kubernetes/manifests/etcd.yaml
'

kubelet 偵測到 manifest 變更，會自動重啟 Follower 的 etcd pod。等約 1~2 分鐘後確認叢集恢復健康（如果還是 unhealthy，再等 30 秒重試）：

sudo podman exec tkha-control-plane etcdctl \
 --endpoints=https://172.22.64.1:2379,https://172.22.64.2:2379,https://172.22.64.3:2379 \
 endpoint health -w table

執行結果（三個 endpoint 都要是 healthy 才能繼續）：

+--------------------------+--------+
| ENDPOINT | HEALTH |
+--------------------------+--------+
| https://172.22.64.1:2379 | true |
| https://172.22.64.2:2379 | true |
| https://172.22.64.3:2379 | true |
+--------------------------+--------+

如果 172.22.64.2 還是 unhealthy，每隔 30 秒重試一次，直到三個都是 true。

驗證 3：tcpdump 觀察 Leader 發封包給 Follower

對應步驟 (3) 和 (5)：Leader 透過 port 2380 發送 AppendEntries 給 Follower，Follower 回覆 ACK。

準備：在 host 上啟動 tcpdump

執行命令（Terminal 1）：

sudo tcpdump -i any host 172.22.64.1 and host 172.22.64.2 and port 2380 -nn -ttt -q -c 100

觸發：寫入一筆資料

執行命令（Terminal 2）：

sudo podman exec tkha-control-plane etcdctl put /hello "world"

執行結果：

OK

tcpdump 抓到的封包

執行結果（Terminal 1，節錄重點）：

Heartbeat 封包（背景流量，大小固定 ~84-85 bytes）：

00:00:00.000000 IP 172.22.64.1.2380 > 172.22.64.2.43206: tcp 85
00:00:00.000034 IP 172.22.64.2.43206 > 172.22.64.1.2380: tcp 0
00:00:00.000157 IP 172.22.64.2.2380 > 172.22.64.1.58336: tcp 84
00:00:00.000027 IP 172.22.64.1.58336 > 172.22.64.2.2380: tcp 0

資料寫入觸發的封包：

00:00:00.005596 IP 172.22.64.1.2380 > 172.22.64.2.43192: tcp 639 <-- AppendEntries
00:00:00.000034 IP 172.22.64.2.43192 > 172.22.64.1.2380: tcp 0 <-- TCP ACK
00:00:00.002040 IP 172.22.64.2.2380 > 172.22.64.1.58336: tcp 75 <-- Follower ACK

實際的 port 號和封包大小會略有不同，重點是觀察 Leader→Follower 出現一個比 heartbeat 大很多的封包，以及 Follower→Leader 的回覆。

這證明了什麼？

步驟 (3) 已驗證 — Leader (172.22.64.1) 發了一個 639 bytes 的封包給 Follower (172.22.64.2)，比 heartbeat 的 85 bytes 大很多。這就是包含 /hello = world 的 AppendEntries。

步驟 (5) 已驗證 — Follower 在 2.040ms 後回覆了一個 75 bytes 的小封包（ACK），比 request 小很多，只是在說「我記好了」。2.040ms 的間隔就是 Follower 處理 + 寫入 WAL (fsync) 的時間。

驗證 4：debug log 觀察 Follower 收到資料

對應步驟 (4)：Follower 收到 AppendEntries 後，寫入自己的 WAL。

執行命令：

sudo podman exec tkha-control-plane1 bash -c '
 crictl logs $(crictl ps -q --name etcd) 2>&1 | grep "hello"
'

執行結果：

{"level":"debug","ts":"2026-04-13T08:17:16.219400Z",
 "caller":"etcdserver/server.go:1971",
 "msg":"applyEntryNormal",
 "raftReq":"header:<ID:1454272925698278610 username:\"kube-apiserver-etcd-client\" auth_revision:1 > put:<key:\"/hello\" value:\"world\" > "}

實際的 timestamp 和 ID 會不同，重點是看到 applyEntryNormal 和 put:<key:"/hello" value:"world">。

這證明了什麼？

步驟 (4) 已驗證 — Follower 的 applyEntryNormal 日誌明確顯示收到了 put:<key:"/hello" value:"world">。這就是 Leader 透過 AppendEntries 送過來的資料，Follower 寫入 WAL 後 apply 到狀態機。

驗證 5：WAL dump 比對 Leader 和 Follower

對應步驟 (2) 和 (4)：Leader 和 Follower 都會把操作寫入 WAL，兩邊的 WAL 應該包含相同的 entry。

寫入測試資料

執行命令：

sudo podman exec tkha-control-plane etcdctl put /wal-test "raft-replicated-data"

複製 WAL 到 host 並用 etcd-dump-logs 解析

執行命令：

# 複製 WAL
sudo podman cp tkha-control-plane:/var/lib/etcd/member /tmp/leader-member
sudo podman cp tkha-control-plane1:/var/lib/etcd/member /tmp/follower-member

# 建立 etcd-dump-logs 需要的目錄結構
sudo mkdir -p /tmp/leader-data/member /tmp/follower-data/member
sudo ln -sf /tmp/leader-member/wal /tmp/leader-data/member/wal
sudo ln -sf /tmp/leader-member/snap /tmp/leader-data/member/snap
sudo ln -sf /tmp/follower-member/wal /tmp/follower-data/member/wal
sudo ln -sf /tmp/follower-member/snap /tmp/follower-data/member/snap

# Dump Leader WAL
sudo etcd-dump-logs /tmp/leader-data | grep "wal-test"

# Dump Follower WAL
sudo etcd-dump-logs /tmp/follower-data | grep "wal-test"

執行結果：

Leader WAL：

 2 41857 norm header:<ID:1454272925698278720 username:"kube-apiserver-etcd-client" auth_revision:1 > put:<key:"/wal-test" value:"raft-replicated-data" >

Follower WAL：

 2 41857 norm header:<ID:1454272925698278720 username:"kube-apiserver-etcd-client" auth_revision:1 > put:<key:"/wal-test" value:"raft-replicated-data" >

實際的 index 和 ID 會不同，重點是兩邊的 term、index、data 完全一致。

這證明了什麼？

步驟 (2) 和 (4) 已驗證 — Leader 和 Follower 的 WAL 中都有完全一致的 entry。term、index、data 一模一樣，證明 Leader 複製給 Follower 的是原封不動的 Raft entry。

驗證 6：從 Follower 讀取確認 commit

對應步驟 (7)：Leader 非同步通知 Follower commit 後，Follower 應該也能讀到這筆資料。

執行命令：

sudo podman exec tkha-control-plane etcdctl --endpoints=https://172.22.64.2:2379 get /hello

執行結果：

/hello
world

這證明了什麼？

步驟 (7) 已驗證 — 從 Follower（172.22.64.2）的 endpoint 直接讀取，確認 /hello = world 已經 commit 並 apply 到 Follower 的 BoltDB。整個 Raft 寫入流程走完了。

清理

# 刪除測試 key
sudo podman exec tkha-control-plane etcdctl del /hello
sudo podman exec tkha-control-plane etcdctl del /wal-test

# 還原 Follower 的 log level
sudo podman exec tkha-control-plane1 bash -c \
 'sed -i "/--log-level=debug/d" /etc/kubernetes/manifests/etcd.yaml'

# 清理 host 上的暫存檔
sudo rm -rf /tmp/leader-member /tmp/follower-member /tmp/leader-data /tmp/follower-data

驗證結果總表

步驟	理論描述	驗證編號	驗證方式	結果
(1)	Client 發送 put 請求	驗證 3	etcdctl put	:white_check_mark:
(2)	Leader 寫入 WAL	驗證 5	WAL dump	:white_check_mark:
(3)	Leader 發送 AppendEntries	驗證 3	tcpdump: 639B 封包	:white_check_mark:
(4)	Follower 寫入 WAL	驗證 4+5	debug log + WAL dump	:white_check_mark:
(5)	Follower 回覆 ACK	驗證 3	tcpdump: 75B 封包, 2.040ms	:white_check_mark:
(6)	Leader commit	驗證 3	Client 收到 “OK”	:white_check_mark:
(7)	Follower commit	驗證 6	從 Follower 讀到 `world`	:white_check_mark:

寫入延遲的組成

Client 感受到的延遲 = (2) Leader fsync + (3) 網路傳輸 + (4) Follower fsync + (5) 網路回覆 + (6) Leader commit
實測：(3) -> (5) 的時間差 = 2.040ms（包含網路 + Follower fsync）

因素	影響的步驟	說明
:floppy_disk: 磁碟延遲（fsync）	(2)、(4)、(6)	每個步驟各需要一次 fsync，把資料刷到磁碟
:globe_with_meridians: 網路延遲（peer 通訊）	(3)、(5)	Leader 和 Follower 之間各需要一次單程傳輸

Docker Mail Server 完整部署指南

Tue, 31 Mar 2026 10:01:38 +0800

前置條件

開始部署前，請確認以下環境條件皆已滿足。

基礎架構

項目	需求	說明
DNS Server	必須	內網需有可控的 DNS Server（如 BIND），用於新增 MX / SPF / DKIM / DMARC 等 TXT Record。本文以 `nsupdate` 動態更新為例
DNS MX Record	必須	域名的 MX 記錄需指向 Mail Server（例如 `kubeantony.com. MX 10 mx1.kubeantony.com.`）
DNS A Record	必須	Mail Server 主機名需有對應的 A 記錄（例如 `mx1.kubeantony.com. A 192.168.11.3`）
固定 IP	建議	Mail Server 應使用固定 IP，避免 DNS 記錄失效

Mail Server 主機

項目	需求	說明
作業系統	Linux（Debian/Ubuntu/RHEL/Rocky 等）	需支援 Podman 4.4+
Podman	4.4 以上	需支援 Quadlet（`.kube` 單元檔）。確認版本：`podman --version`
Git	必須	用於下載 mkcert 憑證工具
OpenSSL	必須	用於產生自簽憑證及驗證 TLS。確認版本：`openssl version`
systemd	必須	Quadlet 依賴 systemd generator 產生 service

網路 Port

Mail Server 需開放以下 Port（使用 hostNetwork 模式會直接綁定主機 Port）：

Port	協定	服務	說明
25	TCP	SMTP	接收外部郵件
465	TCP	SMTPS	SMTP over TLS（隱式 TLS）
587	TCP	Submission	SMTP 寄信（STARTTLS + 認證）
993	TCP	IMAPS	IMAP over TLS（收信）
995	TCP	POP3S	POP3 over TLS（收信）
11334	TCP	Rspamd Web UI	Rspamd 管理介面（HTTP）

測試機器

項目	需求	說明
同網段的其他機器	必須	測試寄信步驟需在內網其他機器執行（不是 Mail Server 本機）
s-nail 或 msmtp	建議	用於 SMTP 寄信測試。步驟十一會說明安裝方式
dig	建議	用於驗證 DNS Record。安裝：`apt install dnsutils` 或 `apk add bind-tools`

快速檢查腳本

在 Mail Server 主機上執行，一次確認所有前置條件：

cat << 'SCRIPT' | sudo tee /usr/local/bin/check-mail-prereqs.sh
#!/bin/bash
# Mail Server 前置條件檢查腳本
# 用法：bash check-mail-prereqs.sh <DNS_IP>

DNS_IP="${1:?用法: bash $0 <DNS_IP>}"

R='\033[31m'
G='\033[32m'
N='\033[0m'
P=0
F=0

c(){
 local label="$1"
 local cmd="$2"
 if eval "$cmd" >/dev/null 2>&1; then
 echo -e " [${G}PASS${N}] ${label}"
 ((P++))
 else
 echo -e " [${R}FAIL${N}] ${label}"
 ((F++))
 fi
}

# 檢查 Port 是否被非 mail 服務佔用
# 排除 master (Postfix)、dovecot、rspamd — Container 內的 mail 服務屬正常
check_port(){
 local port="$1"
 ! ss -tlnp 2>/dev/null | grep -E ":${port}\b" | grep -Eqv 'master|dovecot|rspamd'
}

echo "===== Mail Server 前置條件檢查 ====="

PODMAN_MAJOR=$(podman --version 2>/dev/null | awk '{print $3}' | cut -d. -f1)
c "Podman >= 4.4" "test ${PODMAN_MAJOR:-0} -ge 4"
c "Quadlet generator" "test -f /usr/libexec/podman/quadlet"
c "OpenSSL" "openssl version"
c "Git" "git --version"
c "systemd" "systemctl is-system-running | grep -qE 'running|degraded'"
c "Port 25 未被其他服務佔用" "check_port 25"
c "Port 465 未被其他服務佔用" "check_port 465"
c "Port 587 未被其他服務佔用" "check_port 587"
c "Port 993 未被其他服務佔用" "check_port 993"
c "Port 995 未被其他服務佔用" "check_port 995"
c "Port 11334 未被其他服務佔用" "check_port 11334"
c "DNS Server ${DNS_IP}" "dig @${DNS_IP} google.com +short +time=3"

echo "===== ${P} 通過 / ${F} 失敗 ====="
SCRIPT

sudo chmod +x /usr/local/bin/check-mail-prereqs.sh

執行檢查（帶入 DNS Server IP）：

sudo bash /usr/local/bin/check-mail-prereqs.sh 192.168.11.2 # ← 根據環境修改

注意： Port 檢查會排除 Postfix（master）、Dovecot、Rspamd，因為使用 hostNetwork 模式時 Container 內的服務會直接綁定主機 Port，這是正常的。檢查目的是確認沒有其他非 Mail Server 的服務佔用這些 Port。如果 Mail Server 尚未啟動，所有 Port 檢查應顯示 PASS。

環境變數速查表

後續每個步驟的開頭都會列出該步驟所需的環境變數，請根據你的環境修改後再執行。

變數	範例值	說明
`DN`	`kubeantony.com`	郵件域名
`MAIL_HOST`	`mx1`	郵件主機名稱前綴
`MAIL_FQDN`	`mx1.kubeantony.com`	郵件主機 FQDN
`MAIL_IP`	`192.168.11.3`	Mail Server IP
`DNS_IP`	`192.168.11.2`	內網 DNS Server IP
`MY_NETWORKS`	`127.0.0.0/8,192.168.11.0/24`	允許 relay 的網段
`NET_IF`	`ens18`	Mail Server 網路介面名稱
`POSTMASTER`	`bigred`	Postmaster 帳號名稱
`RSPAMD_PW`	`$2$zmnrfh...`	Rspamd Web UI 密碼 hash

一、建立 Container Image

# ===== 根據環境修改 =====
export DN="kubeantony.com" # 郵件域名

1.1 建立 Dockerfile

sudo mkdir -p /opt/zfs/images/dkmail-rspamd

cat << 'EOF' | sudo tee /opt/zfs/images/dkmail-rspamd/Dockerfile
FROM docker.io/mailserver/docker-mailserver
ARG DN=""
ENV OVERRIDE_HOSTNAME="mx1.${DN}" \
 DMS_DEBUG="1" \
 POSTMASTER_ADDRESS="bigred@${DN}" \
 ENABLE_RSPAMD="1" \
 ENABLE_OPENDKIM="0" \
 ENABLE_OPENDMARC="0" \
 ENABLE_POLICYD_SPF="0" \
 ENABLE_AMAVIS="0" \
 ENABLE_SPAMASSASSIN="0" \
 ENABLE_IMAP="1" \
 ENABLE_POP3="1"
RUN apt-get update && apt-get install -y net-tools curl wget nano && \
 setup email add bigred@${DN} bigred && \
 setup email add rbean@${DN} rbean && \
 setup email add gbean@${DN} gbean && \
 touch /tmp/docker-mailserver/postfix-main.cf
EOF

1.2 Build 映像檔

sudo podman build \
 --build-arg DN="${DN}" \
 --format docker \
 --no-cache \
 -t dkmail.rspamd \
 /opt/zfs/images/dkmail-rspamd/

1.3 標記映像檔（Kubernetes YAML 需要 localhost 前綴）

sudo podman tag dkmail.rspamd localhost/dkmail.rspamd:latest

二、產生自簽 TLS 憑證

# ===== 根據環境修改 =====
export DN="kubeantony.com" # 郵件域名
export MAIL_HOST="mx1" # 郵件主機名稱前綴
export MAIL_FQDN="${MAIL_HOST}.${DN}" # 郵件主機 FQDN（自動組合）

2.1 下載 mkcert 工具

cd /opt
sudo git clone https://github.com/braveantony/mkcert.git
sudo chmod +x /opt/mkcert/certctl

2.2 編輯設定檔

cat << EOF | sudo tee /opt/mkcert/config
# CA 相關設定
CA_KEY="ca.key"
CA_CRT="ca.crt"
CA_DAYS=3650
CA_SUBJ="/C=TW/ST=Taipei/L=Taipei/O=${DN}/OU=Mail/CN=${DN} Root CA"

# Server 相關設定
DOMAIN_NAME="${DN}"
SERVER_KEY="\${DOMAIN_NAME}.key"
SERVER_CSR="\${DOMAIN_NAME}.csr"
SERVER_CRT="\${DOMAIN_NAME}.crt"
SERVER_DAYS=3650
SERVER_SUBJ="/C=TW/ST=Taipei/L=Taipei/O=${DN}/OU=Mail/CN=${MAIL_FQDN}"
V3_EXT="v3.ext"

ALT_NAMES=(
 "DNS.1=*.\${DOMAIN_NAME}"
 "DNS.2=\${DOMAIN_NAME}"
 "DNS.3=${MAIL_FQDN}"
)
EOF

2.3 產生憑證

sudo /opt/mkcert/certctl

2.4 確認產生結果

ls -l /opt/mkcert/${DN}/

預期輸出：

ca.crt # CA 根憑證
ca.key # CA 私鑰
<DN>.crt # 伺服器憑證
<DN>.key # 伺服器私鑰

三、部署 TLS 憑證與設定檔

# ===== 根據環境修改 =====
export DN="kubeantony.com" # 郵件域名
export MY_NETWORKS="127.0.0.0/8,192.168.11.0/24" # 允許 relay 的網段
export RSPAMD_PW='$2$zmnrfhkhbr9sb411b8eykyxgs1do4jeg$3fjncbo78qfsymbzu7nhfi35inhwezqh313trc7if4ie3d6sj1fy' # Rspamd Web UI 密碼 hash

3.1 建立目錄結構

sudo mkdir -p \
 /opt/zfs/dkmail/data \
 /opt/zfs/dkmail/conf/ssl \
 /opt/zfs/dkmail/conf/rspamd/override.d

3.2 複製憑證

sudo cp /opt/mkcert/${DN}/${DN}.key /opt/zfs/dkmail/conf/ssl/

sudo bash -c "cat \
 /opt/mkcert/${DN}/${DN}.crt \
 /opt/mkcert/${DN}/ca.crt \
 > /opt/zfs/dkmail/conf/ssl/fullchain.pem"

sudo chmod 644 /opt/zfs/dkmail/conf/ssl/fullchain.pem
sudo chmod 600 /opt/zfs/dkmail/conf/ssl/${DN}.key

3.3 Rspamd 設定

cat << 'EOF' | sudo tee /opt/zfs/dkmail/conf/rspamd/override.d/options.inc
local_networks = ["127.0.0.1/8"];
EOF

cat << EOF | sudo tee /opt/zfs/dkmail/conf/rspamd/override.d/worker-controller.inc
password = ${RSPAMD_PW}
EOF

cat << 'EOF' | sudo tee /opt/zfs/dkmail/conf/rspamd/override.d/hfilter.conf
enabled = false;
EOF

3.4 Postfix 額外設定

重要： docker-mailserver 透過 SSL_TYPE=manual 環境變數會自動設定 Postfix TLS（smtpd_tls_chain_files）、 Dovecot TLS、以及 SASL 認證 socket。postfix-main.cf 只需放 docker-mailserver 沒有自動處理的額外設定，不可手動設定 smtpd_tls_cert_file / smtpd_tls_key_file，否則會與 smtpd_tls_chain_files 衝突。

cat << EOF | sudo tee /opt/zfs/dkmail/conf/postfix-main.cf
# Relay 設定（允許內網寄信）
mynetworks = ${MY_NETWORKS}

# 寄出郵件啟用 TLS
smtp_tls_security_level = may
smtp_tls_protocols = !SSLv2,!SSLv3,!TLSv1,!TLSv1.1
EOF

四、建立 Kubernetes YAML

# ===== 根據環境修改 =====
export DN="kubeantony.com" # 郵件域名
export MAIL_HOST="mx1" # 郵件主機名稱前綴
export MAIL_FQDN="${MAIL_HOST}.${DN}" # 郵件主機 FQDN（自動組合）
export DNS_IP="192.168.11.2" # 內網 DNS Server IP
export NET_IF="ens18" # Mail Server 網路介面名稱

cat << EOF | sudo tee /etc/containers/systemd/dkmail.yaml
apiVersion: v1
kind: Pod
metadata:
 name: dkmail
 labels:
 app: dkmail
spec:
 hostname: ${MAIL_FQDN}
 hostNetwork: true
 dnsConfig:
 nameservers:
 - ${DNS_IP}
 searches:
 - ${DN}
 containers:
 - name: dkmail
 image: localhost/dkmail.rspamd:latest
 env:
 - name: NETWORK_INTERFACE
 value: "${NET_IF}"
 - name: SSL_TYPE
 value: "manual"
 - name: SSL_CERT_PATH
 value: "/etc/ssl/mail/fullchain.pem"
 - name: SSL_KEY_PATH
 value: "/etc/ssl/mail/${DN}.key"
 volumeMounts:
 - name: mail-data
 mountPath: /var/mail
 - name: postfix-main-cf
 mountPath: /tmp/docker-mailserver/postfix-main.cf
 readOnly: true
 - name: rspamd-config
 mountPath: /tmp/docker-mailserver/rspamd
 - name: ssl-certs
 mountPath: /etc/ssl/mail
 readOnly: true
 volumes:
 - name: mail-data
 hostPath:
 path: /opt/zfs/dkmail/data
 type: Directory
 - name: postfix-main-cf
 hostPath:
 path: /opt/zfs/dkmail/conf/postfix-main.cf
 type: File
 - name: rspamd-config
 hostPath:
 path: /opt/zfs/dkmail/conf/rspamd
 type: Directory
 - name: ssl-certs
 hostPath:
 path: /opt/zfs/dkmail/conf/ssl
 type: Directory
EOF

YAML 與原始 podman run 參數對照

原始 `podman run` 參數	YAML 對應欄位
`--name dkmail`	`metadata.name: dkmail`
`-h ${MAIL_FQDN}`	`spec.hostname`
`--network=host`	`spec.hostNetwork: true`
`--dns ${DNS_IP}`	`spec.dnsConfig.nameservers`
`--dns-search ${DN}`	`spec.dnsConfig.searches`
`-e NETWORK_INTERFACE=${NET_IF}`	`containers[].env`
`-e SSL_TYPE=manual`	`containers[].env`
`-v ...:/var/mail`	`volumes` + `volumeMounts`
`-v ...:ro`	`volumeMounts` 加上 `readOnly: true`

說明： 不需要掛載 Dovecot SSL 設定檔。docker-mailserver 會根據 SSL_TYPE=manual + SSL_CERT_PATH + SSL_KEY_PATH 自動設定 Postfix TLS、Dovecot TLS 和 SASL 認證 socket。

五、建立 Quadlet .kube 檔案

cat << 'EOF' | sudo tee /etc/containers/systemd/dkmail.kube
[Unit]
Description=Docker Mail Server (dkmail) with TLS
After=network-online.target
Wants=network-online.target

[Kube]
Yaml=/etc/containers/systemd/dkmail.yaml
Network=host

[Service]
Restart=always
RestartSec=10
TimeoutStartSec=120

[Install]
WantedBy=multi-user.target default.target
EOF

.kube 各區塊說明

區塊	設定	說明
`[Unit]`	`After=network-online.target`	網路就緒後才啟動
`[Kube]`	`Yaml=...`	指向 Kubernetes YAML 路徑
`[Kube]`	`Network=host`	使用 host 網路（郵件服務需直接綁定 Port）
`[Service]`	`Restart=always`	異常退出自動重啟
`[Service]`	`TimeoutStartSec=120`	給 Container 足夠啟動時間
`[Install]`	`WantedBy=multi-user.target`	開機自動啟動

六、啟動服務

# 重新載入 systemd（讓 Quadlet generator 產生 service）
sudo systemctl daemon-reload

# 啟動服務
sudo systemctl start dkmail.service

# 設定開機自動啟動
sudo systemctl enable dkmail.service

# 確認狀態
sudo systemctl status dkmail.service

七、驗證 TLS

# ===== 根據環境修改 =====
export MAIL_FQDN="mx1.kubeantony.com" # 郵件主機 FQDN

7.1 確認 Pod 與 Container

sudo podman pod ps
sudo podman ps --pod

7.2 確認 TLS

# SMTP STARTTLS（Port 587）
openssl s_client -connect ${MAIL_FQDN}:587 -starttls smtp

# SMTPS（Port 465）
openssl s_client -connect ${MAIL_FQDN}:465

# IMAPS（Port 993）
openssl s_client -connect ${MAIL_FQDN}:993

# POP3S（Port 995）
openssl s_client -connect ${MAIL_FQDN}:995

正常輸出應包含：

subject: CN = <MAIL_FQDN>
issuer: CN = <DN> Root CA
Verify return code: 21 (unable to verify the first certificate) ← 自簽憑證正常現象

八、設定 SPF Record

# ===== 根據環境修改 =====
export DN="kubeantony.com" # 郵件域名
export MAIL_IP="192.168.11.3" # Mail Server IP
export DNS_IP="192.168.11.2" # 內網 DNS Server IP

透過 nsupdate 將 SPF 記錄新增至內網 DNS（BIND）：

nsupdate << EOF
server ${DNS_IP}
zone ${DN}
update del ${DN}. TXT
update add ${DN}. 300 IN TXT "v=spf1 ip4:${MAIL_IP} ~all"
send
EOF

驗證 SPF Record：

dig @${DNS_IP} ${DN}. TXT +short

預期輸出：

"v=spf1 ip4:<MAIL_IP> ~all"

九、設定 DKIM

# ===== 根據環境修改 =====
export DN="kubeantony.com" # 郵件域名
export DNS_IP="192.168.11.2" # 內網 DNS Server IP

9.1 產生 DKIM Key

sudo podman exec -it dkmail-dkmail setup config dkim domain ${DN}

預期輸出：

INFO rspamd-dkim: Creating DKIM keys of type 'rsa' and length '2048' with selector 'mail' for domain '<DN>'
INFO rspamd-dkim: Successfully created DKIM keys
INFO rspamd-dkim: Here is the content of the TXT DNS record mail._domainkey.<DN> that you need to create:
v=DKIM1; k=rsa; p=MIIBIjANBgkqhkiG9w0BAQE...

9.2 啟用內網寄信的 DKIM 簽署

重要： docker-mailserver 預設產生的 dkim_signing.conf 中 sign_local = false，這會導致從內網直接寄出的郵件不會被 DKIM 簽署。必須改為 true。

sudo sed -i 's/sign_local = false/sign_local = true/' \
 /opt/zfs/dkmail/conf/rspamd/override.d/dkim_signing.conf

驗證修改結果：

grep 'sign_local' /opt/zfs/dkmail/conf/rspamd/override.d/dkim_signing.conf

預期輸出：

sign_local = true;

9.3 確認產生的檔案

tree /opt/zfs/dkmail/conf/rspamd/

預期結構：

/opt/zfs/dkmail/conf/rspamd/
├── dkim
│ ├── rsa-2048-mail-<DN>.private.txt
│ ├── rsa-2048-mail-<DN>.public.dns.txt
│ └── rsa-2048-mail-<DN>.public.txt
└── override.d
├── dkim_signing.conf
├── hfilter.conf
├── options.inc
└── worker-controller.inc

9.4 擷取 DKIM Public Key

DKIM_K8S_TXT=$(sed -n 's|.*"\([^"]*\)".*|"\1"|p' \
 /opt/zfs/dkmail/conf/rspamd/dkim/rsa-2048-mail-${DN}.public.txt | tr '\n' ' ')

echo $DKIM_K8S_TXT

9.5 新增 DKIM TXT Record（以 BIND DNS 為例）

nsupdate << EOF
server ${DNS_IP}
zone ${DN}
update del mail._domainkey.${DN}
update add mail._domainkey.${DN} 3600 IN TXT $DKIM_K8S_TXT
send
EOF

9.6 驗證 DKIM Record

dig @${DNS_IP} mail._domainkey.${DN}. TXT +short

預期輸出：

"v=DKIM1; k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA..."

9.7 重啟 Container 套用 DKIM 設定

sudo systemctl restart dkmail.service

十、設定 DMARC Record

# ===== 根據環境修改 =====
export DN="kubeantony.com" # 郵件域名
export DNS_IP="192.168.11.2" # 內網 DNS Server IP
export POSTMASTER="bigred" # Postmaster 帳號名稱

說明： DMARC 需在 SPF 和 DKIM 都設定完成後再新增。 p=none 表示僅監控模式，不影響郵件遞送，待確認運作正常後可改為 p=quarantine 或 p=reject。

nsupdate << EOF
server ${DNS_IP}
zone ${DN}
update del _dmarc.${DN}. TXT
update add _dmarc.${DN}. 300 IN TXT "v=DMARC1; p=none; rua=mailto:${POSTMASTER}@${DN}"
send
EOF

驗證 DMARC Record：

dig @${DNS_IP} _dmarc.${DN}. TXT +short

預期輸出：

"v=DMARC1; p=none; rua=mailto:<POSTMASTER>@<DN>"

十一、測試寄信

重要： 以下測試步驟必須在同一內網的其他機器上執行（不是 Mail Server 本機）。從其他機器寄信才能正確模擬實際使用情境，驗證 mynetworks relay 設定、TLS 連線、SMTP 認證、以及 DKIM 簽署（sign_local 是否對內網來源生效）等功能是否正常。

# ===== 根據環境修改（在測試機器上執行）=====
export DN="kubeantony.com" # 郵件域名
export MAIL_HOST="mx1" # 郵件主機名稱前綴
export MAIL_FQDN="${MAIL_HOST}.${DN}" # 郵件主機 FQDN（自動組合）
export MAIL_IP="192.168.11.3" # Mail Server IP
export POSTMASTER="bigred" # Postmaster 帳號名稱

11.1 安裝寄信工具（在內網其他機器上執行）

# Debian/Ubuntu
sudo apt install -y s-nail

# Alpine Linux
sudo apk add s-nail

11.2 從內網直接寄信測試（不經 SMTP 認證）

echo "Test Mail" | s-nail \
 -S mta=smtp://${MAIL_IP} \
 -s "Mail Server Test" \
 "sreantony@gmail.com"

11.3 透過 SMTP 認證寄信測試（msmtp）

在內網其他機器上安裝 msmtp 並建立設定檔（自簽憑證需關閉憑證檢查）：

cat << EOF > ~/.msmtprc
account test
host ${MAIL_FQDN}
port 587
from ${POSTMASTER}@${DN}
auth plain
user ${POSTMASTER}@${DN}
password ${POSTMASTER}
tls on
tls_starttls on
tls_certcheck off
logfile /tmp/msmtp.log
EOF

chmod 600 ~/.msmtprc

注意： 帳號為 ${POSTMASTER}@${DN}（不是 ${POSTMASTER}@${MAIL_FQDN}），對應 Dockerfile 中 setup email add bigred@${DN} 的設定。

寄信測試：

echo -e "To: sreantony@gmail.com\nSubject: Auth Test\n\n認證測試" | msmtp -a test sreantony@gmail.com

11.4 驗證 Rspamd 評分

開啟 Rspamd Web UI（http://${MAIL_FQDN}:11334）查看 History， SPF / DKIM / DMARC 設定正確後，以下 Symbol 應消失或轉為通過：

Symbol	修正前	修正後
`R_SPF_NA`	+1.5（無 SPF）	`R_SPF_ALLOW`（SPF 通過）
`R_DKIM_NA`	+1.0（無 DKIM）	`R_DKIM_ALLOW`（DKIM 通過）
`DMARC_NA`	+0.5（無 DMARC）	`DMARC_POLICY_ALLOW`（DMARC 通過）
`AUTH_NA`	+2.5（未認證）	消失（經 SMTP 認證寄信）

十二、日常管理

操作	指令
啟動	`sudo systemctl start dkmail.service`
停止	`sudo systemctl stop dkmail.service`
重啟	`sudo systemctl restart dkmail.service`
查看狀態	`sudo systemctl status dkmail.service`
查看 log	`sudo journalctl -u dkmail.service -f`
開機啟動	`sudo systemctl enable dkmail.service`
取消開機啟動	`sudo systemctl disable dkmail.service`
進入 Container	`sudo podman exec -it dkmail-dkmail bash`
Container log	`sudo podman logs -f dkmail-dkmail`
Postfix log	`sudo podman exec -it dkmail-dkmail tail -50 /var/log/mail/mail.log`

注意： Container 名稱為 dkmail-dkmail（Pod 名稱 + Container 名稱）。

十三、客戶端匯入 CA 根憑證

# ===== 根據環境修改 =====
export DN="kubeantony.com" # 郵件域名
export MAIL_IP="192.168.11.3" # Mail Server IP

自簽憑證需在每台客戶端匯入 ca.crt：

# 從伺服器下載 ca.crt
scp user@${MAIL_IP}:/opt/mkcert/${DN}/ca.crt ~/Desktop/

客戶端	匯入方式
Thunderbird	設定 → 隱私與安全 → 憑證 → 匯入 → 選 `ca.crt` → 勾選「信任此 CA 識別網站」
Windows	雙擊 `ca.crt` → 安裝憑證 → 「受信任的根憑證授權單位」
macOS	雙擊 `ca.crt` → 加入鑰匙圈 → 設定為「永遠信任」
Linux	`sudo cp ca.crt /usr/local/share/ca-certificates/ && sudo update-ca-certificates`

十四、故障排除

Quadlet 沒有產生 service

# 手動執行 generator 檢查錯誤
sudo /usr/libexec/podman/quadlet --dryrun

手動測試 YAML 是否正確

# 用 podman kube play 直接測試
sudo podman kube play /etc/containers/systemd/dkmail.yaml

# 測試完畢清除
sudo podman kube down /etc/containers/systemd/dkmail.yaml

映像檔找不到

sudo podman images | grep dkmail

# 如果缺少 localhost 前綴，重新標記
sudo podman tag dkmail.rspamd localhost/dkmail.rspamd:latest

SMTP 寄信出現 Relay access denied

確認 postfix-main.cf 中 mynetworks 包含發信主機的網段：

sudo podman exec -it dkmail-dkmail postconf mynetworks

SMTP 認證失敗（SASL）

確認 Dovecot auth socket 存在：

sudo podman exec -it dkmail-dkmail ls -l /dev/shm/sasl-auth.sock

確認 Postfix 指向正確的 socket 路徑：

sudo podman exec -it dkmail-dkmail postconf smtpd_sasl_path

注意： docker-mailserver 的 Dovecot auth socket 位於 /dev/shm/sasl-auth.sock，不是 Postfix 預設的 private/auth。不要在 postfix-main.cf 手動設定 smtpd_sasl_path / smtpd_sasl_type，讓 docker-mailserver 自動處理。

TLS 憑證與 docker-mailserver 衝突

重要： 不要在 postfix-main.cf 設定 smtpd_tls_cert_file / smtpd_tls_key_file。 docker-mailserver 的 SSL_TYPE=manual 會使用 smtpd_tls_chain_files，兩者同時存在會產生衝突警告且舊的設定會被忽略。

完整目錄結構

/etc/containers/systemd/ # Quadlet 檔案
├── dkmail.kube # Quadlet 單元檔
└── dkmail.yaml # Kubernetes Pod YAML
/opt/zfs/dkmail/ # 資料與設定
├── data/ # 郵件資料（/var/mail）
└── conf/
├── postfix-main.cf # Postfix 額外設定（mynetworks + smtp_tls）
├── ssl/
│ ├── fullchain.pem # 伺服器憑證 + CA 憑證
│ └── <DN>.key # 伺服器私鑰
└── rspamd/
├── dkim/ # DKIM Keys（步驟九產生）
│ ├── rsa-2048-mail-<DN>.private.txt
│ ├── rsa-2048-mail-<DN>.public.dns.txt
│ └── rsa-2048-mail-<DN>.public.txt
└── override.d/
├── dkim_signing.conf # DKIM 簽署設定（步驟九產生）
├── options.inc
├── worker-controller.inc
└── hfilter.conf
/opt/mkcert/ # 憑證產生工具（備份保留）
├── certctl
├── config
└── <DN>/
├── ca.crt
├── ca.key
├── <DN>.crt
└── <DN>.key
/opt/zfs/images/dkmail-rspamd/ # Container Image Dockerfile
└── Dockerfile

Podman Start Docker Mail Server with TLS

Tue, 31 Mar 2026 07:37:44 +0800

環境資訊

項目	值
域名	`kubeantony.com`
主機名	`mx1.kubeantony.com`
容器引擎	Podman（`--network=host`）
網路環境	內網，無 Public IP
DNS 管理	Cloudflare
套用服務	SMTP（25/465/587）、IMAP（993）、POP3（995）、Rspamd Web UI

方案比較

	方案 A：mkcert 自簽憑證	方案 B：Let’s Encrypt + Cloudflare DNS
費用	免費	免費
需要 Public IP	否	否（DNS-01 驗證不需要）
客戶端信任	需手動匯入 CA 憑證	自動信任（公開 CA）
有效期限	10 年	90 天（自動續期）
適用場景	內部測試 / 個人使用	正式環境 / 對外服務
維護難度	低（幾乎不用管）	低（cron 自動續期）

方案 A：使用 braveantony/mkcert 自簽憑證

A-1：產生自簽憑證

# 下載 mkcert 工具
cd /opt
sudo git clone https://github.com/braveantony/mkcert.git
sudo chmod +x /opt/mkcert/certctl

編輯設定檔：

sudo nano /opt/mkcert/config

修改為以下內容：

# CA 相關設定
CA_KEY="ca.key"
CA_CRT="ca.crt"
CA_DAYS=3650
CA_SUBJ="/C=TW/ST=Taipei/L=Taipei/O=kubeantony/OU=Mail/CN=kubeantony Root CA"

# Server 相關設定
DOMAIN_NAME="kubeantony.com"
SERVER_KEY="${DOMAIN_NAME}.key"
SERVER_CSR="${DOMAIN_NAME}.csr"
SERVER_CRT="${DOMAIN_NAME}.crt"
SERVER_DAYS=3650
SERVER_SUBJ="/C=TW/ST=Taipei/L=Taipei/O=kubeantony/OU=Mail/CN=mx1.${DOMAIN_NAME}"
V3_EXT="v3.ext"

ALT_NAMES=(
 "DNS.1=*.${DOMAIN_NAME}"
 "DNS.2=${DOMAIN_NAME}"
 "DNS.3=mx1.${DOMAIN_NAME}"
)

# 產生憑證
sudo /opt/mkcert/certctl

# 確認結果
ls -l /opt/mkcert/kubeantony.com/
# 預期：ca.crt ca.key kubeantony.com.crt kubeantony.com.key

A-2：部署憑證

sudo mkdir -p /opt/zfs/dkmail/conf/ssl

sudo cp /opt/mkcert/kubeantony.com/kubeantony.com.key /opt/zfs/dkmail/conf/ssl/
sudo cp /opt/mkcert/kubeantony.com/kubeantony.com.crt /opt/zfs/dkmail/conf/ssl/

# 產生 fullchain（伺服器憑證 + CA 憑證）
sudo bash -c 'cat /opt/mkcert/kubeantony.com/kubeantony.com.crt \
 /opt/mkcert/kubeantony.com/ca.crt \
 > /opt/zfs/dkmail/conf/ssl/fullchain.pem'

sudo chmod 644 /opt/zfs/dkmail/conf/ssl/fullchain.pem
sudo chmod 600 /opt/zfs/dkmail/conf/ssl/kubeantony.com.key

A-3：客戶端匯入 CA 根憑證

自簽憑證需要在每台客戶端手動匯入 ca.crt：

客戶端	匯入方式
Thunderbird	設定 → 隱私與安全 → 憑證 → 匯入 → 選 `ca.crt` → 勾選「信任此 CA 識別網站」
Windows	雙擊 `ca.crt` → 安裝憑證 → 「受信任的根憑證授權單位」
macOS	雙擊 `ca.crt` → 加入鑰匙圈 → 設定為「永遠信任」
Linux	`sudo cp ca.crt /usr/local/share/ca-certificates/ && sudo update-ca-certificates`

完成後，跳至「共通步驟：設定 Mail Server 並啟動容器」。

方案 B：Let’s Encrypt + Cloudflare DNS-01 驗證

核心原理：acme.sh 透過 Cloudflare API 在 DNS 自動建立 _acme-challenge TXT 記錄， Let’s Encrypt 驗證該記錄後簽發憑證。全程不需要 Public IP 或開放任何 Port。

B-1：在 Cloudflare 建立 API Token

登入 Cloudflare Dashboard
右上角點擊個人頭像 → My Profile → API Tokens
點擊 Create Token
選擇 Edit zone DNS 模板（Use template）
設定權限：
- Permissions：Zone / DNS / Edit
- Zone Resources：Include → Specific zone → kubeantony.com
建立後複製 Token（只會顯示一次）
到 kubeantony.com 的 Overview 頁面，記下右側的 Zone ID

B-2：安裝 acme.sh

# 安裝 acme.sh（不需要 root，但建議用 root 方便管理憑證路徑）
sudo -i
curl https://get.acme.sh | sh -s email=bigred@kubeantony.com

# 讓 acme.sh 指令在當前 shell 可用
source ~/.bashrc

# 設定預設 CA 為 Let's Encrypt
~/.acme.sh/acme.sh --set-default-ca --server letsencrypt

B-3：簽發憑證

# 設定 Cloudflare API 認證
export CF_Token="你的_Cloudflare_API_Token"
export CF_Zone_ID="你的_Zone_ID"

# 簽發萬用字元憑證（含 kubeantony.com 和 *.kubeantony.com）
~/.acme.sh/acme.sh --issue \
 --dns dns_cf \
 -d kubeantony.com \
 -d '*.kubeantony.com'

acme.sh 會自動透過 Cloudflare API 建立 TXT 記錄進行驗證，驗證通過後自動清除 TXT 記錄。整個過程完全不需要 Public IP。

B-4：安裝憑證到 Mail Server 目錄

sudo mkdir -p /opt/zfs/dkmail/conf/ssl

~/.acme.sh/acme.sh --install-cert \
 -d kubeantony.com \
 -d '*.kubeantony.com' \
 --key-file /opt/zfs/dkmail/conf/ssl/kubeantony.com.key \
 --fullchain-file /opt/zfs/dkmail/conf/ssl/fullchain.pem \
 --reloadcmd "podman restart dkmail"

sudo chmod 644 /opt/zfs/dkmail/conf/ssl/fullchain.pem
sudo chmod 600 /opt/zfs/dkmail/conf/ssl/kubeantony.com.key

說明：

--install-cert 會將憑證複製到你指定的路徑

--reloadcmd 會在每次續期後自動重啟容器套用新憑證

acme.sh 會自動建立 cron job，每天檢查是否需要續期（到期前 30 天自動續期）

B-5：確認自動續期 cron

crontab -l
# 應該會看到類似這行：
# 0 0 * * * "/root/.acme.sh"/acme.sh --cron --home "/root/.acme.sh" > /dev/null

完成後，跳至「共通步驟：設定 Mail Server 並啟動容器」。

共通步驟：設定 Mail Server 並啟動容器

以下步驟不論方案 A 或方案 B 都相同。此時你的 /opt/zfs/dkmail/conf/ssl/ 應該已有：

/opt/zfs/dkmail/conf/ssl/
├── fullchain.pem # 完整憑證鏈
└── kubeantony.com.key # 私鑰

C-1：設定 Postfix（SMTP TLS）

sudo tee /opt/zfs/dkmail/conf/postfix-main.cf << 'EOF'
# TLS 設定
smtpd_tls_cert_file = /etc/ssl/mail/fullchain.pem
smtpd_tls_key_file = /etc/ssl/mail/kubeantony.com.key
smtpd_tls_security_level = may
smtpd_tls_protocols = !SSLv2,!SSLv3,!TLSv1,!TLSv1.1
smtpd_tls_mandatory_protocols = !SSLv2,!SSLv3,!TLSv1,!TLSv1.1
smtpd_tls_mandatory_ciphers = medium

# 寄出郵件也啟用 TLS
smtp_tls_security_level = may
smtp_tls_protocols = !SSLv2,!SSLv3,!TLSv1,!TLSv1.1
EOF

C-2：設定 Dovecot（IMAP/POP3 TLS）

sudo mkdir -p /opt/zfs/dkmail/conf/dovecot

sudo tee /opt/zfs/dkmail/conf/dovecot/10-ssl.conf << 'EOF'
ssl = required
ssl_cert = </etc/ssl/mail/fullchain.pem
ssl_key = </etc/ssl/mail/kubeantony.com.key
ssl_min_protocol = TLSv1.2
ssl_prefer_server_ciphers = yes
EOF

注意： Dovecot 設定中 < 是必要語法，代表「讀取此檔案內容」，不是打字錯誤。

C-3：停止舊容器並重新啟動

sudo podman stop dkmail
sudo podman rm dkmail

sudo podman run --name dkmail -itd \
 -h mx1.kubeantony.com --network=host \
 -e NETWORK_INTERFACE=ens18 \
 -e SSL_TYPE=manual \
 -e SSL_CERT_PATH=/etc/ssl/mail/fullchain.pem \
 -e SSL_KEY_PATH=/etc/ssl/mail/kubeantony.com.key \
 --dns 192.168.11.253 --dns-search kubeantony.com \
 -v /opt/zfs/dkmail/data:/var/mail \
 -v /opt/zfs/dkmail/conf/postfix-main.cf:/tmp/docker-mailserver/postfix-main.cf:ro \
 -v /opt/zfs/dkmail/conf/rspamd:/tmp/docker-mailserver/rspamd \
 -v /opt/zfs/dkmail/conf/ssl:/etc/ssl/mail:ro \
 -v /opt/zfs/dkmail/conf/dovecot/10-ssl.conf:/etc/dovecot/conf.d/10-ssl.conf:ro \
 dkmail.rspamd

與你原始指令相比新增的項目：

新增項目	說明
`-e SSL_TYPE=manual`	告訴 docker-mailserver 使用手動指定的憑證
`-e SSL_CERT_PATH=...`	容器內憑證路徑
`-e SSL_KEY_PATH=...`	容器內私鑰路徑
`-v .../ssl:/etc/ssl/mail:ro`	掛載憑證目錄
`-v .../10-ssl.conf:...`	覆蓋 Dovecot SSL 設定

C-4：Rspamd Web UI 的 TLS（選用，透過 Nginx 反向代理）

Rspamd Web UI 本身不支援 TLS，需要用 Nginx 做反向代理：

sudo apt install -y nginx
sudo mkdir -p /etc/nginx/ssl
sudo cp /opt/zfs/dkmail/conf/ssl/fullchain.pem /etc/nginx/ssl/
sudo cp /opt/zfs/dkmail/conf/ssl/kubeantony.com.key /etc/nginx/ssl/

sudo tee /etc/nginx/sites-available/rspamd << 'EOF'
server {
 listen 443 ssl;
 server_name mx1.kubeantony.com;

 ssl_certificate /etc/nginx/ssl/fullchain.pem;
 ssl_certificate_key /etc/nginx/ssl/kubeantony.com.key;
 ssl_protocols TLSv1.2 TLSv1.3;

 location / {
 proxy_pass http://127.0.0.1:11334;
 proxy_set_header Host $host;
 proxy_set_header X-Real-IP $remote_addr;
 proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
 proxy_set_header X-Forwarded-Proto $scheme;
 }
}
EOF

sudo ln -s /etc/nginx/sites-available/rspamd /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl restart nginx

驗證 TLS 是否生效

# SMTP STARTTLS（Port 587）
openssl s_client -connect mx1.kubeantony.com:587 -starttls smtp

# SMTPS（Port 465）
openssl s_client -connect mx1.kubeantony.com:465

# IMAPS（Port 993）
openssl s_client -connect mx1.kubeantony.com:993

# POP3S（Port 995）
openssl s_client -connect mx1.kubeantony.com:995

正常輸出應包含：

方案 A（自簽）：issuer: CN = kubeantony Root CA，Verify return code: 21 — 這是正常的
方案 B（Let’s Encrypt）：issuer: C = US, O = Let's Encrypt，Verify return code: 0 (ok)

完整目錄結構

/opt/zfs/dkmail/
├── data/ # 郵件資料（/var/mail）
└── conf/
├── postfix-main.cf # Postfix TLS 設定
├── ssl/
│ ├── fullchain.pem # 完整憑證鏈
│ └── kubeantony.com.key # 私鑰
├── dovecot/
│ └── 10-ssl.conf # Dovecot SSL 設定
└── rspamd/
└── override.d/
├── options.inc
├── worker-controller.inc
└── hfilter.conf

RKE2 & Rancher Prime Installation

Tue, 31 Mar 2026 04:15:32 +0800

Preface

本篇文章會主要會介紹，如何安裝 Rancher Kubernetes Engine 2 或 K3S，並在 Kubernetes 之中部署 Rancher Prime

可以透過點擊以下目錄，選擇想看的內容，跳轉至特定章節

Install RKE2 v1.34.4

一、安裝前環境檢查

請確保你的環境符合要求
- RKE2 Requirements
- 如果你的主機上安裝並啟用了 NetworkManager，確保它被配置為忽略 CNI 管理的接口。
對於 1.21 及以上版本的 RKE2，如果主機核心支持 AppArmor，那麼在安裝 RKE2 之前還必須有 AppArmor 工具（通常通過 apparmor-parser 軟件包獲得）。
RKE2 的安裝過程必須以 root 用戶或通過 sudo 運行。

Hardware

Linux/Windows

RAM: 4GB Minimum (we recommend at least 8GB)
CPU: 2 Minimum (we recommend at least 4CPU)
Disks: SSD

RKE2 Hardware

二、Server Node Installation

1. Config RKE2 Basic Parameters

1-1. 下載 RKE2 的安裝腳本，並賦予執行權限

在 Server node 的機器上執行以下命令

curl -sfL https://get.rke2.io --output install.sh && chmod +x install.sh

RKE2 提供了一個安裝腳本，在 systemd 的系統上將其作為一個服務來安裝。

1-2. 編輯 Server Node 設定檔

advertise-address, node-ip 和 tls-san 的 IP 需要依據不同的環境來設定。

# 定義 K8s 要跑在哪張網卡上(以下指令預設會去找 default gateway 的網卡)
NIC="$(ip route show default | cut -d' ' -f5)"
IP=$(ip -4 -o addr show ${NIC} | awk '{print $4}' | cut -d/ -f1)
# 定義節點名稱
NODE_NAME="$(hostname -f 2>/dev/null)"
NODE_NAME="${NODE_NAME:-$(hostname)}"

sudo mkdir -p /etc/rancher/rke2/ && \
cat <<EOF | sudo tee /etc/rancher/rke2/config.yaml
write-kubeconfig-mode: "0644"
debug: false
# =============================================
# 每台節點不同的設定
# =============================================
# 本機對外廣播的 IP（其他節點透過此 IP 連線）
advertise-address: "${IP}"
# 本機 IP
node-ip: "${IP}"
# 節點名稱（每台不同）
node-name: "${NODE_NAME}"
# TLS 憑證允許的 SAN（第一台 server 需完整設定）
tls-san:
- "${NODE_NAME}"
- "${IP}"
- "127.0.0.1"
# 第二台以後需加入此行，指向第一台 server（第一台不需要）
# server: "https://<第一台IP>:9345"
# =============================================
# 所有 Server Node 必須相同的設定
# =============================================
# 叢集加入金鑰
token: "hehe"
# 各元件時區設定
etcd-extra-env:
- "TZ=Asia/Taipei"
kube-apiserver-extra-env:
- "TZ=Asia/Taipei"
kube-controller-manager-extra-env:
- "TZ=Asia/Taipei"
kube-scheduler-extra-env:
- "TZ=Asia/Taipei"
cloud-controller-manager-extra-env:
- "TZ=Asia/Taipei"
# kubelet 參數
kubelet-arg:
- "container-log-max-files=5" # 最多保留 5 個 log 檔
- "container-log-max-size=10Mi" # 每個 log 檔最大 10Mi
- "config=/etc/kubernetes/kubeletconfig.yml"
- "eviction-hard=memory.available<1000Mi,imagefs.available<5%,nodefs.available<5%" # 資源不足時驅逐 Pod 的閾值
# 停用內建 cloud controller
disable-cloud-controller: true
# 停用 kube-proxy，改由 Cilium 接管
disable-kube-proxy: true
# 停用不需要的內建元件
disable:
- rke2-canal # 停用預設 CNI Canal
- rke2-kube-proxy # 停用內建 kube-proxy
# 使用 Cilium 作為 CNI
cni:
- "cilium"
# 啟用 CIS security profile
#profile: "cis"
# API Server 額外參數
#kube-apiserver-arg:
# - "service-account-extend-token-expiration=false"
EOF

1-3. 編輯 cilium 設定檔

sudo mkdir -p /var/lib/rancher/rke2/server/manifests && \
cat <<EOF | sudo tee /var/lib/rancher/rke2/server/manifests/rke2-cilium-config.yaml
apiVersion: helm.cattle.io/v1
kind: HelmChartConfig
metadata:
name: rke2-cilium
namespace: kube-system
spec:
valuesContent: |-
operator:
replicas: 1
podAnnotations:
container.apparmor.security.beta.kubernetes.io/cilium-agent: "unconfined"
container.apparmor.security.beta.kubernetes.io/clean-cilium-state: "unconfined"
container.apparmor.security.beta.kubernetes.io/mount-cgroup: "unconfined"
container.apparmor.security.beta.kubernetes.io/apply-sysctl-overwrites: "unconfined"
devices: "$NIC"
nodePort:
directRoutingDevice: "$NIC"
autoDirectNodeRoutes: true
hubble:
enabled: false
relay:
enabled: false
ui:
enabled: false
frontend:
server:
ipv6:
enabled: false
service:
type: NodePort
enableLBIPAM: false
ipv4NativeRoutingCIDR: 10.42.0.0/16
k8sServiceHost: 127.0.0.1
k8sServicePort: 6443
kubeProxyReplacement: true
routingMode: native
l2announcements:
enabled: true
EOF

1-4. 編輯 kubelet 設定檔

sudo mkdir -p /etc/kubernetes && \
cat <<EOF | sudo tee /etc/kubernetes/kubeletconfig.yml
apiVersion: kubelet.config.k8s.io/v1beta1
kind: KubeletConfiguration
systemReserved:
memory: "1Gi"
kubeReserved:
memory: "2Gi"
EOF

evictionHard：
- 用途：設定強制驅逐的值，當系統資源（如記憶體）低於此設定值時，kubelet 會立即終止部分 Pod，以釋放資源，確保系統穩定運行。
- 預設值: 預設打開，Memory 是 100MiB, Ephemeral-Storage 是 10% (開源的 K8s), rke2 預設值是 imagefs 和 nodefs = 5%
- 範例：memory.available: "500Mi" 表示當可用記憶體少於 500MiB 時，kubelet 會觸發驅逐機制。
evictionMinimumReclaim：
- 用途：設定在驅逐 Pod 時，kubelet 希望至少回收的資源量。這有助於避免頻繁的驅逐操作，確保每次驅逐能有效釋放足夠的資源。
- 範例：memory.available: "10Mi" 表示每次驅逐操作至少要回收 10MiB 的記憶體。
systemReserved：
- 用途：為系統背景程序（如 sshd、networking 等非 Kubernetes 組件）預留資源，確保這些系統服務在資源緊張時仍能正常運行。
- 範例：memory: "1Gi" 表示為系統服務預留 1GiB 的記憶體。
kubeReserved：
- 用途：為 Kubernetes 系統的背景程序（如 kubelet、container runtime 時等）預留資源，確保這些組件在資源緊張時的穩定性。
- 範例：memory: "2Gi" 表示為 Kubernetes 系統的背景程序預留 2GiB 的記憶體。

2. Install RKE2 with v1.34.4 version

2-1. 執行以下安裝命令

sudo INSTALL_RKE2_CHANNEL=v1.34.4+rke2r1 ./install.sh

INSTALL_RKE2_CHANNEL

指定要下載 RKE2 URL 的 Channel，預設是 latest

[INFO] finding release for channel v1.34.4+rke2r1
[INFO] using v1.34.4+rke2r1 as release
[INFO] downloading checksums at https://github.com/rancher/rke2/releases/download/v1.34.4%2Brke2r1/sha256sum-amd64.txt
[INFO] downloading tarball at https://github.com/rancher/rke2/releases/download/v1.34.4%2Brke2r1/rke2.linux-amd64.tar.gz
[INFO] verifying tarball
[INFO] unpacking tarball file to /usr/local

3. enable rke2 and setup kubeconfig

3-1. 將 rke2-server 的服務設為開機自動啟動，並立即啟動服務

sudo systemctl enable rke2-server --now

以上命令執行後的螢幕輸出

Created symlink /etc/systemd/system/multi-user.target.wants/rke2-server.service → /etc/systemd/system/rke2-server.service.

3-2. Setup kubeconfig and crictl

{
# 1. 建立目錄並設定 Kubeconfig
mkdir -p $HOME/.kube && \
sudo cp /etc/rancher/rke2/rke2.yaml $HOME/.kube/config && \
sudo chown $(id -u):$(id -g) $HOME/.kube/config && \
# 2. 搬移執行檔
sudo cp /var/lib/rancher/rke2/bin/* /usr/local/bin/ && \
# 3. 寫入 crictl 設定 (使用 printf 保持單行邏輯)
printf "runtime-endpoint: unix:///run/k3s/containerd/containerd.sock\nimage-endpoint: unix:///run/k3s/containerd/containerd.sock\ntimeout: 10\n" | sudo tee /etc/crictl.yaml > /dev/null && \
# 4. 設定 Bash Alias 與補全
printf "\nsource <(kubectl completion bash)\nalias k=kubectl\ncomplete -o default -F __start_kubectl k\n" >> ~/.bashrc && \
# 5. 立即生效
source ~/.bashrc
}

4. check pod status

kubectl get po -A

螢幕輸出 :

NAMESPACE NAME READY STATUS RESTARTS AGE
kube-system cilium-j7jf2 1/1 Running 0 2m12s
kube-system cilium-operator-6fb6d5b896-jj2nx 1/1 Running 0 2m12s
kube-system etcd-rms-1.kubeantony.com 1/1 Running 0 2m31s
kube-system helm-install-rke2-cilium-qhdsl 0/1 Completed 0 2m24s
kube-system helm-install-rke2-coredns-hwsqp 0/1 Completed 0 2m24s
kube-system helm-install-rke2-ingress-nginx-bxt7n 0/1 Completed 0 2m24s
kube-system helm-install-rke2-metrics-server-qln6s 0/1 Completed 0 2m24s
kube-system helm-install-rke2-runtimeclasses-5kj6v 0/1 Completed 0 2m23s
kube-system helm-install-rke2-snapshot-controller-crd-vsbjv 0/1 Completed 0 2m23s
kube-system helm-install-rke2-snapshot-controller-z9kfv 0/1 Completed 1 2m23s
kube-system kube-apiserver-rms-1.kubeantony.com 1/1 Running 0 2m31s
kube-system kube-controller-manager-rms-1.kubeantony.com 1/1 Running 0 2m31s
kube-system kube-scheduler-rms-1.kubeantony.com 1/1 Running 0 2m31s
kube-system rke2-coredns-rke2-coredns-77f54456d4-kqbtc 1/1 Running 0 2m12s
kube-system rke2-coredns-rke2-coredns-autoscaler-6c58bf4677-wj7gp 1/1 Running 0 2m12s
kube-system rke2-ingress-nginx-controller-bhf7h 1/1 Running 0 62s
kube-system rke2-metrics-server-69f4f95bf7-tb6rc 1/1 Running 0 76s
kube-system rke2-snapshot-controller-bc4c494bf-cqj7t 1/1 Running 0 76s

三、Join Additional Server Nodes

1. Config RKE2 Basic Parameters

1-1. 下載 RKE2 的安裝腳本，並賦予執行權限

以下命令請在 Additional Server node 上執行

curl -sfL https://get.rke2.io --output install.sh && chmod +x install.sh

RKE2 提供了一個安裝腳本，在 systemd 的系統上將其作為一個服務來安裝。

1-2. 編輯 RKE2 Additional Server Node 設定檔

# 定義 K8s 要跑在哪張網卡上(以下指令預設會去找 default gateway 的網卡)
NIC="$(ip route show default | cut -d' ' -f5)"
IP=$(ip -4 -o addr show ${NIC} | awk '{print $4}' | cut -d/ -f1)
# 定義節點名稱
NODE_NAME="$(hostname -f 2>/dev/null)"
NODE_NAME="${NODE_NAME:-$(hostname)}"
# 定義第一台 Control-plane node 的 ip
ServerIP="192.168.11.161"

sudo mkdir -p /etc/rancher/rke2/ && \
cat <<EOF | sudo tee /etc/rancher/rke2/config.yaml
write-kubeconfig-mode: "0644"
debug: false
# =============================================
# 每台節點不同的設定
# =============================================
# 本機對外廣播的 IP（其他節點透過此 IP 連線）
advertise-address: "${IP}"
# 本機 IP
node-ip: "${IP}"
# 節點名稱（每台不同）
node-name: "${NODE_NAME}"
# TLS 憑證允許的 SAN（第一台 server 需完整設定）
tls-san:
- "${NODE_NAME}"
- "${IP}"
- "127.0.0.1"
# 第二台以後需加入此行，指向第一台 server（第一台不需要）
server: "https://${ServerIP}:9345"
# =============================================
# 所有 Server Node 必須相同的設定
# =============================================
# 叢集加入金鑰
token: "hehe"
# 各元件時區設定
etcd-extra-env:
- "TZ=Asia/Taipei"
kube-apiserver-extra-env:
- "TZ=Asia/Taipei"
kube-controller-manager-extra-env:
- "TZ=Asia/Taipei"
kube-scheduler-extra-env:
- "TZ=Asia/Taipei"
cloud-controller-manager-extra-env:
- "TZ=Asia/Taipei"
# kubelet 參數
kubelet-arg:
- "container-log-max-files=5" # 最多保留 5 個 log 檔
- "container-log-max-size=10Mi" # 每個 log 檔最大 10Mi
- "config=/etc/kubernetes/kubeletconfig.yml"
- "eviction-hard=memory.available<1000Mi,imagefs.available<5%,nodefs.available<5%" # 資源不足時驅逐 Pod 的閾值
# 停用內建 cloud controller
disable-cloud-controller: true
# 停用 kube-proxy，改由 Cilium 接管
disable-kube-proxy: true
# 停用不需要的內建元件
disable:
- rke2-canal # 停用預設 CNI Canal
- rke2-kube-proxy # 停用內建 kube-proxy
# 使用 Cilium 作為 CNI
cni:
- "cilium"
# 啟用 CIS security profile
#profile: "cis"
# API Server 額外參數
#kube-apiserver-arg:
# - "service-account-extend-token-expiration=false"
EOF

Note: 要指定第一台 RKE2 Server node 的 IP

1-3. 編輯 kubelet 設定檔

sudo mkdir -p /etc/kubernetes && \
cat <<EOF | sudo tee /etc/kubernetes/kubeletconfig.yml
apiVersion: kubelet.config.k8s.io/v1beta1
kind: KubeletConfiguration
systemReserved:
memory: "1Gi"
kubeReserved:
memory: "2Gi"
EOF

2. Install RKE2 with v1.34.4 veersion

2-1. 執行以下安裝命令

sudo INSTALL_RKE2_CHANNEL=v1.34.4+rke2r1 ./install.sh

INSTALL_RKE2_CHANNEL

指定要下載 RKE2 URL 的 Channel，預設是 latest

[WARN] /usr/local is read-only or a mount point; installing to /opt/rke2
[INFO] finding release for channel v1.23.9+rke2r1
[INFO] using v1.23.9+rke2r1 as release
[INFO] downloading checksums at https://github.com/rancher/rke2/releases/download/v1.23.9+rke2r1/sha256sum-amd64.txt
[INFO] downloading tarball at https://github.com/rancher/rke2/releases/download/v1.23.9+rke2r1/rke2.linux-amd64.tar.gz
[INFO] verifying tarball
[INFO] unpacking tarball file to /opt/rke2
[INFO] updating tarball contents to reflect install path
[INFO] moving systemd units to /etc/systemd/system
[INFO] install complete; you may want to run: export PATH=$PATH:/opt/rke2/bin

3. enable rke2 and setup kubeconfig

3-1. 將 rke2-server 的服務設為開機自動啟動，並立即啟動服務

sudo systemctl enable rke2-server --now

以上命令執行後的螢幕輸出

Created symlink /etc/systemd/system/multi-user.target.wants/rke2-server.service → /etc/systemd/system/rke2-server.service.

4. check pod status

kubectl get po -A

螢幕輸出 :

NAMESPACE NAME READY STATUS RESTARTS AGE
kube-system cilium-79sx5 1/1 Running 0 2m35s
kube-system cilium-j7jf2 1/1 Running 0 19m
kube-system cilium-operator-6fb6d5b896-jj2nx 1/1 Running 0 19m
kube-system etcd-rms-1.kubeantony.com 1/1 Running 0 19m
kube-system etcd-rms-2.kubeantony.com 1/1 Running 0 2m35s
kube-system helm-install-rke2-cilium-qhdsl 0/1 Completed 0 19m
kube-system helm-install-rke2-coredns-hwsqp 0/1 Completed 0 19m
kube-system helm-install-rke2-ingress-nginx-bxt7n 0/1 Completed 0 19m
kube-system helm-install-rke2-metrics-server-qln6s 0/1 Completed 0 19m
kube-system helm-install-rke2-runtimeclasses-5kj6v 0/1 Completed 0 19m
kube-system helm-install-rke2-snapshot-controller-crd-vsbjv 0/1 Completed 0 19m
kube-system helm-install-rke2-snapshot-controller-z9kfv 0/1 Completed 1 19m
kube-system kube-apiserver-rms-1.kubeantony.com 1/1 Running 0 19m
kube-system kube-apiserver-rms-2.kubeantony.com 1/1 Running 0 2m35s
kube-system kube-controller-manager-rms-1.kubeantony.com 1/1 Running 0 19m
kube-system kube-controller-manager-rms-2.kubeantony.com 1/1 Running 0 2m34s
kube-system kube-scheduler-rms-1.kubeantony.com 1/1 Running 0 19m
kube-system kube-scheduler-rms-2.kubeantony.com 1/1 Running 0 2m34s
kube-system rke2-coredns-rke2-coredns-77f54456d4-4n5k5 1/1 Running 0 82s
kube-system rke2-coredns-rke2-coredns-77f54456d4-kqbtc 1/1 Running 0 19m
kube-system rke2-coredns-rke2-coredns-autoscaler-6c58bf4677-wj7gp 1/1 Running 0 19m
kube-system rke2-ingress-nginx-controller-bhf7h 1/1 Running 0 18m
kube-system rke2-ingress-nginx-controller-vhmtb 1/1 Running 0 85s
kube-system rke2-metrics-server-69f4f95bf7-tb6rc 1/1 Running 0 18m
kube-system rke2-snapshot-controller-bc4c494bf-cqj7t 1/1 Running 0 18m

四、Join Agent Nodes

1. Config RKE2 Basic Parameters

1-1. 下載 RKE2 的安裝腳本，並賦予執行權限

以下命令請在 agent node 上執行

~> curl -sfL https://get.rke2.io --output install.sh && chmod +x install.sh

RKE2 提供了一個安裝腳本，在 systemd 的系統上將其作為一個服務來安裝。

1-2. 編輯 RKE2 Additional Server Node 設定檔

# 定義 K8s 要跑在哪張網卡上
$ NIC='eth1'
$ IP=$(ip -4 -o addr show ${NIC} | awk '{print $4}' | cut -d/ -f1)
# 定義 API Server 的 IP 位址
$ ServerIP='192.168.11.35'
# 定義節點名稱
$ NODE_NAME='w1'

~> sudo mkdir -p /etc/rancher/rke2/ && \
cat <<EOF | sudo tee /etc/rancher/rke2/config.yaml
server: https://${ServerIP}:9345
write-kubeconfig-mode: "0644"
debug: False
node-ip: "${IP}"
node-name:
- "${NODE_NAME}"
token: "hehe"
etcd-extra-env: TZ=Asia/Taipei
kube-apiserver-extra-env: TZ=Asia/Taipei
kube-controller-manager-extra-env: TZ=Asia/Taipei
kube-proxy-extra-env: TZ=Asia/Taipei
kube-scheduler-extra-env: TZ=Asia/Taipei
cloud-controller-manager-extra-env: TZ=Asia/Taipei
kubelet-arg:
- container-log-max-files=5
- container-log-max-size=10Mi
- "--config=/etc/kubernetes/kubeletconfig.yml"
- "--eviction-hard=memory.available<1000Mi,imagefs.available<5%,nodefs.available<5%"
#selinux: false
EOF

Note: 要指定第一台 RKE2 Server node 的 IP

1-3. 編輯 kubelet 設定檔

~> sudo mkdir -p /etc/kubernetes && \
cat <<EOF | sudo tee /etc/kubernetes/kubeletconfig.yml
apiVersion: kubelet.config.k8s.io/v1beta1
kind: KubeletConfiguration
systemReserved:
memory: "1Gi"
kubeReserved:
memory: "2Gi"
EOF

2. Install RKE2 with 1.31.2 veersion

2-1. 執行以下安裝命令

~> sudo INSTALL_RKE2_TYPE="agent" INSTALL_RKE2_CHANNEL=v1.31.2+rke2r1 ./install.sh

INSTALL_RKE2_CHANNEL

指定要下載 RKE2 URL 的 Channel，預設是 latest

[INFO] finding release for channel v1.34.4+rke2r1
[INFO] using v1.34.4+rke2r1 as release
[INFO] downloading checksums at https://github.com/rancher/rke2/releases/download/v1.34.4%2Brke2r1/sha256sum-amd64.txt
[INFO] downloading tarball at https://github.com/rancher/rke2/releases/download/v1.34.4%2Brke2r1/rke2.linux-amd64.tar.gz
[INFO] verifying tarball
[INFO] unpacking tarball file to /usr/local

3. enable rke2

3-1. 將 rke2-agent 的服務設為開機自動啟動，並立即啟動服務

~> sudo systemctl enable rke2-agent --now

以上命令執行後的螢幕輸出

Created symlink /etc/systemd/system/multi-user.target.wants/rke2-server.service → /etc/systemd/system/rke2-server.service.

4. check pod status

以下命令在第一台 RKE2 Server 執行

~> kubectl get nodes,po -A

螢幕輸出 :

NAME STATUS ROLES AGE VERSION
node/m1 Ready control-plane,etcd,master 4h32m v1.31.1+rke2r1
node/m2 Ready control-plane,etcd,master 18m v1.31.1+rke2r1
node/m3 Ready control-plane,etcd,master 12m v1.31.1+rke2r1
node/w1 Ready <none> 84s v1.31.1+rke2r1
NAMESPACE NAME READY STATUS RESTARTS AGE
kube-system pod/cilium-2w97z 1/1 Running 0 84s
kube-system pod/cilium-b744m 1/1 Running 0 12m
kube-system pod/cilium-operator-84b8ff5b6c-stfdw 1/1 Running 4 (162m ago) 4h25m
kube-system pod/cilium-p45b4 1/1 Running 1 (162m ago) 4h
kube-system pod/cilium-qvqps 1/1 Running 0 18m
kube-system pod/etcd-m1 1/1 Running 1 4h32m
kube-system pod/etcd-m2 1/1 Running 0 18m
kube-system pod/etcd-m3 1/1 Running 0 11m
kube-system pod/helm-install-rke2-cilium-z7qsz 0/1 Completed 0 4h25m
kube-system pod/helm-install-rke2-coredns-9cg6t 0/1 Completed 0 4h32m
kube-system pod/helm-install-rke2-ingress-nginx-fscw4 0/1 Completed 0 4h32m
kube-system pod/helm-install-rke2-metrics-server-gw8qc 0/1 Completed 0 4h32m
kube-system pod/helm-install-rke2-multus-j8h9d 0/1 Completed 0 4h32m
kube-system pod/helm-install-rke2-snapshot-controller-crd-h58vl 0/1 Completed 0 4h32m
kube-system pod/helm-install-rke2-snapshot-controller-v6lwh 0/1 Completed 1 4h32m
kube-system pod/helm-install-rke2-snapshot-validation-webhook-gz77q 0/1 Completed 0 4h32m
kube-system pod/kube-apiserver-m1 1/1 Running 2 3h41m
kube-system pod/kube-apiserver-m2 1/1 Running 0 18m
kube-system pod/kube-apiserver-m3 1/1 Running 0 12m
kube-system pod/kube-controller-manager-m1 1/1 Running 10 (162m ago) 4h32m
kube-system pod/kube-controller-manager-m2 1/1 Running 0 18m
kube-system pod/kube-controller-manager-m3 1/1 Running 0 12m
kube-system pod/kube-scheduler-m1 1/1 Running 2 (162m ago) 4h32m
kube-system pod/kube-scheduler-m2 1/1 Running 0 18m
kube-system pod/kube-scheduler-m3 1/1 Running 0 12m
kube-system pod/rke2-coredns-rke2-coredns-79f8cbfcf7-9rh2l 1/1 Running 0 18m
kube-system pod/rke2-coredns-rke2-coredns-79f8cbfcf7-bwvtc 1/1 Running 0 161m
kube-system pod/rke2-coredns-rke2-coredns-autoscaler-7cf7db4bdc-t8ff7 1/1 Running 1 (162m ago) 4h
kube-system pod/rke2-ingress-nginx-controller-4hns2 1/1 Running 0 48s
kube-system pod/rke2-ingress-nginx-controller-7c5bp 1/1 Running 0 11m
kube-system pod/rke2-ingress-nginx-controller-8qrjf 1/1 Running 0 18m
kube-system pod/rke2-ingress-nginx-controller-rwpdf 1/1 Running 1 (162m ago) 3h40m
kube-system pod/rke2-metrics-server-6d887864c-vdkgn 0/1 Completed 0 4h25m
kube-system pod/rke2-metrics-server-6d887864c-vdt5s 1/1 Running 1 (162m ago) 4h
kube-system pod/rke2-multus-6vcp7 1/1 Running 3 (50s ago) 84s
kube-system pod/rke2-multus-bxdkm 1/1 Running 2 (11m ago) 12m
kube-system pod/rke2-multus-hfqc6 1/1 Running 1 (162m ago) 4h
kube-system pod/rke2-multus-t7vln 1/1 Running 2 (18m ago) 18m
kube-system pod/rke2-snapshot-controller-658d97fccc-7gkrv 1/1 Running 7 (162m ago) 4h25m
kube-system pod/rke2-snapshot-validation-webhook-784bcc6c8-xfq68 1/1 Running 1 (162m ago) 4h25m

Install K3S v1.26.9

安裝命令

$ curl -sfL https://get.k3s.io/ | INSTALL_K3S_VERSION=v1.26.9+k3s1 K3S_KUBECONFIG_MODE="644" sh -

設定 kubeconfig

$ mkdir -p $HOME/.kube && sudo cp /etc/rancher/k3s/k3s.yaml $HOME/.kube/config && sudo chown $(id -u):$(id -g) $HOME/.kube/config && sudo chmod 600 $HOME/.kube/config

Helm Install Rancher Prime v2.13.2

1. Add the Helm Chart Repository

1.1 Install helm3

在第一台 Master Node 上執行以下命令

下載 helm 壓縮檔

wget https://get.helm.sh/helm-v3.8.2-linux-amd64.tar.gz

螢幕輸出

--2022-09-21 09:06:57-- https://get.helm.sh/helm-v3.8.2-linux-amd64.tar.gz
Resolving get.helm.sh (get.helm.sh)... 152.199.39.108, 2606:2800:247:1cb7:261b:1f9c:2074:3c
Connecting to get.helm.sh (get.helm.sh)|152.199.39.108|:443... connected.
HTTP request sent, awaiting response... 200 OK
Length: 13633605 (13M) [application/x-tar]
Saving to: ‘helm-v3.8.2-linux-amd64.tar.gz’
helm-v3.8.2-linux-amd64.tar.gz 100%[=============================================================>] 13.00M 5.95MB/s in 2.2s
2022-09-21 09:07:00 (5.95 MB/s) - ‘helm-v3.8.2-linux-amd64.tar.gz’ saved [13633605/13633605]

解壓縮 helm 壓縮檔

tar zxvf helm-v3.8.2-linux-amd64.tar.gz

螢幕輸出

linux-amd64/
linux-amd64/helm
linux-amd64/LICENSE
linux-amd64/README.md

將 helm 執行檔拷貝至 PATH 環境變數中的 /usr/local/bin/ 目錄下

sudo cp linux-amd64/helm /usr/local/bin/

curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash

1.2 Add the Helm Chart Repository

Prime: Recommended for production environments

helm repo add rancher-prime https://charts.rancher.com/server-charts/prime

helm repo add rancher-latest https://releases.rancher.com/server-charts/latest

helm repo add rancher-stable https://releases.rancher.com/server-charts/stable

2. Create a Namespace for Rancher

This should always be cattle-system

kubectl create ns cattle-system

3. Choose your SSL Configuration

mkdir ssl;cd ssl

下載產生自簽憑證腳本，並賦予執行權限

wget https://raw.githubusercontent.com/cooloo9871/openssl/master/mk && \
chmod +x mk

執行腳本產生自簽憑證

./mk create rancher.example.com 192.168.11.60

第一個參數放 rancher 的 Domain Name 第二個參數放 LB 的 IP (HA Rancher)，或是 rancher 本身的 IP

螢幕輸出

Generating RSA private key, 4096 bit long modulus (2 primes)
.........................................................................................................................................................................................................................++++
....................................................................................................................................................................................................................................................++++
e is 65537 (0x010001)
Generating RSA private key, 4096 bit long modulus (2 primes)
..........................................................++++
..++++
e is 65537 (0x010001)
Signature ok
subject=CN = example
Getting CA Private Key

檢查是否符合預期

ls -l
total 32
-rw------- 1 rancher users 3326 Feb 13 13:58 ca-key.pem
-rw-r--r-- 1 rancher users 2009 Feb 13 13:58 ca.pem
-rw-r--r-- 1 rancher users 41 Feb 13 13:58 ca.srl
-rw-r--r-- 1 rancher users 1582 Feb 13 13:58 cert.csr
-rw------- 1 rancher users 3243 Feb 13 13:58 cert-key.pem
-rw-r--r-- 1 rancher users 1874 Feb 13 13:58 cert.pem
-rw-r--r-- 1 rancher users 86 Feb 13 13:58 extfile.cnf
-rwxr-xr-x 1 rancher users 1166 Feb 13 13:57 mk

Create the certificate secret resource

將伺服器憑證和任何中間證書串聯到一個名為 tls.crt 的檔案中，並在一個名為 tls.key 的檔案中提供相應的證書密鑰。

kubectl -n cattle-system create secret tls tls-rancher-ingress \
--cert=cert.pem \
--key=cert-key.pem
kubectl -n cattle-system create secret generic tls-ca --from-file=cacerts.pem=./cert.pem
kubectl -n cattle-system get secret
NAME TYPE DATA AGE
default-token-h9lwm kubernetes.io/service-account-token 3 2m15s
tls-ca Opaque 1 13s
tls-rancher-ingress kubernetes.io/tls 2 52s

把 ca.pem 複製到 rancher 託管的每座 Downstream cluster 中的每台 Node 上

之後使用 Rancher 註冊就不需要再勾選 insecure 了

scp ca.pem rancher@<client>:~
# ssh 到 client 上
sudo cp ca.pem /etc/pki/trust/anchors/
sudo cp ca.pem /usr/share/pki/trust/anchors/
sudo update-ca-certificates

Install from the cert-manager release manifest

kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.20.0/cert-manager.yaml

Check cert-manager pod status

kubectl -n cert-manager get pods

螢幕輸出 :

NAME READY STATUS RESTARTS AGE
cert-manager-7b8b89f89d-9tsmq 1/1 Running 0 43s
cert-manager-cainjector-7f9fdd5dd5-mqspq 1/1 Running 0 43s
cert-manager-webhook-769f6b94cb-vmwm2 1/1 Running 0 43s

4. Install Rancher Prime with Helm and Your Chosen Certificate Option

建立 Rancher Prime 並且使用自簽憑證

helm install rancher rancher-prime/rancher \
--namespace cattle-system \
--version=2.13.2 \
--set bootstrapPassword=rancheradmin \
--set hostname=rancher.example.com \
--set replicas=3 \
--set ingress.tls.source=secret \
--set privateCA=true
--set global.cattle.psp.enabled=false

建立 Rancher Prime 並且使用 Cert-manager 產生憑證

helm install rancher rancher-prime/rancher \
--namespace cattle-system \
--set hostname=ha-rancher.kubeantony.com \
--set bootstrapPassword=rancheradmin \
--set global.cattle.psp.enabled=false \
--set replicas=3 \
--version 2.13.2

5. Verify that the Rancher Server is Successfully Deployed

kubectl -n cattle-system get po

螢幕輸出 :

NAME READY STATUS RESTARTS AGE
helm-operation-cnlsx 0/2 Completed 0 14m
helm-operation-hfpdh 0/2 Completed 0 15m
helm-operation-llz2m 0/2 Completed 0 15m
helm-operation-pcq4s 0/2 Completed 0 16m
helm-operation-tw5hw 0/2 Completed 0 15m
rancher-647cdd469b-7ctmw 1/1 Running 0 20m
rancher-647cdd469b-l5q7w 1/1 Running 1 (17m ago) 20m
rancher-647cdd469b-mb4rc 1/1 Running 1 (17m ago) 20m
rancher-webhook-fb6768c79-fk9jl 1/1 Running 0 15m

檢查名稱解析

~> curl -k -H "host: rancher.example.com" https://192.168.11.50/dashboard/

匯出 cert-manager 簽的憑證

~> curl -k -s -fL rancher.example.com/v3/settings/cacerts | jq -r .value

將憑證匯入瀏覽器

在 client 的瀏覽器把 ca.pem import 進去 (此方法為自簽憑證時使用)

就可以使用 https 登入 rancher

Rancher 生成 RKE2 之前的必要設定

節點必須能夠透過 DNS 解析 Rancher 的 FQDN，不要透過 /etc/hosts 解析，否則 Rancher 的 Agent ( cattle-cluster-agent ) 會在建立的時候無法存取到 Rancher。
如果想透過 /etc/hosts 去解析 Rancher FQDN 對應的 IP Address 的話，請依照以下步驟設定

編輯 Patch file Yaml 檔

$ cat <<EOF > patch-file-hostalias.yaml
spec:
template:
spec:
hostAliases:
- ip: "192.168.0.11"
hostnames:
- "antony-rancher.example.com"
EOF

hostAliases 輸入 Rancher 所在的主機 IP Address hostnames 輸入 Racher 的 FDQN

Patch cattle-cluster-agent 這個 Deployment

$ kubectl -n cattle-system patch deployment cattle-cluster-agent --patch-file patch-file-hostalias.yaml

檢視 Pods 運作狀態

$ kubectl -n cattle-system get pods -l app=cattle-cluster-agent

螢幕輸出 :

NAME READY STATUS RESTARTS AGE
cattle-cluster-agent-6c54877576-hmtgq 1/1 Running 0 22m
cattle-cluster-agent-6c54877576-zt6mb 1/1 Running 0 22m

請注意，這個方法永遠不要在 Production 環境使用，只能在測試環境使用，因為如果 DownStream Cluster 有被更新，Patch 的設定有可能會被覆蓋

Rancher 生成 RKE2 之後的必要設定

在每一台 Control Plane Node 的設定

{
# 1. 建立目錄並設定 Kubeconfig
mkdir -p $HOME/.kube && \
sudo cp /etc/rancher/rke2/rke2.yaml $HOME/.kube/config && \
sudo chown $(id -u):$(id -g) $HOME/.kube/config && \
# 2. 搬移執行檔
sudo cp /var/lib/rancher/rke2/bin/* /usr/local/bin/ && \
sudo cp /opt/rke2/bin/* /usr/local/bin/ ; \
# 3. 寫入 crictl 設定 (使用 printf 保持單行邏輯)
printf "runtime-endpoint: unix:///run/k3s/containerd/containerd.sock\nimage-endpoint: unix:///run/k3s/containerd/containerd.sock\ntimeout: 10\n" | sudo tee /etc/crictl.yaml > /dev/null && \
# 4. 設定 Bash Alias 與補全
printf "\nsource <(kubectl completion bash)\nalias k=kubectl\ncomplete -o default -F __start_kubectl k\n" >> ~/.bashrc && \
# 5. 立即生效
source ~/.bashrc
}

在每一台 Worker Node 要做的設定

~> sudo cp /opt/rke2/bin/* /usr/local/bin/ && \
sudo cp /var/lib/rancher/rke2/bin/* /usr/local/bin/
# Setup crictl config
~> cat <<EOF | sudo tee /etc/crictl.yaml
runtime-endpoint: unix:///run/k3s/containerd/containerd.sock
image-endpoint: unix:///run/k3s/containerd/containerd.sock
timeout: 10
EOF

Helm upgrade Rancher

Update your local helm repo cache

$ helm repo update

Export the current values to a file:

$ helm get values rancher -n cattle-system -o yaml > values.yaml

Helm 查詢 Rancher 的版本，命令如下 :

$ helm -n cattle-system repo ls
- name: rancher-prime
url: https://charts.rancher.com/server-charts/prime
$ helm search repo rancher-prime --versions
NAME CHART VERSION APP VERSION DESCRIPTION
rancher-prime/rancher 2.8.2 v2.8.2 Install Rancher Server to manage Kubernetes clu...
...

Upgrade Rancher Version

$ helm upgrade rancher rancher-<CHART_REPO>/rancher \
--namespace cattle-system \
-f values.yaml \
--version=2.8.2

RKE2 設定私有 Image Registry

可以透過 Rancher 設定或是手動更改 Containerd 的設定檔，Rancher 做的設定會直接套用到整個叢集的每一台 Node 上，手動設定會需要一台一台 Node 去做設定。

Rancher 設定

更改叢集設定檔

輸入 Image Registry 資訊

Registry Hostname: 10.43.0.11:5000
Mirror Endpoints: http://10.43.0.11:5000

Registry Hostname: 10.43.0.11:5000
TLS Secret: None
Authentication: Create a HTTP Basic Auth Secret
Username: docker
Password: xxx
Skip TLS Verifications

儲存並套用設定至整個叢集

手動設定

注意資訊 :

如果只改一台 Node，那麼就只有該節點能夠到設定的 Image Registry 下載或上傳 Images。
config.toml.tmpl 這個檔案如果被刪掉，那麼假設 RKE2 是被 Rancher 管理的，設定的內容，會被 Rancher 同步回來。反之，如果沒被刪掉，那麼在 Rancher 設定的值將永遠無法被套用，直到 config.toml.tmpl 這個檔案被刪除。

複製一份 Cotainerd 的設定檔

$ sudo cp /var/lib/rancher/rke2/agent/etc/containerd/config.toml /var/lib/rancher/rke2/agent/etc/containerd/config.toml.tmpl

重要: 檔名一定要是 config.toml.tmpl

修改 config.toml.tmpl 檔案內容

$ sudo nano /var/lib/rancher/rke2/agent/etc/containerd/config.toml.tmpl

新增以下內容 :

[plugins."io.containerd.grpc.v1.cri".registry.configs."HARBOR_FQDN".auth]
username = "xxx"
password = "xxx"
[plugins."io.containerd.grpc.v1.cri".registry.configs."HARBOR_FQDN".tls]
insecure_skip_verify = true

如果 Image Registry 是 HTTP，那麼必須再額外新增以下內容

[plugins."io.containerd.grpc.v1.cri".registry.mirrors]
[plugins."io.containerd.grpc.v1.cri".registry.mirrors."{FQDN or IP Address}:Port"]
endpoint = ["http://{FQDN or IP Address}:Port"]

重啟 RKE2 服務

$ sudo systemctl restart rke2-server.service

如果是 RKE2 worker 節點要重啟的服務是 rke2-agent.service

刪除 config.toml.tmpl 檔案 (不一定要做)

$ sudo rm /var/lib/rancher/rke2/agent/etc/containerd/config.toml.tmpl

重要 ! 如果 RKE2 由 Rancher 管理，那麼只要這個檔案存在，在 Rancher 設定的 Image Registry 資訊，都會被這個檔案覆蓋，所以要自行決定是否刪除。

Enable Rrancher Audit log

PreRequest

Note: Rancher 要可以收到 Audit log ，它所在的 K8S 也要先啟動 Audit log

1. RKE2 啟動 Audit log

Step 1: Update the RKE2 Configuration File

$ echo "audit-policy-file: /etc/rancher/rke2/audit-policy.yaml" | sudo tee -a /etc/rancher/rke2/config.yaml

Step 2: Create an Audit Policy File

$ cat <<EOF | sudo tee /etc/rancher/rke2/audit-policy.yaml
apiVersion: audit.k8s.io/v1
kind: Policy
metadata:
creationTimestamp: null
rules:
- level: Metadata
EOF

Step 3: Restart RKE2 Server

$ sudo systemctl restart rke2-server

Step 4: Monitor Audit Log

$ sudo tail -f /var/lib/rancher/rke2/server/logs/audit.log

2. Enable Rrancher Audit log

Step 1: Export the current values to a file:

$ helm get values rancher -n cattle-system -o yaml > values.yaml

Step 2: 新增 Audit log 設定

$ cat <<EOF | sudo tee -a values.yaml
auditLog:
destination: sidecar
hostPath: /var/log/rancher/audit/
level: 3
maxAge: 3
maxBackup: 1
maxSize: 100
EOF

Step 3: 更新 Rancher 啟動 Audit log

$ helm upgrade rancher rancher-prime/rancher \
--namespace cattle-system \
-f values.yaml

設定 RKE2 Cluster Pod 總量限制

點選 “Cluster Management” -> 在要設定的叢集旁邊點選 “Edit Config”

在 Cluster Configuration 的左側選單中點選 “Advanced”，並在 Additional Kubelet Args 區塊下點選 “Add Argument”

輸入以下設定值，並點選右下角 “Save” 套用設定

max-pods=250

max-pods means Number of Pods that can run on this kubelet.

從 Rancher 設定的話，會把以上新增的設定套用到 K8S Cluster 的每個節點上。

回到 “Home”

我的 Cluster 有 3 台 Node，所以 250 x 3 = 750
可以參考我做的測試測試 K8S Pod 數量超過 110 會發生甚麼事?

Trouble shooting

在 Join Master Node 的時候，不小心設定到同一個 node name ，然後 etcd 咬住原來 node 的名稱怎麼辦

錯誤訊息

ETCD join failed: duplicate node name found, please use a unique name for this node

解決辦法

先進去 etcd 的 pod 中

kubectl -n kube-system exec -it etcd-staging-kube-master-1.fqdn.com -- bash

列出 etcd 的成員

etcdctl --cert /var/lib/rancher/rke2/server/tls/etcd/server-client.crt --key /var/lib/rancher/rke2/server/tls/etcd/server-client.key --endpoints https://127.0.0.1:2379 --cacert /var/lib/rancher/rke2/server/tls/etcd/server-ca.crt member list

螢幕輸出

121f9e856446fcc4, started, rsm2-f826f76c, https://192.168.11.62:2380, https://192.168.11.62:2379, false
67f4840cc79f9560, started, rsm1-168e267e, https://192.168.11.61:2380, https://192.168.11.61:2379, false
6b20c6a3411cab14, started, rsm3-2126c18e, https://192.168.11.63:2380, https://192.168.11.63:2379, false

刪除重複的 etcd 成員

etcdctl --cert /var/lib/rancher/rke2/server/tls/etcd/server-client.crt --key /var/lib/rancher/rke2/server/tls/etcd/server-client.key --endpoints https://127.0.0.1:2379 --cacert /var/lib/rancher/rke2/server/tls/etcd/server-ca.crt member remove 6b20c6a3411cab14

螢幕輸出

Member 6b20c6a3411cab14 removed from cluster 9ea915bf6adaa894

手動更新 Cert-manager 做給 Rancher 用的憑證

Rancher 透過 Cert-manager 做出來的憑證，有效期限預設為 90 天，在第 60 天的時候會嘗試自動更換憑證。

SSH 連線至可以執行 kubectl 管理 UpStream Cluster ( Rancher 所在的 Kubernetes Cluster ) 的機器
下載 Cert-manager 管理工具

$ curl -fsSL -o cmctl.tar.gz https://github.com/cert-manager/cert-manager/releases/latest/download/cmctl-linux-amd64.tar.gz && tar xzf cmctl.tar.gz && sudo mv cmctl /usr/local/bin

檢查 Rancher 當前使用憑證的有效日期

$ echo | openssl s_client -connect `kubectl -n cattle-system get ing --no-headers -o custom-columns=HOSTS:.spec.rules[*].host`:443 2>/dev/null | openssl x509 -noout -dates

螢幕輸出如下 :

notBefore=Feb 19 05:31:37 2024 GMT
notAfter=May 19 05:31:37 2024 GMT

手動 Renew Rancher 憑證

4.1. 檢查 Rancher 在 Kubernetes 中使用的憑證名稱

$ kubectl -n cattle-system get certificate

螢幕輸出 :

NAME READY SECRET AGE
tls-rancher-ingress True tls-rancher-ingress 2d21h

4.2. 手動 Renew 憑證

$ cmctl -n cattle-system renew tls-rancher-ingress

螢幕輸出 :

Manually triggered issuance of Certificate cattle-system/tls-rancher-ingress

4.3. 檢查建立憑證的 Request 是否發出

$ kubectl -n cattle-system get certificaterequest --sort-by=.metadata.creationTimestamp

螢幕輸出 :

NAME APPROVED DENIED READY ISSUER REQUESTOR AGE
tls-rancher-ingress-9jb67 True True rancher system:serviceaccount:cert-manager:cert-manager 2d21h
tls-rancher-ingress-m59sk True True rancher system:serviceaccount:cert-manager:cert-manager 3s

確認憑證當前狀態的詳細資訊

$ cmctl -n cattle-system status certificate tls-rancher-ingress

螢幕輸出 :

Name: tls-rancher-ingress
Namespace: cattle-system
Created at: 2024-02-16T17:08:39+08:00
Conditions:
Ready: True, Reason: Ready, Message: Certificate is up to date and has not expired
DNS Names:
- 172.20.0.37.nip.io
Events:
Type Reason Age From Message
---- ------ ---- ---- -------
Normal Requested 13m cert-manager-certificates-request-manager Created new CertificateRequest resource "tls-rancher-ingress-7hdcg"
Normal Requested 6m49s cert-manager-certificates-request-manager Created new CertificateRequest resource "tls-rancher-ingress-8hhjl"
Normal Reused 2m56s (x6 over 156m) cert-manager-certificates-key-manager Reusing private key stored in existing Secret resource "tls-rancher-ingress"
Normal Issuing 2m56s (x6 over 156m) cert-manager-certificates-issuing The certificate has been successfully issued
Normal Requested 2m56s cert-manager-certificates-request-manager Created new CertificateRequest resource "tls-rancher-ingress-m59sk"
Issuer:
Name: rancher
Kind: Issuer
Conditions:
Ready: True, Reason: KeyPairVerified, Message: Signing CA verified
Events: <none>
Secret:
Name: tls-rancher-ingress
Issuer Country:
Issuer Organisation: dynamiclistener-org
Issuer Common Name: dynamiclistener-ca@1708074590
Key Usage: Digital Signature, Key Encipherment
Extended Key Usages:
Public Key Algorithm: RSA
Signature Algorithm: ECDSA-SHA256
Subject Key ID:
Authority Key ID: bc3674dd7762dca834cb5586c463a2c858d11528
Serial Number: c9246b491d331f8d197eed83d4de06d5
Events: <none>
Not Before: 2024-02-19T14:47:46+08:00
Not After: 2024-05-19T14:47:46+08:00
Renewal Time: 2024-04-19T14:47:46+08:00
No CertificateRequest found for this Certificate

Not Before，憑證有效期限的開始日期

Not After，憑證有效期限的結束日期

Renewal Time，cert-manager 將把憑證的 status.RenewalTime 設定為嘗試更新的時間。

參考網站

Logging Operator

Tue, 24 Mar 2026 10:12:54 +0800

Preface

本篇文章會先介紹什麼是 Logging Operator，並透過 Rancher Logging 實作將 Pod Log 導入 OpenSearch

簡介

Logging Operator 是一套專為 Kubernetes 環境設計的日誌管理工具。它能夠自動部署與設定完整的日誌收集流程（logging pipeline），讓你不必手動處理繁瑣的日誌基礎設施配置。

運作流程

Logging Operator 的日誌處理分為三個階段：

1. 日誌收集（Log Collector）

Operator 會在 Kubernetes 叢集中的每個節點上部署一個 Fluent Bit DaemonSet，負責從節點的檔案系統中收集 App Containers 和應用程式的日誌。

2. 中繼資料 enrichment（Metadata Enrichment）

Fluent Bit 會查詢 Kubernetes API，為日誌附加 Pod 的相關中繼資料（metadata），例如 Pod 名稱、namespace、標籤等。接著，將日誌連同這些中繼資料一併傳送給日誌轉發器（Log Forwarder）。

3. 日誌轉發（Log Forwarding）

日誌轉發器負責接收、過濾與轉換傳入的日誌，並將處理完的結果傳送到一個或多個目的地輸出（destination outputs）。

目前支援的日誌轉發器有兩種：

轉發器	說明
Fluentd	廣泛使用的開源日誌轉發工具
syslog-ng（透過 AxoSyslog 發行版）	高效能的系統日誌處理引擎

安全性

所有日誌的傳輸皆透過經過驗證（authenticated）且加密（encrypted）的通道進行，確保資料在傳輸過程中的安全性。

核心優勢

Logging Operator 最大的特色在於：你可以將日誌的行為描述直接定義在應用程式的 Helm Chart 中，Operator 會自動完成其餘的部署與配置工作。

換句話說，日誌設定可以隨著應用程式一起版本控制與部署，實現基礎設施即程式碼（Infrastructure as Code）的理念。

功能特色

Logging Operator 提供以下核心功能：

Namespace 隔離：日誌流（flow）與輸出（output）可以限定在特定的 namespace 中運作，實現多租戶隔離。
原生 Kubernetes Label Selector：直接使用 Kubernetes 原生的標籤選擇器來篩選要收集的日誌來源。
安全通訊（TLS）：所有日誌傳輸皆支援 TLS 加密，確保資料安全。
設定檔驗證：自動驗證設定是否正確，降低配置錯誤的風險。
多重 Flow 支援：同一份日誌可以經由多條 flow 進行不同的過濾與轉換處理。
多重 Output 支援：同一份日誌可以同時傳送到多個儲存目的地，例如 S3、GCS、Elasticsearch、Loki 等。
多重 Logging 系統支援：在同一個叢集中可以部署多套 Fluentd 與 Fluent Bit 實例，滿足不同的日誌需求。
雙轉發器引擎：同時支援 syslog-ng 與 Fluentd 作為核心日誌路由元件。

架構概覽

Logging Operator 管理日誌基礎設施中的三個核心角色：日誌收集器（Log Collector）、日誌轉發器（Log Forwarder），以及定義日誌該送往何處的路由規則。

日誌收集器（Log Collector）

部署在每個 Kubernetes 節點上的端點代理程式（endpoint agent）。
負責收集該節點上所有 App Container 的日誌，並傳送給日誌轉發器。
目前使用 Fluent Bit 作為日誌收集器。

日誌轉發器（Log Forwarder / Log Aggregator）

接收來自收集器的日誌後，進行過濾（filter）與轉換（transform）。
將處理後的日誌傳送到一個或多個目的地輸出。
支援兩種轉發器引擎：

轉發器	適用場景
Fluentd	生態系成熟、外掛豐富，適合大多數使用情境
syslog-ng	高效能、低資源消耗，適合需要進階日誌處理邏輯的場景

如何選擇適合的轉發器，可參考官方文件 Which log forwarder to use。

路由規則（Flow & Output）

你可以透過 Flow 自訂資源來過濾、處理日誌訊息，並將它們路由到適當的 Output（目的地），例如 Elasticsearch 或 Amazon S3。

除了 namespace 層級的 flow 與 output，你也可以定義叢集層級的 ClusterFlow 與 ClusterOutput，讓所有 namespace 的使用者都能引用同一組集中式輸出，但無法修改其設定。

注意： Flow 與 Output 資源是依據你選用的轉發器類型（Fluentd 或 syslog-ng）而不同的，兩者的 CRD 不能混用。

Custom Resource Definitions（CRD）一覽

共用資源

CRD	說明	作用範圍
logging	定義叢集的日誌基礎設施，包含日誌收集器與轉發器的設定。也可包含 Fluent Bit、Fluentd、syslog-ng 的配置。自 4.5 版起，這些元件也可作為獨立資源分開設定。	叢集層級

Fluentd 專用 CRD

CRD	說明	作用範圍
output	定義 Fluentd 的日誌輸出目的地。	Namespace
flow	定義 Fluentd 的日誌路由規則，使用 filter 與 output 將選定的日誌導向指定目的地。	Namespace
clusteroutput	定義可供所有 flow 與 clusterflow 使用的 Fluentd 輸出。預設僅在 `controlNamespace` 中生效，除非設定 `allowClusterResourcesFromAllNamespaces: true`。	叢集層級
clusterflow	定義可從所有 namespace 收集日誌的 Fluentd 路由規則。預設僅在 `controlNamespace` 中生效，除非設定 `allowClusterResourcesFromAllNamespaces: true`。	叢集層級

syslog-ng 專用 CRD

CRD	說明	作用範圍
SyslogNGOutput	定義 syslog-ng 的日誌輸出目的地。	Namespace
SyslogNGFlow	定義 syslog-ng 的日誌路由規則，使用 filter 與 output 將選定的日誌導向指定目的地。	Namespace
SyslogNGClusterOutput	定義可供所有 flow 與 clusterflow 使用的 syslog-ng 輸出。預設僅在 `controlNamespace` 中生效，除非設定 `allowClusterResourcesFromAllNamespaces: true`。	叢集層級
SyslogNGClusterFlow	定義可從所有 namespace 收集日誌的 syslog-ng 路由規則。預設僅在 `controlNamespace` 中生效，除非設定 `allowClusterResourcesFromAllNamespaces: true`。	叢集層級

Fluentd 與 syslog-ng 的 CRD 結構相似，但各自針對自身引擎的特性進行了調整。選用哪一組 CRD 取決於你在 logging 資源中選擇的轉發器類型。

Rancher Logging — 將 Pod Log 導入 OpenSearch 實作指南

環境概述

Rancher 的日誌管理由 Logging operator 提供支持。以下實作將透過 Rancher logging，將指定 Kubernetes Pod 的 stdout log 經由 Fluentd 轉送至外部 OpenSearch。

環境準備

Rancher 安裝 DownStream RKE2 Cluster
DownStream RKE2 Cluster 已安裝 Rancher Logging
在 DownStream RKE2 Cluster 外部已安裝好 opensearch

步驟一：建立 Namespace

kubectl create ns app

步驟二：部署測試用 Pod

建立一個每秒輸出一行遞增計數 log 的 Pod，用以驗證 log pipeline 是否正常運作。

cat <<'EOF' | kubectl apply -f -
apiVersion: v1
kind: Pod
metadata:
 name: test-logging-pod
 namespace: app
 labels:
 logging-test: "true"
spec:
 automountServiceAccountToken: false
 securityContext:
 runAsNonRoot: true
 runAsUser: 1000
 runAsGroup: 1000
 seccompProfile:
 type: RuntimeDefault
 containers:
 - name: sak
 image: rancherlabs/swiss-army-knife:latest
 command: ["/bin/sh"]
 args:
 - -c
 - |
 i=0; while true; do echo "$(date) INFO $i"; i=$((i+1)); sleep 1; done
 securityContext:
 allowPrivilegeEscalation: false
 readOnlyRootFilesystem: true
 capabilities:
 drop:
 - ALL
EOF

確認 Pod 已正常啟動：

kubectl -n app get pods -l logging-test=true

預期輸出：

NAME READY STATUS RESTARTS AGE
test-logging-pod 1/1 Running 0 5s

確認 log 輸出正常：

kubectl -n app logs test-logging-pod

預期輸出（每秒遞增一行）：

Mon Mar 16 07:43:57 UTC 2026 INFO 0
Mon Mar 16 07:43:58 UTC 2026 INFO 1
Mon Mar 16 07:43:59 UTC 2026 INFO 2
...

步驟三：建立 OpenSearch 認證 Secret

將 OpenSearch 的帳號密碼以 kubernetes.io/basic-auth 類型的 Secret 儲存於叢集中，供後續 Output CR 引用。

PW='Test12345@'

kubectl create secret generic opensearch-user-auth \
 --namespace=app \
 --type=kubernetes.io/basic-auth \
 --from-literal=username=admin \
 --from-literal=password=$PW

步驟四：建立 Logging Output CR

定義 Fluentd 將 log 發送至 OpenSearch 的目標端點與 buffer 策略。

cat <<'EOF' | kubectl apply -f -
apiVersion: logging.banzaicloud.io/v1beta1
kind: Output
metadata:
 name: opensearch-admin
 namespace: app
spec:
 opensearch:
 host: opensearch-node.kubeantony.com
 port: 9200
 scheme: https
 ssl_verify: false
 ssl_version: TLSv1_2
 suppress_type_name: true
 user: admin
 password:
 valueFrom:
 secretKeyRef:
 key: password
 name: opensearch-user-auth
 buffer:
 flush_interval: 10s
 flush_mode: interval
 retry_type: exponential_backoff
 retry_forever: true
 chunk_limit_size: 8MB
 total_limit_size: 512MB
EOF

Buffer 參數說明

參數	值	說明
`flush_mode`	`interval`	以固定時間間隔觸發 flush，在即時性與效能間取得平衡
`flush_interval`	`10s`	每 10 秒將累積的 log 批次送出
`chunk_limit_size`	`8MB`	單一 chunk 上限；達到後即使未到 flush 時間也會送出，防止記憶體暴漲
`total_limit_size`	`512MB`	所有 buffer 佔用的磁碟空間上限；超過後新 log 將依 `overflow_action` 處理
`retry_type`	`exponential_backoff`	發送失敗時以指數退避策略重試（1s → 2s → 4s → …），避免對 OpenSearch 造成衝擊
`retry_forever`	`true`	無限重試直到成功，確保 log 不遺失（代價是 buffer 可能在長時間故障時被填滿）

確認 Output 資源已建立（此時 ACTIVE 為 false 是正常的，表示尚未被任何 Flow 引用）：

kubectl -n app get outputs.logging.banzaicloud.io

預期輸出：

NAME ACTIVE PROBLEMS
opensearch-admin false

步驟五：建立 Logging Flow CR

建立 Flow 將帶有 logging-test: "true" label 的 Pod log 路由至上一步定義的 Output。

cat <<'EOF' | kubectl apply -f -
apiVersion: logging.banzaicloud.io/v1beta1
kind: Flow
metadata:
 name: app-to-opensearch
 namespace: app
spec:
 match:
 - select:
 labels:
 logging-test: "true"
 localOutputRefs:
 - opensearch-admin
EOF

確認 Flow 已啟用：

kubectl -n app get flows.logging.banzaicloud.io

預期輸出：

NAME ACTIVE PROBLEMS
app-to-opensearch true

步驟六：於 OpenSearch 驗證 Log 寫入

確認索引已建立

於 OpenSearch Dashboards 左上角選單進入 Index Management → Indexes，搜尋 fluentd，應可看到對應索引已自動建立。

查詢最新 Log

於 Dev Tools 執行以下查詢，取得最近 3 筆 log：

GET fluentd/_search
{
 "size": 3,
 "sort": [{ "time": { "order": "desc" }}],
 "query": {
 "match_all": {}
 }
}

回傳結果中，每筆文件的 _source 應包含 message（原始 log 訊息）、kubernetes（Pod metadata）、以及 time（時間戳記）等欄位，代表 log pipeline 已完整串通。

以下為其中一筆 log

{
 "took": 1000,
 "timed_out": false,
 "_shards": {
 "total": 1,
 "successful": 1,
 "skipped": 0,
 "failed": 0
 },
 "hits": {
 "total": {
 "value": 10000,
 "relation": "gte"
 },
 "max_score": null,
 "hits": [
 {
 "_index": "fluentd",
 "_id": "q0239pwBR50SWBx4toac",
 "_score": null,
 "_source": {
 "time": "2026-03-16T20:55:59.312256038+08:00",
 "stream": "stdout",
 "logtag": "F",
 "message": "Mon Mar 16 12:55:59 UTC 2026 INFO 9961",
 "kubernetes": {
 "pod_name": "test-logging-pod",
 "namespace_name": "app",
 "pod_id": "50148584-185c-475c-b203-4120526c755d",
 "labels": {
 "logging-test": "true"
 },
 "annotations": {
 "kubectl.kubernetes.io/last-applied-configuration": """{"apiVersion":"v1","kind":"Pod","metadata":{"annotations":{},"labels":{"logging-test":"true"},"name":"test-logging-pod","namespace":"app"},"spec":{"automountServiceAccountToken":false,"containers":[{"args":["-c","i=0; while true; do echo \"$(date) INFO $i\"; i=$((i+1)); sleep 1; done\n"],"command":["/bin/sh"],"image":"rancherlabs/swiss-army-knife:latest","name":"sak","securityContext":{"allowPrivilegeEscalation":false,"capabilities":{"drop":["ALL"]},"readOnlyRootFilesystem":true}}],"securityContext":{"runAsGroup":1000,"runAsNonRoot":true,"runAsUser":1000,"seccompProfile":{"type":"RuntimeDefault"}}}}
"""
 },
 "host": "rke2-w2",
 "container_name": "sak",
 "docker_id": "d820db7b9416cde0b968f2e2fa314e74d656a064def3ecc183b7768bef65102a",
 "container_hash": "docker.io/rancherlabs/swiss-army-knife@sha256:af25a3ace6269adb9e494b693644bc2f897ec872076d78f78bc5ded69f2ee222",
 "container_image": "docker.io/rancherlabs/swiss-army-knife:latest"
 },
 "kubernetes_namespace": {
 "name": "app",
 "labels": {
 "field.cattle.io/projectId": "p-pzhk7",
 "kubernetes.io/metadata.name": "app"
 }
 }
 },
 "sort": [
 1773665759312
 ]
 }
 ]
 }
}

log 架構說明

以下逐層說明這個 OpenSearch 查詢回應的結構：

第一層：查詢執行資訊

took 表示 OpenSearch 花了 1000 毫秒完成這次查詢。timed_out: false 代表查詢在設定的超時限制內完成。_shards 記錄了參與查詢的分片狀態，這裡只有 1 個分片且執行成功、無失敗。

第二層：結果集合 hits

hits.total.value 為 10000，搭配 relation: "gte" 表示實際命中數量「大於或等於」10,000 筆，這是 OpenSearch 預設的計數上限（track_total_hits 未啟用精確計數時的行為）。max_score 為 null 是因為查詢使用了 sort 排序，此時相關性分數不會被計算。

第三層：單筆文件 hits.hits[]

每筆文件包含 _index（寫入的索引名稱，這裡是 fluentd）、_id（OpenSearch 自動產生的文件 ID）、以及 sort（排序欄位的原始值，此處為 time 的毫秒級 epoch）。

第四層：_source — Fluentd 寫入的原始資料

這是最核心的部分，由 Fluentd 的 Kubernetes metadata filter 自動附加：

time：log 產生的時間戳記（ISO 8601 格式，含時區）
message：容器的原始 stdout 輸出內容
stream：輸出流類型，stdout 或 stderr
logtag：CRI log 的完整性標記，F 代表完整行（Full），P 代表部分行（Partial，尚有後續）
kubernetes：Pod 層級的元資料，包含 pod 名稱、namespace、pod ID、labels、annotations、所在節點（host）、容器名稱與 image 資訊
kubernetes_namespace：Namespace 層級的元資料，包含名稱及其 labels（如 Rancher 的 projectId）

Rancher Logging — 將 Pod Log 導入 OpenSearch 實作指南 2

環境概述

以下實作將透過 Rancher logging，將指定 Kubernetes namespace 底下所有 Pods 的 log 經由 Fluentd 轉送至外部 logstash 再轉送到 opensearch。

環境準備

Rancher 安裝 DownStream RKE2 Cluster
DownStream RKE2 Cluster 已安裝 Rancher Logging
在 DownStream RKE2 Cluster 外部已安裝好 logstash
在 DownStream RKE2 Cluster 外部已安裝好 opensearch

開始實作

# Secret: CA 憑證
kubectl -n kube-system create secret generic logstash-ca \
--from-file=ca.crt=/etc/logstash/certs/ca.crt
# Secret: basic auth 帳密
kubectl -n kube-system create secret generic logstash-auth \
--from-literal=username=logstash \
--from-literal=password=logstash
cat <<'EOF' | kubectl apply -f -
apiVersion: logging.banzaicloud.io/v1beta1
kind: Output
metadata:
name: logstash-http
namespace: kube-system
spec:
apiVersion: logging.banzaicloud.io/v1beta1
kind: Output
metadata:
name: logstash-http
namespace: kube-system
spec:
http:
endpoint: "https://logstash.kubeantony.com:8080"
content_type: "application/json"
json_array: true
auth:
username:
valueFrom:
secretKeyRef:
name: logstash-auth
key: username
password:
valueFrom:
secretKeyRef:
name: logstash-auth
key: password
tls_ca_cert_path:
mountFrom:
secretKeyRef:
name: logstash-ca
key: ca.crt
buffer:
type: file
flush_interval: 5s
flush_mode: interval
timekey: 1m
timekey_wait: 10s
total_limit_size: 1GB
EOF
cat <<'EOF' | kubectl apply -f -
apiVersion: logging.banzaicloud.io/v1beta1
kind: Flow
metadata:
name: kube-logs
namespace: kube-system
spec:
match:
- select: {}
localOutputRefs:
- logstash-http
EOF

確認索引已建立

於 OpenSearch Dashboards 左上角選單進入 Index Management → Indexes，搜尋 fluentd，應可看到對應索引已自動建立。

查詢最新 Log

於 Dev Tools 執行以下查詢，對日誌索引執行無條件檢索，並依時間戳（@timestamp）降序排列以提取最新的一筆數據紀錄：

GET opensearch-logstash-docker-2026.03.24/_search
{
 "size": 1,
 "query": {
 "match_all": {}
 },
 "sort": [{"@timestamp": "desc"}]
}

以下為其中一筆 log

{
 "took": 563,
 "timed_out": false,
 "_shards": {
 "total": 1,
 "successful": 1,
 "skipped": 0,
 "failed": 0
 },
 "hits": {
 "total": {
 "value": 10000,
 "relation": "gte"
 },
 "max_score": null,
 "hits": [
 {
 "_index": "opensearch-logstash-docker-2026.03.24",
 "_id": "ielEH50BXMB4tDz9Y0CX",
 "_score": null,
 "_source": {
 "logtag": "F",
 "message": "W0324 09:54:23.735867 1 logging.go:55] [core] [Channel #4240 SubChannel #4241]grpc: addrConn.createTransport failed to connect to {Addr: \"127.0.0.1:2379\", ServerName: \"127.0.0.1:2379\", BalancerAttributes: {\"<%!p(pickfirstleaf.managedByPickfirstKeyType={})>\": \"<%!p(bool=true)>\" }}. Err: connection error: desc = \"transport: Error while dialing: dial tcp 127.0.0.1:2379: operation was canceled\"",
 "url": {
 "domain": "logstash.kubeantony.com",
 "path": "/",
 "port": 8080
 },
 "kubernetes": {
 "container_hash": "registry.rancher.com/rancher/hardened-kubernetes@sha256:4fab2ebc142aa1bb04a9641daebd6197404040806758cb3f3e78a6acfde47853",
 "annotations": {
 "kubernetes.io/config.mirror": "88a0909b75e7783678932b6535c63316",
 "kubernetes.io/config.hash": "88a0909b75e7783678932b6535c63316",
 "kubernetes.io/config.source": "file",
 "kubernetes.io/config.seen": "2026-03-04T13:33:01.249775809+08:00"
 },
 "pod_name": "kube-apiserver-rke2-c2",
 "container_image": "registry.rancher.com/rancher/hardened-kubernetes:v1.34.4-rke2r1-build20260210",
 "labels": {
 "tier": "control-plane",
 "component": "kube-apiserver"
 },
 "host": "rke2-c2",
 "container_name": "kube-apiserver",
 "pod_id": "80dc734a-bbbc-48bc-a95f-ba88100ec24b",
 "docker_id": "61c3121ba35fa4fa01f25037d1f27181d0b455cb350d196de37b55f13edb2444",
 "namespace_name": "kube-system"
 },
 "@timestamp": "2026-03-24T09:54:28.785431836Z",
 "user_agent": {
 "original": "Ruby"
 },
 "http": {
 "version": "HTTP/1.1",
 "request": {
 "body": {
 "bytes": "1448"
 },
 "mime_type": "application/json"
 },
 "method": "POST"
 },
 "event": {
 "original": """[{"time":"2026-03-24T17:54:23.73604561+08:00","stream":"stderr","logtag":"F","message":"W0324 09:54:23.735867 1 logging.go:55] [core] [Channel #4240 SubChannel #4241]grpc: addrConn.createTransport failed to connect to {Addr: \"127.0.0.1:2379\", ServerName: \"127.0.0.1:2379\", BalancerAttributes: {\"<%!p(pickfirstleaf.managedByPickfirstKeyType={})>\": \"<%!p(bool=true)>\" }}. Err: connection error: desc = \"transport: Error while dialing: dial tcp 127.0.0.1:2379: operation was canceled\"","kubernetes":{"pod_name":"kube-apiserver-rke2-c2","namespace_name":"kube-system","pod_id":"80dc734a-bbbc-48bc-a95f-ba88100ec24b","labels":{"component":"kube-apiserver","tier":"control-plane"},"annotations":{"kubernetes.io/config.hash":"88a0909b75e7783678932b6535c63316","kubernetes.io/config.mirror":"88a0909b75e7783678932b6535c63316","kubernetes.io/config.seen":"2026-03-04T13:33:01.249775809+08:00","kubernetes.io/config.source":"file"},"host":"rke2-c2","container_name":"kube-apiserver","docker_id":"61c3121ba35fa4fa01f25037d1f27181d0b455cb350d196de37b55f13edb2444","container_hash":"registry.rancher.com/rancher/hardened-kubernetes@sha256:4fab2ebc142aa1bb04a9641daebd6197404040806758cb3f3e78a6acfde47853","container_image":"registry.rancher.com/rancher/hardened-kubernetes:v1.34.4-rke2r1-build20260210"},"kubernetes_namespace":{"name":"kube-system","labels":{"field.cattle.io/projectId":"p-xnskv","kubernetes.io/metadata.name":"kube-system"}}}
]"""
 },
 "stream": "stderr",
 "time": "2026-03-24T17:54:23.73604561+08:00",
 "@version": "1",
 "host": {
 "ip": "192.168.11.156"
 },
 "kubernetes_namespace": {
 "name": "kube-system",
 "labels": {
 "field.cattle.io/projectId": "p-xnskv",
 "kubernetes.io/metadata.name": "kube-system"
 }
 }
 },
 "sort": [
 1774346068785
 ]
 }
 ]
 }
}

沒問題！我將根據您提供的架構，結合這份日誌的實際內容進行邏輯拆解與解釋。這份日誌記錄了 2026-03-24 某個 Kubernetes 核心組件發生連線異常的瞬間。

Log 架構邏輯說明

以下逐層說明這個 OpenSearch 查詢回應的結構：

第一層：查詢執行資訊 (Query Execution Info)

took: 表示 OpenSearch 花了 563 毫秒 完成這次查詢。
timed_out: false: 代表查詢在設定的超時限制內順利完成。
_shards: 記錄了參與查詢的分片狀態，這裡只有 1 個分片 且執行成功、無失敗，顯示索引結構較為簡單或資料量尚在單一分片承載範圍內。

第二層：結果集合 hits (Result Metadata)

hits.total.value: 10000 搭配 relation: "gte": 表示實際命中數量「大於或等於」10,000 筆。這是 OpenSearch 為了查詢效能所做的預設優化（未開啟 track_total_hits），告訴運維人員：符合條件的日誌非常多，這只是冰山一角。
max_score: null: 因為我們在命令中使用了 sort（依照時間排序），OpenSearch 會跳過相關性分數（Relevance Score）的計算，這在日誌分析中是標準做法。

第三層：單筆文件 hits.hits[] (Document Identity)

_index: 寫入的索引名稱為 opensearch-logstash-docker-2026.03.24。
_id: 該筆日誌的唯一標記符 ielEH50BXMB4tDz9Y0CX。
sort: 排序欄位的原始值 1774346068785（這是一個毫秒級的 Epoch 時間戳記，對應到 @timestamp）。

第四層：_source — 採集器寫入的原始資料 (Enriched Data)

這是運維診斷的核心，由日誌採集器（如 Logstash/Fluentd）自動附加的元資料：

時間戳記與時區邏輯：
- message 內: 09:54:23（容器原始輸出的 UTC 時間）。
- time: 17:54:23...+08:00（採集器轉換後的本地時間，兩者相差 8 小時）。
- @timestamp: 09:54:28Z（OpenSearch 儲存用的標準 UTC 格式，比 log 產出晚 5 秒，代表處理延遲）。
message: 核心錯誤內容，顯示 kube-apiserver 無法連線至本地的 etcd (127.0.0.1:2379)。
stream: stderr: 標記這是一條錯誤流日誌，並非正常的標準輸出。
logtag: F: 代表這是一行完整的（Full）Log，沒有因為長度限制而被截斷。
kubernetes (Pod 元資料):
- 定位：發生在命名空間 kube-system 中的 Pod kube-apiserver-rke2-c2。
- 環境：運行於節點 rke2-c2，映像檔版本為 v1.34.4。
- 身份識別：包含 pod_id 與 docker_id，方便進一步去主機端（Node）下 docker/crictl inspect 指令查核。
kubernetes_namespace: 顯示該 Namespace 屬於 Rancher 專案 p-xnskv，這有助於在多租戶環境下快速判斷受影響的專案範圍。

Quick Start OpenSearch

Tue, 24 Mar 2026 06:43:24 +0800

環境準備

os: Ubuntu 24.04.4 LTS
podman version: 4.9.3

OpenSearch

建立 podman volume

sudo podman volume create opensearch-data

Create a Docker network
```
sudo podman network create log-system
```

啟動 OpenSearch，並掛載 volume

sudo podman run -d \
-p 9200:9200 \
-p 9600:9600 \
--name opensearch \
--net log-system \
-e "discovery.type=single-node" \
-e 'OPENSEARCH_INITIAL_ADMIN_PASSWORD=<password>' \
-v opensearch-data:/usr/share/opensearch/data \
docker.io/opensearchproject/opensearch:latest

password 要自己定義，必須使用至少 8 個字元，包含至少一個大寫字母、一個小寫字母、一個數字，以及一個特殊字元。

OpenSearch dashboard

編輯 OpenSearch Dashboards 設定檔

mkdir ~/opensearch; nano opensearch_dashboards.yml

檔案內容：

opensearch.hosts 的值要根據環境做設定，並在環境的 DNS Server 新增一筆 A Record

server.name: opensearch_dashboards
server.host: "0.0.0.0"
server.customResponseHeaders: { "Access-Control-Allow-Credentials": "true" }
server.ssl.enabled: false
opensearch.hosts: ["https://opensearch-node.kubeantony.com:9200"]
opensearch.ssl.verificationMode: none
opensearch.username: kibanaserver
opensearch.password: kibanaserver
opensearch.requestHeadersWhitelist: ["securitytenant","Authorization"]
opensearch_security.multitenancy.enabled: true
opensearch_security.multitenancy.tenants.preferred: ["Private", "Global"]
opensearch_security.readonly_mode.roles: ["kibana_read_only"]

啟動 OpenSearch Dashboards

sudo podman run -d --name osd \
--network host \
-v ./opensearch_dashboards.yml:/usr/share/opensearch-dashboards/config/opensearch_dashboards.yml \
docker.io/opensearchproject/opensearch-dashboards:latest

連線至 Web 管理網站
```
http://<opensearch.hosts>:5601/
```

With Logstash

sudo podman volume create logstash-data

mkdir -p ~/logstash/pipeline
cat > ~/logstash/pipeline/logstash.conf << 'EOF'
input {
http {
host => "0.0.0.0"
port => 8080
}
}
filter {
}
output {
opensearch {
hosts => ["https://opensearch-node.kubeantony.com:9200"]
index => "opensearch-logstash-docker-%{+YYYY.MM.dd}"
user => "admin"
password => "!QAZ2wsx@WSX!!"
ssl => false
ssl_certificate_verification => false
}
}
EOF

sudo podman run -d -it --name logstash \
--net log-system \
-v logstash-data:/usr/share/logstash/data \
-p 8080:8080 \
-v ~/logstash/pipeline/logstash.conf:/usr/share/logstash/pipeline/logstash.conf:Z \
docker.io/opensearchproject/logstash-oss-with-opensearch-output-plugin:8.9.0 \

sudo podman exec -it logstash /usr/share/logstash/bin/logstash-plugin update logstash-output-opensearch
sudo podman restart logstash

curl -XPOST http://logstash.kubeantony.com:8080 \
-H "Content-Type: application/json" \
-d '{"message": "test from outside"}'

Logstash Podman Quadlet 部署指南（Rootful / Podman 4.9.3）

操作方式：以一般使用者登入，必要時透過 sudo 提權。 Quadlet 檔案放在 /etc/containers/systemd/，容器以 rootful 模式執行。

版本限制：Podman 4.9.3 不支援 .build Quadlet（需 5.2.0+），因此自訂映像需先手動 build，再由 .container 直接引用。

前置準備：安裝 podlet

curl -fsSL https://raw.githubusercontent.com/braveantony/bash-script/refs/heads/main/install-podlet.sh | sudo bash

1. 建立目錄結構

sudo mkdir -p /opt/logstash/build
sudo mkdir -p /etc/logstash/pipeline
sudo mkdir -p /etc/logstash/certs
sudo mkdir -p /etc/containers/systemd

2. 建立 Containerfile（自訂映像，含更新 plugin）

sudo tee /opt/logstash/build/Containerfile > /dev/null << 'EOF'
FROM docker.io/opensearchproject/logstash-oss-with-opensearch-output-plugin:8.9.0

RUN /usr/share/logstash/bin/logstash-plugin update logstash-output-opensearch
EOF

3. 手動 Build 自訂映像

由於 Podman 4.9.3 不支援 .build Quadlet，需先手動 build 映像：

sudo podman build -t localhost/logstash-custom:latest \
 -f /opt/logstash/build/Containerfile

注意：此步驟需要網路連線，且首次 build 會花一些時間下載基底映像和更新 plugin。後續如需更新 plugin，重新執行此 build 指令即可。

4. 產生 SSL 憑證

使用 mkcert 產出自簽憑證，再將 key 轉為 PKCS8 格式並以固定檔名放入 /etc/logstash/certs/：

# 產出憑證（依照 mkcert 的使用方式，請先編輯 config 中的 DOMAIN_NAME）
git clone https://github.com/braveantony/mkcert.git
nano ./mkcert/config
./mkcert/certctl

# 設定你的 domain name（與 mkcert config 中一致）
DOMAIN_NAME="your-domain.com"
cd ~/mkcert

# 將 key 轉為 PKCS8 格式
openssl pkcs8 -in "${DOMAIN_NAME}/${DOMAIN_NAME}.key" -topk8 -nocrypt -out "${DOMAIN_NAME}/server.key"

# 複製憑證到固定路徑（使用固定檔名）
sudo cp "${DOMAIN_NAME}/${DOMAIN_NAME}.crt" /etc/logstash/certs/server.crt
sudo cp "${DOMAIN_NAME}/server.key" /etc/logstash/certs/server.key
sudo cp "${DOMAIN_NAME}/ca.crt" /etc/logstash/certs/ca.crt

# 設定權限
sudo chmod 0600 /etc/logstash/certs/server.key
sudo chmod 0644 /etc/logstash/certs/server.crt
sudo chmod 0644 /etc/logstash/certs/ca.crt
sudo chown -R root:root /etc/logstash/certs/

5. 建立 Pipeline 設定檔

HTTP input 啟用 HTTPS + basic auth，OpenSearch output 透過環境變數帶入：

sudo tee /etc/logstash/pipeline/logstash.conf > /dev/null << 'EOF'
input {
 http {
 host => "0.0.0.0"
 port => 8080
 user => "${HTTP_AUTH_USER}"
 password => "${HTTP_AUTH_PASSWORD}"
 ssl => true
 ssl_certificate => "/etc/logstash/certs/server.crt"
 ssl_key => "/etc/logstash/certs/server.key"
 }
}
filter {
}
output {
 opensearch {
 hosts => ["${OPENSEARCH_HOSTS}"]
 index => "${OPENSEARCH_INDEX}"
 user => "admin"
 password => "${OPENSEARCH_PASSWORD}"
 ssl => false
 ssl_certificate_verification => false
 }
}
EOF

6. 建立環境變數檔

將所有敏感資訊和可變設定集中管理：

sudo tee /etc/logstash/logstash.env > /dev/null << 'EOF'
# HTTP input basic auth
HTTP_AUTH_USER=logstash
HTTP_AUTH_PASSWORD=logstash

# OpenSearch output
OPENSEARCH_HOSTS=https://opensearch-node.kubeantony.com:9200
OPENSEARCH_INDEX=opensearch-logstash-docker-%{+YYYY.MM.dd}
OPENSEARCH_PASSWORD=!QAZ2wsx@WSX!!
EOF

sudo chmod 0600 /etc/logstash/logstash.env
sudo chown root:root /etc/logstash/logstash.env

請務必修改上方的預設值，尤其是 HTTP_AUTH_USER、HTTP_AUTH_PASSWORD 和 OPENSEARCH_PASSWORD。

7. 使用 podlet 產生 Quadlet 檔案（Rootful）

7-1. 產生 logstash-data.volume

sudo podlet --file /etc/containers/systemd/ --install \
 podman volume create logstash-data

修正 WantedBy 為 rootful 慣例：

sudo sed -i 's/WantedBy=default.target/WantedBy=multi-user.target/' \
 /etc/containers/systemd/logstash-data.volume

7-2. 產生 log-system.network

sudo podlet --file /etc/containers/systemd/ --install \
 podman network create log-system

修正 WantedBy：

sudo sed -i 's/WantedBy=default.target/WantedBy=multi-user.target/' \
 /etc/containers/systemd/log-system.network

7-3. 產生 logstash.container

sudo podlet --file /etc/containers/systemd/ --name logstash --install \
 --description "Logstash with OpenSearch Output Plugin" \
 podman run -d --name logstash \
 --net log-system.network \
 -v logstash-data.volume:/usr/share/logstash/data \
 -v /etc/logstash/pipeline/logstash.conf:/usr/share/logstash/pipeline/logstash.conf:Z \
 -v /etc/logstash/certs:/etc/logstash/certs:Z,ro \
 -p 8080:8080 \
 localhost/logstash-custom:latest

7-4. 手動補上 EnvironmentFile 和 Service 設定，並修正 WantedBy

podlet 產生的檔案沒有 [Service] 區段，需在 [Install] 之前插入：

# 在 [Install] 前插入 EnvironmentFile 和 [Service] 區段
sudo sed -i '/^\[Install\]/i EnvironmentFile=/etc/logstash/logstash.env\n\n[Service]\nRestart=always\nTimeoutStartSec=120\n' \
 /etc/containers/systemd/logstash.container

# 修正 WantedBy
sudo sed -i 's/WantedBy=default.target/WantedBy=multi-user.target/' \
 /etc/containers/systemd/logstash.container

7-5. 驗證最終檔案內容

執行 sudo cat /etc/containers/systemd/logstash.container，確認內容如下：

[Unit]
Description=Logstash with OpenSearch Output Plugin

[Container]
ContainerName=logstash
Image=localhost/logstash-custom:latest
Network=log-system.network
PublishPort=8080:8080
Volume=logstash-data.volume:/usr/share/logstash/data
Volume=/etc/logstash/pipeline/logstash.conf:/usr/share/logstash/pipeline/logstash.conf:Z
Volume=/etc/logstash/certs:/etc/logstash/certs:Z,ro
EnvironmentFile=/etc/logstash/logstash.env

[Service]
Restart=always
TimeoutStartSec=120

[Install]
WantedBy=multi-user.target

如果 sed 結果不如預期，可直接用 sudo vi /etc/containers/systemd/logstash.container 手動編輯。

8. 使用 Quadlet dry-run 驗證

sudo /usr/libexec/podman/quadlet -dryrun

確認輸出無錯誤後再繼續。

9. 重新載入 systemd 並啟動

sudo systemctl daemon-reload
sudo systemctl start logstash.service

10. 確認狀態

sudo systemctl status logstash.service
sudo podman ps
sudo podman logs logstash

11. 測試 HTTPS + Basic Auth

帶認證 + 信任自簽 CA（應回傳 ok）：

# Example: DOMAIN_NAME="logstash.kubeantony.com"
DOMAIN_NAME="your-domain.com"

curl --cacert /etc/logstash/certs/ca.crt \
 -u logstash:logstash \
 -X POST https://${DOMAIN_NAME}:8080 \
 -H "Content-Type: application/json" \
 -d '{"message": "test with https"}'

或跳過憑證驗證（測試用）：

curl -k -u logstash:logstash \
 -X POST https://${DOMAIN_NAME}:8080 \
 -H "Content-Type: application/json" \
 -d '{"message": "test with https"}'

不帶認證應回傳 401：

curl -k -s -o /dev/null -w "%{http_code}" \
 -X POST https://${DOMAIN_NAME}:8080 \
 -H "Content-Type: application/json" \
 -d '{"message": "should fail"}'

用 HTTP（非 HTTPS）應連線失敗：

curl -s -o /dev/null -w "%{http_code}" \
 -X POST http://${DOMAIN_NAME}:8080 \
 -H "Content-Type: application/json" \
 -d '{"message": "should fail"}'

應該會得到 000

路徑總覽

檔案	路徑	說明
`Containerfile`	`/opt/logstash/build/Containerfile`	自訂映像 build 檔
`logstash.conf`	`/etc/logstash/pipeline/logstash.conf`	Pipeline 設定檔
`logstash.env`	`/etc/logstash/logstash.env`	環境變數檔（權限 0600）
`server.crt`	`/etc/logstash/certs/server.crt`	SSL 憑證
`server.key`	`/etc/logstash/certs/server.key`	SSL 私鑰（PKCS8，權限 0600）
`ca.crt`	`/etc/logstash/certs/ca.crt`	CA 憑證（供客戶端驗證）
`logstash-data.volume`	`/etc/containers/systemd/logstash-data.volume`	Quadlet Volume
`log-system.network`	`/etc/containers/systemd/log-system.network`	Quadlet Network
`logstash.container`	`/etc/containers/systemd/logstash.container`	Quadlet Container

環境變數一覽

變數名	用途	範例值
`HTTP_AUTH_USER`	HTTP input basic auth 帳號	`logstash`
`HTTP_AUTH_PASSWORD`	HTTP input basic auth 密碼	`changeme`
`OPENSEARCH_HOSTS`	OpenSearch 連線 URL	`https://opensearch-node.kubeantony.com:9200`
`OPENSEARCH_INDEX`	OpenSearch index 名稱（含日期格式）	`opensearch-logstash-docker-%{+YYYY.MM.dd}`
`OPENSEARCH_PASSWORD`	OpenSearch admin 密碼	`!QAZ2wsx@WSX!!`

注意事項

以一般使用者操作，透過 sudo 提權，容器以 rootful 模式執行。
使用 sudo systemctl（不帶 --user）管理服務。
Podman 4.9.3 不支援 .build Quadlet，映像需先手動 sudo podman build 建構。
podlet 產生的 WantedBy=default.target 是 rootless 慣例，rootful 需手動改為 multi-user.target。
podlet 產生的檔案不包含 [Service] 區段，需手動補上。
寫入受保護路徑一律使用 sudo tee，避免重導向權限問題。
SSL 私鑰必須為 PKCS8 格式，Logstash HTTP input plugin 不接受一般 PEM 格式的 key。
憑證目錄 /etc/logstash/certs/ 以 ro（唯讀）掛載進容器。
環境變數檔 /etc/logstash/logstash.env 權限務必為 0600。
如需修改任何環境變數，編輯 env 檔後執行 sudo systemctl restart logstash.service。
如需更新 plugin，重新執行步驟 3 的 build 指令後重啟服務。
如需更換憑證，替換 /etc/logstash/certs/ 下的檔案後重啟服務。
部署前建議用 sudo /usr/libexec/podman/quadlet -dryrun 驗證設定。

Rancher RBAC 實務範例

Mon, 23 Mar 2026 08:55:34 +0800

依據職責與最小權限原則，可將使用者劃分為以下幾個層級

層級	角色	Rancher 角色	權限範圍	核心職責
1	平台管理員	Global Administrator（內建）	全域 — 所有叢集、所有資源完整 CRUD	叢集生命週期管理、全域認證與安全策略 (LDAP/AD/SAML)、使用者帳號與角色分配
2	叢集管理／維運人員	Cluster Owner（內建）	特定叢集 — 完整管理權限，不含平台層級操作	節點健康監控 (cordon/drain)、Namespace 與 Project 規劃、叢集內 RBAC、資源配額調整、ETCD 快照
3a	資安稽核員（長官）	Read Only Administrator（客製）	全域 — 所有叢集僅 get/list/watch	跨叢集合規性稽核，查看所有資源但無法修改或刪除
3b	資安稽核員（一般）	Cluster Reader（客製）	特定叢集 — 僅 get/list/watch	特定叢集合規性稽核，查看該叢集所有資源
4	應用系統／專案管理員	Project Owner（內建）	特定 Project — 所屬 Project 內完整 CRUD	Project 成員管理、Namespace 建立、Workload 部署、ResourceQuota/LimitRange、PVC 管理、監控告警
5	應用程式開發人員	Project Member / Read Only（內建）	特定 Namespace — 授權 Namespace 內操作；正式環境通常僅唯讀	Workload 部署與更新、Service/Ingress 設定、ConfigMap/Secret 使用、日誌查看與 Pod 除錯、HPA 設定

1. 平台管理員

角色概述

平台管理員負責維護 Rancher 平台本身的運作，擁有最高權限（Global Administrator）。

職責範圍

在 Rancher 中，平台管理員可處理跨叢集、平台層級的事務，包括：

叢集生命週期管理 — 建立、匯入、刪除 Rancher 本身及其所管理的所有叢集
全域認證與安全策略設定 — LDAP、AD、SAML 等
使用者帳號與角色分配 — 管理平台上所有使用者的權限

具體權限 (內建)

實作範例 : 設定 Windows AD 的 admin 群組為平台管理員

點選左側清單的 Users & Authentication -> Groups -> Assign Global Roles
選擇群組 -> 僅勾選 Administrator
滑鼠滾到頁面最下方，點選 Save 按鈕儲存

2. 叢集管理、維運人員

角色概述

負責管理特定 DownStream Kubernetes 叢集狀態的 SRE 或維運工程師，此角色是特定叢集的維運、管理者，但非平台管理者。

職責範圍

Cluster Admin 專注在自己管理的叢集內。日常工作包括：

node 的健康監控與管理（cordon、drain、新增和刪除節點）
namespace 與 project 的規劃
叢集內的 RBAC 設定（指派 Project owner 等角色）
硬體資源配額的調整
Netwrok policy 的管理
對 ETCD Take Snapshot
叢集層級的日誌和監控設定

具體權限 (內建)

實作範例 : 設定 Windows AD 的 infra 群組為基礎架構維運人員

點選左側選單 Cluster Management -> 找到要管理的 K8s 叢集 -> 點選最右側的三點選單 -> Edit Config
選擇 Member Roles -> Add 按鈕
選擇群組 -> 勾選 Owner 權限 -> Add 按鈕
點選右下角 Save 按鈕儲存

在 NeuVector 通常賦予 CI/CD 操作權限，允許在維運過程中觸發掃描或排除誤判，確保服務穩定。

3. 資訊安全稽核員

角色概述

資安部門長官或一般人員進行合規性的稽核作業。

職責範圍

長官可以讀取所有叢集(包含 local Cluster)的所有資源，但不具備編輯或刪除的其他權限。
一般人員只能讀取特定叢集的所有資源。

具體權限 (客製化) - Read Only Administrator

具體權限 (客製化) - Cluster Reader

建立 Global Read-only Administrator Roletemplate

cat <<'EOF' | kubectl apply -f -
apiVersion: management.cattle.io/v3
builtin: false
context: cluster
description: ''
displayName: View Cluster Resources for Readonly Admin
external: false
hidden: true
kind: RoleTemplate
metadata:
name: cluster-readonly-view
rules:
- apiGroups:
- ''
resources:
- secrets
verbs:
- get
- list
- watch
- apiGroups:
- catalog.cattle.io
resources:
- clusterrepos
- apps
verbs:
- get
- list
- watch
- apiGroups:
- management.cattle.io
resourceNames:
- local
resources:
- clusters
verbs:
- get
---
apiVersion: management.cattle.io/v3
builtin: false
displayName: Read Only Administrator
description: '全域唯讀管理員角色，不具備任何建立、修改或刪除操作的權限。'
inheritedClusterRoles:
- projects-view
- nodes-view
- cluster-readonly-view
kind: GlobalRole
metadata:
name: global-read-only
rules:
- apiGroups:
- management.cattle.io
resources:
- projectroletemplatebindings
- clusterroletemplatebindings
verbs:
- get
- list
- watch
- apiGroups:
- management.cattle.io
resources:
- globalroles
- globalrolebindings
verbs:
- get
- list
- watch
- apiGroups:
- project.cattle.io
resources:
- apps
verbs:
- get
- list
- watch
- apiGroups:
- project.cattle.io
resources:
- apprevisions
verbs:
- get
- list
- watch
- apiGroups:
- management.cattle.io
resources:
- nodes
- nodepools
verbs:
- get
- list
- watch
- apiGroups:
- management.cattle.io
resources:
- roletemplates
verbs:
- get
- list
- watch
- apiGroups:
- management.cattle.io
resources:
- clusterevents
verbs:
- get
- list
- watch
- apiGroups:
- management.cattle.io
resources:
- notifiers
verbs:
- get
- list
- watch
- apiGroups:
- management.cattle.io
resources:
- notificationtemplates
verbs:
- get
- list
- watch
- apiGroups:
- management.cattle.io
resources:
- projectalertgroups
- projectalertrules
verbs:
- get
- list
- watch
- apiGroups:
- management.cattle.io
resources:
- projectloggings
verbs:
- get
- list
- watch
- apiGroups:
- management.cattle.io
resources:
- clusteralertgroups
- clusteralertrules
verbs:
- get
- list
- watch
- apiGroups:
- management.cattle.io
resources:
- clustercatalogs
verbs:
- get
- list
- watch
- apiGroups:
- management.cattle.io
resources:
- projectcatalogs
verbs:
- get
- list
- watch
- apiGroups:
- management.cattle.io
resources:
- projectmonitorgraphs
verbs:
- get
- list
- watch
- apiGroups:
- management.cattle.io
resources:
- catalogtemplates
verbs:
- get
- list
- watch
- apiGroups:
- management.cattle.io
resources:
- catalogtemplateversions
verbs:
- get
- list
- watch
- apiGroups:
- management.cattle.io
resources:
- projects
verbs:
- get
- list
- watch
- apiGroups:
- management.cattle.io
resources:
- clusters
verbs:
- get
- list
- watch
- apiGroups:
- management.cattle.io
resources:
- principals
verbs:
- get
- list
- watch
- apiGroups:
- management.cattle.io
resources:
- users
- userattribute
- groups
- groupmembers
verbs:
- get
- list
- watch
- apiGroups:
- management.cattle.io
resources:
- clusterloggings
verbs:
- get
- list
- watch
- apiGroups:
- management.cattle.io
resources:
- clustermonitorgraphs
verbs:
- get
- list
- watch
- apiGroups:
- management.cattle.io
resources:
- preferences
verbs:
- '*'
- apiGroups:
- management.cattle.io
resources:
- settings
verbs:
- get
- list
- watch
- apiGroups:
- management.cattle.io
resources:
- features
verbs:
- get
- list
- watch
- apiGroups:
- management.cattle.io
resources:
- templates
- templateversions
- catalogs
verbs:
- get
- list
- watch
- apiGroups:
- management.cattle.io
resources:
- nodedrivers
verbs:
- get
- list
- watch
- apiGroups:
- management.cattle.io
resources:
- kontainerdrivers
verbs:
- get
- list
- watch
- apiGroups:
- management.cattle.io
resources:
- operatorsettings
verbs:
- get
- list
- watch
- apiGroups:
- management.cattle.io
resources:
- podsecuritypolicytemplates
verbs:
- get
- list
- watch
- apiGroups:
- management.cattle.io
resources:
- nodetemplates
verbs:
- get
- list
- watch
- apiGroups:
- management.cattle.io
resources:
- multiclusterapps
- globaldnses
- globaldnsproviders
- clustertemplaterevisions
- clustertemplates
verbs:
- get
- list
- watch
- apiGroups:
- management.cattle.io
resources:
- rkek8ssystemimages
verbs:
- get
- list
- watch
- apiGroups:
- management.cattle.io
resources:
- rkek8sserviceoptions
verbs:
- get
- list
- watch
- apiGroups:
- management.cattle.io
resources:
- rkeaddons
verbs:
- get
- list
- watch
- apiGroups:
- management.cattle.io
resources:
- cisconfigs
verbs:
- get
- list
- watch
- apiGroups:
- management.cattle.io
resources:
- cisbenchmarkversions
- clusterscans
verbs:
- get
- list
- watch
- apiGroups:
- management.cattle.io
resources:
- etcdbackups
verbs:
- get
- list
- watch
- apiGroups:
- catalog.cattle.io
resources:
- clusterrepos
verbs:
- get
- list
- watch
- apiGroups:
- provisioning.cattle.io
resources:
- clusters
verbs:
- get
- list
- watch
- apiGroups:
- ''
resources:
- nodes
verbs:
- get
- list
- watch
- apiGroups:
- '*'
resources:
- secrets
verbs:
- get
- list
- watch
EOF

在 local Cluster 建立 cluster-reader Roletemplate 執行以下命令

cat <<'EOF' | kubectl apply -f -
apiVersion: management.cattle.io/v3
kind: RoleTemplate
metadata:
name: cluster-reader
displayName: Cluster Reader
description: "提供叢集層級的唯讀權限，可查看所有資源但無法修改。"
# context 設定為 cluster 表示此角色應用於集群層級
context: cluster
# builtin 設定為 false 表示這是自定義角色
builtin: false
clusterCreatorDefault: true
rules:
- apiGroups:
- '*'
resources:
- '*'
verbs:
- get
- list
- watch
EOF

實作範例 1 : 設定 Windows AD 的特定 User 為 Read Only Administrator

Users & Authentication -> Users -> 選擇使用者 -> 三點選單 -> Edit Config
找到 Custom 區塊 -> 勾選 Read Only Administrator -> 右下角 Save 按鈕

實作範例 2 : 設定 Windows AD 的特定 User 為 Cluster Reader

左側選單點進要管理的叢集 -> Cluster -> Cluster and Project Members -> Add
Select Member 選擇特定 User -> 選擇 Cluster Reader -> Create

4. 應用系統/專案管理員

角色概述

負責管理特定 Downstream Kubernetes 叢集中，特定 Project 底下的所有資源與權限。對應 Rancher 的 Project Owner 角色，通常由各應用系統的 Tech Lead、專案負責人或 AP 維運組長擔任。

職責範圍

在 Rancher 中，應用系統/專案管理員可在其所屬 Project 範圍內處理以下事務：

Project 成員管理 — 負責新增、移除及調整 Project 內成員的角色與權限，為該 Project 的最高管理者
Namespace 規劃與建立 — 依據應用模組或環境需求，在 Project 下建立與管理 Namespace
應用部署與生命週期管理 — 管理 Project 內所有 Workload、Service、Cronjob 等應用資源的部署與更新
資源配額管控 — 設定 Project 層級與 Namespace 層級的 ResourceQuota / LimitRange，確保資源使用不超出分配額度
儲存資源管理 — 為應用申請與管理持久化儲存空間(PVC)，並可查看叢集可用的 StorageClass
監控與告警設定 — 設定 Project 層級的監控規則與告警通知，確保應用異常時能即時回應
基礎設施資訊查看 — 可查看叢集節點狀態與叢集事件，了解底層運行狀況

具體權限 (內建)

實作範例 : 設定 Windows AD 的特定 User 為 Project Owner

左側選單選擇目標 K8s 叢集 -> Cluster and Project Members -> Project Membership -> Add
選擇 User -> 選擇 Owner -> Create

5. 應用程式開發人員

角色概述

負責在被授權的 Project 內進行應用程式的部署、除錯與日常維運操作。對應 Rancher 的 Project Member 或 Read-Only 角色，通常由應用開發工程師或 DevOps 工程師擔任。透過 Rancher 的專案 (Project) 機制，限制他們只能在配發的 Namespace 內部署應用程式與查看 Log。他們無法看見亦無法影響其他團隊的資源或底層基礎建設。

職責範圍

在 Rancher 中，應用程式開發人員可在其所屬 Project 的已授權 Namespace 內執行以下操作：

Workload 部署與管理 — 建立、更新、刪除 Deployment、StatefulSet、Job、CronJob 等Workloads
服務與路由設定 — 建立及修改 Service、Ingress，設定應用的對內與對外存取路徑
組態與密鑰使用 — 建立及編輯自身應用所需的 ConfigMap 與 Secret（依權限範圍）
應用日誌查看 — 透過 Rancher 介面查看 Pod 即時日誌，進行問題排查
Pod 除錯操作 — 使用 kubectl exec / Rancher Shell 進入 App Container 進行偵錯，查看 Pod 事件與狀態
彈性伸縮設定 — 設定 HPA (Horizontal Pod Autoscaler)，調整副本數因應流量變化
CI/CD 管線觸發 — 配合 Pipeline 執行應用的建置與部署流程
正式環境（Production）唯讀除錯 — 在正式環境中，開發人員通常僅具備唯讀（Read-Only）權限，只能查看日誌與監控儀表板以協助排查線上問題，無權直接修改系統配置或重啟服務。

具體權限 (內建) - Project Member

具體權限 (內建) - Project Read only

實作範例 : 設定 Windows AD 的特定 User 為 Project Member

左側選單選擇目標 K8s 叢集 -> Cluster and Project Members -> Project Membership -> Add
選擇 User -> 選擇 Owner -> Create

[Rancher] Downstream cluster 因 cattle-controllers leader lease 過期未釋放而顯示「Waiting for cluster agent to connect」

Mon, 23 Mar 2026 03:48:34 +0800

環境

SUSE Rancher Manager v2.13.2（HA 部署，3 個 replicas）
RKE2 v1.34.4+rke2r1 downstream cluster（3 台 control plane + 3 台 worker 節點）
SUSE Linux Enterprise Server 15 SP7
管理叢集與 downstream cluster 皆使用 Kubernetes v1.34.x

狀況

在 Rancher deployment 更新（例如 rollout restart、Helm upgrade 或 pod 重新排程）之後，一個或多個 downstream cluster 在 Rancher UI 上進入 Reconciling 或 Updating 狀態。受影響的 machine 顯示以下訊息：

Waiting for cluster agent to connect

叢集本身功能完全正常 — 所有節點為 Ready，所有 pod 皆在運行，對 downstream cluster 執行 kubectl 指令也能正常回應。然而 Rancher UI 持續顯示叢集處於已斷線狀態。

症狀

Rancher UI 顯示叢集狀態為 Updating，且一台或多台 machine 處於 Reconciling 狀態，並附帶訊息「Waiting for cluster agent to connect」。
Downstream cluster 的 cattle-cluster-agent 日誌顯示已成功建立 WebSocket 連線至 Rancher server：
```
Connected to proxy url="wss://rancher.example.com/v3/connect/register"
```

儘管看似已連線，但 Rancher server 的日誌顯示 tunnel 認證失敗：

Failed to handle tunnel request from remote address 10.42.x.x:xxxxx
(X-Forwarded-For: x.x.x.x): response 401: failed authentication

管理叢集的 clusters.management.cattle.io 物件顯示 Connected: False：
```
type: Connected
status: "False"
```

Provisioning cluster 的 conditions 顯示：

type: Updated
status: Unknown
message: "configuring bootstrap node(s) custom-xxxxxxxx: waiting for cluster agent to connect"
type: Ready
status: "False"
message: "Cluster agent is not connected"
reason: Disconnected

kube-system namespace 中的 cattle-controllers leader lease 指向一個已不存在的 pod：

$ kubectl get lease cattle-controllers -n kube-system -o yaml
spec:
 holderIdentity: rancher-<old-replicaset>-<old-pod>
 leaseDurationSeconds: 162000

原因

Rancher 的 management controllers（負責叢集狀態調解、tunnel 認證、agent 部署與 machine 狀態更新）使用 kube-system namespace 中名為 cattle-controllers 的 Kubernetes Lease 物件進行 leader election。只有 leader pod 才會處理叢集管理操作。

當 Rancher deployment 更新（rolling restart、Helm upgrade 等）時，舊的 pod 會被終止並由新 ReplicaSet 的新 pod 取代。然而，Rancher 將 cattle-controllers lease 的 leaseDurationSeconds 設定為 162,000 秒（45 小時）。這是刻意設定的長時間值，目的是避免短暫網路中斷時發生不必要的 leader 切換。

問題發生的流程如下：

當前的 leader pod 在 deployment 更新過程中被終止。
過期的 lease 仍然指向已終止 pod 的身份識別。
新的 Rancher pod 檢查 lease 後發現 renewTime + leaseDurationSeconds 尚未到期。
所有新 pod 等待 lease 自然過期 — 最長需要等待 45 小時。
在這段等待期間，沒有任何 management controller 在運作，導致所有 downstream cluster 的管理操作停擺。

這會引發一連串連鎖故障：

Cluster agent 的 tunnel 認證請求無人處理（401 錯誤）。
Cluster 物件上的 Connected 狀態永遠不會被更新。
Machine reconciliation 不會被執行。
Rancher UI 持續反映過期的「Waiting for cluster agent to connect」狀態。

解決方案

立即修復

刪除過期的 leader lease，讓當前的 Rancher pod 立即取得 leadership：

kubectl delete lease cattle-controllers -n kube-system

在 30 秒內，一個新的 Rancher pod 將取得 lease，management controllers 將恢復正常運作。驗證新的 leader：

kubectl get lease cattle-controllers -n kube-system \
 -o jsonpath='{.spec.holderIdentity}'

確認 holder identity 與當前運行中的 Rancher pod 相符：

kubectl get pods -n cattle-system -l app=rancher -o name

在 lease 被取得之後，downstream cluster 的狀態應在 1–3 分鐘內從 Updating/Reconciling 轉為 Active。

驗證

確認叢集已恢復連線：

kubectl get clusters.management.cattle.io <cluster-id> \
 -o jsonpath='{.status.conditions[?(@.type=="Connected")]}' | python3 -m json.tool

預期輸出："status": "True"

在 Rancher UI 確認所有 machine 都顯示 Running 狀態。
驗證對所有節點上的 pod 執行 kubectl logs 時不再出現 502 錯誤。

預防措施

為降低未來 Rancher 更新時再次遇到此問題的影響：

在更新後監控 lease。 每次 Rancher deployment 重啟或升級後，驗證 cattle-controllers lease 是否指向正在運行的 pod：

LEADER=$(kubectl get lease cattle-controllers -n kube-system \
 -o jsonpath='{.spec.holderIdentity}')
kubectl get pod -n cattle-system "$LEADER" 2>/dev/null \
 || echo "警告：Leader pod $LEADER 不存在 — lease 已過期"

將 lease 檢查納入升級手冊。 在您的標準 Rancher 升級流程中，於 rollout 完成後立即加入 lease 驗證步驟。
考慮提交 feature request。 162,000 秒（45 小時）的 lease 過期時間設定過於保守。較短的過期時間（例如 300–600 秒）可以縮短 failover 視窗，同時仍能提供對短暫網路中斷的韌性。

診斷步驟摘要

以下指令用於診斷此問題，可在類似的故障排查中重複使用：

步驟	指令	用途
1	`kubectl get nodes -o wide`	驗證 downstream cluster 節點健康狀態
2	`kubectl get pods -n cattle-system -o wide`	檢查 cluster agent 狀態
3	`kubectl logs -n cattle-system -l app=rancher \| grep "401\|tunnel\|failed auth"`	在 Rancher server 上尋找 tunnel 認證失敗訊息
4	`kubectl get clusters.management.cattle.io <id> -o jsonpath='{.status.conditions}'`	檢查 Connected 狀態
5	`kubectl get clusters.provisioning.cattle.io -n fleet-default <n> -o jsonpath='{.status.conditions}'`	檢查 provisioning conditions
6	`kubectl get lease cattle-controllers -n kube-system -o yaml`	識別過期的 leader lease
7	`kubectl get pods -n cattle-system -l app=rancher -o name`	比對 lease holder 與運行中的 pod

補充資訊

此問題可能同時影響任意數量的 downstream cluster，因為所有叢集管理操作皆依賴單一的 cattle-controllers leader。
此問題不限於 Rancher v2.13.x，任何使用長 leaseDurationSeconds 設定的 cattle-controllers lease 版本都可能發生。
在此期間，downstream cluster 本身保持完全正常運作。僅 Rancher 的 management plane 操作受到影響。
刪除 lease 是非破壞性操作。新的 leader 將根據系統的當前狀態從頭開始重新調解所有叢集狀態。

Install ArgoCD on Rancher RKE2

Fri, 20 Mar 2026 07:58:28 +0800

1. Install ArgoCD

執行以下命令

kubectl create namespace argocd
kubectl apply -n argocd --server-side --force-conflicts -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml

Wait for all pods to be ready

kubectl wait --for=condition=Ready pods --all -n argocd --timeout=300s

執行結果：

pod/argocd-application-controller-0 condition met
pod/argocd-applicationset-controller-7dc85c9598-m4rrd condition met
pod/argocd-dex-server-7d88b5b798-jq58x condition met
pod/argocd-notifications-controller-5f95df7f8c-x94js condition met
pod/argocd-redis-65b5bbd8cb-jw27t condition met
pod/argocd-repo-server-69fb9fb66f-hgvrg condition met
pod/argocd-server-58dbdffdcd-4qz8l condition met

expose ArgoCD with ingress

cat << 'EOF' | kubectl apply -f -
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: argocd-server
namespace: argocd
annotations:
nginx.ingress.kubernetes.io/ssl-passthrough: "true"
nginx.ingress.kubernetes.io/backend-protocol: "HTTPS"
spec:
ingressClassName: nginx
rules:
- host: argocd.kubeantony.com
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: argocd-server
port:
number: 443
EOF

Grafana Reporter 部署指南（Harvester / Rancher 環境）

Wed, 11 Mar 2026 02:27:26 +0800

概述

本文件說明如何在 Harvester（Rancher 管理）環境中部署 IzakMarais/reporter，讓 Grafana Dashboard 能一鍵產生 PDF 報表，並透過 Rancher Proxy 對外存取。

架構說明

瀏覽器
│
▼
Rancher API Proxy（https://hvx.kubeantony.com/api/v1/namespaces/...）
│
├──► grafana-reporter（:8686）──► Grafana（:80）──► Prometheus
│
└──► grafana-image-renderer（:8081）◄── Grafana（render 請求）

Grafana Reporter：接收使用者請求，透過 Grafana API 取得 Dashboard 資料與面板圖片，產生 PDF。
Grafana Image Renderer：Grafana 的圖片渲染服務，將面板渲染為 PNG 圖片供 Reporter 使用。
所有元件都部署在 cattle-monitoring-system namespace 內，透過 K8s 內部 Service 互連。

前置確認

# 確認 Grafana Service 名稱
kubectl get svc -n cattle-monitoring-system | grep grafana

記下 Grafana 的 Service 名稱（通常為 rancher-monitoring-grafana），後續設定會用到。

步驟一：部署 Grafana Reporter

建立 grafana-reporter.yaml：

apiVersion: apps/v1
kind: Deployment
metadata:
 name: grafana-reporter
 namespace: cattle-monitoring-system
spec:
 replicas: 1
 selector:
 matchLabels:
 app: grafana-reporter
 template:
 metadata:
 labels:
 app: grafana-reporter
 spec:
 containers:
 - name: grafana-reporter
 image: izakmarais/grafana-reporter:latest
 command: ["/usr/local/bin/grafana-reporter"]
 args:
 - "-ip"
 - "rancher-monitoring-grafana.cattle-monitoring-system.svc:80"
 ports:
 - containerPort: 8686
---
apiVersion: v1
kind: Service
metadata:
 name: grafana-reporter
 namespace: cattle-monitoring-system
spec:
 selector:
 app: grafana-reporter
 ports:
 - name: http
 port: 8686
 targetPort: 8686
 protocol: TCP
 type: ClusterIP

部署：

kubectl apply -f grafana-reporter.yaml

驗證：

# 確認 Pod 狀態為 Running
kubectl get pods -n cattle-monitoring-system | grep reporter

# 確認 log 顯示正確連線 Grafana
kubectl logs -n cattle-monitoring-system -l app=grafana-reporter

預期 log 輸出：

serving at ':8686' and using grafana at 'http://rancher-monitoring-grafana.cattle-monitoring-system.svc:80'

步驟二：部署 Grafana Image Renderer

Rancher Monitoring Chart 的 imageRenderer.enabled 有已知 template bug，因此採用手動獨立部署。

建立 image-renderer.yaml：

apiVersion: apps/v1
kind: Deployment
metadata:
 name: grafana-image-renderer
 namespace: cattle-monitoring-system
spec:
 replicas: 1
 selector:
 matchLabels:
 app: grafana-image-renderer
 template:
 metadata:
 labels:
 app: grafana-image-renderer
 spec:
 containers:
 - name: image-renderer
 image: grafana/grafana-image-renderer:latest
 ports:
 - containerPort: 8081
 env:
 - name: ENABLE_METRICS
 value: "true"
---
apiVersion: v1
kind: Service
metadata:
 name: grafana-image-renderer
 namespace: cattle-monitoring-system
spec:
 selector:
 app: grafana-image-renderer
 ports:
 - port: 8081
 targetPort: 8081
 type: ClusterIP

部署：

kubectl apply -f image-renderer.yaml

驗證：

kubectl get pods -n cattle-monitoring-system | grep image-renderer

步驟三：設定 Grafana 連線 Image Renderer

重點： 僅設定環境變數不夠，必須修改 grafana.ini 設定檔，Grafana 才會識別 renderer。

3-1. 編輯 Grafana ConfigMap

kubectl edit configmap rancher-monitoring-grafana -n cattle-monitoring-system

在 grafana.ini 最末尾加入 [rendering] 區塊：

 [rendering]
 server_url = http://grafana-image-renderer.cattle-monitoring-system.svc:8081/render
 callback_url = http://rancher-monitoring-grafana.cattle-monitoring-system.svc:80/

完整的 grafana.ini 範例：

 [analytics]
 check_for_updates = true
 [auth]
 disable_login_form = false
 [auth.anonymous]
 enabled = true
 org_role = Viewer
 [auth.basic]
 enabled = false
 [dashboards]
 default_home_dashboard_path = /tmp/dashboards/rancher-default-home.json
 [grafana_net]
 url = https://grafana.net
 [log]
 mode = console
 [paths]
 data = /var/lib/grafana/
 logs = /var/log/grafana
 plugins = /var/lib/grafana/plugins
 provisioning = /etc/grafana/provisioning
 [security]
 allow_embedding = true
 [server]
 domain = ''
 [users]
 auto_assign_org_role = Viewer
 [rendering]
 server_url = http://grafana-image-renderer.cattle-monitoring-system.svc:8081/render
 callback_url = http://rancher-monitoring-grafana.cattle-monitoring-system.svc:80/

3-2. 重啟 Grafana

kubectl rollout restart deployment rancher-monitoring-grafana -n cattle-monitoring-system

3-3. 驗證 Renderer 連線

# 從 Grafana Pod 測試連線 renderer
kubectl exec -n cattle-monitoring-system \
 $(kubectl get pods -n cattle-monitoring-system -l app.kubernetes.io/name=grafana \
 -o jsonpath='{.items[0].metadata.name}') \
 -- curl -s http://grafana-image-renderer.cattle-monitoring-system.svc:8081/

預期回應：

Grafana Image Renderer (Go)

也可以在 Grafana UI 中驗證：Administration → Plugins → 搜尋 “Image Renderer”，應顯示為 remote rendering service。

步驟四：測試 Rancher Proxy 存取 Reporter

在瀏覽器中打開以下 URL（將 <DASHBOARD_UID> 替換為實際的 Dashboard UID）：

https://hvx.kubeantony.com/api/v1/namespaces/cattle-monitoring-system/services/http:grafana-reporter:8686/proxy/api/v5/report/<DASHBOARD_UID>

如果能下載 PDF 且包含圖表，代表全部設定正確。

步驟五：設定 Grafana Dashboard Link

進入目標 Dashboard
點右上角 齒輪圖示（Dashboard Settings）
點左側 Links 頁籤
點 + New link，填入以下設定：

欄位	值
Type	link
Title	reports
URL	見下方
Icon	doc
Open in new tab	✅ 打勾

URL 設定：

https://hvx.kubeantony.com/api/v1/namespaces/cattle-monitoring-system/services/http:grafana-reporter:8686/proxy/api/v5/report/${__dashboard.uid}?from=${__from}&to=${__to}

如果 Dashboard 有使用變數（如 datasource、instance），可以加上：

https://hvx.kubeantony.com/api/v1/namespaces/cattle-monitoring-system/services/http:grafana-reporter:8686/proxy/api/v5/report/${__dashboard.uid}?from=${__from}&to=${__to}&var-datasource=${datasource}&var-instance=${instance}

點 Save dashboard

設定完成後，Dashboard 右上方會出現 reports 連結，點擊即可在新分頁下載 PDF 報表。

疑難排解

PDF 產生但沒有圖表

# 檢查 Grafana log 是否有 renderer 錯誤
kubectl logs -n cattle-monitoring-system \
 $(kubectl get pods -n cattle-monitoring-system -l app.kubernetes.io/name=grafana \
 -o jsonpath='{.items[0].metadata.name}') \
 -c grafana --tail=50 | grep rendering

如果看到 no image renderer found/installed，代表 grafana.ini 的 [rendering] 設定未生效，請重新確認 ConfigMap 並重啟 Grafana。

Reporter 無法連線 Grafana

# 確認 Grafana Service 存在且可連線
kubectl exec -n cattle-monitoring-system \
 $(kubectl get pods -n cattle-monitoring-system -l app=grafana-reporter \
 -o jsonpath='{.items[0].metadata.name}') \
 -- wget -qO- http://rancher-monitoring-grafana.cattle-monitoring-system.svc:80/api/health

Rancher Proxy 回傳 404

確認 Service 已正確建立：

kubectl get svc -n cattle-monitoring-system grafana-reporter

Rancher Proxy URL 格式必須完全正確：

https://<rancher域名>/api/v1/namespaces/<namespace>/services/http:<service名稱>:<port>/proxy/

注意事項

透過 kubectl edit 修改的 ConfigMap 和 Deployment，在下次 Rancher Monitoring Helm Chart 升級時可能被覆蓋。升級後需重新確認 [rendering] 設定是否仍存在。
Image Renderer 和 Reporter 是獨立部署的，不受 Helm Chart 升級影響。
如果未來 Rancher 修復了 image-renderer-deployment.yaml 的 template bug，可以改回透過 Helm values 啟用 grafana.imageRenderer.enabled: true，屆時可移除手動部署的 image-renderer。

Install Minio with Rancher Application Collection

Mon, 09 Mar 2026 07:40:36 +0800

Prepare

helm login Rancher Application Collection

helm registry login dp.apps.rancher.io \
-u <user> \
-p <password>

download helm chart

helm pull oci://dp.apps.rancher.io/charts/minio --version 5.4.0

Create Namespace
```
kubectl create ns minio
```

建立 Image Pull Secret

kubectl -n minio create secret docker-registry application-collection \
--docker-server=dp.apps.rancher.io \
--docker-username=<user> \
--docker-password=<password>

確認已安裝 Ingress Controller 和 StorageClass (本篇文章用的是 Nginx 和 local-path)

確認當前 K8s 叢集的 Ingress Controller

kubectl get ingressclasses.networking.k8s.io

執行結果：

NAME CONTROLLER PARAMETERS AGE
nginx k8s.io/ingress-nginx <none> 7d

確認當前 K8s 叢集的 StorageClass

kubectl get sc local-path

執行結果：

NAME PROVISIONER RECLAIMPOLICY VOLUMEBINDINGMODE ALLOWVOLUMEEXPANSION AGE
local-path (default) rancher.io/local-path Delete WaitForFirstConsumer false 6d3h

確認已安裝 Cert-manager

kubectl -n cert-manager get pods

執行結果：

NAME READY STATUS RESTARTS AGE
cert-manager-578bff8c75-ms6hw 1/1 Running 0 41m
cert-manager-cainjector-566b8f9766-pxnlb 1/1 Running 0 41m
cert-manager-webhook-c9997c6b5-94fsj 1/1 Running 0 41m

Deploy

解壓縮 minio chart
```
tar -zxvf minio-5.4.0.tgz; cd minio
```

定義 MinIO 自簽憑證的簽發架構

mkdir cert-manager/; vim minio-pki-bootstrap.yaml

檔案內容如下：

apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
name: selfsigned-issuer
spec:
selfSigned: {}
---
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
name: selfsigned-ca
namespace: minio
spec:
isCA: true
commonName: selfsigned-ca
secretName: root-secret
privateKey:
algorithm: ECDSA
size: 256
issuerRef:
name: selfsigned-issuer
kind: ClusterIssuer
group: cert-manager.io
---
apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
name: ca-issuer
namespace: minio
spec:
ca:
secretName: root-secret

檔案包含三個資源：

ClusterIssuer（自簽發行者）

Certificate（作為 Root CA 的自簽憑證，使用 ECDSA P-256 演算法，並將私鑰跟憑證都存入 Secret root-secret）

以及 Issuer（引用該 Root CA 來簽發後續憑證）

將上述資源套用至叢集，Cert-manager 會自動產生 Root CA 憑證與私鑰，並建立可用於 minio namespace 中後續憑證簽發的 CA Issuer。
```
kubectl apply -f cert-manager/minio-pki-bootstrap.yaml
```

撰寫 minio values.yaml

vim custom-values.yaml

檔案內容如下：

global:
imagePullSecrets:
- application-collection
mode: standalone
persistence:
size: 5Gi
resources:
requests:
memory: 512Mi
rootPassword: admin123
rootUser: admin
ingress:
enabled: true
ingressClassName: nginx
annotations:
nginx.ingress.kubernetes.io/proxy-body-size: "0"
cert-manager.io/issuer: ca-issuer
path: /
hosts:
- api.minio.kubeantony.com
tls:
- secretName: minio-api-tls
hosts:
- api.minio.kubeantony.com
consoleIngress:
enabled: true
ingressClassName: nginx
annotations:
cert-manager.io/issuer: ca-issuer
path: /
hosts:
- console.minio.kubeantony.com
tls:
- secretName: minio-console-tls
hosts:
- console.minio.kubeantony.com

部署 Minio

helm -n minio upgrade --install minio . -f custom-values.yaml

執行結果：

Release "minio" has been upgraded. Happy Helming!
NAME: minio
LAST DEPLOYED: Mon Mar 9 14:40:55 2026
NAMESPACE: minio
STATUS: deployed
REVISION: 9
TEST SUITE: None
NOTES:
MinIO can be accessed via port 9000 on the following DNS name from within your cluster:
minio.minio.cluster.local
To access MinIO from localhost, run the below commands:
1. export POD_NAME=$(kubectl get pods --namespace minio -l "release=minio" -o jsonpath="{.items[0].metadata.name}")
2. kubectl port-forward $POD_NAME 9000 --namespace minio
Read more about port forwarding here: http://kubernetes.io/docs/user-guide/kubectl/kubectl_port-forward/
You can now access MinIO server on http://localhost:9000. Follow the below steps to connect to MinIO server with mc client:
1. Download the MinIO mc client - https://min.io/docs/minio/linux/reference/minio-mc.html#quickstart
2. export MC_HOST_minio-local=http://$(kubectl get secret --namespace minio minio -o jsonpath="{.data.rootUser}" | base64 --decode):$(kubectl get secret --namespace minio minio -o jsonpath="{.data.rootPassword}" | base64 --decode)@localhost:9000
3. mc ls minio-local

確認 Minio Pods 有正常運作

kubectl -n minio get pods

執行結果：

NAME READY STATUS RESTARTS AGE
minio-7f67bcc94c-7hcc5 1/1 Running 0 3h58m

查看 Ingress

kubectl -n minio get ing

執行結果：

NAME CLASS HOSTS ADDRESS PORTS AGE
minio nginx api.minio.kubeantony.com 192.168.11.154,192.168.11.155,192.168.11.156 80, 443 3h52m
minio-console nginx console.minio.kubeantony.com 192.168.11.154,192.168.11.155,192.168.11.156 80, 443 3h29m

打開瀏覽器，連線至 Minio 管理網站
```
https://console.minio.kubeantony.com/
```
確認打開瀏覽器的電腦能透過 DNS 解析 Minio FQDN 的 IP

Podman Deploy Neuvector AllInOne

Wed, 04 Mar 2026 15:58:24 +0800

Deploy allinone (NO privileged mode) with podman

1. 準備環境

建立 NeuVector 用於持久化儲存設定檔的目錄
```
sudo mkdir /var/neuvector
```
設定開機自動啟動並立即啟動 Podman socket
```
sudo systemctl enable --now podman.socket
```

建立一個 systemd 服務，將 Podman 的 socket 軟連結到傳統 Docker 的 socket 路徑，這是為了讓需要和 Docker API 互動的應用程式 (如此處的 NeuVector) 能無縫地與 Podman 運作

sudo tee /etc/systemd/system/podman-docker-symlink.service <<'EOF'
[Unit]
Description=Create symlink from docker.sock to podman.sock
After=podman.socket
[Service]
Type=oneshot
ExecStart=/bin/ln -sf /run/podman/podman.sock /var/run/docker.sock
RemainAfterExit=yes
[Install]
WantedBy=multi-user.target
EOF

設定開機自動啟動並立即啟動建立 symlink 的服務
```
sudo systemctl enable --now podman-docker-symlink.service
```

2. 建立 NeuVector 內部元件 (Controller, Enforcer, Scanner) 之間加密通訊所需的 TLS 憑證

sudo mkdir -p /etc/neuvector/certs/internal; cd /etc/neuvector/certs/internal

建立 OpenSSL 設定檔，用於定義憑證的內容 (如國家、組織、SANs 等)

sudo tee /etc/neuvector/certs/internal/ca.cfg <<'EOF'
[req]
distinguished_name = req_distinguished_name
x509_extensions = v3_req
prompt = no
[req_distinguished_name]
C = TW
ST = Taipei
L = San Jose
O = NeuVector Inc.
OU = Neuvector
CN = Neuvector
[v3_req]
keyUsage = digitalSignature, keyEncipherment, dataEncipherment
extendedKeyUsage = serverAuth, clientAuth
subjectAltName = @alt_names
[alt_names]
DNS.1 = Neuvector
EOF

產生 CA (憑證頒發機構) 的私鑰
```
sudo openssl genrsa -out ca.key 2048
```

使用 CA 私鑰產生 CA 的根憑證

sudo openssl req -x509 -sha256 -new -nodes -key ca.key -days 3650 -subj "/C=TW/ST=Taipei/L=Taipei/O=NeuVector Inc./OU=Neuvector/CN=Neuvector" -out ca.cert

產生給服務使用的私鑰
```
sudo openssl genrsa -out cert.key 2048
```

產生憑證簽署請求 (CSR)

sudo openssl req -new -key cert.key -sha256 -out cert.csr -config ca.cfg

使用 CA 簽署 CSR，產生最終給服務使用的憑證

sudo openssl x509 -req -sha256 -in cert.csr -CA ca.cert -CAkey ca.key -CAcreateserial -out cert.pem -days 3650 -extensions 'v3_req' -extfile ca.cfg

3. 啟動 NeuVector App Container

動態獲取主機指定網路介面 (此處為 ens18) 的 IP 位址，並存入變數 IP，這個 IP 將用來告訴 NeuVector 元件如何互相連線
```
NIC='ens18' && \
IP=$(ip -4 -o addr show ${NIC} | awk '{print $4}' | cut -d/ -f1)
```

啟動 NeuVector 的 All-in-One main container (包含 Controller, Enforcer, Manager)

sudo podman run -d --name allinone \
--pid=host \
--cap-add=SYS_ADMIN \
--cap-add=NET_ADMIN \
--cap-add=SYS_PTRACE \
--cap-add=IPC_LOCK \
--security-opt label=disable \
--security-opt apparmor=unconfined \
--security-opt seccomp=unconfined \
-e CLUSTER_JOIN_ADDR=${IP} \
-e NV_PLATFORM_INFO=platform=Docker \
-e CTRL_PERSIST_CONFIG=1 \
-p 18300:18300 \
-p 18301:18301 \
-p 18400:18400 \
-p 18401:18401 \
-p 18301:18301/udp \
-p 8443:8443 \
-v /lib/modules:/lib/modules:ro \
-v /var/neuvector:/var/neuvector \
-v /var/run/docker.sock:/var/run/docker.sock:ro \
-v /sys/fs/cgroup:/host/cgroup:ro \
-v /proc:/host/proc:ro \
-v /etc/neuvector/certs/internal:/etc/neuvector/certs/internal/:ro \
docker.io/neuvector/allinone:5.4.9

--pid=host, --cap-add=... 等參數是為了賦予 container 足夠的權限來監控主機的程序與網路活動

-e CLUSTER_JOIN_ADDR=${IP} 設定叢集加入位址

-v 掛載主機路徑，讓 container 能存取 Docker socket、主機核心模組、cgroup 及程序資訊，並持久化設定與讀取憑證

啟動 NeuVector 的 Scanner container，專門用於執行映像檔弱點掃描，它會透過 CLUSTER_JOIN_ADDR 連接到 All-in-One Neuvector Controller

sudo podman run -td --name scanner \
-e CLUSTER_JOIN_ADDR=${IP} \
-e NV_PLATFORM_INFO=platform=Docker \
-p 18402:18402 \
-v /var/run/docker.sock:/var/run/docker.sock:ro \
-v /etc/neuvector/certs/internal:/etc/neuvector/certs/internal/:ro \
docker.io/neuvector/scanner:latest

4. 設定 Neuvector Allinone container 開機自動啟動

建立環境變數檔

sudo mkdir -p /etc/neuvector
sudo tee /etc/neuvector/allinone.env >/dev/null <<'EOF'
# 請把下行改成你的 IP
CLUSTER_JOIN_ADDR=192.168.11.131
NV_PLATFORM_INFO=platform=Docker
CTRL_PERSIST_CONFIG=1
EOF

建立 Quadlet .container 檔案

sudo nano /etc/containers/systemd/allinone.container

設定內容如下：

注意，CLUSTER_JOIN_ADDR 的值需依照環境而設定

[Unit]
Description=NeuVector All-in-One (via Podman Quadlet)
Wants=network-online.target
After=network-online.target
RequiresMountsFor=/var/neuvector /lib/modules /etc/neuvector/certs/internal
[Container]
Image=docker.io/neuvector/allinone:5.4.9
ContainerName=allinone
PodmanArgs=--pid=host --security-opt apparmor=unconfined
AddCapability=SYS_ADMIN
AddCapability=NET_ADMIN
AddCapability=SYS_PTRACE
AddCapability=IPC_LOCK
# 環境變數
EnvironmentFile=/etc/neuvector/allinone.env
# Port 對應（含 UDP）
PublishPort=18300:18300
PublishPort=18301:18301
PublishPort=18400:18400
PublishPort=18401:18401
PublishPort=18301:18301/udp
PublishPort=8443:8443
# Volume 對應
Volume=/lib/modules:/lib/modules:ro
Volume=/var/neuvector:/var/neuvector
Volume=/var/run/docker.sock:/var/run/docker.sock:ro
Volume=/sys/fs/cgroup:/host/cgroup:ro
Volume=/proc:/host/proc:ro
Volume=/etc/neuvector/certs/internal:/etc/neuvector/certs/internal:ro
# 若希望啟動時一定拉一次映像檔，可取消註解
# Pull=always
[Service]
Restart=always
RestartSec=5s
TimeoutStartSec=600
[Install]
WantedBy=multi-user.target

重載 systemd daemon：
```
sudo systemctl daemon-reload
```
啟用並立即啟動服務：
```
sudo systemctl start allinone.service
```
如果噴錯代表 podman Quadlet 的設定檔有寫錯，請執行以下命令確認設定檔哪裡有錯 sudo /usr/libexec/podman/quadlet -dryrun

檢查 systemd 服務狀態：

systemctl status allinone.service

正確執行結果：

● allinone.service - NeuVector All-in-One (via Podman Quadlet)
Loaded: loaded (/etc/containers/systemd/allinone.container; generated)
Active: active (running) since Fri 2025-08-15 17:30:42 CST; 9min ago
Main PID: 3957 (conmon)
Tasks: 83 (limit: 50507)
Memory: 897.2M
CPU: 13.760s
...以下省略

使用 podman 確認容器狀態：

sudo podman ps -a --filter name=allinone

正確執行結果：

CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
7963890f525a docker.io/neuvector/allinone:5.4.9 40 seconds ago Up 41 seconds 0.0.0.0:8443->8443/tcp, 0.0.0.0:10443->10443/tcp, 0.0.0.0:18300-18301->18300-18301/tcp, 0.0.0.0:18400-18401->18400-18401/tcp, 0.0.0.0:18301->18301/udp allinone

5. 設定 Neuvector scanner container 開機自動啟動

建立環境變數檔

sudo tee /etc/neuvector/scanner.env >/dev/null <<'EOF'
# 請把下行改成你的 IP
CLUSTER_JOIN_ADDR=192.168.11.131
NV_PLATFORM_INFO=platform=Docker
EOF

建立 Quadlet .container 檔案

sudo nano /etc/containers/systemd/scanner.container

設定內容如下：

注意，CLUSTER_JOIN_ADDR 的值需依照環境而設定

# /etc/containers/systemd/scanner.container
[Unit]
Description=NeuVector Scanner (via Podman Quadlet)
Wants=network-online.target
After=network-online.target
[Container]
ContainerName=scanner
Image=docker.io/neuvector/scanner:latest
EnvironmentFile=/etc/neuvector/scanner.env
PublishPort=18402:18402
Volume=/var/run/docker.sock:/var/run/docker.sock:ro
Volume=/etc/neuvector/certs/internal:/etc/neuvector/certs/internal:ro
[Install]
WantedBy=multi-user.target

重載 systemd daemon：
```
sudo systemctl daemon-reload
```
啟用並立即啟動服務：
```
sudo systemctl start scanner.service
```
如果噴錯代表 podman Quadlet 的設定檔有寫錯，請執行以下命令確認設定檔哪裡有錯
```
sudo /usr/libexec/podman/quadlet -dryrun
```

檢查 systemd 服務狀態：

sudo systemctl status scanner.service

正確執行結果：

● scanner.service - NeuVector Scanner (via Podman Quadlet)
Loaded: loaded (/etc/containers/systemd/scanner.container; generated)
Active: active (running) since Fri 2025-08-15 17:56:43 CST; 6min ago
Main PID: 4564 (conmon)
Tasks: 12 (limit: 50507)
Memory: 1.8G
CPU: 20.587s
...以下省略

使用 podman 確認 container 狀態：

sudo podman ps -a --filter name=scanner

正確執行結果：

CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
b4fede8ec2ac docker.io/neuvector/scanner:latest 8 minutes ago Up 8 minutes 0.0.0.0:18402->18402/tcp scanner

6. 重新開機測試

將主機重開
```
sudo reboot
```

開機後，檢查 container 狀態

sudo podman ps -a --filter name=scanner --filter name=allinone

正確執行結果：

CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
78a475cb15a3 docker.io/neuvector/scanner:latest 25 seconds ago Up 26 seconds 0.0.0.0:18402->18402/tcp scanner
10bd318a7f4a docker.io/neuvector/allinone:5.4.9 25 seconds ago Up 26 seconds 0.0.0.0:18301->18301/udp, 0.0.0.0:8443->8443/tcp, 0.0.0.0:10443->10443/tcp, 0.0.0.0:18300-18301->18300-18301/tcp, 0.0.0.0:18400-18401->18400-18401/tcp allinone

打開瀏覽器，確認 Neuvector Web Console 是否正常
登入管理網站
- 帳號 : admin
- 密碼 : admin

7. 暴露 Neuvector Metrics

建立 Podman Secret 儲存 admin 帳號的密碼

printf 'admin' | sudo podman secret create neuvector_pass -

啟動 Neuvector Exporter Container

sudo podman run -d \
--name neuvector.prometheus-exporter \
--user 1000:1000 \
-e CTRL_API_SERVICE=192.168.11.131:10443 \
-e CTRL_USERNAME=admin \
--secret neuvector_pass,type=env,target=CTRL_PASSWORD \
-e EXPORTER_PORT=8068 \
--cap-drop=ALL \
--security-opt no-new-privileges:true \
--read-only \
registry.rancher.com/rancher/neuvector-prometheus-exporter:1.0.9

確認 Container 運作狀態

sudo podman ps -a --filter name=neuvector.prometheus-exporter

執行結果:

CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
6acc80576905 registry.rancher.com/rancher/neuvector-prometheus-exporter:1.0.9 7 minutes ago Up 7 minutes neuvector.prometheus-exporter

獲取 Container IP

sudo podman inspect neuvector.prometheus-exporter --format '{{.NetworkSettings.IPAddress}}'

執行結果:

10.88.0.19

測試是否可得到 Metrics

curl -s http://10.88.0.19:8068/ | head -n 5

執行結果:

# HELP python_gc_objects_collected_total Objects collected during gc
# TYPE python_gc_objects_collected_total counter
python_gc_objects_collected_total{generation="0"} 368.0
python_gc_objects_collected_total{generation="1"} 0.0
python_gc_objects_collected_total{generation="2"} 0.0

建立 Quadlet .container 檔案

sudo nano /etc/containers/systemd/neuvector-prometheus-exporter.container

設定內容如下：

注意，CTRL_API_SERVICE 的值需依照環境而設定如果無 TLS 的需求，可將 PublishPort 取消註解並跳過第 11 步驟之後的所有步驟。

[Unit]
Description=NeuVector Prometheus Exporter
After=network-online.target
Wants=network-online.target
[Container]
ContainerName=neuvector.prometheus-exporter
Image=registry.rancher.com/rancher/neuvector-prometheus-exporter:1.0.9
User=1000
Group=1000
# Environment
Environment=CTRL_API_SERVICE=192.168.11.131:10443
Environment=CTRL_USERNAME=admin
Environment=EXPORTER_PORT=8068
# Secret (must be pre-created)
Secret=neuvector_pass,type=env,target=CTRL_PASSWORD
# Security hardening
DropCapability=ALL
SecurityLabelNested=true
NoNewPrivileges=true
ReadOnly=true
# Publish port if external access is needed (uncomment to enable)
# PublishPort=8068:8068
[Service]
Restart=on-failure
TimeoutStartSec=300
[Install]
WantedBy=default.target

重載 systemd daemon：
```
sudo systemctl daemon-reload
```
啟用並立即啟動服務：
```
sudo systemctl start neuvector-prometheus-exporter.service
```
如果噴錯代表 podman Quadlet 的設定檔有寫錯，請執行以下命令確認設定檔哪裡有錯
```
sudo /usr/libexec/podman/quadlet -dryrun
```

檢查 systemd 服務狀態：

sudo systemctl status neuvector-prometheus-exporter.service

正確執行結果：

● neuvector-prometheus-exporter.service - NeuVector Prometheus Exporter
Loaded: loaded (/etc/containers/systemd/neuvector-prometheus-exporter.container; generated)
Active: active (running) since Wed 2026-03-04 21:32:32 CST; 18min ago
Main PID: 7980 (conmon)
Tasks: 4 (limit: 50507)
Memory: 23.6M
CPU: 387ms
...

使用 podman 確認 container 狀態：

sudo podman ps -a --filter name=neuvector.prometheus-exporter

正確執行結果：

CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
6acc80576905 registry.rancher.com/rancher/neuvector-prometheus-exporter:1.0.9 19 minutes ago Up 19 minutes neuvector.prometheus-exporter

請參考以下 Git repo 的 README 做出 TLS 自簽憑證
```
https://github.com/braveantony/mkcert.git
```

建立目錄，並拷貝憑證

mkdir -p ${HOME}/nginx/
cp mkcert/kubeantony.com/kubeantony.com.crt ${HOME}/nginx/server.crt
cp mkcert/kubeantony.com/kubeantony.com.key ${HOME}/nginx/server.key
chmod 644 ${HOME}/nginx/server.key
ls -lZ ${HOME}/nginx/server.*

執行結果:

-rw-r--r--. 1 bigred bigred system_u:object_r:container_file_t:s0:c948,c1020 2167 Mar 4 22:39 /home/bigred/nginx/server.crt
-rw-r--r--. 1 bigred bigred system_u:object_r:container_file_t:s0:c948,c1020 3272 Mar 4 22:39 /home/bigred/nginx/server.key

注意 server.key 權限要設為 644

撰寫 nginx.conf

nano ${HOME}/nginx/nginx.conf

檔案內容如下:

server_name 請依序環境設定，記得在環境中的 DNS Server 將之添加為 A Record

error_log /dev/stderr warn;
worker_processes 4;
worker_rlimit_nofile 40000;
pid /var/run/nginx.pid;
events {
worker_connections 8192;
}
http {
access_log /dev/stdout;
server_tokens off;
add_header X-Content-Type-Options "nosniff" always;
add_header X-Frame-Options "DENY" always;
add_header X-XSS-Protection "1; mode=block" always;
add_header Referrer-Policy "strict-origin-when-cross-origin" always;
client_max_body_size 1m;
client_body_timeout 10s;
client_header_timeout 10s;
send_timeout 10s;
ssl_session_cache shared:SSL:10m;
ssl_session_timeout 10m;
ssl_session_tickets off;
ssl_prefer_server_ciphers on;
# 預設拒絕未匹配的 Host
server {
listen 8443 ssl default_server;
server_name _;
ssl_certificate /etc/nginx/ssl/server.crt;
ssl_certificate_key /etc/nginx/ssl/server.key;
return 444;
}
server {
listen 8443 ssl;
server_name aionv-metrics.kubeantony.com;
ssl_certificate /etc/nginx/ssl/server.crt;
ssl_certificate_key /etc/nginx/ssl/server.key;
ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305;
# add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
location / {
proxy_pass http://neuvector.prometheus-exporter:8068;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_read_timeout 90s;
proxy_connect_timeout 10s;
proxy_send_timeout 10s;
proxy_hide_header X-Powered-By;
}
location ~* ^/(\.env|\.git|wp-admin|phpMyAdmin) {
return 444;
}
}
}

設定 Podman Default Network 啟用 DNS

sudo sed -i '/dns_enabled/s/false/true/' /etc/containers/networks/podman.json
sudo podman network reload --all

建立 Nginx Container

sudo podman run -d --name nginx -p 8068:8443 \
--read-only \
--mount type=tmpfs,destination=/tmp,tmpfs-size=10M,tmpfs-mode=1777,U=true \
--mount type=tmpfs,destination=/var/cache/nginx,tmpfs-size=50M,U=true \
--mount type=tmpfs,destination=/var/run,tmpfs-size=10M,U=true \
--mount type=tmpfs,destination=/var/log/nginx,tmpfs-size=10M,U=true \
--mount type=tmpfs,destination=/var/lib/nginx,tmpfs-size=50M,U=true \
--user $(id -u):$(id -g) \
--cap-drop ALL \
--security-opt no-new-privileges:true \
--pids-limit 100 \
--restart unless-stopped \
-v ${HOME}/nginx/nginx.conf:/etc/nginx/nginx.conf:ro,Z \
-v ${HOME}/nginx/server.crt:/etc/nginx/ssl/server.crt:ro,Z \
-v ${HOME}/nginx/server.key:/etc/nginx/ssl/server.key:ro,Z \
registry.suse.com/suse/nginx:latest

檢視 Container 狀態

sudo podman ps -a --filter name=nginx

執行結果:

CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
041b60ecbc36 registry.suse.com/suse/nginx:latest nginx -g daemon o... 7 seconds ago Up 7 seconds 0.0.0.0:8068->8443/tcp, 80/tcp nginx

驗證是否成功能透過 TLS 存取 Neuvector Metrics

curl -sk https://aionv-metrics.kubeantony.com:8068/ | head -n 5

執行結果:

# HELP python_gc_objects_collected_total Objects collected during gc
# TYPE python_gc_objects_collected_total counter
python_gc_objects_collected_total{generation="0"} 368.0
python_gc_objects_collected_total{generation="1"} 0.0
python_gc_objects_collected_total{generation="2"} 0.0

建立 Quadlet .container 檔案

# 定義變數
CONTAINER_NAME="nginx"
IMAGE="registry.suse.com/suse/nginx:latest"
HOST_PORT="8068"
CONTAINER_PORT="8443"
NGINX_CONF_DIR="${HOME}/nginx"
QUADLET_DIR="/etc/containers/systemd/"

# 建立目錄
sudo mkdir -p "${QUADLET_DIR}"

設定內容如下：

sudo tee "${QUADLET_DIR}/${CONTAINER_NAME}.container" > /dev/null <<EOF
[Unit]
Description=Nginx Reverse Proxy (Hardened)
After=network-online.target
Wants=network-online.target
[Container]
ContainerName=${CONTAINER_NAME}
Image=${IMAGE}
PublishPort=${HOST_PORT}:${CONTAINER_PORT}
ReadOnly=true
UserNS=keep-id
DropCapability=ALL
SecurityLabelDisable=false
PidsLimit=100
NoNewPrivileges=true
User=$(id -u):$(id -g)
Mount=type=tmpfs,destination=/tmp,tmpfs-size=10M,tmpfs-mode=1777,U=true
Mount=type=tmpfs,destination=/var/cache/nginx,tmpfs-size=50M,U=true
Mount=type=tmpfs,destination=/var/run,tmpfs-size=10M,U=true
Mount=type=tmpfs,destination=/var/log/nginx,tmpfs-size=10M,U=true
Mount=type=tmpfs,destination=/var/lib/nginx,tmpfs-size=50M,U=true
Volume=${NGINX_CONF_DIR}/nginx.conf:/etc/nginx/nginx.conf:ro,Z
Volume=${NGINX_CONF_DIR}/server.crt:/etc/nginx/ssl/server.crt:ro,Z
Volume=${NGINX_CONF_DIR}/server.key:/etc/nginx/ssl/server.key:ro,Z
[Service]
Restart=always
TimeoutStartSec=30
[Install]
WantedBy=default.target
EOF

重載 systemd daemon：
```
sudo systemctl daemon-reload
```
啟用並立即啟動服務：
```
sudo systemctl start nginx.service
```
如果噴錯代表 podman Quadlet 的設定檔有寫錯，請執行以下命令確認設定檔哪裡有錯
```
sudo /usr/libexec/podman/quadlet -dryrun
```

檢查 systemd 服務狀態：

sudo systemctl status nginx.service

正確執行結果：

● nginx.service - Nginx Reverse Proxy (Hardened)
Loaded: loaded (/etc/containers/systemd/nginx.container; generated)
Active: active (running) since Wed 2026-03-04 23:27:42 CST; 33s ago
Main PID: 296160 (conmon)
Tasks: 6 (limit: 50507)
Memory: 17.2M
CPU: 107ms
...

使用 podman 確認 container 狀態：

sudo podman ps -a --filter name=nginx

正確執行結果：

CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
dde5bc3186e8 registry.suse.com/suse/nginx:latest nginx -g daemon o... About a minute ago Up About a minute 0.0.0.0:8068->8443/tcp, 80/tcp nginx

再次測試是否可得到 Metrics

curl -sk https://aionv-metrics.kubeantony.com:8068/ | head -n 5

執行結果:

# HELP python_gc_objects_collected_total Objects collected during gc
# TYPE python_gc_objects_collected_total counter
python_gc_objects_collected_total{generation="0"} 368.0
python_gc_objects_collected_total{generation="1"} 0.0
python_gc_objects_collected_total{generation="2"} 0.0

參考網站

Install Prometheus with Rancher Application Collection

Wed, 04 Mar 2026 06:29:22 +0800

Prepare

helm login

helm registry login dp.apps.rancher.io \
-u tropical_flower_6fT5U@apps.rancher.io \
-p Z2xlbHB3enpmcXdmdnBkbnl0aGZ3Znlia2l2cHRoZ3hlY2VveWptdnBrZXh3Y215eG13Y2xhcGRocGpyemZreg==

Harvester 使用 Velero 外部 CSI 儲存備份：如何確保 VM 資料一致性。

Sat, 28 Feb 2026 14:17:54 +0800

1. Preface

Harvester 1.5 導入了對使用外部容器儲存介面（CSI）驅動程式來配置虛擬機器根磁碟區（root volumes）與資料磁碟區（data volumes）的支援。

本文將示範如何使用 Velero 1.17.0 在 Harvester 中執行虛擬機器的備份與還原。文章將透過具體的指令與資源清單（manifests）來完成以下操作：

備份特 namespace 內的虛擬機器、其 NFS CSI 磁碟區，以及相關的命名空間層級設定檔
將備份產物匯出至 AWS S3 儲存體（bucket）
還原至同一個叢集（cluster）上的不同 namespace
還原至不同的叢集

Velero 是一款 Kubernetes 原生的備份與還原工具，讓使用者能夠對虛擬機器執行排程與隨選（on-demand）備份，並將資料儲存至外部的物件儲存供應商（例如 S3、Azure Blob 或 GCS），完美契合企業級的備份與災難復原實務標準。

2. 安裝與部署 Garage（輕量級 S3 相容的物件儲存系統）

建立永存目錄

sudo mkdir -p /garage/{data,meta,config}

撰寫 garage.toml 設定檔

[s3_api] 和 [s3_web] 區塊底下的 root_domain 的值需要根據環境調整

cat <<EOF | sudo tee /garage/config/garage.toml > /dev/null
metadata_dir = "/var/lib/garage/meta"
data_dir = "/var/lib/garage/data"
db_engine = "sqlite"
replication_factor = 1
rpc_bind_addr = "[::]:3901"
rpc_public_addr = "127.0.0.1:3901"
rpc_secret = "ba7861f27fccfe06a99245b49e33113ca846cecdc9956169a47d7eecd74aa7d8"
[s3_api]
s3_region = "garage"
api_bind_addr = "[::]:3900"
root_domain = "api.garage.kubeantony.com"
[s3_web]
bind_addr = "[::]:3902"
root_domain = "web.garage.kubeantony.com"
index = "index.html"
[k2v_api]
api_bind_addr = "[::]:3904"
[admin]
api_bind_addr = "[::]:3903"
admin_token = "KV0EuVoDxze0Ut7tQdkvNiU8TKcD8LejZQglH/JGK00="
metrics_token = "RQxx1DjKcnhpEVnPmjxWn+CzLY5wNBNT60GMvHQ+LXo="
EOF

透過 Podman 部署 Garage

sudo podman run \
-d \
--name garaged \
--network host \
-v /garage/config/garage.toml:/etc/garage.toml \
-v /garage/meta:/var/lib/garage/meta \
-v /garage/data:/var/lib/garage/data \
dxflrs/garage:v2.2.0

確認 Garage Container 運作狀態

sudo podman ps -a --filter name=garage

執行結果：

CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
499fff9ed2db docker.io/dxflrs/garage:v2.2.0 /garage server 31 minutes ago Up 31 minutes garaged

查詢 Garage 節點狀態

sudo podman exec -it garaged /garage status

執行結果：

2026-02-26T06:41:45.072105Z INFO garage_net::netapp: Connected to 127.0.0.1:3901, negotiating handshake...
2026-02-26T06:41:45.113726Z INFO garage_net::netapp: Connection established to 368849c86cba2382
==== HEALTHY NODES ====
ID Hostname Address Tags Zone Capacity DataAvail Version
368849c86cba2382 garage.kubeantony.com 127.0.0.1:3901 NO ROLE ASSIGNED v2.2.0

將指定的 Garage 節點設定至 dc1 可用區（Zone）和 50GB 的儲存容量。

sudo podman exec -it garaged /garage layout assign -z dc1 -c 50G 368849c86cba2382

執行結果：

2026-02-26T06:42:30.841741Z INFO garage_net::netapp: Connected to 127.0.0.1:3901, negotiating handshake...
2026-02-26T06:42:30.882712Z INFO garage_net::netapp: Connection established to 368849c86cba2382
Role changes are staged but not yet committed.
Use `garage layout show` to view staged role changes,
and `garage layout apply` to enact staged changes.

執行結果顯示此變更目前僅處於「暫存 staged」狀態

正式套用先前暫存的叢集配置（版本 1），使節點的角色與容量設定正式生效。

sudo podman exec garaged /garage layout apply --version 1

執行結果：

2026-02-26T06:42:50.085913Z INFO garage_net::netapp: Connected to 127.0.0.1:3901, negotiating handshake...
2026-02-26T06:42:50.126651Z INFO garage_net::netapp: Connection established to 368849c86cba2382
==== COMPUTATION OF A NEW PARTITION ASSIGNATION ====
Partitions are replicated 1 times on at least 1 distinct zones.
Optimal partition size: 195.3 MB
Usable capacity / total cluster capacity: 50.0 GB / 50.0 GB (100.0 %)
Effective capacity (replication factor 1): 50.0 GB
dc1 Tags Partitions Capacity Usable capacity
368849c86cba2382 [] 256 (256 new) 50.0 GB 50.0 GB (100.0%)
TOTAL 256 (256 unique) 50.0 GB 50.0 GB (100.0%)
New cluster layout with updated role assignment has been applied in cluster.
Data will now be moved around between nodes accordingly.

再次確認 Garage 節點狀態

sudo podman exec garaged /garage status

執行結果：

2026-02-26T07:49:07.462651Z INFO garage_net::netapp: Connected to 127.0.0.1:3901, negotiating handshake...
2026-02-26T07:49:07.503706Z INFO garage_net::netapp: Connection established to 368849c86cba2382
==== HEALTHY NODES ====
ID Hostname Address Tags Zone Capacity DataAvail Version
368849c86cba2382 garage.kubeantony.com 127.0.0.1:3901 [] dc1 50.0 GB 58.5 GB (82.0%) v2.2.0

建立 Bucket

sudo podman exec garaged /garage bucket create vm-backup

執行結果：

2026-02-26T07:54:42.568429Z INFO garage_net::netapp: Connected to 127.0.0.1:3901, negotiating handshake...
2026-02-26T07:54:42.609720Z INFO garage_net::netapp: Connection established to 368849c86cba2382
==== BUCKET INFORMATION ====
Bucket: be30df62bea032acdc9ba3b992b32a43794b9f950599870e21ee706340c39c96
Created: 2026-02-26 07:54:42.610 +00:00
Size: 0 B (0 B)
Objects: 0
Website access: false
Global alias: vm-backup
==== KEYS FOR THIS BUCKET ====
Permissions Access key Local aliases

建立 API Key

sudo podman exec garaged /garage key create vm-backup-access-key

執行結果：

2026-02-26T07:56:11.307951Z INFO garage_net::netapp: Connected to 127.0.0.1:3901, negotiating handshake...
2026-02-26T07:56:11.348732Z INFO garage_net::netapp: Connection established to 368849c86cba2382
==== ACCESS KEY INFORMATION ====
Key ID: GK6e4243deca7bc09fdffcb405
Key name: vm-backup-access-key
Secret key: 9280dbc88cb656a8589783f0762652fdb93362b2df0c7a47cfa7f2ae9b15899f
Created: 2026-02-26 07:56:11.348 +00:00
Validity: valid
Expiration: never
Can create buckets: false
==== BUCKETS FOR THIS KEY ====
Permissions ID Global aliases Local aliases

賦予權限

sudo podman exec garaged /garage bucket allow --read --write --owner vm-backup --key vm-backup-access-key

執行結果：

2026-02-26T07:57:44.077279Z INFO garage_net::netapp: Connected to 127.0.0.1:3901, negotiating handshake...
2026-02-26T07:57:44.118727Z INFO garage_net::netapp: Connection established to 368849c86cba2382
==== BUCKET INFORMATION ====
Bucket: be30df62bea032acdc9ba3b992b32a43794b9f950599870e21ee706340c39c96
Created: 2026-02-26 07:54:42.610 +00:00
Size: 0 B (0 B)
Objects: 0
Website access: false
Global alias: vm-backup
==== KEYS FOR THIS BUCKET ====
Permissions Access key Local aliases
RWO GK6e4243deca7bc09fdffcb405 vm-backup-access-key

測試掛載，安裝 s3fs
```
sudo apt-get install s3fs -y
```

設定 s3fs

echo "GK6e4243deca7bc09fdffcb405:9280dbc88cb656a8589783f0762652fdb93362b2df0c7a47cfa7f2ae9b15899f" > ${HOME}/.passwd-s3fs
chmod 600 ${HOME}/.passwd-s3fs
sudo sed -i 's/#user_allow_other/user_allow_other/' /etc/fuse.conf

建立掛載點

sudo mkdir -p /mnt/garage-s3
sudo chown $USER:$USER /mnt/garage-s3

將自建 Garage S3 上的 vm-backup bucket 儲存體掛載至本地 /mnt/garage-s3

s3fs vm-backup /mnt/garage-s3 \
-o passwd_file=${HOME}/.passwd-s3fs \
-o url=http://garage.kubeantony.com:3900 \
-o use_path_request_style \
-o allow_other \
-o umask=000 \
-o endpoint=garage

檢視 /mnt/garage-s3 目錄已掛載到 s3

findmnt -t fuse.s3fs

執行結果：

TARGET SOURCE
FSTYPE OPTIONS
/mnt/garage-s3 s3fs fuse.s3fs rw,nosuid,nodev,relatime,user_id=1000,group_id=1000,allow_other

寫入資料

echo "test connection" > /mnt/garage-s3/test.txt

查詢 vm-backup Bucket 詳細狀態

sudo podman exec garaged /garage bucket info vm-backup

執行結果：

2026-02-26T08:17:07.919852Z INFO garage_net::netapp: Connected to 127.0.0.1:3901, negotiating handshake...
2026-02-26T08:17:07.960680Z INFO garage_net::netapp: Connection established to 368849c86cba2382
==== BUCKET INFORMATION ====
Bucket: be30df62bea032acdc9ba3b992b32a43794b9f950599870e21ee706340c39c96
Created: 2026-02-26 07:54:42.610 +00:00
Size: 16 B (16 B)
Objects: 1
Website access: false
Global alias: vm-backup
==== KEYS FOR THIS BUCKET ====
Permissions Access key Local aliases
RWO GK6e4243deca7bc09fdffcb405 vm-backup-access-key

清除測試資料與取消掛載

rm /mnt/garage-s3/test.txt
umount /mnt/garage-s3

3. Install and Configure Velero

ssh 連線到 Harvester Control plane 節點執行以下操作

安裝 Velero CLI

# 設定版本
VERSION=v1.17.0
# 使用 curl 下載並重新命名檔案
curl -L https://github.com/vmware-tanzu/velero/releases/download/$VERSION/velero-$VERSION-linux-amd64.tar.gz -o velero.tar.gz
# 解壓縮
tar -xvf velero.tar.gz
# 移動到系統路徑
mv velero-$VERSION-linux-amd64/velero /root/bin/
# 測試
velero version --client-only

執行結果：

Client:
Version: v1.17.0
Git commit: 3172d9f99c3d501aad9ddfac8176d783f7692dce

設置以下 shell 變數

BUCKET_NAME=vm-backup
BUCKET_REGION=garage
echo "[default]
aws_access_key_id=GK6e4243deca7bc09fdffcb405
aws_secret_access_key=9280dbc88cb656a8589783f0762652fdb93362b2df0c7a47cfa7f2ae9b15899f" > ${HOME}/.passwd
AWS_CREDENTIALS_FILE=${HOME}/.passwd

在 Harvester 集群上安裝 Velero
```
velero install \
--provider aws \
--features=EnableCSI \
--plugins "velero/velero-plugin-for-aws:v1.12.0,quay.io/kubevirt/kubevirt-velero-plugin:v0.7.1" \
--bucket "${BUCKET_NAME}" \
--secret-file "${AWS_CREDENTIALS_FILE}" \
--backup-location-config region="${BUCKET_REGION}" \
--snapshot-location-config region="${BUCKET_REGION}" \
--use-node-agent
```
在這個設定中，Velero 被設定為：
- 跑在 velero namespace
- 啟用 CSI 儲存卷快照 (volume snapshot) API
- 啟用內建的節點代理程式 (node agent) 資料移動控制器與 Pod
- 使用 velero-plugin-for-aws 外掛程式來管理與 S3 物件儲存庫的互動
- 使用 kubevirt-velero-plugin 外掛程式來備份與還原 KubeVirt 資源

確認 Velero 已安裝並正在運行

kubectl -n velero get pods

執行結果：

NAME READY STATUS RESTARTS AGE
node-agent-49f56 1/1 Running 0 4m30s
node-agent-dhtmj 1/1 Running 0 4m30s
node-agent-n4wh9 1/1 Running 0 4m30s
velero-6c57f94f49-bxcjx 1/1 Running 0 4m30s

設定 velero CLI 以輸出 CSI 物件的備份和還原狀態
```
velero client config set features=EnableCSI
```

patch backupstoragelocation

kubectl patch backupstoragelocation default -n velero --type merge --patch '{"spec":{"config":{"s3Url":"http://garage.kubeantony.com:3900","s3ForcePathStyle":"true"}}}'

Check Backup-location status

velero backup-location get

執行結果:

NAME PROVIDER BUCKET/PREFIX PHASE LAST VALIDATED ACCESS MODE DEFAULT
default aws vm-backup Available 2026-02-28 11:56:20 +0000 UTC ReadWrite true

4. Deploy the NFS CSI and Example Server

在 Kubernetes 叢集上設置 NFS 伺服器

curl -s -O https://raw.githubusercontent.com/kubernetes-csi/csi-driver-nfs/master/deploy/example/nfs-provisioner/nfs-server.yaml
vim nfs-server.yaml

檔案內容：

 volumes:
- name: nfs-vol
hostPath:
path: /root/nfs-data # modify this to specify another path to store nfs share data
type: DirectoryOrCreate

部署 NFS 伺服器

kubectl apply -f nfs-server.yaml

執行結果：

service/nfs-server created
deployment.apps/nfs-server created

檢查 NFS 伺服器是否正常運作

kubectl get pods

執行結果：

NAME READY STATUS RESTARTS AGE
nfs-server-69ff4786bd-4pf6v 1/1 Running 0 3m22s

部署 NFS CSI 驅動程式

curl -skSL https://raw.githubusercontent.com/kubernetes-csi/csi-driver-nfs/v4.13.1/deploy/install-driver.sh | bash -s v4.13.1 --

執行結果：

Installing NFS CSI driver, version: v4.13.1 ...
serviceaccount/csi-nfs-controller-sa created
serviceaccount/csi-nfs-node-sa created
clusterrole.rbac.authorization.k8s.io/nfs-external-provisioner-role created
clusterrolebinding.rbac.authorization.k8s.io/nfs-csi-provisioner-binding created
clusterrole.rbac.authorization.k8s.io/nfs-external-resizer-role created
clusterrolebinding.rbac.authorization.k8s.io/nfs-csi-resizer-role created
csidriver.storage.k8s.io/nfs.csi.k8s.io created
deployment.apps/csi-nfs-controller created
daemonset.apps/csi-nfs-node created
NFS CSI driver installed successfully.

確認 pods 狀態

kubectl -n kube-system get pod -o wide -l 'app in (csi-nfs-controller, csi-nfs-node)'

執行結果：

NAME READY STATUS RESTARTS AGE IP NODE NOMINATED NODE READINESS GATES
csi-nfs-controller-68599bd8b6-v68cr 5/5 Running 0 8m36s 192.168.11.183 hvx-03 <none> <none>
csi-nfs-node-2s57l 3/3 Running 0 8m35s 192.168.11.181 hvx-01 <none> <none>
csi-nfs-node-79zpf 3/3 Running 0 8m35s 192.168.11.182 hvx-02 <none> <none>
csi-nfs-node-smcq8 3/3 Running 0 8m35s 192.168.11.183 hvx-03 <none> <none>

建立 Client pod 掛載 NFS Volume 檢查 NFS 伺服器是否正常運作

kubectl create -f https://raw.githubusercontent.com/kubernetes-csi/csi-driver-nfs/master/deploy/example/nfs-provisioner/nginx-pod.yaml

確認 client pod 運作正常

kubectl get pod nginx-nfs-example

執行結果：

NAME READY STATUS RESTARTS AGE
nginx-nfs-example 1/1 Running 0 43m

從範例 pod 檢查掛載點

kubectl exec nginx-nfs-example -- bash -c "findmnt /var/www -o TARGET,SOURCE,FSTYPE"

執行結果：

TARGET SOURCE FSTYPE
/var/www nfs-server.default.svc.cluster.local:/ nfs4

清除 client pod

kubectl delete -f https://raw.githubusercontent.com/kubernetes-csi/csi-driver-nfs/master/deploy/example/nfs-provisioner/nginx-pod.yaml

撰寫 NFS Storage Class YAML 檔

vi nfs-sc.yaml

檔案內容如下:

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
name: nfs-csi
provisioner: nfs.csi.k8s.io
parameters:
server: nfs-server.default.svc.cluster.local
share: /
# csi.storage.k8s.io/provisioner-secret is only needed for providing mountOptions in DeleteVolume
# csi.storage.k8s.io/provisioner-secret-name: "mount-options"
# csi.storage.k8s.io/provisioner-secret-namespace: "default"
reclaimPolicy: Delete
volumeBindingMode: Immediate
allowVolumeExpansion: true
mountOptions:
- nfsvers=4.1

建立 NFS Storage Class
```
kubectl apply -f nfs-sc.yaml
```

Create source PVC and an example pod to write data

kubectl apply -f https://raw.githubusercontent.com/kubernetes-csi/csi-driver-nfs/master/deploy/example/pvc-nfs-csi-dynamic.yaml
kubectl apply -f https://raw.githubusercontent.com/kubernetes-csi/csi-driver-nfs/master/deploy/example/nginx-pod-nfs.yaml

Check the Source PVC

kubectl exec nginx-nfs -- ls /mnt/nfs

執行結果:

outfile

Create a snapshot on source PVC

kubectl apply -f https://raw.githubusercontent.com/kubernetes-csi/csi-driver-nfs/master/deploy/example/snapshot/snapshotclass-nfs.yaml
kubectl apply -f https://raw.githubusercontent.com/kubernetes-csi/csi-driver-nfs/master/deploy/example/snapshot/snapshot-nfs-dynamic.yaml

Check snapshot Status

kubectl describe volumesnapshot test-nfs-snapshot

執行結果:

Name: test-nfs-snapshot
Namespace: default
Labels: <none>
Annotations: <none>
API Version: snapshot.storage.k8s.io/v1
Kind: VolumeSnapshot
Metadata:
Creation Timestamp: 2026-02-28T09:37:06Z
Finalizers:
snapshot.storage.kubernetes.io/volumesnapshot-as-source-protection
snapshot.storage.kubernetes.io/volumesnapshot-bound-protection
Generation: 1
Resource Version: 15038120
UID: 59a4ddb9-a123-4dea-b220-e0fcac477f59
Spec:
Source:
Persistent Volume Claim Name: pvc-nfs-dynamic
Volume Snapshot Class Name: csi-nfs-snapclass
Status:
Bound Volume Snapshot Content Name: snapcontent-59a4ddb9-a123-4dea-b220-e0fcac477f59
Creation Time: 2026-02-28T09:37:06Z
Ready To Use: true
Restore Size: 1026
Events:
Type Reason Age From Message
---- ------ ---- ---- -------
Normal CreatingSnapshot 46s snapshot-controller Waiting for a snapshot default/test-nfs-snapshot to be created by the CSI driver.
Normal SnapshotCreated 46s snapshot-controller Snapshot default/test-nfs-snapshot was successfully created by the CSI driver.
Normal SnapshotReady 46s snapshot-controller Snapshot default/test-nfs-snapshot is ready to use.

In above example, snapcontent-59a4ddb9-a123-4dea-b220-e0fcac477f59 is the snapshot name.

Create a new PVC based on snapshot

kubectl apply -f https://raw.githubusercontent.com/kubernetes-csi/csi-driver-nfs/master/deploy/example/snapshot/pvc-nfs-snapshot-restored.yaml
kubectl apply -f https://raw.githubusercontent.com/kubernetes-csi/csi-driver-nfs/master/deploy/example/snapshot/nginx-pod-restored-snapshot.yaml

Check data

kubectl exec nginx-nfs-restored-snapshot -- ls /mnt/nfs

執行結果:

outfile

清除範例 pod

kubectl delete -f https://raw.githubusercontent.com/kubernetes-csi/csi-driver-nfs/master/deploy/example/nginx-pod-nfs.yaml
kubectl delete -f https://raw.githubusercontent.com/kubernetes-csi/csi-driver-nfs/master/deploy/example/pvc-nfs-csi-dynamic.yaml
kubectl delete -f https://raw.githubusercontent.com/kubernetes-csi/csi-driver-nfs/master/deploy/example/snapshot/nginx-pod-restored-snapshot.yaml
kubectl delete -f https://raw.githubusercontent.com/kubernetes-csi/csi-driver-nfs/master/deploy/example/snapshot/pvc-nfs-snapshot-restored.yaml

5. Preparing the Virtual Machine and Image

Create a custom namespace named demo-src
```
kubectl create ns demo-src
```
上傳 ubuntu images
```
https://cloud-images.ubuntu.com/minimal/releases/noble/release-20260218/ubuntu-24.04-minimal-cloudimg-amd64.img
```
點選左側選單 images -> 在 URL 欄位輸入以上網址

Stoage 選擇 nfs-csi -> Create

確認虛擬機映像檔已成功上傳至 Harvester：
建立 VM

輸入 VM 名稱: test

點選 Volumes -> 選擇剛剛上傳的 Image demo-src/ubuntu-24.04-minimal-cloudimg-amd64.img (nfs-csi / 3.5 Gi)

點選 Add Volume -> StorageClass nfs-csi -> Volume Mode: Filesystem

Cloud Config user-data
```
ssh_pwauth: true
users:
- default
- name: rancher
gecos: rancher
groups: users
lock_passwd: false
sudo: ALL=(ALL) NOPASSWD:ALL
plain_text_passwd: 'rancher'
shell: /bin/bash
```
點選 Console -> Open in Serial Console

add some files to both the root and data volumes.

sudo touch /test
sudo mkdir /data
sudo mkfs.ext4 /dev/vdb
echo '/dev/vdb /data ext4 defaults 0 2' | sudo tee -a /etc/fstab
sudo mount -a
echo "haha" | sudo tee /data/test

6. 驗證檔案系統凍結相容性

Access the virtual machine’s virt-launcher compute container

POD=$(kubectl get pods -n demo-src \
-l vm.kubevirt.io/name=test \
-o jsonpath='{.items[0].metadata.name}')
kubectl exec -it $POD -n demo-src -c compute -- bash

Test filesystem freeze using the virt-freezer application available in the compute container:

virt-freezer --freeze --namespace demo-src --name test

執行結果:

{"component":"freezer","level":"info","msg":"Guest agent version is 8.2.2","pos":"virt-freezer.go:114","timestamp":"2026-02-28T14:00:43.873324Z"}
{"component":"freezer","level":"info","msg":"Operation completed successfully","pos":"virt-freezer.go:152","timestamp":"2026-02-28T14:00:43.940305Z"}

解凍

virt-freezer --unfreeze --namespace demo-src --name test

執行結果:

{"component":"freezer","level":"info","msg":"Guest agent version is 8.2.2","pos":"virt-freezer.go:114","timestamp":"2026-02-28T14:02:06.328210Z"}
{"component":"freezer","level":"info","msg":"Operation completed successfully","pos":"virt-freezer.go:152","timestamp":"2026-02-28T14:02:06.338162Z"}

設定在開始建立備份前凍結 VM 檔案系統，備份完成後解凍虛擬機檔案系統

kubectl patch virtualmachine test -n demo-src --type merge --patch '{
"spec": {
"template": {
"metadata": {
"annotations": {
"pre.hook.backup.velero.io/command": "[\"/usr/bin/virt-freezer\", \"--freeze\", \"--namespace\", \"demo-src\", \"--name\", \"ub-test\"]",
"pre.hook.backup.velero.io/container": "compute",
"pre.hook.backup.velero.io/on-error": "Fail",
"pre.hook.backup.velero.io/timeout": "30s",
"post.hook.backup.velero.io/command": "[\"/usr/bin/virt-freezer\", \"--thaw\", \"--namespace\", \"demo-src\", \"--name\", \"ub-test\"]",
"post.hook.backup.velero.io/container": "compute",
"post.hook.backup.velero.io/on-error": "Continue",
"post.hook.backup.velero.io/timeout": "30s"
}
}
}
}
}'

到 Harvester UI 將目標 vm 重新開機，套用最新的設定檔

7. Backup the Source Namespace

使用 velero CLI 利用 Velero 內建的資料移動工具，建立 demo-src 命名空間的備份

BACKUP_NAME=backup-demo-src-`date "+%s"`
velero backup create "${BACKUP_NAME}" \
--include-namespaces demo-src \
--snapshot-move-data

執行結果:

Backup request "backup-demo-src-1772286287" submitted successfully.
Run `velero backup describe backup-demo-src-1772286287` or `velero backup logs backup-demo-src-1772286287` for more details.

DataUpload 的自訂資源提供了備份進度的見解

velero backup get "${BACKUP_NAME}"

執行結果:

NAME STATUS ERRORS WARNINGS CREATED EXPIRES STORAGE LOCATION SELECTOR
backup-demo-src-1772278089 InProgress 0 0 2026-02-28 11:56:33 +0000 UTC 29d default <none>

…過幾分鐘後

NAME STATUS ERRORS WARNINGS CREATED EXPIRES STORAGE LOCATION SELECTOR
backup-demo-src-1772278089 Completed 0 0 2026-02-28 11:56:33 +0000 UTC 29d default <none>

8. Restore To A Different Namespace

Save the following restore modifier to a local file named modifier-data-volumes.yaml

cat <<EOF > modifier-data-volumes.yaml
version: v1
resourceModifierRules:
- conditions:
groupResource: persistentvolumeclaims
matches:
- path: /metadata/annotations/harvesterhci.io~1volumeForVirtualMachine
value: "\"true\""
patches:
- operation: remove
path: /metadata/annotations/harvesterhci.io~1volumeForVirtualMachine
EOF

Create the restore modifier

kubectl -n velero create cm modifier-data-volumes --from-file=modifier-data-volumes.yaml

Assign the backup name to a shell variable

velero restore create \
--from-backup "${BACKUP_NAME}" \
--namespace-mappings "demo-src:demo-dst" \
--exclude-resources "virtualmachineimages.harvesterhci.io" \
--resource-modifier-configmap "modifier-data-volumes" \
--labels "velero.kubevirt.io/clear-mac-address=true,velero.kubevirt.io/generate-new-firmware-uuid=true"

執行結果:

Restore request "backup-demo-src-1772286287-20260228141734" submitted successfully.
Run `velero restore describe backup-demo-src-1772286287-20260228141734` or `velero restore logs backup-demo-src-1772286287-20260228141734` for more details.

修復期間：虛擬機的 MAC 位址與韌體 UUID 會被重置，以避免與現有虛擬機發生潛在衝突。虛擬機映像清單被排除，因為 Velero 會從備份中恢復整個虛擬機狀態。會呼叫 modifier-data-volumes 的還原修飾符來修改虛擬機器的資料卷的元資料，以避免與 CDI 卷匯入填充器發生衝突。

當還原操作仍在進行中時，DataDownload 的自訂資源可用來檢視作業進度：

RESTORE_NAME=backup-demo-src-1772286287-20260228141734
kubectl -n velero get datadownload -l velero.io/restore-name="${RESTORE_NAME}"

執行結果:

NAME STATUS STARTED BYTES DONE TOTAL BYTES STORAGE LOCATION AGE NODE
backup-demo-src-1772286287-20260228135229-9fnqg Completed 59s 3758096384 3758096384 default 75s hvx-02
backup-demo-src-1772286287-20260228135229-fqrhx Completed 72s 192040960 192040960 default 74s hvx-02
backup-demo-src-1772286287-20260228135229-kp2jw Completed 71s 10737418240 10737418240 default 75s hvx-01
backup-demo-src-1772286287-20260228135229-n7bcp Completed 70s 10146021376 10146021376 default 74s hvx-03

確認還原成功完成：

velero restore get

執行結果:

NAME BACKUP STATUS STARTED COMPLETED ERRORS WARNINGS CREATED SELECTOR
backup-demo-src-1772286287-20260228135229 backup-demo-src-1772286287 Completed 2026-02-28 13:52:29 +0000 UTC 2026-02-28 13:54:00 +0000 UTC 0 6 2026-02-28 13:52:29 +0000 UTC <none>

確認虛擬機及其設定是否已恢復到新的 demo-dst namespace：

How to update rke2 to cis profile

Tue, 24 Feb 2026 07:18:08 +0800

以下命令要先在 update 之前執行

Control-plane node 跑

sudo cp -vf /usr/local/share/rke2/rke2-cis-sysctl.conf /etc/sysctl.d/60-rke2-cis.conf && \
sudo systemctl restart systemd-sysctl && \
sudo useradd -r -c "etcd user" -s /sbin/nologin -M etcd -U; \
sudo reboot

如果先更新下去會在 rke2-server 的 service 看到以下錯誤訊息
missing required: user: unknown user etcd\nmissing required: group: unknown group etcd\n

worker node 跑 (如果是透過 Rancher 去更新，以下指令不用做)

cp /opt/rke2/share/rke2/rke2-cis-sysctl.conf /etc/sysctl.d/60-rke2-cis.conf && \
systemctl restart systemd-sysctl
reboot

Ref

CIS Hardening Guide - RKE2 Docs

Install Harbor using Podman

Tue, 24 Feb 2026 02:14:22 +0800

先決條件

已安裝 podman，版本 4.9.x 或以上

已安裝 curl, wget, jq, git 和 httpd-tools 工具

sudo dnf install -y podman curl wget jq httpd-tools git

本篇文章環境資訊
- OS 發行版: Red Hat Enterprise Linux 9.7 (Plow)
- Kernel 版本: 5.14.0-611.24.1.el9_7.x86_64
- podman 版本: 5.6.0
- SELinux: Enforcing
- Firewalld systemd service: active and enabled

硬體資源需求

資源項目	最低配置	建議配置
CPU	2 核 (CPU)	4 核 (CPU)
記憶體 (Mem)	4 GB	8 GB
磁碟空間 (Disk)	40 GB	160 GB

Setp1: 建立 podman network

sudo podman network create --subnet 10.8.0.0/16 harbor

若不想建立網路，可以使用預設 podman 網路，但需要將 dns 解析打開預設網路目前版本沒有開啟 dns 解析，要不然 containers 之間沒法透過主機名稱進行互訪。修改設定檔後需要將網路介面刪除或重新啟動主機才能生效。

Step2: 下載 Harbor 離線安裝所需的檔案

下載官方發布的離線版本

HARBOR_VERSION=$(curl -s https://api.github.com/repos/goharbor/harbor/releases/latest | jq -r .tag_name)
wget https://github.com/goharbor/harbor/releases/download/${HARBOR_VERSION}/harbor-offline-installer-${HARBOR_VERSION}.tgz

第一行命令會直接到 github 抓 Harbor 官方最新 release 的版本，如果要安裝其他版本，請自行定義

解壓縮檔案，並切換工作目錄

tar zxf harbor-offline-installer-${HARBOR_VERSION}.tgz; cd harbor

匯入 image

sudo podman load -i harbor.${HARBOR_VERSION}.tar.gz

檢查是否成功

sudo podman images

執行結果如下 :

REPOSITORY TAG IMAGE ID CREATED SIZE
localhost/goharbor/harbor-exporter v2.14.2 26fc5ce17425 13 days ago 133 MB
localhost/goharbor/redis-photon v2.14.2 d62cec11627f 13 days ago 190 MB
localhost/goharbor/trivy-adapter-photon v2.14.2 6165b96861b7 13 days ago 403 MB
localhost/goharbor/harbor-registryctl v2.14.2 1364c6d80c42 13 days ago 167 MB
localhost/goharbor/registry-photon v2.14.2 4161f69794cf 13 days ago 88.4 MB
localhost/goharbor/nginx-photon v2.14.2 9383173f860e 13 days ago 175 MB
localhost/goharbor/harbor-log v2.14.2 77a92995972a 13 days ago 188 MB
localhost/goharbor/harbor-jobservice v2.14.2 5b11a15a5cb0 13 days ago 180 MB
localhost/goharbor/harbor-core v2.14.2 604ea0c2c17f 13 days ago 205 MB
localhost/goharbor/harbor-portal v2.14.2 b936a8ce0efb 13 days ago 183 MB
localhost/goharbor/harbor-db v2.14.2 d80918ffd062 13 days ago 293 MB
localhost/goharbor/prepare v2.14.2 6337f8dedb39 13 days ago 203 MB

Step3: 部署 Harbor 各元件

注意，Harbor 各別的元件相互依賴，需要依照順序部署，否則元件無法啟動

3.1. 部署 redis

建立 redis container

# 定義 Redis 資料永存目錄區
REDIS_PV="/data/redis"
[ ! -d ${REDIS_PV} ] && sudo mkdir -p ${REDIS_PV}
sudo chown 999:999 ${REDIS_PV}
sudo podman run --name redis --detach \
--network=harbor \
--cap-add=chown --cap-add=setuid \
--cap-add=setgid --cap-drop=all \
--volume=${REDIS_PV}:/var/lib/redis:z \
goharbor/redis-photon:${HARBOR_VERSION}

3.2. 部署 postgresql

建立 secret：資料庫 root 使用者的密碼，這裡使用隨機密碼

tr -dc 'A-Za-z0-9' < /dev/urandom | head -c 16 | sudo podman secret create db-secret -

建立 pg container

# 定義 Redis 資料永存目錄區
PG_PV="/data/database"
[ ! -d ${PG_PV} ] && sudo mkdir -p ${PG_PV}
sudo chown -R 999:999 ${PG_PV}
sudo podman run --name postgresql \
--detach --network=harbor \
--cap-add=chown --cap-add=setuid \
--cap-add=setgid --cap-add=dac_override \
--cap-drop=all --shm-size=1gb \
--secret=db-secret,type=env,target=POSTGRES_PASSWORD \
--volume=${PG_PV}:/var/lib/postgresql/data:z \
goharbor/harbor-db:${HARBOR_VERSION}

3.3. 部署 Registry

編輯 registry 設定檔

sudo mkdir -p /etc/harbor
sudo nano /etc/harbor/registry.yml

檔案內容如下 :

version: 0.1
log:
level: info
fields:
service: registry
storage:
cache:
layerinfo: redis
filesystem:
rootdirectory: /storage
maintenance:
uploadpurging:
enabled: true
age: 168h
interval: 24h
dryrun: false
delete:
enabled: true
redis:
addr: redis:6379
readtimeout: 10s
writetimeout: 10s
dialtimeout: 10s
password:
db: 1
enableTLS: false
pool:
maxidle: 100
maxactive: 500
idletimeout: 60s
http:
addr: :5000
secret: placeholder
debug:
addr: :9090
prometheus:
enabled: true
path: /metrics
auth:
htpasswd:
realm: harbor-registry-basic-realm
path: /etc/registry/passwd
validation:
disabled: true
compatibility:
schema1:
enabled: true

建立密碼

USERNAME="harbor_registry_user"
PASSWORD="password"
HASH=$(htpasswd -nbB -C 5 "$USERNAME" "$PASSWORD" | cut -d: -f2)
echo "$USERNAME:$HASH" | sudo podman secret create registry-auth -

啟動 registry container

# 定義 REGISTRY 資料永存目錄區
REGISTRY_PV="/data/registry"
[ ! -d ${REGISTRY_PV} ] && sudo mkdir -p ${REGISTRY_PV}
sudo chown 10000:10000 ${REGISTRY_PV}
sudo podman run --name=registry \
--detach --network=harbor \
--cap-add=chown --cap-add=setuid \
--cap-add=setgid --cap-drop=all \
--secret=registry-auth,target=/etc/registry/passwd \
--volume=${REGISTRY_PV}:/storage:z \
--volume=/etc/harbor/registry.yml:/etc/registry/config.yml:ro \
--volume=$(find /etc/ssl/certs/ -name ca-*.crt ! -name "*trust*"):/etc/registry/root.crt:ro \
goharbor/registry-photon:${HARBOR_VERSION}

3.4. 部署 portal

建立設定檔

sudo nano /etc/harbor/portal.conf

檔案內容如下 :

worker_processes auto;
pid /tmp/nginx.pid;
events {
worker_connections 1024;
}
http {
client_body_temp_path /tmp/client_body_temp;
proxy_temp_path /tmp/proxy_temp;
fastcgi_temp_path /tmp/fastcgi_temp;
uwsgi_temp_path /tmp/uwsgi_temp;
scgi_temp_path /tmp/scgi_temp;
server {
listen 8080;
server_name localhost;
root /usr/share/nginx/html;
index index.html index.htm;
include /etc/nginx/mime.types;
gzip on;
gzip_min_length 1000;
gzip_proxied expired no-cache no-store private auth;
gzip_types text/plain text/css application/json application/javascript application/x-javascript text/xml application/xml application/xml+rss text/javascript;
location /devcenter-api-2.0 {
try_files $uri $uri/ /swagger-ui-index.html;
}
location / {
try_files $uri $uri/ /index.html;
}
location = /index.html {
add_header Cache-Control "no-store, no-cache, must-revalidate";
}
}
}

建立 portal container

sudo podman run --name=portal \
--detach --network=harbor \
--cap-add=setuid --cap-add=setgid \
--cap-add=net_bind_service --cap-drop=all \
--volume=/etc/harbor/portal.conf:/etc/nginx/nginx.conf:ro \
goharbor/harbor-portal:${HARBOR_VERSION}

3.5. 部署 registryctl

編輯設定檔

sudo nano /etc/harbor/registryctl.yml

檔案內容如下 :

---
protocol: "http"
port: 8080
log_level: info
registry_config: "/etc/registry/config.yml"

建立密碼

# 產生 harbor 私鑰: 用於建立 token
openssl genrsa 4096 | openssl pkey -traditional | sudo podman secret create harbor-key -
# 產生 harbor secretkey
openssl rand -base64 12 | head -c 16| sudo podman secret create harbor-secretkey -
# harbor 密碼：用於其他元件與 harbor 通訊認證
openssl rand -base64 12 | head -c 16 | sudo podman secret create harbor-secret -
# jobservice 密碼： 用於與 jobservice 通訊認證
openssl rand -base64 12 | head -c 16 | sudo podman secret create jobservice-secret -
# registry 密碼: 主要給 harbor 和 jobservice 使用
printf "password" | sudo podman secret create registry-passwd -

建立 registryctl container

sudo podman run --name=registryctl \
--detach --network=harbor \
--cap-add=setuid --cap-add=setgid --cap-drop=all \
--secret=harbor-secret,type=env,target=CORE_SECRET \
--secret=jobservice-secret,type=env,target=JOBSERVICE_SECRET \
--volume=${REGISTRY_PV}:/storage:z \
--volume=/etc/harbor/registry.yml:/etc/registry/config.yml:ro \
--volume=/etc/harbor/registryctl.yml:/etc/registryctl/config.yml:ro \
--volume=$(find /etc/ssl/certs/ -name ca-*.crt ! -name "*trust*"):/etc/registry/root.crt:ro \
goharbor/harbor-registryctl:${HARBOR_VERSION}

3.6. 部署 harbor

編輯設定檔

sudo nano /etc/harbor/harbor.conf

檔案內容如下 :

appname = Harbor
runmode = prod
enablegzip = true
[prod]
httpport = 8080

編輯 Harbor 運作所需之環境變數

sudo nano /etc/harbor/coreenv

檔案內容如下 :

CONFIG_PATH=/etc/core/app.conf
UAA_CA_ROOT=/etc/core/certificates/uaa_ca.pem
_REDIS_URL_CORE=redis://redis:6379?idle_timeout_seconds=30
SYNC_QUOTA=true
_REDIS_URL_REG=redis://redis:6379/1?idle_timeout_seconds=30
LOG_LEVEL=info
DATABASE_TYPE=postgresql
POSTGRESQL_HOST=postgresql
POSTGRESQL_PORT=5432
POSTGRESQL_USERNAME=postgres
POSTGRESQL_DATABASE=registry
POSTGRESQL_SSLMODE=disable
POSTGRESQL_MAX_IDLE_CONNS=100
POSTGRESQL_MAX_OPEN_CONNS=900
POSTGRESQL_CONN_MAX_LIFETIME=5m
POSTGRESQL_CONN_MAX_IDLE_TIME=0
REGISTRY_URL=http://registry:5000
PORTAL_URL=http://portal:8080
TOKEN_SERVICE_URL=http://core:8080/service/token
HARBOR_ADMIN_PASSWORD=Harbor12345
MAX_JOB_WORKERS=10
WITH_TRIVY=True
CORE_URL=http://core:8080
CORE_LOCAL_URL=http://127.0.0.1:8080
JOBSERVICE_URL=http://jobservice:8080
TRIVY_ADAPTER_URL=http://trivy-adapter:8080
REGISTRY_STORAGE_PROVIDER_NAME=filesystem
READ_ONLY=false
RELOAD_KEY=
REGISTRY_CONTROLLER_URL=http://registryctl:8080
REGISTRY_CREDENTIAL_USERNAME=harbor_registry_user
CSRF_KEY=jPcpPYw2HU4V0r2LG2kyHWWSIwRE4Ln8
ROBOT_SCANNER_NAME_PREFIX=2GA78XLs
PERMITTED_REGISTRY_TYPES_FOR_PROXY_CACHE=docker-hub,harbor,azure-acr,ali-acr,aws-ecr,google-gcr,quay,docker-registry,github-ghcr,jfrog-artifactory
HTTP_PROXY=
HTTPS_PROXY=
NO_PROXY=localhost,postgresql,portal,trivy-adapter,jobservice,127.0.0.1,.local,.internal,core,registryctl,redis,registry,nginx,db,log,exporter
PORT=8080
METRIC_ENABLE=true
METRIC_PATH=/metrics
METRIC_PORT=9090
METRIC_NAMESPACE=harbor
METRIC_SUBSYSTEM=core
QUOTA_UPDATE_PROVIDER=db

建立 Harbor container

# 定義 Harbor 對外的 url
HARBOR_FQDN="pharbor.example.com"
# 定義 Harbor 資料永存目錄區
HARBOR_PV="/data"
[ ! -d ${HARBOR_PV} ] && sudo mkdir -p ${HARBOR_PV}
sudo chown 10000:10000 ${HARBOR_PV}
# Run Harbor Container
sudo podman run --name=core --detach \
--network=harbor \
--cap-add=setuid \
--cap-add=setgid \
--cap-drop=all \
--env-file=/etc/harbor/coreenv \
--env=EXT_ENDPOINT=https://${HARBOR_FQDN} \
--secret=harbor-secret,type=env,target=CORE_SECRET \
--secret=db-secret,type=env,target=POSTGRESQL_PASSWORD \
--secret=jobservice-secret,type=env,target=JOBSERVICE_SECRET \
--secret=registry-passwd,type=env,target=REGISTRY_CREDENTIAL_PASSWORD \
--secret=harbor-secretkey,type=mount,target=/etc/core/key \
--secret=harbor-key,type=mount,target=/etc/core/private_key.pem \
--volume=${HARBOR_PV}:/data:z \
--volume=/etc/harbor/harbor.conf:/etc/core/app.conf:ro \
--volume=$(find /etc/ssl/certs/ -name ca-*.crt ! -name "*trust*"):/etc/core/certificates/root.crt:ro \
--volume=/usr/share/zoneinfo/Asia/Taipei:/etc/localtime:ro \
goharbor/harbor-core:${HARBOR_VERSION}

3.7. 部署 jobservice

編輯設定檔

sudo nano /etc/harbor/jobservice.yml

檔案內容如下 :

---
#Protocol used to serve
protocol: "http"
#Server listening port
port: 8080
#Worker pool
worker_pool:
#Worker concurrency
workers: 10
backend: "redis"
#Additional config if use 'redis' backend
redis_pool:
#redis://[arbitrary_username:password@]ipaddress:port/database_index
redis_url: redis://redis:6379/2?idle_timeout_seconds=30
namespace: "harbor_job_service_namespace"
idle_timeout_second: 3600
#Loggers for the running job
job_loggers:
# The jobLoggers backend name, only support "STD_OUTPUT", "FILE" and/or "DB"
- name: "STD_OUTPUT"
level: "INFO" # INFO/DEBUG/WARNING/ERROR/FATAL
- name: "FILE"
level: "INFO"
settings: # Customized settings of logger
base_dir: "/var/log/jobs"
sweeper:
duration: 1 #days
settings: # Customized settings of sweeper
work_dir: "/var/log/jobs"
#Loggers for the job service
loggers:
- name: "STD_OUTPUT" # Same with above
level: "INFO"
metric:
enabled: true
path: /metrics
port: 9090
reaper:
# the max time to wait for a task to finish, if unfinished after max_update_hours, the task will be mark as error, but the task will continue to run, default value is 24,
max_update_hours: 24
# the max time for execution in running state without new task created
max_dangling_hours: 168
# the max size of job log returned by API, default is 10M
max_retrieve_size_mb: 10

編輯環境變數

sudo nano /etc/harbor/jobservice.env

檔案內容 :

REGISTRY_URL=http://registry:5000
CORE_URL=http://core:8080
REGISTRY_CONTROLLER_URL=http://registryctl:8080
JOBSERVICE_WEBHOOK_JOB_MAX_RETRY=3
JOBSERVICE_WEBHOOK_JOB_HTTP_CLIENT_TIMEOUT=3
LOG_LEVEL=info
HTTP_PROXY=
HTTPS_PROXY=
NO_PROXY=localhost,postgresql,portal,trivy-adapter,jobservice,127.0.0.1,.local,.internal,core,registryctl,redis,registry,nginx,db,log,exporter
REGISTRY_CREDENTIAL_USERNAME=harbor_registry_user
MAX_JOB_DURATION_SECONDS=86400
METRIC_NAMESPACE=harbor
METRIC_SUBSYSTEM=jobservice

建立 jobservice container

# 定義 Jobservice 資料永存目錄區
JOBSVC_PV="/data/job_logs"
[ ! -d ${JOBSVC_PV} ] && sudo mkdir -p ${JOBSVC_PV}
sudo chown 10000:10000 ${JOBSVC_PV}
sudo podman run --name=jobservice --detach \
--network=harbor \
--cap-add=setuid \
--cap-add=setgid \
--cap-add=chown \
--cap-drop=all \
--env-file=/etc/harbor/jobservice.env \
--secret=harbor-secret,type=env,target=CORE_SECRET \
--secret=jobservice-secret,type=env,target=JOBSERVICE_SECRET \
--secret=registry-passwd,type=env,target=REGISTRY_CREDENTIAL_PASSWORD \
--volume=/etc/harbor/jobservice.yml:/etc/jobservice/config.yml \
--volume=${JOBSVC_PV}:/var/log/jobs:z \
--volume=$(realpath $(find /etc/ssl/certs/ -name ca-*.crt ! -name "*trust*")):/harbor_cust_cert/root.crt:ro,Z \
goharbor/harbor-jobservice:${HARBOR_VERSION}

3.8. 部署 exporter

編輯環境變數檔

sudo nano /etc/harbor/exporter.env

檔案內容如下 :

LOG_LEVEL=info
HARBOR_EXPORTER_PORT=8080
HARBOR_EXPORTER_METRICS_PATH=/metrics
HARBOR_EXPORTER_METRICS_ENABLED=true
HARBOR_EXPORTER_MAX_REQUESTS=30
HARBOR_EXPORTER_CACHE_TIME=23
HARBOR_EXPORTER_CACHE_CLEAN_INTERVAL=14400
HARBOR_METRIC_NAMESPACE=harbor
HARBOR_METRIC_SUBSYSTEM=exporter
HARBOR_SERVICE_HOST=core
HARBOR_REDIS_URL=redis://redis:6379/2?idle_timeout_seconds=30
HARBOR_REDIS_NAMESPACE=harbor_job_service_namespace
HARBOR_REDIS_TIMEOUT=3600
HARBOR_SERVICE_PORT=8080
HARBOR_SERVICE_SCHEME=http
HARBOR_DATABASE_HOST=postgresql
HARBOR_DATABASE_PORT=5432
HARBOR_DATABASE_USERNAME=postgres
HARBOR_DATABASE_DBNAME=registry
HARBOR_DATABASE_SSLMODE=disable
HARBOR_DATABASE_MAX_IDLE_CONNS=100
HARBOR_DATABASE_MAX_OPEN_CONNS=900
HARBOR_DATABASE_CONN_MAX_LIFETIME=5m
HARBOR_DATABASE_CONN_MAX_IDLE_TIME=0

建立 exporter container

sudo podman run -d \
--name exporter --network harbor \
--env-file /etc/harbor/exporter.env \
--secret=db-secret,type=env,target=HARBOR_DATABASE_PASSWORD \
--volume=$(realpath $(find /etc/ssl/certs/ -name ca-*.crt ! -name "*trust*")):/harbor_cust_cert/root.crt:ro,Z \
goharbor/harbor-exporter:${HARBOR_VERSION}

3.9. 部署 Nginx

產生自簽憑證

git clone https://github.com/braveantony/mkcert.git
# change for your base domain
nano mkcert/config
# Server 相關設定
DOMAIN_NAME="example.com"
./mkcert/certctl
sudo mkdir -p /data/secret/cert
sudo cp mkcert/example.com/example.com.crt /data/secret/cert/server.crt
sudo cp mkcert/example.com/example.com.key /data/secret/cert/server.key
sudo chown -R 10000:10000 /data/secret/cert

建立設定檔

sudo nano /etc/harbor/nginx.conf

檔案內容 :

worker_processes auto;
pid /tmp/nginx.pid;
events {
worker_connections 3096;
use epoll;
multi_accept on;
}
http {
client_body_temp_path /tmp/client_body_temp;
proxy_temp_path /tmp/proxy_temp;
fastcgi_temp_path /tmp/fastcgi_temp;
uwsgi_temp_path /tmp/uwsgi_temp;
scgi_temp_path /tmp/scgi_temp;
tcp_nodelay on;
include /etc/nginx/conf.d/*.upstream.conf;
# this is necessary for us to be able to disable request buffering in all cases
proxy_http_version 1.1;
upstream core {
server core:8080;
}
upstream portal {
server portal:8080;
}
log_format timed_combined '$remote_addr - '
'"$request" $status $body_bytes_sent '
'"$http_referer" "$http_user_agent" '
'$request_time $upstream_response_time $pipe';
access_log /dev/stdout timed_combined;
map $http_x_forwarded_proto $x_forwarded_proto {
default $http_x_forwarded_proto;
"" $scheme;
}
include /etc/nginx/conf.d/*.server.conf;
server {
listen 8443 ssl;
# server_name harbordomain.com;
server_tokens off;
# SSL
ssl_certificate /etc/cert/server.crt;
ssl_certificate_key /etc/cert/server.key;
# Recommendations from https://raymii.org/s/tutorials/Strong_SSL_Security_On_nginx.html
ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers '!aNULL:kECDH+AESGCM:ECDH+AESGCM:RSA+AESGCM:kECDH+AES:ECDH+AES:RSA+AES:';
ssl_prefer_server_ciphers on;
ssl_session_cache shared:SSL:10m;
# disable any limits to avoid HTTP 413 for large image uploads
client_max_body_size 0;
# required to avoid HTTP 411: see Issue #1486 (https://github.com/docker/docker/issues/1486)
chunked_transfer_encoding on;
# Add extra headers
add_header Strict-Transport-Security "max-age=31536000; includeSubdomains; preload";
add_header X-Frame-Options DENY;
add_header Content-Security-Policy "frame-ancestors 'none'";
# customized location config file can place to /etc/nginx dir with prefix harbor.https. and suffix .conf
include /etc/nginx/conf.d/harbor.https.*.conf;
location / {
proxy_pass http://portal/;
proxy_set_header Host $http_host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $x_forwarded_proto;
proxy_cookie_path / "/; HttpOnly; Secure";
proxy_buffering off;
proxy_request_buffering off;
}
location /c/ {
proxy_pass http://core/c/;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $x_forwarded_proto;
proxy_cookie_path / "/; Secure";
proxy_buffering off;
proxy_request_buffering off;
}
location /api/ {
proxy_pass http://core/api/;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $x_forwarded_proto;
proxy_cookie_path / "/; Secure";
proxy_buffering off;
proxy_request_buffering off;
}
location /v1/ {
return 404;
}
location /v2/ {
proxy_pass http://core/v2/;
proxy_set_header Host $http_host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $x_forwarded_proto;
proxy_buffering off;
proxy_request_buffering off;
proxy_send_timeout 900;
proxy_read_timeout 900;
}
location /service/ {
proxy_pass http://core/service/;
proxy_set_header Host $http_host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $x_forwarded_proto;
proxy_cookie_path / "/; Secure";
proxy_buffering off;
proxy_request_buffering off;
}
location /service/notifications {
return 404;
}
}
server {
listen 8080;
#server_name harbordomain.com;
return 308 https://$host:443$request_uri;
}
upstream core_metrics {
server core:9090;
}
upstream js_metrics {
server jobservice:9090;
}
upstream registry_metrics {
server registry:9090;
}
upstream harbor_exporter {
server exporter:8080;
}
server {
listen 9090;
location = /metrics {
if ($arg_comp = core) { proxy_pass http://core_metrics; }
if ($arg_comp = jobservice) { proxy_pass http://js_metrics; }
if ($arg_comp = registry) { proxy_pass http://registry_metrics; }
proxy_pass http://harbor_exporter;
}
}
}

建立 nginx container

sudo podman run --name=proxy \
--detach --network=harbor \
--cap-drop=all \
--cap-add=setuid --cap-add=setgid --cap-add=chown \
--cap-add=net_bind_service --cap-add=dac_override \
--volume=/etc/harbor/jobservice.yml:/etc/jobservice/config.yml:z \
--volume=/etc/harbor/nginx.conf:/etc/nginx/nginx.conf:ro,z \
--volume=/data/secret/cert:/etc/cert:ro,Z \
--publish=80:8080/tcp \
--publish=443:8443/tcp \
--publish=9090:9090/tcp \
goharbor/nginx-photon:${HARBOR_VERSION}

3.10. 部署 trivy

編輯環境變數檔

sudo nano /etc/harbor/trivy.env

檔案內容如下 :

REGISTRY_URL=http://registry:5000
SCANNER_LOG_LEVEL=info
SCANNER_REDIS_URL=redis://redis:6379/5?idle_timeout_seconds=30
SCANNER_STORE_REDIS_URL=redis://redis:6379/5?idle_timeout_seconds=30
SCANNER_STORE_REDIS_NAMESPACE=harbor.scanner.trivy:store
SCANNER_STORE_REDIS_NAMESPACE=harbor.scanner.trivy:store
SCANNER_JOB_QUEUE_REDIS_URL=redis://redis:6379/5?idle_timeout_seconds=30
SCANNER_JOB_QUEUE_REDIS_NAMESPACE=harbor.scanner.trivy:job-queue
SCANNER_TRIVY_CACHE_DIR=/home/scanner/.cache/trivy
SCANNER_TRIVY_REPORTS_DIR=/home/scanner/.cache/reports
SCANNER_TRIVY_VULN_TYPE=os,library
SCANNER_TRIVY_SEVERITY=UNKNOWN,LOW,MEDIUM,HIGH,CRITICAL
SCANNER_TRIVY_IGNORE_UNFIXED=False
SCANNER_TRIVY_SKIP_UPDATE=False
SCANNER_TRIVY_SKIP_JAVA_DB_UPDATE=False
SCANNER_TRIVY_OFFLINE_SCAN=True
SCANNER_TRIVY_SECURITY_CHECKS=vuln
SCANNER_TRIVY_GITHUB_TOKEN=
SCANNER_TRIVY_INSECURE=False
SCANNER_TRIVY_TIMEOUT=5m0s

建立 trivy container

sudo podman run --name=trivy-adapter --detach \
--network=harbor \
--cap-drop=all \
--env-file=/etc/harbor/trivy.env \
goharbor/trivy-adapter-photon:${HARBOR_VERSION}

3.11. 檢查所有服務是否異常

執行以下命令檢查 container 運作狀態

sudo podman ps -a

正確執行結果 :

CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
ad033894240e localhost/goharbor/redis-photon:v2.14.2 redis-server /etc... 2 hours ago Up 2 hours (healthy) redis
15a84e395302 localhost/goharbor/harbor-db:v2.14.2 2 hours ago Up 2 hours (healthy) postgresql
a2ac4a2928d0 localhost/goharbor/harbor-portal:v2.14.2 nginx -g daemon o... About an hour ago Up About an hour (healthy) portal
5dd1ea9c53d8 localhost/goharbor/registry-photon:v2.14.2 About an hour ago Up About an hour (healthy) registry
7ad9c1c36d54 localhost/goharbor/harbor-registryctl:v2.14.2 52 minutes ago Up 52 minutes (healthy) registryctl
1ecd13d98484 localhost/goharbor/harbor-core:v2.14.2 42 minutes ago Up 42 minutes (healthy) core
c7fc40df1b30 localhost/goharbor/harbor-jobservice:v2.14.2 28 minutes ago Up 28 minutes (healthy) jobservice
05c09539108d localhost/goharbor/harbor-exporter:v2.14.2 21 minutes ago Up 21 minutes exporter
243817e09c05 localhost/goharbor/nginx-photon:v2.14.2 nginx -g daemon o... 36 seconds ago Up 36 seconds (healthy) 0.0.0.0:80->8080/tcp, 0.0.0.0:443->8443/tcp proxy
8c381495220b localhost/goharbor/trivy-adapter-photon:v2.14.2 3 seconds ago Up 4 seconds (healthy) trivy

3.12. 連線 Harbor UI

打開瀏覽器，連線至

https://$HARBOR_FQDN

輸入身分資訊 :

帳號 : admin
密碼 : Harbor12345

3.13. 設定 Harbor 開機自動啟動

目前只適用 systemd 的 OS，如果是 OpenRC 就不適用

產生 Systemd Unit 並控制順序

sudo podman generate systemd --name redis --restart-policy=always --after network-online.target --files
sudo podman generate systemd --name postgresql --restart-policy=always --after container-redis.service --files
sudo podman generate systemd --name registry --restart-policy=always --after container-postgresql.service --files
sudo podman generate systemd --name portal --restart-policy=always --after container-registry.service --files
sudo podman generate systemd --name registryctl --restart-policy=always --after container-portal.service --files
sudo podman generate systemd --name core --restart-policy=always --after container-registryctl.service --files
sudo podman generate systemd --name jobservice --restart-policy=always --after container-core.service --files
sudo podman generate systemd --name exporter --restart-policy=always --after container-jobservice.service --files
sudo podman generate systemd --name proxy --restart-policy=always --after container-exporter.service --files
sudo podman generate systemd --name trivy-adapter --restart-policy=always --after container-proxy.service --files

將這些 .service 檔案複製到 systemd 系統目錄
```
sudo cp container-*.service /etc/systemd/system/
```
重新載入 daemon
```
sudo systemctl daemon-reload
```

設定服務開機自動啟動

sudo systemctl enable \
container-redis.service \
container-postgresql.service \
container-registry.service \
container-portal.service \
container-registryctl.service \
container-core.service \
container-jobservice.service \
container-exporter.service \
container-proxy.service \
container-trivy-adapter.service

重開機測試
```
sudo reboot
```
ssh 連線進 podman host 主機

確認 harbor 各元件的 containers 運作狀態

sudo podman ps -a

執行結果 :

CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
ad033894240e localhost/goharbor/redis-photon:v2.14.2 redis-server /etc... 7 hours ago Up 50 seconds (healthy) redis
15a84e395302 localhost/goharbor/harbor-db:v2.14.2 7 hours ago Up 50 seconds (healthy) postgresql
a2ac4a2928d0 localhost/goharbor/harbor-portal:v2.14.2 nginx -g daemon o... 6 hours ago Up 49 seconds (healthy) portal
7ad9c1c36d54 localhost/goharbor/harbor-registryctl:v2.14.2 6 hours ago Up 49 seconds (healthy) registryctl
1ecd13d98484 localhost/goharbor/harbor-core:v2.14.2 6 hours ago Up 49 seconds (healthy) core
c7fc40df1b30 localhost/goharbor/harbor-jobservice:v2.14.2 6 hours ago Up 49 seconds (healthy) jobservice
05c09539108d localhost/goharbor/harbor-exporter:v2.14.2 5 hours ago Up 49 seconds exporter
8df8d211ff56 localhost/goharbor/registry-photon:v2.14.2 3 hours ago Up 49 seconds (healthy) registry
a5c4a370ab25 localhost/goharbor/trivy-adapter-photon:v2.14.2 8 minutes ago Up 49 seconds (healthy) trivy-adapter
479f0bd782bf localhost/goharbor/nginx-photon:v2.14.2 nginx -g daemon o... 5 minutes ago Up 48 seconds (healthy) 0.0.0.0:80->8080/tcp, 0.0.0.0:443->8443/tcp, 0.0.0.0:9090->9090/tcp proxy

Step4：驗證

設定 podman 信任 harbor 自簽 root CA 憑證

HARBOR_FQDN="pharbor.example.com"
sudo mkdir -p /etc/containers/certs.d/${HARBOR_FQDN}
sudo cp ${HOME}/mkcert/example.com/example.com.crt /etc/containers/certs.d/${HARBOR_FQDN}/ca.crt

podman 登入 harbor

podman login ${HARBOR_FQDN} -u admin -p "Harbor12345"

執行結果：

Login Succeeded!

下載 Nginx container image

podman pull docker.io/library/nginx:stable

修改 image tag

podman tag docker.io/library/nginx:stable ${HARBOR_FQDN}/library/nginx:stable

push image 至 harbor

podman push ${HARBOR_FQDN}/library/nginx:stable

執行結果：

Getting image source signatures
Copying blob e50a58335e13 done |
Copying blob 5c00c19cd4b3 done |
Copying blob 7dfc0854a228 done |
Copying blob 4b43bb8fd938 done |
Copying blob 5f3758e9c329 done |
Copying blob ac61f062f9a7 done |
Copying blob 16b60074fa6f done |
Copying config 94a30ed18e done |
Writing manifest to image destination

在 UI 檢查 library 專案是否多了一片 nginx image

刪除原始的 image

podman rmi docker.io/library/nginx:stable ${HARBOR_FQDN}/library/nginx:stable

執行結果：

Untagged: docker.io/library/nginx:stable
Untagged: pharbor.example.com/library/nginx:stable
Deleted: 94a30ed18e45363486a55379bd1fbb8c479f36524ae816779f3553afe6b787ed

從 harbor 下載 nginx image

podman pull ${HARBOR_FQDN}/library/nginx:stable

執行結果：

Trying to pull pharbor.example.com/library/nginx:stable...
Getting image source signatures
Copying blob 2efbe32a5480 done |
Copying blob 6996c0be3403 done |
Copying blob ea368c811a9e done |
Copying blob 765e9812de72 done |
Copying blob b94f38f9c422 done |
Copying blob 88e560633873 done |
Copying blob f72edb929581 done |
Copying config 94a30ed18e done |
Writing manifest to image destination
94a30ed18e45363486a55379bd1fbb8c479f36524ae816779f3553afe6b787ed

掃描弱點和產出 SBOM

點進 library/nginx

點選 “開始掃描” 按鈕和 “GENERATE SBOM” 按鈕

點選 “SBOM detials”

檢視掃描節點

參考資料

Podman 安裝 harbor - zggzcgy blog

部署 VKS Clusters

Tue, 10 Feb 2026 05:10:28 +0800

1. 先決條件

多個 ESX 主機透過 vSphere Distributed Switch (VDS) 連接。
已設定 Shared storage，例如 vSAN 或 NFS。
已啟用 vSphere HA 和 fully-automated DRS。
已啟用 vSphere Lifecycle Manager (vLCM)。
已設定網路，可使用 NSX 及其內嵌的 load balancer，或使用 VDS 搭配外部的 load balancer。

2. ESXI 安裝設定

幫每一台 esxi 都設定固定 ip、DNS

幫每一台 esxi 設定 ntp 校時

2.1 設定 vCenter

參考：https://hackmd.io/@wu-andy/rkXpmTGteg

2.2. 環境資訊

vCenter 版本：8.0.3
3 台 ESXi 版本：8.0.3

2.3. 設定 VSS 和 VDS

每台 ESXI 要再添加兩張網卡，總共三個，並且都要不同網段

重新命名 VSS(VM Network)

此網段為 172.21.1.0/24
將 VSS(VM Network) 重新命名成 mgmt，所有 ESXI 都要做，這裡更改名稱主要是因為 supervisor 再找網卡會因為名稱有空格找不到

第二台 ESXI

第三台 ESXI

設定 VDS 給 VIP 使用

此網段為 172.20.2.0/24
做出 VDS ，這個 VDS 給 VIP 使用

在 vSphere Client 中，導覽到 Datacenter。
在瀏覽器中的 Datacenter 上按一下滑鼠右鍵，然後選取 Distributed Switch > 新增 Distributed Switch。
輸入新 Distributed Switch 的名稱，例如：DSwitch。
在選取版本中，輸入 Distributed Switch 的版本。選取 8.0.3。
在設定組態中，輸入上行連接埠數目，輸入值 1 和取名 VIP。
檢閱設定，然後按一下完成。
在您建立的 Distributed Switch 上按一下滑鼠右鍵，然後選取設定編輯設定。
在進階索引標籤上，輸入大於 1700 的值作為 MTU (位元組) 值，然後按一下確定。在承載覆疊流量的任何網路上，MTU 大小必須大於或等於 1700。例如，9000。如果 vks 是安裝在 NSX 環境， MTU 就要設大於 1700。沒有的話可以只設 1500
加入 esxi 主機

指定一張網卡

VDS 給 workload cluster 使用

此網段為 172.20.3.0/24
再做出一個 VDS，這個 VDS 給 workload cluster 使用

加入 esxi 主機

指定一張網卡

2.4. 確認已設定 vsan

要記得略過快速入門

在監控 -> Skyline Health 點選無回應警示

2.5. 確認已啟用 vSphere HA 和 fully-automated DRS

2.6. 確認已啟用 vSphere Lifecycle Manager (vLCM)

安裝 Avi VM

VMware Avi Load Balancer

設定 Avi

第一次登入才需設管理帳號密碼

設定一組密碼，用來加密設定匯出與排程備份中的敏感資料（例如金鑰、憑證、雲端/整合帳密等）。之後做還原/匯入時，必須提供同一組密語，否則無法還原。

設定 avi 自己的 vip

如果有多個 avi 主機也可以把其他主機加入，做出 avi 叢集

可以透過 vip 登入 avi

設定授權

到授權頁面把 license 改成 enterprise tier

設定 DNS/NTP

Administration Settings DNS/NTP

設定 VMware Cloud

建立 vCenter Cloud 讓 Avi 能「在 vSphere 上自動部署並管理」Service Engine，並使用該 vSphere 環境的 network/storage/compute 資源來提供 load balancing

透過在「建立」下拉清單中選擇此選項來設定VMware vCenter/vSphere ESX雲端

為雲端提供一個名稱，然後從類型選單中選擇 VMware vCenter/vSphere ESX

設定關閉 dhcp 和 ipv6
勾選 Prefer Static Routes vs Directly Connected Network : Avi 在決定如何把 VIP 的流量送出去時，會優先使用「靜態路由（static route）」定義的 next-hop，而不是直接利用 SE 所在介面上的「直接相連（directly-connected）」行為（例如 ARP）去處理該子網流量

配置 vCenter 的憑證

選擇指定的 datacenter ，以及選擇 Service Engine（SE）用來做管理介面（management vNIC）的網路。不用勾選 content library，然後保存

設定 Network

設定後保存離開，等待狀態變為綠色

Infrastructure > Cloud Resources > Networks

定義一個子網路（subnet）與一組靜態 IP 範圍，供 Controller 配發給 Virtual Service 的 VIP（虛擬 IP）和 Service Engine（SE）VM 的管理 / data IP

這邊定義 ip range，supervisor 在啟用的時候會先從裡面拿兩個 VIP 出來用，這兩個 VIP 後端會導流到 supervisor 在 worklaod 網路的那隻腳

所以 supervisor 會有三個 VIP

一個在管理網段(5 個 IP 裡面其中的一個) —> 提供 supervisor 內部運作用

兩個在 SE 的 VI P範圍 (獨立的兩個VIP) —> 提供使用這下指令與監控用 1 號不過 AVI ，由 supervisor CP 節點取得 2 號使用 AVI，在啟用過程中由 vCenter/Supervisor 發送 API 自動配置

定義 VIP ip range

建立 IPAM profile

建立虛擬服務時，需要使用 IPAM 來指派虛擬 IP 位址。

當有人（例如 vCenter Supervisor）向我要一個 VIP 時，我被授權從哪些網路發放 IP？這邊指定 VIP 的 network。

建立 DNS profile

這邊先新增任意一個 domain

再回到 VMware Cloud 設定 IPAM

設定 Certificate

這邊 common name 要填的是 avi 自己的 vip 所對應的 domain

SAN 要填的就是 avi 自己的 vip 位置

複製憑證，待會在創建 supervisor cluster 時會需要貼上此憑證

更換訪問 avi 入口憑證

設定 Service Engine Group

Infrastructure > Cloud Resources > Service Engine Group

設定 Static Routes

Infrastructure > Cloud Resources > VRF Context

這邊要設定 workload 網段要路由到 VIP 網段的 gateway

設定 vSphere zone

選擇要用於 VKS 叢集和 vSphere Pod 的叢集

設定工作負載管理 (啟動 supervisor)

要將前面在 avi 創建的憑證放進來

起始 ip 這邊是設給 supervisor cluster 的 vip，他需要保留五個連續 ip ，所以這裡設定 172.21.1.30，就是代表到 172.21.1.34 都會分配給 supervisor cluster 使用，會使用的是 supervisor control plane 的節點 IP+VIP+升級保留，總共 5 個 IP，但是使用順序不一定
這意這邊起始 ip 不能跟前面 avi 設定的 vip 範圍重疊

設定 workload cluster 網路資訊

這邊會設定 workload cluster 的 vm 他拿到的 ip 是在以下範圍
網路名稱要填小寫
網路範圍也不能跟前面重複

創建 workload cluster(TKG)

確認 supervisor 狀態都正確

開啟瀏覽器，連接 https://172.21.2.81，下載 kubectl CLI Plugin

準備一台 ubuntu bastion 機使用指令下載

$ curl -k https://172.21.2.81/wcp/plugin/linux-amd64/vsphere-plugin.zip -o vsphere-plugin.zip

解壓縮

$ sudo apt install unzip
$ unzip vsphere-plugin.zip
$ sudo cp -r bin/* /usr/local/bin

登入 supervisor，使用 VC 帳號登入

$ kubectl vsphere login --insecure-skip-tls-verify --server=172.21.2.81
Username: administrator@vsphere.local
Password:
Logged in successfully.
You have access to the following contexts:
172.21.2.81
svc-tkg-domain-c19
svc-velero-domain-c19
If the context you wish to use is not in this list, you may need to try
logging in again later, or contact your cluster administrator.
To change context, use `kubectl config use-context <workload name>`

此時看到的 control-plane 三台就是剛剛創建的 supervisor vm，而 worker 就是 esxi 三台，因此如果在這裡創見 pod ，就是直接跑在 esxi 上

$ kubectl get no -owide
NAME STATUS ROLES AGE VERSION INTERNAL-IP EXTERNAL-IP OS-IMAGE KERNEL-VERSION CONTAINER-RUNTIME
423d9b295547c821ffd05433fe560885 Ready control-plane,master 42m v1.30.10+vmware.1-fips 172.21.3.52 <none> VMware Photon OS/Linux 5.10.237-2.ph4-esx containerd://1.7.25+vmware.2-fips
423dee48377f7b6bf5ee23a17f104118 Ready control-plane,master 42m v1.30.10+vmware.1-fips 172.21.3.51 <none> VMware Photon OS/Linux 5.10.237-2.ph4-esx containerd://1.7.25+vmware.2-fips
423df53a268cb03c9c8f7833d1968033 Ready control-plane,master 50m v1.30.10+vmware.1-fips 172.21.3.50 <none> VMware Photon OS/Linux 5.10.237-2.ph4-esx containerd://1.7.25+vmware.2-fips
esxi1.andy.lab Ready agent 4m58s v1.30.5-sph-806add6 172.21.1.2 <none> <unknown> <unknown> <unknown>
esxi2.andy.lab Ready agent 7m v1.30.5-sph-806add6 172.21.1.3 <none> <unknown> <unknown> <unknown>
esxi3.andy.lab Ready agent 5m53s v1.30.5-sph-806add6 172.21.1.4 <none> <unknown> <unknown> <unknown>

建立 vSphere namespace

建立一個 tkg-workloads namespace

新增權限

設定 administrator@vsphere.local 為擁有者

新增儲存區

vSAN Default Storage Policy 在 sc 裡名稱會叫 vsan-default-storage-policy

$ kubectl get storageclass
NAME PROVISIONER RECLAIMPOLICY VOLUMEBINDINGMODE ALLOWVOLUMEEXPANSION AGE
management-storage-policy-encryption csi.vsphere.vmware.com Delete Immediate true 5d18h
management-storage-policy-regular csi.vsphere.vmware.com Delete Immediate true 5d18h
management-storage-policy-single-node csi.vsphere.vmware.com Delete Immediate true 5d18h
management-storage-policy-stretched-lite csi.vsphere.vmware.com Delete Immediate true 5d18h
management-storage-policy-thin csi.vsphere.vmware.com Delete Immediate true 5d18h
vm-encryption-policy csi.vsphere.vmware.com Delete Immediate true 5d18h
vsan-default-storage-policy csi.vsphere.vmware.com Delete Immediate true 5d18h

新增 VM Class

選用預設定義的 best-effort-medium

也可以建立自定義 VM Class

建立一個 4core CPU,16G RAM

登入 supervisor，使用 VC 帳號登入

$ kubectl vsphere login --insecure-skip-tls-verify --server=172.21.2.81
Username: administrator@vsphere.local
Password:
Logged in successfully.
You have access to the following contexts:
10.200.2.31
svc-tkg-domain-c17
svc-velero-domain-c17
tkg-workloads

切換 context

$ kubectl config use-context tkg-workloads

檢視目前 TKG 可使用的版本，這邊會使用 v1.32.3---vmware.1-fips-vkr.2 版本

$ kubectl get tkr
v1.31.11---vmware.3-fips-vkr.1 v1.31.11+vmware.3-fips-vkr.1 True True 5d17h
v1.31.4---vmware.1-fips-vkr.3 v1.31.4+vmware.1-fips-vkr.3 True True 5d17h
v1.31.7---vmware.1-fips-vkr.2 v1.31.7+vmware.1-fips-vkr.2 True True 5d17h
v1.32.0---vmware.6-fips-vkr.2 v1.32.0+vmware.6-fips-vkr.2 True True 5d17h
v1.32.3---vmware.1-fips-vkr.2 v1.32.3+vmware.1-fips-vkr.2 True True 5d17h
v1.32.7---vmware.3-fips-vkr.1 v1.32.7+vmware.3-fips-vkr.1 True True 5d17h
......

在 content library 檢查是否已經存在

如果遇到一直同步失敗，就移除 Kubernetes Service Content Library 後再重新指定讓他在同步一次

離線環境要自行準備 content library https://wp-content.vmware.com/v2/latest/ 可參考

編輯 cluster.yaml

$ nano my-tkg-cluster.yaml
apiVersion: run.tanzu.vmware.com/v1alpha2
kind: TanzuKubernetesCluster
metadata:
name: tkgs-v2-cluster-default
namespace: tkg-workloads
spec:
topology:
controlPlane:
replicas: 1
vmClass: best-effort-medium # 根據自己定義的名稱更換
storageClass: 'vsan-default-storage-policy' # 根據自己定義的名稱更換
tkr:
reference:
name: v1.32.3---vmware.1-fips-vkr.2
nodePools:
- name: worker-nodepool-a1
replicas: 1
vmClass: best-effort-medium # 根據自己定義的名稱更換
storageClass: 'vsan-default-storage-policy' # 根據自己定義的名稱更換
tkr:
reference:
name: v1.32.3---vmware.1-fips-vkr.2

部署 3m1w 架構

apiVersion: run.tanzu.vmware.com/v1alpha2
kind: TanzuKubernetesCluster
metadata:
name: my-tkgs-cluster
namespace: tkg-workloads
spec:
topology:
controlPlane:
replicas: 3
vmClass: myvm # 根據自己定義的名稱更換
storageClass: 'vsan-default-storage-policy' # 根據自己定義的名稱更換
tkr:
reference:
name: v1.32.3---vmware.1-fips-vkr.2
nodePools:
- name: worker-nodepool-a1
replicas: 1
vmClass: myvm # 根據自己定義的名稱更換
storageClass: 'vsan-default-storage-policy' # 根據自己定義的名稱更換
volumes:
- name: containerd
mountPath: /var/lib/containerd
capacity:
storage: 50Gi
tkr:
reference:
name: v1.32.3---vmware.1-fips-vkr.2
settings:
storage:
defaultClass: 'vsan-default-storage-policy'
network:
cni:
name: calico
serviceDomain: cluster.local

新版使用 cluster yaml 部署 TKG 參考

部署 TKG

$ kubectl apply -f my-tkg-cluster.yaml

檢視 TKG 部署完成

$ kubectl -n tkg-workloads get tkc
Warning: run.tanzu.vmware.com/tanzukubernetescluster is deprecated. It is succeeded by cluster.x-k8s.io/cluster. Refer to documentation.
NAME CONTROL PLANE WORKER KUBERNETES RELEASE NAME AGE READY KUBERNETES RELEASE COMPATIBLE UPDATES AVAILABLE
tkgs-v2-cluster-default 1 1 v1.32.7---vmware.3-fips-vkr.1 80m True True

登入 TKG 叢集

$ kubectl vsphere login --server=10.200.2.31 \
--tanzu-kubernetes-cluster-name tkgs-v2-cluster-default \
--tanzu-kubernetes-cluster-namespace tkg-workloads \
--insecure-skip-tls-verify \
-u administrator@vsphere.local

檢視叢集狀態是否正常

$ kubectl get no
NAME STATUS ROLES AGE VERSION
tkgs-v2-cluster-default-ljb66-8jk74 Ready control-plane 18m v1.32.7+vmware.3-fips
tkgs-v2-cluster-default-worker-nodepool-a1-jh2cz-f65qq-9q5fl Ready <none> 9m1s v1.32.7+vmware.3-fips
$ kubectl get po -A
NAMESPACE NAME READY STATUS RESTARTS AGE
kube-system antrea-agent-9dqxv 2/2 Running 0 9m47s
kube-system antrea-agent-tjkn5 2/2 Running 0 17m
kube-system antrea-controller-798b767987-7hl8h 1/1 Running 0 17m
kube-system coredns-5958c95bcd-hvdrg 1/1 Running 0 18m
kube-system coredns-5958c95bcd-ms2qz 1/1 Running 0 15m
kube-system docker-registry-tkgs-v2-cluster-default-ljb66-8jk74 1/1 Running 0 19m
kube-system docker-registry-tkgs-v2-cluster-default-worker-nodepool-a1-jh2cz-f65qq-9q5fl 1/1 Running 0 9m47s
kube-system etcd-tkgs-v2-cluster-default-ljb66-8jk74 1/1 Running 0 19m
kube-system kube-apiserver-tkgs-v2-cluster-default-ljb66-8jk74 1/1 Running 0 19m
kube-system kube-controller-manager-tkgs-v2-cluster-default-ljb66-8jk74 1/1 Running 1 (17m ago) 19m
kube-system kube-proxy-lt8qd 1/1 Running 0 9m47s
kube-system kube-proxy-rfmtp 1/1 Running 0 18m
kube-system kube-scheduler-tkgs-v2-cluster-default-ljb66-8jk74 1/1 Running 1 (17m ago) 19m
kube-system metrics-server-54d7fc854c-5v4zn 1/1 Running 0 17m
kube-system snapshot-controller-fd845b8f8-fwxr2 1/1 Running 0 18m
secretgen-controller secretgen-controller-5dd46bbcfc-tljsr 1/1 Running 0 17m
tkg-system kapp-controller-7449dcf686-d2hnt 2/2 Running 0 18m
vmware-system-antrea antrea-pre-upgrade-job-klmv4 0/1 Completed 0 18m
vmware-system-auth guest-cluster-auth-svc-vz9zh 1/1 Running 0 16m
vmware-system-cloud-provider guest-cluster-cloud-provider-86466bf878-jp8t2 1/1 Running 1 (17m ago) 18m
vmware-system-csi vsphere-csi-controller-798c4f56b9-gcr69 7/7 Running 0 18m
vmware-system-csi vsphere-csi-node-fqs8t 3/3 Running 4 (15m ago) 18m
vmware-system-csi vsphere-csi-node-r6csv 3/3 Running 0 9m47s

troubshooting

進到 VC

root@vc [ ~ ]# cd /usr/lib/vmware-wcp/
# 查看 supervisor 密碼
root@vc [ /usr/lib/vmware-wcp ]# ./decryptK8Pwd.py
Read key from file
Connected to PSQL
Cluster: domain-c17:16f96da8-eab0-4cb7-b70c-fdcb7737bb3a
IP: 10.200.0.60
PWD: (WV92wWtP{+7F^~1
------------------------------------------------------------

登入 supervisor 後查看 pod 是否異常

root@422f993f634f1e829e2340fa1d73b0eb [ ~ ]# k -n vmware-system-ako get po
NAME READY STATUS RESTARTS AGE
vmware-system-ako-ako-controller-manager-677ff55d9d-x5k94 1/1 Running 0 53m

參考

https://techdocs.broadcom.com/us/en/vmware-security-load-balancing/avi-load-balancer/avi-load-balancer-vmware-cloud-foundation/9-0/deploying-vsphere-supervisor-with-vds-and-avi-load-balancer.html

https://techdocs.broadcom.com/us/en/vmware-cis/vcf/vsphere-supervisor-services-and-standalone-components/latest/managing-vsphere-kubernetes-service/running-tkg-service-clusters/deploying-tkg-service-clusters.html

https://techdocs.broadcom.com/us/en/vmware-security-load-balancing/avi-load-balancer/avi-load-balancer/22-1/vmware-avi-load-balancer-administration-guide/access-settings/certificates/changing-the-nsx-advanced-load-balancer-controller-s-default-certificate.html

Quick Start Kube-ovn on Kubeadm K8s

Mon, 09 Feb 2026 01:50:20 +0800

Quick Start Kube-ovn on HA Kubeadm K8s

1. 建置 K8s 前置作業

K8s 叢集中的每台節點需做以下設定

對於其他 Linux 發行版，請確保 geneve 、 openvswitch 、 ip_tables 、 iptable_nat 、 overlay 和 br_netfilter kernel module 存在。

檢查 OS Kernel 是否有 geneve, openvswitch, ip_tables, iptable_nat 模組

# 定義需要檢查的模組
MODULES="geneve|openvswitch|ip_tables|iptable_nat|overlay|br_netfilter"
# 執行檢查
sudo lsmod | grep -E "$MODULES"

執行結果：

ip_tables 32768 0
x_tables 65536 1 ip_tables
bridge 421888 1 br_netfilter
overlay 212992 0

永久添加

cat <<EOF | sudo tee /etc/modules-load.d/kube-ovn.conf
geneve
openvswitch
ip_tables
iptable_nat
EOF
cat <<EOF | sudo tee /etc/modules-load.d/k8s.conf
overlay
br_netfilter
EOF

現在立刻添加

sudo modprobe geneve
sudo modprobe openvswitch
sudo modprobe ip_tables
sudo modprobe iptable_nat
sudo modprobe overlay
sudo modprobe br_netfilter

檢查

sudo lsmod | grep -E "$MODULES"

執行結果：

iptable_nat 12288 0
openvswitch 217088 0
nsh 12288 1 openvswitch
nf_conncount 24576 1 openvswitch
nf_nat 61440 2 openvswitch,iptable_nat
nf_conntrack 196608 3 nf_nat,openvswitch,nf_conncount
geneve 49152 0
ip6_udp_tunnel 16384 1 geneve
udp_tunnel 32768 1 geneve
br_netfilter 32768 0
bridge 421888 1 br_netfilter
overlay 212992 0
ip_tables 32768 1 iptable_nat
x_tables 65536 2 ip_tables,iptable_nat
libcrc32c 12288 6 nf_conntrack,nf_nat,openvswitch,btrfs,nf_tables,raid456

核心啟動需要開啟 IPv6，如果核心啟動參數包含 ipv6.disable=1 需要設定為 0。

檢查當前 kernel 參數

cat /proc/cmdline

執行結果：

BOOT_IMAGE=/vmlinuz-6.8.0-60-generic root=/dev/mapper/ubuntu--vg-ubuntu--lv ro ipv6.disable=1

設定 ipv6.disable=0

sudo nano /etc/default/grub

需修改的檔案內容如下：

...
GRUB_CMDLINE_LINUX="ipv6.disable=0"

更新 Grub
```
sudo update-grub
```
重新開機
```
sudo reboot
```

確認值為 0

cat /proc/sys/net/ipv6/conf/all/disable_ipv6

執行結果：

kube-proxy 正常運作，Kube-OVN 可以透過 Service ClusterIP 存取 kube-apiserver。
確認 kubelet 設定參數開啟了 CNI，且配置在標準路徑下, kubelet 啟動時應包含下列參數：
- --network-plugin=cni
- --cni-bin-dir=/opt/cni/bin
- --cni-conf-dir=/etc/cni/net.d
確認未安裝其他網路插件，或其他網路插件已被清除，檢查 /etc/cni/net.d/ 路徑下無其他網路插件設定檔。如果之前安裝過其他網路插件，建議刪除後重新啟動機器清理殘留網路資源。

確認 swap 是否關閉

cat /proc/swaps

執行結果如下

Filename Type Size Used Priority

永久添加必要 Kernel Parameters

cat <<EOF | sudo tee /etc/sysctl.d/99-k8s-cri.conf
net.bridge.bridge-nf-call-iptables = 1
net.bridge.bridge-nf-call-ip6tables = 1
net.ipv4.ip_forward = 1
EOF

立即載入 Kernel Parameters
```
sudo sysctl --system
```

驗證 net.bridge.bridge-nf-call-iptables, net.bridge.bridge-nf-call-ip6tables, 和 net.ipv4.ip_forward 的值都設成 1

sysctl net.bridge.bridge-nf-call-iptables net.bridge.bridge-nf-call-ip6tables net.ipv4.ip_forward

執行結果：

net.bridge.bridge-nf-call-iptables = 1
net.bridge.bridge-nf-call-ip6tables = 1
net.ipv4.ip_forward = 1

定義要安裝 K8s 軟體套件版本

KUBERNETES_VERSION=v1.35
CRIO_VERSION=v1.35

安裝添加儲存庫的依賴項

sudo apt-get update
sudo apt-get install -y software-properties-common curl

添加 Kubernetes 和 CRI-O 儲存庫

curl -fsSL https://pkgs.k8s.io/core:/stable:/$KUBERNETES_VERSION/deb/Release.key |
gpg --dearmor -o /etc/apt/keyrings/kubernetes-apt-keyring.gpg
echo "deb [signed-by=/etc/apt/keyrings/kubernetes-apt-keyring.gpg] https://pkgs.k8s.io/core:/stable:/$KUBERNETES_VERSION/deb/ /" |
tee /etc/apt/sources.list.d/kubernetes.list
curl -fsSL https://download.opensuse.org/repositories/isv:/cri-o:/stable:/$CRIO_VERSION/deb/Release.key |
gpg --dearmor -o /etc/apt/keyrings/cri-o-apt-keyring.gpg
echo "deb [signed-by=/etc/apt/keyrings/cri-o-apt-keyring.gpg] https://download.opensuse.org/repositories/isv:/cri-o:/stable:/$CRIO_VERSION/deb/ /" |
tee /etc/apt/sources.list.d/cri-o.list

安裝套件

sudo apt-get update
sudo apt-get install -y cri-o kubelet kubeadm kubectl crun runc

關閉 ufw Systemd Service
```
sudo systemctl disable --now ufw
```

設定 kubelet service node ip

INTERFACE=ens18
IPV4_IP=$(ip -4 a s $INTERFACE | awk '/inet / {print $2}' | cut -d'/' -f1)
sudo sed -i \
-e '/^KUBELET_EXTRA_ARGS=$/s/$/\"--node-ip='"$IPV4_IP"'\"/' \
/etc/default/kubelet

檢查是否正確修改

cat /etc/default/kubelet

執行結果：

KUBELET_EXTRA_ARGS="--node-ip=172.20.6.61"

啟動 kubelet 服務

sudo systemctl enable --now kubelet.service

安裝 chrony
```
sudo apt-get install -y chrony
```
設定 chronyd 服務開機自動啟動
```
sudo systemctl enable chrony
```

設定跟 Google 校時

sudo nano /etc/chrony/chrony.conf

修改內容如下：

server time.google.com prefer

啟用 chronyd 服務
```
sudo systemctl start chrony
```

手動確定已校時

sudo chronyc sources

執行結果如下：

MS Name/IP address Stratum Poll Reach LastRx Last sample
===============================================================================
^* time4.google.com 1 6 377 22 +271us[ +332us] +/- 3178us

SSH 連到其他節點做步驟 1 ~ 22 的設定

2. 透過 kubeadm 開始建立 HA K8s

ssh 連到第一台 Control-plane node
```
ssh sudo_user@ipaddderss
```

設定 kube-vip

export VIP="172.20.6.60"
export VIPSUBSET="16"
export INTERFACE="ens18"
KVVERSION="v1.0.1"
alias kube-vip="sudo podman run --network host --rm ghcr.io/kube-vip/kube-vip:$KVVERSION"
sudo mkdir -p /etc/kubernetes/manifests/
kube-vip manifest pod \
--interface $INTERFACE \
--address $VIP \
--vipSubnet $VIPSUBSET \
--controlplane \
--arp \
--leaderElection | sudo tee /etc/kubernetes/manifests/kube-vip-static-pod.yaml

拷貝到另外兩台 Control plane nodes

ssh sudo_user@control_plane_node_2_node_hostname 'sudo mkdir -p /etc/kubernetes/manifests/'
ssh sudo_user@control_plane_node_3_node_hostname 'sudo mkdir -p /etc/kubernetes/manifests/'
scp /etc/kubernetes/manifests/kube-vip-static-pod.yaml sudo_user@control_plane_node_2_hostname:
scp /etc/kubernetes/manifests/kube-vip-static-pod.yaml sudo_user@control_plane_node_3_node_hostname:
ssh sudo_user@control_plane_node_3_node_hostname 'sudo mv kube-vip-static-pod.yaml /etc/kubernetes/manifests/'
ssh sudo_user@control_plane_node_3_node_hostname 'sudo mv kube-vip-static-pod.yaml /etc/kubernetes/manifests/'

修改 kube-vip 的 Service Account，只需在第一台 Control-plane 需要修改

sudo sed -i 's|path: /etc/kubernetes/admin.conf|path: /etc/kubernetes/super-admin.conf|g' \
/etc/kubernetes/manifests/kube-vip-static-pod.yaml

編輯 kubeadm 初始化設定檔

mkdir -p ${HOME}/k8s/config; \
nano "$HOME"/k8s/config/kubeadm-init.yaml

檔案內容如下：

apiVersion: kubeadm.k8s.io/v1beta4
kind: InitConfiguration
localAPIEndpoint:
advertiseAddress: 172.20.6.61
bindPort: 6443
nodeRegistration:
criSocket: unix:///var/run/crio/crio.sock
imagePullPolicy: IfNotPresent
imagePullSerial: true
name: taroko-m1.kubeantony.com
taints: []
timeouts:
controlPlaneComponentHealthCheck: 4m0s
discovery: 5m0s
etcdAPICall: 2m0s
kubeletHealthCheck: 4m0s
kubernetesAPICall: 1m0s
tlsBootstrap: 5m0s
upgradeManifests: 5m0s
---
apiServer:
certSANs:
- 127.0.0.1
- api-taroko.kubeantony.com
extraVolumes:
- name: tz-config
hostPath: /etc/localtime
mountPath: /etc/localtime
readOnly: true
apiVersion: kubeadm.k8s.io/v1beta4
caCertificateValidityPeriod: 87600h0m0s
certificateValidityPeriod: 8760h0m0s
certificatesDir: /etc/kubernetes/pki
clusterName: taroko-ovn
controllerManager:
extraArgs:
- name: bind-address
value: "0.0.0.0"
- name: secure-port
value: "10257"
extraVolumes:
- name: tz-config
hostPath: /etc/localtime
mountPath: /etc/localtime
readOnly: true
#dns:
# imageRepository: harbor.example.com/library/coredns
encryptionAlgorithm: RSA-2048
etcd:
local:
dataDir: /var/lib/etcd
extraArgs:
- name: listen-metrics-urls
value: http://0.0.0.0:2381
#imageRepository: harbor.example.com/library
kind: ClusterConfiguration
kubernetesVersion: 1.35.0
networking:
dnsDomain: cluster.local
serviceSubnet: 10.96.0.0/16
podSubnet: 10.244.0.0/16
#proxy:
# disabled: true
scheduler:
extraArgs:
- name: bind-address
value: "0.0.0.0"
- name: secure-port
value: "10259"
extraVolumes:
- name: tz-config
hostPath: /etc/localtime
mountPath: /etc/localtime
readOnly: true
#controlPlaneEndpoint: 172.20.6.60:6443
controlPlaneEndpoint: api-taroko.kubeantony.com:6443
---
apiVersion: kubelet.config.k8s.io/v1beta1
authentication:
anonymous:
enabled: false
webhook:
cacheTTL: 0s
enabled: true
x509:
clientCAFile: /etc/kubernetes/pki/ca.crt
authorization:
mode: Webhook
webhook:
cacheAuthorizedTTL: 0s
cacheUnauthorizedTTL: 0s
cgroupDriver: systemd
clusterDNS:
- 10.96.0.10
clusterDomain: cluster.local
containerRuntimeEndpoint: ""
cpuManagerReconcilePeriod: 0s
crashLoopBackOff: {}
evictionPressureTransitionPeriod: 0s
fileCheckFrequency: 0s
healthzBindAddress: 127.0.0.1
healthzPort: 10248
httpCheckFrequency: 0s
imageMaximumGCAge: "168h"
imageMinimumGCAge: "2m0s"
kind: KubeletConfiguration
logging:
flushFrequency: 0
options:
json:
infoBufferSize: "0"
text:
infoBufferSize: "0"
verbosity: 0
memorySwap: {}
nodeStatusReportFrequency: 0s
nodeStatusUpdateFrequency: 0s
rotateCertificates: true
runtimeRequestTimeout: 0s
shutdownGracePeriod: 30s
shutdownGracePeriodCriticalPods: 10s
staticPodPath: /etc/kubernetes/manifests
streamingConnectionIdleTimeout: 0s
syncFrequency: 0s
volumeStatsAggPeriod: 0s
maxPods: 110
systemReserved:
memory: "1Gi"
kubeReserved:
memory: "2Gi"
---
apiVersion: kubeproxy.config.k8s.io/v1alpha1
kind: KubeProxyConfiguration
metricsBindAddress: "0.0.0.0:10249"
mode: "nftables"
nftables:
masqueradeAll: false
masqueradeBit: 14
minSyncPeriod: 1s
syncPeriod: 30s

Dry run set up the Kubernetes control plane，用以檢視是否設定檔有誤

sudo kubeadm init \
--dry-run \
--upload-certs \
--config="$HOME"/k8s/config/kubeadm-init.yaml

正確執行結果：

...
[addons] Applied essential addon: kube-proxy
Your Kubernetes control-plane has initialized successfully!
To start using your cluster, you need to run the following as a regular user:
mkdir -p $HOME/.kube
sudo cp -i /etc/kubernetes/tmp/kubeadm-init-dryrun1288532023/admin.conf $HOME/.kube/config
sudo chown $(id -u):$(id -g) $HOME/.kube/config
Alternatively, if you are the root user, you can run:
export KUBECONFIG=/etc/kubernetes/admin.conf
You should now deploy a pod network to the cluster.
Run "kubectl apply -f [podnetwork].yaml" with one of the options listed at:
https://kubernetes.io/docs/concepts/cluster-administration/addons/
You can now join any number of control-plane nodes running the following command on each as root:
kubeadm join api-taroko.kubeantony.com:6443 --token tvxdmf.8yjcy5j5wgi0tkk8 \
--discovery-token-ca-cert-hash sha256:7c7ff5930966bcb4e5ef89f4008fbc5a1578fceff088cd0dcf5b67ecb6ae4c07 \
--control-plane --certificate-key 962bae62c93cbd3f706b07014d837be78b7f120e0e75adb6f82ad942f18a092a
Please note that the certificate-key gives access to cluster sensitive data, keep it secret!
As a safeguard, uploaded-certs will be deleted in two hours; If necessary, you can use
"kubeadm init phase upload-certs --upload-certs" to reload certs afterward.
Then you can join any number of worker nodes by running the following on each as root:
kubeadm join api-taroko.kubeantony.com:6443 --token tvxdmf.8yjcy5j5wgi0tkk8 \
--discovery-token-ca-cert-hash sha256:7c7ff5930966bcb4e5ef89f4008fbc5a1578fceff088cd0dcf5b67ecb6ae4c07

Set up the Kubernetes control plane

sudo kubeadm init \
--upload-certs \
--config="$HOME"/k8s/config/kubeadm-init.yaml

正確執行結果 :

[init] Using Kubernetes version: v1.35.0
[preflight] Running pre-flight checks
[preflight] Pulling images required for setting up a Kubernetes cluster
[preflight] This might take a minute or two, depending on the speed of your internet connection
[preflight] You can also perform this action beforehand using 'kubeadm config images pull'
[certs] Using certificateDir folder "/etc/kubernetes/pki"
[certs] Generating "ca" certificate and key
[certs] Generating "apiserver" certificate and key
[certs] apiserver serving cert is signed for DNS names [api-taroko.kubeantony.com kubernetes kubernetes.default kubernetes.default.svc kubernetes.default.svc.cluster.local taroko-m1.kubeantony.com] and IPs [10.96.0.1 172.20.6.61 127.0.0.1]
[certs] Generating "apiserver-kubelet-client" certificate and key
[certs] Generating "front-proxy-ca" certificate and key
[certs] Generating "front-proxy-client" certificate and key
[certs] Generating "etcd/ca" certificate and key
[certs] Generating "etcd/server" certificate and key
[certs] etcd/server serving cert is signed for DNS names [localhost taroko-m1.kubeantony.com] and IPs [172.20.6.61 127.0.0.1 ::1]
[certs] Generating "etcd/peer" certificate and key
[certs] etcd/peer serving cert is signed for DNS names [localhost taroko-m1.kubeantony.com] and IPs [172.20.6.61 127.0.0.1 ::1]
[certs] Generating "etcd/healthcheck-client" certificate and key
[certs] Generating "apiserver-etcd-client" certificate and key
[certs] Generating "sa" key and public key
[kubeconfig] Using kubeconfig folder "/etc/kubernetes"
[kubeconfig] Writing "admin.conf" kubeconfig file
[kubeconfig] Writing "super-admin.conf" kubeconfig file
[kubeconfig] Writing "kubelet.conf" kubeconfig file
[kubeconfig] Writing "controller-manager.conf" kubeconfig file
[kubeconfig] Writing "scheduler.conf" kubeconfig file
[etcd] Creating static Pod manifest for local etcd in "/etc/kubernetes/manifests"
[control-plane] Using manifest folder "/etc/kubernetes/manifests"
[control-plane] Creating static Pod manifest for "kube-apiserver"
[control-plane] Creating static Pod manifest for "kube-controller-manager"
[control-plane] Creating static Pod manifest for "kube-scheduler"
[kubelet-start] Writing kubelet environment file with flags to file "/var/lib/kubelet/kubeadm-flags.env"
[kubelet-start] Writing kubelet configuration to file "/var/lib/kubelet/instance-config.yaml"
[patches] Applied patch of type "application/strategic-merge-patch+json" to target "kubeletconfiguration"
[kubelet-start] Writing kubelet configuration to file "/var/lib/kubelet/config.yaml"
[kubelet-start] Starting the kubelet
[wait-control-plane] Waiting for the kubelet to boot up the control plane as static Pods from directory "/etc/kubernetes/manifests"
[kubelet-check] Waiting for a healthy kubelet at http://127.0.0.1:10248/healthz. This can take up to 4m0s
[kubelet-check] The kubelet is healthy after 501.521647ms
[control-plane-check] Waiting for healthy control plane components. This can take up to 4m0s
[control-plane-check] Checking kube-apiserver at https://172.20.6.61:6443/livez
[control-plane-check] Checking kube-controller-manager at https://0.0.0.0:10257/healthz
[control-plane-check] Checking kube-scheduler at https://0.0.0.0:10259/livez
[control-plane-check] kube-controller-manager is healthy after 505.527348ms
[control-plane-check] kube-scheduler is healthy after 1.008943332s
[control-plane-check] kube-apiserver is healthy after 3.001586313s
[upload-config] Storing the configuration used in ConfigMap "kubeadm-config" in the "kube-system" Namespace
[kubelet] Creating a ConfigMap "kubelet-config" in namespace kube-system with the configuration for the kubelets in the cluster
[upload-certs] Storing the certificates in Secret "kubeadm-certs" in the "kube-system" Namespace
[upload-certs] Using certificate key:
064ae9995157a471491e92d05c1498092c59b389d99878b87ad08eb5c5a1231f
[mark-control-plane] Marking the node taroko-m1.kubeantony.com as control-plane by adding the labels: [node-role.kubernetes.io/control-plane node.kubernetes.io/exclude-from-external-load-balancers]
[bootstrap-token] Using token: 2mjfj9.wluywejrou2isf9n
[bootstrap-token] Configuring bootstrap tokens, cluster-info ConfigMap, RBAC Roles
[bootstrap-token] Configured RBAC rules to allow Node Bootstrap tokens to get nodes
[bootstrap-token] Configured RBAC rules to allow Node Bootstrap tokens to post CSRs in order for nodes to get long term certificate credentials
[bootstrap-token] Configured RBAC rules to allow the csrapprover controller automatically approve CSRs from a Node Bootstrap Token
[bootstrap-token] Configured RBAC rules to allow certificate rotation for all node client certificates in the cluster
[bootstrap-token] Creating the "cluster-info" ConfigMap in the "kube-public" namespace
[kubelet-finalize] Updating "/etc/kubernetes/kubelet.conf" to point to a rotatable kubelet client certificate and key
[addons] Applied essential addon: CoreDNS
[addons] Applied essential addon: kube-proxy
Your Kubernetes control-plane has initialized successfully!
To start using your cluster, you need to run the following as a regular user:
mkdir -p $HOME/.kube
sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
sudo chown $(id -u):$(id -g) $HOME/.kube/config
Alternatively, if you are the root user, you can run:
export KUBECONFIG=/etc/kubernetes/admin.conf
You should now deploy a pod network to the cluster.
Run "kubectl apply -f [podnetwork].yaml" with one of the options listed at:
https://kubernetes.io/docs/concepts/cluster-administration/addons/
You can now join any number of control-plane nodes running the following command on each as root:
kubeadm join api-taroko.kubeantony.com:6443 --token 2mjfj9.wluywejrou2isf9n \
--discovery-token-ca-cert-hash sha256:a7b161d19a125ccc6efc5511a81ea5dfb4563667a8d5fd922aa5f31093609094 \
--control-plane --certificate-key 064ae9995157a471491e92d05c1498092c59b389d99878b87ad08eb5c5a1231f
Please note that the certificate-key gives access to cluster sensitive data, keep it secret!
As a safeguard, uploaded-certs will be deleted in two hours; If necessary, you can use
"kubeadm init phase upload-certs --upload-certs" to reload certs afterward.
Then you can join any number of worker nodes by running the following on each as root:
kubeadm join api-taroko.kubeantony.com:6443 --token 2mjfj9.wluywejrou2isf9n \
--discovery-token-ca-cert-hash sha256:a7b161d19a125ccc6efc5511a81ea5dfb4563667a8d5fd922aa5f31093609094

設定 kubeconfig

mkdir -p $HOME/.kube
sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
sudo chown $(id -u):$(id -g) $HOME/.kube/config
printf "\nsource <(kubectl completion bash)\nalias k=kubectl\ncomplete -o default -F __start_kubectl k\n" >> ~/.bashrc
source ~/.bashrc

第一台 control plan 安裝好後再將 kube-vip 權限調整回來

sudo sed -i 's|path: /etc/kubernetes/super-admin.conf|path: /etc/kubernetes/admin.conf|g' /etc/kubernetes/manifests/kube-vip-static-pod.yaml
sudo systemctl daemon-reload
sudo systemctl restart kubelet

確認 kube-system pods 運作正常

k -n kube-system get pods

執行結果：

NAME READY STATUS RESTARTS AGE
coredns-7d764666f9-5mnc5 1/1 Running 0 58s
coredns-7d764666f9-62cqv 1/1 Running 0 58s
etcd-taroko-m1.kubeantony.com 1/1 Running 0 65s
kube-apiserver-taroko-m1.kubeantony.com 1/1 Running 0 65s
kube-controller-manager-taroko-m1.kubeantony.com 1/1 Running 0 67s
kube-proxy-xww8m 1/1 Running 0 59s
kube-scheduler-taroko-m1.kubeantony.com 1/1 Running 0 66s
kube-vip-taroko-m1.kubeantony.com 1/1 Running 0 21s

下載 kube-ovn CNI 安裝腳本

mkdir -p ${HOME}/k8s/addon/cni/kube-ovn
wget -P ${HOME}/k8s/addon/cni/kube-ovn \
https://raw.githubusercontent.com/kubeovn/kube-ovn/refs/tags/v1.15.2/dist/images/install.sh

修改設定參數

nano ${HOME}/k8s/addon/cni/kube-ovn/install.sh

檔案內容：

IFACE=ens18
POD_CIDR="10.244.0.0/16" # Do NOT overlap with NODE/SVC/JOIN CIDR
POD_GATEWAY="10.244.0.1"
SVC_CIDR="10.96.0.0/16"

執行安裝腳本

cd ${HOME}/k8s/addon/cni/kube-ovn; \
sudo KUBECONFIG="$HOME"/.kube/config bash install.sh

執行結果：

-------------------------------
Kube-OVN Version: v1.15.2
Default Network Mode: geneve
Default Subnet CIDR: 10.244.0.0/16
Join Subnet CIDR: 100.64.0.0/16
Enable SVC LB: true
Enable Networkpolicy: true
Enable EIP and SNAT: true
Enable Mirror: false
-------------------------------
[Step 1/6] Label kube-ovn-master node and label datapath type
node/taroko-m1.kubeantony.com labeled
-------------------------------
[Step 2/6] Install OVN components
Install OVN DB in 172.20.6.61
customresourcedefinition.apiextensions.k8s.io/vpc-dnses.kubeovn.io created
customresourcedefinition.apiextensions.k8s.io/switch-lb-rules.kubeovn.io created
customresourcedefinition.apiextensions.k8s.io/vpc-nat-gateways.kubeovn.io created
customresourcedefinition.apiextensions.k8s.io/vpc-egress-gateways.kubeovn.io created
customresourcedefinition.apiextensions.k8s.io/iptables-eips.kubeovn.io created
customresourcedefinition.apiextensions.k8s.io/iptables-fip-rules.kubeovn.io created
customresourcedefinition.apiextensions.k8s.io/iptables-dnat-rules.kubeovn.io created
customresourcedefinition.apiextensions.k8s.io/iptables-snat-rules.kubeovn.io created
customresourcedefinition.apiextensions.k8s.io/ovn-eips.kubeovn.io created
customresourcedefinition.apiextensions.k8s.io/ovn-fips.kubeovn.io created
customresourcedefinition.apiextensions.k8s.io/ovn-snat-rules.kubeovn.io created
customresourcedefinition.apiextensions.k8s.io/ovn-dnat-rules.kubeovn.io created
customresourcedefinition.apiextensions.k8s.io/vpcs.kubeovn.io created
customresourcedefinition.apiextensions.k8s.io/ips.kubeovn.io created
customresourcedefinition.apiextensions.k8s.io/vips.kubeovn.io created
customresourcedefinition.apiextensions.k8s.io/subnets.kubeovn.io created
customresourcedefinition.apiextensions.k8s.io/ippools.kubeovn.io created
customresourcedefinition.apiextensions.k8s.io/vlans.kubeovn.io created
customresourcedefinition.apiextensions.k8s.io/provider-networks.kubeovn.io created
customresourcedefinition.apiextensions.k8s.io/security-groups.kubeovn.io created
customresourcedefinition.apiextensions.k8s.io/qos-policies.kubeovn.io created
serviceaccount/ovn-ovs created
clusterrole.rbac.authorization.k8s.io/system:ovn-ovs created
clusterrolebinding.rbac.authorization.k8s.io/ovn-ovs created
serviceaccount/ovn created
clusterrole.rbac.authorization.k8s.io/system:ovn created
clusterrolebinding.rbac.authorization.k8s.io/ovn created
rolebinding.rbac.authorization.k8s.io/ovn created
serviceaccount/kube-ovn-cni created
clusterrole.rbac.authorization.k8s.io/system:kube-ovn-cni created
role.rbac.authorization.k8s.io/secret-reader-ovn-ipsec created
clusterrolebinding.rbac.authorization.k8s.io/kube-ovn-cni created
rolebinding.rbac.authorization.k8s.io/kube-ovn-cni created
rolebinding.rbac.authorization.k8s.io/kube-ovn-cni-secret-reader created
serviceaccount/kube-ovn-app created
clusterrole.rbac.authorization.k8s.io/system:kube-ovn-app created
clusterrolebinding.rbac.authorization.k8s.io/kube-ovn-app created
rolebinding.rbac.authorization.k8s.io/kube-ovn-app created
service/ovn-nb created
service/ovn-sb created
service/ovn-northd created
deployment.apps/ovn-central created
daemonset.apps/ovs-ovn created
Waiting for deployment "ovn-central" rollout to finish: 0 of 1 updated replicas are available...
deployment "ovn-central" successfully rolled out
Waiting for daemon set "ovs-ovn" rollout to finish: 0 of 1 updated pods are available...
daemon set "ovs-ovn" successfully rolled out
-------------------------------
[Step 3/6] Install Kube-OVN
configmap/ovn-vpc-nat-config created
configmap/ovn-vpc-nat-gw-config created
deployment.apps/kube-ovn-controller created
daemonset.apps/kube-ovn-cni created
deployment.apps/kube-ovn-monitor created
service/kube-ovn-monitor created
service/kube-ovn-controller created
service/kube-ovn-cni created
Waiting for deployment "kube-ovn-controller" rollout to finish: 0 of 1 updated replicas are available...
deployment "kube-ovn-controller" successfully rolled out
Waiting for daemon set "kube-ovn-cni" rollout to finish: 0 of 1 updated pods are available...
daemon set "kube-ovn-cni" successfully rolled out
-------------------------------
Check to delete multus pods to reload CNI config
[Step 4/6] Delete pod that not in host network mode
pod "coredns-7d764666f9-bdk5d" deleted from kube-system namespace
pod "coredns-7d764666f9-r94v9" deleted from kube-system namespace
Waiting for deployment "coredns" rollout to finish: 1 out of 2 new replicas have been updated...
Waiting for deployment "coredns" rollout to finish: 0 of 2 updated replicas are available...
Waiting for deployment "coredns" rollout to finish: 1 out of 2 new replicas have been updated...
Waiting for deployment "coredns" rollout to finish: 0 of 2 updated replicas are available...
Waiting for deployment "coredns" rollout to finish: 1 of 2 updated replicas are available...
Waiting for deployment "coredns" rollout to finish: 1 of 2 updated replicas are available...
Waiting for deployment "coredns" rollout to finish: 1 of 2 updated replicas are available...
deployment "coredns" successfully rolled out
Install Kube-ovn-pinger
service/kube-ovn-pinger created
daemonset.apps/kube-ovn-pinger created
Waiting for daemon set "kube-ovn-pinger" rollout to finish: 0 of 1 updated pods are available...
daemon set "kube-ovn-pinger" successfully rolled out
pod/kube-ovn-pinger-lgml7 condition met
-------------------------------
[Step 5/6] Add kubectl plugin PATH
[Step 6/6] Run network diagnose
Defaulted container "cni-server" out of: cni-server, hostpath-init (init), install-cni (init)
tar: Removing leading `/' from member names
NAME READY STATUS RESTARTS AGE IP NODE NOMINATED NODE READINESS GATES
coredns-7d764666f9-c66hz 1/1 Running 0 34s 10.244.0.5 taroko-m1.kubeantony.com <none> <none>
coredns-7d764666f9-nj725 1/1 Running 0 35s 10.244.0.4 taroko-m1.kubeantony.com <none> <none>
etcd-taroko-m1.kubeantony.com 1/1 Running 0 4m6s 172.20.6.61 taroko-m1.kubeantony.com <none> <none>
kube-apiserver-taroko-m1.kubeantony.com 1/1 Running 0 4m4s 172.20.6.61 taroko-m1.kubeantony.com <none> <none>
kube-controller-manager-taroko-m1.kubeantony.com 1/1 Running 0 4m4s 172.20.6.61 taroko-m1.kubeantony.com <none> <none>
kube-ovn-cni-v8nl5 1/1 Running 0 46s 172.20.6.61 taroko-m1.kubeantony.com <none> <none>
kube-ovn-controller-6bd89b7549-xj2l6 1/1 Running 0 46s 172.20.6.61 taroko-m1.kubeantony.com <none> <none>
kube-ovn-monitor-5d9bf9858c-sw8lq 1/1 Running 0 46s 172.20.6.61 taroko-m1.kubeantony.com <none> <none>
kube-ovn-pinger-lgml7 1/1 Running 0 19s 10.244.0.6 taroko-m1.kubeantony.com <none> <none>
kube-proxy-8qvlw 1/1 Running 0 3m59s 172.20.6.61 taroko-m1.kubeantony.com <none> <none>
kube-scheduler-taroko-m1.kubeantony.com 1/1 Running 0 4m4s 172.20.6.61 taroko-m1.kubeantony.com <none> <none>
kube-vip-taroko-m1.kubeantony.com 1/1 Running 0 3m22s 172.20.6.61 taroko-m1.kubeantony.com <none> <none>
ovn-central-55d8dfb46c-wqktr 1/1 Running 0 77s 172.20.6.61 taroko-m1.kubeantony.com <none> <none>
ovs-ovn-tctvd 1/1 Running 0 77s 172.20.6.61 taroko-m1.kubeantony.com <none> <none>
NAME CREATED AT
vpcs.kubeovn.io 2026-02-05T10:23:16Z
NAME CREATED AT
vpc-nat-gateways.kubeovn.io 2026-02-05T10:23:16Z
NAME CREATED AT
vpc-egress-gateways.kubeovn.io 2026-02-05T10:23:16Z
NAME CREATED AT
subnets.kubeovn.io 2026-02-05T10:23:16Z
NAME CREATED AT
ips.kubeovn.io 2026-02-05T10:23:16Z
NAME CREATED AT
vlans.kubeovn.io 2026-02-05T10:23:16Z
NAME CREATED AT
provider-networks.kubeovn.io 2026-02-05T10:23:16Z
NAME CREATED AT
security-groups.kubeovn.io 2026-02-05T10:23:16Z
NAME CREATED AT
vips.kubeovn.io 2026-02-05T10:23:16Z
NAME CREATED AT
vpc-dnses.kubeovn.io 2026-02-05T10:23:16Z
NAME CREATED AT
switch-lb-rules.kubeovn.io 2026-02-05T10:23:16Z
NAME CREATED AT
ippools.kubeovn.io 2026-02-05T10:23:16Z
NAME CREATED AT
ovn-eips.kubeovn.io 2026-02-05T10:23:16Z
NAME CREATED AT
ovn-fips.kubeovn.io 2026-02-05T10:23:16Z
NAME CREATED AT
ovn-dnat-rules.kubeovn.io 2026-02-05T10:23:16Z
NAME CREATED AT
ovn-snat-rules.kubeovn.io 2026-02-05T10:23:16Z
NAME CREATED AT
iptables-eips.kubeovn.io 2026-02-05T10:23:16Z
NAME CREATED AT
iptables-fip-rules.kubeovn.io 2026-02-05T10:23:16Z
NAME CREATED AT
iptables-snat-rules.kubeovn.io 2026-02-05T10:23:16Z
NAME CREATED AT
iptables-dnat-rules.kubeovn.io 2026-02-05T10:23:16Z
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
kube-dns ClusterIP 10.96.0.10 <none> 53/UDP,53/TCP,9153/TCP 4m5s
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
kubernetes ClusterIP 10.96.0.1 <none> 443/TCP 4m6s
NAME AGE
ovn 78s
NAME CREATED AT
system:ovn 2026-02-05T10:23:17Z
NAME ROLE AGE
ovn ClusterRole/system:ovn 78s
NAME STATUS ROLES AGE VERSION INTERNAL-IP EXTERNAL-IP OS-IMAGE KERNEL-VERSION CONTAINER-RUNTIME
taroko-m1.kubeantony.com Ready control-plane 4m8s v1.35.0 172.20.6.61 <none> Ubuntu 24.04.3 LTS 6.8.0-90-generic cri-o://1.35.0
switch 7aeda674-777a-48ca-8f85-657035f13057 (ovn-default)
port coredns-7d764666f9-nj725.kube-system
addresses: ["52:93:cd:e8:0d:18 10.244.0.4"]
port coredns-7d764666f9-c66hz.kube-system
addresses: ["3a:e4:49:26:c4:51 10.244.0.5"]
port kube-ovn-pinger-lgml7.kube-system
addresses: ["ca:41:f2:66:e8:0b 10.244.0.6"]
port ovn-default-ovn-cluster
type: router
router-port: ovn-cluster-ovn-default
switch 7736cdb4-13b5-40d8-aa59-2f7682578e08 (join)
port join-ovn-cluster
type: router
router-port: ovn-cluster-join
port node-taroko-m1.kubeantony.com
addresses: ["ca:d5:9f:ca:6e:3e 100.64.0.2"]
router 0484e79c-fb16-403a-8feb-f9e9c1ca7578 (ovn-cluster)
port ovn-cluster-join
mac: "92:a1:79:05:14:a6"
ipv6-lla: "fe80::90a1:79ff:fe05:14a6"
networks: ["100.64.0.1/16"]
port ovn-cluster-ovn-default
mac: "96:27:4d:84:37:3b"
ipv6-lla: "fe80::9427:4dff:fe84:373b"
networks: ["10.244.0.1/16"]
Routing Policies
31000 ip4.dst == 10.244.0.0/16 allow
31000 ip4.dst == 100.64.0.0/16 allow
30000 ip4.dst == 172.20.6.61 reroute 100.64.0.2
29000 ip4.src == $ovn.default.taroko.m1.kubeantony.com_ip4 reroute 100.64.0.2
IPv4 Routes
Route Table <main>:
0.0.0.0/0 100.64.0.1 dst-ip
UUID LB PROTO VIP IPs
40a8ae8f-4e37-4ce6-aba2-2ad07cf5e062 cluster-tcp-load tcp 10.96.0.10:53 10.244.0.4:53,10.244.0.5:53
tcp 10.96.0.10:9153 10.244.0.4:9153,10.244.0.5:9153
tcp 10.96.0.1:443 172.20.6.61:6443
tcp 10.96.100.143:6641 172.20.6.61:6641
tcp 10.96.146.40:6643 172.20.6.61:6643
tcp 10.96.210.107:10665 172.20.6.61:10665
tcp 10.96.220.97:8080 10.244.0.6:8080
tcp 10.96.222.234:10661 172.20.6.61:10661
tcp 10.96.247.174:10660 172.20.6.61:10660
tcp 10.96.68.175:6642 172.20.6.61:6642
b298161a-2218-4447-a410-1c86548f3ba4 cluster-udp-load udp 10.96.0.10:53 10.244.0.4:53,10.244.0.5:53
_uuid : 26e09350-9f60-4dbd-a61b-b9448f3ab531
action : drop
direction : from-lport
external_ids : {parent=ovn.sg.kubeovn_deny_all, vendor=kube-ovn}
label : 0
log : false
match : "inport == @ovn.sg.kubeovn_deny_all && ip"
meter : []
name : []
options : {}
priority : 2003
sample_est : []
sample_new : []
severity : []
tier : 2
_uuid : 193e7062-2a24-459b-a696-5806a78aab34
action : drop
direction : to-lport
external_ids : {parent=ovn.sg.kubeovn_deny_all, vendor=kube-ovn}
label : 0
log : false
match : "outport == @ovn.sg.kubeovn_deny_all && ip"
meter : []
name : []
options : {}
priority : 2003
sample_est : []
sample_new : []
severity : []
tier : 2
Chassis "d4527da6-6748-420f-9839-646dbded1df7"
hostname: taroko-m1.kubeantony.com
Encap geneve
ip: "172.20.6.61"
options: {csum="true", is_default="true"}
Port_Binding kube-ovn-pinger-lgml7.kube-system
Port_Binding node-taroko-m1.kubeantony.com
Port_Binding coredns-7d764666f9-c66hz.kube-system
Port_Binding coredns-7d764666f9-nj725.kube-system
54cf
Name: OVN_Southbound
Cluster ID: 218b (218b1cca-afbe-4670-94c0-18f16abb94e3)
Server ID: 54cf (54cf652c-99c9-431b-9bb3-d0dcdffa4bf3)
Address: tcp:[172.20.6.61]:6644
Status: cluster member
Role: leader
Term: 1
Leader: self
Vote: self
Last Election won: 64441 ms ago
Election timer: 5000
Log: [2, 84]
Entries not yet committed: 0
Entries not yet applied: 0
Connections:
Disconnections: 0
Servers:
54cf (54cf at tcp:[172.20.6.61]:6644) (self) next_index=2 match_index=83
status: ok
8f1c
Name: OVN_Northbound
Cluster ID: e5d5 (e5d5a2ef-3b2d-493b-8bff-96396e4d6461)
Server ID: 8f1c (8f1c7a0c-ef84-4d5f-b157-96c2f1ffd614)
Address: tcp:[172.20.6.61]:6643
Status: cluster member
Role: leader
Term: 1
Leader: self
Vote: self
Last Election won: 64879 ms ago
Election timer: 5000
Log: [2, 101]
Entries not yet committed: 0
Entries not yet applied: 0
Connections:
Disconnections: 12
Servers:
8f1c (8f1c at tcp:[172.20.6.61]:6643) (self) next_index=2 match_index=100
status: ok
ds kube-proxy ready
kube-proxy ready
deployment ovn-central ready
deployment kube-ovn-controller ready
ds kube-ovn-cni ready
ds ovs-ovn ready
deployment coredns ready
ovn-nb leader check ok
ovn-sb leader check ok
ovn-northd leader check ok
service/test-node-port created
### kube-ovn-controller recent log
Defaulted container "kube-ovn-controller" out of: kube-ovn-controller, hostpath-init (init)
### start to diagnose node taroko-m1.kubeantony.com
#### ovn-controller log:
Defaulted container "pinger" out of: pinger, hostpath-init (init)
2026-02-05T10:24:09.776Z|00073|binding|INFO|Claiming lport coredns-7d764666f9-c66hz.kube-system for this chassis.
2026-02-05T10:24:09.776Z|00074|binding|INFO|coredns-7d764666f9-c66hz.kube-system: Claiming 3a:e4:49:26:c4:51 10.244.0.5
2026-02-05T10:24:09.777Z|00075|binding|INFO|Setting lport coredns-7d764666f9-c66hz.kube-system ovn-installed in OVS
2026-02-05T10:24:09.784Z|00076|binding|INFO|Setting lport coredns-7d764666f9-c66hz.kube-system up in Southbound
2026-02-05T10:24:10.345Z|00077|binding|INFO|Releasing lport coredns-7d764666f9-r94v9.kube-system from this chassis (sb_readonly=0)
2026-02-05T10:24:10.345Z|00078|binding|INFO|Setting lport coredns-7d764666f9-r94v9.kube-system down in Southbound
2026-02-05T10:24:15.878Z|00079|binding|INFO|Claiming lport kube-ovn-pinger-lgml7.kube-system for this chassis.
2026-02-05T10:24:15.878Z|00080|binding|INFO|kube-ovn-pinger-lgml7.kube-system: Claiming ca:41:f2:66:e8:0b 10.244.0.6
2026-02-05T10:24:15.882Z|00081|binding|INFO|Setting lport kube-ovn-pinger-lgml7.kube-system ovn-installed in OVS
2026-02-05T10:24:15.889Z|00082|binding|INFO|Setting lport kube-ovn-pinger-lgml7.kube-system up in Southbound
#### ovs-vswitchd log:
Defaulted container "pinger" out of: pinger, hostpath-init (init)
2026-02-05T10:23:56.412Z|00041|bridge|INFO|bridge br-int: added interface ovn0 on port 2
2026-02-05T10:23:57.868Z|00042|bridge|INFO|bridge br-int: added interface 7a4d9583419a_h on port 3
2026-02-05T10:23:57.983Z|00043|bridge|INFO|bridge br-int: added interface 99fecbc31137_h on port 4
2026-02-05T10:24:00.369Z|00044|connmgr|INFO|br-int<->unix#3: 657 flow_mods in the 9 s starting 10 s ago (634 adds, 23 deletes)
2026-02-05T10:24:00.463Z|00045|bridge|INFO|bridge br-int: added interface d10dda60b2bd_h on port 5
2026-02-05T10:24:09.337Z|00046|bridge|INFO|bridge br-int: deleted interface 7a4d9583419a_h on port 3
2026-02-05T10:24:09.775Z|00047|bridge|INFO|bridge br-int: added interface fc4fb4fc28e6_h on port 6
2026-02-05T10:24:10.345Z|00048|bridge|INFO|bridge br-int: deleted interface 99fecbc31137_h on port 4
2026-02-05T10:24:15.876Z|00049|bridge|INFO|bridge br-int: added interface 8ed870f01d82_h on port 7
2026-02-05T10:24:18.249Z|00002|ofproto_dpif_xlate(handler1)|WARN|dropping packet received on port mirror0, which is reserved exclusively for mirroring on bridge br-int while processing icmp6,in_port=1,vlan_tci=0x0000,dl_src=d6:f9:e3:fe:29:40,dl_dst=33:33:00:00:00:02,ipv6_src=fe80::d4f9:e3ff:fefe:2940,ipv6_dst=ff02::2,ipv6_label=0x00000,nw_tos=0,nw_ecn=0,nw_ttl=255,nw_frag=no,icmp_type=133,icmp_code=0
#### ovs-vsctl show results:
Defaulted container "pinger" out of: pinger, hostpath-init (init)
4dcba15a-02ed-4933-860e-d52da853027b
Bridge br-int
fail_mode: secure
datapath_type: system
Port d10dda60b2bd_h
Interface d10dda60b2bd_h
Port ovn0
Interface ovn0
type: internal
Port br-int
Interface br-int
type: internal
Port mirror0
Interface mirror0
type: internal
Port fc4fb4fc28e6_h
Interface fc4fb4fc28e6_h
Port "8ed870f01d82_h"
Interface "8ed870f01d82_h"
ovs_version: "3.5.3"
#### pinger diagnose results:
Defaulted container "pinger" out of: pinger, hostpath-init (init)
I0205 18:24:40.105197 53 pinger.go:21]
-------------------------------------------------------------------------------
Kube-OVN:
Version: v1.15.2
Build: 2026-01-29_08:13:34
Commit: git-0622723
Go Version: go1.25.6
Arch: amd64
-------------------------------------------------------------------------------
I0205 18:24:40.105233 53 pinger.go:24] current capabilities: cap_net_bind_service,cap_net_raw=ep
I0205 18:24:40.153647 53 config.go:202] pinger config is &{KubeConfigFile: KubeClient:0xc000637a40 Port:8080 Interval:5 Mode:job ExitCode:0 InternalDNS:kubernetes.default ExternalDNS: NodeName:taroko-m1.kubeantony.com HostIP:172.20.6.61 PodName:kube-ovn-pinger-lgml7 PodNamespace:kube-system PodIP:10.244.0.6 PodProtocols:[IPv4] LabelSelector:app=kube-ovn-pinger ExternalAddress:1.1.1.1,2606:4700:4700::1111 NetworkMode:kube-ovn EnableMetrics:true PollTimeout:2 PollInterval:15 SystemRunDir:/var/run/openvswitch DatabaseVswitchName:Open_vSwitch DatabaseVswitchSocketRemote:unix:/var/run/openvswitch/db.sock DatabaseVswitchFileDataPath:/etc/openvswitch/conf.db DatabaseVswitchFileLogPath:/var/log/openvswitch/ovsdb-server.log DatabaseVswitchFilePidPath:/var/run/openvswitch/ovsdb-server.pid DatabaseVswitchFileSystemIDPath:/etc/openvswitch/system-id.conf ServiceVswitchdFileLogPath:/var/log/openvswitch/ovs-vswitchd.log ServiceVswitchdFilePidPath:/var/run/openvswitch/ovs-vswitchd.pid ServiceOvnControllerFileLogPath:/var/log/ovn/ovn-controller.log ServiceOvnControllerFilePidPath:/var/run/ovn/ovn-controller.pid EnableVerboseConnCheck:false TCPConnCheckPort:8100 UDPConnCheckPort:8101 TargetIPPorts:tcp-172.20.6.61-31185 LogPerm:640}
I0205 18:24:40.157925 53 ovn.go:36] ovsdb-server and ovs-vswitchd are up
I0205 18:24:40.159364 53 ovn.go:52] ovn-controller is up
I0205 18:24:40.159374 53 ovn.go:60] start to check port binding
I0205 18:24:40.161788 53 ovn.go:66] ports in ovs: coredns-7d764666f9-c66hz.kube-system, coredns-7d764666f9-nj725.kube-system, kube-ovn-pinger-lgml7.kube-system, node-taroko-m1.kubeantony.com
I0205 18:24:40.165161 53 ovn.go:73] ports in sb: coredns-7d764666f9-c66hz.kube-system, coredns-7d764666f9-nj725.kube-system, kube-ovn-pinger-lgml7.kube-system, node-taroko-m1.kubeantony.com
I0205 18:24:40.165170 53 ovn.go:84] ovs and ovn-sb port binding check passed
I0205 18:24:40.165173 53 ping.go:383] start to check apiserver connectivity
I0205 18:24:40.165690 53 ping.go:394] connect to apiserver success in 0.51ms
I0205 18:24:40.165698 53 ping.go:174] start to check pod connectivity
I0205 18:24:40.489218 53 ping.go:220] ping pod: kube-ovn-pinger-lgml7 10.244.0.6, count: 3, loss count 0, average rtt 0.11ms
I0205 18:24:40.489239 53 ping.go:106] start to check node connectivity
I0205 18:24:40.752376 53 ping.go:151] ping node: taroko-m1.kubeantony.com 172.20.6.61, count: 3, loss count 0, average rtt 0.09ms
I0205 18:24:40.752395 53 ping.go:339] start to check dns connectivity
I0205 18:24:40.753552 53 ping.go:356] resolve dns kubernetes.default to [10.96.0.1] in 1.15ms
I0205 18:24:40.753563 53 ping.go:291] start to check Service or externalIPPort connectivity
I0205 18:24:40.753575 53 ping.go:298] checking targetIPPort tcp-172.20.6.61-31185
I0205 18:24:40.754269 53 ping.go:321] TCP connectivity to targetIPPort 172.20.6.61:31185 success
I0205 18:24:40.754281 53 ping.go:255] start to check ping external to 1.1.1.1
I0205 18:24:41.025593 53 ping.go:271] ping external address: 1.1.1.1, total count: 3, loss count 0, average rtt 3.43ms
### finish diagnose node taroko-m1.kubeantony.com
kubectl delete svc -l app=conn-check -n kube-system
service "test-node-port" deleted from kube-system namespace
-------------------------------
,,,,
,::,
,,::,,,,
,,,,,::::::::::::,,,,,
,,,::::::::::::::::::::::,,,
,,::::::::::::::::::::::::::::,,
,,::::::::::::::::::::::::::::::::,,
,::::::::::::::::::::::::::::::::::::,
,:::::::::::::,, ,,:::::,,,::::::::::,
,,:::::::::::::, ,::, ,:::::::::,
,:::::::::::::, :x, ,:: :, ,:::::::::,
,:::::::::::::::, ,,, ,::, ,, ,::::::::::,
,:::::::::::::::::,,,,,,:::::,,,,::::::::::::, ,:, ,:, ,xx, ,:::::, ,:, ,:: :::, ,x
,::::::::::::::::::::::::::::::::::::::::::::, :x: ,:xx: , :xx, :xxxxxxxxx, :xx, ,xx:,xxxx, :x
,::::::::::::::::::::::::::::::::::::::::::::, :xxxxx:, ,xx, :x: :xxx:x::, ::xxxx: :xx:, ,:xxx :xx, ,xx: ,xxxxx:, :x
,::::::::::::::::::::::::::::::::::::::::::::, :xxxxx, :xx, :x: :xxx,,:xx,:xx:,:xx, ,,,,,,,,,xxx, ,xx: :xx:xx: ,xxx,:xx::x
,::::::,,::::::::,,::::::::,,:::::::,,,::::::, :x:,xxx: ,xx, :xx :xx: ,xx,xxxxxx:, ,xxxxxxx:,xxx:, ,xxx, :xxx: ,xxx, :xxxx
,::::, ,::::, ,:::::, ,,::::, ,::::, :x: ,:xx,,:xx::xxxx,,xxx::xx: :xx::::x: ,,,,,, ,xxxxxxxxx, ,xx: ,xxx, :xxx
,::::, ,::::, ,::::, ,::::, ,::::, ,:, ,:, ,,::,,:, ,::::,, ,:::::, ,,:::::, ,, :x: ,::
,::::, ,::::, ,::::, ,::::, ,::::,
,,,,, ,::::, ,::::, ,::::, ,:::, ,,,,,,,,,,,,,
,::::, ,::::, ,::::, ,:::, ,,,:::::::::::::::,
,::::, ,::::, ,::::, ,::::, ,,,,:::::::::,,,,,,,:::,
,::::, ,::::, ,::::, ,::::::::::::,,,,,
,,,, ,::::, ,,,, ,,,::::,,,,
,::::,
,,::,
Thanks for choosing Kube-OVN!
For more advanced features, please read https://kubeovn.github.io/docs/stable/en/
If you have any question, please file an issue https://github.com/kubeovn/kube-ovn/issues/new/choose

確認 kube-ovn 安裝成功

k -n kube-system get pods

執行結果：

NAME READY STATUS RESTARTS AGE
coredns-7d764666f9-c66hz 1/1 Running 0 2m47s
coredns-7d764666f9-nj725 1/1 Running 0 2m48s
etcd-taroko-m1.kubeantony.com 1/1 Running 0 6m19s
kube-apiserver-taroko-m1.kubeantony.com 1/1 Running 0 6m17s
kube-controller-manager-taroko-m1.kubeantony.com 1/1 Running 0 6m17s
kube-ovn-cni-v8nl5 1/1 Running 0 2m59s
kube-ovn-controller-6bd89b7549-xj2l6 1/1 Running 0 2m59s
kube-ovn-monitor-5d9bf9858c-sw8lq 1/1 Running 0 2m59s
kube-ovn-pinger-lgml7 1/1 Running 0 2m32s
kube-proxy-8qvlw 1/1 Running 0 6m12s
kube-scheduler-taroko-m1.kubeantony.com 1/1 Running 0 6m17s
kube-vip-taroko-m1.kubeantony.com 1/1 Running 0 5m35s
ovn-central-55d8dfb46c-wqktr 1/1 Running 0 3m30s
ovs-ovn-tctvd 1/1 Running 0 3m30s

新增其他 Control-plane 節點進 K8s 叢集

獲得 Control-plane node Kubeadm Join Command

kubeadm_init_config_file="${HOME}/k8s/config/kubeadm-init.yaml"
certificate_key=$(sudo kubeadm init phase upload-certs --upload-certs --config ${kubeadm_init_config_file} | tail -n 1)
join_cmd=$(sudo kubeadm token create --print-join-command)
join_cp_cmd="sudo $join_cmd --control-plane --certificate-key $certificate_key"
echo $join_cp_cmd

執行結果：

sudo kubeadm join api-taroko.kubeantony.com:6443 --token j1d0fh.3se96b07m4h4gst6 --discovery-token-ca-cert-hash sha256:8f41e3f883eed0f27055c5146da5c0de5a739ef2d4282417d2ea2bdc8c0ccaf6 --control-plane --certificate-key 1e2dd91966c34bbc34602c07415bc30cf58348e96275b72f475b6c0001986e47

以可以執行 sudo 的 user 透過 ssh 連線至其他 Control-plane node
```
ssh sudo_user@ipaddderss
```

將 Control-plane 2 節點加入 K8s 叢集

sudo kubeadm join api-taroko.kubeantony.com:6443 --token j1d0fh.3se96b07m4h4gst6 --discovery-token-ca-cert-hash sha256:8f41e3f883eed0f27055c5146da5c0de5a739ef2d4282417d2ea2bdc8c0ccaf6 --control-plane --certificate-key 1e2dd91966c34bbc34602c07415bc30cf58348e96275b72f475b6c0001986e47

ssh 連到第三台 control plane node
```
ssh sudo_user@ipaddderss
```

將 Control-plane 3 節點加入 K8s 叢集

sudo kubeadm join api-taroko.kubeantony.com:6443 --token j1d0fh.3se96b07m4h4gst6 --discovery-token-ca-cert-hash sha256:8f41e3f883eed0f27055c5146da5c0de5a739ef2d4282417d2ea2bdc8c0ccaf6 --control-plane --certificate-key 1e2dd91966c34bbc34602c07415bc30cf58348e96275b72f475b6c0001986e47

新增 Worker 節點進 K8s 叢集

在第一台 Controlplane 將 join worker node 指令 print 出來

sudo kubeadm token create --print-join-command

執行結果：

kubeadm join api-taroko.kubeantony.com:6443 --token q2djge.km9ms68fttqidlj7 --discovery-token-ca-cert-hash sha256:8f41e3f883eed0f27055c5146da5c0de5a739ef2d4282417d2ea2bdc8c0ccaf6

以可以執行 sudo 的 user 透過 ssh 連線至 worker node 1
```
ssh sudo_user@ipaddderss
```

將 worker node 1 加入 K8s 叢集

sudo kubeadm join api-taroko.kubeantony.com:6443 --token q2djge.km9ms68fttqidlj7 --discovery-token-ca-cert-hash sha256:8f41e3f883eed0f27055c5146da5c0de5a739ef2d4282417d2ea2bdc8c0ccaf6

以可以執行 sudo 的 user 透過 ssh 連線至 worker node 2
```
ssh sudo_user@ipaddderss
```

將 worker node 2 加入 K8s 叢集

sudo kubeadm join api-taroko.kubeantony.com:6443 --token q2djge.km9ms68fttqidlj7 --discovery-token-ca-cert-hash sha256:8f41e3f883eed0f27055c5146da5c0de5a739ef2d4282417d2ea2bdc8c0ccaf6

以可以執行 sudo 的 user 透過 ssh 連線至 worker node 3
```
ssh sudo_user@ipaddderss
```

將 worker node 3 加入 K8s 叢集

sudo kubeadm join api-taroko.kubeantony.com:6443 --token q2djge.km9ms68fttqidlj7 --discovery-token-ca-cert-hash sha256:8f41e3f883eed0f27055c5146da5c0de5a739ef2d4282417d2ea2bdc8c0ccaf6

回到第一台 Control-plane 執行以下命令，將所有 worker nodes 都貼 label

kubectl label node taroko-w1.kubeantony.com node-role.kubernetes.io/worker=
kubectl label node taroko-w2.kubeantony.com node-role.kubernetes.io/worker=
kubectl label node taroko-w3.kubeantony.com node-role.kubernetes.io/worker=

檢視 K8s 狀態是否正常

檢視 K8s node 狀態

kubectl get nodes

執行結果：

NAME STATUS ROLES AGE VERSION
taroko-m1.kubeantony.com Ready control-plane 20m v1.35.0
taroko-m2.kubeantony.com Ready control-plane 7m35s v1.35.0
taroko-m3.kubeantony.com Ready control-plane 7m1s v1.35.0
taroko-w1.kubeantony.com Ready worker 105s v1.35.0
taroko-w2.kubeantony.com Ready worker 99s v1.35.0
taroko-w3.kubeantony.com Ready worker 94s v1.35.0

檢視 kube-system namespace 底下所有 pods 狀態

kubectl -n kube-system get pods

執行結果：

NAME READY STATUS RESTARTS AGE
coredns-7d764666f9-c66hz 1/1 Running 0 18m
coredns-7d764666f9-nj725 1/1 Running 0 18m
etcd-taroko-m1.kubeantony.com 1/1 Running 0 21m
etcd-taroko-m2.kubeantony.com 1/1 Running 0 8m13s
etcd-taroko-m3.kubeantony.com 1/1 Running 0 7m40s
kube-apiserver-taroko-m1.kubeantony.com 1/1 Running 0 21m
kube-apiserver-taroko-m2.kubeantony.com 1/1 Running 0 8m13s
kube-apiserver-taroko-m3.kubeantony.com 1/1 Running 0 7m40s
kube-controller-manager-taroko-m1.kubeantony.com 1/1 Running 0 21m
kube-controller-manager-taroko-m2.kubeantony.com 1/1 Running 0 8m13s
kube-controller-manager-taroko-m3.kubeantony.com 1/1 Running 0 7m40s
kube-ovn-cni-qrx5m 1/1 Running 0 2m13s
kube-ovn-cni-r2bjz 1/1 Running 0 7m40s
kube-ovn-cni-v8nl5 1/1 Running 0 18m
kube-ovn-cni-wcqdd 1/1 Running 0 2m18s
kube-ovn-cni-xfgqv 1/1 Running 0 2m24s
kube-ovn-cni-zkwxj 1/1 Running 0 8m14s
kube-ovn-controller-6bd89b7549-xj2l6 1/1 Running 0 18m
kube-ovn-monitor-5d9bf9858c-sw8lq 1/1 Running 0 18m
kube-ovn-pinger-dtm8w 1/1 Running 0 112s
kube-ovn-pinger-h5sqd 1/1 Running 0 104s
kube-ovn-pinger-lbd48 1/1 Running 0 113s
kube-ovn-pinger-lgml7 1/1 Running 0 17m
kube-proxy-5kf45 1/1 Running 0 7m40s
kube-proxy-8qvlw 1/1 Running 0 21m
kube-proxy-c2vbq 1/1 Running 0 2m13s
kube-proxy-ct7jn 1/1 Running 0 8m14s
kube-proxy-nfb9w 1/1 Running 0 2m18s
kube-proxy-xnkwj 1/1 Running 0 2m24s
kube-scheduler-taroko-m1.kubeantony.com 1/1 Running 0 21m
kube-scheduler-taroko-m2.kubeantony.com 1/1 Running 0 8m13s
kube-scheduler-taroko-m3.kubeantony.com 1/1 Running 0 7m40s
kube-vip-taroko-m1.kubeantony.com 1/1 Running 0 20m
kube-vip-taroko-m2.kubeantony.com 1/1 Running 0 8m13s
kube-vip-taroko-m3.kubeantony.com 1/1 Running 0 7m40s
ovn-central-55d8dfb46c-wqktr 1/1 Running 0 18m
ovs-ovn-8rg8h 1/1 Running 0 2m18s
ovs-ovn-b2zmj 1/1 Running 0 2m24s
ovs-ovn-ch9jw 1/1 Running 0 7m40s
ovs-ovn-ft9m8 1/1 Running 0 2m13s
ovs-ovn-nq67b 1/1 Running 0 8m14s
ovs-ovn-tctvd 1/1 Running 0 18m

檢測 K8s 網路延遲和吞吐量

安裝 cilium 指令

CILIUM_CLI_VERSION=$(curl -s https://raw.githubusercontent.com/cilium/cilium-cli/main/stable.txt)
CLI_ARCH=amd64
if [ "$(uname -m)" = "aarch64" ]; then CLI_ARCH=arm64; fi
curl -L --fail --remote-name-all https://github.com/cilium/cilium-cli/releases/download/${CILIUM_CLI_VERSION}/cilium-linux-${CLI_ARCH}.tar.gz{,.sha256sum}
sha256sum --check cilium-linux-${CLI_ARCH}.tar.gz.sha256sum
sudo tar xzvfC cilium-linux-${CLI_ARCH}.tar.gz /usr/local/bin
rm cilium-linux-${CLI_ARCH}.tar.gz{,.sha256sum}

透過 cilium 指令檢測 K8s 網路頻寬

cilium connectivity perf \
--crr \
--host-to-pod \
--pod-to-host \
--node-selector-client kubernetes.io/hostname=taroko-w1.kubeantony.com \
--node-selector-server kubernetes.io/hostname=taroko-w2.kubeantony.com

執行結果：

🔥 [taroko-ovn] Deleting connectivity check deployments...
✨ [taroko-ovn] Creating namespace cilium-test-1 for connectivity check...
ℹ️ Nodes used for performance testing:
ℹ️ * Node name: taroko-w2.kubeantony.com, zone:
ℹ️ * Node name: taroko-w1.kubeantony.com, zone:
✨ [taroko-ovn] Deploying perf-client deployment...
✨ [taroko-ovn] Deploying perf-client-other-node deployment...
✨ [taroko-ovn] Deploying perf-server deployment...
✨ [taroko-ovn] Deploying perf-client-host-net deployment...
✨ [taroko-ovn] Deploying perf-client-other-node-host-net deployment...
✨ [taroko-ovn] Deploying perf-server-host-net deployment...
⌛ [taroko-ovn] Waiting for deployment cilium-test-1/perf-client to become ready...
⌛ [taroko-ovn] Waiting for deployment cilium-test-1/perf-client-other-node to become ready...
⌛ [taroko-ovn] Waiting for deployment cilium-test-1/perf-server to become ready...
⌛ [taroko-ovn] Waiting for deployment cilium-test-1/perf-client-host-net to become ready...
⌛ [taroko-ovn] Waiting for deployment cilium-test-1/perf-client-other-node-host-net to become ready...
⌛ [taroko-ovn] Waiting for deployment cilium-test-1/perf-server-host-net to become ready...
ℹ️ Cilium version: 0.0.0
🏃[cilium-test-1] Running 1 tests ...
[=] [cilium-test-1] Test [network-perf] [1/1]
................................
🔥 Network Performance Test Summary [cilium-test-1]:
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
📋 Scenario | Node | Test | Duration | Min | Mean | Max | P50 | P90 | P99 | Transaction rate OP/s
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
📋 pod-to-pod | same-node | TCP_CRR | 10s | 60µs | 85.91µs | 677µs | 82µs | 98µs | 125µs | 11615.84
📋 pod-to-pod | same-node | TCP_RR | 10s | 14µs | 29.22µs | 695µs | 28µs | 33µs | 48µs | 34070.14
📋 pod-to-host | same-node | TCP_CRR | 10s | 74µs | 88.54µs | 179µs | 86µs | 96µs | 120µs | 474.50
📋 pod-to-host | same-node | TCP_RR | 10s | 18µs | 29.87µs | 1.801ms | 29µs | 33µs | 49µs | 33340.49
📋 host-to-pod | same-node | TCP_CRR | 10s | 82µs | 96.1µs | 189µs | 92µs | 113µs | 137µs | 11.60
📋 host-to-pod | same-node | TCP_RR | 10s | 16µs | 29.97µs | 716µs | 29µs | 33µs | 48µs | 33217.61
📋 host-to-host | same-node | TCP_CRR | 10s | 59µs | 76.15µs | 683µs | 73µs | 84µs | 118µs | 13101.67
📋 host-to-host | same-node | TCP_RR | 10s | 15µs | 28.35µs | 700µs | 28µs | 31µs | 46µs | 35113.98
📋 pod-to-pod | other-node | TCP_CRR | 10s | 242µs | 293.67µs | 1.817ms | 290µs | 323µs | 381µs | 2641.99
📋 pod-to-pod | other-node | TCP_RR | 10s | 96µs | 121.1µs | 1.509ms | 118µs | 137µs | 167µs | 8245.27
📋 pod-to-host | other-node | TCP_CRR | 10s | 246µs | 1.07221ms | 3.071576s | 293µs | 329µs | 400µs | 926.89
📋 pod-to-host | other-node | TCP_RR | 10s | 93µs | 135.28µs | 1.03699s | 118µs | 137µs | 169µs | 7382.95
📋 host-to-pod | other-node | TCP_CRR | 10s | 246µs | 299.94µs | 2.051ms | 296µs | 325µs | 386µs | 3331.08
📋 host-to-pod | other-node | TCP_RR | 10s | 98µs | 121.49µs | 1.927ms | 118µs | 137µs | 168µs | 8218.90
📋 host-to-host | other-node | TCP_CRR | 10s | 190µs | 230.35µs | 1.95ms | 227µs | 255µs | 305µs | 4336.79
📋 host-to-host | other-node | TCP_RR | 10s | 85µs | 107.45µs | 3.69ms | 106µs | 120µs | 148µs | 9292.06
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
----------------------------------------------------------------------------------------
📋 Scenario | Node | Test | Duration | Throughput Mb/s
----------------------------------------------------------------------------------------
📋 pod-to-pod | same-node | TCP_STREAM | 10s | 11263.46
📋 pod-to-pod | same-node | TCP_STREAM_MULTI | 10s | 41560.29
📋 pod-to-host | same-node | TCP_STREAM | 10s | 10561.07
📋 pod-to-host | same-node | TCP_STREAM_MULTI | 10s | 40874.81
📋 host-to-pod | same-node | TCP_STREAM | 10s | 11463.51
📋 host-to-pod | same-node | TCP_STREAM_MULTI | 10s | 42231.56
📋 host-to-host | same-node | TCP_STREAM | 10s | 26166.77
📋 host-to-host | same-node | TCP_STREAM_MULTI | 10s | 96386.74
📋 pod-to-pod | other-node | TCP_STREAM | 10s | 2823.65
📋 pod-to-pod | other-node | TCP_STREAM_MULTI | 10s | 4573.82
📋 pod-to-host | other-node | TCP_STREAM | 10s | 2886.42
📋 pod-to-host | other-node | TCP_STREAM_MULTI | 10s | 4405.81
📋 host-to-pod | other-node | TCP_STREAM | 10s | 2828.99
📋 host-to-pod | other-node | TCP_STREAM_MULTI | 10s | 5137.81
📋 host-to-host | other-node | TCP_STREAM | 10s | 9404.16
📋 host-to-host | other-node | TCP_STREAM_MULTI | 10s | 9407.35
----------------------------------------------------------------------------------------
✅ [cilium-test-1] All 1 tests (32 actions) successful, 0 tests skipped, 0 scenarios skipped.

Podman build Multi-Arch Images

Wed, 28 Jan 2026 06:36:54 +0800

撰寫 go 範例程式

nano hello.go

檔案內容如下：

package main
import (
"fmt"
"net/http"
)
func handler(w http.ResponseWriter, r *http.Request) {
fmt.Fprintf(w, "Hello")
}
func main() {
http.HandleFunc("/", handler)
http.ListenAndServe(":8080", nil)
}

編輯 Dockerfile

nano Dockerfile

檔案內容如下：

FROM --platform=$BUILDPLATFORM docker.io/library/golang:1.22 AS builder
ARG TARGETOS
ARG TARGETARCH
WORKDIR /app
COPY . .
# 利用 Go 的環境變數進行交叉編譯
RUN GOOS=$TARGETOS GOARCH=$TARGETARCH go build -o /build/hello hello.go
# 最後階段
FROM scratch
COPY --from=builder /build/hello /usr/local/bin/hello
CMD ["/usr/local/bin/hello"]

初始化 image manifest

podman manifest create hello

執行結果：

413534f46ca55438f717d734a4e088af1a92b003c6c837cf5753b6808161b125

build image

podman build --platform linux/amd64,linux/arm64 --manifest localhost/hello .

執行結果：

[linux/arm64] [1/2] STEP 1/6: FROM docker.io/library/golang:1.22 AS builder
[linux/arm64] [1/2] STEP 2/6: ARG TARGETOS
--> 6af98f118a47
[linux/arm64] [1/2] STEP 3/6: ARG TARGETARCH
--> de656f2a8f6b
[linux/arm64] [1/2] STEP 4/6: WORKDIR /app
--> 2e367870d334
[linux/arm64] [1/2] STEP 5/6: COPY . .
--> 6ad772c2ca91
[linux/arm64] [1/2] STEP 6/6: RUN GOOS=$TARGETOS GOARCH=$TARGETARCH go build -o /build/hello hello.go
--> 30515c7aaf86
[linux/arm64] [2/2] STEP 1/3: FROM scratch
[linux/arm64] [2/2] STEP 2/3: COPY --from=builder /build/hello /usr/local/bin/hello
--> 4ac0f5942408
[linux/arm64] [2/2] STEP 3/3: CMD ["/usr/local/bin/hello"]
[linux/arm64] [2/2] COMMIT
--> 6251d8b5a1f3
[linux/amd64] [1/2] STEP 1/6: FROM docker.io/library/golang:1.22 AS builder
6251d8b5a1f392aed47bc124a0bd3f2b7c18f3d4ba9681ea153e853bf5d23370
[linux/amd64] [1/2] STEP 2/6: ARG TARGETOS
--> Using cache 6af98f118a47e4fbbcaff838816b73e31d7f5bd72e4b546baf82b026fe424662
--> 6af98f118a47
[linux/amd64] [1/2] STEP 3/6: ARG TARGETARCH
--> Using cache de656f2a8f6bc7fc0e3f97eaaff21df053837e3d0e1a97f659a8a0ca40e2bb4a
--> de656f2a8f6b
[linux/amd64] [1/2] STEP 4/6: WORKDIR /app
--> Using cache 2e367870d3341f7f57dbf1a1924281e277a645ecb29f031a979ea6f656ef2c07
--> 2e367870d334
[linux/amd64] [1/2] STEP 5/6: COPY . .
--> Using cache 6ad772c2ca9135caef7c1fbeb79c126b36638dccab3b8eac884642020f330b4a
--> 6ad772c2ca91
[linux/amd64] [1/2] STEP 6/6: RUN GOOS=$TARGETOS GOARCH=$TARGETARCH go build -o /build/hello hello.go
--> afbe26b87b3c
[linux/amd64] [2/2] STEP 1/3: FROM scratch
[linux/amd64] [2/2] STEP 2/3: COPY --from=builder /build/hello /usr/local/bin/hello
--> 6dcdcf58bf83
[linux/amd64] [2/2] STEP 3/3: CMD ["/usr/local/bin/hello"]
[linux/amd64] [2/2] COMMIT
--> b6c0da75b480
b6c0da75b480acb9283ba0978937fe3668490c17bd39739a02211b1079227752

檢視 image

podman images localhost/hello:latest

執行結果：

REPOSITORY TAG IMAGE ID CREATED SIZE
<none> <none> b6c0da75b480 20 minutes ago 7.07 MB
localhost/hello latest 413534f46ca5 25 minutes ago 1.04 kB

檢視 image manifest

podman manifest inspect localhost/hello:latest

執行結果：

{
"schemaVersion": 2,
"mediaType": "application/vnd.docker.distribution.manifest.list.v2+json",
"manifests": [
{
"mediaType": "application/vnd.oci.image.manifest.v1+json",
"size": 498,
"digest": "sha256:48c8c68bc197b35831750d260600d3eb6c127ac64463d8f26d4f369e801ec4dd",
"platform": {
"architecture": "arm64",
"os": "linux"
}
},
{
"mediaType": "application/vnd.oci.image.manifest.v1+json",
"size": 498,
"digest": "sha256:27a5911345bd07fc3461092bb0b7c5fb52fed1e35f4dd27eaf0cf833e2c19860",
"platform": {
"architecture": "amd64",
"os": "linux"
}
}
]
}

Push the manifest and included images

podman manifest push localhost/hello:latest docker://quay.io/myuser/image:latest

Step by step install HA Kubernetes with Kubeadm in Disconnected environment

Fri, 23 Jan 2026 12:22:46 +0800

0. Preface

本篇文章會介紹，如何在全離線的環境下，在多台 VM 上使用 kubeadm 安裝 3 台 Control-plane Node 和 3 台 Worker Node 架構的 Kubernetes Cluster

0.1. 環境架構規劃

1. 準備 K8s 全離線安裝包

1.1. 準備 K8s 軟體套件

連線到一台 Disk 空間 70G 或以上, 可以透過網路正常連線到公有網路的 RHEL 9 電腦

註冊 RHEL 9

sudo rhc connect --activation-key $ACTIVATION-KEY --organization $ORGANIZATION

設定 Kubernetes 和 CRI-O 版本

KUBERNETES_VERSION=v1.34
CRIO_VERSION=v1.34

添加 Kubernetes yum repository

cat <<EOF | sudo tee /etc/yum.repos.d/kubernetes.repo
[kubernetes]
name=Kubernetes
baseurl=https://pkgs.k8s.io/core:/stable:/$KUBERNETES_VERSION/rpm/
enabled=1
gpgcheck=1
gpgkey=https://pkgs.k8s.io/core:/stable:/$KUBERNETES_VERSION/rpm/repodata/repomd.xml.key
EOF

添加 CRI-O yum repository

cat <<EOF | sudo tee /etc/yum.repos.d/cri-o.repo
[cri-o]
name=CRI-O
baseurl=https://download.opensuse.org/repositories/isv:/cri-o:/stable:/$CRIO_VERSION/rpm/
enabled=1
gpgcheck=1
gpgkey=https://download.opensuse.org/repositories/isv:/cri-o:/stable:/$CRIO_VERSION/rpm/repodata/repomd.xml.key
EOF

建立工作目錄

mkdir -p "$HOME"/k8s/{addon/{cni/cilium,csi/nfs-provisioner,ingress/ingress-nginx,metrics/metrics-server,logging/{fluentd,logging-operator},kube-vip/{ha-control-plane,k8s-lb-service}},img,pkg/{kubernetes,podman,skopeo},config}

目錄結構如下

tree "$HOME"/k8s

執行結果：

/home/bigred/k8s
├── addon
│   ├── cni
│   │   └── cilium
│   ├── csi
│   │   └── nfs-provisioner
│   ├── ingress
│   │   └── ingress-nginx
│   ├── kube-vip
│   │   ├── ha-control-plane
│   │   └── k8s-lb-service
│   ├── logging
│   │   ├── fluentd
│   │   └── logging-operator
│   └── metrics
│   └── metrics-server
├── config
├── img
└── pkg
├── kubernetes
├── podman
└── skopeo
21 directories, 0 files

將必要套件載入指定目錄

sudo yum install --downloadonly --downloaddir="$HOME"/k8s/pkg/kubernetes -y \
crun \
runc \
cri-o \
kubeadm \
kubectl \
kubelet

檢視已載入的套件

ls -lh "$HOME"/k8s/pkg/kubernetes

執行結果：

total 78M
-rw-r--r--. 1 root root 240K Oct 16 16:28 conntrack-tools-1.4.7-4.el9_5.x86_64.rpm
-rw-r--r--. 1 root root 66K Oct 16 16:28 container-selinux-2.235.0-1.el9_6.noarch.rpm
-rw-r--r--. 1 root root 21M Oct 16 16:28 cri-o-1.34.1-150500.1.1.x86_64.rpm
-rw-r--r--. 1 root root 7.3M Oct 16 16:28 cri-tools-1.34.0-150500.1.1.x86_64.rpm
-rw-r--r--. 1 root root 563K Oct 16 16:28 criu-3.19-1.el9.x86_64.rpm
-rw-r--r--. 1 root root 33K Oct 16 16:28 criu-libs-3.19-1.el9.x86_64.rpm
-rw-r--r--. 1 root root 244K Oct 16 16:28 crun-1.23.1-2.el9_6.x86_64.rpm
-rw-r--r--. 1 root root 13M Oct 16 16:28 kubeadm-1.34.1-150500.1.1.x86_64.rpm
-rw-r--r--. 1 root root 12M Oct 16 16:28 kubectl-1.34.1-150500.1.1.x86_64.rpm
-rw-r--r--. 1 root root 13M Oct 16 16:28 kubelet-1.34.1-150500.1.1.x86_64.rpm
-rw-r--r--. 1 root root 8.6M Oct 16 16:28 kubernetes-cni-1.7.1-150500.1.1.x86_64.rpm
-rw-r--r--. 1 root root 60K Oct 16 16:28 libnet-1.2-7.el9.x86_64.rpm
-rw-r--r--. 1 root root 26K Oct 16 16:28 libnetfilter_cthelper-1.0.0-22.el9.x86_64.rpm
-rw-r--r--. 1 root root 26K Oct 16 16:28 libnetfilter_cttimeout-1.0.0-19.el9.x86_64.rpm
-rw-r--r--. 1 root root 31K Oct 16 16:28 libnetfilter_queue-1.0.5-1.el9.x86_64.rpm
-rw-r--r--. 1 root root 38K Oct 16 16:28 protobuf-c-1.3.3-13.el9.x86_64.rpm
-rw-r--r--. 1 root root 3.6M Oct 16 16:28 runc-1.2.4-2.el9.x86_64.rpm
-rw-r--r--. 1 root root 42K Oct 16 16:28 yajl-2.1.0-25.el9.x86_64.rpm

下載並準備 podman pkg

sudo yum install --downloadonly --downloaddir="$HOME"/k8s/pkg/podman -y \
podman

檢視已載入的套件

ls -l "$HOME"/k8s/pkg/podman

執行結果：

total 24048
-rw-r--r--. 1 bigred bigred 902510 Oct 16 16:59 aardvark-dns-1.14.0-1.el9.x86_64.rpm
-rw-r--r--. 1 bigred bigred 55519 Oct 16 16:59 conmon-2.1.12-1.el9.x86_64.rpm
-rw-r--r--. 1 bigred bigred 158417 Oct 16 16:59 containers-common-1-117.el9_6.x86_64.rpm
-rw-r--r--. 1 bigred bigred 67105 Oct 16 16:59 container-selinux-2.235.0-1.el9_6.noarch.rpm
-rw-r--r--. 1 bigred bigred 576009 Oct 16 16:59 criu-3.19-1.el9.x86_64.rpm
-rw-r--r--. 1 bigred bigred 33643 Oct 16 16:59 criu-libs-3.19-1.el9.x86_64.rpm
-rw-r--r--. 1 bigred bigred 249255 Oct 16 16:59 crun-1.23.1-2.el9_6.x86_64.rpm
-rw-r--r--. 1 bigred bigred 58706 Oct 16 16:59 fuse3-3.10.2-9.el9.x86_64.rpm
-rw-r--r--. 1 bigred bigred 95573 Oct 16 16:59 fuse3-libs-3.10.2-9.el9.x86_64.rpm
-rw-r--r--. 1 bigred bigred 8750 Oct 16 16:59 fuse-common-3.10.2-9.el9.x86_64.rpm
-rw-r--r--. 1 bigred bigred 71022 Oct 16 16:59 fuse-overlayfs-1.14-1.el9.x86_64.rpm
-rw-r--r--. 1 bigred bigred 61278 Oct 16 16:59 libnet-1.2-7.el9.x86_64.rpm
-rw-r--r--. 1 bigred bigred 71992 Oct 16 16:59 libslirp-4.4.0-8.el9.x86_64.rpm
-rw-r--r--. 1 bigred bigred 3846970 Oct 16 16:59 netavark-1.14.1-1.el9_6.x86_64.rpm
-rw-r--r--. 1 bigred bigred 268131 Oct 16 16:59 'passt-0^20250217.ga1e48a0-10.el9_6.x86_64.rpm'
-rw-r--r--. 1 bigred bigred 27658 Oct 16 16:59 'passt-selinux-0^20250217.ga1e48a0-10.el9_6.noarch.rpm'
-rw-r--r--. 1 bigred bigred 17803252 Oct 16 16:59 podman-5.4.0-13.el9_6.x86_64.rpm
-rw-r--r--. 1 bigred bigred 38224 Oct 16 16:59 protobuf-c-1.3.3-13.el9.x86_64.rpm
-rw-r--r--. 1 bigred bigred 90389 Oct 16 16:59 shadow-utils-subid-4.9-12.el9.x86_64.rpm
-rw-r--r--. 1 bigred bigred 50387 Oct 16 16:59 slirp4netns-1.3.2-1.el9.x86_64.rpm
-rw-r--r--. 1 bigred bigred 42487 Oct 16 16:59 yajl-2.1.0-25.el9.x86_64.rpm

下載並準備 skopeo pkg

sudo yum install --downloadonly --downloaddir="$HOME"/k8s/pkg/skopeo -y \
skopeo

檢視已載入的套件

ls -l "$HOME"/k8s/pkg/skopeo

執行結果：

total 9308
-rw-r--r--. 1 root root 9530108 Oct 17 10:19 skopeo-1.18.1-2.el9_6.x86_64.rpm

1.2. 準備 kubeadm 要安裝 K8s 所需的 images

列出安裝 kubeadm 要安裝 K8s 所需的 images

kubeadm config images list | tee ${HOME}/k8s/img/img-list.txt

執行結果：

registry.k8s.io/kube-apiserver:v1.34.1
registry.k8s.io/kube-controller-manager:v1.34.1
registry.k8s.io/kube-scheduler:v1.34.1
registry.k8s.io/kube-proxy:v1.34.1
registry.k8s.io/coredns/coredns:v1.12.1
registry.k8s.io/pause:3.10.1
registry.k8s.io/etcd:3.6.4-0

將 K8s images 備份到指定目錄中

for i in $(cat ${HOME}/k8s/img/img-list.txt); do podman pull ${i}; done
podman save -m $(cat ${HOME}/k8s/img/img-list.txt) > ${HOME}/k8s/img/all-K8s-Components-v1.34.1.tar

拷貝 K8s 所有 components 的 images 到 Harbor 的 library project 中

for i in $(cat ${HOME}/k8s/img/img-list.txt); do skopeo copy docker://${i} docker://${i/registry.k8s.io/${HARBOR_FQDN}/library}; done

1.2.3. 準備 ingress-nginx `v1.13.3` 所需之 images 和安裝 yaml

找到 ingress-nginx v1.13.3 所需之 images

INGRESS_NGINX_VERSION="v1.13.3"
curl -s https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-${INGRESS_NGINX_VERSION}/deploy/static/provider/cloud/deploy.yaml | grep image: | sort -u | tr -s " " | cut -d " " -f 3 | tee -a ${HOME}/k8s/img/img-list.txt

執行結果：

registry.k8s.io/ingress-nginx/controller:v1.13.3@sha256:1b044f6dcac3afbb59e05d98463f1dec6f3d3fb99940bc12ca5d80270358e3bd
registry.k8s.io/ingress-nginx/kube-webhook-certgen:v1.6.3@sha256:3d671cf20a35cd94efc5dcd484970779eb21e7938c98fbc3673693b8a117cf39

將 Ingress-nginx Controller image 備份到指定目錄

for i in $(grep ingress-nginx ${HOME}/k8s/img/img-list.txt); do podman pull ${i}; podman tag ${i} ${i%@*};done
podman save -m $(grep ingress-nginx ${HOME}/k8s/img/img-list.txt | cut -d "@" -f 1) > ${HOME}/k8s/img/ingress-nginx-controller-v1.13.3.tar

將安裝 yaml 下載至指定目錄

curl -so ${HOME}/k8s/addon/ingress/ingress-nginx/deploy.yaml https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-${INGRESS_NGINX_VERSION}/deploy/static/provider/cloud/deploy.yaml

1.3. 準備 kube-vip `v1.0.1` 所需之 images

設定環境資訊

export VIP="172.20.6.110"
export VIPSUBSET="16"
export INTERFACE="ens18"
KVVERSION="v1.0.1"
alias kube-vip="sudo podman run --network host --rm ghcr.io/kube-vip/kube-vip:$KVVERSION"

產生 kube-vip static pod yaml

kube-vip manifest pod \
--interface $INTERFACE \
--address $VIP \
--vipSubnet $VIPSUBSET \
--controlplane \
--arp \
--leaderElection | tee ${HOME}/k8s/addon/kube-vip/ha-control-plane/kube-vip-static-pod.yaml

上述參數沒有 --service 是因為 control-plane 的 static pod 不需要管理 loadbalancer type service

產生 kube-vip daemonset yaml

kube-vip manifest daemonset \
--interface $INTERFACE \
--vipSubnet $VIPSUBSET \
--services \
--arp \
--leaderElection \
--servicesElection | tee ${HOME}/k8s/addon/kube-vip/k8s-lb-service/kube-vip-ds.yaml

下載 kube-vip Cloud Provider yaml 檔

curl -so ${HOME}/k8s/addon/kube-vip/k8s-lb-service/kube-vip-cloud-controller.yaml https://raw.githubusercontent.com/kube-vip/kube-vip-cloud-provider/main/manifest/kube-vip-cloud-controller.yaml

下載 kube-vip daemonset 所需之 rbac.yaml

curl -so ${HOME}/k8s/addon/kube-vip/k8s-lb-service/kube-vip-rbac.yaml https://kube-vip.io/manifests/rbac.yaml

檢視 Kubevip 執行所需之 images

find ${HOME}/k8s/addon/kube-vip -name "*.yaml" -type f -exec cat {} \; | grep image: | tr -s " " | uniq | cut -d " " -f 3 | tee -a ${HOME}/k8s/img/img-list.txt

執行結果：

ghcr.io/kube-vip/kube-vip:v1.0.1
ghcr.io/kube-vip/kube-vip-cloud-provider:v0.0.12

將 kube-vip images 備份到指定目錄

for i in $(tail -n 2 ${HOME}/k8s/img/img-list.txt); do podman pull ${i}; done
podman save -m $(tail -n 2 ${HOME}/k8s/img/img-list.txt) > ${HOME}/k8s/img/kube-vip-v1.0.1.tar

1.4. 準備 Metrics Server `v0.8.0` 所需之 images

定義 Metrics Server 版本變數
```
METRICS_SERVER_VERSION="v0.8.0"
```

下載安裝 yaml 到指定路徑

curl -sLo ${HOME}/k8s/addon/metrics/metrics-server/components.yaml https://github.com/kubernetes-sigs/metrics-server/releases/download/${METRICS_SERVER_VERSION}/components.yaml

檢視 Metrics Server 執行所需之 images

find ${HOME}/k8s/addon/metrics/metrics-server -name "*.yaml" -type f -exec cat {} \; | grep image: | tr -s " " | uniq | cut -d " " -f 3 | tee -a ${HOME}/k8s/img/img-list.txt

執行結果：

registry.k8s.io/metrics-server/metrics-server:v0.8.0

將 Metrics Server image 備份到指定目錄

for i in $(grep metrics-server ${HOME}/k8s/img/img-list.txt); do podman pull ${i}; done
podman save -m $(grep metrics-server ${HOME}/k8s/img/img-list.txt) > ${HOME}/k8s/img/metrics-server-${METRICS_SERVER_VERSION}.tar

1.5. 準備 Fluentd `v1.19.0` 所需之 images

定義 Fluentd 版本變數
```
FLUENTED_VERSION="v1.19.0-1.1"
```

下載安裝 yaml 到指定路徑

curl -sLo ${HOME}/k8s/addon/logging/fluentd/fluentd-daemonset-syslog.yaml https://raw.githubusercontent.com/fluent/fluentd-kubernetes-daemonset/refs/tags/${FLUENTED_VERSION}/fluentd-daemonset-syslog.yaml

修改 yaml

sed -i "s|version: v1|version: ${FLUENTED_VERSION}|g" fluentd-daemonset-syslog.yaml
sed -i "s|v1-debian-syslog|v1.19.0-debian-syslog-amd64-1.1|g" fluentd-daemonset-syslog.yaml
sed -i 's|fluent/fluentd-kubernetes-daemonset|docker.io/fluent/fluentd-kubernetes-daemonset|g' fluentd-daemonset-syslog.yaml

檢視 fluentd 執行所需之 images

find ${HOME}/k8s/addon/logging/fluentd -name "*.yaml" -type f -exec cat {} \; | grep image: | tr -s " " | uniq | cut -d " " -f 3 | tee -a ${HOME}/k8s/img/img-list.txt

執行結果：

docker.io/fluent/fluentd-kubernetes-daemonset:v1.19.0-debian-syslog-amd64-1.1

將 fluentd image 備份到指定目錄

for i in $(grep fluentd ${HOME}/k8s/img/img-list.txt); do podman pull ${i}; done
podman save -m $(grep fluentd ${HOME}/k8s/img/img-list.txt) > ${HOME}/k8s/img/fluentd-kubernetes-daemonset-v1.19.0-debian-syslog-amd64-1.1.tar

1.6. 準備 cilium `1.18.2` 所需之 images

定義 helm 和 cilium 版本變數

HELM_VERSION="v3.19.0"
CILIUM_VERSION="1.18.2"

下載 helm Binary

curl -sLo ${HOME}/k8s/addon/cni/cilium/helm-${HELM_VERSION}-linux-amd64.tar.gz https://get.helm.sh/helm-${HELM_VERSION}-linux-amd64.tar.gz

添加 Cilium Helm repository

helm repo add cilium https://helm.cilium.io/

下載 cilium chart file

helm fetch cilium/cilium --version=${CILIUM_VERSION} -d ${HOME}/k8s/addon/cni/cilium/

設定 helm values yaml

echo 'bpf:
masquerade: true
hubble:
relay:
enabled: true
ui:
enabled: true
service:
type: NodePort
ipam:
mode: kubernetes
ipv4NativeRoutingCIDR: 10.244.0.0/16
k8sServiceHost: 172.20.6.10
k8sServicePort: 6443
kubeProxyReplacement: true' > ${HOME}/k8s/addon/cni/cilium/custom-values.yaml

檢視 cilium 執行所需之 images

helm template ${HOME}/k8s/addon/cni/cilium/cilium-${CILIUM_VERSION}.tgz -f ${HOME}/k8s/addon/cni/cilium/custom-values.yaml | awk '$1 ~ /image:/ {print $2}' | sed -e 's/\"//g' | sort -u | tee -a ${HOME}/k8s/img/img-list.txt

執行結果：

quay.io/cilium/cilium-envoy:v1.34.7-1757592137-1a52bb680a956879722f48c591a2ca90f7791324@sha256:7932d656b63f6f866b6732099d33355184322123cfe1182e6f05175a3bc2e0e0
quay.io/cilium/cilium:v1.18.2@sha256:858f807ea4e20e85e3ea3240a762e1f4b29f1cb5bbd0463b8aa77e7b097c0667
quay.io/cilium/hubble-relay:v1.18.2@sha256:6079308ee15e44dff476fb522612732f7c5c4407a1017bc3470916242b0405ac
quay.io/cilium/hubble-ui-backend:v0.13.3@sha256:db1454e45dc39ca41fbf7cad31eec95d99e5b9949c39daaad0fa81ef29d56953
quay.io/cilium/hubble-ui:v0.13.3@sha256:661d5de7050182d495c6497ff0b007a7a1e379648e60830dd68c4d78ae21761d
quay.io/cilium/operator-generic:v1.18.2@sha256:cb4e4ffc5789fd5ff6a534e3b1460623df61cba00f5ea1c7b40153b5efb81805

將 cilium images 備份到指定目錄

for i in $(grep "quay.io/cilium" ${HOME}/k8s/img/img-list.txt); do podman pull ${i}; podman tag ${i} ${i%@*}; done
podman save -m $(grep "quay.io/cilium" ${HOME}/k8s/img/img-list.txt | cut -d "@" -f 1) > ${HOME}/k8s/img/cilium-${CILIUM_VERSION}.tar

下載 Cilium CLI

CILIUM_CLI_VERSION=$(curl -s https://raw.githubusercontent.com/cilium/cilium-cli/main/stable.txt)
CLI_ARCH=amd64
if [ "$(uname -m)" = "aarch64" ]; then CLI_ARCH=arm64; fi
curl -L --fail --remote-name-all https://github.com/cilium/cilium-cli/releases/download/${CILIUM_CLI_VERSION}/cilium-linux-${CLI_ARCH}.tar.gz{,.sha256sum}
sha256sum --check cilium-linux-${CLI_ARCH}.tar.gz.sha256sum

下載 Hubble Client

HUBBLE_VERSION="$(curl -s https://raw.githubusercontent.com/cilium/hubble/master/stable.txt)"
HUBBLE_ARCH=amd64
if [ "$(uname -m)" = "aarch64" ]; then HUBBLE_ARCH=arm64; fi
curl -L --fail --remote-name-all https://github.com/cilium/hubble/releases/download/$HUBBLE_VERSION/hubble-linux-${HUBBLE_ARCH}.tar.gz{,.sha256sum}
sha256sum --check hubble-linux-${HUBBLE_ARCH}.tar.gz.sha256sum

準備 cilium 測試網路效能 image

sudo tar xzvfC cilium-linux-${CLI_ARCH}.tar.gz /usr/local/bin
cilium connectivity perf --print-image-artifacts | tee -a ${HOME}/k8s/img/img-list.txt

執行結果：

quay.io/cilium/network-perf:1751527436-c2462ae@sha256:0c491ed7ca63e6c526593b3a2d478f856410a50fbbce7fe2b64283c3015d752f

將 cilium 測試網路效能 images 備份到指定目錄

for i in $(grep "network-perf" ${HOME}/k8s/img/img-list.txt); do podman pull ${i}; podman tag ${i} ${i%@*}; done
podman save $(grep "network-perf" ${HOME}/k8s/img/img-list.txt | cut -d "@" -f 1) > ${HOME}/k8s/img/cilium-network-perf.tar

1.7. 準備 NFS subdir external provisioner `v4.0.2` 所需之 images

定義 NFS provisioner 版本變數
```
NFS_PROVISIONER_VERSION="v4.0.2"
```

下載安裝 yaml 到指定路徑

git clone --no-checkout --depth=1 --filter=tree:0 https://github.com/kubernetes-sigs/nfs-subdir-external-provisioner.git ${HOME}/k8s/addon/csi/nfs-provisioner/nfs-subdir-external-provisioner
cd ${HOME}/k8s/addon/csi/nfs-provisioner/nfs-subdir-external-provisioner
git sparse-checkout set --no-cone /deploy
git checkout
mv ${HOME}/k8s/addon/csi/nfs-provisioner/nfs-subdir-external-provisioner/deploy/ ${HOME}/k8s/addon/csi/nfs-provisioner/
sudo rm -r ${HOME}/k8s/addon/csi/nfs-provisioner/nfs-subdir-external-provisioner
sed -i "s|busybox:stable|docker.io/library/busybox:stable|g" ${HOME}/k8s/addon/csi/nfs-provisioner/deploy/test-pod.yaml

建立 kustomization.yaml

echo 'namespace: nfs-provisioner
bases:
- ./deploy
resources:
- namespace.yaml
patchesStrategicMerge:
- patch_nfs_details.yaml' > ${HOME}/k8s/addon/csi/nfs-provisioner/kustomization.yaml

建立 namespace.yaml

echo '# namespace.yaml
apiVersion: v1
kind: Namespace
metadata:
name: nfs-provisioner' > ${HOME}/k8s/addon/csi/nfs-provisioner/namespace.yaml

建立 patch_nfs_details.yaml

echo 'apiVersion: apps/v1
kind: Deployment
metadata:
labels:
app: nfs-client-provisioner
name: nfs-client-provisioner
spec:
template:
spec:
containers:
- name: nfs-client-provisioner
env:
- name: NFS_SERVER
value: 172.20.6.9
- name: NFS_PATH
value: /k8s
volumes:
- name: nfs-client-root
nfs:
server: 172.20.6.9
path: /k8s' > ${HOME}/k8s/addon/csi/nfs-provisioner/patch_nfs_details.yaml

檢視 nfs-provisioner 執行所需之 images

find ${HOME}/k8s/addon/csi/nfs-provisioner -name "*.yaml" -type f -exec cat {} \; | grep image: | tr -s " " | uniq | cut -d " " -f 3 | tee -a ${HOME}/k8s/img/img-list.txt

執行結果：

registry.k8s.io/sig-storage/nfs-subdir-external-provisioner:v4.0.2
docker.io/library/busybox:stable

將 nfs-provisioner images 備份到指定目錄

for i in $(grep -E "nfs-subdir-external-provisioner|busybox" ${HOME}/k8s/img/img-list.txt); do podman pull ${i}; done
podman save -m $(grep -E "nfs-subdir-external-provisioner|busybox" ${HOME}/k8s/img/img-list.txt) > ${HOME}/k8s/img/nfs-provisioner-${NFS_PROVISIONER_VERSION}.tar

1.8. 準備 Ingress NGINX `v1.13.3` 所需之 images 和 yaml 檔

定義 Ingress NGINX 版本變數
```
INGRESS_NGINX="v1.13.3"
```

下載部署 Ingress NGINX YAML

curl -sLo ${HOME}/k8s/addon/ingress/ingress-nginx/deployment.yaml \
https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-${INGRESS_NGINX}/deploy/static/provider/baremetal/deploy.yaml

將 deployment 轉成 daemonset

nano daemonSet.yaml

apiVersion: v1
kind: Namespace
metadata:
labels:
app.kubernetes.io/instance: ingress-nginx
app.kubernetes.io/name: ingress-nginx
name: ingress-nginx
---
apiVersion: v1
automountServiceAccountToken: true
kind: ServiceAccount
metadata:
labels:
app.kubernetes.io/component: controller
app.kubernetes.io/instance: ingress-nginx
app.kubernetes.io/name: ingress-nginx
app.kubernetes.io/part-of: ingress-nginx
app.kubernetes.io/version: 1.13.3
name: ingress-nginx
namespace: ingress-nginx
---
apiVersion: v1
automountServiceAccountToken: true
kind: ServiceAccount
metadata:
labels:
app.kubernetes.io/component: admission-webhook
app.kubernetes.io/instance: ingress-nginx
app.kubernetes.io/name: ingress-nginx
app.kubernetes.io/part-of: ingress-nginx
app.kubernetes.io/version: 1.13.3
name: ingress-nginx-admission
namespace: ingress-nginx
---
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
labels:
app.kubernetes.io/component: controller
app.kubernetes.io/instance: ingress-nginx
app.kubernetes.io/name: ingress-nginx
app.kubernetes.io/part-of: ingress-nginx
app.kubernetes.io/version: 1.13.3
name: ingress-nginx
namespace: ingress-nginx
rules:
- apiGroups:
- ""
resources:
- namespaces
verbs:
- get
- apiGroups:
- ""
resources:
- configmaps
- pods
- secrets
- endpoints
verbs:
- get
- list
- watch
- apiGroups:
- ""
resources:
- services
verbs:
- get
- list
- watch
- apiGroups:
- networking.k8s.io
resources:
- ingresses
verbs:
- get
- list
- watch
- apiGroups:
- networking.k8s.io
resources:
- ingresses/status
verbs:
- update
- apiGroups:
- networking.k8s.io
resources:
- ingressclasses
verbs:
- get
- list
- watch
- apiGroups:
- coordination.k8s.io
resourceNames:
- ingress-nginx-leader
resources:
- leases
verbs:
- get
- update
- apiGroups:
- coordination.k8s.io
resources:
- leases
verbs:
- create
- apiGroups:
- ""
resources:
- events
verbs:
- create
- patch
- apiGroups:
- discovery.k8s.io
resources:
- endpointslices
verbs:
- list
- watch
- get
---
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
labels:
app.kubernetes.io/component: admission-webhook
app.kubernetes.io/instance: ingress-nginx
app.kubernetes.io/name: ingress-nginx
app.kubernetes.io/part-of: ingress-nginx
app.kubernetes.io/version: 1.13.3
name: ingress-nginx-admission
namespace: ingress-nginx
rules:
- apiGroups:
- ""
resources:
- secrets
verbs:
- get
- create
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
labels:
app.kubernetes.io/instance: ingress-nginx
app.kubernetes.io/name: ingress-nginx
app.kubernetes.io/part-of: ingress-nginx
app.kubernetes.io/version: 1.13.3
name: ingress-nginx
rules:
- apiGroups:
- ""
resources:
- configmaps
- endpoints
- nodes
- pods
- secrets
- namespaces
verbs:
- list
- watch
- apiGroups:
- coordination.k8s.io
resources:
- leases
verbs:
- list
- watch
- apiGroups:
- ""
resources:
- nodes
verbs:
- get
- apiGroups:
- ""
resources:
- services
verbs:
- get
- list
- watch
- apiGroups:
- networking.k8s.io
resources:
- ingresses
verbs:
- get
- list
- watch
- apiGroups:
- ""
resources:
- events
verbs:
- create
- patch
- apiGroups:
- networking.k8s.io
resources:
- ingresses/status
verbs:
- update
- apiGroups:
- networking.k8s.io
resources:
- ingressclasses
verbs:
- get
- list
- watch
- apiGroups:
- discovery.k8s.io
resources:
- endpointslices
verbs:
- list
- watch
- get
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
labels:
app.kubernetes.io/component: admission-webhook
app.kubernetes.io/instance: ingress-nginx
app.kubernetes.io/name: ingress-nginx
app.kubernetes.io/part-of: ingress-nginx
app.kubernetes.io/version: 1.13.3
name: ingress-nginx-admission
rules:
- apiGroups:
- admissionregistration.k8s.io
resources:
- validatingwebhookconfigurations
verbs:
- get
- update
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
labels:
app.kubernetes.io/component: controller
app.kubernetes.io/instance: ingress-nginx
app.kubernetes.io/name: ingress-nginx
app.kubernetes.io/part-of: ingress-nginx
app.kubernetes.io/version: 1.13.3
name: ingress-nginx
namespace: ingress-nginx
roleRef:
apiGroup: rbac.authorization.k8s.io
kind: Role
name: ingress-nginx
subjects:
- kind: ServiceAccount
name: ingress-nginx
namespace: ingress-nginx
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
labels:
app.kubernetes.io/component: admission-webhook
app.kubernetes.io/instance: ingress-nginx
app.kubernetes.io/name: ingress-nginx
app.kubernetes.io/part-of: ingress-nginx
app.kubernetes.io/version: 1.13.3
name: ingress-nginx-admission
namespace: ingress-nginx
roleRef:
apiGroup: rbac.authorization.k8s.io
kind: Role
name: ingress-nginx-admission
subjects:
- kind: ServiceAccount
name: ingress-nginx-admission
namespace: ingress-nginx
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
labels:
app.kubernetes.io/instance: ingress-nginx
app.kubernetes.io/name: ingress-nginx
app.kubernetes.io/part-of: ingress-nginx
app.kubernetes.io/version: 1.13.3
name: ingress-nginx
roleRef:
apiGroup: rbac.authorization.k8s.io
kind: ClusterRole
name: ingress-nginx
subjects:
- kind: ServiceAccount
name: ingress-nginx
namespace: ingress-nginx
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
labels:
app.kubernetes.io/component: admission-webhook
app.kubernetes.io/instance: ingress-nginx
app.kubernetes.io/name: ingress-nginx
app.kubernetes.io/part-of: ingress-nginx
app.kubernetes.io/version: 1.13.3
name: ingress-nginx-admission
roleRef:
apiGroup: rbac.authorization.k8s.io
kind: ClusterRole
name: ingress-nginx-admission
subjects:
- kind: ServiceAccount
name: ingress-nginx-admission
namespace: ingress-nginx
---
apiVersion: v1
data: null
kind: ConfigMap
metadata:
labels:
app.kubernetes.io/component: controller
app.kubernetes.io/instance: ingress-nginx
app.kubernetes.io/name: ingress-nginx
app.kubernetes.io/part-of: ingress-nginx
app.kubernetes.io/version: 1.13.3
name: ingress-nginx-controller
namespace: ingress-nginx
---
apiVersion: v1
kind: Service
metadata:
labels:
app.kubernetes.io/component: controller
app.kubernetes.io/instance: ingress-nginx
app.kubernetes.io/name: ingress-nginx
app.kubernetes.io/part-of: ingress-nginx
app.kubernetes.io/version: 1.13.3
name: ingress-nginx-controller
namespace: ingress-nginx
spec:
externalTrafficPolicy: Local
ipFamilies:
- IPv4
ipFamilyPolicy: SingleStack
ports:
- appProtocol: http
name: http
port: 80
protocol: TCP
targetPort: http
- appProtocol: https
name: https
port: 443
protocol: TCP
targetPort: https
selector:
app.kubernetes.io/component: controller
app.kubernetes.io/instance: ingress-nginx
app.kubernetes.io/name: ingress-nginx
type: LoadBalancer
---
apiVersion: v1
kind: Service
metadata:
labels:
app.kubernetes.io/component: controller
app.kubernetes.io/instance: ingress-nginx
app.kubernetes.io/name: ingress-nginx
app.kubernetes.io/part-of: ingress-nginx
app.kubernetes.io/version: 1.13.3
name: ingress-nginx-controller-admission
namespace: ingress-nginx
spec:
ports:
- appProtocol: https
name: https-webhook
port: 443
targetPort: webhook
selector:
app.kubernetes.io/component: controller
app.kubernetes.io/instance: ingress-nginx
app.kubernetes.io/name: ingress-nginx
type: ClusterIP
---
apiVersion: apps/v1
kind: DaemonSet
metadata:
labels:
app.kubernetes.io/component: controller
app.kubernetes.io/instance: ingress-nginx
app.kubernetes.io/name: ingress-nginx
app.kubernetes.io/part-of: ingress-nginx
app.kubernetes.io/version: 1.13.3
name: ingress-nginx-controller
namespace: ingress-nginx
spec:
selector:
matchLabels:
app.kubernetes.io/component: controller
app.kubernetes.io/instance: ingress-nginx
app.kubernetes.io/name: ingress-nginx
template:
metadata:
labels:
app.kubernetes.io/component: controller
app.kubernetes.io/instance: ingress-nginx
app.kubernetes.io/name: ingress-nginx
app.kubernetes.io/part-of: ingress-nginx
app.kubernetes.io/version: 1.13.3
spec:
automountServiceAccountToken: true
containers:
- args:
- /nginx-ingress-controller
- --election-id=ingress-nginx-leader
- --controller-class=k8s.io/ingress-nginx
- --ingress-class=nginx
- --configmap=$(POD_NAMESPACE)/ingress-nginx-controller
- --validating-webhook=:8443
- --validating-webhook-certificate=/usr/local/certificates/cert
- --validating-webhook-key=/usr/local/certificates/key
- --enable-metrics=false
- --report-node-internal-ip-address=true
- --watch-ingress-without-class=true
env:
- name: POD_NAME
valueFrom:
fieldRef:
fieldPath: metadata.name
- name: POD_NAMESPACE
valueFrom:
fieldRef:
fieldPath: metadata.namespace
- name: LD_PRELOAD
value: /usr/local/lib/libmimalloc.so
image: registry.k8s.io/ingress-nginx/controller:v1.13.3@sha256:1b044f6dcac3afbb59e05d98463f1dec6f3d3fb99940bc12ca5d80270358e3bd
imagePullPolicy: IfNotPresent
lifecycle:
preStop:
exec:
command:
- /wait-shutdown
livenessProbe:
failureThreshold: 5
httpGet:
path: /healthz
port: 10254
scheme: HTTP
initialDelaySeconds: 10
periodSeconds: 10
successThreshold: 1
timeoutSeconds: 1
name: controller
ports:
- containerPort: 80
name: http
protocol: TCP
hostPort: 80
- containerPort: 443
name: https
protocol: TCP
hostPort: 443
- containerPort: 8443
name: webhook
protocol: TCP
readinessProbe:
failureThreshold: 3
httpGet:
path: /healthz
port: 10254
scheme: HTTP
initialDelaySeconds: 10
periodSeconds: 10
successThreshold: 1
timeoutSeconds: 1
resources:
requests:
cpu: 100m
memory: 90Mi
securityContext:
allowPrivilegeEscalation: false
capabilities:
add:
- NET_BIND_SERVICE
drop:
- ALL
readOnlyRootFilesystem: false
runAsGroup: 82
runAsNonRoot: true
runAsUser: 101
seccompProfile:
type: RuntimeDefault
volumeMounts:
- mountPath: /usr/local/certificates/
name: webhook-cert
readOnly: true
dnsPolicy: ClusterFirst
nodeSelector:
kubernetes.io/os: linux
serviceAccountName: ingress-nginx
terminationGracePeriodSeconds: 300
volumes:
- name: webhook-cert
secret:
secretName: ingress-nginx-admission
---
apiVersion: batch/v1
kind: Job
metadata:
labels:
app.kubernetes.io/component: admission-webhook
app.kubernetes.io/instance: ingress-nginx
app.kubernetes.io/name: ingress-nginx
app.kubernetes.io/part-of: ingress-nginx
app.kubernetes.io/version: 1.13.3
name: ingress-nginx-admission-create
namespace: ingress-nginx
spec:
template:
metadata:
labels:
app.kubernetes.io/component: admission-webhook
app.kubernetes.io/instance: ingress-nginx
app.kubernetes.io/name: ingress-nginx
app.kubernetes.io/part-of: ingress-nginx
app.kubernetes.io/version: 1.13.3
name: ingress-nginx-admission-create
spec:
automountServiceAccountToken: true
containers:
- args:
- create
- --host=ingress-nginx-controller-admission,ingress-nginx-controller-admission.$(POD_NAMESPACE).svc
- --namespace=$(POD_NAMESPACE)
- --secret-name=ingress-nginx-admission
env:
- name: POD_NAMESPACE
valueFrom:
fieldRef:
fieldPath: metadata.namespace
image: registry.k8s.io/ingress-nginx/kube-webhook-certgen:v1.6.3@sha256:3d671cf20a35cd94efc5dcd484970779eb21e7938c98fbc3673693b8a117cf39
imagePullPolicy: IfNotPresent
name: create
securityContext:
allowPrivilegeEscalation: false
capabilities:
drop:
- ALL
readOnlyRootFilesystem: true
runAsGroup: 65532
runAsNonRoot: true
runAsUser: 65532
seccompProfile:
type: RuntimeDefault
nodeSelector:
kubernetes.io/os: linux
restartPolicy: OnFailure
serviceAccountName: ingress-nginx-admission
ttlSecondsAfterFinished: 0
---
apiVersion: batch/v1
kind: Job
metadata:
labels:
app.kubernetes.io/component: admission-webhook
app.kubernetes.io/instance: ingress-nginx
app.kubernetes.io/name: ingress-nginx
app.kubernetes.io/part-of: ingress-nginx
app.kubernetes.io/version: 1.13.3
name: ingress-nginx-admission-patch
namespace: ingress-nginx
spec:
template:
metadata:
labels:
app.kubernetes.io/component: admission-webhook
app.kubernetes.io/instance: ingress-nginx
app.kubernetes.io/name: ingress-nginx
app.kubernetes.io/part-of: ingress-nginx
app.kubernetes.io/version: 1.13.3
name: ingress-nginx-admission-patch
spec:
automountServiceAccountToken: true
containers:
- args:
- patch
- --webhook-name=ingress-nginx-admission
- --namespace=$(POD_NAMESPACE)
- --patch-mutating=false
- --secret-name=ingress-nginx-admission
- --patch-failure-policy=Fail
env:
- name: POD_NAMESPACE
valueFrom:
fieldRef:
fieldPath: metadata.namespace
image: registry.k8s.io/ingress-nginx/kube-webhook-certgen:v1.6.3@sha256:3d671cf20a35cd94efc5dcd484970779eb21e7938c98fbc3673693b8a117cf39
imagePullPolicy: IfNotPresent
name: patch
securityContext:
allowPrivilegeEscalation: false
capabilities:
drop:
- ALL
readOnlyRootFilesystem: true
runAsGroup: 65532
runAsNonRoot: true
runAsUser: 65532
seccompProfile:
type: RuntimeDefault
nodeSelector:
kubernetes.io/os: linux
restartPolicy: OnFailure
serviceAccountName: ingress-nginx-admission
ttlSecondsAfterFinished: 0
---
apiVersion: networking.k8s.io/v1
kind: IngressClass
metadata:
labels:
app.kubernetes.io/component: controller
app.kubernetes.io/instance: ingress-nginx
app.kubernetes.io/name: ingress-nginx
app.kubernetes.io/part-of: ingress-nginx
app.kubernetes.io/version: 1.13.3
name: nginx
spec:
controller: k8s.io/ingress-nginx
---
apiVersion: admissionregistration.k8s.io/v1
kind: ValidatingWebhookConfiguration
metadata:
labels:
app.kubernetes.io/component: admission-webhook
app.kubernetes.io/instance: ingress-nginx
app.kubernetes.io/name: ingress-nginx
app.kubernetes.io/part-of: ingress-nginx
app.kubernetes.io/version: 1.13.3
name: ingress-nginx-admission
webhooks:
- admissionReviewVersions:
- v1
clientConfig:
service:
name: ingress-nginx-controller-admission
namespace: ingress-nginx
path: /networking/v1/ingresses
port: 443
failurePolicy: Fail
matchPolicy: Equivalent
name: validate.nginx.ingress.kubernetes.io
rules:
- apiGroups:
- networking.k8s.io
apiVersions:
- v1
operations:
- CREATE
- UPDATE
resources:
- ingresses
sideEffects: None

檢視 ingress nginx 執行所需之 images

find ${HOME}/k8s/addon/ingress/ingress-nginx \
-name "daemonSet.yaml" \
-type f \
-exec grep image: {} + | \
tr -s " " | \
cut -d " " -f 3 | \
sort -u | \
uniq | \
tee -a ${HOME}/k8s/img/img-list.txt

執行結果：

registry.k8s.io/ingress-nginx/controller:v1.13.3@sha256:1b044f6dcac3afbb59e05d98463f1dec6f3d3fb99940bc12ca5d80270358e3bd
registry.k8s.io/ingress-nginx/kube-webhook-certgen:v1.6.3@sha256:3d671cf20a35cd94efc5dcd484970779eb21e7938c98fbc3673693b8a117cf39

將 ingress nginx images 備份到指定目錄

for i in $(grep "ingress-nginx" ${HOME}/k8s/img/img-list.txt); do podman pull ${i}; podman tag ${i} ${i%@*}; done
podman save -m $(grep "ingress-nginx" ${HOME}/k8s/img/img-list.txt | cut -d "@" -f 1) > ${HOME}/k8s/img/ingress-nginx-controller-${INGRESS_NGINX}.tar

1.9. 準備 logging operator `6.1.0` 所需之 images

定義 logging operator 版本變數
```
LOGGING_OPERATOR="6.1.0"
```

下載 logging operator chart file

helm pull oci://ghcr.io/kube-logging/helm-charts/logging-operator \
--version ${LOGGING_OPERATOR} \
-d ${HOME}/k8s/addon/logging/logging-operator/

檢視 logging operator 執行所需之 images

echo 'ghcr.io/kube-logging/logging-operator:6.1.0
ghcr.io/axoflow/axosyslog:4.18.1
ghcr.io/kube-logging/logging-operator/fluentd:6.1.0-full
ghcr.io/kube-logging/logging-operator/syslog-ng-reloader:6.1.0
ghcr.io/kube-logging/logging-operator/config-reloader:6.1.0
ghcr.io/kube-logging/logging-operator/fluentd-drain-watch:6.1.0
ghcr.io/kube-logging/logging-operator/node-exporter:6.1.0
ghcr.io/axoflow/axosyslog-metrics-exporter:0.0.13' >> ${HOME}/k8s/img/img-list.txt

將 logging operator images 備份到指定目錄

for i in $(grep -E "kube-logging|axoflow" ${HOME}/k8s/img/img-list.txt); do podman pull ${i}; done
podman save -m $(grep -E "kube-logging|axoflow" ${HOME}/k8s/img/img-list.txt) > ${HOME}/k8s/img/kube-logging-${LOGGING_OPERATOR}.tar

1.10. 將整個工作目錄打包並匯入全離線的主機

壓縮出全離線安裝包
```
cd ~; tar -zcvf k8s-v1.34.1.tar.gz k8s/
```

檢視全離線安裝包

ls -lh ${HOME}/k8s-v1.34.1.tar.gz

執行結果：

-rw-r--r--. 1 bigred bigred 1.5G Oct 17 17:25 /home/bigred/k8s-v1.34.1.tar.gz

將檔案上傳至所有全離線的 K8s 叢集主機，包含可上傳 image 至 Harbor 的主機
```
scp ${HOME}/k8s-v1.34.1.tar.gz user_name@vm_ipaddress:.
```

1.11. 將離線安裝所需之 Container Images 匯入 Harbor

先決條件：已安裝好 Harbor

連線到可將 image tar 檔上傳至 Harbor 的主機
```
ssh user@ipaddress
```
定義 Harbor FQDN
```
HARBOR_FQDN=harbor.example.com
```

下載 Harbor CA 憑證

sudo curl -k \
-o /etc/pki/ca-trust/source/anchors/harbor-ca.crt \
https://${HARBOR_FQDN}/api/v2.0/systeminfo/getcert

更新系統的 CA 信任清單，讓 HTTPS 連線時能信任此憑證
```
sudo update-ca-trust
```

設定 podman 信任 Harbor 自簽 CA 憑證

sudo mkdir /etc/containers/certs.d/${HARBOR_FQDN}
sudo curl -k \
-o /etc/containers/certs.d/${HARBOR_FQDN}/ca.crt \
https://${HARBOR_FQDN}/api/v2.0/systeminfo/getcert

登入 harbor

podman login ${HARBOR_FQDN}

執行結果：

Username: admin
Password:
Login Succeeded!

上傳所有 container images 至 Harbor

cd ~/k8s/img; ./imgctl.sh

正確執行結果：

Load All Images Successfully
Currnt: 1/29 harbor.example.com/library/kube-apiserver:v1.34.1 push ok
Currnt: 2/29 harbor.example.com/library/kube-controller-manager:v1.34.1 push ok
Currnt: 3/29 harbor.example.com/library/kube-scheduler:v1.34.1 push ok
Currnt: 4/29 harbor.example.com/library/kube-proxy:v1.34.1 push ok
Currnt: 5/29 harbor.example.com/library/coredns/coredns:v1.12.1 push ok
Currnt: 6/29 harbor.example.com/library/pause:3.10.1 push ok
Currnt: 7/29 harbor.example.com/library/etcd:3.6.4-0 push ok
Currnt: 8/29 harbor.example.com/library/ingress-nginx/controller:v1.13.3@sha256:1b044f6dcac3afbb59e05d98463f1dec6f3d3fb99940bc12ca5d80270358e3bd push ok
Currnt: 9/29 harbor.example.com/library/ingress-nginx/kube-webhook-certgen:v1.6.3@sha256:3d671cf20a35cd94efc5dcd484970779eb21e7938c98fbc3673693b8a117cf39 push ok
Currnt: 10/29 harbor.example.com/library/kube-vip/kube-vip:v1.0.1 push ok
Currnt: 11/29 harbor.example.com/library/kube-vip/kube-vip-cloud-provider:v0.0.12 push ok
Currnt: 12/29 harbor.example.com/library/metrics-server/metrics-server:v0.8.0 push ok
Currnt: 13/29 harbor.example.com/library/fluent/fluentd-kubernetes-daemonset:v1.19.0-debian-syslog-amd64-1.1 push ok
Currnt: 14/29 harbor.example.com/library/cilium/cilium-envoy:v1.34.7-1757592137-1a52bb680a956879722f48c591a2ca90f7791324@sha256:7932d656b63f6f866b6732099d33355184322123cfe1182e6f05175a3bc2e0e0 push ok
Currnt: 15/29 harbor.example.com/library/cilium/cilium:v1.18.2@sha256:858f807ea4e20e85e3ea3240a762e1f4b29f1cb5bbd0463b8aa77e7b097c0667 push ok
Currnt: 16/29 harbor.example.com/library/cilium/hubble-relay:v1.18.2@sha256:6079308ee15e44dff476fb522612732f7c5c4407a1017bc3470916242b0405ac push ok
Currnt: 17/29 harbor.example.com/library/cilium/hubble-ui-backend:v0.13.3@sha256:db1454e45dc39ca41fbf7cad31eec95d99e5b9949c39daaad0fa81ef29d56953 push ok
Currnt: 18/29 harbor.example.com/library/cilium/hubble-ui:v0.13.3@sha256:661d5de7050182d495c6497ff0b007a7a1e379648e60830dd68c4d78ae21761d push ok
Currnt: 19/29 harbor.example.com/library/cilium/operator-generic:v1.18.2@sha256:cb4e4ffc5789fd5ff6a534e3b1460623df61cba00f5ea1c7b40153b5efb81805 push ok
Currnt: 20/29 harbor.example.com/library/sig-storage/nfs-subdir-external-provisioner:v4.0.2 push ok
Currnt: 21/29 harbor.example.com/library/library/busybox:stable push ok
Currnt: 22/29 harbor.example.com/library/kube-logging/logging-operator:6.1.0 push ok
Currnt: 23/29 harbor.example.com/library/axoflow/axosyslog:4.18.1 push ok
Currnt: 24/29 harbor.example.com/library/kube-logging/logging-operator/fluentd:6.1.0-full push ok
Currnt: 25/29 harbor.example.com/library/kube-logging/logging-operator/syslog-ng-reloader:6.1.0 push ok
Currnt: 26/29 harbor.example.com/library/kube-logging/logging-operator/config-reloader:6.1.0 push ok
Currnt: 27/29 harbor.example.com/library/kube-logging/logging-operator/fluentd-drain-watch:6.1.0 push ok
Currnt: 28/29 harbor.example.com/library/kube-logging/logging-operator/node-exporter:6.1.0 push ok
Currnt: 29/29 harbor.example.com/library/axoflow/axosyslog-metrics-exporter:0.0.13 push ok

2. 建置 HA K8s 前置作業

2.1. 先決條件

已將 K8s 全離線安裝包(檔名:k8s-v1.34.1.tar.gz)匯入 K8s 叢集中的每一台主機
已將 Harbor 自簽 root CA 憑證匯入匯入 K8s 叢集中的每一台 (Harbor 如果不是自簽 root CA 則不用做到此步驟)

2.2. 連線至 K8s 的第一台 Control-plane 節點

ssh 連線至第一台 Control-plane 節點
```
ssh user@ipaddress
```

2.3. 關閉 Firewalld Systemd Service

關閉 Firewalld Systemd Service

sudo systemctl disable --now firewalld.service

2.4. 調整 SELinux 為 `permissive` mode

調整 SELinux 為 permissive mode

# Set SELinux in permissive mode (effectively disabling it)
sudo setenforce 0
sudo sed -i 's/^SELINUX=enforcing$/SELINUX=permissive/' /etc/selinux/config

2.5. 確認 SWAP 已關閉

確認 SWAP 已關閉

free -mh

執行結果：

 total used free shared buff/cache available
Mem: 7.5Gi 530Mi 6.2Gi 8.0Mi 1.0Gi 7.0Gi
Swap: 0B 0B 0B

確認 swap 欄位的值都是 0 B

2.6. 確認 Kernel 版本 >= 5.10

確認 Kernel 版本 >= 5.10
```
uname -r
```
執行結果：
```
5.14.0-570.52.1.el9_6.x86_64
```

2.7. 添加必要 Kernel Modules

永久添加 br_netfilter 和 overlay Kernel Modules

cat <<EOF | sudo tee /etc/modules-load.d/k8s.conf
overlay
br_netfilter
EOF

立即啟用 br_netfilter 和 overlay Kernel Modules

sudo modprobe overlay
sudo modprobe br_netfilter

驗證已載入 br_netfilter 和 overlay Kernel Modules

sudo lsmod | grep -E "overlay|br_netfilter"

執行結果：

br_netfilter 36864 0
bridge 417792 1 br_netfilter
overlay 229376 0

2.8. 添加必要 Kernel Parameters

永久添加必要 Kernel Parameters

cat <<EOF | sudo tee /etc/sysctl.d/99-k8s-cri.conf
net.bridge.bridge-nf-call-iptables = 1
net.bridge.bridge-nf-call-ip6tables = 1
net.ipv4.ip_forward = 1
EOF

立即載入 Kernel Parameters
```
sudo sysctl --system
```

驗證 net.bridge.bridge-nf-call-iptables, net.bridge.bridge-nf-call-ip6tables, 和 net.ipv4.ip_forward 的值都設成 1

sysctl net.bridge.bridge-nf-call-iptables net.bridge.bridge-nf-call-ip6tables net.ipv4.ip_forward

執行結果：

net.bridge.bridge-nf-call-iptables = 1
net.bridge.bridge-nf-call-ip6tables = 1
net.ipv4.ip_forward = 1

2.9. 解壓縮 K8s 全離線安裝包

設定 K8s 全離線安裝包所在的目錄變數
```
PREFIX="$HOME"
```

解壓縮 K8s 全離線安裝包

tar -zxvf "$PREFIX"/k8s-v1.34.1.tar.gz

執行結果：

...
tar: k8s/img/ingress-nginx-controller-v1.13.3.tar: time stamp 2025-10-20 14:18:13 is 166476.992186816 s in the future
k8s/config/
tar: k8s/img: time stamp 2025-10-20 14:34:01 is 167424.992012128 s in the future

2.10. 安裝所有必要軟體套件

安裝所有必要軟體套件

sudo yum localinstall "$HOME"/k8s/pkg/kubernetes/*.rpm

2.11. 確認節點可以透過 DNS 解析到 harbor

定義 Harbor FQDN 變數

HARBOR_FQDN=harbor.example.com
DOMAIN_NAME_SYSTEM_SERVER=172.20.6.11

確認節點可以透過 DNS 解析到 harbor

dig @$DOMAIN_NAME_SYSTEM_SERVER $HARBOR_FQDN +short

執行結果：

172.20.7.32

2.12. 啟動 CRI-O Service 並設為開機自動啟動

啟動 CRI-O Service 並設為開機自動啟動
```
sudo systemctl enable --now crio.service
```

確認 CRI-O Service 狀態

sudo systemctl status crio.service

執行結果：

● crio.service - Container Runtime Interface for OCI (CRI-O)
Loaded: loaded (/usr/lib/systemd/system/crio.service; enabled; preset: disabled)
Active: active (running) since Sat 2025-10-18 16:48:59 CST; 1min 18s ago
Docs: https://github.com/cri-o/cri-o
Main PID: 5734 (crio)
Tasks: 7
Memory: 20.0M
CPU: 126ms
CGroup: /system.slice/crio.service
└─5734 /usr/bin/crio
Oct 18 16:48:59 topgun-c1.kubeantony.com crio[5734]: time="2025-10-18T16:48:59.314737723+08:00" le…cher"
Oct 18 16:48:59 topgun-c1.kubeantony.com crio[5734]: time="2025-10-18T16:48:59.314774402+08:00" le…face"
Oct 18 16:48:59 topgun-c1.kubeantony.com crio[5734]: time="2025-10-18T16:48:59.314808872+08:00" le…bled"
Oct 18 16:48:59 topgun-c1.kubeantony.com crio[5734]: time="2025-10-18T16:48:59.314814672+08:00" le…ated"
Oct 18 16:48:59 topgun-c1.kubeantony.com crio[5734]: time="2025-10-18T16:48:59.314820552+08:00" le… NRI"
Oct 18 16:48:59 topgun-c1.kubeantony.com crio[5734]: time="2025-10-18T16:48:59.314823302+08:00" le…p..."
Oct 18 16:48:59 topgun-c1.kubeantony.com crio[5734]: time="2025-10-18T16:48:59.314825973+08:00" le…s..."
Oct 18 16:48:59 topgun-c1.kubeantony.com crio[5734]: time="2025-10-18T16:48:59.314833213+08:00" le…tate"
Oct 18 16:48:59 topgun-c1.kubeantony.com crio[5734]: time="2025-10-18T16:48:59.314882773+08:00" le…bled"
Oct 18 16:48:59 topgun-c1.kubeantony.com systemd[1]: Started Container Runtime Interface for OCI (…I-O).
Hint: Some lines were ellipsized, use -l to show in full.

2.13. 設定 private registry 驗證

將 Harbor 自簽 ca 憑證上傳至主機家目錄
設定 Harbor 自簽 ca 憑證所在的目錄和 CA 憑證檔名為變數
```
CA_PREFIX="$HOME"
CA_FILE_NAME="ca.pem"
```

讓 RHEL 信任 Harbor 自簽 ca 憑證

sudo cp "$CA_PREFIX"/"$CA_FILE_NAME" /etc/pki/ca-trust/source/anchors/harbor-ca.crt
sudo update-ca-trust

編輯 CRI-O 設定檔，告訴它去哪裡讀取全域的認證資訊
```
sudo nano /etc/crio/crio.conf.d/10-crio.conf
```
檔案內容：

新增 global_auth_file 那一行：指定 CRI-O 讀取 Docker 格式的全域認證檔案路徑還有 pause_image 這行，如果沒指定這行預設還是會到 K8s 的 image repo 去拉還有 conmon_cgroup 和 cgroup_manager 也要指定在 crio.runtime 區塊底下
```
[crio.image]
signature_policy = "/etc/crio/policy.json"
global_auth_file = "/etc/crio/registries.d/auth.json"
pause_image="harbor.example.com/library/pause:3.10.1"
[crio.runtime]
default_runtime = "crun"
conmon_cgroup = "pod"
cgroup_manager = "systemd"
```
建立存放認證檔案的目錄
```
sudo mkdir -p /etc/crio/registries.d/
```
設定 Harbor Registry 的 FQDN (網域名稱) 變數，方便後續使用
```
HARBOR_FQDN=harbor.example.com
```
使用 podman 登入 Harbor，並將產生的認證 token 儲存到 CRI-O 指定的 auth.json 檔案中
```
sudo podman login $HARBOR_FQDN --authfile /etc/crio/registries.d/auth.json
```

驗證認證檔案是否已成功建立

sudo cat /etc/crio/registries.d/auth.json

執行結果如下：

{
"auths": {
"harbor.example.com": {
"auth": "YWRtaW46SGFyYm9yMTIzNDU="
}
}
}

編輯 system-wide 的 registry 設定檔，供 Podman, CRI-O, Skopeo 等工具共用
```
sudo nano /etc/containers/registries.conf
```
檔案內容如下：

注意，Harbor FQDN 每個環境會不同。
```
[[registry]]
location = "harbor.example.com"
insecure = false 
```
重新啟動 CRI-O 服務，使其載入所有新的設定 (10-crio.conf 和 registries.conf)
```
sudo systemctl restart crio
```

使用 crictl (CRI 的客戶端工具) 測試是否能成功從私有 Harbor 拉取映像檔

sudo crictl pull ${HARBOR_FQDN}/library/library/busybox:stable

成功執行結果：

Image is up to date for harbor.example.com/library/library/busybox@sha256:f0d4f96113b0ebc3bc741b49cc158254ddd91bbba8dba20281b2dacd2da4a45f

清理測試，移除剛剛拉取的映像檔

sudo crictl rmi ${HARBOR_FQDN}/library/library/busybox:stable

2.14. 設定 kubelet service node ip

指定節點 internal ip

INTERFACE=ens18
IPV4_IP=$(ip -4 a s $INTERFACE | awk '/inet / {print $2}' | cut -d'/' -f1)
sudo sed -i \
-e '/^KUBELET_EXTRA_ARGS=$/s/$/\"--node-ip='"$IPV4_IP"'\"/' \
/etc/sysconfig/kubelet

檢查是否正確修改

cat /etc/sysconfig/kubelet

執行結果:

KUBELET_EXTRA_ARGS="--node-ip=172.20.6.111"

2.15. 在執行 kubeadm 之前啟用 kubelet 服務

啟動 kubelet 服務

sudo systemctl enable --now kubelet.service

2.16. 設定 NTP 校時

編輯 chrony 設定檔

sudo nano /etc/chrony.conf

檔案內容如下：

#pool 2.rhel.pool.ntp.org iburst
server 172.20.6.249 iburst

重啟 chronyd 服務
```
sudo systemctl restart chronyd
```

確認是否成功校時

sudo chronyc sources

正確執行結果：

MS Name/IP address Stratum Poll Reach LastRx Last sample
===============================================================================
^* 172.20.6.249 3 6 377 20 -64us[ -237us] +/- 19ms

2.16. 在其他所有 K8s 節點重複執行所有步驟 2.2. ~ 2.16.

3. 透過 kubeadm 開始建立 HA K8s

3.1. 設定 kube-vip (單台 Control-plane 可跳過此步驟)

以可以執行 sudo 的 user 透過 ssh 連線至第一台 Control-plane node
```
ssh sudo_user@ipaddderss
```

將 kube-vip static pod 拷貝到 /etc/kubernetes/manifests/

sudo cp "$HOME"/k8s/addon/kube-vip/ha-control-plane/kube-vip-static-pod.yaml /etc/kubernetes/manifests/kube-vip.yaml

修改 kube-vip 的 Service Account，只需在第一台 Control-plane 需要修改

sudo sed -i 's|path: /etc/kubernetes/admin.conf|path: /etc/kubernetes/super-admin.conf|g' \
/etc/kubernetes/manifests/kube-vip.yaml

設定 harbor fqdn
```
HARBOR_FQDN=harbor.example.com
```

修改 kube-vip 的 image repo

sudo sed -i "s|image: ghcr.io|image: ${HARBOR_FQDN}/library|g" \
/etc/kubernetes/manifests/kube-vip.yaml

$ sudo nano /etc/kubernetes/manifests/kube-vip.yaml
......
spec:
containers:
......
- name: vip_interface
value: ens18
- name: vip_subnet
value: "24"
......
- name: address
value: 10.10.7.31

3.2. 編輯 kubeadm 初始化設定檔

設定 kubeadm 初始化設定檔

nano "$HOME"/k8s/config/kubeadm-init.yaml

注意每個環境需設定以下項目:

localAPIEndpoint.advertiseAddress: API Server 宣告(Advertise)給叢集其他成員的 IP 位址。

nodeRegistration.criSocket: Kubelet 應使用的 CRI socket 路徑。

nodeRegistration.name: 此節點在 Kubernetes 叢集中的唯一識別名稱 (通常使用主機名稱)。

clusterName: K8s 叢集的名稱。

controllerManager.extraVolumes: 掛載額外的磁碟區 (Volume) 到 kube-controller-manager Pod 中。

imageRepository: 用於拉取 Kubernetes 核心組件 (如 API Server, etcd) images 的 Registry 位址。

kubernetesVersion: 要部署的 Kubernetes 確切版本。

networking.serviceSubnet: 分配給 Kubernetes Services 使用的虛擬 IP 位址範圍 (CIDR)。

networking.podSubnet: 分配給叢集中所有 Pods 使用的 IP 位址範圍 (CIDR)。

proxy.disabled: 停用節點上的 kube-proxy 組件。

controlPlaneEndpoint: HA 架構的 K8s LoadBalance IP，供所有節點和使用者存取 Kubernetes API Server 的 IP 或 FQDN。

imageMaximumGCAge: 節點上未使用 images 在被垃圾回收 (GC) 前可保留的最長存留時間。

imageMinimumGCAge: 節點上未使用 images 在被垃圾回收 (GC) 前必須保留的最短存留時間。

shutdownGracePeriod: Kubelet 執行正常關機程序 (Node Shutdown) 的總寬限時間。

shutdownGracePeriodCriticalPods: 在正常關機期間，Kubelet 等待「關鍵 Pods (Critical Pods)」優雅終止的專用寬限時間。

systemReserved.memory: 為 OS 系統守護進程 (如 systemd, sshd) 保留的記憶體量，Kubelet 不會使用這部分。

kubeReserved.memory: 為 Kubernetes 系統組件 (如 kubelet, 容器執行階段) 保留的記憶體量，Pod 無法使用這部分。

檔案內容如下 :

apiVersion: kubeadm.k8s.io/v1beta4
kind: InitConfiguration
localAPIEndpoint:
advertiseAddress: 172.20.6.111
bindPort: 6443
nodeRegistration:
criSocket: unix:///var/run/crio/crio.sock
imagePullPolicy: IfNotPresent
imagePullSerial: true
name: topgun-c1.kubeantony.com
taints: null
timeouts:
controlPlaneComponentHealthCheck: 4m0s
discovery: 5m0s
etcdAPICall: 2m0s
kubeletHealthCheck: 4m0s
kubernetesAPICall: 1m0s
tlsBootstrap: 5m0s
upgradeManifests: 5m0s
---
apiServer:
certSANs:
- 127.0.0.1
apiVersion: kubeadm.k8s.io/v1beta4
caCertificateValidityPeriod: 87600h0m0s
certificateValidityPeriod: 8760h0m0s
certificatesDir: /etc/kubernetes/pki
clusterName: topgun
controllerManager:
extraArgs:
- name: bind-address
value: "0.0.0.0"
- name: secure-port
value: "10257"
extraVolumes:
- name: tz-config
hostPath: /etc/localtime
mountPath: /etc/localtime
readOnly: true
dns:
imageRepository: harbor.example.com/library/coredns
encryptionAlgorithm: RSA-2048
etcd:
local:
dataDir: /var/lib/etcd
extraArgs:
- name: listen-metrics-urls
value: http://0.0.0.0:2381
imageRepository: harbor.example.com/library
kind: ClusterConfiguration
kubernetesVersion: 1.34.1
networking:
dnsDomain: cluster.local
serviceSubnet: 10.96.0.0/16
podSubnet: 10.244.0.0/16
proxy:
disabled: true
scheduler:
extraArgs:
- name: bind-address
value: "0.0.0.0"
- name: secure-port
value: "10259"
controlPlaneEndpoint: 172.20.6.110:6443
---
apiVersion: kubelet.config.k8s.io/v1beta1
authentication:
anonymous:
enabled: false
webhook:
cacheTTL: 0s
enabled: true
x509:
clientCAFile: /etc/kubernetes/pki/ca.crt
authorization:
mode: Webhook
webhook:
cacheAuthorizedTTL: 0s
cacheUnauthorizedTTL: 0s
cgroupDriver: systemd
clusterDNS:
- 10.96.0.10
clusterDomain: cluster.local
containerRuntimeEndpoint: ""
cpuManagerReconcilePeriod: 0s
crashLoopBackOff: {}
evictionPressureTransitionPeriod: 0s
fileCheckFrequency: 0s
healthzBindAddress: 127.0.0.1
healthzPort: 10248
httpCheckFrequency: 0s
imageMaximumGCAge: "168h"
imageMinimumGCAge: "2m0s"
kind: KubeletConfiguration
logging:
flushFrequency: 0
options:
json:
infoBufferSize: "0"
text:
infoBufferSize: "0"
verbosity: 0
memorySwap: {}
nodeStatusReportFrequency: 0s
nodeStatusUpdateFrequency: 0s
rotateCertificates: true
runtimeRequestTimeout: 0s
shutdownGracePeriod: 30s
shutdownGracePeriodCriticalPods: 10s
staticPodPath: /etc/kubernetes/manifests
streamingConnectionIdleTimeout: 0s
syncFrequency: 0s
volumeStatsAggPeriod: 0s
maxPods: 110
systemReserved:
memory: "1Gi"
kubeReserved:
memory: "2Gi"

3.3. 初始化第一台 Kubernetes control plane

Dry run set up the Kubernetes control plane，用以檢視是否設定檔有誤

sudo kubeadm init \
--dry-run \
--upload-certs \
--config="$HOME"/k8s/config/kubeadm-init.yaml

正確執行結果 :

...
Then you can join any number of worker nodes by running the following on each as root:
kubeadm join 172.20.6.110:6443 --token 0n2iwr.ugdsni61mrtuqv4l \
--discovery-token-ca-cert-hash sha256:0e9dd65a4b3ba662a1a9b9f448cc1a632b808f863dd892d46fa4005b731da5bb

Set up the Kubernetes control plane

sudo kubeadm init \
--upload-certs \
--config="$HOME"/k8s/config/kubeadm-init.yaml

正確執行結果 :

W1018 22:31:59.203382 8373 initconfiguration.go:332] error unmarshaling configuration schema.GroupVersionKind{Group:"kubeadm.k8s.io", Version:"v1beta4", Kind:"ClusterConfiguration"}: strict decoding error: unknown field "apiServer.timeoutForControlPlane"
[init] Using Kubernetes version: v1.34.1
[preflight] Running pre-flight checks
[WARNING SystemVerification]: kernel release 5.14.0-570.52.1.el9_6.x86_64 is unsupported. Supported LTS versions from the 5.x series are 5.4, 5.10 and 5.15. Any 6.x version is also supported. For cgroups v2 support, the recommended version is 5.10 or newer
[preflight] Pulling images required for setting up a Kubernetes cluster
[preflight] This might take a minute or two, depending on the speed of your internet connection
[preflight] You can also perform this action beforehand using 'kubeadm config images pull'
[certs] Using certificateDir folder "/etc/kubernetes/pki"
[certs] Generating "ca" certificate and key
[certs] Generating "apiserver" certificate and key
[certs] apiserver serving cert is signed for DNS names [kubernetes kubernetes.default kubernetes.default.svc kubernetes.default.svc.cluster.local topgun-c1.kubeantony.com] and IPs [10.96.0.1 172.20.6.111 172.20.6.110 127.0.0.1]
[certs] Generating "apiserver-kubelet-client" certificate and key
[certs] Generating "front-proxy-ca" certificate and key
[certs] Generating "front-proxy-client" certificate and key
[certs] Generating "etcd/ca" certificate and key
[certs] Generating "etcd/server" certificate and key
[certs] etcd/server serving cert is signed for DNS names [localhost topgun-c1.kubeantony.com] and IPs [172.20.6.111 127.0.0.1 ::1]
[certs] Generating "etcd/peer" certificate and key
[certs] etcd/peer serving cert is signed for DNS names [localhost topgun-c1.kubeantony.com] and IPs [172.20.6.111 127.0.0.1 ::1]
[certs] Generating "etcd/healthcheck-client" certificate and key
[certs] Generating "apiserver-etcd-client" certificate and key
[certs] Generating "sa" key and public key
[kubeconfig] Using kubeconfig folder "/etc/kubernetes"
[kubeconfig] Writing "admin.conf" kubeconfig file
[kubeconfig] Writing "super-admin.conf" kubeconfig file
[kubeconfig] Writing "kubelet.conf" kubeconfig file
[kubeconfig] Writing "controller-manager.conf" kubeconfig file
[kubeconfig] Writing "scheduler.conf" kubeconfig file
[etcd] Creating static Pod manifest for local etcd in "/etc/kubernetes/manifests"
[control-plane] Using manifest folder "/etc/kubernetes/manifests"
[control-plane] Creating static Pod manifest for "kube-apiserver"
[control-plane] Creating static Pod manifest for "kube-controller-manager"
[control-plane] Creating static Pod manifest for "kube-scheduler"
[kubelet-start] Writing kubelet environment file with flags to file "/var/lib/kubelet/kubeadm-flags.env"
[kubelet-start] Writing kubelet configuration to file "/var/lib/kubelet/instance-config.yaml"
[patches] Applied patch of type "application/strategic-merge-patch+json" to target "kubeletconfiguration"
[kubelet-start] Writing kubelet configuration to file "/var/lib/kubelet/config.yaml"
[kubelet-start] Starting the kubelet
[wait-control-plane] Waiting for the kubelet to boot up the control plane as static Pods from directory "/etc/kubernetes/manifests"
[kubelet-check] Waiting for a healthy kubelet at http://127.0.0.1:10248/healthz. This can take up to 4m0s
[kubelet-check] The kubelet is healthy after 501.238442ms
[control-plane-check] Waiting for healthy control plane components. This can take up to 4m0s
[control-plane-check] Checking kube-apiserver at https://172.20.6.111:6443/livez
[control-plane-check] Checking kube-controller-manager at https://0.0.0.0:10257/healthz
[control-plane-check] Checking kube-scheduler at https://0.0.0.0:10259/livez
[control-plane-check] kube-controller-manager is healthy after 1.860780055s
[control-plane-check] kube-scheduler is healthy after 2.364803775s
[control-plane-check] kube-apiserver is healthy after 4.00165287s
[upload-config] Storing the configuration used in ConfigMap "kubeadm-config" in the "kube-system" Namespace
[kubelet] Creating a ConfigMap "kubelet-config" in namespace kube-system with the configuration for the kubelets in the cluster
[upload-certs] Storing the certificates in Secret "kubeadm-certs" in the "kube-system" Namespace
[upload-certs] Using certificate key:
681423a365cee2a5ff5b612831e42a97ff941c0c6ad0595298a6ff603b0fae5d
[mark-control-plane] Marking the node topgun-c1.kubeantony.com as control-plane by adding the labels: [node-role.kubernetes.io/control-plane node.kubernetes.io/exclude-from-external-load-balancers]
[mark-control-plane] Marking the node topgun-c1.kubeantony.com as control-plane by adding the taints [node-role.kubernetes.io/control-plane:NoSchedule]
[bootstrap-token] Using token: z6kmo1.qp9d9u4xcb85xmjl
[bootstrap-token] Configuring bootstrap tokens, cluster-info ConfigMap, RBAC Roles
[bootstrap-token] Configured RBAC rules to allow Node Bootstrap tokens to get nodes
[bootstrap-token] Configured RBAC rules to allow Node Bootstrap tokens to post CSRs in order for nodes to get long term certificate credentials
[bootstrap-token] Configured RBAC rules to allow the csrapprover controller automatically approve CSRs from a Node Bootstrap Token
[bootstrap-token] Configured RBAC rules to allow certificate rotation for all node client certificates in the cluster
[bootstrap-token] Creating the "cluster-info" ConfigMap in the "kube-public" namespace
[kubelet-finalize] Updating "/etc/kubernetes/kubelet.conf" to point to a rotatable kubelet client certificate and key
[addons] Applied essential addon: CoreDNS
Your Kubernetes control-plane has initialized successfully!
To start using your cluster, you need to run the following as a regular user:
mkdir -p $HOME/.kube
sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
sudo chown $(id -u):$(id -g) $HOME/.kube/config
Alternatively, if you are the root user, you can run:
export KUBECONFIG=/etc/kubernetes/admin.conf
You should now deploy a pod network to the cluster.
Run "kubectl apply -f [podnetwork].yaml" with one of the options listed at:
https://kubernetes.io/docs/concepts/cluster-administration/addons/
You can now join any number of control-plane nodes running the following command on each as root:
kubeadm join 172.20.6.110:6443 --token z6kmo1.qp9d9u4xcb85xmjl \
--discovery-token-ca-cert-hash sha256:4ea08e749828d599c6e3aefb69be7bbfbfe47bdab702907464fe033f22547e50 \
--control-plane --certificate-key 681423a365cee2a5ff5b612831e42a97ff941c0c6ad0595298a6ff603b0fae5d
Please note that the certificate-key gives access to cluster sensitive data, keep it secret!
As a safeguard, uploaded-certs will be deleted in two hours; If necessary, you can use
"kubeadm init phase upload-certs --upload-certs" to reload certs afterward.
Then you can join any number of worker nodes by running the following on each as root:
kubeadm join 172.20.6.110:6443 --token z6kmo1.qp9d9u4xcb85xmjl \
--discovery-token-ca-cert-hash sha256:4ea08e749828d599c6e3aefb69be7bbfbfe47bdab702907464fe033f22547e50

3.4. 設定 kubeConfig

設定 kubeconfig

mkdir -p $HOME/.kube
sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
sudo chown $(id -u):$(id -g) $HOME/.kube/config
printf "\nsource <(kubectl completion bash)\nalias k=kubectl\ncomplete -o default -F __start_kubectl k\n" >> ~/.bashrc
source ~/.bashrc

第一台 control plan 安裝好後再將 kube-vip 權限調整回來

$ sudo sed -i 's|path: /etc/kubernetes/super-admin.conf|path: /etc/kubernetes/admin.conf|g' /etc/kubernetes/manifests/kube-vip.yaml
$ sudo systemctl daemon-reload
$ sudo systemctl restart kubelet

3.5. 安裝 Cilium CNI

安裝 helm 指令

cd ${HOME}/k8s/addon/cni/cilium/
tar -zxvf helm-v3.19.0-linux-amd64.tar.gz
sudo mv linux-amd64/helm /usr/local/bin/

安裝 cilium 與 hubble client 指令

tar -zxvf cilium-linux-amd64.tar.gz -C /tmp
tar -zxvf hubble-linux-amd64.tar.gz -C /tmp
sudo mv /tmp/cilium /usr/bin/
sudo mv /tmp/hubble /usr/bin/

編輯 cilium 設定檔

nano custom-values.yaml

檔案內容：

operator:
image:
repository: harbor.example.com/library/cilium/operator
tag: v1.18.2
useDigest: false
image:
repository: harbor.example.com/library/cilium/cilium
tag: v1.18.2
useDigest: false
envoy:
image:
repository: harbor.example.com/library/cilium/cilium-envoy
tag: v1.34.7-1757592137-1a52bb680a956879722f48c591a2ca90f7791324
useDigest: false
bpf:
masquerade: true
hubble:
relay:
enabled: true
image:
repository: harbor.example.com/library/cilium/hubble-relay
tag: v1.18.2
useDigest: false
ui:
enabled: true
service:
type: NodePort
frontend:
image:
repository: harbor.example.com/library/cilium/hubble-ui
tag: v0.13.3
useDigest: false
backend:
image:
repository: harbor.example.com/library/cilium/hubble-ui-backend
tag: v0.13.3
useDigest: false
ipam:
mode: kubernetes
ipv4NativeRoutingCIDR: 10.244.0.0/16
k8sServiceHost: 172.20.6.110
k8sServicePort: 6443
kubeProxyReplacement: true
autoDirectNodeRoutes: true
routingMode: native
devices: ens18

安裝 cilium

helm -n kube-system install cilium ./cilium-1.18.2.tgz -f custom-values.yaml

確認 cilium 已安裝成功

cilium status

執行結果：

 /¯¯\
/¯¯\__/¯¯\ Cilium: OK
\__/¯¯\__/ Operator: OK
/¯¯\__/¯¯\ Envoy DaemonSet: OK
\__/¯¯\__/ Hubble Relay: OK
\__/ ClusterMesh: disabled
DaemonSet cilium Desired: 6, Ready: 6/6, Available: 6/6
DaemonSet cilium-envoy Desired: 6, Ready: 6/6, Available: 6/6
Deployment cilium-operator Desired: 2, Ready: 2/2, Available: 2/2
Deployment hubble-relay Desired: 1, Ready: 1/1, Available: 1/1
Deployment hubble-ui Desired: 1, Ready: 1/1, Available: 1/1
Containers: cilium Running: 6
cilium-envoy Running: 6
cilium-operator Running: 2
clustermesh-apiserver
hubble-relay Running: 1
hubble-ui Running: 1
Cluster Pods: 9/9 managed by Cilium
Helm chart version:
Image versions cilium harbor.example.com/library/cilium/cilium:v1.18.2: 6
cilium-envoy harbor.example.com/library/cilium/cilium-envoy:v1.34.7-1757592137-1a52bb680a956879722f48c591a2ca90f7791324: 6
cilium-operator harbor.example.com/library/cilium/operator-generic:v1.18.2: 2
hubble-relay harbor.example.com/library/cilium/hubble-relay:v1.18.2: 1
hubble-ui harbor.example.com/library/cilium/hubble-ui-backend:v0.13.3: 1
hubble-ui harbor.example.com/library/cilium/hubble-ui:v0.13.3: 1

確認 cilium 有啟用 eBPF host routing

cilium_pod=$(kubectl -n kube-system get pods --field-selector status.phase=Running -l k8s-app=cilium -o name | tail -n 1 | cut -d "/" -f 2)
kubectl -n kube-system exec -it ${cilium_pod} -- cilium-dbg status

執行結果：

KubeProxyReplacement: True [ens18 172.20.6.115 172.20.6.117 fe80::be24:11ff:fe2e:cc62 (Direct Routing)]
Host firewall: Disabled
SRv6: Disabled
CNI Chaining: none
CNI Config file: successfully wrote CNI configuration file to /host/etc/cni/net.d/05-cilium.conflist
Cilium: Ok 1.18.2 (v1.18.2-5bd307a8)
NodeMonitor: Listening for events on 2 CPUs with 64x4096 of shared memory
Cilium health daemon: Ok
IPAM: IPv4: 7/254 allocated from 10.244.5.0/24,
IPv4 BIG TCP: Disabled
IPv6 BIG TCP: Disabled
BandwidthManager: Disabled
Routing: Network: Native Host: BPF
Attach Mode: TCX
Device Mode: veth
Masquerading: BPF [ens18] 10.244.0.0/16 [IPv4: Enabled, IPv6: Disabled]
Controller Status: 47/47 healthy
Proxy Status: OK, ip 10.244.5.177, 0 redirects active on ports 10000-20000, Envoy: external
Global Identity Range: min 256, max 65535
Hubble: Ok Current/Max Flows: 2491/4095 (60.83%), Flows/s: 3.51 Metrics: Disabled
Encryption: Disabled
Cluster health: 6/6 reachable (2025-10-23T08:51:12Z) (Probe interval: 2m33.896961447s)
Name IP Node Endpoints
Modules Health: Stopped(12) Degraded(0) OK(78)

3.6. 新增其他 Control-plane 節點進 K8s 叢集 (單台 Control-plane 可跳過此步驟)

以可以執行 sudo 的 user 透過 ssh 連線至其他 Control-plane node
```
ssh sudo_user@ipaddderss
```

將 kube-vip static pod 拷貝到 /etc/kubernetes/manifests/

sudo cp "$HOME"/k8s/addon/kube-vip/ha-control-plane/kube-vip-static-pod.yaml /etc/kubernetes/manifests/kube-vip.yaml

設定 harbor fqdn
```
HARBOR_FQDN=harbor.example.com
```

修改 kube-vip 的 image repo

sudo sed -i "s|image: ghcr.io|image: ${HARBOR_FQDN}/library|g" \
/etc/kubernetes/manifests/kube-vip.yaml

獲得 Control-plane node Kubeadm Join Command 請在第一台 Control-plane node 執行以下命令

kubeadm_init_config_file="${HOME}/k8s/config/kubeadm-init.yaml"
certificate_key=$(sudo kubeadm init phase upload-certs --upload-certs --config ${kubeadm_init_config_file} | tail -n 1)
join_cmd=$(sudo kubeadm token create --print-join-command)
join_cp_cmd="sudo $join_cmd --control-plane --certificate-key $certificate_key"
echo $join_cp_cmd

執行結果：

sudo kubeadm join 172.20.6.110:6443 --token rl5cdl.8552g1j3ezrvxk21 --discovery-token-ca-cert-hash sha256:4ea08e749828d599c6e3aefb69be7bbfbfe47bdab702907464fe033f22547e50 --control-plane --certificate-key d52af404ed5765485f28e0c5e7e886ae244a8861a78dc3b1ce1a0487194e8a1a

將 Control-plane 節點加入 K8s 叢集請在要加入 K8s 的 Control-plane node 執行以下命令

sudo kubeadm join 172.20.6.110:6443 --token rl5cdl.8552g1j3ezrvxk21 --discovery-token-ca-cert-hash sha256:4ea08e749828d599c6e3aefb69be7bbfbfe47bdab702907464fe033f22547e50 --control-plane --certificate-key d52af404ed5765485f28e0c5e7e886ae244a8861a78dc3b1ce1a0487194e8a1a

join node 使用的 token 會在 24 小時後自動過期

重複以上 1. ~ 6. 步驟將其他 Control-plane node 加到 K8s Cluster

3.7. 新增 Worker 節點進 K8s 叢集

在第一台 Controlplane 將 join worker node 指令 print 出來

sudo kubeadm token create --print-join-command

執行結果：

kubeadm join 172.20.6.110:6443 --token inyh77.qp4dqe6wto9uhk8m --discovery-token-ca-cert-hash sha256:4ea08e749828d599c6e3aefb69be7bbfbfe47bdab702907464fe033f22547e50

以可以執行 sudo 的 user 透過 ssh 連線至 worker node
```
ssh sudo_user@ipaddderss
```

將 worker node 加入 K8s 叢集

sudo kubeadm join 172.20.6.110:6443 \
--token inyh77.qp4dqe6wto9uhk8m \
--discovery-token-ca-cert-hash sha256:4ea08e749828d599c6e3aefb69be7bbfbfe47bdab702907464fe033f22547e50

ssh 連線到其他 worker node，重複執行步驟 3，將其他 worker node 也加入 K8s 叢集

回到第一台 Control-plane 執行以下命令，將所有 worker nodes 都貼 label

kubectl label node topgun-w1.kubeantony.com node-role.kubernetes.io/worker=
kubectl label node topgun-w2.kubeantony.com node-role.kubernetes.io/worker=
kubectl label node topgun-w3.kubeantony.com node-role.kubernetes.io/worker=

3.8. 檢視 K8s 狀態是否正常

檢視 K8s node 狀態

kubectl get nodes

執行結果：

NAME STATUS ROLES AGE VERSION
topgun-c1.kubeantony.com Ready control-plane 3d15h v1.34.1
topgun-c2.kubeantony.com Ready control-plane 26h v1.34.1
topgun-c3.kubeantony.com Ready control-plane 3h24m v1.34.1
topgun-w1.kubeantony.com Ready worker 3d6h v1.34.1
topgun-w2.kubeantony.com Ready worker 17m v1.34.1
topgun-w3.kubeantony.com Ready worker 16m v1.34.1

檢視 kube-system namespace 底下所有 pods 狀態

kubectl -n kube-system get pods

執行結果：

NAME READY STATUS RESTARTS AGE
cilium-b74sh 1/1 Running 0 26h
cilium-btg2h 1/1 Running 0 26h
cilium-envoy-24skx 1/1 Running 0 26h
cilium-envoy-llwv7 1/1 Running 0 17m
cilium-envoy-nb5l2 1/1 Running 0 3h24m
cilium-envoy-nvkz9 1/1 Running 0 26h
cilium-envoy-vz6kj 1/1 Running 0 16m
cilium-envoy-wm4xw 1/1 Running 0 26h
cilium-gp9v9 1/1 Running 0 17m
cilium-operator-794b864946-8j8j5 1/1 Running 1 (10h ago) 26h
cilium-operator-794b864946-9whct 1/1 Running 0 26h
cilium-vqp5v 1/1 Running 0 26h
cilium-xgcch 1/1 Running 0 16m
cilium-zj2xj 1/1 Running 0 3h24m
coredns-f74588c75-86h95 1/1 Running 0 26h
coredns-f74588c75-9992t 1/1 Running 0 26h
etcd-topgun-c1.kubeantony.com 1/1 Running 0 3d15h
etcd-topgun-c2.kubeantony.com 1/1 Running 0 26h
etcd-topgun-c3.kubeantony.com 1/1 Running 0 3h24m
hubble-relay-7d6865bf7b-7wvhl 1/1 Running 0 26h
hubble-ui-c6998f8ff-6m4cn 2/2 Running 0 26h
kube-apiserver-topgun-c1.kubeantony.com 1/1 Running 0 3d15h
kube-apiserver-topgun-c2.kubeantony.com 1/1 Running 0 26h
kube-apiserver-topgun-c3.kubeantony.com 1/1 Running 0 3h24m
kube-controller-manager-topgun-c1.kubeantony.com 1/1 Running 1 (10h ago) 3d15h
kube-controller-manager-topgun-c2.kubeantony.com 1/1 Running 0 26h
kube-controller-manager-topgun-c3.kubeantony.com 1/1 Running 0 3h24m
kube-scheduler-topgun-c1.kubeantony.com 1/1 Running 1 (10h ago) 3d15h
kube-scheduler-topgun-c2.kubeantony.com 1/1 Running 0 26h
kube-scheduler-topgun-c3.kubeantony.com 1/1 Running 0 3h24m
kube-vip-topgun-c1.kubeantony.com 1/1 Running 1 (10h ago) 3d15h
kube-vip-topgun-c3.kubeantony.com 1/1 Running 0 3h24m

3.9. 檢測 K8s 網路延遲和吞吐量

主要測試以下項目
- 吞吐量 - TCP Throughput (TCP_STREAM)：有助於了解在特定配置下可達到的最大吞吐量。
  - 此測試代表大量資料傳輸的應用程式，例如串流服務或執行資料上傳/下載的服務。
- 請求/回應速率 - Request/Response Rate (TCP_RR)：主要測量處理單一網路封包來回轉發的延遲與效率。這項基準測試將在線路上產生每秒可能的最大封包數（packets per second），並著重測試處理單一網路封包的成本（資源消耗）。
  - 此測試代表了那些維持持續性連線（persistent connections）、並與其他服務交換請求/回應類型互動的服務。這對於使用 REST 或 gRPC API 的服務來說很常見。
- 連線速率 - Connection Rate (TCP_CRR)：它類似於 Request/Response Rate 測試，但會為每一次來回建立一個新的 TCP 連線。
  - 此測試代表暴露於公網的服務，它會接收來自許多客戶端的連線。L4 代理或對外部端點開啟許多連線的服務，都是很好的例子。

透過 cilium 指令檢測 K8s 網路頻寬

cilium connectivity perf \
--crr \
--host-to-pod \
--pod-to-host \
--performance-image quay.io/cilium/network-perf:1751527436-c2462ae \
--node-selector-client kubernetes.io/hostname=topgun-w1.kubeantony.com \
--node-selector-server kubernetes.io/hostname=topgun-w2.kubeantony.com

執行結果如下：

🏃[cilium-test-1] Running 1 tests ...
[=] [cilium-test-1] Test [network-perf] [1/1]
................................
🔥 Network Performance Test Summary [cilium-test-1]:
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
📋 Scenario | Node | Test | Duration | Min | Mean | Max | P50 | P90 | P99 | Transaction rate OP/s
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
📋 pod-to-pod | same-node | TCP_CRR | 10s | 50µs | 84.48µs | 11.99ms | 77µs | 96µs | 144µs | 11787.95
📋 pod-to-pod | same-node | TCP_RR | 10s | 11µs | 30.74µs | 4.659ms | 31µs | 35µs | 46µs | 32197.86
📋 pod-to-host | same-node | TCP_CRR | 10s | 61µs | 98.57µs | 21.094ms | 90µs | 109µs | 155µs | 10104.54
📋 pod-to-host | same-node | TCP_RR | 10s | 12µs | 31.86µs | 1.091ms | 32µs | 37µs | 49µs | 31071.90
📋 host-to-pod | same-node | TCP_CRR | 10s | 60µs | 100.33µs | 14.059ms | 90µs | 109µs | 160µs | 9930.36
📋 host-to-pod | same-node | TCP_RR | 10s | 12µs | 31.94µs | 892µs | 32µs | 36µs | 48µs | 30996.63
📋 host-to-host | same-node | TCP_CRR | 10s | 52µs | 76.41µs | 1.924ms | 73µs | 89µs | 127µs | 13016.02
📋 host-to-host | same-node | TCP_RR | 10s | 12µs | 31.89µs | 1.281ms | 32µs | 36µs | 48µs | 31043.05
📋 pod-to-pod | other-node | TCP_CRR | 10s | 242µs | 330.04µs | 13.257ms | 301µs | 342µs | 790µs | 3027.08
📋 pod-to-pod | other-node | TCP_RR | 10s | 87µs | 112.64µs | 4.085ms | 112µs | 124µs | 146µs | 8867.04
📋 pod-to-host | other-node | TCP_CRR | 10s | 243µs | 321.36µs | 15.197ms | 302µs | 340µs | 483µs | 3108.95
📋 pod-to-host | other-node | TCP_RR | 10s | 89µs | 113.52µs | 3.172ms | 113µs | 125µs | 147µs | 8797.96
📋 host-to-pod | other-node | TCP_CRR | 10s | 230µs | 311.48µs | 13.035ms | 287µs | 334µs | 635µs | 3207.10
📋 host-to-pod | other-node | TCP_RR | 10s | 88µs | 115.57µs | 4.126ms | 114µs | 128µs | 153µs | 8641.95
📋 host-to-host | other-node | TCP_CRR | 10s | 229µs | 303.13µs | 21.099ms | 285µs | 322µs | 417µs | 2739.19
📋 host-to-host | other-node | TCP_RR | 10s | 89µs | 114.78µs | 4.428ms | 114µs | 126µs | 148µs | 8702.07
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
----------------------------------------------------------------------------------------
📋 Scenario | Node | Test | Duration | Throughput Mb/s
----------------------------------------------------------------------------------------
📋 pod-to-pod | same-node | TCP_STREAM | 10s | 18952.05
📋 pod-to-pod | same-node | TCP_STREAM_MULTI | 10s | 45634.84
📋 pod-to-host | same-node | TCP_STREAM | 10s | 16338.34
📋 pod-to-host | same-node | TCP_STREAM_MULTI | 10s | 41785.81
📋 host-to-pod | same-node | TCP_STREAM | 10s | 15643.64
📋 host-to-pod | same-node | TCP_STREAM_MULTI | 10s | 40812.09
📋 host-to-host | same-node | TCP_STREAM | 10s | 36117.05
📋 host-to-host | same-node | TCP_STREAM_MULTI | 10s | 82274.99
📋 pod-to-pod | other-node | TCP_STREAM | 10s | 9407.21
📋 pod-to-pod | other-node | TCP_STREAM_MULTI | 10s | 9417.40
📋 pod-to-host | other-node | TCP_STREAM | 10s | 9411.27
📋 pod-to-host | other-node | TCP_STREAM_MULTI | 10s | 9411.89
📋 host-to-pod | other-node | TCP_STREAM | 10s | 9409.00
📋 host-to-pod | other-node | TCP_STREAM_MULTI | 10s | 9398.15
📋 host-to-host | other-node | TCP_STREAM | 10s | 9408.12
📋 host-to-host | other-node | TCP_STREAM_MULTI | 10s | 9416.04
----------------------------------------------------------------------------------------
✅ [cilium-test-1] All 1 tests (32 actions) successful, 0 tests skipped, 0 scenarios skipped.

未開 ebpf host routing 的數值：

...
🏃[cilium-test-1] Running 1 tests ...
[=] [cilium-test-1] Test [network-perf] [1/1]
................................
🔥 Network Performance Test Summary [cilium-test-1]:
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
📋 Scenario | Node | Test | Duration | Min | Mean | Max | P50 | P90 | P99 | Transaction rate OP/s
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
📋 pod-to-pod | same-node | TCP_CRR | 10s | 50µs | 82.85µs | 10.656ms | 78µs | 94µs | 124µs | 12017.63
📋 pod-to-pod | same-node | TCP_RR | 10s | 10µs | 30.71µs | 828µs | 30µs | 35µs | 46µs | 32231.92
📋 pod-to-host | same-node | TCP_CRR | 10s | 59µs | 94.56µs | 12.326ms | 91µs | 108µs | 137µs | 10532.25
📋 pod-to-host | same-node | TCP_RR | 10s | 12µs | 31.94µs | 2.572ms | 32µs | 37µs | 48µs | 30996.44
📋 host-to-pod | same-node | TCP_CRR | 10s | 56µs | 93.13µs | 15.588ms | 90µs | 107µs | 136µs | 10694.60
📋 host-to-pod | same-node | TCP_RR | 10s | 12µs | 31.27µs | 1.842ms | 31µs | 36µs | 48µs | 31651.76
📋 host-to-host | same-node | TCP_CRR | 10s | 53µs | 75µs | 1.479ms | 72µs | 88µs | 123µs | 13261.02
📋 host-to-host | same-node | TCP_RR | 10s | 12µs | 31.87µs | 583µs | 32µs | 36µs | 47µs | 31059.78
📋 pod-to-pod | other-node | TCP_CRR | 10s | 278µs | 368.98µs | 9.809ms | 339µs | 382µs | 965µs | 2707.98
📋 pod-to-pod | other-node | TCP_RR | 10s | 95µs | 123.71µs | 4.119ms | 122µs | 137µs | 163µs | 8073.77
📋 pod-to-host | other-node | TCP_CRR | 10s | 248µs | 371.53µs | 1.052362s | 298µs | 335µs | 500µs | 2006.19
📋 pod-to-host | other-node | TCP_RR | 10s | 90µs | 114.49µs | 2.982ms | 114µs | 126µs | 147µs | 8723.87
📋 host-to-pod | other-node | TCP_CRR | 10s | 279µs | 366.76µs | 12.3ms | 338µs | 375µs | 850µs | 2724.34
📋 host-to-pod | other-node | TCP_RR | 10s | 105µs | 135.79µs | 15.723ms | 133µs | 148µs | 176µs | 7355.48
📋 host-to-host | other-node | TCP_CRR | 10s | 229µs | 301.42µs | 15.967ms | 284µs | 314µs | 415µs | 2739.19
📋 host-to-host | other-node | TCP_RR | 10s | 88µs | 114.62µs | 4.249ms | 114µs | 127µs | 148µs | 8713.25
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
----------------------------------------------------------------------------------------
📋 Scenario | Node | Test | Duration | Throughput Mb/s
----------------------------------------------------------------------------------------
📋 pod-to-pod | same-node | TCP_STREAM | 10s | 19819.33
📋 pod-to-pod | same-node | TCP_STREAM_MULTI | 10s | 44767.93
📋 pod-to-host | same-node | TCP_STREAM | 10s | 17519.15
📋 pod-to-host | same-node | TCP_STREAM_MULTI | 10s | 41288.42
📋 host-to-pod | same-node | TCP_STREAM | 10s | 15667.62
📋 host-to-pod | same-node | TCP_STREAM_MULTI | 10s | 40686.99
📋 host-to-host | same-node | TCP_STREAM | 10s | 36663.82
📋 host-to-host | same-node | TCP_STREAM_MULTI | 10s | 83454.15
📋 pod-to-pod | other-node | TCP_STREAM | 10s | 5515.69
📋 pod-to-pod | other-node | TCP_STREAM_MULTI | 10s | 5462.09
📋 pod-to-host | other-node | TCP_STREAM | 10s | 9393.23
📋 pod-to-host | other-node | TCP_STREAM_MULTI | 10s | 9399.02
📋 host-to-pod | other-node | TCP_STREAM | 10s | 5456.02
📋 host-to-pod | other-node | TCP_STREAM_MULTI | 10s | 5423.52
📋 host-to-host | other-node | TCP_STREAM | 10s | 9410.65
📋 host-to-host | other-node | TCP_STREAM_MULTI | 10s | 9416.39
----------------------------------------------------------------------------------------
✅ [cilium-test-1] All 1 tests (32 actions) successful, 0 tests skipped, 0 scenarios skipped.

通用欄位
- Scenario (情境): 描述流量的來源和目的地。
  - pod-to-pod: 從一個 Pod 到另一個 Pod。
  - pod-to-host: 從一個 Pod 到其運行的節點 (Host)。
  - host-to-pod: 從一個節點 (Host) 到一個 Pod。
  - host-to-host: 從一個節點 (Host) 到另一個節點 (Host)。
- Node (節點): 描述來源和目的地的相對位置。
  - same-node: 來源和目的地在同一個 Kubernetes 節點上。
  - other-node: 來源和目的地在不同的 Kubernetes 節點上。
表 1 這張表格專注於延遲（完成一個操作需要多長時間）和事務處理速率（每秒可以完成多少操作），主要用於 TCP_CRR 和 TCP_RR 測試。時間單位是微秒 (µs) 或毫秒 (ms)。
- Min (最小延遲): 在測試期間觀察到的最快的單次事務（請求/回應或連接/關閉）延遲。
- Mean (平均延遲): 所有事務延遲的算術平均值。
- Max (最大延遲): 在測試期間觀察到的最慢的單次事務延遲。高 Max 值可能表示網路抖動或偶發性的效能瓶頸。
- P50 (50百分位延遲): 也稱為中位數。50% 的事務延遲低於此值。與 Mean 相比，P50 受極端異常值的影響較小。
- P90 (90百分位延遲): 90% 的事務延遲低於此值。這是一個常見的服務水平指標 (SLI)，用於衡量絕大多數用戶的體驗。
- P99 (99百分位延遲): 99% 的事務延遲低於此值。這有助於識別「長尾延遲」(long-tail latency)，即影響少數請求的嚴重效能問題。
- Transaction rate OP/s (每秒事務處理速率): 每秒操作數 (Operations Per Second)。
  - 這個值越高越好，表示處理事務的效率越高。
表 2 這張表格專注於頻寬（每秒可以傳輸多少數據），主要用於 TCP_STREAM 和 TCP_STREAM_MULTI 測試。
- Throughput Mb/s (吞吐量 Mb/s):
  - 每秒百萬位元 (Megabits per second)。這個值顯示了在測試期間，來源和目的地之間數據傳輸的平均速率。值越高，表示網路頻寬越大。
- TCP_STREAM:
  - 使用單個 TCP 連接測量最大數據傳輸吞吐量（頻寬）。
- TCP_STREAM_MULTI:
  - 使用 32 個並行 TCP 連接測量最大數據傳輸吞吐量。這通常能更好地佔滿網路鏈路，顯示系統的總頻寬上限。

4. 安裝 K8s Addon

4.1. 安裝 Metrics server

切換工作目錄

cd ${HOME}/k8s/addon/metrics/metrics-server

編輯 Kustomization File

nano kustomization.yaml

檔案內容：

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
- ./components.yaml
images:
- name: registry.k8s.io/metrics-server/metrics-server
newName: harbor.example.com/library/metrics-server/metrics-server
newTag: v0.8.0
patches:
- target:
kind: Deployment
name: metrics-server
patch: |-
- op: add
path: /spec/template/spec/containers/0/args/-
value: --kubelet-insecure-tls

驗證 yaml 設定檔是否有誤

kubectl apply -k . --dry-run=server

正確執行結果：

serviceaccount/metrics-server created (server dry run)
clusterrole.rbac.authorization.k8s.io/system:aggregated-metrics-reader created (server dry run)
clusterrole.rbac.authorization.k8s.io/system:metrics-server created (server dry run)
rolebinding.rbac.authorization.k8s.io/metrics-server-auth-reader created (server dry run)
clusterrolebinding.rbac.authorization.k8s.io/metrics-server:system:auth-delegator created (server dry run)
clusterrolebinding.rbac.authorization.k8s.io/system:metrics-server created (server dry run)
service/metrics-server created (server dry run)
deployment.apps/metrics-server created (server dry run)
apiservice.apiregistration.k8s.io/v1beta1.metrics.k8s.io created (server dry run)

部署 Metrics Server
```
kubectl apply -k .
```

檢視 Metrics Server pods 運作狀態

kubectl -n kube-system get pods -l k8s-app=metrics-server

執行結果：

NAME READY STATUS RESTARTS AGE
metrics-server-69779649f-frvqz 1/1 Running 0 43s

檢視 K8s 所有 nodes 的 cpu 記憶體使用狀況

kubectl top nodes

執行結果：

NAME CPU(cores) CPU(%) MEMORY(bytes) MEMORY(%)
topgun-c1.kubeantony.com 41m 2% 1705Mi 37%
topgun-c2.kubeantony.com 34m 1% 1175Mi 26%
topgun-c3.kubeantony.com 28m 1% 1057Mi 23%
topgun-w1.kubeantony.com 12m 0% 1066Mi 23%
topgun-w2.kubeantony.com 10m 0% 947Mi 21%
topgun-w3.kubeantony.com 9m 0% 778Mi 17%

4.2. 安裝 kube-vip On-Premises Cloud Controller

切換工作目錄

cd ${HOME}/k8s/addon/kube-vip/k8s-lb-service

將可分配的 IP Range 寫入 configmap

kubectl -n kube-system create configmap kubevip \
--from-literal range-global=172.20.6.117-172.20.6.120 \
--dry-run=client -o yaml > kube-vip-cm.yaml

編輯 Kustomization File

nano kustomization.yaml

檔案內容：

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
- ./kube-vip-rbac.yaml
- ./kube-vip-ds.yaml
- ./kube-vip-cloud-controller.yaml
- ./kube-vip-cm.yaml
images:
- name: ghcr.io/kube-vip/kube-vip
newName: harbor.example.com/library/kube-vip/kube-vip
newTag: v1.0.1
- name: ghcr.io/kube-vip/kube-vip-cloud-provider
newName: harbor.example.com/library/kube-vip/kube-vip-cloud-provider
newTag: v0.0.12
patches:
- target:
kind: DaemonSet
name: kube-vip-ds
namespace: kube-system
patch: |-
apiVersion: apps/v1
kind: DaemonSet
metadata:
name: kube-vip-ds
spec:
template:
spec:
serviceAccountName: kube-vip
nodeSelector:
node-role.kubernetes.io/worker: ""
containers:
- name: kube-vip
env:
- name: vip_interface
value: "ens18"
- name: vip_subnet
value: "16"
volumeMounts:
- mountPath: /etc/kubernetes/admin.conf
$patch: delete
volumes:
- name: kubeconfig
$patch: delete
- target:
kind: ConfigMap
name: kubevip
namespace: kube-system
patch: |-
- op: add
path: /data/range-global
value: "172.20.6.117-172.20.6.120"

驗證 yaml 設定檔是否有誤

kubectl apply -k . --dry-run=server

正確執行結果：

serviceaccount/kube-vip created (server dry run)
serviceaccount/kube-vip-cloud-controller created (server dry run)
clusterrole.rbac.authorization.k8s.io/system:kube-vip-cloud-controller-role created (server dry run)
clusterrole.rbac.authorization.k8s.io/system:kube-vip-role created (server dry run)
clusterrolebinding.rbac.authorization.k8s.io/system:kube-vip-binding created (server dry run)
clusterrolebinding.rbac.authorization.k8s.io/system:kube-vip-cloud-controller-binding created (server dry run)
configmap/kubevip created (server dry run)
Warning: spec.template.spec.affinity.nodeAffinity.preferredDuringSchedulingIgnoredDuringExecution[1].preference.matchExpressions[0].key: node-role.kubernetes.io/master is use "node-role.kubernetes.io/control-plane" instead
deployment.apps/kube-vip-cloud-provider created (server dry run)
daemonset.apps/kube-vip-ds created (server dry run)

部署 kube-vip On-Premises Cloud Controller
```
kubectl apply -k .
```

檢視 kube-vip On-Premises Cloud Controller pods 運作狀態

kubectl -n kube-system get pods -l component=kube-vip-cloud-provider

執行結果：

NAME READY STATUS RESTARTS AGE
kube-vip-cloud-provider-d9b9446b9-6ll6t 1/1 Running 0 45s

檢視 kube-vip ds pods 運作狀態，並確認 pods 只跑在 worker nodes 上

kubectl -n kube-system get pods -l app.kubernetes.io/name=kube-vip-ds -o wide

執行結果：

NAME READY STATUS RESTARTS AGE IP NODE NOMINATED NODE READINESS GATES
kube-vip-ds-kglmc 1/1 Running 0 59s 172.20.6.114 topgun-w1.kubeantony.com <none> <none>
kube-vip-ds-krst5 1/1 Running 0 59s 172.20.6.115 topgun-w2.kubeantony.com <none> <none>
kube-vip-ds-r8cmc 1/1 Running 0 59s 172.20.6.116 topgun-w3.kubeantony.com <none> <none>

4.3. 安裝 Ingress NGINX Controller

切換工作目錄

cd ${HOME}/k8s/addon/ingress/ingress-nginx

編輯 Kustomization File

nano kustomization.yaml

檔案內容如下：

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
#- ./deployment.yaml
- ./daemonSet.yaml
images:
- name: registry.k8s.io/ingress-nginx/controller
newName: harbor.example.com/library/ingress-nginx/controller
newTag: v1.13.3
- name: registry.k8s.io/ingress-nginx/kube-webhook-certgen:v1.6.3
newName: harbor.example.com/library/ingress-nginx/kube-webhook-certgen
newTag: v1.6.3
patches:
- target:
kind: DaemonSet
name: ingress-nginx-controller
patch: |-
apiVersion: apps/v1
kind: DaemonSet
metadata:
name: ingress-nginx-controller
spec:
template:
spec:
nodeSelector:
node-role.kubernetes.io/worker: ""

驗證 yaml 設定檔是否有誤

kubectl apply -k . --dry-run=server

正確執行結果：

namespace/ingress-nginx created (server dry run)
clusterrole.rbac.authorization.k8s.io/ingress-nginx created (server dry run)
clusterrole.rbac.authorization.k8s.io/ingress-nginx-admission created (server dry run)
clusterrolebinding.rbac.authorization.k8s.io/ingress-nginx created (server dry run)
clusterrolebinding.rbac.authorization.k8s.io/ingress-nginx-admission created (server dry run)
ingressclass.networking.k8s.io/nginx created (server dry run)
validatingwebhookconfiguration.admissionregistration.k8s.io/ingress-nginx-admission created (server dry run)
Error from server (NotFound): error when creating ".": namespaces "ingress-nginx" not found
Error from server (NotFound): error when creating ".": namespaces "ingress-nginx" not found
Error from server (NotFound): error when creating ".": namespaces "ingress-nginx" not found
Error from server (NotFound): error when creating ".": namespaces "ingress-nginx" not found
Error from server (NotFound): error when creating ".": namespaces "ingress-nginx" not found
Error from server (NotFound): error when creating ".": namespaces "ingress-nginx" not found
Error from server (NotFound): error when creating ".": namespaces "ingress-nginx" not found
Error from server (NotFound): error when creating ".": namespaces "ingress-nginx" not found
Error from server (NotFound): error when creating ".": namespaces "ingress-nginx" not found
Error from server (NotFound): error when creating ".": namespaces "ingress-nginx" not found
Error from server (NotFound): error when creating ".": namespaces "ingress-nginx" not found
Error from server (NotFound): error when creating ".": namespaces "ingress-nginx" not found

部署 Ingress NGINX Controller
```
kubectl apply -k .
```

檢視 Ingress NGINX Controller pods 運作狀態，並確認是否只在 woker nodes 上執行

kubectl -n ingress-nginx get pods -o wide

執行結果：

NAME READY STATUS RESTARTS AGE IP NODE NOMINATED NODE READINESS GATES
ingress-nginx-controller-4tgxs 1/1 Running 0 90s 10.244.5.109 topgun-w2.kubeantony.com <none> <none>
ingress-nginx-controller-n9t75 1/1 Running 0 67s 10.244.6.115 topgun-w3.kubeantony.com <none> <none>
ingress-nginx-controller-thkd4 1/1 Running 0 44s 10.244.1.190 topgun-w1.kubeantony.com <none> <none>

建立測試目錄
```
mkdir test
```

編輯測試用 deployment

nano test/test-deployment

檔案內容：

apiVersion: apps/v1
kind: Deployment
metadata:
labels:
app: httpd
name: httpd
spec:
replicas: 3
selector:
matchLabels:
app: httpd
strategy: {}
template:
metadata:
labels:
app: httpd
spec:
containers:
- image: harbor.example.com/library/library/busybox:stable
name: busybox
command: ["/bin/sh", "-c"]
args:
- echo haha > /tmp/index.html;
httpd -p 888 -h /tmp -f

編輯 K8s service yaml

nano test/test-svc.yaml

檔案內容：

apiVersion: v1
kind: Service
metadata:
labels:
app: httpd
name: test-svc
spec:
ports:
- port: 80
protocol: TCP
targetPort: 888
selector:
app: httpd

編輯 K8s ingress yaml

nano test/test-ing.yaml

檔案內容：

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: minimal-ingress
spec:
ingressClassName: nginx
rules:
- host: test.k8s.io
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: test-svc
port:
number: 80

部署測試 deployment, service 和 ingress
```
kubectl apply -f test/
```

確認 pods 狀態

kubectl get pods

執行結果：

NAME READY STATUS RESTARTS AGE
httpd-77c9cfcf7d-2tqks 1/1 Running 0 70m
httpd-77c9cfcf7d-4g9fl 1/1 Running 0 70m
httpd-77c9cfcf7d-6w2l2 1/1 Running 0 70m

確認 ingress 有拿到節點的 ip

kubectl get ing

執行結果：

NAME CLASS HOSTS ADDRESS PORTS AGE
minimal-ingress nginx test.k8s.io 172.20.6.114,172.20.6.115,172.20.6.116 80 66m

驗證可以存取網站服務

for i in {114..116}; do time curl -H "Host: test.k8s.io" http://172.20.6.${i};echo ;done

正確執行結果：

haha
real 0m0.006s
user 0m0.003s
sys 0m0.002s
haha
real 0m0.005s
user 0m0.002s
sys 0m0.002s
haha
real 0m0.005s
user 0m0.002s
sys 0m0.001s

Antony 筆記：技術原理與實務經驗 – Antony 筆記：技術原理與實務經驗

Install a kubeadm Kubernetes cluster with Cilium, disabling kube-proxy

Ubuntu 24.04

1. 每一台節點都要做環境準備

裝 K8s

設定 kubeconfig

裝 Cilium

Validate the Installation

跨叢集 CoreDNS AXFR 同步與 PodCIDR 路由設定紀錄

Claude Code Best Practice

AGENTS.md (全域)

洞悉 Cilium 如何傳遞 K8s Pod 網路封包

1. Preface

2. 環境資訊

3. 檢視單一 Pod 的網路架構

小結論

4. 檢視同一台節點內 Pods 之間網路封包如何傳遞

小總結

補充說明

5. 參考文章

CNI 運作原理：理解 Container Network Interface 如何讓跨主機的 Pod 通訊

TL;DR

目錄

目標

0. 前提條件

1. Kubernetes networking model 三條公約

2. Canal 架構快速理解

3. 環境探勘（Podman 特有步驟）

4. 部署 demo workload

5. 第一層觀察：Pod 內看到什麼

6. 第二層觀察：node container 內看到什麼

6.1 Interface 全貌

6.2 Routing 表

6.3 VXLAN forwarding database 與 neighbor

6.4 Calico Felix 的痕跡

7. 第三層觀察：抓真正的 VXLAN 封包

8. Packet flow 圖

MTU mismatch 小提醒

9. 常見驗證 checklist

9.1 node 互通

9.2 podCIDR 是否設置

9.3 flannel 寫好的 subnet

9.4 VXLAN checksum offload（只在懷疑時才下）

10. 收尾

Appendix A. 指令速查表

Appendix B. 術語表

B.1 Linux kernel networking

B.2 Encapsulation 與 overlay 網路

B.3 Kubernetes / CNI 元件

References

資安事件報告 - 內部跳板伺服器遭加密貨幣挖礦惡意程式入侵

1. 事件概要

2. 受影響範圍評估

3. 攻擊時間軸 (Timeline)

4. 威脅指標 (IoCs)

4.1 惡意檔案與 Hash (SHA256)

4.2 系統入侵跡證

4.3 網路與通訊 (Network/C2)

4.4 攻擊者 Vortix DePIN 識別標記 (Tokens)

5. 攻擊手法分析 (MITRE ATT&CK Mapping)

6. 處置與防護建議

6.1 立即止血 (Containment)

6.2 系統重建與憑證輪替 (Eradication & Recovery)

6.3 長期安全強化 (Post-Incident)

Gemini CLI `/init` 異常延遲重現步驟

背景

環境前置條件

一鍵建立 workspace

啟動 CLI(建議開啟 debug log + YOLO 模式)

重現步驟

Step 1 — 完整需求

Step 2 — 確認 plan(第一次)

Step 4 — 要求繁中

Step 5 — 觸發 /init(關鍵卡點 1)

Step 6 — Tool 執行間卡頓(關鍵卡點 2)

Step 7 — 驗證 CLI 是否還活著

觀察重點與紀錄

對照組建議(強烈建議跑)

對照組 A:空目錄獨立 /init

對照組 B:同目錄但全新 session

Step 5 — 觸發 `/init`(關鍵卡點 1)

對照組 A:空目錄獨立 `/init`

第一階段:測試 `serializeImagePulls=false`(平行拉取)