Careful!
You are browsing documentation for a version of Kuma that is not the latest release.
Looking for even older versions? Learn more.
CLI
Kuma ships in a bundle that includes a few executables:
kuma-cp
: this is the main Kuma executable that runs the control plane (CP).kuma-dp
: this is the Kuma data plane proxy executable that - under the hood - invokesenvoy
.envoy
: this is the Envoy executable that we bundle for convenience into the archive.kumactl
: this is the the user CLI to interact with Kuma (kuma-cp
) and its data.kuma-prometheus-sd
: this is a helper tool that enables native integration between Kuma andPrometheus
. Thanks to it,Prometheus
will be able to automatically find all dataplanes in your Mesh and scrape metrics out of them.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 Kuma. It allows to:
- Retrieve the state of Kuma and the configured policies in every environment.
- On Universal environments, it allows to change the state of Kuma by applying new policies with the
kumactl apply [..]
command. - On Kubernetes it is read-only, because you are supposed to change the state of Kuma by leveraging Kuma’s CRDs.
- It provides helpers to install Kuma 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 Kuma. Therefore, you can access the state of Kuma 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 Kuma components in Kubernetes.kumactl install control-plane
: Installs Kuma in Kubernetes in akuma-system
namespace.kumactl install observability
: Install Observability (Metrics, Logging, Tracing) backend in Kubernetes cluster (Prometheus + Grafana + Loki + Jaeger + Zipkin) inmesh-observability
namespace.
kumactl config [..]
: configures the local or zone control-planes thatkumactl
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 Kuma. Only available on Universal.kumactl get [..]
: used to retrieve the raw state of entities Kuma.kumactl inspect [..]
: used to retrieve an augmented state of entities in Kuma.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