如何搭建 Kubernetes 一站式平台

---

1. 什麼是 Kubernetes / k8s

k8s 也就是 Kubernetes 是一個面向容器化應用的自動化管理平台, 核心職責是管理程序運行的環境, 包括 部署应用/调度资源/维护副本/处理故障/对外暴露服务等等...

對於初學者來說可以把它理解成一個專門管理容器集群的平台, 當你只有一個容器時也許還感覺不到它的必要性

但當你需要同時運行多個服務, 需要讓服務彼此通信, 需要保證應用異常後自動恢復, 甚至需要後續擴容到多台機器時 Kubernetes 的價值就會非常明顯

而本文要做的事情, 就是在一台主機上先搭建一個最小可運行的 Kubernetes 環境, 藉助這個過程去理解 Kubernetes 是怎樣從零開始被組織起來的

為了易讀性, 在這裡會將 Kubernetes 簡稱為 k8s

2. 環境說明

運行 kubeadm 集群建議 control plane 節點至少具備 2 Core CPU 和 2 GiB 運存, 推薦購買搬瓦工的 ECOMMERCE SLA 套餐

• 操作系統以 Debian13 為例
• 主機數量 1 台
• 使用 root 用戶
• 主機承擔 control plane 和 workload 調度
• k8s pod網段為 10.10.0.0/16 , service網段為 192.168.0.0/16
• 使用 Headlamp 管理k8s pods

3. 前置準備

3.1 加載模塊並啟用轉發

cat <<'EOF' | tee /etc/modules-load.d/k8s.conf
overlay
br_netfilter
EOF

modprobe overlay
modprobe br_netfilter

cat <<'EOF' | tee /etc/sysctl.d/k8s.conf
net.bridge.bridge-nf-call-iptables = 1
net.bridge.bridge-nf-call-ip6tables = 1
net.ipv4.ip_forward = 1
net.ipv6.conf.all.forwarding = 1
EOF
sysctl --system

3.2 配置 hosts

tee -a /etc/hosts > /dev/null <<'EOF'
127.0.0.1 k8s-master
EOF

3.3 關閉 swap (可選)

swapoff -a
sed -ri '/\sswap\s/s/^/#/' /etc/fstab

4. 安裝 containerd

更新軟件源並安裝 containerd 與 其他核心組件

apt update
apt install -y containerd apt-transport-https ca-certificates curl gpg

生成默認配置文件並修改配置文件, 這裡為了防止後續可能報錯, 修改了 bin_dir

mkdir -p /etc/containerd
containerd config default | tee /etc/containerd/config.toml > /dev/null
sed -i 's#bin_dir = "/usr/lib/cni"#bin_dir = "/opt/cni/bin"#' /etc/containerd/config.toml
sed -i 's/SystemdCgroup = false/SystemdCgroup = true/' /etc/containerd/config.toml

重啟並設置自啟

systemctl daemon-reload
systemctl restart containerd
systemctl enable containerd
systemctl status containerd

5. 安裝 kubeadm kubelet kubectl

mkdir -p -m 755 /etc/apt/keyrings
curl -fsSL https://pkgs.k8s.io/core:/stable:/v1.35/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:/v1.35/deb/ /' | tee /etc/apt/sources.list.d/kubernetes.list
apt-get update
apt-get install -y kubelet kubeadm kubectl
apt-mark hold kubelet kubeadm kubectl
systemctl enable --now kubelet

檢查

kubeadm version
kubectl version --client
kubelet --version

6. 初始化單節點 k8s 集群

新建一個初始化配置

mkdir -p /main/k8s
nano /main/k8s/kubeadm-config.yaml

粘貼並自行修改配置後進行保存

apiVersion: kubeadm.k8s.io/v1beta4
kind: InitConfiguration
nodeRegistration:
  name: master
  criSocket: "unix:///run/containerd/containerd.sock"
localAPIEndpoint:
  advertiseAddress: <你的公网主机IP>
  bindPort: 6443

---
apiVersion: kubeadm.k8s.io/v1beta4
kind: ClusterConfiguration
kubernetesVersion: v1.35.0
networking:
  podSubnet: 10.10.0.0/16
  serviceSubnet: 192.168.0.0/16
  dnsDomain: cluster.local

# 若开启了Swap需要解除此注释!
#---
#apiVersion: kubelet.config.k8s.io/v1beta1
#kind: KubeletConfiguration
#cgroupDriver: systemd
#failSwapOn: false
#memorySwap:
#  swapBehavior: LimitedSwap

開始初始化

kubeadm init --config /main/k8s/kubeadm-config.yaml

初始化完成後配置 kubectl

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

因為我們是單節點, 需要移除 control plane 污點, 除非多台主機節點

kubectl taint nodes --all node-role.kubernetes.io/control-plane-

檢查

kubectl get nodes
kubectl get pods -A

這時 master 大概率是 NotReady 狀態, 目前 CNI 還沒有安裝, CoreDNS 也通常不會處於 Running 狀態

7. 安裝 Helm並設置補全

安裝 Helm

curl -fsSL -o get_helm.sh https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-4
chmod 700 get_helm.sh
./get_helm.sh
helm version

命令補全:

• zsh

  echo 'source <(kubectl completion zsh)' >> ~/.zshrc
  echo 'source <(helm completion zsh)' >> ~/.zshrc
  source ~/.zshrc
  

• bash

  echo 'source <(kubectl completion bash)' >> ~/.bashrc
  echo 'source <(helm completion bash)' >> ~/.bashrc
  source ~/.bashrc
  

• fish

  kubectl completion fish | sudo tee /etc/fish/completions/kubectl.fish > /dev/null
  helm completion fish | sudo tee /etc/fish/completions/helm.fish > /dev/null
  

8. 安裝 CNI 插件

在資源緊湊的主機中我更推薦使用 Flannel , 這裡也會提供 Calico 與 Cilium 的安裝, 根據應用場景自行選擇其一

資源占用: Flannel < Calico < Cilium

8.1 Flannel

kubectl create namespace kube-flannel
kubectl label namespace kube-flannel --overwrite pod-security.kubernetes.io/enforce=privileged
kubectl label namespace kube-flannel --overwrite pod-security.kubernetes.io/audit=privileged
kubectl label namespace kube-flannel --overwrite pod-security.kubernetes.io/warn=privileged
helm upgrade --install flannel -n kube-flannel --create-namespace --set podCidr=10.10.0.0/16 https://github.com/flannel-io/flannel/releases/download/v0.28.1/flannel.tgz

8.2 Calico

helm repo add projectcalico https://docs.tigera.io/calico/charts
helm repo update
kubectl create namespace tigera-operator
helm upgrade --install calico projectcalico/tigera-operator --version v3.31.4 --namespace tigera-operator --set installation.calicoNetwork.ipPools[0].cidr=10.10.0.0/16 --set installation.calicoNetwork.ipPools[0].encapsulation=VXLAN

8.3 Cilium

helm repo add cilium https://helm.cilium.io/
helm repo update
helm upgrade --install cilium cilium/cilium --version 1.19.1 --namespace kube-system

檢查CNI

kubectl get nodes
kubectl get pods -A

節點狀態從 NotReady 變為 Ready , CoreDNS 進入 Running 狀態, 至此, k8s 已經初步部署完成

9. Headlamp (可選)

9.1 什麼是 Headlamp

Headlamp是一個面向 k8s 的圖形化管理界面, 它的目標是用更直觀的方式幫助用戶查看和管理集群資源, 例如節點/Pod/Deployment/Service/ConfigMap/Secret 等常見對象, 都可以通過 Web 頁面進行瀏覽和操作

它定義為一個易用且可擴展的 Kubernetes WebUI 並強調它既可以作為集群內 Web 應用運行, 也可以作為桌面應用使用, 和很多傳統 Dashboard 相比

Headlamp 的特點主要有三點:

1. 界面更現代 更偏向日常運維與開發使用
2. 它支持基於 Kubernetes RBAC 的權限控制 用戶能看到和操作的資源會自動受當前權限約束
3. 它具備插件擴展能力 可以根據團隊需求定製界面和功能

我個人認為可以幫助初學者擺脫只看命令行輸出的方式, 更直觀地觀察集群中資源的創建/狀態變化/日誌/配置情況, 因此很適合作為 k8s 學習和演示環境中的可視化入口.

9.2 開始安裝

先新建一個 values.yml 文件

mkdir -p /main/k8s/headlamp
nano /main/k8s/headlamp/values.yml

粘貼並自行修改配置後進行保存

replicaCount: 1

image:
  registry: ghcr.io
  repository: headlamp-k8s/headlamp
  tag: ""
  pullPolicy: IfNotPresent

nameOverride: ""
fullnameOverride: "headlamp"
namespaceOverride: ""


service:
  type: NodePort
  port: 80
  # 宿主机开放端口
  nodePort: 30080


env:
  - name: TZ
    value: "Asia/Shanghai"

config:
  pluginsDir: /headlamp/plugins

volumes:
  - name: plugins-volume
    hostPath:
      path: /main/k8s/headlamp/plugins
      type: DirectoryOrCreate

volumeMounts:
  - name: plugins-volume
    mountPath: /headlamp/plugins


resources:
  requests:
    cpu: 100m
    memory: 128Mi
  limits:
    cpu: 500m
    memory: 512Mi

用 Helm 安裝

helm repo add headlamp https://kubernetes-sigs.github.io/headlamp/
helm repo update
helm upgrade --install headlamp headlamp/headlamp -n headlamp --create-namespace -f /main/k8s/headlamp/values.yml

通過開放的端口訪問到 Headlamp, 初次加載需要等待一會, 之後需要輸入 token, 使用命令生成

kubectl create token headlamp --namespace headlamp --duration 168h

若不通則進行檢查

kubectl get nodes
kubectl get pods -A

9.3 查看資源使用概覽

Headlamp中各種資源顯示, 需要依賴 metrics-server

helm repo add metrics-server https://kubernetes-sigs.github.io/metrics-server/
helm repo update
helm upgrade --install metrics-server metrics-server/metrics-server -n kube-system --set "args[0]=--kubelet-insecure-tls"

安裝好後就可以正常顯示資源占用情況

10. 常見問題排查

10.1 Flannel 啟動失敗

優先檢查這幾個點, Flannel 官方 README 明確指出 它依賴 br_netfilter 另外它默認使用 portmap 作為 CNI 網絡插件的一部分 並要求相關 CNI 二進制位於 /opt/cni/bin

10.2 Headlamp 頁面能打開但無法登錄

重點檢查

• token 是否複製完整
• ServiceAccount 是否創建在 kube-system
• ClusterRoleBinding 是否綁定成功
• Headlamp 是否真的暴露成 NodePort

10.3 Pod 無法聯網

重點檢查

• kubeadm init 的 --pod-network-cidr
• Flannel Chart 的 podCidr
• 主機自身網段是否與 Pod 網段衝突

Kubernetes 官方明確提醒 Pod network 不應與宿主機網絡重疊 否則容易出現網絡異常

11. 常用命令

# -------------------------
# 1 集群和命名空间
# -------------------------
kubectl config current-context                               # 查看当前 kubeconfig 上下文
kubectl config get-contexts                                 # 查看所有可用上下文
kubectl config use-context my-cluster                       # 切换到指定集群上下文
kubectl get ns                                              # 查看所有命名空间
kubectl get pods -n kube-system                             # 查看指定命名空间中的 Pod
kubectl config set-context --current --namespace=default    # 设置当前上下文默认命名空间

# -------------------------
# 2 Helm 安装和版本管理
# -------------------------
helm repo add bitnami https://charts.bitnami.com/bitnami    # 添加 Helm 仓库
helm repo update                                            # 更新 Helm 仓库索引
helm search repo nginx                                      # 在 Helm 仓库中搜索 chart
helm install my-nginx bitnami/nginx                         # 安装一个 Helm release
helm install my-nginx bitnami/nginx -n web --create-namespace   # 安装到指定命名空间 不存在则创建
helm install headlamp headlamp/headlamp -n kube-system -f values.yaml   # 使用 values 文件安装 release
helm upgrade headlamp headlamp/headlamp -n kube-system -f values.yaml    # 升级已有 release
helm upgrade --install headlamp headlamp/headlamp -n kube-system -f values.yaml   # 不存在则安装 存在则升级
helm list -A                                                # 查看所有命名空间中的 Helm release
helm status headlamp -n kube-system                         # 查看某个 release 当前状态
helm history headlamp -n kube-system                        # 查看 release 历史版本
helm rollback headlamp 2 -n kube-system                     # 回滚到指定 revision
helm uninstall headlamp -n kube-system                      # 卸载 release
helm show values headlamp/headlamp                          # 查看 chart 默认 values
helm template headlamp headlamp/headlamp -n kube-system -f values.yaml   # 本地渲染模板 不实际安装
helm upgrade --install headlamp headlamp/headlamp -n kube-system -f values.yaml --dry-run   # 试运行安装或升级
helm upgrade --install headlamp headlamp/headlamp -n kube-system -f values.yaml --dry-run --debug   # 试运行并输出详细调试信息

# -------------------------
# 3 常用资源查看
# -------------------------
kubectl get pods                                            # 查看当前命名空间的 Pod
kubectl get pods -o wide                                    # 查看 Pod 并显示节点 IP 等更多信息
kubectl get pods -w                                         # 持续监听 Pod 状态变化
kubectl get deploy                                          # 查看 Deployment
kubectl get svc                                             # 查看 Service
kubectl get ds                                              # 查看 DaemonSet
kubectl get sts                                             # 查看 StatefulSet
kubectl get ingress                                         # 查看 Ingress
kubectl get all -n kube-system                              # 查看命名空间下常见资源
kubectl get pods -l app.kubernetes.io/name=headlamp -n kube-system   # 根据标签筛选 Pod
kubectl get deploy headlamp -n kube-system -o yaml          # 查看 Deployment 的完整 YAML
kubectl get svc headlamp -n kube-system -o wide             # 查看 Service 详细信息

# -------------------------
# 4 排障常用
# -------------------------
kubectl describe pod headlamp-xxx-xxx -n kube-system        # 查看 Pod 详细状态和事件
kubectl describe deploy headlamp -n kube-system             # 查看 Deployment 详细信息
kubectl describe svc headlamp -n kube-system                # 查看 Service 详细信息
kubectl get events -n kube-system --sort-by=.metadata.creationTimestamp   # 按时间排序查看命名空间事件
kubectl get events -A --sort-by=.metadata.creationTimestamp # 查看全局事件并按时间排序
kubectl logs headlamp-xxx-xxx -n kube-system                # 查看 Pod 日志
kubectl logs -f headlamp-xxx-xxx -n kube-system             # 持续跟踪 Pod 日志
kubectl logs headlamp-xxx-xxx -n kube-system -c headlamp    # 查看指定容器日志
kubectl logs headlamp-xxx-xxx -n kube-system --previous     # 查看容器上一次崩溃前日志
kubectl exec -it headlamp-xxx-xxx -n kube-system -- /bin/sh # 进入容器 shell
kubectl exec -it headlamp-xxx-xxx -n kube-system -- /bin/bash   # 进入容器 bash
kubectl get pods -n kube-system                             # 先列出 Pod 再选择进入
kubectl exec -it pod-name -n kube-system -- /bin/sh         # 进入指定 Pod
kubectl top pod -n kube-system                              # 查看 Pod CPU 和内存使用量
kubectl top node                                            # 查看节点资源使用量

# -------------------------
# 5 发布和重启相关
# -------------------------
kubectl rollout restart deploy headlamp -n kube-system      # 滚动重启 Deployment
kubectl rollout status deploy headlamp -n kube-system       # 查看 Deployment 发布状态
kubectl rollout history deploy headlamp -n kube-system      # 查看 Deployment 发布历史
kubectl rollout undo deploy headlamp -n kube-system         # 回滚 Deployment 到上一版本
kubectl scale deploy headlamp --replicas=3 -n kube-system   # 调整副本数
kubectl delete pod headlamp-xxx-xxx -n kube-system          # 删除 Pod 让控制器自动重建

# -------------------------
# 6 网络和端口相关
# -------------------------
kubectl get svc -n kube-system                              # 查看命名空间下 Service
kubectl port-forward pod/headlamp-xxx-xxx 8080:80 -n kube-system   # 将本地 8080 转发到 Pod 的 80
kubectl port-forward svc/headlamp 8080:80 -n kube-system    # 将本地 8080 转发到 Service 的 80
kubectl get endpoints headlamp -n kube-system               # 查看 Service 后端 Endpoint
kubectl run tmp-shell -it --rm --image=busybox -- /bin/sh   # 临时启动调试 Pod
nslookup kubernetes.default                                 # 在调试容器中解析集群 DNS
wget -qO- http://headlamp.kube-system.svc.cluster.local     # 在调试容器中访问集群内部 Service

# -------------------------
# 7 配置和存储相关
# -------------------------
kubectl get configmap -n kube-system                        # 查看 ConfigMap
kubectl get secret -n kube-system                           # 查看 Secret
kubectl get pvc -A                                          # 查看所有 PVC
kubectl get pv                                              # 查看所有 PV
kubectl get nodes -o wide                                   # 查看节点及详细信息
kubectl describe node node-1                                # 查看节点详细状态
kubectl get deploy headlamp -n kube-system -o yaml          # 查看实际生效的 Deployment YAML

# -------------------------
# 8 Helm 配合排障常用
# -------------------------
helm status headlamp -n kube-system                         # 查看 release 当前运行状态
helm get values headlamp -n kube-system                     # 查看用户自定义 values
helm get values headlamp -n kube-system -a                  # 查看合并后的全部 values
helm get manifest headlamp -n kube-system                   # 查看 release 实际渲染出的 manifest
helm get notes headlamp -n kube-system                      # 查看安装说明和访问提示
kubectl get pod headlamp-xxx-xxx -n kube-system --show-labels   # 查看 Pod 标签 判断所属 release
kubectl get all -n kube-system -l app.kubernetes.io/instance=headlamp   # 根据 Helm release 标签筛选整套资源

# -------------------------
# 9 最常用 20 个命令
# -------------------------
kubectl get pods -A                                         # 查看所有命名空间 Pod
kubectl get svc -A                                          # 查看所有命名空间 Service
kubectl get deploy -A                                       # 查看所有命名空间 Deployment
kubectl get all -n kube-system                              # 查看 kube-system 中常见资源
kubectl get pods -o wide -n kube-system                     # 查看 Pod 详细信息
kubectl describe pod pod-name -n kube-system                # 查看 Pod 详情
kubectl describe deploy deploy-name -n kube-system          # 查看 Deployment 详情
kubectl logs pod-name -n kube-system                        # 查看日志
kubectl logs -f pod-name -n kube-system                     # 持续跟踪日志
kubectl logs pod-name -n kube-system --previous             # 查看上一次容器日志
kubectl exec -it pod-name -n kube-system -- /bin/sh         # 进入容器
kubectl get events -n kube-system --sort-by=.metadata.creationTimestamp   # 查看时间排序事件
kubectl port-forward svc/service-name 8080:80 -n kube-system   # 本地端口转发到 Service
kubectl rollout restart deploy deploy-name -n kube-system   # 重启 Deployment
kubectl rollout status deploy deploy-name -n kube-system    # 查看滚动发布状态
kubectl scale deploy deploy-name --replicas=2 -n kube-system   # 调整副本数
helm list -A                                                # 查看所有 Helm release
helm status release-name -n kube-system                     # 查看 release 状态
helm get values release-name -n kube-system -a              # 查看 release 全部 values
helm upgrade --install release-name repo/chart -n kube-system -f values.yaml   # Helm 安装或升级

# -------------------------
# 10 实战排障流程
# -------------------------
helm status headlamp -n kube-system                         # 先检查 release 状态
kubectl get all -n kube-system -l app.kubernetes.io/instance=headlamp   # 查看 release 关联资源
kubectl get pods -n kube-system -o wide                     # 查看 Pod 是否正常运行
kubectl describe pod pod-name -n kube-system                # 检查 Pod 事件和错误
kubectl logs pod-name -n kube-system                        # 查看应用日志
kubectl get svc -n kube-system                              # 查看 Service 是否创建成功
kubectl describe svc headlamp -n kube-system                # 查看 Service 配置详情
kubectl get endpoints headlamp -n kube-system               # 查看 Service 是否关联到后端 Pod
kubectl port-forward svc/headlamp 8080:80 -n kube-system    # 用本地转发验证服务本身是否正常

# -------------------------
# 11 常用别名
# -------------------------
alias k=kubectl                                             # kubectl 简写
alias kgp='kubectl get pods'                                # 快速查看 Pod
alias kgs='kubectl get svc'                                 # 快速查看 Service
alias kgd='kubectl get deploy'                              # 快速查看 Deployment
alias kdp='kubectl describe pod'                            # 快速查看 Pod 详情
alias kdd='kubectl describe deploy'                         # 快速查看 Deployment 详情

12. Helm Chart 配置文件模板

replicaCount: 1                                           # Pod 副本数. 单节点或测试环境常设为 1
revisionHistoryLimit: 10                                  # Deployment 保留的历史版本数. 便于回滚
minReadySeconds: 0                                        # Pod 就绪后保持多久才视为可用

deploymentStrategy:                                       # Deployment 更新策略
  type: RollingUpdate                                     # 推荐 RollingUpdate. Recreate 会先删后建
  rollingUpdate:
    maxUnavailable: 25%                                   # 滚动更新期间最大不可用比例
    maxSurge: 25%                                         # 滚动更新期间可额外创建的副本比例

image:
  registry: ghcr.io                                       # 镜像仓库地址
  repository: headlamp-k8s/headlamp                       # 示例镜像名. 新容器可改为自己的镜像
  tag: ""                                                 # 镜像标签. 留空时通常使用 chart 默认 appVersion
  pullPolicy: IfNotPresent                                # 拉取策略. 常用 IfNotPresent 或 Always

imagePullSecrets: []                                      # 私有仓库拉取密钥. 无需私仓时保持空数组

nameOverride: ""                                          # 覆盖 chart 名称的一部分. 一般不需要
fullnameOverride: "headlamp"                              # 最终资源名. 示例中固定方便管理. 新项目可改
namespaceOverride: ""                                     # 覆盖命名空间. 一般更建议 helm -n 指定

initContainers:                                           # 初始化容器. 在主容器启动前执行
  - name: init-plugin-dir                                 # 初始化容器名称
    image: busybox:1.36                                   # 使用轻量 busybox 镜像
    imagePullPolicy: IfNotPresent                         # initContainer 拉取策略
    command:
      - sh
      - -c
      - mkdir -p /headlamp/plugins && chmod -R 755 /headlamp/plugins   # 创建插件目录并赋权
    securityContext:
      runAsNonRoot: false                                 # 初始化目录时通常允许 root 更省事. 严格环境可改
      allowPrivilegeEscalation: false                     # 禁止提权
    volumeMounts:
      - name: plugins-volume                              # 挂载插件卷以便初始化目录
        mountPath: /headlamp/plugins                      # 容器内插件目录路径

extraContainers: []                                       # 额外 sidecar 容器. 例如日志采集或代理

terminationGracePeriodSeconds: 30                         # 优雅退出宽限期. 过短可能导致连接被硬切断
hostNetwork: false                                        # 是否使用宿主机网络. 一般保持 false
dnsPolicy: ClusterFirst                                   # DNS 策略. hostNetwork=true 时常配 ClusterFirstWithHostNet
dnsConfig: {}                                             # 自定义 DNS 配置. 需模板支持
hostAliases: []                                           # 额外 hosts 映射. 仅少数场景使用

config:
  inCluster: true                                         # 集群内访问模式. Pod 通过 ServiceAccount 访问 K8s API
  inClusterContextName: "main"                            # 集群内上下文名称
  baseURL: ""                                             # 子路径访问时填写如 /headlamp. 根路径保持空
  sessionTTL: 86400                                       # 登录会话有效期. 单位秒. 86400 = 24 小时

  oidc:
    secret:
      create: false                                       # 是否由 chart 自动创建 OIDC Secret
      name: oidc                                          # OIDC Secret 名称
    clientID: ""                                          # OIDC 客户端 ID
    clientSecret: ""                                      # OIDC 客户端密钥
    issuerURL: ""                                         # OIDC 发行者地址
    scopes: ""                                            # OIDC scopes
    callbackURL: ""                                       # OIDC 回调地址
    validatorClientID: ""                                 # Token 校验客户端 ID
    validatorIssuerURL: ""                                # Token 校验发行者地址
    useAccessToken: false                                 # 是否使用 Access Token
    usePKCE: false                                        # 是否启用 PKCE
    useCookie: false                                      # 是否通过 Cookie 保存认证信息
    externalSecret:
      enabled: false                                      # 是否使用外部 Secret
      name: ""                                            # 外部 Secret 名称

  meUserInfoURL: ""                                       # 用户信息接口地址. 未接入外部认证时可留空
  pluginsDir: "/headlamp/plugins"                         # 插件目录
  enableHelm: false                                       # 最新 chart 默认值为 false. 仅需展示 Helm 信息时开启
  watchPlugins: false                                     # 是否实时监听插件目录变化
  extraArgs: []                                           # 额外启动参数. 例如 -plugins-dir=/headlamp/plugins

env:                                                      # 环境变量
  - name: TZ                                              # 时区环境变量名称
    value: "Asia/Shanghai"                                # 时区设置

envFrom: []                                               # 从 ConfigMap 或 Secret 批量导入环境变量. 需模板支持

containerPorts:                                           # 容器端口示例. 需模板支持
  - name: http                                            # 端口名称. 多端口 Service 时建议显式命名
    containerPort: 4466                                   # 容器监听端口. 请按实际应用修改
    protocol: TCP                                         # 协议. 通常 TCP

livenessProbe: {}                                         # 存活探针. K8S 原生支持 exec/httpGet/tcpSocket/grpc. 需模板支持
readinessProbe: {}                                        # 就绪探针. 控制是否加入 Service 端点. 需模板支持
startupProbe: {}                                          # 启动探针. 慢启动应用推荐配置. 需模板支持
lifecycle: {}                                             # 生命周期钩子. preStop/postStart. 需模板支持

automountServiceAccountToken: true                        # 自动挂载 ServiceAccount Token. 集群内访问通常保持 true

serviceAccount:
  create: true                                            # 是否自动创建 ServiceAccount
  annotations: {}                                         # ServiceAccount 注解
  name: ""                                                # 最新 chart 默认空字符串. 留空时一般按 fullname 生成

clusterRoleBinding:
  create: true                                            # 是否自动创建 ClusterRoleBinding
  clusterRoleName: "cluster-admin"                        # 示例使用 cluster-admin. 生产环境建议改成最小权限角色
  annotations: {}                                         # ClusterRoleBinding 注解

deploymentAnnotations: {}                                 # Deployment 注解
podAnnotations:                                           # Pod 注解. 可用于 sidecar 注入 监控抓取等
  kubectl.kubernetes.io/default-container: "headlamp"     # kubectl exec/logs 默认容器提示. 非必须但更顺手

podLabels:
  app.kubernetes.io/name: "headlamp"                      # 推荐使用标准标签
  app.kubernetes.io/component: "web"                      # 组件标签. 便于筛选和治理

hostUsers: true                                           # Pod 是否共享宿主用户命名空间. 设 false 可启用 user namespaces

podSecurityContext:
  fsGroup: 101                                            # 卷文件组 ID. 便于挂载目录权限控制
  fsGroupChangePolicy: OnRootMismatch                     # 新版常用项. 仅在需要时递归改卷权限
  seccompProfile:
    type: RuntimeDefault                                  # 推荐使用运行时默认 seccomp 配置

securityContext:
  runAsNonRoot: true                                      # 强制非 root 运行
  privileged: false                                       # 不使用特权模式
  runAsUser: 100                                          # 容器运行用户 UID
  runAsGroup: 101                                         # 容器运行用户组 GID
  allowPrivilegeEscalation: false                         # 禁止提权
  readOnlyRootFilesystem: false                           # 需要更强约束时可设 true 并配 writable 卷
  capabilities:
    drop:
      - ALL                                               # 建议默认移除全部 Linux capabilities

service:
  annotations: {}                                         # Service 注解
  type: NodePort                                          # 暴露方式. 可选 ClusterIP / NodePort / LoadBalancer
  port: 80                                                # Service 端口
  targetPort: http                                        # 目标端口. 建议引用命名端口便于变更
  appProtocol: http                                       # 应用层协议提示. v1.20 稳定
  clusterIP: ""                                           # ClusterIP 一般不手动指定
  # loadBalancerIP: ""                                    # 该字段自 v1.24 起已废弃. 新环境不建议再依赖
  loadBalancerSourceRanges: []                            # 限制允许访问的来源网段
  nodePort: 30080                                         # NodePort 固定端口. 浏览器可通过 NodeIP:30080 访问
  externalTrafficPolicy: Cluster                          # 对外流量策略. Local 可保留客户端源 IP
  internalTrafficPolicy: Cluster                          # 集群内流量策略. v1.26 稳定. Local 可优先本地端点
  sessionAffinity: None                                   # 会话亲和性. 可选 None / ClientIP
  sessionAffinityConfig: {}                               # 会话亲和性高级配置. 需按需填写
  ipFamilyPolicy: SingleStack                             # 可选 SingleStack / PreferDualStack / RequireDualStack
  ipFamilies: []                                          # 双栈时可写 [IPv4, IPv6] 或 [IPv6, IPv4]
  trafficDistribution: PreferSameZone                     # v1.33 稳定. v1.35 支持 PreferSameZone / PreferSameNode

volumeMounts:
  - name: plugins-volume                                  # 插件卷名称
    mountPath: /headlamp/plugins                          # 容器内挂载路径

  # - name: kubeconfig-volume                             # 可选 kubeconfig 卷名称
  #   mountPath: /home/headlamp/.config/Headlamp/kubeconfigs/config   # 容器内 kubeconfig 文件路径
  #   subPath: config                                     # 将卷中的 config 文件挂载为单文件

volumes:
  - name: plugins-volume                                  # 卷名称. 需与 volumeMounts 对应
    hostPath:
      path: /data/headlamp/plugins                        # 宿主机目录. 等价于 Docker 左侧路径
      type: DirectoryOrCreate                             # 不存在时自动创建目录

  # - name: kubeconfig-volume                             # 可选 kubeconfig 卷
  #   hostPath:
  #     path: /data/headlamp/kubeconfigs                  # 宿主机 kubeconfig 所在目录
  #     type: DirectoryOrCreate                           # 不存在时自动创建

persistentVolumeClaim:
  enabled: false                                          # 是否改用 PVC 持久化. 使用 hostPath 时通常设 false
  annotations: {}                                         # PVC 注解
  accessModes: []                                         # PVC 访问模式. 如 ReadWriteOnce
  size: ""                                                # PVC 大小. 如 5Gi
  storageClassName: ""                                    # 存储类名称
  selector: {}                                            # PVC 选择器
  volumeMode: ""                                          # 卷模式. 如 Filesystem / Block
  dataSource: {}                                          # 高级项. 可从快照或现有卷克隆. 需模板支持

ingress:
  enabled: false                                          # 是否启用 Ingress
  annotations: {}                                         # Ingress 注解
  labels: {}                                              # Ingress 标签
  ingressClassName: ""                                    # IngressClass 名称. 替代旧注解 kubernetes.io/ingress.class
  hosts: []                                               # 域名和路径配置
  tls: []                                                 # TLS 配置

httpRoute:
  enabled: false                                          # 是否启用 Gateway API 的 HTTPRoute
  annotations: {}                                         # HTTPRoute 注解
  labels: {}                                              # HTTPRoute 标签
  parentRefs: []                                          # 关联 Gateway. 启用时通常必填
  hostnames: []                                           # 绑定域名
  rules: []                                               # 路由规则. 未配置时通常走默认前缀路由

resources:                                                # 资源请求与限制
  requests:
    cpu: "100m"                                           # 最低 CPU 请求
    memory: "128Mi"                                       # 最低内存请求
  limits:
    cpu: "500m"                                           # CPU 上限
    memory: "512Mi"                                       # 内存上限

nodeSelector:
  kubernetes.io/os: linux                                 # 仅调度到 Linux 节点

tolerations: []                                           # 容忍污点. 无特殊需求可留空
affinity: {}                                              # 亲和性规则. 无特殊需求可留空
topologySpreadConstraints:                                # 拓扑分布约束. 新版 K8S 常用高可用配置
  # - maxSkew: 1                                           # 单个拓扑域允许的最大偏斜
  #   topologyKey: topology.kubernetes.io/zone             # 按可用区分布. 也可用 kubernetes.io/hostname
  #   whenUnsatisfiable: ScheduleAnyway                    # 可选 DoNotSchedule / ScheduleAnyway
  #   labelSelector:
  #     matchLabels:
  #       app.kubernetes.io/name: headlamp                # 选取同类 Pod
  #   matchLabelKeys:                                      # v1.27 起 Beta. 可按 Pod 标签键自动匹配
  #     - pod-template-hash
  #   nodeAffinityPolicy: Honor                            # v1.26 起 Beta. 可选 Honor / Ignore
  #   nodeTaintsPolicy: Ignore                             # v1.26 起 Beta. 可选 Honor / Ignore
  []

priorityClassName: ""                                     # 优先级类名称
runtimeClassName: ""                                      # 运行时类. 如 gvisor kata 等. 需模板支持

pluginsManager:
  enabled: false                                           # 是否启用插件管理 sidecar
  configFile: "plugin.yml"                                # 插件配置文件名
  configContent: ""                                       # 插件配置内容
  baseImage: node:lts-alpine                               # 插件管理器基础镜像
  version: latest                                          # 插件管理器版本
  volumeMounts: []                                         # 插件管理器额外挂载
  securityContext: {}                                      # 插件管理器安全上下文

podDisruptionBudget:
  enabled: false                                           # 是否启用 PDB
  minAvailable: 0                                          # 最少可用副本数
  maxUnavailable: null                                     # 最大不可用副本数
  unhealthyPodEvictionPolicy: null                         # 不健康 Pod 驱逐策略. 新集群可按需设置

extraManifests: []                                         # 附加资源清单. 可内嵌额外 K8s YAML