Install the meshctl CLI

Use the Gloo Mesh command line interface (CLI) tool, meshctl, to set up Gloo Mesh, register clusters, describe your Gloo Mesh resources, and more.

Quick installation

Install the latest version of meshctl. Make sure to add meshctl to your PATH (see Windows, macOS, or Linux for specific instructions).

curl -sL https://run.solo.io/meshctl/install | sh

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/v1.2.4/meshctl-darwin-amd64.

  1. From the Changelog, find the release version that you want to install.

  2. Set the Gloo Mesh Enterprise version. The latest version is used as an example. You can find other versions in the Changelog documentation.
    export GLOO_MESH_VERSION=v1.2.4
    
  3. Install the meshctl CLI.

    curl -sL https://run.solo.io/meshctl/install | sh -
    
  4. 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 Windows, macOS, or Linux.

    export PATH=$HOME/.gloo-mesh/bin:$PATH
    echo $PATH
    

    Example output:

    /Users/<name>/.gloo-mesh/bin:/usr/local/bin
    
  5. Verify that you can run meshctl commands.

    meshctl version
    

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 such as this blog.

Good job! You now have the version of meshctl that you want installed. Next, install Gloo Mesh in your clusters.

Do you have multiple cluster environments that require different versions of Gloo Mesh, 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 Mesh versions match.

Upgrading the meshctl CLI does not upgrade the Gloo Mesh 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 Mesh version that is installed in your clusters.

Configuration file

When you run certain meshctl commands, the commands attempt to read a configuration file located at $HOME/.gloo-mesh/meshctl-config.yaml. This configuration file contains information about your management and remote clusters. For example, if cluster-1 serves as the management cluster and both cluster-1 and cluster-2 are registered as remote clusters, meshctl-config.yaml might look like the following:

apiVersion: v1
clusters:
  cluster1: # data plane cluster
    kubeConfig: <home_directory>/.kube/config
    kubeContext: kind-cluster-1
  cluster2: # data plane cluster
    kubeConfig: <home_directory>/.kube/config
    kubeContext: kind-cluster-2
  managementPlane: # management cluster
    kubeConfig: <home_directory>/.kube/config
    kubeContext: kind-cluster-1

If you change your setup, you can configure the meshctl-config.yaml file by using the following command, which opens an interactive prompt. You can also configure this file non-interactively by using the --disable-prompt flag.

meshctl cluster configure

Additionally, you can override the default $HOME/.gloo-mesh/meshctl-config.yaml file location when you run meshctl commands by setting a location in the --config flag.

Reference documentation

For more information about each meshctl command, see the CLI documentation or run the help flag for a command.

meshctl cluster --help