Grey Matter Control API

The purpose of the Grey Matter Control API is to update the configuration of every Grey Matter Proxy in the mesh. It works as follows:

1. Control API creates, deletes, and modifies mesh configuration objects

2. Grey Matter Control takes these configuration objects from Control API

3. Control feeds these configuration objects to each proxy

Learn more about the Grey Matter Proxy here.

Sample Setup

GM_CONTROL_API_ADDRESS="0.0.0.0:5555"
GM_CONTROL_API_ORG_KEY="deciphernow"
GM_CONTROL_API_PERSISTER_TYPE="file"
GM_CONTROL_API_PERSISTER_PATH="/control-plane/data/backend.json"
GM_CONTROL_API_ZONE_KEY="default-zone"
GM_CONTROL_API_ZONE_NAME="default-zone"

Mesh Persistence

The Control API server has a number of options for how to enable backup and restore capabilities for the mesh configuration.

Null

GM_CONTROL_API_PERSISTER_TYPE=null

The NULL persister means that no persistent storage of the mesh will be done. If the server were to shut down (due to things like server failure, platform outage, or server migration) then all mesh setup would be lost.

This option is not recommended for any production deployments. If it is used, then some other means to export all created objects to a local store for backup purposes is recommended.

File

GM_CONTROL_API_PERSISTER_TYPE=file

The File persister writes out the mesh configuration to local disk. The location is determined by setting GM_CONTROL_API_PERSISTER_PATH to a file on disk. This file is updated each time an operation is performed in the API, so the file will be modified after every call.

Note that this file needs to be mounted on some form of persistent storage depending on the PaaS being used. In Kubernetes or OpenShift this would be a Persistent Volume Claim (PVC).

GM-Data

GM_CONTROL_API_PERSISTER_TYPE=gmdata

The GM Data persister backs up the mesh configuration in a provisioned instance of the Grey matter Data server. This provides a secure, persistent, storage option. Similar to the file persister, this writes a new backup file each time a modification is made to the mesh. Due to the way GM Date stores this file, this means that the entire mesh configuration can be backtracked across time.

When using the gmdata persister, the following environment variables must also be used to control the exact desired behavior.

• GM_CONTROL_API_GMDATA_OBJECT_POLICY_TEMPLATE

• GM_CONTROL_API_GMDATA_POLICY_LABEL

• GM_CONTROL_API_GMDATA_TOP_LEVEL_FOLDER_SECURITY

• GM_CONTROL_API_GMDATA_SERVICES_FILE_SECURITY

• GM_CONTROL_API_GMDATA_STARTUP_DELAY

• GM_CONTROL_API_GMDATA_MAX_EVENTS

• GM_CONTROL_API_GMDATA_POLLING_INTERVAL

• GM_CONTROL_API_GMDATA_MAX_RETRIES

• GM_CONTROL_API_GMDATA_RETRY_DELAY

• GM_CONTROL_API_GMDATA_ROOT_EVENT_NAME

• CLIENT_ADDRESS

• CLIENT_PORT

• CLIENT_PREFIX

• CLIENT_IDENTITY

• CLIENT_EMAIL

• CLIENT_USE_TLS

• INSECURE_TLS

• MONGO_USE_TLS

Full Config

Name	Type	Default	Description
GM_CONTROL_API_ADDRESS	String	"0.0.0.0:5555"	Host interface and port to start the server on
GM_CONTROL_API_USE_TLS	Boolean	false	Trigger serving only on HTTPS
GM_CONTROL_API_CA_CERT_PATH	String	""	Path to SSL CA on disk
GM_CONTROL_API_SERVER_CERT_PATH	String	""	Path to SSL Cert on disk
GM_CONTROL_API_SERVER_KEY_PATH	String	""	Path to SSL Key on disk
GM_CONTROL_API_ORG_KEY	String	"org-deciphernow"	Default Organization key to create on startup
GM_CONTROL_API_ORG_NAME	String	"deciphernow"	Name of default Organization
GM_CONTROL_API_ORG_EMAIL	String	"[e-mail]"	Email of default Organization
GM_CONTROL_API_ZONE_KEY	String	"zone-default-zone"	Default Zone key to create on startup
GM_CONTROL_API_ZONE_NAME	String	"default-zone"	Name of default Zone created on startup
GM_CONTROL_API_LOG_LEVEL	String	"info"	Log level ("info", "debug", "warn")
GM_CONTROL_API_VERBOSE_LOGGING	Boolean	false	Trigger extra verbose logging of the debug level
GM_CONTROL_API_PERSISTER_TYPE	String	"file"	Type of persistent storage for mesh config ("null", "file", "gmdata")
GM_CONTROL_API_PERSISTER_PATH	String	"gm_control_api_backend.json"	FUll path to file on disk. Only used if GM_CONTROL_API_PERSISTER_TYPE="file"
GM_CONTROL_API_DOCS_PATH	String	"swagger.yaml"	Path, relative to the server binary, of the swagger docs. Will be served at /.
GM_CONTROL_API_GMDATA_OBJECT_POLICY_TEMPLATE	String	(if (contains email %s) (yield-all) (yield R X))	Trigger serving only on HTTPS
GM_CONTROL_API_GMDATA_POLICY_LABEL	String	"Localuser owned"	User-friendly label to apply to all gm-data uploaded objects
GM_CONTROL_API_GMDATA_TOP_LEVEL_FOLDER_SECURITY	String	"{"label":"PUBLIC//EVERYBODY","foreground":"#FFFFFF","background":"#008800"}"	Trigger serving only on HTTPS
GM_CONTROL_API_GMDATA_SERVICES_FILE_SECURITY	String	"{"label":"PUBLIC//EVERYBODY","foreground":"#FFFFFF","background":"#008800"}"	Trigger serving only on HTTPS
GM_CONTROL_API_GMDATA_STARTUP_DELAY	String	"5s"	Duration to wait after startup before trying to connect to gm-data
GM_CONTROL_API_GMDATA_MAX_EVENTS	Integer	1000	Maximum number of history events to return with each listing
GM_CONTROL_API_GMDATA_POLLING_INTERVAL	String	"2s"	Duration to wait between polling gm-data for configuration changes
GM_CONTROL_API_GMDATA_MAX_RETRIES	Integer	50	Maximum number of time to attempt to connect to gm-data
GM_CONTROL_API_GMDATA_RETRY_DELAY	String	"5s"	During between gm-data connection attempts
GM_CONTROL_API_GMDATA_ROOT_EVENT_NAME	String	"world"	The name of the root folder in gm-data. Must match the gm-data deployment.
CLIENT_ADDRESS	String	"localhost"	Host of the gm-data connection
CLIENT_PORT	String	"5555"	Port of the gm-data connection
CLIENT_PREFIX	String	"/services/data/1.0"	Any URI path prefix on the gm-data connection
CLIENT_IDENTITY	String	""	Identity to use when connecting to gm-data. Determines available policies and permissions.
CLIENT_EMAIL	String	""	Email field of objects stored in gm-data
CLIENT_USE_TLS	Boolean	false	Connect to gm-data using TLS
INSECURE_TLS	Boolean	true	Connect to gm-data instance without doing server name verification
MONGO_USE_TLS	Boolean	false	​

Questions

Need help configuring the Control API? Contact our team: Grey Matter Support.