Rancher/k3d 配置文件使用完全指南

温宝沫Morgan

于 2025-06-07 09:06:54 发布

阅读量227

点赞数 3

本文链接：https://blog.csdn.net/gitblog_00027/article/details/148488792

版权

Rancher/k3d 配置文件使用完全指南

k3d 项目地址: https://gitcode.com/gh_mirrors/k3d/k3d

前言

在现代容器化开发环境中，Kubernetes集群的快速部署和管理变得尤为重要。Rancher/k3d作为轻量级Kubernetes发行版k3s的Docker封装工具，为开发者提供了便捷的本地开发环境搭建方案。随着k3d v4.0.0版本的发布，配置文件的引入使得集群管理更加灵活和可维护。

配置文件基础概念

配置文件优势

相比传统的命令行参数方式，使用配置文件具有以下显著优势：

版本控制友好：YAML文件可以轻松纳入版本控制系统
可复用性：同一配置文件可重复用于创建相似集群
可读性强：结构化展示所有配置参数
参数完整性：避免遗漏重要配置项

基本结构要求

k3d配置文件必须包含两个基本字段：

apiVersion: k3d.io/v1alpha5  # 当前配置文件版本
kind: Simple                 # 配置文件类型

这是最小化的有效配置文件，虽然它实际上不配置任何具体参数。

配置文件详解

核心配置项

集群基础配置

metadata:
  name: mycluster  # 集群名称(自动添加k3d-前缀)
servers: 1         # 控制平面节点数量
agents: 2          # 工作节点数量
image: rancher/k3s:v1.20.4-k3s1  # 使用的k3s镜像

网络配置

network: my-custom-net  # 自定义Docker网络
subnet: "172.28.0.0/16" # 指定子网范围

Kubernetes API配置

kubeAPI:
  host: "myhost.my.domain"  # API服务器地址
  hostIP: "127.0.0.1"       # 监听IP
  hostPort: "6445"          # 映射端口

高级配置项

存储卷映射

volumes:
  - volume: /my/host/path:/path/in/node
    nodeFilters:
      - server:0    # 应用到server0节点
      - agent:*     # 应用到所有agent节点

端口转发

ports:
  - port: 8080:80
    nodeFilters:
      - loadbalancer  # 应用到负载均衡器

环境变量

env:
  - envVar: bar=baz
    nodeFilters:
      - server:0  # 仅应用到server0节点

注册表配置

k3d支持多种注册表配置方式：

registries:
  create:  # 创建本地注册表
    name: registry.localhost
    hostPort: "5000"
    proxy:  # 配置为代理缓存
      remoteURL: https://registry-1.docker.io
  use:     # 使用现有注册表
    - k3d-myotherregistry:5000

最佳实践

配置优先级理解

k3d遵循以下配置优先级（从高到低）：

命令行参数
环境变量
配置文件
默认值

这意味着您可以通过命令行参数覆盖配置文件中的设置。

环境变量扩展

配置文件支持环境变量扩展，例如：

volumes:
  - volume: ${HOME}/k3d-data:/data

验证配置文件

建议使用支持JSON Schema的编辑器编写配置文件，以获得自动补全和验证功能。k3d提供的Schema可以确保配置的正确性。

典型应用场景

开发环境配置示例

apiVersion: k3d.io/v1alpha5
kind: Simple
metadata:
  name: dev-cluster
servers: 1
agents: 2
ports:
  - port: 8080:80
    nodeFilters:
      - loadbalancer
volumes:
  - volume: ./k8s-manifests:/var/lib/rancher/k3s/server/manifests
    nodeFilters:
      - server:0
options:
  k3d:
    wait: true
    timeout: "60s"

生产模拟配置示例

apiVersion: k3d.io/v1alpha5
kind: Simple
metadata:
  name: prod-sim
servers: 3  # 高可用控制平面
agents: 5   # 多个工作节点
kubeAPI:
  host: "k3d-prod.local"
  hostPort: "6443"
registries:
  create:
    name: registry.prod.local
    volumes:
      - /mnt/registry-data:/var/lib/registry
options:
  k3s:
    extraArgs:
      - arg: "--tls-san=k3d-prod.local"
        nodeFilters:
          - server:*