Light Dark Auto

CLI

Configuring the `greymatter` CLI

The greymatter CLI allows users to create and edit Grey Matter service mesh configurations. It connects to the control plane API.

The CLI exposes its functionality through subcommands, and help is available at the command line by passing --help to any subcommand.

Configuration Sources

The CLI evaluates config options in the following order.

  1. Command line flags
  2. Environment variables
  3. Configuration file

The default location of the config is ~/.config/greymatter/config.toml. This can be overridden with the --config command line flag.

GitOps Sync Mode

In addition to interactive use, greymatter supports a continuous sync mode. In continuous sync mode, the CLI will pull service mesh configurations from a repository on an interval, and apply them to the mesh.

Configuration File Overview

The config file for greymatter is a single TOML-formatted file with several configuration sections, or stanzas.

Not every section is required, and many options have defaults. Most config options available in the config file are also available via command line flags.

Control Plane API

[api] configuration stanza for the Control API service.

  • host(String) - A protocol scheme (http or https), host and port where the Control API is listening. Can also include an HTTP route prefix portion at the end. Example: http://127.0.0.1:8080 or http://127.0.0.1:8080/v1
  • use_tls(Boolean) - Enables or disables TLS.
  • tls_cert(String) - Path to a pem-encoded TLS certificate.
  • tls_key(String) - Path to a pem-encoded private key.
  • insecure(Boolean) - If true, do not verify the API server's certificate.

Catalog

[catalog] configuration stanza for the Catalog service.

  • host(String) - A protocol scheme (http or https), host and port where the Catalog is listening. Can also include an HTTP route prefix portion at the end. Example: http://127.0.0.1:8080 or http://127.0.0.1:8080/v1
  • use_tls(Boolean) - Enables or disables TLS.
  • tls_cert(String) - Path to a pem-encoded TLS certificate.
  • tls_key(String) - Path to a pem-encoded private key.
  • insecure(Boolean) - If true, do not verify the API server's certificate.

Sync

[sync] configuration stanza for CLI's sync subcommand. For more information on how to use sync, check out our GitOps guide.

  • root(String) - Path to a directory on disk, the root of a configuration tree.
  • git(Boolean) - If true, sync from a git repository. Setting this is required for other git configurations to take effect.
  • remote(String) - A valid URL for a git remote.
  • git_branch(String) - The branch to check out after cloning (required).
  • git_user(String) - A username for HTTP-based authentication to a git remote
  • git_password(String) - Password for HTTP-based authentication to a git remote.
  • ssh_private_key(String) - Path to an ssh key on disk for git authentication.
  • git_dir(String) - Path to the directory where a git repository will be cloned and updated
  • relative_path(String) - A subpath relative to the root of a git repo.
  • forever(Boolean) - If true, cli will never exit, but sync on an interval.
  • interval(String, default: "60s") - The interval for a CLI in --forever mode to attempt a sync. Must be parsable as a duration.
  • report(Boolean) - Generate a full in-depth sync report in the shell on completion of a sync cycle. Introduced in v4.1.0+

Sync: CUE Directory Structure

In version 4.0, CUE configuration support was introduced. It has numerous advantages over raw JSON such as comments, templating, and type-checking on top of a composable configuration language for added organization.

CUE support requires use of additional configuration options.

  • cue(Boolean) - If true, sync will interpret the configuration directory as the root of a CUE module. Must be paired with the root config param. The root param should be a path to the module's root, e.g. the directory that contains the cue.mod directory. See the CUE docs for details. This flag was removed in v4.1.0+ and is now a subcommand of sync.
  • cue_expression(Boolean, default: configs) - The target CUE expression to evaluate in a Grey Matter CUE mesh config project. This was introduced in CLI v4.1.0+.
  • cue_package(Boolean) - Optional. CUE files declare a package at the top. Packages group CUE files together, even across directories. More than one package can live in a single CUE directory. If that is the case for you, cue-package is required.

An example directory structure for a CUE based sync tree should look like the following:

gitops-examples/
  cue.mod/
  EXPORT.cue --> top level configuration arrays that can be concretely evaluated.
  services/
    intermediates.cue
    inputs.cue
    hamburger/
      lettuce.cue
      tomato.cue
      onion.cue
    apple-pie/
      apple.cue
      crust.cue

This tree is a CUE module, and could be applied with the following command:

greymatter sync --root ./mesh cue -e configs

The CUE configuration engine will evaluate all array expressions that are specified in EXPORT.cue. For more information on how CUE evaluates configuration, read CUE logic concepts.

Sync: Alternative JSON Directory Structure

Sync requires a tree of Grey Matter Mesh configuration. The tree requires the a layout similar to the following

meshconfigs/
  webserver/
    catalog-services/*.json 
    cluster/*.json
    domain/*.json
    listener/*.json
    proxy/*.json
    shared_rules/*.json
    route/*.json
  database/
    ...etc.

This config tree could be applied with the following command

greymatter sync --root ./meshconfigs

Note the directories underneath webserver. The greymatter CLI requires the names of "leaf" directories match the mesh configuration object type. In those directories, store the mesh configs of a specific type (e.g. cluster).

The CLI will walk the directory structure, and apply the JSON configs it finds in the leaf directories. The names of the intermediate directories (e.g. webserver) have no effect on the service mesh, but their presence is required. It is common to create a directory per service.

SOCKS5

The CLI can be configured to connect through a SOCKS5 proxy.

  • protocol(String) - One of: "tcp", "udp".
  • address(String) - IP address of the SOCKS5 proxy.
  • username(String) - SOCKS5 username
  • password(String) - SOCKS5 password

Full CLI Configuration Example 

[api]
host = "http://127.0.0.1:5555"
use_tls = false
zone_name = "default-zone"
tls_cert = "/path/to/client/cert"
tls_key = "/path/to/client/key"
insecure = true

[catalog]
host = "http://127.0.0.1:8080"
use_tls = false
zone_name = "default-zone"
tls_cert = "/path/to/client/cert"
tls_key = "/path/to/client/key"
insecure = false

[sync]
root = "/path/to/non/git/dir"
git = false
remote = "git@github.com:greymatter-io/gitops-examples.git"
git_branch = "main"
git_user = "user"
git_password = "hunter2"
ssh_private_key = "/some/user/.ssh/id_ed25519"
git_dir = "some_dir"
relative_path = "sub_dir"
forever = true
interval = "60s"
cue_expression = "all_configs"
cue_package = "mesh"
report = true

[socks5]
protocol = ""
address = ""
username = ""
password = ""