Skip to main content

Edge Proxy

Running​

The Edge Proxy runs as a Docker container with no external dependencies. It connects to the Flagsmith API to download environment documents, and your Flagsmith client applications connect to it using remote flag evaluation.

The examples below assume you have a configuration file located at ./config.json. Your Flagsmith client applications can then consume the Edge Proxy by setting their API URL to http://localhost:8000/api/v1/.

Docker CLI
docker run \
    -v ./config.json:/app/config.json \
    -p 8000:8000 \
    flagsmith/edge-proxy:latest
Docker Compose
services:
 edge_proxy:
  image: flagsmith/edge-proxy:latest
  volumes:
   - type: bind
     source: ./config.json
     target: /app/config.json
  ports:
   - '8000:8000'

Configuration​

The Edge Proxy can be configured with any combination of:

  • Environment variables.
  • A JSON configuration file, by default located at /app/config.json in the Edge Proxy container.

Environment variables take priority over their corresponding options defined in the configuration file.

Environment variables are case-insensitive, and are processed using Pydantic.

Example configuration​

Configuration file
{
 "environment_key_pairs": [
  {
   "server_side_key": "ser.your_server_side_key_1",
   "client_side_key": "your_client_side_key_1"
  }
 ],
 "api_poll_frequency": 5,
 "logging": {
  "log_level": "DEBUG",
  "log_format": "json"
 }
}
Environment variables
ENVIRONMENT_KEY_PAIRS='[{"server_side_key":"ser.your_server_side_key_1","client_side_key":"your_client_side_key_1"}]'
API_POLL_FREQUENCY=5
LOGGING='{"log_level":"DEBUG","log_format":"json"}'

Basic Settings​

environment_key_pairs​

Specifies which environments to poll environment documents for. Each environment requires a server-side key and its corresponding client-side key.

"environment_key_pairs": [{
  "server_side_key": "ser.your_server_side_key",
  "client_side_key": "your_client_side_environment_key"
}]

api_url​

If you are self-hosting Flagsmith, set this to your API URL:

"api_url": "https://flagsmith.example.com/api/v1"

api_poll_frequency​

How often to poll the Flagsmith API for changes, in seconds. Defaults to 10.

"api_poll_frequency": 30

api_poll_timeout​

The request timeout when trying to retrieve new changes, in seconds. Defaults to 5.

"api_poll_timeout": 1

allow_origins​

Set a value for the Access-Control-Allow-Origin header. Defaults to *.

"allow_origins": "https://my-flagsmith.domain.com"

Endpoint Caches​

endpoint_caches​

Enables a LRU cache per endpoint.

Optionally, specify the LRU cache size with cache_max_size. Defaults to 128.

"endpoint_caches": {
  "flags": {
    "use_cache": false
  },
  "identities": {
    "use_cache": true,
    "cache_max_size": 1000,
  }
}

Logging​

logging.log_level​

Choose a logging level from "CRITICAL", "ERROR", "WARNING", "INFO", "DEBUG". Defaults to "INFO".

"logging": {"log_level": "DEBUG"}

logging.log_format​

Choose a logging format between "generic" and "json". Defaults to "generic".

"logging": {"log_format": "json"}

logging.log_event_field_name​

Set a name used for human-readable log entry field when logging events in JSON. Defaults to "message".

"logging": {"log_event_field_name": "event"}

logging.colour​

Added in 2.13.0.

Set to false to disable coloured output. Useful when outputting the log to a file.

logging.override​

Added in 2.13.0.

Accepts Python-compatible logging settings in JSON format. You're able to define custom formatters, handlers and logger configurations. For example, to log everything a file, one can set up own file handler and assign it to the root logger:

"logging": {
  "override": {
      "handlers": {
          "file": {
              "level": "INFO",
              "class": "logging.FileHandler",
              "filename": "edge-proxy.log",
              "formatter": "json"
          }
      },
      "loggers": {
          "": {
              "handlers": ["file"],
              "level": "INFO",
              "propagate": true
          }
      }
  }
}

Or, log access logs to file in generic format while logging everything else to stdout in JSON:

"logging": {
  "override": {
      "handlers": {
          "file": {
              "level": "INFO",
              "class": "logging.FileHandler",
              "filename": "edge-proxy.log",
              "formatter": "generic"
          }
      },
      "loggers": {
          "": {
              "handlers": ["default"],
              "level": "INFO"
          },
          "uvicorn.access": {
              "handlers": ["file"],
              "level": "INFO",
              "propagate": false
          }
      }
  }
}

When adding logger configurations, you can use the "default" handler which writes to stdout and uses formatter specified by the "logging.log_format" setting.

Health Check​

The Edge Proxy exposes a health check endpoint at /proxy/health that responds with a 200 status code if it was able to fetch all its configured environment documents. If any environment document could not be fetched during a configurable grace period, the health check will fail with a 500 status code. This allows the Edge Proxy to continue reporting as healthy even if the Flagsmith API is temporarily unavailable.

health_check.environment_update_grace_period_seconds​

Default: 30.

The number of seconds to allow per environment key pair before the environment data stored by the Edge Proxy is considered stale.

When set to null, cached environment documents are never considered stale, and health checks will succeed if all environments were successfully fetched at some point since the Edge Proxy started.

The effective grace period depends on how many environments the Edge Proxy is configured to serve. It can be calculated using the following pseudo-Python code:

total_grace_period_seconds = api_poll_frequency + (environment_update_grace_period_seconds * len(environment_key_pairs))
if last_updated_all_environments_at < datetime.now() - timedelta(seconds=total_grace_period_seconds):
    # Data is stale
    return 500
# Data is not stale
return 200

Environment Variables​

You can configure the Edge Proxy with the following Environment Variables:

  • WEB_CONCURRENCY The number of Uvicorn workers. Defaults to 1. Set to the number of available CPU cores.

Monitoring​

There are 2 health check endpoints for the Edge Proxy.

SDK Proxy Health Check​

When making a request to /proxy/health the proxy will respond with a HTTP 200 and {"status": "ok"}. You can point your orchestration health checks to this endpoint. This endpoint checks that the Environment Document is not stale, and that the proxy is serving SDK requests.

Architecture​

The standard Flagsmith architecture:

Image

With the proxy added to the mix:

Image