Deploy Kuma on Universal

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

Install Kuma

Install a Kuma control plane using the Docker images:

  • kuma-cp: at docker.io/kumahq/kuma-cp:2.7.7
  • kuma-dp: at docker.io/kumahq/kuma-dp:2.7.7
  • kumactl: at docker.io/kumahq/kumactl:2.7.7

You can freely docker pull these images to start using Kuma, as we will demonstrate in the following steps.

Do one of the following to download Kuma:

  • Run the following script to automatically detect the operating system (Amazon Linux, CentOS, RedHat, Debian, Ubuntu, and macOS) and download Kuma:

    1. curl -L https://kuma.io/installer.sh | VERSION=2.7.7 sh -

    ```

  • Download the distribution manually. Then, extract the archive with: tar xvzf kuma-2.7.x--.tar.gz.

Generate tokens

Create a token for Redis and a token for the app (both are valid for 30 days):

  1. kumactl generate dataplane-token --tag kuma.io/service=redis --valid-for=720h > kuma-token-redis
  2. kumactl generate dataplane-token --tag kuma.io/service=app --valid-for=720h > kuma-token-app

This requires authentication unless executed against a control-plane running on localhost. If kuma-cp is running inside a Docker container, see docker authentication docs .

Create a data plane proxy for each service

Because this is a quickstart, we don’t setup certificates for communication between the data plane proxies and the control plane. You’ll see a warning like the following in the kuma-dp logs:

  1. 2024-07-25T20:06:36.082Z    INFO    dataplane    [WARNING] The data plane proxy cannot verify the identity of the control plane because you are not setting the "--ca-cert-file" argument or setting the KUMA_CONTROL_PLANE_CA_CERT environment variable.

This isn’t related to mTLS between services.

For Redis:

  1. kuma-dp run \
  2.   --cp-address=https://localhost:5678/ \
  3.   --dns-enabled=false \
  4.   --dataplane-token-file=kuma-token-redis \
  5.   --dataplane="
  6.   type: Dataplane
  7.   mesh: default
  8.   name: redis
  9.   networking: 
  10.     address: 127.0.0.1
  11.     inbound: 
  12.       - port: 16379
  13.         servicePort: 26379
  14.         serviceAddress: 127.0.0.1
  15.         tags: 
  16.           kuma.io/service: redis
  17.           kuma.io/protocol: tcp
  18.     admin:
  19.       port: 9901"

For the demo app:

  1. kuma-dp run \
  2.   --cp-address=https://localhost:5678/ \
  3.   --dns-enabled=false \
  4.   --dataplane-token-file=kuma-token-app \
  5.   --dataplane="
  6.   type: Dataplane
  7.   mesh: default
  8.   name: app
  9.   networking: 
  10.     address: 127.0.0.1
  11.     outbound:
  12.       - port: 6379
  13.         tags:
  14.           kuma.io/service: redis
  15.     inbound: 
  16.       - port: 15000
  17.         servicePort: 5000
  18.         serviceAddress: 127.0.0.1
  19.         tags: 
  20.           kuma.io/service: app
  21.           kuma.io/protocol: http
  22.     admin:
  23.       port: 9902"

Deploy the demo application

  1. Run redis as a daemon on port 26379 and set a default zone name:

    1.   redis-server --port 26379 --daemonize yes
    2.   redis-cli -p 26379 set zone local

  2. Install and start demo-app on the default port 5000:

    1.   npm install --prefix=app/
    2.   npm start --prefix=app/

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

Explore the 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 and defaults to :5681/gui.

You can navigate to 127.0.0.1:5681/meshes/default/dataplanes to see the connected dataplanes.

Kuma ships with a read-only HTTP API that you can use to retrieve Kuma resources.

By default the HTTP API listens on port 5681.

Navigate to 127.0.0.1:5681/meshes/default/dataplanes to see the connected dataplanes.

You can use the kumactl CLI to perform read-only operations on Kuma resources. The kumactl binary is a client to the Kuma HTTP API, you will need to first port-forward the API service with:

Run kumactl, for example:

  1. kumactl get dataplanes
  2. # MESH      NAME                                              TAGS
  3. # default   kuma-demo-app-68758d8d5d-dddvg.kuma-demo          app=kuma-demo-demo-app env=prod pod-template-hash=68758d8d5d protocol=http service=demo-app_kuma-demo_svc_5000 version=v8
  4. # default   redis-master-657c58c859-5wkb4.kuma-demo           app=redis pod-template-hash=657c58c859 protocol=tcp role=master service=redis_kuma-demo_svc_6379 tier=backend

You can configure kumactl to point to any zone kuma-cp instance by running:

  1. kumactl config control-planes add --name=XYZ --address=http://{address-to-kuma}:5681

Introduction to 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.

  1. To create a MeshTrafficPermission policy that allows all traffic, do the following:
  1.   echo 'type: MeshTrafficPermission 
  2.   name: allow-all 
  3.   mesh: default 
  4.   spec: 
  5.     targetRef: 
  6.       kind: Mesh 
  7.     from: 
  8.       - targetRef: 
  9.           kind: Mesh 
  10.       default: 
  11.         action: Allow' | kumactl apply -f -
  1. To create a Mesh policy with a builtin CA backend, do the following:
  1.   echo 'type: Mesh
  2.     name: default
  3.     mtls:
  4.       enabledBackend: ca-1
  5.       backends:
  6.       - name: ca-1
  7.         type: builtin' | kumactl apply -f -

Once Mutual TLS has been enabled, Kuma will not allow traffic to flow freely across our services unless we explicitly have a Traffic Permission policy that describes what services can be consumed by other services. By default, a very permissive traffic permission is created.

For the sake of this demo, we will delete it:

  1. kumactl delete traffic-permission allow-all-default

You can try to make requests to the demo application at 127.0.0.1:5000/ and you will notice that they will not work.

Now, let’s add back the default traffic permission:

  1. echo 'type: MeshTrafficPermission
  2. name: allow-all
  3. mesh: default
  4. spec:
  5.   targetRef:
  6.     kind: Mesh
  7.   from:
  8.   - targetRef:
  9.       kind: Mesh
  10.     default:
  11.       action: Allow' | kumactl apply -f -

By doing so every request, we now make sure our demo application at 127.0.0.1:5000/ is not only working again, but it’s automatically encrypted and secure.

As usual, you can visualize the Mutual TLS configuration and the Traffic Permission policies we have just applied via the GUI, the HTTP API or kumactl.

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.