You are browsing documentation for the next version of Kuma. Use this version at your own risk.
Explore Kuma with the Kubernetes demo app
To start learning how Kuma works, you can download and run a simple demo application that consists of two services:
demo-app: web application that lets you increment a numeric counter
redis: data store for the counter
This guide also introduces some of the tools Kuma provides to help you control and monitor traffic, track resource status, and more.
demo-app service 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) where the Redis instance is running. This name is displayed in the browser.
The zone key is purely static and arbitrary. Different zone values for different Redis instances let you keep track of which Redis instance stores the counter if you manage routes across different zones, clusters, and clouds.
git clone https://github.com/kumahq/kuma-counter-demo.git
Set up and run
Two different YAML files are available:
demo.yamlinstalls the basic resources
demo-v2.yamlinstalls the frontend service with different colors. This lets you more clearly view routing across multiple versions, for example.
gateway.yamlinstalls a builtin gateway
Install resources in a
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
In a browser, go to
127.0.0.1:5000and increment the counter.
Explore the mesh
The demo app includes the
kuma.io/sidecar-injection label enabled on the
kuma-demo namespace. This means that Kuma
that it needs to automatically inject a sidecar proxy to every Kubernetes deployment in the
apiVersion: v1 kind: Namespace metadata: name: kuma-demo labels: kuma.io/sidecar-injection: enabled
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
To access Kuma we need to first port-forward the API service with:
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.
Enable Mutual TLS and Traffic Permissions
By default, the network is unsecure and not encrypted. We can change this with Kuma by enabling the Mutual TLS policy to provision a dynamic Certificate Authority (CA) on the
resource that will automatically assign TLS certificates to our services (more specifically to the injected dataplane proxies running alongside the services).
We can enable Mutual TLS with a
builtin CA backend by executing:
echo "apiVersion: kuma.io/v1alpha1 kind: Mesh metadata: name: default spec: mtls: enabledBackend: ca-1 backends: - name: ca-1 type: builtin" | kubectl 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:
kubectl delete trafficpermission 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:
echo "apiVersion: kuma.io/v1alpha1 kind: TrafficPermission mesh: default metadata: name: allow-all-default spec: sources: - match: kuma.io/service: '*' destinations: - match: kuma.io/service: '*'" | kubectl apply -f -
By doing so every request we now make on our demo application at
127.0.0.1:5000/ is not only working again, but it is 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
The resources for creating a builtin gateway is included with
gateway.yaml as well:
MeshGatewaythat sets up the listeners
MeshGatewayRoutethat directs requests to the demo app
MeshGatewayInstancethat manages and deploys proxies to serve gateway traffic
Learn more about builtin gateways in the dedicated gateway docs.
Explore Observability features
kumactl you can quickly install all observability components (metrics, logs, tracing) with a single command:
kumactl install observability | kubectl apply -f -
Once that is installed you can use different policies to configure each component.
With Traffic Metrics we can leverage Prometheus and Grafana to provide powerful dashboards that visualize the overall traffic activity of our application and the status of the service mesh.
We can now go ahead and enable metrics on our Mesh object by executing:
echo "apiVersion: kuma.io/v1alpha1 kind: Mesh metadata: name: default spec: mtls: enabledBackend: ca-1 backends: - name: ca-1 type: builtin metrics: enabledBackend: prometheus-1 backends: - name: prometheus-1 type: prometheus" | kubectl apply -f -
This will enable the
prometheus metrics backend on the
and automatically collect metrics for all of our traffic.
Increment the counter to generate traffic. Then you can expose the Grafana dashboard:
kubectl port-forward svc/grafana -n mesh-observability 3000:80
and access the dashboard at 127.0.0.1:3000 with default credentials for both the username (
admin) and the password (
Kuma automatically installs three dashboard that are ready to use:
Kuma Mesh: to visualize the status of the overall Mesh.
Kuma Dataplane: to visualize metrics for a single individual dataplane.
Kuma Service to Service: to visualize traffic metrics for our services.
You can now explore the dashboards and see the metrics being populated over time.