Developing for Kubernetes with KinD

This guide is meant to serve as a cross-platform resource for setting up a local Kubernetes development environment. In this guide, we’ll be using KinD. It creates a Kubernetes cluster using Docker, and provides easy mechanisms for deploying different versions as well as multiple nodes.

We will also make use of nip.io, which lets us map any IP address to a hostname using a format like this: 192.168.1.250.nip.io, which maps to 192.168.1.250. No installation is required.

note
With the SSL-enabled installation options below, if you want to clone repositories and push changes, you will have to do so over HTTPS instead of SSH. We are planning to address this with an update to GitLab Shell’s service exposure via NodePorts.

Apple silicon (M1/M2)

kind can be used with colima to provide a local Kubernetes development environment on macOS, including M1 and M2 variants.

Installing dependencies

  • Make sure that you’re running MacOS >= 13 (Ventura).
  • Install colima.

  • Install Rosetta:

    softwareupdate --install-rosetta

Building the VM

Create the colima VM:

colima start --cpu 4 --memory 16 --disk 40 --profile docker --arch aarch64 --vm-type=vz --vz-rosetta

When ready, you can follow the preparation below to install GitLab with kind.

Managing the VM

To stop the colima VM:

colima stop --profile docker

To start again the VM:

colima start --profile docker

To remove and clean up the local system:

colima delete --profile docker

Preparation

Required information

All of the following installation options require knowing your host IP. Here are a couple options to find this information:

  • Linux: hostname -i
  • MacOS: ipconfig getifaddr en0
note
Most MacOS systems use en0 as the primary interface. If using a system with a different primary interface, please substitute that interface name for en0.

Using namespaces

It is considered best practice to install applications in namespaces other than default. Create a namespace prior to running helm install with kubectl:

kubectl create namespace YOUR_NAMESPACE

Add --namespace YOUR_NAMESPACE to all future kubectl commands to use the namespace. Alternatively, use kubens from the kubectx project to contextually switch into the namespace and skip the extra typing.

Installing dependencies

You can use asdf (more info) to install the following tools:

  • kubectl
  • helm
  • kind

Note that kind uses Docker to run local Kubernetes clusters, so be sure to install Docker.

Obtaining configuration examples

The GitLab charts repository contains every example referenced in the following steps. Clone the repository or update an existing checkout to get the latest versions:

git clone https://gitlab.com/gitlab-org/charts/gitlab.git

Adding GitLab Helm chart

Follow these commands to set up your system to access the GitLab Helm charts:

helm repo add gitlab https://charts.gitlab.io/
helm repo update

Deployment options

Select from one of the following deployment options based on your needs.

note
The first full deployment process may take around 10 minutes depending on network and system resources while the cloud-native GitLab images are downloaded. Confirm GitLab is running with the following command:
kubectl --namespace YOUR_NAMESPACE get pods

GitLab is fully deployed when the webservice pod shows a READY state with 2/2 containers.

NGINX Ingress NodePort with SSL

In this method, we will use kind to expose the NGINX controller service’s NodePorts to ports on your local machine with SSL enabled.

kind create cluster --config examples/kind/kind-ssl.yaml
helm upgrade --install gitlab gitlab/gitlab \
  --set global.hosts.domain=(your host IP).nip.io \
  -f examples/kind/values-base.yaml \
  -f examples/kind/values-ssl.yaml

You can then access GitLab at https://gitlab.(your host IP).nip.io.

(Optional) Add root CA

In order for your browser to trust our self-signed certificate, download the root CA and trust it:

kubectl get secret gitlab-wildcard-tls-ca -ojsonpath='{.data.cfssl_ca}' | base64 --decode > gitlab.(your host IP).nip.io.ca.pem

Now that the root CA is downloaded, you can add it to your local chain (instructions vary per platform and are readily available online).

note
If you need to log into the registry with docker login, you will need to take additional steps to configure the registry to work with your self-signed certificates. More instructions can be found here and here.

NGINX Ingress NodePort without SSL

In this method, we will use kind to expose the NGINX controller service’s NodePorts to ports on your local machine with SSL disabled.

kind create cluster --config examples/kind/kind-no-ssl.yaml
helm upgrade --install gitlab gitlab/gitlab \
  --set global.hosts.domain=(your host IP).nip.io \
  -f examples/kind/values-base.yaml \
  -f examples/kind/values-no-ssl.yaml

Access GitLab at http://gitlab.(your host IP).nip.io.

note
If you need to log into the registry with docker login, you will need to tell Docker to trust your insecure registry.

Handling DNS

This guide assumes you have network access to nip.io. If this is not available to you, please refer to the handling DNS section in the minikube documentation which will also work for KinD.

note
When editing /etc/hosts, remember to use the host computer’s IP address rather than the output of $(minikube ip).

Cleaning up

When you’re ready to clean up your local system, run this command:

kind delete cluster
note
If you named your cluster upon creation, or if you are running multiple clusters, you can delete specific ones with the --name flag.