Use the Kong Mesh CLI

Uses: Kong Mesh

Deployment Platform:

Prerequisites

Kong Konnect

If you don’t have a Konnect account, you can get started quickly with our onboarding wizard.

The following Konnect items are required to complete this tutorial:
- Personal access token (PAT): Create a new personal access token by opening the Konnect PAT page and selecting Generate Token.
Set the personal access token as an environment variable:
```
export KONNECT_TOKEN='YOUR KONNECT TOKEN'
```

Download kumactl

Go to the Kuma packages page to download and extract the installation archive for your OS, or download and extract the latest release automatically (Linux or macOS):

  curl -L https://developer.konghq.com/mesh/installer.sh | VERSION=2.11.4 sh -

Review Kong Mesh documentation

Go to the CLI reference to see what options you have on the command line.

After Kong Mesh is installed, you can access the control plane via the following methods:

Access method	Mode	Permissions
The Konnect GUI	Kubernetes and Universal self managed control plane	Read-only
HTTP API	Kubernetes and Universal	Read-only
`kumactl`	Kubernetes self managed control plane	Read-only
`kumactl`	Kubernetes Konnect managed control plane	Read and write
`kubectl`	Kubernetes self managed control plane	Read and write
`kubectl`	Kubernetes Konnect managed control plane	Read-only

By accessing the control plane using one of these methods, you can see the current Kong Mesh configuration or with some methods, you can edit the configuration.

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 to the API 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.

You will notice that Kong Mesh automatically creates a Mesh entity with name default.

You can use Kong Mesh with kubectl to perform read and write operations on Kong Mesh resources. For example:

kubectl get meshes
# NAME          AGE
# default       1m

or you can enable mTLS on the default Mesh with:

echo "apiVersion: kuma.io/v1alpha1
kind: Mesh
metadata:
  name: default
spec:
  mtls:
    enabledBackend: ca-1
    backends:
    - name: ca-1
      type: builtin" | kubectl apply -f -

You will notice that Kong Mesh automatically creates a Mesh entity with name default.

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 to the API 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 to see the HTTP API.

You will notice that Kong Mesh automatically creates a Mesh entity with name default.

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 to the API with:

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

and then run kumactl, for example:

kumactl get meshes
# NAME          mTLS      METRICS      LOGGING   TRACING
# default       off       off          off       off

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

You will notice that Kong Mesh automatically creates a Mesh entity with name default.

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 you can navigate to 127.0.0.1:5681/gui to see the GUI.

You will notice that Kong Mesh automatically creates a Mesh entity with name default.

Kong Mesh ships with a read and write HTTP API that you can use to perform operations on Kong Mesh resources. By default the HTTP API listens on port 5681.

To access Kong Mesh you can navigate to 127.0.0.1:5681 to see the HTTP API.

You will notice that Kong Mesh automatically creates a Mesh entity with name default.

You can use the kumactl CLI to perform read and write operations on Kong Mesh resources. The kumactl binary is a client to the Kong Mesh HTTP API. For example:

kumactl get meshes
# NAME          mTLS      METRICS      LOGGING   TRACING
# default       off       off          off       off

or you can enable mTLS on the default Mesh with:

echo "type: Mesh
name: default
mtls:
  enabledBackend: ca-1
  backends:
  - name: ca-1
    type: builtin" | kumactl apply -f -

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

You will notice that Kong Mesh automatically creates a Mesh entity with name default.

Kong Mesh, being an application that improves the underlying connectivity between your services by making the underlying network more reliable, also comes with some networking requirements itself.

Control plane ports

First and foremost, the kuma-cp application is a server that offers a number of services - some meant for internal consumption by kuma-dp data plane proxies and some meant for external consumption by kumactl, the HTTP API, the GUI or other systems.

The number and type of exposed ports depends on the mode in which the control plane is running as:

Global control plane

When Kong Mesh is run as a distributed service mesh, the global control plane exposes the following ports:

TCP
- 5443: the port for the admission webhook, only enabled in Kubernetes. The default Kubernetes kong-mesh-control-plane service exposes this port on 443.
- 5680: the HTTP server that returns the health status of the control plane.
- 5681: the HTTP API server that is being used by kumactl, and that you can also use to retrieve Kong Mesh’s policies and - when running in universal - that you can use to apply new policies. Manipulating Dataplane resources is not possible. It also exposes the Kong Mesh GUI at /gui
- 5682: HTTPS version of the services available under 5681
- 5683: gRPC Intercommunication CP server used internally by Kong Mesh to communicate between CP instances.
- 5685: the Kong Mesh Discovery Service port, leveraged in multi-zone deployments

Zone control plane

When Kong Mesh is run as a distributed service mesh, the zone control plane exposes the following ports:

TCP
- 5443: the port for the admission webhook, only enabled in Kubernetes. The default Kubernetes kong-mesh-control-plane service exposes this port on 443.
- 5676: the Monitoring Assignment server that responds to discovery requests from monitoring tools, such as Prometheus, that are looking for a list of targets to scrape metrics from.
- 5678: the server for the control plane to data plane proxy communication (bootstrap configuration, xDS to retrieve data plane proxy configuration, SDS to retrieve mTLS certificates).
- 5680: the HTTP server that returns the health status and metrics of the control plane.
- 5681: the HTTP API server that is being used by kumactl. You can also use it to retrieve Kong Mesh’s policies and, when running in universal, you can manage Dataplane resources. When not connected to global, it also exposes the Kong Mesh GUI at /gui
- 5682: HTTPS version of the services available under 5681
- 5683: gRPC Intercommunication CP server used internally by Kong Mesh to communicate between CP instances.

Use the Kong Mesh CLI

Prerequisites

Kong Konnect

Download kumactl

Review Kong Mesh documentation

Control plane ports

Global control plane

Zone control plane

Help us make these docs great!

Still need help