# Control API The purpose of the **Grey Matter Control API** is to update the configuration of every [Grey Matter Proxy](https://github.com/greymatter-io/gm-gitbook-sync/tree/59c71f09956d6cb016b8bb46a0ea26a8c417244f/reference/setup/fabric-1/control-api/grey-matter-proxy/README.md) 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 ## 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](https://github.com/greymatter-io/gm-gitbook-sync/tree/59c71f09956d6cb016b8bb46a0ea26a8c417244f/reference/setup/fabric-1/control-api/configure.md#backend-persister-configuration). | 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") | > Note: a full list of detailed configuration options can be found [below](https://github.com/greymatter-io/gm-gitbook-sync/tree/59c71f09956d6cb016b8bb46a0ea26a8c417244f/reference/setup/fabric-1/control-api/configure.md#full-config). ### 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 ``` 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). #### Redis ``` GM_CONTROL_API_PERSISTER_TYPE=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](https://redis.io/topics/persistence). When using the `redis` persister, the following environment variables must also be used: * `GM_CONTROL_API_REDIS_HOST` * `GM_CONTROL_API_REDIS_PORT` The following environment variables allow for custom settings: * `GM_CONTROL_API_REDIS_USE_TLS` * `GM_CONTROL_API_REDIS_CA_CERT_PATH` * `GM_CONTROL_API_REDIS_SERVER_CERT_PATH` * `GM_CONTROL_API_REDIS_SERVER_KEY_PATH` * `GM_CONTROL_API_REDIS_PASS` * `GM_CONTROL_API_REDIS_DB` * `GM_CONTROL_API_REDIS_MAX_RETRIES` * `GM_CONTROL_API_REDIS_RETRY_DELAY` #### Grey Matter Data ``` GM_CONTROL_API_PERSISTER_TYPE=gmdata ``` 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_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` ### 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](https://github.com/rs/zerolog#pretty-logging), set this value to `console`. ## 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" ``` ## 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_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 {% hint style="success" %} **Need help configuring the Control API?** Contact our team: [Grey Matter Support](https://support.greymatter.io/support/home). {% endhint %}