Skip to main content

Configurations

Look up the environment variables that configure an Edge PDP, the permitio/pdp-v2 policy decision point (PDP) container you run in your network. This page is for operators who deploy and tune Edge PDPs. The Cloud PDP is managed by Permit and doesn't read these variables.

How PDP configuration works​

  • Pass variables to the container. Set each variable with --env NAME=value in docker run, or in the env section of your Kubernetes deployment. See Run an Edge PDP with Docker for a docker run command that sets PDP_API_KEY and PDP_DEBUG.
  • PDP_ prefix: settings of the PDP itself.
  • OPAL_ prefix: settings of the Open Policy Administration Layer (OPAL) client inside the PDP. Every OPAL client configuration is available with the OPAL_ prefix.
  • Settings controlled by Permit: at startup, the PDP fetches part of its configuration from the Permit control plane. Variables marked "controlled by Permit" below are set that way. Changing them can stop the PDP from connecting to Permit.
PDP versions follow Semantic Versioning

PDP versions follow Semantic Versioning. A patch release, for example from 1.2.3 to 1.2.4, doesn't introduce breaking changes.

Required and common settings​

VariableDefaultSet it to
PDP_API_KEYNone (required)Your environment API key
PDP_DEBUGUnsetTrue to add debug information to decision logs from this PDP
PDP_CACHE_STOREnonein-memory or redis to cache decisions
PDP_ENABLE_MONITORINGFalseTrue to enable Datadog APM tracing
ALL_PROXYUnsetYour HTTP proxy URL, when the PDP reaches Permit through a proxy

Connection to Permit​

PDP_API_KEY​

Default: none. This variable is required.

The API key the PDP uses to authenticate to Permit.io. Use an environment-level API key. See API keys.

PDP_CONTROL_PLANE​

Default: https://api.permit.io

The URL of the Permit.io control plane.

PDP_CONTROL_PLANE_TIMEOUT​

Default: 75

Timeout in seconds for requests to the control plane. The timeout also applies to requests the PDP proxies for the Send Consistent Updates APIs.

PDP_SHARD_ID​

Default: None

The shard ID of this PDP. The control plane uses the shard ID to identify the PDP.

PDP_PING_INTERVAL​

Default: 10

The interval, in seconds, between pings to the control plane.

PDP_CONTROL_PLANE_PDP_DELTAS_API​

Default: controlled by Permit.

The URL of the Permit.io PDP deltas API.

PDP_CONTROL_PLANE_RELAY_API​

Default: controlled by Permit.

The URL of the Permit.io relay API.

PDP_CONTROL_PLANE_RELAY_JWT_TIER​

Default: controlled by Permit.

The URL of the Permit.io service that issues relay API JSON Web Tokens (JWTs).

PDP_BACKEND_SERVICE_URL​

Default: {PDP_CONTROL_PLANE}/v1 (https://api.permit.io/v1)

The Permit.io API URL that the PDP sends proxied API requests to. Controlled by Permit: changing the value can stop proxied requests from working.

PDP_BACKEND_LEGACY_URL​

Default: {PDP_CONTROL_PLANE}/sdk (https://api.permit.io/sdk)

The legacy Permit.io API URL that the PDP sends proxied requests to. Controlled by Permit: changing the value can stop proxied requests from working.

PDP_REMOTE_CONFIG_ENDPOINT​

Default: /v2/pdps/me/config

The control plane route the PDP calls at startup to fetch its configuration and policy data topics.

PDP_REMOTE_STATE_ENDPOINT​

Default: /v2/pdps/me/state

The control plane route the PDP calls to report state changes.

PDP server and health checks​

PDP_HOST​

Default: 0.0.0.0

The address the PDP server listens on. Set :: to listen on IPv6.

PDP_PORT​

Default: 7000 in the permitio/pdp-v2 image

The port the PDP server listens on inside the container. Map it to a host port with docker run -p, for example -p 7766:7000.

Added in PDP v0.9.0. PDP versions before v0.9.0 use UVICORN_PORT instead.

PDP_HEALTHCHECK_TIMEOUT​

Default: 3

Timeout in seconds for health checks. A health check response that takes longer fails.

PDP_USE_NEW_AUTHORIZED_USERS​

Default: false

Feature flag that enables the new implementation of the authorized users API.

Added in PDP v0.9.0.

PDP_ALLOW_METRICS_UNAUTHENTICATED​

Default: False

When True, the /metrics endpoint is accessible without authentication.

Debug mode and logging​

PDP_DEBUG​

Default: unset

Enables Debug Mode, which adds debug attributes to Open Policy Agent (OPA) policy queries and to decision logs:

ValueBehavior
Unset (None)The PDP uses the Debug Mode setting from the Permit environment configuration.
TrueDebug Mode is on for this PDP.
FalseDebug Mode is off for this PDP.
Debug Mode adds latency

Debug Mode increases policy evaluation latency. Turn off Debug Mode for PDPs that serve production traffic.

See Debug Mode for how to configure Debug Mode for a whole environment.

PDP_DECISION_LOG_DEBUG_INFO​

Default: True

When True, the PDP logs more data for each allow decision.

PDP_PRINT_CONFIG_ON_STARTUP​

Default: False

When True, the PDP prints its full configuration at startup.

PDP_ENABLE_MONITORING​

Default: False

When True, the PDP sends Datadog APM traces.

PDP_TEMP_LOG_FORMAT​

Default: <green>{time}</green> | {process} | <blue>{name: <40}</blue>|<level>{level:^6} | {message}</level>

The log format the PDP uses until it receives its configuration from Permit. Change the format to remove colors, for example.

PDP_CENTRAL_LOG_DRAIN_URL​

Default: https://listener.logz.io:8071

The URL for centralized logging.

PDP_CENTRAL_LOG_DRAIN_TIMEOUT​

Default: 5

Timeout in seconds for the centralized log drain.

PDP_CENTRAL_LOG_TOKEN​

Default: None

The token for centralized logging.

OPA client​

PDP_OPA_URL​

Default: http://localhost:8181

The URL of the OPA process inside the PDP.

Added in PDP v0.9.0.

PDP_OPA_CLIENT_QUERY_TIMEOUT​

Default: 1

Timeout in seconds for querying OPA for an allow decision. The meaning of 0 depends on the PDP version:

PDP version0 means
0.8.x and earlierNo timeout
0.9.0 and laterA timeout of 0 seconds

PDP_OPA_CLIENT_FAILURE_THRESHOLD​

Default: 0.1

The fraction of failed OPA requests that fails the PDP health check.

PDP_OPA_CLIENT_FAILURE_THRESHOLD_INTERVAL​

Default: 60

The interval, in seconds, over which the PDP calculates the failure threshold.

PDP_OPA_CONFIG_FILE_PATH​

Default: ~/opa/config.yaml

The path of the OPA configuration file in the container.

PDP_OPA_AUTH_POLICY_FILE_PATH​

Default: ~/opa/basic-authz.rego

The path of the OPA authorization policy (a Rego file) in the container.

PDP_OPA_BEARER_TOKEN_REQUIRED​

Default: True

When True, every API call to OPA must include a bearer token (the value of CLIENT_TOKEN).

Decision logs​

PDP_OPA_DECISION_LOG_ENABLED​

Default: True

When True, the PDP uploads OPA decision logs to Permit.io, where they appear in the audit log.

PDP_OPA_DECISION_LOG_CONSOLE​

Default: False

When True, the PDP also prints OPA decision logs to the console. Applies only when PDP_OPA_DECISION_LOG_ENABLED is True.

PDP_OPA_DECISION_LOG_INGRESS_ROUTE​

Default: /v1/decision_logs/ingress

The route on Permit.io that decision logs are uploaded to.

PDP_OPA_DECISION_LOG_INGRESS_BACKEND_TIER_URL​

Default: None. Controlled by Permit.

The URL that decision logs are uploaded to.

PDP_OPA_DECISION_LOG_MIN_DELAY​

Default: 1

The minimum time, in seconds, between decision log uploads. When an upload fails, the PDP retries with exponential backoff up to PDP_OPA_DECISION_LOG_MAX_DELAY.

PDP_OPA_DECISION_LOG_MAX_DELAY​

Default: 10

The maximum time, in seconds, between decision log uploads.

PDP_OPA_DECISION_LOG_UPLOAD_SIZE_LIMIT​

Default: 65536

The size limit, in bytes, of one decision log upload. OPA splits uploads into chunks that fit the limit.

Trino authorization​

PDP_ALLOW_UNAUTHENTICATED_TRINO​

Default: False

When True, the PDP serves its Trino authorization routes without authentication, so clients can call them without an API key.

Unauthenticated Trino routes

Trino doesn't support passing an API key or credentials to external authorization endpoints. To use the PDP with Trino, you must set PDP_ALLOW_UNAUTHENTICATED_TRINO=True, which exposes the PDP's Trino routes (such as /trino/allowed, /trino/row-filter, and /trino/batch-column-masking) without authentication.

Anyone who can reach those routes can query your authorization decisions. Deploy the PDP behind a firewall or in a trusted network that only the Trino cluster can reach, and never expose the PDP to the public internet. Follow the Trino issue for API key support in Trino.

PDP_TRINO_AUTHZ_CONFIG_PATH​

Default: /app/config/trino-authz.yaml

The absolute path of the YAML file that defines Trino row filters and column masking policies. If the file is missing or fails to parse, the PDP starts without Trino row filter and column masking rules.

See the Trino integration.

Local facts and data updates​

PDP_LOCAL_FACTS_WAIT_TIMEOUT​

Default: 10

When the SDK sends facts through the PDP (Send Consistent Updates), the time in seconds the PDP waits for the facts to apply.

PDP_LOCAL_FACTS_TIMEOUT_POLICY​

Default: ignore

What the PDP does when a data update doesn't apply within PDP_LOCAL_FACTS_WAIT_TIMEOUT:

ValueBehavior
ignoreRespond immediately.
failRespond with HTTP status 424.

PDP_DATA_UPDATE_CALLBACKS​

Default: []

A JSON list of callbacks the PDP calls when its data is updated. Each entry has a url, an optional key, and an optional config with the HTTP method, headers, and body. For example:

[
  {
    "url": "http://example.com/callback",
    "key": "example",
    "config": {
      "headers": {
        "Authorization": "Bearer token"
      },
      "method": "GET",
      "data": {
        "key": "value"
      }
    }
  }
]

When an entry has no config, the PDP sends a POST request with a JSON content type. The variable must be valid JSON.

For the full schema, see the CallbackEntry model in OPAL.

Callbacks add sync latency

The PDP calls each callback as part of a data update, so a slow callback endpoint delays data synchronization. Size the callback endpoint for your data update rate.

Cache​

PDP_CACHE_STORE​

Default: none

The cache store for PDP decisions: none, in-memory, or redis. See PDP caching mechanism.

Added in PDP v0.9.0.

PDP_CACHE_TTL​

Default: 3600

Time to live, in seconds, of cached items.

Added in PDP v0.9.0.

PDP_CACHE_MEMORY_CAPACITY​

Default: 128

Memory capacity, in MiB, of the in-memory cache. Applies when PDP_CACHE_STORE is in-memory.

Added in PDP v0.9.0.

PDP_CACHE_REDIS_URL​

Default: "" (empty string)

The Redis connection URL. Applies when PDP_CACHE_STORE is redis.

Added in PDP v0.9.0.

Horizon service​

Horizon is the internal Python service in the PDP. The PDP server starts Horizon, checks its health, and restarts it after repeated health check failures.

PDP_HORIZON_PORT​

Default: 7001

The port of the Horizon service inside the container.

Added in PDP v0.9.0.

PDP_HORIZON_CLIENT_TIMEOUT​

Default: 60

Timeout in seconds for requests from the PDP server to Horizon.

Added in PDP v0.9.0.

PDP_HORIZON_NICENESS​

Default: 10

The process niceness of Horizon. Values range from -20 (highest priority) to 19 (lowest priority), and 0 is neutral. A higher value makes Horizon yield CPU to other processes, such as OPA, sooner.

Added in PDP v0.9.0.

PDP_HORIZON_HEALTH_CHECK_TIMEOUT​

Default: 1

Timeout in seconds for one Horizon health check. A health check that takes longer fails.

Added in PDP v0.9.0.

PDP_HORIZON_HEALTH_CHECK_INTERVAL​

Default: 5

The interval, in seconds, between Horizon health checks.

Added in PDP v0.9.0.

PDP_HORIZON_HEALTH_CHECK_FAILURE_THRESHOLD​

Default: 12

The number of consecutive failed health checks after which the PDP restarts Horizon.

Added in PDP v0.9.0.

PDP_HORIZON_STARTUP_DELAY​

Default: 5

The delay, in seconds, after startup before the PDP starts Horizon health checks.

Added in PDP v0.9.0.

PDP_HORIZON_RESTART_INTERVAL​

Default: 1

The interval, in seconds, between Horizon restart attempts.

Added in PDP v0.9.0.

PDP_HORIZON_TERMINATION_TIMEOUT​

Default: 30

The time, in seconds, the PDP waits for Horizon to shut down during a stop or restart. After this timeout, the PDP terminates Horizon forcefully.

Added in PDP v0.9.0.

OPAL configurations​

These are the OPAL client settings you are most likely to change. The OPAL documentation lists the rest.

OPAL_SERVER_URL​

Default: controlled by Permit.

The URL of the OPAL server.

OPAL_SERVER_WS_URL​

Default: OPAL_SERVER_URL with https replaced by wss. Controlled by Permit.

The WebSocket URL of the OPAL server.

OPAL_CLIENT_TOKEN​

Default: controlled by Permit. The PDP fetches the token from the control plane at startup.

The token the PDP uses to authenticate to the OPAL server.

OPAL_INLINE_OPA_ENABLED​

Default: True

When True, OPAL runs OPA inside the PDP container. Controlled by Permit.

OPAL_INLINE_OPA_LOG_FORMAT​

Default: http in the permitio/pdp-v2 image

The format of OPA logs:

ValueLogs
noneNo OPA logs
minimalThe event name only
httpThe HTTP method, path, and status code
fullThe entire data returned

OPAL_INLINE_CEDAR_ENABLED​

Default: True

When True, OPAL runs the Cedar agent inside the PDP container. Controlled by Permit.

OPAL_INLINE_CEDAR_LOG_FORMAT​

Default: none

The format of Cedar logs. Accepts the same values as OPAL_INLINE_OPA_LOG_FORMAT.

OPAL_FETCHING_WORKER_COUNT​

Default: 6

The number of workers that fetch data concurrently.

OPAL_FETCHING_CALLBACK_TIMEOUT​

Default: 10

The time, in seconds, to wait for a queued fetch task.

OPAL_FETCHING_ENQUEUE_TIMEOUT​

Default: 10

The time, in seconds, to wait to queue a new fetch task when the queue is full.

OPAL_ENABLE_DATADOG_APM​

Default: False

When True, OPAL sends Datadog APM traces.

OPAL_LOG_DIAGNOSE​

Default: False

When True, OPAL includes diagnosis information, including local variable values, in log tracebacks.

Secrets in logs

When OPAL_LOG_DIAGNOSE is True, logs can include sensitive values, such as authentication headers and tokens. Keep the setting off in production.

OPAL_LOG_SERIALIZE​

Default: False

When True, OPAL writes log records as JSON to standard error, for log aggregation services.

Additional configurations​

ALL_PROXY​

Default: unset

Set ALL_PROXY when the PDP runs in an isolated network and reaches Permit through an HTTP proxy:

# Proxy for all protocols (i.e. HTTPS, WSS)
ALL_PROXY=http://proxy.example.com:8080

Proxy requirements:

  • HTTP proxy address only. The PDP opens TLS connections to Permit for both HTTP and WebSocket traffic, and TLS inside TLS is not supported, so the proxy address must use http://. See the aiohttp proxy documentation.
  • HTTP/2 and WebSocket support. A proxy that doesn't support HTTP/2 and WebSocket connections breaks the PDP's connection to Permit. See the OPAL proxy tutorial.

Added in PDP v0.9.4.

Settings for PDP versions before v0.9.0​

PDP v0.9.0 and later start the Horizon service with Uvicorn directly, without Gunicorn, so UVICORN_NUM_WORKERS and GUNICORN_TIMEOUT apply only to earlier PDP versions.

UVICORN_NUM_WORKERS​

Default: 1

The number of parallel workers that run the PDP server.

GUNICORN_TIMEOUT​

Default: 600

The time, in seconds, a worker can be idle or unresponsive before Gunicorn stops it. See the Gunicorn timeout setting.

Contents

Edit this page

Need help?