Skip to content
Kong Docs are moving soon! Our docs are migrating to a new home. You'll be automatically redirected to the new site in the future. In the meantime, view this page on the new site!
Kong Logo | Kong Docs Logo
  • Docs
    • Explore the API Specs
      View all API Specs View all API Specs View all API Specs arrow image
    • Documentation
      API Specs
      Kong Gateway
      Lightweight, fast, and flexible cloud-native API gateway
      Kong Konnect
      Single platform for SaaS end-to-end connectivity
      Kong AI Gateway
      Multi-LLM AI Gateway for GenAI infrastructure
      Kong Mesh
      Enterprise service mesh based on Kuma and Envoy
      decK
      Helps manage Kong’s configuration in a declarative fashion
      Kong Ingress Controller
      Works inside a Kubernetes cluster and configures Kong to proxy traffic
      Kong Gateway Operator
      Manage your Kong deployments on Kubernetes using YAML Manifests
      Insomnia
      Collaborative API development platform
  • Plugin Hub
    • Explore the Plugin Hub
      View all plugins View all plugins View all plugins arrow image
    • Functionality View all View all arrow image
      View all plugins
      AI's icon
      AI
      Govern, secure, and control AI traffic with multi-LLM AI Gateway plugins
      Authentication's icon
      Authentication
      Protect your services with an authentication layer
      Security's icon
      Security
      Protect your services with additional security layer
      Traffic Control's icon
      Traffic Control
      Manage, throttle and restrict inbound and outbound API traffic
      Serverless's icon
      Serverless
      Invoke serverless functions in combination with other plugins
      Analytics & Monitoring's icon
      Analytics & Monitoring
      Visualize, inspect and monitor APIs and microservices traffic
      Transformations's icon
      Transformations
      Transform request and responses on the fly on Kong
      Logging's icon
      Logging
      Log request and response data using the best transport for your infrastructure
  • Support
  • Community
  • Kong Academy
Get a Demo Start Free Trial
Kong Mesh
2.2.x
  • Home icon
  • Kong Mesh
  • Quickstart
  • Explore Kong Mesh with the Universal demo app
github-edit-pageEdit this page
report-issueReport an issue
  • Kong Gateway
  • Kong Konnect
  • Kong Mesh
  • Kong AI Gateway
  • Plugin Hub
  • decK
  • Kong Ingress Controller
  • Kong Gateway Operator
  • Insomnia
  • Kuma

  • Docs contribution guidelines
  • dev
  • 2.10.x (latest)
  • 2.9.x
  • 2.8.x
  • 2.7.x (LTS)
  • 2.6.x
  • 2.5.x
  • 2.4.x
  • 2.3.x
  • 2.2.x
  • Introduction
    • About service meshes
    • Overview of Kong Mesh
    • How Kong Mesh works
    • Architecture
    • Stages of software availability
    • Version support policy
    • Mesh requirements
    • Release notes
  • Getting Started
  • Kong Mesh in Production
    • Overview
    • Deployment topologies
      • Overview
      • Standalone deployment
      • Multi-zone deployment
    • Install kumactl
    • Use Kong Mesh
    • Control plane deployment
      • Kong Mesh license
      • Deploy a standalone control plane
      • Deploy a multi-zone global control plane
      • Zone Ingress
      • Zone Egress
      • Configure zone proxy authentication
      • Control plane configuration reference
      • Systemd
    • Create multiple service meshes in a cluster
    • Data plane configuration
      • Data plane proxy
      • Configure the data plane on Kubernetes
      • Configure the data plane on Universal
      • Configure the Kong Mesh CNI
      • Configure transparent proxying
      • IPv6 support
    • Secure your deployment
      • Manage secrets
      • Authentication with the API server
      • Authentication with the data plane proxy
      • Configure data plane proxy membership
      • Secure access across services
      • Kong Mesh RBAC
      • FIPS support
    • Kong Mesh user interface
    • Upgrades and tuning
      • Upgrade Kong Mesh
      • Performance fine-tuning
  • Deploy
    • Explore Kong Mesh with the Kubernetes demo app
    • Explore Kong Mesh with the Universal demo app
  • Explore
    • Gateway
      • Delegated
      • Builtin
    • CLI
      • kumactl
    • Observability
      • Demo setup
      • Control plane metrics
      • Configuring Prometheus
      • Configuring Grafana
      • Configuring Datadog
      • Observability in multi-zone
    • Inspect API
      • Matched policies
      • Affected data plane proxies
      • Envoy proxy configuration
    • Kubernetes Gateway API
      • Installation
      • Usage
      • TLS termination
      • Customization
      • Multi-mesh
      • Multi-zone
      • How it works
  • Networking
    • Service Discovery
    • DNS
      • How it works
      • Installation
      • Configuration
      • Usage
    • Non-mesh traffic
      • Incoming
      • Outgoing
    • Transparent Proxying
  • Monitor & manage
    • Dataplane Health
      • Circuit Breaker Policy
      • Kubernetes and Universal Service Probes
      • Health Check Policy
    • Control Plane Configuration
      • Modifying the configuration
      • Inspecting the configuration
      • Store
  • Policies
    • 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
    • Mutual TLS
      • Usage of "builtin" CA
      • Usage of "provided" CA
      • Permissive mTLS
      • Certificate Rotation
    • Traffic Permissions
      • Usage
      • Access to External Services
    • Traffic Route
      • Usage
    • Traffic Metrics
      • Expose metrics from data plane proxies
      • Expose metrics from applications
      • Override Prometheus settings per data plane proxy
      • Filter Envoy metrics
      • Secure data plane proxy metrics
    • Traffic Trace
      • Add a tracing backend to the mesh
      • Add TrafficTrace resource
    • Traffic Log
      • Add a logging backend
      • Add a TrafficLog resource
      • Logging external services
      • Builtin Gateway support
      • Access Log Format
    • Locality-aware Load Balancing
      • Enabling locality-aware load balancing
    • Fault Injection
      • Usage
      • Matching
    • Health Check
      • Usage
      • Matching
    • Circuit Breaker
      • Usage
      • Matching
      • Builtin Gateway support
      • Non-mesh traffic
    • External Service
      • Usage
      • Builtin Gateway support
    • Retry
      • Usage
      • Matching
      • Builtin Gateway support
    • Timeout
      • Usage
      • Configuration
      • Default general-purpose Timeout policy
      • Matching
      • Builtin Gateway support
      • Inbound timeouts
      • Non-mesh traffic
    • Rate Limit
      • Usage
      • Matching destinations
      • Builtin Gateway support
    • Virtual Outbound
      • Examples
    • MeshGateway
      • TLS Termination
    • MeshGatewayRoute
      • Listener tags
      • Matching
      • Filters
      • Reference
    • MeshGatewayInstance
    • Service Health Probes
      • Kubernetes
      • Universal probes
    • MeshAccessLog (Beta)
      • TargetRef support matrix
      • Configuration
      • Examples
    • MeshCircuitBreaker (Beta)
      • TargetRef support matrix
      • Configuration
      • Examples
    • MeshFaultInjection (Beta)
      • TargetRef support matrix
      • Configuration
      • Examples
    • MeshHealthCheck (Beta)
      • TargetRef support matrix
      • Configuration
      • Examples
    • MeshHTTPRoute (Beta)
      • TargetRef support matrix
      • Configuration
      • Examples
      • Merging
    • MeshProxyPatch (Beta)
      • TargetRef support matrix
      • Configuration
      • Examples
      • Merging
    • MeshRateLimit (Beta)
      • TargetRef support matrix
      • Configuration
      • Examples
    • MeshRetry (Beta)
      • TargetRef support matrix
      • Configuration
      • Examples
    • MeshTimeout (Beta)
      • TargetRef support matrix
      • Configuration
      • Examples
    • MeshTrace (Beta)
      • TargetRef support matrix
      • Configuration
      • Examples
    • MeshTrafficPermission (Beta)
      • TargetRef support matrix
      • Configuration
      • Examples
    • MeshLoadBalancingStrategy (Beta)
      • TargetRef support matrix
      • Configuration
      • Examples
    • OPA policy
    • MeshOPA (beta)
    • MeshGlobalRateLimit (beta)
  • Enterprise Features
    • Overview
    • HashiCorp Vault CA
    • Amazon ACM Private CA
    • cert-manager Private CA
    • OPA policy support
    • MeshOPA (beta)
    • Multi-zone authentication
    • FIPS support
    • Certificate Authority rotation
    • Role-Based Access Control
    • UBI Images
    • Windows Support
    • ECS Support
    • Auditing
    • MeshGlobalRateLimit (beta)
  • Reference
    • HTTP API
    • Kubernetes annotations and labels
    • Kuma data collection
    • Control plane configuration reference
    • Envoy proxy template
  • Community
    • Contribute to Kuma
enterprise-switcher-icon Switch to OSS
On this pageOn this page
  • Prerequisites
  • Set up
  • Generate tokens
  • Create a data plane proxy for each service
  • Run
  • Explore the mesh
  • Enable Mutual TLS and Traffic Permissions
  • Explore Traffic Metrics
  • Next steps
You are browsing documentation for an older version. See the latest documentation here.

Explore Kong Mesh with the Universal 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

  • Redis installed
  • Kong Mesh installed
  • Demo app downloaded from GitHub:

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

To explore traffic metrics with the demo app, you also need to set up Prometheus. See the traffic metrics policy documentation.

Set up

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

    redis-server --port 26379 --daemonize yes
    redis-cli -p 26379 set zone local
    
  2. Install and start demo-app on the default port 5000:

    npm install --prefix=app/
    npm start --prefix=app/
    

Generate tokens

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

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

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

Create a data plane proxy for each service

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
    inbound: 
      - port: 16379
        servicePort: 26379
        serviceAddress: 127.0.0.1
        tags: 
          kuma.io/service: redis
          kuma.io/protocol: tcp
    admin:
      port: 9901"

And for the demo 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
    outbound:
      - port: 6379
        tags:
          kuma.io/service: redis
    inbound: 
      - port: 15000
        servicePort: 5000
        serviceAddress: 127.0.0.1
        tags: 
          kuma.io/service: app
          kuma.io/protocol: http
    admin:
      port: 9902"

Run

Navigate to 127.0.0.1:5000 and increment the counter.

Explore the mesh

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

usage GUI (Read-Only)
usage HTTP API (Read/Write)
usage kumactl (Read/Write)

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.

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

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.

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:

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:

cat <<EOF | kumactl apply -f -
type: Mesh
name: default
mtls:
  enabledBackend: ca-1
  backends:
  - name: ca-1
    type: builtin
EOF

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:

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:

cat <<EOF | kumactl apply -f -
type: TrafficPermission
name: allow-all-default
mesh: default
sources:
  - match:
      kuma.io/service: '*'
destinations:
  - match:
      kuma.io/service: '*'
EOF

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.

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

cat <<EOF | kumactl apply -f -
type: Mesh
name: default
mtls:
  enabledBackend: ca-1
  backends:
  - name: ca-1
    type: builtin
metrics:
  enabledBackend: prometheus-1
  backends:
  - name: prometheus-1
    type: prometheus
    conf:
      skipMTLS: true
EOF

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

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?
Too much on your plate? close cta icon
More features, less infrastructure with Kong Konnect. 1M requests per month for free.
Try it for Free
  • Kong
    Powering the API world

    Increase developer productivity, security, and performance at scale with the unified platform for API management, service mesh, and ingress controller.

    • Products
      • Kong Konnect
      • Kong Gateway Enterprise
      • Kong Gateway
      • Kong Mesh
      • Kong Ingress Controller
      • Kong Insomnia
      • Product Updates
      • Get Started
    • Documentation
      • Kong Konnect Docs
      • Kong Gateway Docs
      • Kong Mesh Docs
      • Kong Insomnia Docs
      • Kong Konnect Plugin Hub
    • Open Source
      • Kong Gateway
      • Kuma
      • Insomnia
      • Kong Community
    • Company
      • About Kong
      • Customers
      • Careers
      • Press
      • Events
      • Contact
  • Terms• Privacy• Trust and Compliance
© Kong Inc. 2025