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
    • Deploy a standalone control plane
    • Multi-zone deployment
    • Deploy a multi-zone global control plane
    • 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
    • Non-mesh traffic
    • 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
    • MeshAccessLog (Beta)
    • MeshCircuitBreaker (Beta)
    • MeshFaultInjection (Beta)
    • MeshHealthCheck (Beta)
    • MeshHTTPRoute (Beta)
    • MeshProxyPatch (Beta)
    • MeshRateLimit (Beta)
    • MeshRetry (Beta)
    • MeshTimeout (Beta)
    • MeshTrace (Beta)
    • MeshTrafficPermission (Beta)
    • 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
    • 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
    • Open source License
    • Contribute to Mesh

github-edit-pageEdit this page

report-issueReport an issue

enterprise-switcher-iconSwitch to OSS

On this page
  • kumactl
    • Using variables
    • Configuration
Kong Mesh
2.1.x (latest)
  • Home
  • Kong Mesh
  • Explore
  • CLI

CLI

Kong Mesh ships in a bundle that includes a few executables:

  • kuma-cp: this is the main Kong Mesh executable that runs the control plane (CP).
  • kuma-dp: this is the Kong Mesh data plane proxy executable that - under the hood - invokes envoy.
  • envoy: this is the Envoy executable that we bundle for convenience into the archive.
  • kumactl: this is the the user CLI to interact with Kong Mesh (kuma-cp) and its data.
  • kuma-tcp-echo: this is a sample application that echos back the requests we are making, used for demo purposes.

According to the installation instructions, some of these executables are automatically executed as part of the installation workflow, while some other times you will have to execute them directly.

You can check the usage of the executables by running the -h flag, like:

kuma-cp -h

and you can check their version by running the version [--detailed] command like:

kuma-cp version --detailed

kumactl

The kumactl executable is a very important component in your journey with Kong Mesh. It allows to:

  • Retrieve the state of Kong Mesh and the configured policies in every environment.
  • On Universal environments, it allows to change the state of Kong Mesh by applying new policies with the kumactl apply [..] command.
  • On Kubernetes it is read-only, because you are supposed to change the state of Kong Mesh by leveraging Kong Mesh’s CRDs.
  • It provides helpers to install Kong Mesh on Kubernetes, and to configure the PostgreSQL schema on Universal (kumactl install [..]).

The kumactl application is a CLI client for the underlying HTTP API of Kong Mesh. Therefore, you can access the state of Kong Mesh by leveraging with the API directly. On Universal you will be able to also make changes via the HTTP API, while on Kubernetes the HTTP API is read-only.

Available commands on kumactl are:

  • kumactl install [..]: provides helpers to install Kong Mesh components in Kubernetes.
    • kumactl install control-plane: Installs Kong Mesh in Kubernetes in a kong-mesh-system namespace.
    • kumactl install observability: Install Observability (Metrics, Logging, Tracing) backend in Kubernetes cluster (Prometheus + Grafana + Loki + Jaeger + Zipkin) in mesh-observability namespace.
  • kumactl config [..]: configures the local or zone control-planes that kumactl should talk to. You can have more than one enabled, and the configuration will be stored in ~/.kumactl/config.
  • kumactl apply [..]: used to change the state of Kong Mesh. Only available on Universal.
  • kumactl get [..]: used to retrieve the raw state of entities Kong Mesh.
  • kumactl inspect [..]: used to retrieve an augmented state of entities in Kong Mesh.
  • kumactl generate dataplane-token: used to generate Dataplane Token .
  • kumactl generate tls-certificate: used to generate a TLS certificate for client or server.
  • kumactl manage ca [..]: used to manage certificate authorities.
  • kumactl help [..]: help dialog that explains the commands available.
  • kumactl version [--detailed]: shows the version of the program.

Checkout the kumactl usage docs for full documentation.

Using variables

When using kumactl apply you can specify variables to use your yaml as a template. This is useful for parametrizing policies and specifying values at runtime.

For example with a yaml like:

type: Mesh
name: default
mtls:
  backends:
  - name: vault-1
    type: 
    dpCert:
      rotation:
        expiration: 10h

You can then set the caType when applying it:

kumactl apply -f ~/res/mesh.yaml -v caType=builtin

This will create this mesh:

type: Mesh
name: default
mtls:
  backends:
    - name: vault-1
      type: builtin
      dpCert:
        rotation:
          expiration: 10h

Configuration

You can view the current configuration using kumactl config view.

The configuration is stored in $HOME/.kumactl/config, which is created when you run kumactl for the first time. When you add a new control plane with kumactl config control-planes add, the config file is updated. To change the path of the config file, run kumactl with --config-file /new-path/config.

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