How to set up a local Knative environment with KinD and without DNS headaches

A how-to guide to deploy Knative, Kourier, and your first app on top of a Kubernetes cluster.

By Leon Stigter | 01.01.0001

Reviewer	Date	Approval
@retgits	2020-06-03	:+1:

Knative builds on Kubernetes to abstract away complexity for developers, and enables them to focus on delivering value to their business. The complex (and sometimes boring) parts of building apps to run on Kubernetes are managed by Knative. In this post, we will focus on setting up a lightweight environment to help you to develop modern apps faster using Knative.

Step 1: Setting up your Kubernetes deployment using KinD

There are many options for creating a Kubernetes cluster on your local machine. However, since we are running containers in the Kubernetes cluster anyway, let’s also use containers for the cluster itself. Kubernetes IN Docker, or KinD for short, enables developers to spin up a Kubernetes cluster where each cluster node is a container.

You can install KinD on your machine by running the following commands:

curl -Lo ./kind https://kind.sigs.k8s.io/dl/v0.8.1/kind-$(uname)-amd64
chmod +x ./kind
mv ./kind /some-dir-in-your-PATH/kind

Next, create a Kubernetes cluster using KinD, and expose the ports the ingress gateway to listen on the host. To do this, you can pass in a file with the following cluster configuration parameters:

cat > clusterconfig.yaml <<EOF
kind: Cluster
apiVersion: kind.sigs.k8s.io/v1alpha3
nodes:
- role: control-plane
  extraPortMappings:
	## expose port 31380 of the node to port 80 on the host
  - containerPort: 31080
    hostPort: 80
	## expose port 31443 of the node to port 443 on the host
  - containerPort: 31443
    hostPort: 443
EOF

The values for the container ports are randomly chosen, and are used later on to configure a NodePort service with these values. The values for the host ports are where you’ll send cURL requests to as you deploy applications to the cluster.

After the cluster configuration file has been created, you can create a cluster. Your kubeconfig will automatically be updated, and the default cluster will be set to your new cluster.

$ kind create cluster --name knative --config clusterconfig.yaml

Creating cluster "knative" ...
 ✓ Ensuring node image (kindest/node:v1.18.2) 🖼
 ✓ Preparing nodes 📦
 ✓ Writing configuration 📜
 ✓ Starting control-plane 🕹️
 ✓ Installing CNI 🔌
 ✓ Installing StorageClass 💾
Set kubectl context to "kind-knative"
You can now use your cluster with:

kubectl cluster-info --context kind-knative

Have a nice day! 👋

Step 2: Install Knative Serving

Now that the cluster is running, you can add Knative components using the Knative CRDs. At the time of writing, the latest available version is 0.15.

$ kubectl apply --filename https://github.com/knative/serving/releases/download/v0.15.0/serving-crds.yaml

customresourcedefinition.apiextensions.k8s.io/certificates.networking.internal.knative.dev created
customresourcedefinition.apiextensions.k8s.io/configurations.serving.knative.dev created
customresourcedefinition.apiextensions.k8s.io/ingresses.networking.internal.knative.dev created
customresourcedefinition.apiextensions.k8s.io/metrics.autoscaling.internal.knative.dev created
customresourcedefinition.apiextensions.k8s.io/podautoscalers.autoscaling.internal.knative.dev created
customresourcedefinition.apiextensions.k8s.io/revisions.serving.knative.dev created
customresourcedefinition.apiextensions.k8s.io/routes.serving.knative.dev created
customresourcedefinition.apiextensions.k8s.io/serverlessservices.networking.internal.knative.dev created
customresourcedefinition.apiextensions.k8s.io/services.serving.knative.dev created
customresourcedefinition.apiextensions.k8s.io/images.caching.internal.knative.dev created

After the CRDs, the core components are next to be installed on your cluster. For brevity, the unchanged components are removed from the response.

$ kubectl apply --filename https://github.com/knative/serving/releases/download/v0.15.0/serving-core.yaml

namespace/knative-serving created
serviceaccount/controller created
clusterrole.rbac.authorization.k8s.io/knative-serving-admin created
clusterrolebinding.rbac.authorization.k8s.io/knative-serving-controller-admin created
image.caching.internal.knative.dev/queue-proxy created
configmap/config-autoscaler created
configmap/config-defaults created
configmap/config-deployment created
configmap/config-domain created
configmap/config-gc created
configmap/config-leader-election created
configmap/config-logging created
configmap/config-network created
configmap/config-observability created
configmap/config-tracing created
horizontalpodautoscaler.autoscaling/activator created
deployment.apps/activator created
service/activator-service created
deployment.apps/autoscaler created
service/autoscaler created
deployment.apps/controller created
service/controller created
deployment.apps/webhook created
service/webhook created
clusterrole.rbac.authorization.k8s.io/knative-serving-addressable-resolver created
clusterrole.rbac.authorization.k8s.io/knative-serving-namespaced-admin created
clusterrole.rbac.authorization.k8s.io/knative-serving-namespaced-edit created
clusterrole.rbac.authorization.k8s.io/knative-serving-namespaced-view created
clusterrole.rbac.authorization.k8s.io/knative-serving-core created
clusterrole.rbac.authorization.k8s.io/knative-serving-podspecable-binding created
validatingwebhookconfiguration.admissionregistration.k8s.io/config.webhook.serving.knative.dev created
mutatingwebhookconfiguration.admissionregistration.k8s.io/webhook.serving.knative.dev created
validatingwebhookconfiguration.admissionregistration.k8s.io/validation.webhook.serving.knative.dev created

Step 3: Set up networking using Kourier

Next, choose a networking layer. This example uses Kourier. Kourier is the option with the lowest resource requirements, and connects to Envoy and the Knative Ingress CRDs directly.

To install Kourier and make it available as a service leveraging the node ports, you’ll need to download the YAML file first and make a few changes.

curl -Lo kourier.yaml https://github.com/knative-sandbox/net-kourier/releases/download/v0.15.0/kourier.yaml

By default, the Kourier service is set to be of type LoadBalancer. On local machines, this type doesn’t work, so you’ll have to change the type to NodePort and add nodePort elements to the two listed ports.

The complete Service portion (which runs from line 75 to line 94 in the document), should be replaced with:

apiVersion: v1
kind: Service
metadata:
  name: kourier
  namespace: kourier-system
  labels:
    networking.knative.dev/ingress-provider: kourier
spec:
  ports:
  - name: http2
    port: 80
    protocol: TCP
    targetPort: 8080
    nodePort: 31080
  - name: https
    port: 443
    protocol: TCP
    targetPort: 8443
    nodePort: 31443
  selector:
    app: 3scale-kourier-gateway
  type: NodePort

To install the Kourier controller, enter the command:

$ kubectl apply --filename kourier.yaml

namespace/kourier-system created
configmap/config-logging created
configmap/config-observability created
configmap/config-leader-election created
service/kourier created
deployment.apps/3scale-kourier-gateway created
deployment.apps/3scale-kourier-control created
clusterrole.rbac.authorization.k8s.io/3scale-kourier created
serviceaccount/3scale-kourier created
clusterrolebinding.rbac.authorization.k8s.io/3scale-kourier created
service/kourier-internal created
service/kourier-control created
configmap/kourier-bootstrap created

Now you will need to set Kourier as the default networking layer for Knative Serving. You can do this by entering the command:

$ kubectl patch configmap/config-network \
  --namespace knative-serving \
  --type merge \
  --patch '{"data":{"ingress.class":"kourier.ingress.networking.knative.dev"}}'

If you want to validate that the patch command was successful, run the command:

$ kubectl describe configmap/config-network --namespace knative-serving

... (abbreviated for readability)
ingress.class:
----
kourier.ingress.networking.knative.dev
...

To get the same experience that you would when using a cluster that has DNS names set up, you can add a “magic” DNS provider.

nip.io provides a wildcard DNS setup that will automatically resolve to the IP address you put in front of nip.io.

To patch the domain configuration for Knative Serving using nip.io, enter the command:

$ kubectl patch configmap/config-domain \
  --namespace knative-serving \
  --type merge \
  --patch '{"data":{"127.0.0.1.nip.io":""}}'

If you want to validate that the patch command was successful, run the command:

$ kubectl describe configmap/config-domain --namespace knative-serving

... (abbreviated for readability)
Data
====
127.0.0.1.nip.io:
----
...

By now, all pods in the knative-serving and kourier-system namespaces should be running. You can check this by entering the commands:

$ kubectl get pods --namespace knative-serving

NAME                          READY   STATUS    RESTARTS   AGE
activator-6d9f95b7f8-w6m68    1/1     Running   0          12m
autoscaler-597fd8d69d-gmh9s   1/1     Running   0          12m
controller-7479cc984d-492fm   1/1     Running   0          12m
webhook-bf465f954-4c7wq       1/1     Running   0          12m

$ kubectl get pods --namespace kourier-system

NAME                                      READY   STATUS    RESTARTS   AGE
3scale-kourier-control-699cbc695-ztswk    1/1     Running   0          10m
3scale-kourier-gateway-7df98bb5db-5bw79   1/1     Running   0          10m

To validate your cluster gateway is in the right state and using the right ports, enter the command:

$ kubectl --namespace kourier-system get service kourier

NAME      TYPE       CLUSTER-IP      EXTERNAL-IP   PORT(S)                      AGE
kourier   NodePort   10.98.179.178   <none>        80:31080/TCP,443:31443/TCP   87m

$ docker ps -a

CONTAINER ID        IMAGE                  COMMAND                  CREATED             STATUS              PORTS                                                                      NAMES
d53c275d7461        kindest/node:v1.18.2   "/usr/local/bin/entr…"   4 hours ago         Up 4 hours          127.0.0.1:49350->6443/tcp, 0.0.0.0:80->31080/tcp, 0.0.0.0:443->31443/tcp   knative-control-plane

The ports, and how they’re tied to the host, should be the same as you’ve defined in the clusterconfig file. For example, port 31380 in the cluster is exposed as port 80.

Step 4: Deploying your first app

Now that the cluster, Knative, and the networking components are ready, you can deploy an app. The straightforward Go app that already exists, is an excellent example app to deploy. The first step is to create a yaml file with the hello world service definition:

cat > service.yaml <<EOF
apiVersion: serving.knative.dev/v1 # Current version of Knative
kind: Service
metadata:
  name: helloworld-go # The name of the app
  namespace: default # The namespace the app will use
spec:
  template:
    spec:
      containers:
        - image: gcr.io/knative-samples/helloworld-go # The URL to the image of the app
          env:
            - name: TARGET # The environment variable printed out by the sample app
              value: "Hello Knative Serving is up and running with Kourier!!"
EOF

To deploy your app to Knative, enter the command:

$ kubectl apply --filename service.yaml

To validate your deployment, you can use kubectl get ksvc. NOTE: While your cluster is configuring the components that make up the service, the output of the kubectl get ksvc command will show that the revision is missing. The status ready eventually changes to true.

$ kubectl get ksvc

NAME            URL                                             LATESTCREATED         LATESTREADY   READY     REASON
helloworld-go   http://helloworld-go.default.127.0.0.1.nip.io   helloworld-go-fqqs6                 Unknown   RevisionMissing

NAME            URL                                             LATESTCREATED         LATESTREADY           READY   REASON
helloworld-go   http://helloworld-go.default.127.0.0.1.nip.io   helloworld-go-fqqs6   helloworld-go-fqqs6   True

The final step is to test your application, by checking that the code returns what you expect. You can do this by sending a cURL request to the URL listed above.

Because this example mapped port 80 of the host to be forwarded to the cluster and set the DNS, you can use the exact URL.

$ curl -v http://helloworld-go.default.127.0.0.1.nip.io

Hello Knative Serving is up and running with Kourier!!

Step 5: Cleaning up

You can stop your cluster and remove all the resources you’ve created by entering the command:

kind delete cluster --name knative

About the author

As a Product Manager, Leon is very passionate and outspoken when it comes to serverless and container technologies. He believes that “devs wanna dev” and that drives his passion to help build better products. He enjoys writing code, speaking at conferences and meetups, and blogging about that. In his personal life, he’s on a mission to taste cheesecake in every city he visits (suggestions are welcome @retgits).

← Previous