Light Dark Auto

CLI

Configuring the `greymatter` CLI

The greymatter CLI is the official client for communicating with a greymatter.io mesh.

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.

  • url(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.

  • url(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.

SOCKS5

[socks5] configuration stanza for the CLI 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

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.
  • git_dir(String) - Path to the directory where a git repository will be cloned and updated
  • ssh_private_key(String) - Path to an ssh key on disk for git authentication.
  • ssh_passphrase(String, default: "") - Passphrase protecting the private key.
  • 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.
  • relative_path(String) - A subpath relative to the root of a git repo.
  • report(Boolean) - Generate a full in-depth sync report in the shell on completion of a sync cycle. Introduced in v4.1.0+
  • cue_expression(String, default: "configs") - Selects which top level CUE value to evaluate in the modules root package. Introduced in v4.2.0+
  • cue_package(String, default: "") - Optionally select a single package from within a CUE module. Introduced in v4.2.0+

Redis

[redis] configuration stanza for CLI's sync subcommand. Redis is required for sync to perform its reconciliation against the greymatter.io control-plane.

  • db(Integer) - Redis target database.
  • address(String) - IP address of the Redis instance.
  • username(String) - Redis username
  • password(String) - Redis password

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.

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

grocery-list/
  cue.mod/
  EXPORT.cue --> top level configuration arrays that can be concretely evaluated.
  greymatter/
    intermediates.cue
    inputs.cue
    grocerylist/
      lettuce.cue
      tomato.cue
      onion.cue
      apple.cue
      crust.cue
  k8s/
    manifests.yaml

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

greymatter sync --root ./mesh -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.

Full CLI Configuration Example

log_level = "debug"

[api]
url = "http://127.0.0.1:5555"
use_tls = false
tls_cert = "/path/to/client/cert"
tls_key = "/path/to/client/key"
insecure = true

[catalog]
url = "http://127.0.0.1:8080"
use_tls = false
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"
ssh_passphrase = ""
git_dir = "some_dir"
relative_path = "sub_dir"
forever = true
interval = "60s"
cue_expression = "configs"
cue_package = "mesh"
report = true

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