⚠️ This page is a stub! We're working on it! ⚠️

Configuration

This guide covers how to configure KIND cluster creation.

We know this is currently a bit lacking right now and will expand it over time - PRs welcome!

Getting Started

To configure kind cluster creation, you will need to create a [YAML] config file.This file follows Kubernetes conventions for versioning etc.

A minimal valid config is:

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

This config merely specifies that we are configuration a KIND cluster (kind: Cluster)and that the version of KIND's config we are using is v1alpha4 (apiVersion: kind.x-k8s.io/v1alpha4).

Any given version of kind may support different versions which will have differentoptions and behavior. This is why we must always specify the version.

This mechanism is inspired by Kubernetes resources and component config.

To use this config, place the contents in a file config.yaml and then runkind create cluster —config=config.yaml from the same directory.

You can also include a full file path like kind create cluster —config=/foo/bar/config.yaml.

Cluster-Wide Options

The following high level options are available.

NOTE: not all options are documented yet! We will fix this with time, PRs welcome!

Networking

Multiple details of the cluster's networking can be customized under thenetworking field.

IP Family

KIND has limited support for IPv6 (and soon dual-stack!) clusters, you can switchfrom the default of IPv4 by setting:

  1. kind: Cluster
  2. apiVersion: kind.x-k8s.io/v1alpha4
  3. networking:
  4.   ipFamily: ipv6

NOTE: you may need to reconfigure your docker daemon to enable ipv6 in orderto use this.

IPv6 does not work on docker for mac because port forwarding ipv6is not yet supported in docker for mac.

API Server

The API Server listen address and port can be customized with:

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

Pod Subnet

You can configure the subnet used for pod IPs by setting

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

Service Subnet

You can configure the Kubernetes service subnet used for service IPs by setting

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

Disable Default CNI

KIND ships with a simple networking implementation (“kindnetd”) based aroundstandard CNI plugins (ptp, host-local, …) and simple netlink routes.

This CNI also handles IP masquerade.

You may disable the default to install a different CNI. This is a power userfeature with limited support, but many common CNI manifests are known to work,e.g. Calico.

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

Nodes

The kind: Cluster object has a nodes field containing a list of nodeobjects. If unset this defaults to:

  1. nodes:
  2. # one node hosting a control plane
  3. - role: control-plane

You can create a multi node cluster with the following config:

  1. kind: Cluster
  2. apiVersion: kind.x-k8s.io/v1alpha4
  3. # One control plane node and three "workers".
  4. #
  5. # While these will not add more real compute capacity and
  6. # have limited isolation, this can be useful for testing
  7. # rolling updates etc.
  8. #
  9. # The API-server and other control plane components will be
  10. # on the control-plane node.
  11. #
  12. # You probably don't need this unless you are testing Kubernetes itself.
  13. nodes:
  14. - role: control-plane
  15. - role: worker
  16. - role: worker
  17. - role: worker

Per-Node Options

The following options are available for setting on each entry in nodes.

NOTE: not all options are documented yet! We will fix this with time, PRs welcome!

Extra Mounts

Extra mounts can be used to pass through storage on the host to a kind nodefor persisting data, mounting through code etc.

  1. kind: Cluster
  2. apiVersion: kind.x-k8s.io/v1alpha4
  3. nodes:
  4. - role: control-plane
  5.   # add a mount from /path/to/my/files on the host to /files on the node
  6.   extraMounts:
  7.   - hostPath: /path/to/my/files/
  8.     containerPath: /files

Extra Port Mappings

Extra port mappings can be used to port forward to the kind nodes. This is across-platform option to get traffic into your kind cluster.

With docker on Linux you can simply send traffic to the node IPs from the hostwithout this, but to cover macOS and Windows you'll want to use these.

You may also want to see the Ingress Guide.

  1. kind: Cluster
  2. apiVersion: kind.x-k8s.io/v1alpha4
  3. nodes:
  4. - role: control-plane
  5.   # port forward 80 on the host to 80 on this node
  6.   extraPortMappings:
  7.   - containerPort: 80
  8.     hostPort: 80
  9.     # optional: set the bind address on the host
  10.     # 0.0.0.0 is the current default
  11.     listenAddress: "127.0.0.0"
  12.     # optional: set the protocol to one of TCP, UDP, SCTP.
  13.     # TCP is the default
  14.     protocol: TCP