k3d

k3s in docker

k3s is the lightweight Kubernetes distribution by Rancher: rancher/k3s

This repository is based on @zeerorg's zeerorg/k3s-in-docker, reimplemented in Go by @iwilltry42 in iwilltry42/k3d, which is now rancher/k3d.

Requirements

• docker

Get

You have several options there:

• use the install script to grab the latest release:
  • wget: wget -q -O - https://raw.githubusercontent.com/rancher/k3d/master/install.sh | bash
  • curl: curl -s https://raw.githubusercontent.com/rancher/k3d/master/install.sh | bash
• Grab a release from the release tab and install it yourself.
• Via go: go install github.com/rancher/k3d (Note: this will give you unreleased/bleeding-edge changes)

or...

Build

1. Clone this repo, e.g. via go get -u github.com/rancher/k3d
2. Inside the repo run
   • 'make install-tools' to make sure required go packages are installed
3. Inside the repo run
   • make build to build for your current system
   • go install to install it to your GOPATH (Note: this will give you unreleased/bleeding-edge changes)
   • make build-cross to build for all systems

Usage

Check out what you can do via k3d help

Example Workflow: Create a new cluster and use it with kubectl

1. k3d create to create a new single-node cluster (docker container)
2. export KUBECONFIG=$(k3d get-kubeconfig) to make kubectl to use the kubeconfig for that cluster
3. execute some commands like kubectl get pods --all-namespaces
4. k3d delete to delete the default cluster

Expose services

1. via Ingress

1. Create a cluster, mapping the ingress port 80 to localhost:8081

   k3d create --api-port 6550 --publish 8081:80 --workers 2

   • Note: --api-port 6550 is not required for the example to work. It's used to have k3s's ApiServer listening on port 6550 with that port mapped to the host system.

2. Get the kubeconfig file

   export KUBECONFIG="$(k3d get-kubeconfig --name='k3s-default')"

3. Create a nginx deployment

   kubectl create deployment nginx --image=nginx

4. Create a ClusterIP service for it

   kubectl create service clusterip nginx --tcp=80:80

5. Create an ingress object for it with kubectl apply -f

   apiVersion: extensions/v1beta1
   kind: Ingress
   metadata:
     name: nginx
     annotations:
       ingress.kubernetes.io/ssl-redirect: "false"
   spec:
     rules:
     - http:
         paths:
         - path: /
           backend:
             serviceName: nginx
             servicePort: 80
   

6. Curl it via localhost

   curl localhost:8081/

2. via NodePort

1. Create a cluster, mapping the port 30080 from worker-0 to localhost:8082

   k3d create --publish 8082:30080@k3d-k3s-default-worker-0 --workers 2

   • Note: Kubernetes' default NodePort range is 30000-32767

... (Steps 2 and 3 like above) ...

1. Create a NodePort service for it with kubectl apply -f

   apiVersion: v1
   kind: Service
   metadata:
     labels:
       app: nginx
     name: nginx
   spec:
     ports:
     - name: 80-80
       nodePort: 30080
       port: 80
       protocol: TCP
       targetPort: 80
     selector:
       app: nginx
     type: NodePort
   

2. Curl it via localhost

   curl localhost:8082/

FAQ / Nice to know

• As @jaredallard pointed out, people running k3d on Linux with LUKS/LVM, may need to mount /dev/mapper into the nodes for the setup to work.
  • This will do: k3d create -v /dev/mapper:/dev/mapper