Minikube 集群配置文件详解（Ubuntu 22.04）

目标：深入解析 minikube v1.39.0 在 Ubuntu 22.04 上的配置体系——全局配置 ~/.minikube/config/config.json、集群 profile 配置 ~/.minikube/profiles/minikube/config.json（Driver / KicBaseImage / Memory / CPUs / DiskSize / KubernetesConfig / Nodes / Addons 等字段）以及节点内 kubeadm.yaml / kubelet config.yaml / containerd config.toml 关键项的含义、取值范围、默认值与修改方法，并给出可直接落地的生产配置模板，以及 minikube start 启动参数到配置字段的映射。文中配置与回显在 Ubuntu 22.04.5 LTS + minikube v1.39.0 + Kubernetes v1.37.0 实测通过。

一、环境信息

• 操作系统：Ubuntu 22.04.5 LTS / x86_64（内核 6.8.0-138-generic）
• minikube：v1.39.0（commit 7a9f6a841470a207de8cf4bafcccee0969d8ba10）
• kubectl：v1.37.0（Kustomize v5.8.1）；Kubernetes：v1.37.0
• 驱动：docker；节点承载基础镜像 kicbase v0.0.51；节点内运行时 containerd 2.3.4
• 集群：单节点 control-plane，节点名 minikube，节点 IP 192.168.49.2，apiserver 端口 8443
• 全局配置：~/.minikube/config/config.json；profile 配置：~/.minikube/profiles/minikube/config.json
• 节点内配置：/var/tmp/minikube/kubeadm.yaml、/var/lib/kubelet/config.yaml、/etc/containerd/config.toml
• 示例账号：root（示例密码 q1w2e3r4）

二、配置文件一览与生成方式

minikube 的配置分三层：CLI 全局默认值、集群 profile 配置、节点内引导配置。三者关系为「全局默认 → profile 固化（启动时写入）→ 节点内展开」。

查看 profile 配置文件：

cat ~/.minikube/profiles/minikube/config.json

💡 profile 配置只在 minikube start 时按命令行参数固化一次；修改资源配置（CPU/内存/磁盘）需 minikube delete 后用新参数重建，或在 minikube start 时传入新值由 minikube 更新 profile。

三、配置查看与修改方式

3.1 查看当前生效配置

查看全局配置（minikube config set 写入项）：

minikube config view

查看 profile 全量配置：

cat ~/.minikube/profiles/minikube/config.json

查看 profile 汇总（等价于配置的「视图」）：

minikube profile list

实测回显：

┌──────────┬────────┬────────────┬──────────────┬─────────┬────────┬───────┬────────────────┬────────────────────┐
│ PROFILE  │ DRIVER │  RUNTIME   │      IP      │ VERSION │ STATUS │ NODES │ ACTIVE PROFILE │ ACTIVE KUBECONTEXT │
├──────────┼────────┼────────────┼──────────────┼─────────┼────────┼───────┼────────────────┼────────────────────┤
│ minikube │ docker │ containerd │ 192.168.49.2 │ v1.37.0 │ OK     │ 1     │ *              │ *                  │
└──────────┴────────┴────────────┴──────────────┴─────────┴────────┴───────┴────────────────┴────────────────────┘

3.2 修改方式

• 全局默认值：minikube config set <字段> <值>（写入 ~/.minikube/config/config.json，对新建 profile 生效）；
• 启动参数：minikube start --<参数>=<值>（写在命令上，固化到 profile）；
• profile 配置：编辑 ~/.minikube/profiles/minikube/config.json 后需 minikube delete 重建使改动完全生效；
• 节点内配置：minikube ssh 进入节点后按需修改，重启对应服务（如 containerd）。

示例（设置全局默认驱动与资源，再重建集群）：

minikube config set driver docker
minikube config set cpus 2
minikube config set memory 2200
minikube delete
minikube start

⚠️ 节点内配置（/etc/containerd/config.toml 等）由 minikube 在每次 minikube start 时按 profile 重新下发，手工改动在集群重建后会被覆盖；持久化改动应通过 profile 配置或自定义基础镜像实现。

3.3 修改后验证命令与预期结果

minikube start
kubectl get nodes -o wide

预期结果（Ubuntu 22.04 实测回显）：

NAME       STATUS   ROLES    AGE   VERSION   INTERNAL-IP    EXTERNAL-IP   OS-IMAGE                         KERNEL-VERSION              CONTAINER-RUNTIME
minikube   Ready    <none>   15m   v1.37.0   192.168.49.2   <none>        Debian GNU/Linux 12 (bookworm)   6.8.0-138-generic (amd64)   containerd://2.3.4

💡 节点 Ready、CONTAINER-RUNTIME 为 containerd://2.3.4、minikube profile list 的 DRIVER/RUNTIME/NODES 与配置一致，即视为配置生效。

四、配置结构与参数总览

本环境实测的 profile 配置（~/.minikube/profiles/minikube/config.json）关键字段：

{
	"Name": "minikube",
	"KeepContext": false,
	"KicBaseImage": "gcr.io/k8s-minikube/kicbase:v0.0.51",
	"Memory": 2200,
	"CPUs": 2,
	"DiskSize": 20000,
	"Driver": "docker",
	"APIServerPort": 8443,
	"SSHUser": "root",
	"SSHPort": 22,
	"KubernetesConfig": {
		"KubernetesVersion": "v1.37.0",
		"ClusterName": "minikube",
		"Namespace": "default",
		"APIServerName": "minikubeCA",
		"DNSDomain": "cluster.local",
		"ContainerRuntime": "containerd",
		"NetworkPlugin": "cni",
		"ServiceCIDR": "10.96.0.0/12",
		"ImageRepository": "registry.cn-hangzhou.aliyuncs.com/google_containers",
		"ShouldLoadCachedImages": true,
		"EnableDefaultCNI": false,
		"CNI": "bridge"
	},
	"Nodes": [
		{
			"Name": "",
			"IP": "192.168.49.2",
			"Port": 8443,
			"KubernetesVersion": "v1.37.0",
			"ContainerRuntime": "containerd",
			"ControlPlane": true,
			"Worker": true
		}
	],
	"Addons": {
		"default-storageclass": true,
		"storage-provisioner": true
	},
	"BinaryMirror": "https://dl.k8s.io/release",
	"Mount9PVersion": "9p2000.L",
	"MountType": "9p",
	"AutoPauseInterval": 60000000000
}

参数总览（功能域）：

五、核心配置详解

5.1 顶层资源与驱动字段

修改方法：用 minikube start --cpus=4 --memory=4096 --disk-size=30000 覆盖，或 minikube config set cpus 4 设全局默认；资源类改动须 minikube delete 后重建才完全生效。

5.2 KubernetesConfig：Kubernetes 引导参数

• KubernetesVersion 由 minikube start --kubernetes-version 指定，默认 stable；
• ContainerRuntime 由 -c/--container-runtime 指定，默认 auto（docker 驱动下自动选 containerd）；
• ImageRepository 由 --image-mirror-country=cn 自动推导为阿里云镜像仓库；
• CNI 为 --cni 参数值，本环境集群实际采用 bridge 插件。

⚠️ ContainerRuntime 一旦确定不可通过 minikube start 原地切换，须 minikube delete 后用新运行时重建。

5.3 Nodes：节点定义

"Nodes": [
	{
		"Name": "",
		"IP": "192.168.49.2",
		"Port": 8443,
		"KubernetesVersion": "v1.37.0",
		"ContainerRuntime": "containerd",
		"ControlPlane": true,
		"Worker": true
	}
]

• 单节点模式下 ControlPlane 与 Worker 均为 true（控制平面同时承载负载，不设控制平面污点）；
• 追加节点用 minikube node add（生成 worker 节点），minikube node list 查看；
• 节点 IP 可在 minikube start --subnet=<网段> 或 --static-ip=<IP> 调整（docker/podman 驱动）。

5.4 Addons：启用的附加组件

"Addons": {
	"default-storageclass": true,
	"storage-provisioner": true
}

• 由 minikube start --addons=<名>[,<名>...] 或 minikube addons enable <名> 启用；
• minikube addons list 查看全部 addon 与状态；
• 本环境集群实测默认启用上述两项，kubectl get pods -A 中可见 storage-provisioner 运行。

5.5 网络与镜像源字段

💡 本环境通过 --image-mirror-country=cn 将组件镜像切到阿里云仓库，ImageRepository 字段即反映该值；业务镜像（如 nginx:alpine）若拉取慢，用 minikube image load 从本机导入，或配置 --registry-mirror。

5.6 节点内 kubeadm.yaml

minikube 在节点内生成 /var/tmp/minikube/kubeadm.yaml（minikube ssh 查看）。实测关键段：

apiVersion: kubeadm.k8s.io/v1beta4
kind: InitConfiguration
localAPIEndpoint:
  advertiseAddress: 192.168.49.2
  bindPort: 8443
bootstrapTokens:
  - groups:
      - system:bootstrappers:kubeadm:default-node-token
    ttl: 24h0m0s
    usages:
      - signing
      - authentication
nodeRegistration:
  criSocket: unix:///run/containerd/containerd.sock
  name: "minikube"
  kubeletExtraArgs:
    - name: "node-ip"
      value: "192.168.49.2"
  taints: []
---
apiVersion: kubeadm.k8s.io/v1beta4
kind: ClusterConfiguration
imageRepository: registry.cn-hangzhou.aliyuncs.com/google_containers
apiServer:
  certSANs: ["127.0.0.1", "localhost", "192.168.49.2"]
certificatesDir: /var/lib/minikube/certs
clusterName: mk
controlPlaneEndpoint: control-plane.minikube.internal:8443
etcd:
  local:
    dataDir: /var/lib/minikube/etcd
kubernetesVersion: v1.37.0
networking:
  dnsDomain: cluster.local
  podSubnet: "10.244.0.0/16"
  serviceSubnet: 10.96.0.0/12

💡 controlPlaneEndpoint: control-plane.minikube.internal:8443 为 minikube 内部服务名；etcd.dataDir 与 certificatesDir 均位于 /var/lib/minikube/ 下，随节点数据持久化。

5.7 节点内 kubelet config.yaml

节点内 /var/lib/kubelet/config.yaml 实测关键段：

apiVersion: kubelet.config.k8s.io/v1beta1
kind: KubeletConfiguration
authentication:
  anonymous:
    enabled: false
  webhook:
    enabled: true
authorization:
  mode: Webhook
cgroupDriver: systemd
clusterDNS:
- 10.96.0.10
clusterDomain: cluster.local
containerRuntimeEndpoint: unix:///run/containerd/containerd.sock
evictionHard:
  imagefs.available: 0%
  nodefs.available: 0%
  nodefs.inodesFree: 0%
failSwapOn: false
imageGCHighThresholdPercent: 100
runtimeRequestTimeout: 15m0s
staticPodPath: /etc/kubernetes/manifests

💡 minikube 默认关闭磁盘资源驱逐（evictionHard 全 0%、imageGCHighThresholdPercent: 100）、允许 swap（failSwapOn: false），以适配本地开发环境的资源自由度；cgroupDriver: systemd 与 containerd SystemdCgroup 保持一致。

5.8 节点内 containerd config.toml

节点内 /etc/containerd/config.toml 实测关键段（本环境为适配受限内核将快照器设为 native）：

version = 4
root = '/var/lib/containerd'
state = '/run/containerd'

[plugins.'io.containerd.cri.v1.images']
    snapshotter = 'native'
    [plugins.'io.containerd.cri.v1.images'.pinned_images]
      sandbox = 'registry.cn-hangzhou.aliyuncs.com/google_containers/pause:3.10.2'
    [plugins.'io.containerd.cri.v1.images'.registry]
      config_path = ''

[plugins.'io.containerd.cri.v1.runtime'.containerd.runtimes.runc.options]
    SystemdCgroup = true

[plugins.'io.containerd.server.v1.grpc']
    address = '/run/containerd/containerd.sock'

💡 该文件由 minikube 在 minikube start 时按 profile 生成，手工修改后需 systemctl restart containerd 生效，且会在集群重建时被覆盖。

5.9 全局配置 minikube config

minikube config 读写 ~/.minikube/config/config.json，作为「全局默认值」。可配置字段（minikube config --help 回显节选）：

config modifies minikube config files using subcommands like "minikube config set driver kvm2"

 * driver
 * container-runtime
 * cpus
 * memory
 * kubernetes-version
 * insecure-registry

示例：

minikube config set driver docker
minikube config get driver
minikube config view
minikube config unset driver

💡 全局配置对之后新建的 profile 生效；已存在 profile 的取值固化在其 profiles/<名>/config.json 中，不受全局配置后续改动影响。

六、生产环境配置模板

6.1 生产形态说明

适用场景：16GB 内存、SSD 磁盘的本地开发/测试服务器，单节点集群承载日常开发与联调；通过启动参数一次性固化 profile 配置。

minikube start \
  --driver=docker \
  --container-runtime=containerd \
  --cpus=2 \
  --memory=2200mb \
  --disk-size=20000mb \
  --kubernetes-version=v1.37.0 \
  --image-mirror-country=cn \
  --binary-mirror=https://dl.k8s.io/release \
  --wait-timeout=10m

对应固化的关键字段：

6.2 全局配置持久化模板

若希望服务器上所有新建集群都沿用默认值，可先将默认项写入全局配置：

minikube config set driver docker
minikube config set container-runtime containerd
minikube config set cpus 2
minikube config set memory 2200
minikube config set kubernetes-version v1.37.0
minikube config view

💡 生产要点：driver / container-runtime / 资源类默认值按服务器规格设置；改动资源类默认值后，已存在的 profile 需 minikube delete 重建才生效；kubernetes-version 建议显式锁定版本以便复现。

七、常见问题（FAQ）

Q1：修改了 profile 配置或全局配置，为什么集群没有变化？

定位：profile 配置只在 minikube start 时固化；全局配置只对新建 profile 生效。

解决：资源/运行时类改动须 minikube delete 后用新参数重建；仅 Kubernetes 版本可用 minikube start --kubernetes-version=<版本> 触发重新引导。

Q2：节点内 /etc/containerd/config.toml 手工改的配置生效后又丢了？

定位：节点内配置由 minikube 每次 minikube start 按 profile 重新下发，重启/重建会被覆盖。

解决：持久化需求应通过 profile 配置、--registry-mirror 等启动参数，或自定义基础镜像（--base-image）实现；临时改动在当次运行内有效，改完 systemctl restart containerd。

Q3：CNI 字段为 bridge 是什么含义？

定位：KubernetesConfig.CNI 为 minikube 选定并固化的 CNI 插件名。

解决：bridge 表示集群使用 bridge CNI 插件（网络桥接，配套 CNI 配置文件名为 1-k8s.conflist）；kubectl get pods -A 中 kube-proxy 与系统组件均正常，业务 Pod 网络连通（nginx-demo NodePort 实测 HTTP 200）。

Q4：如何调整节点内存/磁盘（YAML 编辑还是命令）？

定位：资源类字段以启动参数为准，不建议直接编辑 profile config.json。

解决：用 minikube start --memory=<MB> --cpus=<核> --disk-size=<MB> 覆盖；磁盘只能增大不能缩小，缩小须重建集群。

Q5：快照器为什么是 native，能否改回 overlayfs？

定位：受限内核环境中 overlayfs 快照器挂载受限，minikube 实例化时切到 native 以稳定运行。

解决：物理服务器（支持 overlayfs）无需该调整；如需改回，可在节点内将 containerd snapshotter 设为 overlayfs 并重启 containerd 验证挂载能力，或在自定义基础镜像中固定。

八、参考链接

• minikube 配置参考：https://minikube.sigs.k8s.io/docs/handbook/config/
• minikube 命令参考（start/config）：https://minikube.sigs.k8s.io/docs/commands/start/
• minikube 官方文档：https://minikube.sigs.k8s.io/docs/
• kubeadm 配置 API（v1beta4）：https://kubernetes.io/docs/reference/config-api/kubeadm-config.v1beta4/
• kubelet 配置参考：https://kubernetes.io/docs/reference/config-api/kubelet-config.v1beta1/