Prepare a kind Cluster

kind is a tool for running local Kubernetes clusters using Docker container “nodes”. Follow these instructions to prepare a kind cluster for running Verrazzano.

Prerequisites

Prepare the kind cluster

To prepare the kind cluster for use with Verrazzano, you must create the cluster and then install and configure MetalLB in that cluster.

You can create the kind cluster in two ways: with or without image caching; image caching can speed up your installation time.

Create a kind cluster

kind images are prebuilt for each release. To find images suitable for a given release, check the release notes for your kind version (check with kind version). There you’ll find a complete listing of images created for a kind release.

The following example references a Kubernetes v1.26-based image built for kind v0.20.0. Replace that image with one suitable for the kind release you are using. For the supported Kubernetes versions, see the listing here.

$ kind create cluster --config - <<EOF
kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
nodes:
  - role: control-plane
    image: kindest/node:v1.26@sha256:69860bda5563ac81e3c0057d654b5253219618a22ec3a346306239bba8cfa1a6
    kubeadmConfigPatches:
      - |
        kind: ClusterConfiguration
        apiServer:
          extraArgs:
            "service-account-issuer": "kubernetes.default.svc"
            "service-account-signing-key-file": "/etc/kubernetes/pki/sa.key"
EOF

Create a kind cluster with image caching

While developing or experimenting with Verrazzano, you might destroy and re-create your kind cluster multiple times. To speed up Verrazzano installation, follow these steps to ensure that the image cache used by containerd inside a kind cluster, is preserved across clusters. Subsequent installations will be faster because they will not need to pull the images again.

1. Create a named Docker volume that will be used for the image cache and note its mountPoint path. In this example, the volume is named containerd.

$ docker volume create containerd

$ docker volume inspect containerd

# Sample output
{
    "CreatedAt": "2021-01-11T16:27:47Z",
    "Driver": "local",
    "Labels": {},
    "Mountpoint": "/var/lib/docker/volumes/containerd/_data",
    "Name": "containerd",
    "Options": {},
    "Scope": "local"
}

2. Specify the mountPoint path obtained, as the hostPath under extraMounts in your kind configuration file, with a containerPath of /var/lib/containerd, which is the default containerd image caching location inside the kind container. An example of the modified kind configuration is shown in the following create cluster command.

$ kind create cluster --config - <<EOF
kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
nodes:
  - role: control-plane
    image: kindest/node:v1.26@sha256:69860bda5563ac81e3c0057d654b5253219618a22ec3a346306239bba8cfa1a6
    kubeadmConfigPatches:
      - |
        kind: ClusterConfiguration
        apiServer:
          extraArgs:
            "service-account-issuer": "kubernetes.default.svc"
            "service-account-signing-key-file": "/etc/kubernetes/pki/sa.key"
    extraMounts:
      - hostPath: /var/lib/docker/volumes/containerd/_data
        containerPath: /var/lib/containerd #This is the location of the image cache inside the kind container
EOF

NOTE: When using a private container registry or experiencing rate-limiting of container image pulls, refer to the kind documentation.

Install and configure MetalLB

By default, kind does not provide an implementation of network load balancers (Services of type LoadBalancer). MetalLB offers a network load balancer implementation.

To install MetalLB:

$ kubectl apply -f https://raw.githubusercontent.com/metallb/metallb/v0.13.7/config/manifests/metallb-native.yaml --wait=true

Wait for MetalLB to be ready, as shown:

$ kubectl get pods -n metallb-system -L app=metallb
NAME                         READY   STATUS    RESTARTS       AGE   APP=METALLB
controller-d9d8c78b6-hhplg   1/1     Running   1 (3d4h ago)   9d    
speaker-4lqpg                1/1     Running   1 (3d4h ago)   9d

For further details, see the MetalLB installation guide.

MetalLB is idle until configured. Configure MetalLB in Layer 2 mode and give it control over a range of IP addresses in the kind Docker network. In versions v0.7.0 and earlier, kind uses Docker’s default bridge network; in versions v0.8.0 and later, it creates its own bridge network in kind.

To determine the subnet of the kind Docker network in kind v0.8.0 and later:

$ docker inspect kind | jq '.[0].IPAM.Config[0].Subnet' -r

# Sample output
172.18.0.0/16

To determine the subnet of the kind Docker network in kind v0.7.0 and earlier:

$ docker inspect bridge | jq '.[0].IPAM.Config[0].Subnet' -r

# Sample output
172.17.0.0/16

For use by MetalLB, assign a range of IP addresses at the end of the kind network’s subnet CIDR range. To set an address range, use the ADDRESS_RANGE environment variable:

ADDRESS_RANGE="172.18.0.230-172.18.0.254"

#Create the IPAddressPool for the cluster

$ kubectl apply -f - <<-EOF
apiVersion: metallb.io/v1beta1
kind: IPAddressPool
metadata:
  name: vzlocalpool
  namespace: metallb-system
spec:
  addresses:
  - ${ADDRESS_RANGE}
EOF

#Create the L2Advertisment resource for the cluster

$ kubectl apply -f - <<-EOF
apiVersion: metallb.io/v1beta1
kind: L2Advertisement
metadata:
  name: vzmetallb
  namespace: metallb-system
spec:
  ipAddressPools:
  - vzlocalpool
EOF

Next steps

To continue, see the Installation Guide.