Ubuntu

Don't forget! The Official Documentation of Kuma is a great place to learn about both basic and more advanced topics.

To install and run Kuma on Ubuntu execute the following steps:

1. Download and run Kuma

You can download Kuma from here or by running:

$ wget https://kong.bintray.com/kuma/kuma-0.3.0-ubuntu-amd64.tar.gz
1

You can extract the archive and check the contents of the bin folder by running:

$ tar xvzf kuma-0.3.0-ubuntu-amd64.tar.gz
$ cd bin/ && ls
envoy   kuma-cp   kuma-dp   kuma-tcp-echo kumactl
1
2
3

As you can see Kuma already ships with an envoy executable ready to use.

To run Kuma execute:

$ kuma-cp run
1

Kuma automatically creates a Mesh entity with name default.

By default this will run Kuma with a memory backend, but you can change this to use PostgreSQL by updating the conf/kuma-cp.conf file.

2. Start the Data-Plane

Before starting the sidecar proxy data-plane, the service should already be running. For demo purposes, we can start a sample TCP server that comes bundled with Kuma and that echoes back the requests we are sending to it:

$ kuma-tcp-echo -port 9000
1

You can then consume the service by making requests to 127.0.0.1:9000, like: curl http://127.0.0.1:9000/ or nc 127.0.0.1 9000

We now have our control-plane and services running. For each service we can now provision a Dataplane Entity that configures the inbound and outbound networking configuration:

$ echo "type: Dataplane
mesh: default
name: dp-echo-1
networking:
  inbound:
  - interface: 127.0.0.1:10000:9000
    tags:
      service: echo" | kumactl apply -f -
1
2
3
4
5
6
7
8

Next, generate a data-plane token that is used by the control-plane to verify identity of the data-plane:

$ kumactl generate dataplane-token --dataplane=dp-echo-1 > /tmp/kuma-dp-echo-1
1

And run the actual data-plane process with:

$ kuma-dp run \
  --name=dp-echo-1 \
  --mesh=default \
  --cp-address=http://127.0.0.1:5681 \
  --dataplane-token-file=/tmp/kuma-dp-echo-1
1
2
3
4
5

You can now consume the service on port 10000, which will be internally redirected to the service on port 9000:

$ curl http://127.0.0.1:10000
GET / HTTP/1.1
Host: 127.0.0.1:10000
User-Agent: curl/7.54.0
Accept: */*
1
2
3
4
5

3. Apply Policies

Now you can start applying Policies to your default Service Mesh, like Mutual TLS:

$ echo "type: Mesh
name: default
mtls:
  enabled: true 
  ca:
    builtin: {}" | kumactl apply -f -
1
2
3
4
5
6

4. Done!

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

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

If you consume the service again on port 10000, you will now notice that the communication requires now a TLS connection.

You can now review the entities created by Kuma by using the kumactl CLI. For example you can list the Meshes:

$ kumactl get meshes
NAME
default
1
2
3

and you can list the data-planes that have been registered, and their status:

$ kumactl get dataplanes
MESH      NAME        TAGS
default   dp-echo-1   service=echo

$ kumactl inspect dataplanes
MESH      NAME        TAGS              STATUS   LAST CONNECTED AGO   LAST UPDATED AGO   TOTAL UPDATES   TOTAL ERRORS
default   dp-echo-1   service=echo      Online   19s                  18s                2               0
1
2
3
4
5
6
7