You are browsing documentation for an outdated version. See the
latest documentation here.
Kong Mesh with Kubernetes
To install and run Kong Mesh on Kubernetes, execute the
following steps:
Finally, you can follow the Quickstart to take it from here
and continue your Kong Mesh journey.
Prerequisites
You have a license for Kong Mesh.
1. Download Kong Mesh
To run Kong Mesh on Kubernetes, you need to download a
compatible version of Kong Mesh for the machine from which you
will be executing the commands.
You can run the following script to automatically detect the operating system
and download Kong Mesh:
$ curl -L https://docs.konghq.com/mesh/installer.sh | VERSION=1.1.4 sh -
You can also download the distribution manually. Download a distribution for
the client host from where you will be executing the commands to access
Kubernetes:
Then, extract the archive with:
$ tar xvzf kong-mesh-1.1.4*.tar.gz
2. Run Kong Mesh
Note: Before running the Kong Mesh
control plane process in the next step — which is served by the
kuma-cp
container — you need to have a valid
Kong Mesh license in place.
Navigate to the bin
folder:
Then, run the control plane with:
$ kumactl install control-plane --license-path=/path/to/license.json | kubectl apply -f -
Where /path/to/license.json
is the path to a valid Kong Mesh
license file on the file system.
This example will run Kong Mesh in standalone mode for a flat
deployment, but there are more advanced deployment modes
like multi-zone.
We suggest adding the kumactl
executable to your PATH
so that it’s always
available in every working directory. Alternatively, you can also create a link
in /usr/local/bin/
by executing:
$ ln -s ./kumactl /usr/local/bin/kumactl
Note: It may take a while for Kubernetes to start the
Kong Mesh resources. You can check the status by executing:
$ kubectl get pod -n kuma-system
3. Verify the Installation
Now that Kong Mesh (kuma-cp
) has been installed in the newly
created kuma-system
namespace, you can access the control plane using either
the GUI, kubectl
, the HTTP API, or the CLI:
GUI (Read-Only)
kubectl (Read & Write)
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 5681
.
To access Kong Mesh, port-forward the API service with:
$ kubectl port-forward svc/kuma-control-plane -n kuma-system 5681:5681
Now you can navigate to 127.0.0.1:5681/gui
to see the GUI.
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 -
Kong Mesh ships with a read-only HTTP API that you use
to retrieve Kong Mesh resources. By default,
the HTTP API listens on port 5681
.
To access Kong Mesh, port-forward the API service with:
$ kubectl port-forward svc/kuma-control-plane -n kuma-system 5681:5681
Now you can navigate to 127.0.0.1:5681
to see the HTTP API.
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. To use it, first port-forward the API
service with:
$ kubectl port-forward svc/kuma-control-plane -n kuma-system 5681:5681
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 remote kuma-cp
instance by running:
$ kumactl config control-planes add --name=XYZ --address=http://{address-to-kong-mesh}:5681
You will notice that Kong Mesh automatically creates a Mesh
entity with the name default
.
4. Quickstart
Congratulations! You have successfully installed Kong Mesh.
After installation, the Kuma quickstart documentation is fully compatible with
Kong Mesh, except that you are running Kong Mesh
binaries instead of the vanilla Kuma ones.
To start using Kong Mesh, see the
quickstart guide for Kubernetes deployments.