Skip to main content
Version: Config V2

ConfigCat Proxy

The ConfigCat Proxy allows you to host a feature flag evaluation service in your own infrastructure. It's a small Go application that communicates with ConfigCat's CDN network and caches/proxies config JSON files for your frontend and backend applications. The config JSON contains all the data that is needed for ConfigCat SDKs to evaluate feature flags.

The Proxy provides the following:

  • Performance: The Proxy can be deployed close to your applications and can serve the downloaded config JSON files from memory. ConfigCat SDKs then can operate on the proxied config JSON. This can reduce the duration of feature flag evaluation for stateless or short lived applications.
  • Reliability: The Proxy can store the downloaded config JSON files in an external cache. It can fall back to operating on the cached config JSON if the ConfigCat CDN network becomes inaccessible.
  • Security: The Proxy can act as a server side flag evaluation component. Using it like that can prevent the exposure of config JSON files to frontend and mobile applications.
  • Scalability: Horizontal scaling allows you to align with the load coming from your applications accordingly.
  • Streaming: The Proxy provides real-time feature flag change notifications via Server-Sent Events (SSE) and gRPC.

Architecture​

The following diagram shows the high level architecture of the Proxy.

High level Proxy architecture

How It Works​

The Proxy wraps one or more SDK instances for handling feature flag evaluation requests. It also serves the related config JSON files that can be consumed by other ConfigCat SDKs running in your applications.

Within the Proxy, the underlying SDK instances can run in the following modes:

  • Online: In this mode, the underlying SDK has an active connection to the ConfigCat CDN network through the internet.
  • Offline: In this mode, the underlying SDK doesn't have an active connection to ConfigCat. Instead, it uses the configured cache or a file as a source of its config JSON.

With the combination of the above modes, you can construct a cluster of proxies where only one node is responsible for the communication with ConfigCat, and all the other nodes are working from a central cache.

Load balanced Proxy architecture

Communication​

There are three ways how the Proxy is informed about the availability of new feature flag evaluation data:

  • Polling: The ConfigCat SDKs within the Proxy are regularly polling the ConfigCat CDN for new config JSON versions.
  • Webhook: The Proxy has webhook endpoints (for each underlying SDK) which can be set on the ConfigCat Dashboard to be invoked when someone saves & publishes new feature flag changes.
  • Cache polling / file watching: In offline mode, the Proxy can regularly poll a cache or watch a file for new config JSON versions.

These are the ports used by the Proxy by default:

Installation​

You can install the ConfigCat Proxy from the following sources:

Docker

The docker image is available on DockerHub. You can run the image either as a standalone docker container or via docker-compose.

Pull the docker image:

docker pull configcat/proxy

Run the ConfigCat Proxy:

docker run -d --name configcat-proxy \ 
  -p 8050:8050 -p 8051:8051 -p 50051:50051 \
  -e CONFIGCAT_SDKS='{"<sdk-identifier>":"<your-sdk-key>"}' \
  configcat/proxy
Standalone executable

You can download the executables directly from GitHub Releases for your desired platform.

You can then check the status endpoint of the Proxy to ensure it's working correctly: http://localhost:8051/status

Configuration Options​

You can specify options for the Proxy either via a YAML file or with environment variables. When an option is defined in both places, the environment variable's value takes precedence.

The Proxy is able to read the options YAML from the following default locations:

  • Windows: %PROGRAMDATA%\configcat\proxy\options.yml, usually C:\ProgramData\configcat\proxy\options.yml
  • macOS: /Library/Application Support/configcat/proxy/options.yml
  • Linux: /etc/configcat/proxy/options.yml

When the default location is not suitable, you can specify a custom location for your options YAML file via the -c argument.

Docker

When running the Proxy in docker, you can mount the options YAML file as a volume.

docker run -d --name configcat-proxy \ 
  -p 8050:8050 -p 8051:8051 -p 50051:50051 \
  -v <path-to-file>/options.yml:/etc/configcat/proxy/options.yml

(Optional) With the -c argument to specify a custom path for your options YAML file:

docker run -d --name configcat-proxy \ 
  -p 8050:8050 -p 8051:8051 -p 50051:50051 \
  -v <path-to-file>/options.yml:/cnf/options.yml \
  configcat/proxy -c /cnf/options.yml
Standalone executable

Run the Proxy as a standalone executable with the options YAML file in its default location:

./configcat-proxy

(Optional) With the -c argument to specify a custom path for your options YAML file:

./configcat-proxy -c /path-to-file/options.yml

The following sections will go through each available option in detail.

Logging​

The Proxy supports the following log levels: debug, info, warn, and error. The default is warn.

You can specify the log level either globally or for each individual component. If you don't set a component's log level explicitly, it will inherit the global level's value.

log:
  level: "<error|warn|info|debug>"
info

When the main HTTP server's or gRPC server's log level is set to debug, each HTTP request or RPC the Proxy receives is logged with additional details. (duration, response status, etc.)

Default User Attributes​

There's an option to predefine User Object attributes with default values. Whenever the Proxy receives an evaluation request it will automatically attach these predefined attributes to the request. If the evaluation request contains a different value for an attribute you previously defined, the request's value will take precedence.

default_user_attributes:
  attribute_key1: "<attribute_value1>"
  attribute_key2: "<attribute_value2>"
info

It's also possible to set default user attributes at the SDK level. See the SDK options section below for more details.

SDK​

In order to make the Proxy work properly, it must be set up with one or more SDK keys. It will instantiate one SDK instance for each SDK key. In case of environment variables, the SDK keys can be specified in a JSON key-value format, where the key is the identifier of a specific SDK and the value is the actual SDK key. The SDK identifier part is later used in endpoint route variables to recognize which SDK must serve the given flag evaluation request.

Furthermore, when configuring the Proxy via environment variables, the identifier becomes a part of the SDK specific environment variable's name using the following format: CONFIGCAT_<SDK_ID>_<OPTION>.

For example, suppose we have the following SDK key-value option: CONFIGCAT_SDKS={"my-sdk":"<your-sdk-key>"}.
In this case, the environment variable that sets the SDK's poll interval will be named as follows: CONFIGCAT_MY_SDK_POLL_INTERVAL.

info

The SDK identifier part of the environment variables is always transformed to uppercase and each hyphen (-) character is replaced with underscore (_).

In case of a YAML file, the SDK identifier is the property name set under the sdks node.

options.yml
sdks:
  my_sdk:
    ...

This is the whole YAML section of the SDK specific options.

options.yml
sdks:
  my_sdk:
    key: "<your-sdk-key>"
    base_url: "<base-url>"
    poll_interval: 30
    data_governance: <"eu"|"global">
    webhook_signing_key: "<key>"
    webhook_signature_valid_for: 300
    default_user_attributes:
      attribute_key: "<attribute_value>"
    log:
      level: "<error|warn|info|debug>"
    offline:
      log:
        level: "<error|warn|info|debug>"
      enabled: <true|false>
      use_cache: <true|false>
      cache_poll_interval: 5
      local:
        file_path: "./path/local.json"
        polling: <true|false>
        poll_interval: 5
  another_sdk:
    ...

Here's the explanation for each option:

SDK Identifier / SDK Key​

OptionDescription
my_sdk:
  key: "<your-sdk-key>"
The SDK identifier and the SDK key. The SDK identifier is used in endpoint route variables to recognize which SDK must serve the given flag evaluation request. The SDK key is crucial for the underlying SDK to operate.

Additional SDK Options​

OptionDefaultDescription
my_sdk:
  base_url: "<base-url>"
ConfigCat's CDN url.The CDN base url (forward proxy, dedicated subscription) from where the SDK will download the config.json.
my_sdk:
  poll_interval: 30
30The underlying SDK's polling interval in seconds.
my_sdk:
  data_governance: "<global|eu>"
globalDescribes the location of your feature flag and setting data within the ConfigCat CDN. This parameter needs to be in sync with your Data Governance preferences. More about Data Governance.
my_sdk:
  webhook_signing_key: "<key>"
-The key used to sign the webhook requests sent to the Proxy. More about the webhook endpoint.
my_sdk:
  webhook_signature_valid_for: 300
300The time period within the webhook requests are considered valid. More about the webhook endpoint.
my_sdk:
  default_user_attributes:
    attribute_key: "<attribute_value>"
-Additional SDK specific default user attributes. The Proxy will use these attributes when an evaluation request doesn't contain a value for the predefined attribute.
When there's a default value defined for the same attribute at both SDK and global level, the one at the SDK level will take precedence.
my_sdk:
  log:
    level: "<error|warn|info|debug>"
warnThe verbosity of the SDK related logs.
Possible values: error, warn, info, or debug.

Offline Mode​

The following options are specific to the SDK's offline mode. In offline mode, there are two ways the Proxy can get the required feature flag evaluation data for the underlying SDKs.

  • Polling a cache: The Proxy can poll a cache for feature flag changes. It can use the same cache that an online Proxy instance writes. More about the cache option.
  • Watching / polling a file: The Proxy can watch or poll for modifications in a file that contains the evaluation data of feature flags. For watching, the Proxy uses the fsnotify library.
OptionDefaultDescription
my_sdk:
  offline:
    enabled: <true|false>
falseTurns the SDK's offline mode on/off. In offline mode the SDK will not communicate with the ConfigCat CDN network. Instead, it uses the configured cache or a file as the source of its config.json.
my_sdk:
  offline:
    use_cache: <true|false>
falseIndicates whether the SDK should use the configured cache as the source of its config.json. More about the cache option.
my_sdk:
  offline:
    cache_poll_interval: 5
5The cache polling interval in seconds. Used only, when the use_cache option is true. More about the cache option.
my_sdk:
  offline:
    log:
      level: "<error|warn|info|debug>"
warnThe verbosity of the offline mode related logs.
Possible values: error, warn, info or debug.
my_sdk:
  offline:
    local:
      file_path: "./path/local.json"
-Path to the local file that contains the appropriate config.json.
my_sdk:
  offline:
    local:
      polling: <true|false>
falseIndicates whether the Proxy should switch to local file polling instead of file system watching.
my_sdk:
  offline:
    local:
      poll_interval: 5
5The polling interval of the local file in seconds.

Global Offline Mode​

It is possible to turn on offline mode globally for a whole Proxy instance. When it's turned on, each underlying SDK switches to work from the configured cache.

OptionDefaultDescription
offline:
  enabled: <true|false>
falseTurns the global offline mode on/off.
offline:
  cache_poll_interval: 5
5The cache polling interval in seconds. More about the cache option.
offline:
  log:
    level: "<error|warn|info|debug>"
warnThe verbosity of the offline mode related logs.
Possible values: error, warn, info or debug.
note

When an SDK also has its offline option set, that will override what it would inherit from the global offline option.

Cache​

The Proxy in its default setup stores all the information it needs for feature flag evaluation in memory. This behavior is extendable with an external cache that you can use for pointing the underlying SDKs to your own data storage.

Currently, Redis, MongoDB, and DynamoDB is supported as external cache. The cache key for the underlying SDKs is based on the SDK Key. This means that multiple Proxy instances using the same SDK key will read/write the same cache entry.

info

The ConfigCat Proxy supports shared caching, which means it can feed an external cache that is shared by other ConfigCat SDKs. You can read more about this feature and the required minimum SDK versions here.

Shared cache architecture

Redis​

This is the whole YAML section of the Redis specific options.

options.yml
cache:
  redis:
    enabled: <true|false>
    db: 0
    user: "<user>"
    password: "<pass>"
    addresses: ["<addr1>", "<addr2>"]
    tls: 
      enabled: <true|false>
      min_version: <1.0|1.1|1.2|1.3>
      server_name: "<server-name>"
      certificates:
        - cert: "<path-to-cert>"
          key: "<path-to-key>"

Here's the explanation for each option:

OptionDefaultDescription
cache:
  redis:
    enabled: <true|false>
falseTurns caching into Redis on/off.
cache:
  redis:
    addresses: ["<addr1>", "<addr2>"]
["localhost:6379"]The addresses of the Redis instances. The Proxy uses Universal Redis clients, so if the array contains multiple addresses, it will use a ClusterClient instance.
cache:
  redis:
    db: 0
0The selected Redis database.
cache:
  redis:
    user: "<user>"
-The username for connecting to Redis.
cache:
  redis:
    password: "<pass>"
-The password for connecting to Redis.

The following options are for securing the connection to Redis with TLS.

OptionDefaultDescription
cache:
  redis:
    tls: 
      enabled: <true|false>
falseTurns the TLS connection to Redis on/off.
cache:
  redis:
    tls: 
      min_version: <1.0|1.1|1.2|1.3>
1.2The minimum TLS version to use.
cache:
  redis:
    tls: 
      server_name: "<server-name>"
-The name of the Redis server.
cache:
  redis:
    certificates:
      - cert: "<path-to-cert>"
        key: "<path-to-key>"
-A list of TLS certificate/key pairs.

MongoDB​

When the configured MongoDB database and collection doesn't exist, the Proxy automatically creates them. The following document structure is used to store the downloaded config JSON in BSON format:

{ 
  "key": "<The unique cache key determined by the ConfigCat SDK within the Proxy>", 
  "payload": "<The downloaded config JSON in a standardized format determined by the ConfigCat SDK within the Proxy>" 
}

At the collection creation, the Proxy also creates a unique index for the key field.

This is the whole YAML section of the MongoDB specific options.

options.yml
cache:
  mongodb:
    enabled: <true|false>
    url: "<connection-url>"
    database: "<database-name>"
    collection: "<collection-name>"
    tls: 
      enabled: <true|false>
      min_version: <1.0|1.1|1.2|1.3>
      server_name: "<server-name>"
      certificates:
        - cert: "<path-to-cert>"
          key: "<path-to-key>"

Here's the explanation for each option:

OptionDefaultDescription
cache:
  mongodb:
    enabled: <true|false>
falseTurns caching into MongoDB on/off.
cache:
  mongodb:
    url: "<connection-url>"
-The connection url to MongoDB.
cache:
  mongodb:
    database: "<database-name>"
configcat_proxyThe name of the MongoDB database that the Proxy will use for storing data.
cache:
  mongodb:
    collection: "<collection-name>"
cacheThe name of the collection inside the MongoDB database.

The following options are for securing the connection to MongoDB with TLS.

OptionDefaultDescription
cache:
  mongodb:
    tls: 
      enabled: <true|false>
falseTurns the TLS connection to MongoDB on/off.
cache:
  mongodb:
    tls: 
      min_version: <1.0|1.1|1.2|1.3>
1.2The minimum TLS version to use.
cache:
  mongodb:
    tls: 
      server_name: "<server-name>"
-The name of the MongoDB server.
cache:
  mongodb:
    certificates:
      - cert: "<path-to-cert>"
        key: "<path-to-key>"
-A list of TLS certificate/key pairs.

DynamoDB​

By default, the Proxy uses the standard AWS CLI environment variables (or a local AWS configuration file) to read the AWS credentials and region for connecting to DynamoDB.

The Proxy doesn't create the DynamoDB table automatically, it must already exist with a partition key called key. The data stored in the table has the following attributes:

  • key: The unique cache key determined by the ConfigCat SDK within the Proxy.
  • payload: The downloaded config JSON in a standardized format determined by the ConfigCat SDK within the Proxy.

The following permissions are needed to read and write the table:

  • GetItem
  • PutItem

This is the whole YAML section of the DynamoDB specific options.

options.yml
cache:
  dynamodb:
    enabled: <true|false>
    url: "<url>"
    table: "<table-name>"

Here's the explanation for each option:

OptionDefaultDescription
cache:
  dynamodb:
    enabled: <true|false>
falseTurns caching into DynamoDB on/off.
cache:
  dynamodb:
    url: "<url>"
-The DynamoDB service endpoint.
cache:
  dynamodb:
    table: "<table-name>"
configcat_proxy_cacheThe name of the DynamoDB table that the Proxy will use for storing data.

HTTP​

The following HTTP and HTTP Proxy related options are available:

options.yml
http:
  enabled: <true|false>
  port: 8050
  log: 
    level: "<error|warn|info|debug>"
  status:
    enabled: <true|false>

http_proxy:
  url: "<proxy-url>"

Here's the explanation for each option:

OptionDefaultDescription
http: 
  enabled: <true|false>
trueTurns the main HTTP server on/off. This server hosts the CDN proxy, API, SSE, and webhook endpoints.
http:
  port: 8050
8050The main HTTP server's port.
http:
  log:
    level: "<error|warn|info|debug>"
warnThe verbosity of the HTTP related logs.
Possible values: error, warn, info, or debug.
When debug is set, the Proxy will log each HTTP request with additional details.
http:
  status: 
    enabled: <true|false>
falseTurns the hosting of the status endpoint on the main HTTP port (default: 8050) on/off.

HTTP Proxy​

OptionDefaultDescription
http_proxy:
  url: "<proxy-url>"
-The network proxy's URL that the ConfigCat Proxy must use for communication through the internet.

Endpoints​

The options for HTTP endpoints are discussed in the Endpoints section.

TLS​

For securing direct communication to the ConfigCat Proxy, you have the option to set up TLS. Another option would be to use a full-featured reverse proxy that secures the communication and forwards each request to the Proxy.

The following options are for the first scenario where you secure the direct HTTP and gRPC communication.

options.yml
tls: 
  enabled: <true|false>
  min_version: <1.0|1.1|1.2|1.3>
  certificates:
    - cert: "<path-to-cert>"
      key: "<path-to-key>"

Here's the explanation for each option:

OptionDefaultDescription
tls: 
  enabled: <true|false>
falseTurns the enforcement of TLS connection to the ConfigCat Proxy on/off.
tls: 
  min_version: <1.0|1.1|1.2|1.3>
1.2The minimum TLS version to accept.
tls:
  certificates:
    - cert: "<path-to-cert>"
      key: "<path-to-key>"
-A list of TLS certificate/key pairs.