Welcome to a sample application that demonstrates the Kuma service mesh in action. Kuma is designed to work across Kubernetes and VMs environments, with support for multi-zone deployments across many different clusters, data centers, and clouds.
To learn more about Kuma, see the Kuma repository.
Kuma is a CNCF Sandbox project.
The application consists of two services:
- A
demo-app
service that presents a web application that allows us to increment a numeric counter - A
redis
service that stores the counter
The demo-app
service presents a browser interface that listens on port 5000
. When it starts, it expects to find a zone
key in Redis that specifies the name of the datacenter (or cluster) that the current redis
instance belongs to. This name is then displayed in the demo-app
GUI.
The zone
key is purely static and arbitrary, but by having different zone
values across different redis
instances, we know at any given time from which Redis instance we are fetching/incrementing our counter when we route across a distributed environment across many zones, clusters and clouds.
-
Run
redis
- (Kubernetes setup) on the default port
6379
and set a defaultzone
name:
$ redis-server $ redis-cli set zone local
- (Universal setup) on port
26379
and set a defaultzone
name:
$ redis-server --port 26379 $ redis-cli -p 26379 set zone local
- (Kubernetes setup) on the default port
-
Install and start
demo-app
on the default port5000
:$ npm install --prefix=app/ $ npm start --prefix=app/
-
(Only for Kubernetess) Navigate to
127.0.0.1:5000
and increment the counter!
- First we need to generate two tokens:
-
One for redis
-
Second for node-app To do so we need to run:
$ kumactl generate dataplane-token --name=redis > kuma-token-redis $ kumactl generate dataplane-token --name=app > kuma-token-app
- Then we need to generate two DPPs:
- For redis:
kuma-dp run \
--cp-address=https://localhost:5678/ \
--dns-enabled=false \
--dataplane-token-file=kuma-token-redis \
--dataplane="type: Dataplane
mesh: default
name: redis
networking:
address: 127.0.0.1 # Or any public address (needs to be reachable by every other dp in the zone)
inbound:
- port: 16379
servicePort: 26379
tags:
kuma.io/service: redis
kuma.io/protocol: tcp"
- And for app:
kuma-dp run \
--cp-address=https://localhost:5678/ \
--dns-enabled=false \
--dataplane-token-file=kuma-token-app \
--dataplane="type: Dataplane
mesh: default
name: app
networking:
address: 127.0.0.1 # Or any public address (needs to be reachable by every other dp in the zone)
outbound:
- port: 6379
tags:
kuma.io/service: redis
inbound:
- port: 15000
servicePort: 5000
tags:
kuma.io/service: app
kuma.io/protocol: http
admin:
port: 9902"
- Navigate to
127.0.0.1:5000
and increment the counter!
Two different YAML files are provided for Kubernetes:
- one that installs the basic resources
- one that installs a version of the frontend service with different colors (useful to demonstrate routing across multiple versions, for example)
-
Install the basic demo resources in a
kuma-demo
namespace:$ kubectl apply -f demo.yaml
-
Port-forward the service to the namespace on port
5000
:$ kubectl port-forward svc/demo-app -n kuma-demo 5000:5000
-
Navigate to
127.0.0.1:5000
and increment the counter!
An additional YAML file gateway.yaml
is provided for setting up a
Kuma MeshGateway
to
serve the demo app.
-
Install the
MeshGateway
resources:$ kubectl apply -f gateway.yaml
-
If your k8s environment supports
LoadBalancer
Services
, you can access the gateway via its external IP:$ curl $(kubectl get svc -n kuma-demo demo-app-gateway -o=jsonpath='{.status.loadBalancer.ingress[0].ip}')
Otherwise you can access the gateway inside the cluster via its cluster IP:
$ kubectl run curl-gateway --rm -i --tty --image nicolaka/netshoot --restart=OnFailure -- curl $(kubectl get svc -n kuma-demo demo-app-gateway -o=jsonpath='{.spec.clusterIP}')
To install the v2
version of the demo application, we can apply the following YAML file instead, which will change the colors and version number of our frontend application:
$ kubectl apply -f demo-v2.yaml
By inspecting the file we can see that the demo-v2.yaml
file sets the following environment variables - which are also available on VMs - to different values so that we have immediate visual feedback that a new version is runnning.
We can configure the following environment variables when running demo-app
:
REDIS_HOST
: Determines the hostname to use when connecting to Redis. Default is127.0.0.1
.REDIS_PORT
: Determines the port to use when connecting to Redis. Default is6379
.APP_VERSION
: Lets you change the version number displayed in the main page ofdemo-app
. Default is1.0
.APP_COLOR
: Lets you change background color of thedemo-app
main page. Default is#efefef
.
The APP_VERSION
and APP_COLOR
environment variables are handy when we want to create different versions of demo-app
and get immediate visual feedback when routing across them.