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:
Control API creates, deletes, and modifies mesh configuration objects
Grey Matter Control takes these configuration objects from Control API
Control feeds these configuration objects to each proxy
Configuration
The following describe the common configuration options for the Grey Matter Control API, set the following to configure the server and configure the desired persister type.
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_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")
Note: a full list of detailed configuration options can be found below.
Backend Persister Configuration
The Control API server has a number of options for how to enable backup and restore capabilities for the mesh configuration.
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
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).
Redis
The Redis persister stores the mesh configuration in a provisioned instance of Redis. This is the preferred persistence method for deployments of the Control API that will be scaled up to multiple nodes.
It is also recommended to persist the data written to Redis to disk by setting the appendonly setting in your Redis server configuration. See the Redis documentation for more details.
When using the redis persister, the following environment variables must also be used:
GM_CONTROL_API_REDIS_HOSTGM_CONTROL_API_REDIS_PORT
The following environment variables allow for custom settings:
GM_CONTROL_API_REDIS_USE_TLSGM_CONTROL_API_REDIS_CA_CERT_PATHGM_CONTROL_API_REDIS_SERVER_CERT_PATHGM_CONTROL_API_REDIS_SERVER_KEY_PATHGM_CONTROL_API_REDIS_PASSGM_CONTROL_API_REDIS_DBGM_CONTROL_API_REDIS_MAX_RETRIESGM_CONTROL_API_REDIS_RETRY_DELAY
Grey Matter Data
The Grey Matter Data persister backs up the mesh configuration in a provisioned instance of the Grey Matter Data server. This provides a secure, persistent storage option for a single instance of the Control API. Similar to the file persister, this writes a new backup file each time a modification is made to the mesh. Due to the way Grey Matter Data 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_TEMPLATEGM_CONTROL_API_GMDATA_POLICY_LABELGM_CONTROL_API_GMDATA_TOP_LEVEL_FOLDER_SECURITYGM_CONTROL_API_GMDATA_SERVICES_FILE_SECURITYGM_CONTROL_API_GMDATA_STARTUP_DELAYGM_CONTROL_API_GMDATA_MAX_EVENTSGM_CONTROL_API_GMDATA_POLLING_INTERVALGM_CONTROL_API_GMDATA_MAX_RETRIESGM_CONTROL_API_GMDATA_RETRY_DELAYGM_CONTROL_API_GMDATA_ROOT_EVENT_NAMECLIENT_ADDRESSCLIENT_PORTCLIENT_PREFIXCLIENT_IDENTITYCLIENT_EMAILCLIENT_USE_TLSINSECURE_TLSMONGO_USE_TLS
Logging
There are two configurable logging options for Grey Matter Control API. As described above, the log level can be specified with GM_CONTROL_API_LOG_LEVEL. There is also the option to set GM_CONTROL_API_LOG_FORMAT to one of console or json. It's default value is json. To enable pretty logging, set this value to console.
Sample Setup
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_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_LOG_FORMAT
String
"json"
Selects the format for console log messages ("console", "json")
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_REDIS_HOST
String
"localhost"
Host of the Redis connection
GM_CONTROL_API_REDIS_PORT
Integer
6379
Port of the Redis connection
GM_CONTROL_API_REDIS_USE_TLS
Boolean
false
Whether to connect to Redis over TLS
GM_CONTROL_API_REDIS_CA_CERT_PATH
String
""
Path to SSL CA on disk for connecting to Redis
GM_CONTROL_API_REDIS_SERVER_CERT_PATH
String
""
Path to SSL Cert on disk for connecting to Redis
GM_CONTROL_API_REDIS_SERVER_KEY_PATH=
String
""
Path to SSL Key on disk for connecting to Redis
GM_CONTROL_API_REDIS_PASS
String
""
Password if required by Redis
GM_CONTROL_API_REDIS_DB
Integer
0
Which database to use in Redis
GM_CONTROL_API_REDIS_MAX_RETRIES
String
5
Max number of times to attempt to connect to Redis
GM_CONTROL_API_REDIS_RETRY_DELAY
String
"1s"
Duration between Redis connection attempts
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"
Duration 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.
Last updated
Was this helpful?