Skip to main content

OPAL Configuration Guide

Getting Started with OPAL Configuration

OPAL supports multiple ways to configure your deployment:

  • Environment Variables (recommended) - export OPAL_SERVER_URL=http://localhost:7002
  • Command Line Arguments - opal-server run --server-url http://localhost:7002
  • Configuration Files - .env or .ini files in your project

Essential Configuration

Let's get OPAL running! You'll need to set a few environment variables that tell OPAL where to find your policies and how to connect everything together.

OPAL Server

# Where your policies are stored (Git repo)
export OPAL_POLICY_REPO_URL=https://github.com/your-org/policy-repo.git

# Where clients get initial data
export OPAL_DATA_CONFIG_SOURCES='{"config":{"entries":[{"url":"http://localhost:7002/policy-data","topics":["policy_data"],"dst_path":"/static"}]}}'

# Broadcast channel for scaling (use Redis or PostgreSQL)
export OPAL_BROADCAST_URI=postgres://postgres:postgres@localhost:5432/postgres

OPAL Client

# Connect to your OPAL server
export OPAL_SERVER_URL=http://localhost:7002

# Authentication token (change in production!)
export OPAL_CLIENT_TOKEN=your-secret-token

# Policy engine type (OPA is default, Cedar also available)
export OPAL_POLICY_STORE_TYPE=opa

Production Configuration

When you're ready to deploy to production, you'll need to configure a few more things to ensure security and reliability.

  • Use HTTPS for all OPAL server communication
  • Generate strong cryptographic keys for JWT authentication
  • Store secrets securely (never commit to repositories)
  • Use webhooks instead of polling for policy updates

Common Configuration

Below are some common configuration options that you may want to consider:

🔐 Security Configuration
# Enable secure mode with proper authentication
export OPAL_AUTH_PRIVATE_KEY="your-rsa-private-key"
export OPAL_AUTH_PUBLIC_KEY="your-rsa-public-key"
export OPAL_AUTH_MASTER_TOKEN="secure-random-token"

# Use HTTPS
export OPAL_SERVER_URL=https://opal.your-domain.com
⚡ Performance & Scaling
# Scale with multiple server workers
export UVICORN_NUM_WORKERS=4

# Use webhooks instead of polling for better performance
export OPAL_POLICY_REPO_POLLING_INTERVAL=0
export OPAL_POLICY_REPO_WEBHOOK_SECRET=your-webhook-secret
📊 Monitoring & Logging
# Enhanced logging and statistics
export OPAL_LOG_FORMAT_INCLUDE_PID=true
export OPAL_LOG_LEVEL=INFO
export OPAL_STATISTICS_ENABLED=true

Read more about secure mode setup.

Configuration Reference

Common OPAL Configs

These configuration variables are shared between OPAL Client and OPAL Server.

General Configuration

OPAL_ALLOWED_ORIGINS

Default: *

Comma-separated list of allowed origins for CORS. Use * to allow all origins.

OPAL_PROCESS_NAME

Default: opal

The process name to be shown in logs.

OPAL_CLIENT_SELF_SIGNED_CERTIFICATES_ALLOWED

Default: False

Whether OPAL Client will trust HTTPS connections protected by self-signed certificates. Not recommended for production use.

Read more about using self-signed certificates.

OPAL_CLIENT_SSL_CONTEXT_TRUSTED_CA_FILE

Default: None

Path to your own CA public certificate file (usually a .crt or .pem file). Certificates signed by this issuer will be trusted by OPAL Client.

Read more about using self-signed certificates.

OPAL_POLICY_REPO_POLICY_EXTENSIONS

Default: [".rego"]

List of file extensions to serve as policy modules.

OPAL_ENABLE_METRICS

Default: False

Enable metrics collection.

For more information, see monitoring OPAL.

OPAL_ENABLE_DATADOG_APM

Default: False

Enable tracing with DataDog APM. Note: OPAL uses ddtrace v3.0.0+ which requires Python 3.8+.

For more information, see monitoring OPAL.

OPAL_HTTP_FETCHER_PROVIDER_CLIENT

Default: aiohttp

The client to use for fetching data. Options: aiohttp, httpx.

Added in OPAL v0.7.7

OPAL_GIT_SSH_KEY_FILE

Default: ~/.ssh/opal_repo_ssh_key

Path to the SSH key file for Git operations.

For more information, see tracking a Git repository.

OPAL_STATISTICS_ENABLED

Default: False

Collect statistics about OPAL clients.

For more information, see monitoring OPAL.

OPAL_STATISTICS_ADD_CLIENT_CHANNEL

Default: __opal_stats_add

The topic to update about new OPAL client connections.

For more information, see monitoring OPAL.

OPAL_STATISTICS_REMOVE_CLIENT_CHANNEL

Default: __opal_stats_rm

The topic to update about OPAL client disconnections.

For more information, see monitoring OPAL.

Logging Configuration

OPAL_LOG_FORMAT_INCLUDE_PID

Default: False

Whether to include the process ID in log messages.

OPAL_LOG_FORMAT

Default: {time} | {process} | {name} | {level} | {message}

The format string for log messages.

OPAL_LOG_TRACEBACK

Default: True

Whether to include traceback information in log messages.

OPAL_LOG_DIAGNOSE

Default: True

Include diagnosis in log messages.

Added in OPAL v0.6.0

danger

When OPAL_LOG_DIAGNOSE is enabled, logs may contain sensitive information such as secrets.

OPAL_LOG_COLORIZE

Default: True

Whether to colorize log messages.

OPAL_LOG_SERIALIZE

Default: False

Serialize log messages into JSON format (useful for log aggregation platforms).

Added in OPAL v0.6.0

OPAL_LOG_SHOW_CODE_LINE

Default: True

Whether to include the source code line number in log messages.

OPAL_LOG_LEVEL

Default: INFO

The minimum log level to display. Options: DEBUG, INFO, WARNING, ERROR, CRITICAL.

OPAL_LOG_MODULE_EXCLUDE_LIST

Default: ["uvicorn"]

List of module names to exclude from logging.

OPAL_LOG_MODULE_INCLUDE_LIST

Default: ["uvicorn.protocols.http"]

List of module names to include in logging (if empty, all modules are included).

OPAL_LOG_PATCH_UVICORN_LOGS

Default: True

Take over Uvicorn's logs so they appear in the main logger.

OPAL_LOG_PIPE_TO_STDERR

Default: True

Whether to send logs to stderr instead of stdout.

Added in OPAL v0.8.2

OPAL_LOG_TO_FILE

Default: False

Whether to write logs to a file in addition to console output.

OPAL_LOG_FILE_PATH

Default: opal_{process_name}{time}.log

Path to define where to save the log file.

OPAL_LOG_FILE_ROTATION

Default: 250 MB

Log file rotation size (e.g., "10 MB", "1 GB").

OPAL_LOG_FILE_RETENTION

Default: 10 days

How long to keep rotated log files (e.g., "30 days", "1 week").

OPAL_LOG_FILE_COMPRESSION

Default: None

Compression format for rotated log files.

OPAL_LOG_FILE_SERIALIZE

Default: True

Serialize log messages in file into JSON format (useful for log aggregation platforms).

OPAL_LOG_FILE_LEVEL

Default: INFO

The minimum log level for file logging.

Authentication Configuration

OPAL_AUTH_PUBLIC_KEY_FORMAT

Default: SSH

Format of the public key. Options: PEM, JWK, SSH.

Read more about secure mode setup.

OPAL_AUTH_PUBLIC_KEY

Default: None

The public key for JWT verification.

Read more about secure mode setup.

OPAL_AUTH_JWT_ALGORITHM

Default: RS256

JWT algorithm for token verification. See possible values here.

Read more about secure mode setup.

OPAL_AUTH_JWT_AUDIENCE

Default: https://api.opal.ac/v1/

The expected audience in JWT tokens.

Read more about secure mode setup.

OPAL_AUTH_JWT_ISSUER

Default: https://opal.ac/

The expected issuer in JWT tokens.

Read more about secure mode setup.

Fetching Configuration

OPAL_FETCH_PROVIDER_MODULES

Default: ["opal_common.fetcher.providers"]

List of custom fetch provider modules to load.

For more information, see writing your own fetch provider and available fetch providers.

OPAL_FETCHING_WORKER_COUNT

Default: 6

The number of workers to use for fetching data concurrently.

OPAL_FETCHING_CALLBACK_TIMEOUT

Default: 10

The timeout for fetching callbacks, in seconds.

OPAL_FETCHING_ENQUEUE_TIMEOUT

Default: 10

The timeout for enqueueing a fetch operation, in seconds.

OPAL Server Configs

These configuration variables are specific to the OPAL Server.

Server Configuration

OPAL_SERVER_WORKER_COUNT

Default: auto (calculated based on CPU cores)

Worker count for the server (when run using CLI).

OPAL_SERVER_HOST

Default: 127.0.0.1

Address for the server to bind to (when run using CLI).

OPAL_SERVER_PORT

Default: None

note

DEPRECATED - Use OPAL_SERVER_BIND_PORT instead.

OPAL_SERVER_BIND_PORT

Default: 7002

Port for the server to bind to (when run using CLI).

Added in OPAL v0.6.0

OPAL_BASE_DIR

Default: ~/.local/state/opal

Base directory for OPAL server.

OPAL_NO_RPC_LOGS

Default: True

Disable RPC logging.

OPAL_WS_LOCAL_URL

Default: ws://localhost:7002/ws

The local WebSocket URL for OPAL.

OPAL_WS_TOKEN

Default: THIS_IS_A_DEV_SECRET

The WebSocket token for OPAL.

OPAL_CLIENT_LOAD_LIMIT_NOTATION

Default: None

If supplied, rate limiting will be enforced on the server's WebSocket endpoint. Format is limits-style notation (e.g., "10 per second"). Learn more.

OPAL_SCOPES

Default: False

Enable scopes for multi-tenancy.

Added in OPAL v0.2.0

OPAL_SCOPES_REPO_CLONES_SHARDS

Default: 1

The max number of local clones to use for the same repo (reused across scopes).

OPAL_LEADER_LOCK_FILE_PATH

Default: /tmp/opal_server_leader.lock

Path to the leader lock file for distributed deployments.

OPAL_MAX_CHANNELS_PER_CLIENT

Default: 15

Maximum number of records per client. After this number, it will not be added to statistics (relevant only if OPAL_STATISTICS_ENABLED is true).

OPAL_STATISTICS_WAKEUP_CHANNEL

Default: __opal_stats_wakeup

The topic a waking-up OPAL server uses to notify others it needs their statistics data.

OPAL_STATISTICS_STATE_SYNC_CHANNEL

Default: __opal_stats_state_sync

The topic other servers with statistics provide their state to a waking-up server.

OPAL_STATISTICS_SERVER_KEEPALIVE_CHANNEL

Default: __opal_stats_server_keepalive

The topic workers use to signal they exist and are alive.

OPAL_STATISTICS_SERVER_KEEPALIVE_TIMEOUT

Default: 20

Timeout for forgetting a server from which a keep-alive haven't been seen (keep-alive frequency would be half of this value).

Broadcasting Configuration

OPAL_BROADCAST_URI

Default: None

URI for the broadcast backend (Redis, PostgreSQL, etc.).

For more information, see running OPAL with Kafka and running OPAL with Apache Pulsar.

OPAL_BROADCAST_CHANNEL_NAME

Default: EventNotifier

The channel name for broadcasting messages.

For more information, see running OPAL with Kafka and running OPAL with Apache Pulsar.

OPAL_BROADCAST_CONN_LOSS_BUGFIX_EXPERIMENT_ENABLED

Default: True

Enable experimental fix for broadcast connection loss issues.

OPAL_BROADCAST_KEEPALIVE_INTERVAL

Default: 3600

The time to wait between sending two consecutive broadcaster keepalive messages, in seconds.

OPAL_BROADCAST_KEEPALIVE_TOPIC

Default: __broadcast_session_keepalive__

The topic on which to send broadcaster keepalive messages.

OPAL_PUBLISHER_ENABLED

Default: True

Enable the publisher for broadcasting updates.

OPAL_REDIS_URL

Default: redis://localhost

Redis connection URL.

Authentication Configuration

OPAL_AUTH_PRIVATE_KEY_FORMAT

Default: PEM

Format of the private key. Options: PEM, JWK.

Read more about secure mode setup.

OPAL_AUTH_PRIVATE_KEY_PASSPHRASE

Default: None

Passphrase for the private key (if encrypted).

Read more about secure mode setup.

OPAL_AUTH_PRIVATE_KEY

Default: None

The private key for JWT signing.

Read more about secure mode setup.

OPAL_AUTH_JWKS_URL

Default: /.well-known/jwks.json

URL to fetch JSON Web Key Set (JWKS).

Read more about secure mode setup.

OPAL_AUTH_JWKS_STATIC_DIR

Default: ./jwks_dir

Directory containing static JWKS files.

Read more about secure mode setup.

OPAL_AUTH_MASTER_TOKEN

Default: None

Master token for authentication (bypasses JWT verification).

Read more about secure mode setup.

Policy Configuration

OPAL_POLICY_SOURCE_TYPE

Default: GIT

Set your policy source type. Options: GIT, API.

For more information, see tracking a Git repository and tracking an API bundle server.

OPAL_POLICY_REPO_URL

Default: None

Set your remote repository URL - relevant only for GIT source type. Example: https://github.com/permitio/opal-example-policy-repo.git.

For more information, see tracking a Git repository.

OPAL_POLICY_REPO_CLONE_PATH

Default: ./regoclone

Base path to create local git folder for managing policy changes.

For more information, see tracking a Git repository.

OPAL_POLICY_REPO_CLONE_FOLDER_PREFIX

Default: opal_repo_clone

Prefix for the local git folder.

OPAL_POLICY_REPO_REUSE_CLONE_PATH

Default: False

Set if OPAL server should use a fixed clone path (and reuse if it already exists) instead of randomizing its suffix on each run.

OPAL_POLICY_REPO_MAIN_BRANCH

Default: master

The main branch to track for policy files.

For more information, see tracking a Git repository.

OPAL_POLICY_REPO_SSH_KEY

Default: None

SSH private key content for Git repository access.

For more information, see tracking a Git repository.

OPAL_POLICY_REPO_MANIFEST_PATH

Default: ""

Path of the directory holding the '.manifest' file (updated way), or of the manifest file itself (old way). Repository root is used by default.

For more information, see tracking a Git repository.

OPAL_POLICY_REPO_CLONE_TIMEOUT

Default: 0

Timeout for Git clone operations in seconds. If set to 0, waits indefinitely until successful clone.

OPAL_REPO_WATCHER_ENABLED

Default: True

Enable repository watching for policy changes.

OPAL_POLICY_REFRESH_INTERVAL

Default: 0

Interval in seconds for refreshing policies. If set to 0, automatic refresh is disabled.

OPAL_POLICY_REPO_POLLING_INTERVAL

Default: 0

Interval in seconds for polling the policy repository for changes. If set to 0, polling is disabled.

For more information, see tracking a Git repository.

OPAL_FILTER_FILE_EXTENSIONS

Default: [".rego", ".json"]

List of file extensions to filter when processing policy files.

OPAL_BUNDLE_IGNORE

Default: []

List of patterns to ignore in the bundle.

For more information, see tracking a Git repository.

OPAL_POLICY_BUNDLE_GIT_ADD_PATTERN

Default: *

File pattern to add files to all git default files.

OPAL_POLICY_BUNDLE_URL

Default: None

Set your API bundle URL - relevant only for API source type.

For more information, see tracking an API bundle server.

OPAL_POLICY_BUNDLE_SERVER_TYPE

Default: HTTP

Type of policy bundle server. Options: HTTP (authenticated with bearer token), AWS-S3 (authenticated with AWS REST Auth).

For more information, see tracking an API bundle server.

OPAL_POLICY_BUNDLE_SERVER_TOKEN_ID

Default: None

The Secret Token ID (AKA user ID, AKA access-key) sent to the API bundle server.

For more information, see tracking an API bundle server.

OPAL_POLICY_BUNDLE_SERVER_TOKEN

Default: None

The Secret Token (AKA password, AKA secret-key) sent to the API bundle server.

For more information, see tracking an API bundle server.

OPAL_POLICY_BUNDLE_SERVER_AWS_REGION

Default: us-east-1

The AWS region of the S3 bucket.

For more information, see tracking an API bundle server.

OPAL_POLICY_BUNDLE_TMP_PATH

Default: /tmp/bundle.tar.gz

Path for temporary policy files. Must be writable.

OPAL_POLICY_REPO_WEBHOOK_SECRET

Default: None

Secret for validating webhook requests from the policy repository.

For more information, see tracking a Git repository.

OPAL_POLICY_REPO_WEBHOOK_TOPIC

Default: webhook

Topic for policy repository webhook events.

OPAL_POLICY_REPO_WEBHOOK_ENFORCE_BRANCH

Default: False

Enforce webhook events only from a specific branch.

OPAL_POLICY_REPO_WEBHOOK_PARAMS

Default: {"secret_header_name": "x-hub-signature-256", "secret_type": "signature", "secret_parsing_regex": "sha256=(.*)", "event_header_name": "X-GitHub-Event", "event_request_key": null, "push_event_value": "push"}

Additional parameters for webhook processing.

For more information, see tracking a Git repository.

OPAL_OPAL_POLICY_REPO_URL

Default: None

note

DEPRECATED - Use OPAL_POLICY_REPO_URL instead.

The repository URL where the policy repository is located. Must be available from the machine running OPAL (prefer public internet addresses). Supported URI schemes: https:// and ssh (i.e., git@).

OPAL_OPAL_POLICY_REPO_SSH_KEY

Default: None

note

DEPRECATED - Use OPAL_POLICY_REPO_SSH_KEY instead.

The content of the SSH private key. You will need to register the matching public key with your repository. The passed value must be the contents of the SSH key in one line (replace newlines with underscores, i.e., \n with _).

OPAL_OPAL_POLICY_REPO_CLONE_PATH

Default: /tmp/opal_policy_repo

note

DEPRECATED - Use OPAL_POLICY_REPO_CLONE_PATH instead.

Where to clone the repository in your Docker filesystem (not important unless you mount a Docker volume).

OPAL_OPAL_POLICY_REPO_MAIN_BRANCH

Default: main

note

DEPRECATED - Use OPAL_POLICY_REPO_MAIN_BRANCH instead.

Name of the git branch to track for policy files.

OPAL_OPAL_BUNDLE_IGNORE

Default: []

note

DEPRECATED - Use OPAL_BUNDLE_IGNORE instead.

Paths to omit from policy bundle. List of glob-style paths, or paths without wildcards but ending with "/**" indicating a parent path (ignoring all under it).

Added in OPAL v0.5.0

Data Configuration

OPAL_ALL_DATA_TOPIC

Default: data

Top-level topic for data updates.

OPAL_ALL_DATA_ROUTE

Default: /policy-data

Route for all data configuration.

OPAL_ALL_DATA_URL

Default: http://localhost:7002/policy-data

URL for all data configuration (if you choose to have it all in one place).

OPAL_DATA_CONFIG_ROUTE

Default: /data/config

URL to fetch the full basic configuration of data.

OPAL_DATA_CALLBACK_DEFAULT_ROUTE

Default: /data/callback_report

Default route for data callbacks (exists as a sane default in case the user did not set OPAL_DEFAULT_UPDATE_CALLBACKS).

OPAL_DATA_CONFIG_SOURCES

Default: {"config": {"entries": [{"url": "http://localhost:7002/policy-data", "topics": ["data"]}]}}

Configuration of data sources by topics.

For more information, see configuring external data sources and data source configuration.

OPAL_DATA_UPDATE_TRIGGER_ROUTE

Default: /data/update

URL to trigger data update events.

For more information, see triggering data updates.

OPAL Client Configs

These configuration variables are specific to the OPAL Client.

Client Configuration

OPAL_SERVER_URL

Default: http://localhost:7002

The URL of the OPAL server.

OPAL_SERVER_WS_URL

Default: ws://localhost:7002/ws

The WebSocket URL of the OPAL server.

OPAL_SERVER_PUBSUB_URL

Default: ws://localhost:7002/ws

The Pub/Sub URL of the OPAL server.

OPAL_CLIENT_TOKEN

Default: THIS_IS_A_DEV_SECRET

The OPAL Server Auth Token.

For more information, see obtaining a JWT token.

OPAL_WAIT_ON_SERVER_LOAD

Default: False

If set, client will wait for 200 response from server's loadlimit endpoint before starting background tasks.

OPAL_CLIENT_API_SERVER_WORKER_COUNT

Default: 1

Worker count for the opal-client's internal server (when run using CLI).

OPAL_CLIENT_API_SERVER_HOST

Default: 127.0.0.1

Address for the opal-client's internal server to bind to (when run using CLI).

OPAL_CLIENT_API_SERVER_PORT

Default: 7000

Port for the opal-client's internal server to bind to (when run using CLI).

OPAL_KEEP_ALIVE_INTERVAL

Default: 0

Interval in seconds for keep-alive messages.

OPAL_SCOPE_ID

Default: default

Scope identifier for multi-tenancy.

For more information, see OPAL scopes.

OPAL_OPAL_CLIENT_STAT_ID

Default: auto-generated

Unique client statistics identifier.

For more information, see monitoring OPAL.

OPAL_OFFLINE_MODE_ENABLED

Default: False

If set, OPAL client will try to load policy store from backup file and operate even if server is unreachable. Ignored if OPAL_INLINE_OPA_ENABLED=False.

Added in OPAL v0.6.0

OPAL_STORE_BACKUP_PATH

Default: /opal/backup/opa.json

Path to backup policy store's data to.

Added in OPAL v0.6.0

OPAL_STORE_BACKUP_INTERVAL

Default: 60

Interval in seconds to backup policy store's data.

Added in OPAL v0.6.0

Policy Store Configuration

OPAL_POLICY_STORE_TYPE

Default: opa

Type of policy store to use. Options: opa, cedar.

For more information, see Cedar and OPAL.

OPAL_POLICY_STORE_URL

Default: http://localhost:8181

The URL of the policy store (e.g., OPA agent).

OPAL_POLICY_STORE_AUTH_TYPE

Default: none

The authentication method for connecting to the policy store. Options: none, oauth, token.

OPAL_POLICY_STORE_AUTH_TOKEN

Default: None

The authentication (bearer) token OPAL client will use to authenticate against the policy store (i.e., OPA agent).

OPAL_POLICY_STORE_AUTH_OAUTH_SERVER

Default: None

The authentication server OPAL client will use to authenticate against for retrieving the access token.

OPAL_POLICY_STORE_AUTH_OAUTH_CLIENT_ID

Default: None

The client ID OPAL will use to authenticate against the OAuth server.

OPAL_POLICY_STORE_AUTH_OAUTH_CLIENT_SECRET

Default: None

The client secret OPAL will use to authenticate against the OAuth server.

OPAL_POLICY_STORE_TLS_CLIENT_CERT

Default: None

Path to the client certificate used for TLS authentication with the policy store.

Added in OPAL v0.7.2

OPAL_POLICY_STORE_TLS_CLIENT_KEY

Default: None

Path to the client key used for TLS authentication with the policy store.

Added in OPAL v0.7.2

OPAL_POLICY_STORE_TLS_CA

Default: None

Path to the file containing the CA certificate(s) used for TLS authentication with the policy store.

Added in OPAL v0.7.2

OPAL_EXCLUDE_POLICY_STORE_SECRETS

Default: False

If set, policy store secrets will be excluded from the /policy-store/config route.

Added in OPAL v0.7.8

OPAL_POLICY_STORE_CONN_RETRY

Default: {"retries": 3, "backoff_factor": 0.3}

Retry options when connecting to the policy store (i.e., the agent that handles the policy, e.g., OPA).

OPAL_POLICY_STORE_POLICY_PATHS_TO_IGNORE

Default: []

Which policy paths pushed to the client should be ignored. List of glob-style paths, or paths without wildcards but ending with "/**" indicating a parent path (ignoring all under it). Supports paths starting with '!' to force not ignoring them: a negated path always takes precedence.

OPAL_OPA_HEALTH_CHECK_POLICY_ENABLED

Default: False

Should we load a special healthcheck policy into OPA that checks that OPA was synced correctly and is ready to answer authorization queries.

For more information, see monitoring OPAL.

OPAL_OPA_HEALTH_CHECK_TRANSACTION_LOG_PATH

Default: system/opal/transactions

Path to OPA document that stores the OPA write transactions.

For more information, see monitoring OPAL.

OPAL_OPA_HEALTH_CHECK_POLICY_PATH

Default: engine/healthcheck/opal.rego

Path to the custom healthcheck policy file.

For more information, see monitoring OPAL.

Inline Engines Configuration

OPAL_INLINE_OPA_ENABLED

Default: True

Whether OPAL should run OPA by itself in the same container.

OPAL_INLINE_OPA_EXEC_PATH

Default: None

The path to the OPA executable. Defaults to searching for 'opa' binary in PATH if not specified.

OPAL_INLINE_OPA_CONFIG

Default: {}

If inline OPA is enabled, the user can set the server configuration options that affect how OPA will start when running opa run --server inline. Watch escaping quotes.

OPAL_INLINE_OPA_LOG_FORMAT

Default: none

The log format for inline OPA. Options: none, minimal, http, full.

OPAL_INLINE_CEDAR_ENABLED

Default: True

Whether OPAL should run Cedar agent by itself in the same container.

Added in OPAL v0.7.0

For more information, see Cedar and OPAL.

OPAL_INLINE_CEDAR_EXEC_PATH

Default: None

The path to the Cedar agent executable. Defaults to searching for 'cedar-agent' binary in PATH if not specified.

Added in OPAL v0.7.0

For more information, see Cedar and OPAL.

OPAL_INLINE_CEDAR_CONFIG

Default: {}

If inline Cedar is enabled, provide options for running the Cedar agent.

Added in OPAL v0.7.0

For more information, see Cedar and OPAL.

OPAL_INLINE_CEDAR_LOG_FORMAT

Default: none

The log format for inline Cedar. Options: none, minimal, http, full.

Added in OPAL v0.7.0

For more information, see Cedar and OPAL.

Policy Updates Configuration

OPAL_POLICY_UPDATER_ENABLED

Default: True

If set to FALSE, OPAL Client will not fetch policies or listen to policy updates.

OPAL_SPLIT_ROOT_DATA

Default: False

Split writing data updates to root path.

OPAL_POLICY_SUBSCRIPTION_DIRS

Default: ["."]

The directories in a policy repository to subscribe to for policy code (rego) modules.

For more information, see tracking a Git repository.

OPAL_POLICY_UPDATER_CONN_RETRY

Default: {"wait_strategy": "random_exponential", "max_wait": 10, "attempts": 5, "wait_time": 1}

Retry options when connecting to the policy source (e.g., the policy bundle server).

Data Updates Configuration

OPAL_DATA_UPDATER_ENABLED

Default: True

If set to FALSE, OPAL Client will not listen to dynamic data updates.

OPAL_DATA_TOPICS

Default: ["data"]

Data topics to subscribe to.

For more information, see subscribing to data topics.

OPAL_DEFAULT_DATA_SOURCES_CONFIG_URL

Default: {SERVER_URL}/data/config

Default URL to fetch data configuration from.

For more information, see configuring external data sources.

OPAL_DEFAULT_DATA_URL

Default: http://localhost:8000/policy-config

Default URL to fetch data from.

OPAL_SHOULD_REPORT_ON_DATA_UPDATES

Default: False

Should the client report on updates to callbacks defined in OPAL_DEFAULT_UPDATE_CALLBACKS or within the given updates.

For more information, see monitoring OPAL.

OPAL_DEFAULT_UPDATE_CALLBACK_CONFIG

Default: {"method": "POST", "headers": {"content-type": "application/json"}, "process_data": false}

Default configuration for update callbacks.

For more information, see monitoring OPAL.

OPAL_DEFAULT_UPDATE_CALLBACKS

Default: {"callbacks": ["{SERVER_URL}/data/callback_report"]}

Where/how the client should report on the completion of data updates.

For more information, see monitoring OPAL.

OPAL_DATA_UPDATER_CONN_RETRY

Default: {"wait_strategy": "random_exponential", "max_wait": 10, "attempts": 5, "wait_time": 1}

Retry options when connecting to the base data source (e.g., an external API server which returns data snapshot).

OPAL_DATA_STORE_CONN_RETRY

Default: None

note

DEPRECATED - The old confusing name for OPAL_DATA_UPDATER_CONN_RETRY, kept for backwards compatibility.

Added in OPAL v0.7.5

Advanced Configuration Options

CLI Help

# View all options
opal-server --help
opal-client --help

# View specific command options
opal-server run --help
opal-client run --help

Kubernetes Deployment

For Kubernetes deployments, see OPAL Helm Chart for Kubernetes.

Proxy Configuration

For proxy configurations, see Setup OPAL Behind a Proxy.

Source Code

Configuration Architecture

OPAL's configuration is based on our very own Confi module, which in turn is based on Decouple, and adds complex value parsing with Pydantic, and command line arguments via Typer/Click.