Install the meshctl CLI
Use the Gloo command line interface (CLI) tool, meshctl
, to set up Gloo Platform, register clusters, describe your Gloo resources, and more. You can also review other CLI tools that you commonly interact with while using Gloo.
Quick installation
Install the latest version of meshctl
. Make sure to add meshctl
to your PATH (see macOS, or Linux for specific instructions).
- Linux and macOS: If you use Gloo Mesh 2.2.0 or 2.2.1 on macOS X Ventura 13.0, see the specific install instructions instead.
curl -sL https://run.solo.io/meshctl/install | sh
- Windows is not currently supported.
macOS X Ventura 13.0 (meshctl 2.2.0 and 2.2.1 only)
When you use Gloo Mesh 2.2.0 or 2.2.1 on macOS X Ventura 13.0, UPX-compressed amd64 and x86_64 executables do not work and result in a segmentation fault error.
For example, when you attempt to run a command such as meshctl check server
on MacOS X Ventura, the command returns the following error message:
[1] 2931 segmentation fault meshctl check server
To fix this issue, you have two options:
- Upgrade Gloo Mesh to 2.2.2 or later.
- Unpack the binary for
meshctl
using UPX v4.0.0 instead, using the following steps.
-
Download version 2.2.0 or 2.2.1 of the
meshctl
CLI, and add it to your PATH system variable.export GLOO_MESH_VERSION=v2.2.1 curl -sL https://run.solo.io/meshctl/install | GLOO_MESH_VERSION=${GLOO_MESH_VERSION} sh - export PATH=$HOME/.gloo-mesh/bin:$PATH
-
Unpack the binary for
meshctl
using UPX v4.0.0.git clone https://github.com/upx/upx.git cd upx git submodule update --init git checkout -b v4.0.0 tags/v4.0.0 make ./build/release/upx -d ~/.gloo-mesh/bin/meshctl
-
Verify that you can run
meshctl
commands and check the client version matches the version that you installed.meshctl version
Example output:
{ "client": { "version": "2.2.4" },
Install a specific version of the CLI
You can pass a variable on the command line to download a specific version of meshctl
. The installation script uses the version and automatically detects your operating system to download the binary files from a public Google storage bucket, https://storage.googleapis.com/meshctl/
. For example, if you install the latest version on a macOS workstation, the binary file is downloaded from https://storage.googleapis.com/meshctl/v2.2.4/meshctl-darwin-amd64
.
-
From the Changelog, find the release version that you want to install.
-
Install the
meshctl
CLI, setting the Gloo version to install.curl -sL https://run.solo.io/meshctl/install | GLOO_MESH_VERSION=v2.2.4 sh -
-
Add
meshctl
on your PATH system variable for global access on the command line. The steps vary depending on your operating system. The following example is for macOS. For more information, see macOS, or Linux.export PATH=$HOME/.gloo-mesh/bin:$PATH echo $PATH
Example output:
/Users/<name>/.gloo-mesh/bin:/usr/local/bin
-
Verify that you can run
meshctl
commands and check the client version matches the version that you installed.meshctl version
Example output:
{ "client": { "version": "2.2.4" },
On macOS, you might see the following warning: “meshctl” cannot be opened because it is from an unidentified developer.
In the Finder app, navigate to the ~/.gloo-mesh/binmeshctl
executable file, right-click the file, click Open, and confirm that you want to open the file. For more information, try searching the warning and following a guide.
Good job! You now have the version of meshctl
that you want installed. Next, install Gloo in your clusters.
Do you have multiple cluster environments that require different versions of Gloo, Istio, and Kubernetes? Consider downloading each meshctl
, istioctl
, and kubectl
version binary file to a separate directory. Then, you can set up an alias in your local command line interface profile to point to the binary file directory that matches the version of the cluster environment that you want to work with.
Upgrade the CLI
To upgrade, re-install the CLI. You can install the latest or a specific version. Make sure that your meshctl
and Gloo versions match.
Upgrading the meshctl
CLI does not upgrade the Gloo version that you run in your clusters.
Uninstall the CLI
To uninstall meshctl
, you can delete the executable file from your system, such as on macOS in the following example.
rm ~/.gloo-mesh/bin/meshctl
Skew policy
Use the same version of the meshctl
CLI as the Gloo version that is installed in your clusters.
- Slight skews within minor versions typically work, such as
meshctl
2.0.8 and Gloo 2.0.9. - Compatibility across beta versions is not guaranteed, even within minor version skews.
- To resolve bugs in
meshctl
, you might have to upgrade the entire CLI to a specific or latest version.
Configuration file
When you run certain meshctl
commands (like meshctl check
or meshctl debug report
), the commands attempt to read a configuration file located inside the home directory (e.g. $HOME/.gloo-mesh/meshctl-config.yaml
on Linux). This configuration file contains information about your management and workload clusters. For example, if cluster-1
serves as the management cluster and both cluster-1
and cluster-2
are registered as workload clusters, meshctl-config.yaml
might look like the following:
apiVersion: v1
clusters:
cluster-1: # data plane cluster
kubeConfig: <home_directory>/.kube/config
kubeContext: kind-cluster-1
namespace: gloo-mesh
cluster-2: # data plane cluster
kubeConfig: <home_directory>/.kube/config
kubeContext: kind-cluster-2
namespace: gloo-mesh
managementPlane: # management cluster
kubeConfig: <home_directory>/.kube/config
kubeContext: kind-cluster-1
namespace: gloo-mesh
Some meshctl
commands (like meshctl install
) will make changes to the configuration automatically. You can also configure the meshctl-config.yaml
file by using the following command, which opens an
interactive prompt.
meshctl cluster configure
You can configure this file non-interactively by using the --disable-prompt
flag.
meshctl cluster configure --disable-prompt --cluster-name managementPlane --kubeconfig <home_directory>/.kube/config --kubecontext kind-cluster-1
Additionally, you can override the default config file location when you run meshctl
commands (for either writing or reading the config file) with the --config
flag. For example,
meshctl install --config /path/to/file/meshctl-config.yaml [remaining arguments...]
Reference documentation
For more information about each meshctl
command, see the CLI documentation or run the help flag for a command.
meshctl cluster --help
Other command line tools
As you use Gloo, you might need the following common cluster management command line tools on your local system.
CLI tool | Description |
---|---|
Cloud provider CLI | The CLI to interact with your preferred cloud provider, such as aws or gcloud . You might also have local cluster testing tools such as kind or k3d . gcloud . |
istioctl |
The Istio command line tool. The guides in this documentation use Istio version 1.16.2. To check your installed version, run istioctl version . |
jq |
Parse JSON output, such as from logs, to get values that can be used in subsequent commands, environment variables, or other contexts. |
kubectl |
The Kubernetes command line tool. Download the kubectl version that is within one minor version of the Kubernetes clusters you plan to use with Gloo. |
openssl |
Make sure that you have the OpenSSL version of
|