Deploy Kuma on Kubernetes

To start learning how Kuma works, you run and secure a simple demo application that consists of two services:

  • demo-app: a web application that lets you increment a numeric counter. It listens on port 5000
  • redis: data store for the counter
  2. ---
  3. title: service graph of the demo app
  4. ---
  5. flowchart LR
  6. demo-app(demo-app :5000)
  7. redis(redis :6379)
  8. demo-app --> redis

Prerequisites

  • Helm - a package manager for Kubernetes
  • Kind - a tool for running local Kubernetes clusters

Start Kubernetes cluster

Start a new Kubernetes cluster on your local machine by executing:

  1. kind create cluster --name=mesh-zone

You can skip this step if you already have a Kubernetes cluster running. It can be a cluster running locally or in a public cloud like AWS EKS, GCP GKE, etc.

Install Kuma

Install Kuma control plane with Helm by executing:

  1. helm repo add kuma https://kumahq.github.io/charts
  2. helm repo update
  3. helm install --create-namespace --namespace kuma-system kuma kuma/kuma

Deploy demo application

  1. Deploy the application

    1. kubectl apply -f https://raw.githubusercontent.com/kumahq/kuma-counter-demo/master/demo.yaml
    2. kubectl wait -n kuma-demo --for=condition=ready pod --selector=app=demo-app --timeout=90s

  2. Port-forward the service to the namespace on port 5000:

    1. kubectl port-forward svc/demo-app -n kuma-demo 5000:5000

  3. In a browser, go to 127.0.0.1:5000 and increment the counter.

The demo app includes the kuma.io/sidecar-injection label enabled on the kuma-demo namespace.

  1. apiVersion: v1
  2. kind: Namespace
  3. metadata:
  4.   name: kuma-demo
  5.   labels:
  6.     kuma.io/sidecar-injection: enabled

This means that Kuma already knows that it needs to automatically inject a sidecar proxy to every Kubernetes pod in the kuma-demo namespace.

Explore GUI

You can view the sidecar proxies that are connected to the Kuma control plane.

Kuma ships with a read-only GUI that you can use to retrieve Kuma resources. By default, the GUI listens on the API port which defaults to 5681.

To access Kuma we need to first port-forward the API service with:

  1. kubectl port-forward svc/kuma-control-plane -n kuma-system 5681:5681

And then navigate to 127.0.0.1:5681/gui to see the GUI.

Introduce zero-trust security

By default, the network is insecure and not encrypted. We can change this with Kuma by enabling the Mutual TLS policy to provision a Certificate Authority (CA) that will automatically assign TLS certificates to our services (more specifically to the injected data plane proxies running alongside the services).

Before enabling Mutual TLS (mTLS) in your mesh, you need to create a MeshTrafficPermission policy that allows traffic between your applications.

If you enable mTLS without a MeshTrafficPermission policy, all traffic between your applications will be blocked.

To create a MeshTrafficPermission policy, you can use the following command:

  1. echo "apiVersion: kuma.io/v1alpha1
  2. kind: MeshTrafficPermission
  3. metadata:
  4.   namespace: kuma-system
  5.   name: mtp
  6. spec:
  7.   targetRef:
  8.     kind: Mesh
  9.   from:
  10.     - targetRef:
  11.         kind: Mesh
  12.       default:
  13.         action: Allow" | kubectl apply -f -

This command will create a policy that allows all traffic between applications within your mesh. If you need to create more specific rules, you can do so by editing the policy manifest.

We can enable Mutual TLS with a builtin CA backend by executing:

  1. echo "apiVersion: kuma.io/v1alpha1
  2. kind: Mesh
  3. metadata:
  4.   name: default
  5. spec:
  6.   mtls:
  7.     enabledBackend: ca-1
  8.     backends:
  9.     - name: ca-1
  10.       type: builtin" | kubectl apply -f -

The traffic is now encrypted with mTLS and each service can reach any other service.

We can then restrict the traffic by default by executing:

  1. echo "
  2. apiVersion: kuma.io/v1alpha1
  3. kind: MeshTrafficPermission
  4. metadata:
  5.   namespace: kuma-system
  6.   name: mtp
  7. spec:
  8.   targetRef:
  9.     kind: Mesh
  10.   from:
  11.     - targetRef:
  12.         kind: Mesh
  13.       default:
  14.         action: Deny" | kubectl apply -f -

At this point, the demo application should not function, because we blocked the traffic. You can verify this by clicking the increment button again and seeing the error message in the browser. We can allow the traffic from the demo-app to redis by applying the following MeshTrafficPermission

  1. echo "
  2. apiVersion: kuma.io/v1alpha1
  3. kind: MeshTrafficPermission
  4. metadata:
  5.   namespace: kuma-system
  6.   name: redis
  7. spec:
  8.   targetRef:
  9.     kind: MeshService
  10.     name: redis_kuma-demo_svc_6379
  11.   from:
  12.     - targetRef:
  13.         kind: MeshSubset
  14.         tags:
  15.           kuma.io/service: demo-app_kuma-demo_svc_5000
  16.       default:
  17.         action: Allow" | kubectl apply -f -

You can click the increment button, the application should function once again. However, the traffic to redis from any other service than demo-app is not allowed.

Next steps

  • Explore the Features available to govern and orchestrate your service traffic.
  • Add a gateway to access the demo from the outside by following the builtin gateway guide.
  • Add Kong as gateway to access the demo from the outside by following the delegated gateway guide.
  • Federate zone into a multizone deployment.

  • Read the full documentation to learn about all the capabilities of Kuma.

  • Chat with us at the official Kuma Slack for questions or feedback.