Kong Mesh CLI tools

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

• kuma-cp: The main Kong Mesh executable that runs the control plane.
• kuma-dp: The Kong Mesh data plane proxy executable that invokes envoy.
• envoy: The Envoy executable that we bundle into the archive for convenience.
• kumactl: The user CLI to interact with Kong Mesh (kuma-cp) and its data.
• kuma-tcp-echo: A sample application that echoes back the requests we make, used for demo purposes.

You can learn how to use each executable by running it with the -h flag:

kuma-cp -h

You can check their versions by running the version [--detailed] command:

kuma-cp version --detailed

The kumactl executable is your primary CLI tool for managing Kong Mesh. It allows you to:

• Retrieve the state of Kong Mesh and the configured policies in every environment.
• Change the state of Kong Mesh by applying new policies with the kumactl apply [..] command.

  This is only possible on Universal. On Kubernetes, kumactl is read-only. You can change the state of Kong Mesh by leveraging its CRDs.

• Install Kong Mesh on Kubernetes, and configure the PostgreSQL schema on Universal (kumactl install [..]).

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

kumactl commands

The following commands are available on kumactl:

• 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: Installs an observability (metrics, logging, tracing) backend in a Kubernetes cluster (Prometheus, Grafana, Loki, Jaeger, and Zipkin) in the 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 [..]: Changes the state of Kong Mesh. Only available on Universal.
• kumactl get [..]: Retrieves the raw state of Kong Mesh entities.
• kumactl inspect [..]: Retrieves an augmented state of Kong Mesh entities.
• kumactl generate dataplane-token: Generates a data plane token.
• kumactl generate tls-certificate: Generates a TLS certificate for the client or server.
• kumactl manage ca [..]: Manages certificate authorities.
• kumactl help [..]: Explains the commands available.
• kumactl version [--detailed]: Shows the version of the program.

You can use kumactl [cmd] --help for documentation.

Using variables

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

For example, using the following YAML snippet:

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

You can set the caType when applying the configuration:

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

This will create the following 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.