Lazy loaded image
运维管理
通过 minikube 入门 k8s 集群
Words 2623Read Time≈ 7 min
2025-10-6
2025-11-10
date
related_level
slug
k8s_minikube
type
Post
relate_date
summary
minikube 安装与使用指南，涵盖启动配置、镜像管理、服务部署、Ingress 应用及常见问题排查
status
Published
tags
k8s
调试
category
运维管理
last_updated
Nov 10, 2025 10:02 PM
是否已更新
orginal_page
是否推荐
 

debian/ubuntu 安装 minikube

安装需求
  • 2 CPUs or more
  • 2GB of free memory
  • 20GB of free disk space
  • Internet connection
ubuntu 安装 deb 包
 

使用 minikube

使用代理需要在启动前添加对应 HTTP_PROXY, HTTPS_PROXY, NO_PROXY 变量
  • unset HTTP_PROXY && unset HTTPS_PROXY && unset NO_PROXY
    • 取消代理
启动 minikube
  • minikube start --kubernetes-version=v1.23.8 --image-mirror-country='cn' --image-repository='registry.cn-hangzhou.aliyuncs.com/google_containers'
    • 需要  --kubernetes-version=v1.23.8 指定下载老版本，否则默认下载最新版本，可能失败
可以在 minikube 里下载安装使用 kubectl
  • minikube kubectl -- get po -A
  • 通过设置别名来简化
    • vim ~/.zshrc
      • alias kubectl="minikube kubectl --"
      • 其余 shell 根据配置文件来
  • 查看仪表盘 minikube dashboard
  • 查看易于安装的 Kubernetes 服务目录 minikube addons list
部分镜像由于 registry.cn-hangzhou.aliyuncs.com 位置与官方不一致，需要手动拉取
  • docker images -a
  • 以 kube-webhook-certgen:v1.4.3 为例
    • IMAGE_VERSION="kube-webhook-certgen:v1.4.3"
    • docker pull registry.cn-hangzhou.aliyuncs.com/google_containers/$IMAGE_VERSION
      • docker images --digests
      • minikube image load registry.cn-hangzhou.aliyuncs.com/google_containers/$IMAGE_VERSION
    • docker tag registry.cn-hangzhou.aliyuncs.com/google_containers/$IMAGE_VERSION registry.cn-hangzhou.aliyuncs.com/google_containers/k8s-minikube/$IMAGE_VERSION
      • 添加 tag
    • minikube image load registry.cn-hangzhou.aliyuncs.com/google_containers/k8s-minikube/$IMAGE_VERSION
kubectl 更改插件镜像源
  • minikube addons images ingress
    • 查看镜像情况
  • kubectl get pods -n ingress-nginx
  • kubectl edit deployment ingress-nginx-controller -n ingress-nginx
    • 修改 container 项下的 image 地址
 

minikube 内部署应用和服务

部署应用和服务
  • kubectl create deployment hello-minikube --image=kicbase/echo-server:1.0
  • kubectl expose deployment hello-minikube --type=NodePort --port=8080
    • --type=NodePort 指定服务的类型为 NodePort
      • 在每个 Kubernetes 节点的指定端口上暴露服务，允许外部用户通过 <NodeIP>:<NodePort> 的形式访问该服务
    • --port=8080 暴露端口 8080
  • kubectl get services hello-minikube
    • 列出指定服务的基本信息
  • minikube service hello-minikube
    • 直接访问服务
  • 使用kubectl 转发端口 7080:8080
    • kubectl port-forward service/hello-minikube 7080:8080
    • 此时访问 http://localhost:7080/ 即可
部署具有负载均衡的服务和应用
  • kubectl create deployment balanced --image=kicbase/echo-server:1.0
  • kubectl expose deployment balanced --type=LoadBalancer --port=8080
    • --type=LoadBalancer 创建一个外部负载均衡器
      • 需要 Kubernetes 集群的环境支持，比如运行在云服务提供商的集群上
    • --port=8080 暴露端口 8080
  • minikube tunnel
    • 启用负载均衡模拟功能，分配一个外部 IP 地址供本地访问服务
  • kubectl get services balanced
    • 列出指定服务的基本信息
    • 结合获取 EXTERNAL-IP 列中的地址即可访问
通过 ingress 部署服务和应用
  • minikube addons enable ingress
    • 启用插件
vim ingress-example.yaml
  • 或者直接下载
    • curl -O https://storage.googleapis.com/minikube-site-examples/ingress-example.yaml
  • 部署两个简单的 HTTP 应用，分别通过服务 foo-service 和 bar-service 暴露
  • 使用 Ingress 实现基于路径的路由
    • 访问 /foo 路径时，流量转发到 foo-service，最终到达 foo-app Pod
    • 访问 /bar 路径时，流量转发到 bar-service，最终到达 bar-app Pod
  • kubectl apply -f ingress-example.yaml
    • 使用配置文件部署应用和服务
  • kubectl get ingress
    • 获取 ingress 暴露的外部地址，见 ADDRESS 列
curl <ip>/foo
  • <ip> 为上面 kubectl get ingress 返回的 ADDRESS 列地址
  • 输出如下
curl <ip>/bar
  • <ip> 为上面 kubectl get ingress 返回的 ADDRESS 列地址
  • 输出如下
  • kubectl delete -f ingress-example.yaml
    • 删除对应应用和服务
  • 停止运行 minikube 集群
    • minikube stop
  • 删除 minikube 集群
    • minikube delete --all
 

管理 minikube 集群

使用 kubectl 与 minikube 集群交互
  • 需要安装 kubectl
  • kubectl get pods -A
  • kubectl logs <pod-name>
    • <pod-name> 替换为上面输出的 Pod 实际名称
  • kubectl get deployments
    • 查看部署
  • kubectl get services
    • 查看服务
  • kubectl get events
  • kubectl config view
    • 查看 kubectl 配置
  • kubectl delete service <service-name>
  • kubectl delete deployment <deployment-name>
创建新集群或升级已有集群
  • minikube start -p aged --kubernetes-version=v1.16.1
    • 创建运行于旧版本 Kubernetes 的第二个集群 aged
  • minikube start --kubernetes-version=latest
    • 升级集群
修改配置
  • minikube config --help
    • 查看可配置项
  • minikube config view
    • 查看现有配置
  • minikube config set memory 9001
    • 更改默认内存限制，需要重启
使用自签证书
假设已创建了 .PEM 格式的 X.509 根证书 my_company.pem
  • 如果是 .DER 需要转换
  • openssl x509 -inform der -in my_company.cer -out my_company.pem
  • mkdir -p $HOME/.minikube/certs
  • cp my_company.pem $HOME/.minikube/certs/my_company.pem
  • minikube start --embed-certs
    • 启动时指定包含自签证书
暂停 Kubernetes 而不影响已部署的应用
  • minikube pause
  • minikube unpause
挂载文件系统（MountingFilesystems）和持久物理卷（PV, PersistentVolume）
  • 9P Mounts 可以在所有管理程序上工作，但在与大型文件夹（>600个文件）一起使用时会出现性能和可靠性问题
    • minikube mount <source directory>:<target directory>
      • 后续可以在 manifest 中引用
      • minikube mount $HOME:/host
  • Driver mounts 可靠且性能良好，但路径在操作系统或管理程序之间是不可预测的
定义 PV 持久物理卷的样例 pv0001
images 镜像管理
services 服务管理
访问 NodePort 服务
  • minikube service <service-name> --url
    • 直接获取
      • 如果是在 Darwin, Windows, WSL 上的 docker 驱动运行，网络将会受限且不可直接访问 Node IP，需要通过隧道（tunnel）访问，此时需要维持该指令
      • minikube service <service-name> --url 运行程序创建隧道
  • kubectl get service <service-name> --output='jsonpath="{.spec.ports[0].nodePort}"'
    • 通过 kubectl 获取
增加 NodePort 端口范围
  • 默认范围在 30000-32767
  • minikube start --extra-config=apiserver.service-node-port-range=1-65535
访问 LoadBalancer 服务
  • 在另一窗口创建隧道，将外部IP直接暴露给主机操作系统上运行的任何程序
    • minikube tunnel
    • minikube 隧道作为一个进程运行，使用集群的IP地址作为网关，在主机上创建到集群服务CIDR的网络路由
  • 清理由于崩溃而导致的孤立网络路由
    • minikube tunnel --cleanup
    从 pod 访问宿主机 host.minikube.internal
    • 服务必须绑定到 0.0.0.0 等全 IP 和接口，而非 127.0.0.1 等 localhost
    • minikube ssh
      • 进入集群内部
    • ping host.minikube.internal
    • nc -vz host.minikube.internal 8000
      • 测试特定 tcp 服务监听端口
    addons 插件管理
    • minikube addons enable <name1>
      • 启用插件
    • minikube start --addons <name1> --addons <name2>
      • 开始时启用插件
    • minikube addons disable <name1>
      • 禁用插件
    配置插件使用定制镜像仓库和镜像
    • 假设使用本地镜像仓库 192.168.10.2:5555 以替代 registry.k8s.io
    • 查看插件镜像
      • minikube addons images efk
    • 加载本地镜像至 minikube
      • minikube cache add kibana/kibana:5.6.2-custom
    • 使用 --images, --registries 选项指定镜像和镜像仓库
      • 格式 IMAGE_NAME=CUSTOM_VALUE
      • minikube addons enable efk --images="Kibana=kibana/kibana:5.6.2-custom" --registries="Kibana=,Elasticsearch=192.168.10.2:5555,FluentdElasticsearch=192.168.10.2:5555"
      部分插件介绍
      minikube addons enable yakd
      • 完整的 Kubernetes Dashboard
      • minikube service yakd-dashboard -n yakd-dashboard
      minikube addons enable inspektor-gadget
      • 提供可观察性工具，用于调试和监控 Kubernetes 集群中的问题
      minikube addons enable headlamp
      • 易用可拓展的 Kubernetes web UI
        • 安装 metrics-server 可以显示更多信息
        • minikube addons enable metrics-server
      • minikube service headlamp -n headlamp
      在 Headlamp 里使用认证
      minikube addons enable kong
      minikube addons enable ingress-dns
      • 为 Minikube 集群中的 Ingress 资源提供 DNS 支持
        • 自动将 Ingress 主机名解析为 Minikube 的 IP 地址
        • 简化本地开发环境中使用自定义域名的操作
      • 前提
        • minikube addons enable ingress
        • 添加 minikube ip 为 DNS 服务器
      • （可选）配置群集DNS服务器以在集群中解析本地DNS名称
        • 不要使用 .local 域名
          • 为 mDNS 和 bind9 DNS 服务器保留的顶级域名
          kubectl edit configmap coredns -n kube-system
          • 添加以下 Block
          • 192.168.99.169 替换为实际的 minikube ip
      测试 ingress-dns
      • 添加测试 Ingress
        • kubectl apply -f https://raw.githubusercontent.com/kubernetes/minikube/master/deploy/addons/ingress-dns/example/example.yaml
      • 确认 DNS 查询是否返回 A 类型 DNS 记录（ipv4）
        • nslookup hello-john.test $(minikube ip)
        • nslookup hello-jane.test $(minikube ip)
      • ping 测试
        • ping hello-john.test
        • ping hello-jane.test
      • curl HTTP 测试
        • curl http://hello-john.test
        • curl http://hello-jane.test
      minikube addons enable ambassador
      • 管理和路由 Kubernetes 中的外部流量
      • 通过 minikube tunnel 访问 ambassador
        • minikube tunnel
        • kubectl get service ambassador -n ambassador
      通过 ingress 资源配置
      部署应用和无法从外部访问的 ClusterIP 类型服务
      • 暴露内部应用到路径 /hello/
        • 必须有 annotations kubernetes.io/ingress.class: ambassador
          • vim hello-ingress.yaml
      • kubectl apply -f hello-ingress.yaml
      • curl http://<Ambassdor's External IP'/hello/>
      通过 mapping 资源配置
      部署应用和无法从外部访问的 ClusterIP 类型服务
      • 暴露内部应用到路径 /hello-mapping/
          • vim hello-mapping.yaml
      • kubectl apply -f hello-mapping.yaml
      • curl http://<Ambassdor's External IP'/hello-mapping/>
      minikube addons enable registry-aliases
      • 为本地镜像仓库提供别名支持，简化镜像地址的书写
        • 可以使用 example.com, example.orgtest.com, test.org 来 push 和 pull 本地镜像仓库
      • 前提
        • minikube addons enable registry
      • 检查是否更新
        • watch minikube ssh -- cat /etc/hosts
          • 检查 /etc/hosts
        • kubectl get cm -n kube-system coredns -o yaml
          • 检查 CoreDNS
            • 样例 coredns ConfigMap
      minikube addons enable storage-provisioner-gluster
      • 提供基于 GlusterFS 的动态存储配置功能
      minikube addons enable gvisor
      • 为 Kubernetes 提供一个轻量级的沙箱运行时，增强容器的安全性
      • 依赖于容器运行时，启动时需传递对应选项
        • minikube start --container-runtime=containerd \ --docker-opt containerd=/var/run/containerd/containerd.sock
      在 Pod 的 spec 部分添加 runtimeClassName: gvisor
      停止运行集群
      • minikube stop
      • 删除所有集群
        • minikube delete --all
       

      进入 minkube 内部更改容器镜像源下载地址

      参考资料
      • minikube ssh
      • 为了确保后续重启 minikube 后无需再次修改 daemon.json 文件，需要创建 alternate-daemon.json 并管理 docker 服务启动配置
      更改容器镜像源下载地址
      • sudo cp /etc/docker/daemon.json /etc/docker/alternate-daemon.json
      • sudo vi /etc/docker/alternate-daemon.json
        • 添加镜像源
        • ,"registry-mirrors":["https://mirror.iscas.ac.cn","https://docker.nju.edu.cn","https://dockerproxy.com"]
      创建 docker 服务启动配置文件
      • sudo mkdir -p /etc/systemd/system/docker.service.d
      • sudo vi /etc/systemd/system/docker.service.d/docker.conf
        重启 docker
        • sudo systemctl daemon-reload
        • sudo systemctl restart docker
        • docker info | grep -A5 "Registry Mirrors"
        • exit
         

        故障排除

        • 下载失败时清空数据
          • minikube delete --all
        • 错误排查
          • kubectl get pods -n ingress-nginx
          • kubectl describe pod -n ingress-nginx <ingress-nginx-admission-create-pod-name>
          • kubectl logs -n ingress-nginx <ingress-nginx-admission-create-pod-name>
         
         
        上一篇
        NotionNext 博客运营
        下一篇
        Docker Compose 部署 code-server 服务器
        Comments
        Loading...
        Catalog