Skip to main content

ConfigCat Proxy (Beta)

info

The ConfigCat Proxy is in a public beta phase. If you have feedback or questions, please contact us.

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 latest image:

docker pull configcat/proxy:latest

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(s)://localhost:8050/status

Available 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>"

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>
falseEnables or disables the SDK's offline mode. 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>
falseEnables or disables the global offline mode.
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, the only available option is Redis. 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

This is the whole YAML section of the cache 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:

Redis​

OptionDefaultDescription
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 ClusterClient instances.
cache:
  redis:
    enabled: <true|false>
falseEnables or disables caching into Redis.
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 related to securing the connection to Redis with TLS.

OptionDefaultDescription
cache:
  redis:
    tls: 
      enabled: <true|false>
falseEnables or disables TLS connection to Redis.
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.

HTTP​

The following HTTP and HTTP Proxy related options are available:

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

http_proxy:
  url: "<proxy-url>"

Here's the explanation for each option:

OptionDefaultDescription
http:
  port: 8050
8050The HTTP server's port that serves the CDN proxy, API, SSE, and webhook endpoints.
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 every HTTP request it receives.

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>
falseEnables or disables the enforcement of TLS connection to the ConfigCat Proxy.
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.