Skip to content
Kong Logo | Kong Docs Logo
search
  • We're Hiring!
  • Docs
    • Kong Gateway
    • Kong Konnect
    • Kong Mesh
    • Plugin Hub
    • decK
    • Kubernetes Ingress Controller
    • Insomnia
    • Kuma

    • Docs contribution guidelines
  • Plugin Hub
  • Support
  • Community
  • Kong Academy
Get a Demo Start Free Trial
  • Kong Gateway
  • Kong Konnect
  • Kong Mesh
  • Plugin Hub
  • decK
  • Kubernetes Ingress Controller
  • Insomnia
  • Kuma

  • Docs contribution guidelines
  • 2.1.x (latest)
  • 2.0.x
  • 1.9.x
  • 1.8.x
  • 1.7.x
  • 1.6.x
  • 1.5.x
  • 1.4.x
  • 1.3.x
  • 1.2.x
  • 1.1.x
  • 1.0.x
    • Introduction to Kong Mesh
    • What is Service Mesh?
    • How Kong Mesh works
    • Deployments
    • Version support policy
    • Stability
    • Release notes
    • Installation Options
    • Kubernetes
    • Helm
    • OpenShift
    • Docker
    • Amazon ECS
    • Amazon Linux
    • Red Hat
    • CentOS
    • Debian
    • Ubuntu
    • macOS
    • Windows
    • Explore Kong Mesh with the Kubernetes demo app
    • Explore Kong Mesh with the Universal demo app
    • Standalone deployment
    • Multi-zone deployment
    • License
    • Overview
    • Data plane proxy
    • Data plane on Kubernetes
    • Data plane on Universal
    • Gateway
    • Zone Ingress
    • Zone Egress
    • CLI
    • GUI
    • Observability
    • Inspect API
    • Kubernetes Gateway API
    • Networking
    • Service Discovery
    • DNS
    • Kong Mesh CNI
    • Transparent Proxying
    • IPv6 support
    • Secure access across Kong Mesh components
    • Secrets
    • Kong Mesh API Access Control
    • API server authentication
    • Data plane proxy authentication
    • Zone proxy authentication
    • Data plane proxy membership
    • Dataplane Health
    • Fine-tuning
    • Control Plane Configuration
    • Upgrades
    • Requirements
    • Introduction
    • General notes about Kong Mesh policies
    • Applying Policies
    • How Kong Mesh chooses the right policy to apply
    • Understanding TargetRef policies
    • Protocol support in Kong Mesh
    • Mesh
    • Mutual TLS
    • Traffic Permissions
    • Traffic Route
    • Traffic Metrics
    • Traffic Trace
    • Traffic Log
    • Locality-aware Load Balancing
    • Fault Injection
    • Health Check
    • Circuit Breaker
    • Proxy Template
    • External Service
    • Retry
    • Timeout
    • Rate Limit
    • Virtual Outbound
    • MeshGateway
    • MeshGatewayRoute
    • Service Health Probes
    • MeshTrace (Beta)
    • MeshAccessLog (Beta)
    • MeshTrafficPermission (Beta)
    • Overview
    • HashiCorp Vault CA
    • Amazon ACM Private CA
    • cert-manager Private CA
    • OPA policy support
    • Multi-zone authentication
    • FIPS support
    • Certificate Authority rotation
    • Role-Based Access Control
    • UBI Images
    • Windows Support
    • Auditing
    • HTTP API
    • Annotations and labels in Kubernetes mode
    • Kong Mesh data collection
      • Mesh
      • CircuitBreaker
      • ExternalService
      • FaultInjection
      • HealthCheck
      • MeshGateway
      • MeshGatewayRoute
      • ProxyTemplate
      • RateLimit
      • Retry
      • Timeout
      • TrafficLog
      • TrafficPermission
      • TrafficRoute
      • TrafficTrace
      • VirtualOutbound
      • Dataplane
      • ZoneEgress
      • ZoneIngress
      • kuma-cp
      • kuma-dp
      • kumactl
    • Kuma-cp configuration reference

github-edit-pageEdit this page

report-issueReport an issue

enterprise-switcher-iconSwitch to OSS

On this page
  • Prerequisites
  • Set up and run
  • Explore the mesh
  • Enable Mutual TLS and Traffic Permissions
  • Builtin gateways
  • Explore Observability features
    • Traffic Metrics
    • Traffic logs and trace
  • Next steps
Kong Mesh
2.0.x
  • Home
  • Kong Mesh
  • Quickstart
  • Explore Kong Mesh with the Kubernetes demo app
You are browsing documentation for an outdated version. See the latest documentation here.

Explore Kong Mesh with the Kubernetes demo app

To start learning how Kong Mesh 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 Kong Mesh provides to help you control and monitor traffic, track resource status, and more.

The 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.

Prerequisites

  • Kong Mesh installed on your Kubernetes cluster
  • Demo app downloaded from GitHub:

    git clone https://github.com/kumahq/kuma-counter-demo.git
    

Set up and run

Two different YAML files are available:

  • demo.yaml installs the basic resources
  • demo-v2.yaml installs the frontend service with different colors. This lets you more clearly view routing across multiple versions, for example.
  • gateway.yaml installs a builtin gateway
  1. Install resources in a kuma-demo namespace:

    kubectl apply -f demo.yaml
    
  2. Port forward the service to the namespace on port 5000:

    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.

Explore the mesh

The demo app includes the kuma.io/sidecar-injection label enabled on the kuma-demo namespace. This means that Kong Mesh already knows that it needs to automatically inject a sidecar proxy to every Kubernetes deployment in the default Mesh resource:

apiVersion: v1
kind: Namespace
metadata:
  name: kuma-demo
  namespace: kuma-demo
  labels:
    kuma.io/sidecar-injection: enabled

Run:

kubectl get namespace kuma-demo -oyaml

to see what the full namespace looks like:

apiVersion: v1
kind: Namespace
metadata:
  annotations:
    kubectl.kubernetes.io/last-applied-configuration: |
      {"apiVersion":"v1","kind":"Namespace","metadata":{"labels":{"kuma.io/sidecar-injection":"enabled"},"name":"kuma-demo"}}
  labels:
    kuma.io/sidecar-injection: enabled
  creationTimestamp: "2021-08-13T09:17:48Z"
  labels:
    kubernetes.io/metadata.name: kuma-demo
  name: kuma-demo
  resourceVersion: "749"
  uid: 66b1279e-e49c-427d-af01-3adc91e505c1
spec:
  finalizers:
  - kubernetes
status:
  phase: Active

You can view the sidecar proxies that are connected to the Kong Mesh control plane:

GUI (Read-Only)
HTTP API (Read-Only)
kumactl (Read-Only)

Kong Mesh ships with a read-only GUI that you can use to retrieve Kong Mesh resources. By default the GUI listens on the API port and defaults to :5681/gui.

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

kubectl port-forward svc/kong-mesh-control-plane -n kong-mesh-system 5681:5681

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

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

By default the HTTP API listens on port 5681. To access Kong Mesh we need to first port-forward the API service with:

kubectl port-forward svc/kong-mesh-control-plane -n kong-mesh-system 5681:5681

And then you can 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 Kong Mesh resources. The kumactl binary is a client to the Kong Mesh HTTP API, you will need to first port-forward the API service with:

kubectl port-forward svc/kong-mesh-control-plane -n kong-mesh-system 5681:5681

and then run kumactl, for example:

kumactl get dataplanes
# MESH      NAME                                              TAGS
# 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
# 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:

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

Enable Mutual TLS and Traffic Permissions

By default, the network is unsecure and not encrypted. We can change this with Kong Mesh by enabling the Mutual TLS policy to provision a dynamic Certificate Authority (CA) on the default Mesh 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, Kong Mesh 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 kumactl.

Builtin gateways

The resources for creating a builtin gateway is included with kuma-counter-demo in gateway.yaml as well:

  • a MeshGateway that sets up the listeners
  • a MeshGatewayRoute that directs requests to the demo app
  • a MeshGatewayInstance that manages and deploys proxies to serve gateway traffic

Learn more about builtin gateways in the dedicated gateway docs.

Explore Observability features

With 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.

Traffic Metrics

One of the most important policies that Kong Mesh provides out of the box is Traffic Metrics.

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 default Mesh 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 (admin).

Kong Mesh automatically installs three dashboard that are ready to use:

  • Kong Mesh Mesh: to visualize the status of the overall Mesh.
  • Kong Mesh Dataplane: to visualize metrics for a single individual dataplane.
  • Kong Mesh Service to Service: to visualize traffic metrics for our services.

You can now explore the dashboards and see the metrics being populated over time.

Traffic logs and trace

You can check out specific instructions on Traffic Log and Traffic Trace policies in separate documents.

Next steps

  • Explore the Policies available to govern and orchestrate your service traffic.
  • Read the full documentation to learn about all the capabilities of Kong Mesh.
  • Chat with us at the official Kuma Slack for questions or feedback.
Thank you for your feedback.
Was this page useful?
  • Kong
    THE CLOUD CONNECTIVITY COMPANY

    Kong powers reliable digital connections across APIs, hybrid and multi-cloud environments.

    • Company
    • Customers
    • Events
    • Investors
    • Careers Hiring!
    • Partners
    • Press
    • Contact
  • Products
    • Kong Konnect
    • Kong Gateway
    • Kong Mesh
    • Get Started
    • Pricing
  • Resources
    • eBooks
    • Webinars
    • Briefs
    • Blog
    • API Gateway
    • Microservices
  • Open Source
    • Install Kong Gateway
    • Kong Community
    • Kubernetes Ingress
    • Kuma
    • Insomnia
  • Solutions
    • Decentralize
    • Secure & Govern
    • Create a Dev Platform
    • API Gateway
    • Kubernetes
    • Service Mesh
Star
  • Terms•Privacy
© Kong Inc. 2023