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.
- Command line flags
- Environment variables
- 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/v1use_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/v1use_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 remotegit_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 updatedrelative_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 theroot
config param. Theroot
param should be a path to the module's root, e.g. the directory that contains thecue.mod
directory. See the CUE docs for details. This flag was removed in v4.1.0+ and is now a subcommand ofsync
.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 usernamepassword
(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 = ""