# 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](https://github.com/DecipherNow/gm-gitbook-sync/tree/f88cd215baf3ba5b6bc0076f1fd2e9791f661496/setup/introduction/internals/grey-matter-proxy-sidecar.md) here. ## Sample Setup ```bash 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 | "" | 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 {% hint style="success" %} **Need help configuring the Control API?** Contact our team: [Grey Matter Support](https://support.greymatter.io/support/home). {% endhint %}