配置

本指南介绍如何配置 KIND 集群创建。

我们知道目前这方面内容还比较缺乏,我们会随着时间的推移进行扩展 - 欢迎 PR!

内容 🔗︎

入门 🔗︎

要配置 kind 集群创建,您需要创建一个 YAML 配置文件。此文件遵循 Kubernetes 的版本控制等约定。

一个最小的有效配置是

kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4

此配置仅指定我们正在配置一个 KIND 集群 (kind: Cluster) 以及我们正在使用的 KIND 配置版本为 v1alpha4 (apiVersion: kind.x-k8s.io/v1alpha4)。

任何给定版本的 kind 都可能支持不同的版本,这些版本将具有不同的选项和行为。这就是为什么我们必须始终指定版本的原因。

这种机制的灵感来自 Kubernetes 资源和组件配置。

要使用此配置,请将内容放置在名为 config.yaml 的文件中,然后从同一目录运行 kind create cluster --config=config.yaml

您还可以包含完整的路径,例如 kind create cluster --config=/foo/bar/config.yaml

Cluster 类型的结构由 Go 结构体定义,该结构体在 此处 描述。

关于 CLI 参数和配置文件的说明 🔗︎

除非另有说明,传递给 CLI 的参数优先于配置文件中的等效参数。例如,如果您调用

kind create cluster --name my-cluster

将使用名称 my-cluster,无论您的配置文件中是否存在该值。

集群范围选项 🔗︎

以下高级选项可用。

注意:并非所有选项都已记录!我们会随着时间的推移修复这个问题,欢迎 PR!

命名您的集群 🔗︎

您可以在配置中指定集群名称

kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
name: app-1-cluster

功能开关 🔗︎

Kubernetes 功能开关 可以使用以下配置在所有 Kubernetes 组件中启用集群范围

kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
featureGates:
  # any feature gate can be enabled here with "Name": true
  # or disabled here with "Name": false
  # not all feature gates are tested, however
  "CSIMigration": true

运行时配置 🔗︎

Kubernetes API 服务器运行时配置可以使用 runtimeConfig 键进行切换,该键映射到 --runtime-config kube-apiserver 标志。这可用于例如禁用 beta/alpha API。

kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
runtimeConfig:
  "api/alpha": "false"

网络 🔗︎

集群网络的多个细节可以在 networking 字段下进行自定义。

IP 族 🔗︎

KIND 支持 IPv4、IPv6 和双栈集群,您可以通过设置以下内容从默认的 IPv4 切换

IPv6 集群 🔗︎

如果您运行 Docker 容器的主机支持 IPv6,则可以使用 kind 运行 IPv6 单栈集群。大多数操作系统/发行版默认情况下启用了 IPv6,但您可以在 Linux 上使用以下命令进行检查

sudo sysctl net.ipv6.conf.all.disable_ipv6

您应该看到

net.ipv6.conf.all.disable_ipv6 = 0

如果您在 Windows 或 Mac 上使用 Docker,则需要使用从主机到 API 服务器的 IPv4 端口转发,因为 IPv6 端口转发在这些平台上不起作用,您可以使用以下配置进行操作

kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
networking:
  ipFamily: ipv6
  apiServerAddress: 127.0.0.1

在 Linux 上,您只需要

kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
networking:
  ipFamily: ipv6
双栈集群 🔗︎

您可以在 kind 0.11+ 上运行双栈集群,在 kubernetes 版本 1.20+ 上。

kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
networking:
  ipFamily: dual

API 服务器 🔗︎

API 服务器监听地址和端口可以使用以下内容进行自定义

kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
networking:
  # WARNING: It is _strongly_ recommended that you keep this the default
  # (127.0.0.1) for security reasons. However it is possible to change this.
  apiServerAddress: "127.0.0.1"
  # By default the API server listens on a random open port.
  # You may choose a specific port but probably don't need to in most cases.
  # Using a random port makes it easier to spin up multiple clusters.
  apiServerPort: 6443

security goose says

安全提示

注意:在公开您的 kind 集群之前,您应该认真考虑三次!kind 不附带最先进的安全功能或任何更新策略(除了处置您的集群并创建一个新的集群之外)!我们强烈建议不要将 kind 公开给除环回之外的任何内容。

Pod 子网 🔗︎

您可以通过设置以下内容来配置用于 Pod IP 的子网

kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
networking:
  podSubnet: "10.244.0.0/16"

默认情况下,kind 使用 10.244.0.0/16 Pod 子网用于 IPv4,fd00:10:244::/56 Pod 子网用于 IPv6。

服务子网 🔗︎

您可以通过设置以下内容来配置用于服务 IP 的 Kubernetes 服务子网

kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
networking:
  serviceSubnet: "10.96.0.0/12"

默认情况下,kind 使用 10.96.0.0/16 服务子网用于 IPv4,fd00:10:96::/112 服务子网用于 IPv6。

禁用默认 CNI 🔗︎

KIND 附带一个简单的网络实现(“kindnetd”),它基于标准 CNI 插件 (ptphost-local、…) 和简单的 netlink 路由。

此 CNI 还处理 IP 伪装。

您可以禁用默认值以安装不同的 CNI。这是一个高级用户功能,支持有限,但许多常见的 CNI 清单已知可以正常工作,例如 Calico。

kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
networking:
  # the default CNI will not be installed
  disableDefaultCNI: true

kube-proxy 模式 🔗︎

您可以配置将使用的 kube-proxy 模式,在 iptables、nftables(Kubernetes v1.31+)和 ipvs 之间。默认情况下使用 iptables

kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
networking:
  kubeProxyMode: "nftables"

要禁用 kube-proxy,请将模式设置为 "none"

节点 🔗︎

kind: Cluster 对象具有一个 nodes 字段,其中包含 node 对象列表。如果未设置,则默认为

nodes:
# one node hosting a control plane
- role: control-plane

您可以使用以下配置创建多节点集群

kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
# One control plane node and three "workers".
#
# While these will not add more real compute capacity and
# have limited isolation, this can be useful for testing
# rolling updates etc.
#
# The API-server and other control plane components will be
# on the control-plane node.
#
# You probably don't need this unless you are testing Kubernetes itself.
nodes:
- role: control-plane
- role: worker
- role: worker
- role: worker

每个节点的选项 🔗︎

以下选项可用于在 nodes 中的每个条目上进行设置。

注意:并非所有选项都已记录!我们会随着时间的推移修复这个问题,欢迎 PR!

Kubernetes 版本 🔗︎

您可以通过设置 node 的容器镜像来设置特定的 Kubernetes 版本。您可以在 发布页面 上找到可用的镜像标签。请在发布说明中包含来自镜像的 @sha256: 镜像摘要,如以下示例所示

kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
nodes:
- role: control-plane
  image: kindest/node:v1.16.4@sha256:b91a2c2317a000f3a783489dfb755064177dbc3a0b2f4147d50f04825d016f55
- role: worker
  image: kindest/node:v1.16.4@sha256:b91a2c2317a000f3a783489dfb755064177dbc3a0b2f4147d50f04825d016f55

参考

注意:Kubernetes 版本表示为 x.y.z,其中 x 是主版本,y 是次版本,z 是补丁版本,遵循 语义版本控制 术语。有关更多信息,请参阅 Kubernetes 发布版本控制。

额外挂载 🔗︎

额外挂载可用于将主机上的存储传递给 kind 节点,以持久化数据、通过代码挂载等。

examples/config-with-mounts.yaml
kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
nodes:
- role: control-plane
  # add a mount from /path/to/my/files on the host to /files on the node
  extraMounts:
  - hostPath: /path/to/my/files
    containerPath: /files
  #
  # add an additional mount leveraging *all* of the config fields
  #
  # generally you only need the two fields above ...
  #
  - hostPath: /path/to/my/other-files/
    containerPath: /other-files
    # optional: if set, the mount is read-only.
    # default false
    readOnly: true
    # optional: if set, the mount needs SELinux relabeling.
    # default false
    selinuxRelabel: false
    # optional: set propagation mode (None, HostToContainer or Bidirectional)
    # see https://kubernetes.ac.cn/docs/concepts/storage/volumes/#mount-propagation
    # default None
    #
    # WARNING: You very likely do not need this field.
    #
    # This field controls propagation of *additional* mounts created
    # *at runtime* underneath this mount.
    #
    # On MacOS with Docker Desktop, if the mount is from macOS and not the
    # docker desktop VM, you cannot use this field. You can use it for
    # mounts to the linux VM.
    propagation: None

注意:如果您使用的是 Docker for Mac 或 Windows,请检查 hostPath 是否包含在首选项 -> 资源 -> 文件共享中。

有关更多信息,请参阅 Docker 文件共享指南。

额外端口映射 🔗︎

额外端口映射可用于将端口转发到 kind 节点。这是一个跨平台选项,用于将流量引入您的 kind 集群。

如果您在 Linux 上运行 Docker 而不使用 Docker Desktop 应用程序,则可以简单地将流量从主机发送到节点 IP,而无需额外的端口映射。安装 Docker Desktop 应用程序后,无论是在 macOS、Windows 还是 Linux 上,您都需要使用这些端口映射。

您可能还想查看 Ingress 指南

examples/config-with-port-mapping.yaml
kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
nodes:
- role: control-plane
  # port forward 80 on the host to 80 on this node
  extraPortMappings:
  - containerPort: 80
    hostPort: 80
    # optional: set the bind address on the host
    # 0.0.0.0 is the current default
    listenAddress: "127.0.0.1"
    # optional: set the protocol to one of TCP, UDP, SCTP.
    # TCP is the default
    protocol: TCP

一个将主机端口映射到容器端口的示例 http pod。

kind: Pod
apiVersion: v1
metadata:
  name: foo
spec:
  containers:
  - name: foo
    image: hashicorp/http-echo:0.2.3
    args:
    - "-text=foo"
    ports:
    - containerPort: 5678
      hostPort: 80

使用端口映射的 NodePort 🔗︎

要将端口映射与 NodePort 一起使用,kind 节点的 containerPort 和服务的 nodePort 需要相等。

kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
nodes:
- role: control-plane
  extraPortMappings:
  - containerPort: 30950
    hostPort: 80

然后将 nodePort 设置为 30950。

kind: Pod
apiVersion: v1
metadata:
  name: foo
  labels:
    app: foo
spec:
  containers:
  - name: foo
    image: hashicorp/http-echo:0.2.3
    args:
    - "-text=foo"
    ports:
    - containerPort: 5678
---
apiVersion: v1
kind: Service
metadata:
  name: foo
spec:
  type: NodePort
  ports:
  - name: http
    nodePort: 30950
    port: 5678
  selector:
    app: foo

额外标签 🔗︎

额外标签可能对使用 nodeSelectors 有用。

一个用于指定 tier 标签的示例标签

kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
nodes:
- role: control-plane
- role: worker
  extraPortMappings:
  - containerPort: 30950
    hostPort: 80
  labels:
    tier: frontend
- role: worker
  labels:
    tier: backend

Kubeadm 配置补丁 🔗︎

KIND 使用 kubeadm 来配置集群节点。

正式来说,KIND 在第一个控制平面节点上运行 kubeadm init,我们可以通过使用 kubeadm InitConfiguration (spec) 来自定义标志。

kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
nodes:
- role: control-plane
  kubeadmConfigPatches:
  - |
    kind: InitConfiguration
    nodeRegistration:
      kubeletExtraArgs:
        node-labels: "my-label=true"    

如果您想进行更多自定义,在 kubeadm init 期间有四种可用的配置类型:InitConfigurationClusterConfigurationKubeProxyConfigurationKubeletConfiguration。例如,我们可以通过使用 kubeadm ClusterConfiguration (spec) 来覆盖 apiserver 标志。

kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
nodes:
- role: control-plane
  kubeadmConfigPatches:
  - |
    kind: ClusterConfiguration
    apiServer:
        extraArgs:
          enable-admission-plugins: NodeRestriction,MutatingAdmissionWebhook,ValidatingAdmissionWebhook    

在 KIND 集群中配置的每个附加节点(工作节点或控制平面节点(在 HA 模式下)),KIND 都会运行 kubeadm join,可以使用 JoinConfiguration (spec) 来配置。

kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
nodes:
- role: control-plane
- role: worker
- role: worker
  kubeadmConfigPatches:
  - |
    kind: JoinConfiguration
    nodeRegistration:
      kubeletExtraArgs:
        node-labels: "my-label2=true"    
- role: control-plane
  kubeadmConfigPatches:
  - |
    kind: JoinConfiguration
    nodeRegistration:
      kubeletExtraArgs:
        node-labels: "my-label3=true"    

如果您需要对补丁进行更多控制,也可以使用策略性合并和 JSON6092 补丁。这些是使用目录中的文件指定的,例如 ./patches/kube-controller-manager.yaml 可以是以下内容。

apiVersion: v1
kind: Pod
metadata:
  name: kube-controller-manager
  namespace: kube-system
spec:
  containers:
  - name: kube-controller-manager
    env:
    - name: KUBE_CACHE_MUTATION_DETECTOR
      value: "true"

然后在您的 kind YAML 配置中使用以下内容。

nodes:
- role: control-plane
  extraMounts:
  - hostPath: ./patches
    containerPath: /patches

kubeadmConfigPatches:
  - |
    kind: InitConfiguration
    patches:
      directory: /patches    

请注意 extraMounts 部分。该节点是由 kind 创建的容器。kubeadm 在此节点容器内运行,并且包含补丁的本地目录必须对 kubeadm 可访问。extraMounts 将本地目录连接到此节点容器。

此示例用于更改控制平面中的管理器。要对工作节点使用补丁,请使用 JoinConfiguration 补丁和 worker 角色的 extraMounts 部分。