From dea5a3355061468efc6e617b67c1478bb8f552a9 Mon Sep 17 00:00:00 2001 From: Omer Zuarets Date: Tue, 24 Mar 2026 13:43:54 +0200 Subject: [PATCH 1/2] Update deployment documentation for PDP offline mode and backup strategies - Corrected spelling of "deliberately" in the offline data section. - Clarified the default behavior of PDP starting in online mode and its transition to offline mode. - Added details on the `PDP_OFFLINE_MODE_RESTORE_ONLY` flag for restoring from local backups. - Expanded the backup and restore resiliency section to emphasize the importance of frequent backups. - Updated the advanced configuration section with new parameters related to offline mode and backup management. --- docs/how-to/deploy/deploy-to-production.mdx | 19 +++++++++++++++---- 1 file changed, 15 insertions(+), 4 deletions(-) diff --git a/docs/how-to/deploy/deploy-to-production.mdx b/docs/how-to/deploy/deploy-to-production.mdx index 81216044..5767d892 100644 --- a/docs/how-to/deploy/deploy-to-production.mdx +++ b/docs/how-to/deploy/deploy-to-production.mdx @@ -157,18 +157,28 @@ When using `` instead of a volume, use `chmod` to set the permi ::: -If you need to delibrately run PDP with static offline data (e.g. in a CI environment), first generate the 2 backup files (configuration & policy store) by running your PDP in an online environment. Then you can run the PDP again in the offline environment - just make sure to use the same configuration and have those backup files in the directory/volume you mount onto `/app/backup`. +If you need to deliberately run PDP with static offline data (e.g. in a CI environment), first generate the 2 backup files (configuration & policy store) by running your PDP in an online environment. Then you can run the PDP again in the offline environment - just make sure to use the same configuration and have those backup files in the directory/volume you mount onto `/app/backup`. ### How it works -PDP always starts in online mode, trying to fetch its configuration from Permit's cloud. +By default, PDP starts in online mode, trying to fetch its configuration from Permit's cloud. In case of `PDP_CONFIG_FETCH_MAX_RETRIES` failed fetching attempts, and if `PDP_ENABLE_OFFLINE_MODE` is set to true - the PDP will switch to offline mode and load its configuration from the backup file (if it exists). Once PDP is up and running (whether loaded from cloud or from local backup) - it won't try to fetch or load its configuration again from cloud until it's restarted. +If `PDP_OFFLINE_MODE_RESTORE_ONLY` is set to true and valid backup files are available, the PDP will start from the local backup and will not connect to Permit Cloud for configuration or policy updates. This effectively pins the PDP to the restored local snapshot until it is restarted without that flag. + For backing up the policy store's state (both policy rules/code & data), PDP internally uses [OPAL's offline mode](https://docs.opal.ac/getting-started/running-opal/run-opal-client/opa-runner-parameters/#policy-store-backup) (no need to explicitly enable OPAL's offline mode, PDP would do it automatically). -OPAL uses policy and data from a backup file (if exists) to initialy load the policy store, but it never gives up on syncing with cloud - so once Permit cloud is reachable again, the most updated policy data could be fetched. +In the standard offline-mode flow, OPAL uses policy and data from a backup file (if it exists) to initially load the policy store, but it never gives up on syncing with cloud - so once Permit cloud is reachable again, the most updated policy data could be fetched. + +Policy store's backup is done periodically (See "Advanced Configuration" below for customizing the interval), and also on a graceful shutdown of the PDP. This backup file is written to the same directory as the PDP configuration backup. + +### Backup and Restore Resiliency + +For stronger resilience, it is recommended to back up the volume or host directory mounted to the path configured by `PDP_OFFLINE_MODE_BACKUP_DIR` (default: `/app/backup`) frequently. This gives you an additional recovery point if the local backup files become corrupted or if policy data is deleted accidentally, allowing you to restore the PDP locally while the corresponding state is being restored in the Permit control plane. + +When restoring the backup directory to an earlier point in time, and the Permit control plane is still reachable, start the PDP with `PDP_OFFLINE_MODE_RESTORE_ONLY=true`. When this mode is enabled and valid backup files are present, the PDP will continue serving decisions from the restored local snapshot and will not connect to the control plane for further configuration or policy updates. This prevents the restored snapshot from being overwritten by newer state that still exists in the control plane. -Policy store's backup is is done periodically (See "Advanced Configuration" below for customizing the interval), and also on a graceful shutdown of the PDP. This backup file is written to the same directory as the PDP configuration backup. +After the desired state has also been restored in the control plane, restart the PDP without `PDP_OFFLINE_MODE_RESTORE_ONLY` so normal synchronization can resume. ### Advanced Configuration @@ -176,6 +186,7 @@ Policy store's backup is is done periodically (See "Advanced Configuration" belo * `PDP_OFFLINE_MODE_BACKUP_DIR` Sets the directory path of the PDP's configuration backup file (default "/app/backup") * `PDP_OFFLINE_MODE_BACKUP_FILENAME` Sets the file name of the PDP's configuration backup file (default "pdp_cloud_config_backup.json") * `PDP_OFFLINE_MODE_POLICY_BACKUP_FILENAME` Sets the file name of the policy store's backup (holds both data & code) within the PDP's backup dir. This replaces OPAL's `OPAL_STORE_BACKUP_PATH`. (default "policy_store_backup.json") +* `PDP_OFFLINE_MODE_RESTORE_ONLY` - If set to true and valid backup files exist, forces the PDP to use the local backup as the active snapshot and skip synchronization with Permit Cloud. Useful for point-in-time restores and controlled recovery scenarios. (default: false) * `PDP_CONFIG_FETCH_MAX_RETRIES` - Would determine after how many retries (to fetch cloud configuration) the PDP should switch to offline mode (default: 6) * `OPAL_STORE_BACKUP_INTERVAL` - Determines how often would the policy store backup be saved. (default: 1m) From 23943f753cfc671ec89e78b23e03b96856537967 Mon Sep 17 00:00:00 2001 From: Omer Zuarets Date: Sun, 29 Mar 2026 17:42:50 +0300 Subject: [PATCH 2/2] Separate PDP offline mode into its own page and document connectivity control API Move offline mode content from deploy-to-production into a dedicated page, add documentation for the new control plane connectivity control endpoints and PDP_CONTROL_PLANE_CONNECTIVITY_DISABLED config option. Co-Authored-By: Claude Opus 4.6 (1M context) --- docs/how-to/deploy/deploy-to-production.mdx | 61 +------ docs/how-to/deploy/offline-mode.mdx | 167 ++++++++++++++++++++ sidebars.js | 1 + 3 files changed, 170 insertions(+), 59 deletions(-) create mode 100644 docs/how-to/deploy/offline-mode.mdx diff --git a/docs/how-to/deploy/deploy-to-production.mdx b/docs/how-to/deploy/deploy-to-production.mdx index 5767d892..26f2eb6b 100644 --- a/docs/how-to/deploy/deploy-to-production.mdx +++ b/docs/how-to/deploy/deploy-to-production.mdx @@ -134,63 +134,6 @@ To achieve high throughput and low latency: ## PDP Offline Mode -The PDP relies on Permit's cloud for fetching configuration, loading policies, and keeping those up to date. -Despite the high availability of Permit's cloud, there still might be cases when the PDP can't reach it (e.g. network issues). -For extra resilience, the PDP can be configured to work in offline mode, where it will use a local backup of the configuration, data, and policies. +For extra resilience, the PDP can be configured to work in offline mode, serving decisions from a local backup when it can't reach Permit's cloud. Offline mode also supports starting the PDP fully disconnected from the control plane, with runtime API endpoints to toggle connectivity without restarting. -### Using Offline Mode - -To enable the PDP offline mode, use the `PDP_ENABLE_OFFLINE_MODE` environment variable. -You would also have to mount a volume or a host directory to the PDP container at `/app/backup`, where the backup files will be persisted. -When PDP offline mode is enabled, the PDP will automatically enable OPAL's offline mode, and will use the backup files from the mounted volume. - -```sh -docker run -it -p 7766:7000 -p 8181:8181 - --env PDP_API_KEY= \ - --env PDP_ENABLE_OFFLINE_MODE=true \ - -v :/app/backup - permitio/pdp-v2:latest -``` - -:::tip -When using `` instead of a volume, use `chmod` to set the permissions of `` to 777. This allows the container to write logs properly. -::: - - -If you need to deliberately run PDP with static offline data (e.g. in a CI environment), first generate the 2 backup files (configuration & policy store) by running your PDP in an online environment. Then you can run the PDP again in the offline environment - just make sure to use the same configuration and have those backup files in the directory/volume you mount onto `/app/backup`. - -### How it works -By default, PDP starts in online mode, trying to fetch its configuration from Permit's cloud. -In case of `PDP_CONFIG_FETCH_MAX_RETRIES` failed fetching attempts, and if `PDP_ENABLE_OFFLINE_MODE` is set to true - the PDP will switch to offline mode and load its configuration from the backup file (if it exists). -Once PDP is up and running (whether loaded from cloud or from local backup) - it won't try to fetch or load its configuration again from cloud until it's restarted. - -If `PDP_OFFLINE_MODE_RESTORE_ONLY` is set to true and valid backup files are available, the PDP will start from the local backup and will not connect to Permit Cloud for configuration or policy updates. This effectively pins the PDP to the restored local snapshot until it is restarted without that flag. - -For backing up the policy store's state (both policy rules/code & data), PDP internally uses [OPAL's offline mode](https://docs.opal.ac/getting-started/running-opal/run-opal-client/opa-runner-parameters/#policy-store-backup) -(no need to explicitly enable OPAL's offline mode, PDP would do it automatically). -In the standard offline-mode flow, OPAL uses policy and data from a backup file (if it exists) to initially load the policy store, but it never gives up on syncing with cloud - so once Permit cloud is reachable again, the most updated policy data could be fetched. - -Policy store's backup is done periodically (See "Advanced Configuration" below for customizing the interval), and also on a graceful shutdown of the PDP. This backup file is written to the same directory as the PDP configuration backup. - -### Backup and Restore Resiliency - -For stronger resilience, it is recommended to back up the volume or host directory mounted to the path configured by `PDP_OFFLINE_MODE_BACKUP_DIR` (default: `/app/backup`) frequently. This gives you an additional recovery point if the local backup files become corrupted or if policy data is deleted accidentally, allowing you to restore the PDP locally while the corresponding state is being restored in the Permit control plane. - -When restoring the backup directory to an earlier point in time, and the Permit control plane is still reachable, start the PDP with `PDP_OFFLINE_MODE_RESTORE_ONLY=true`. When this mode is enabled and valid backup files are present, the PDP will continue serving decisions from the restored local snapshot and will not connect to the control plane for further configuration or policy updates. This prevents the restored snapshot from being overwritten by newer state that still exists in the control plane. - -After the desired state has also been restored in the control plane, restart the PDP without `PDP_OFFLINE_MODE_RESTORE_ONLY` so normal synchronization can resume. - - -### Advanced Configuration - -* `PDP_OFFLINE_MODE_BACKUP_DIR` Sets the directory path of the PDP's configuration backup file (default "/app/backup") -* `PDP_OFFLINE_MODE_BACKUP_FILENAME` Sets the file name of the PDP's configuration backup file (default "pdp_cloud_config_backup.json") -* `PDP_OFFLINE_MODE_POLICY_BACKUP_FILENAME` Sets the file name of the policy store's backup (holds both data & code) within the PDP's backup dir. This replaces OPAL's `OPAL_STORE_BACKUP_PATH`. (default "policy_store_backup.json") -* `PDP_OFFLINE_MODE_RESTORE_ONLY` - If set to true and valid backup files exist, forces the PDP to use the local backup as the active snapshot and skip synchronization with Permit Cloud. Useful for point-in-time restores and controlled recovery scenarios. (default: false) -* `PDP_CONFIG_FETCH_MAX_RETRIES` - Would determine after how many retries (to fetch cloud configuration) the PDP should switch to offline mode (default: 6) -* `OPAL_STORE_BACKUP_INTERVAL` - Determines how often would the policy store backup be saved. (default: 1m) - -### Security Considerations - -PDP's configuration backup file is securely encrypted on disk using a key derived from your secret `PDP_API_KEY` token. -Currently OPAL's backup file of the policy store is not encrypted, so make sure to secure the mounted host directory / volume where the backup files are stored. (let us know if that's something you need). +See the dedicated [PDP Offline Mode](/how-to/deploy/offline-mode) page for full details on setup, configuration, and the connectivity control API. diff --git a/docs/how-to/deploy/offline-mode.mdx b/docs/how-to/deploy/offline-mode.mdx new file mode 100644 index 00000000..24ebdce8 --- /dev/null +++ b/docs/how-to/deploy/offline-mode.mdx @@ -0,0 +1,167 @@ +--- +sidebar_position: 2 +title: PDP Offline Mode +description: "Configure the PDP to work offline with local backups and runtime connectivity control" +--- + +The PDP relies on Permit's cloud for fetching configuration, loading policies, and keeping those up to date. +Despite the high availability of Permit's cloud, there still might be cases when the PDP can't reach it (e.g. network issues). +For extra resilience, the PDP can be configured to work in offline mode, where it will use a local backup of the configuration, data, and policies. + +## Using Offline Mode + +To enable the PDP offline mode, use the `PDP_ENABLE_OFFLINE_MODE` environment variable. +You would also have to mount a volume or a host directory to the PDP container at `/app/backup`, where the backup files will be persisted. +When PDP offline mode is enabled, the PDP will automatically enable OPAL's offline mode, and will use the backup files from the mounted volume. + +```sh +docker run -it -p 7766:7000 -p 8181:8181 \ + --env PDP_API_KEY= \ + --env PDP_ENABLE_OFFLINE_MODE=true \ + -v :/app/backup \ + permitio/pdp-v2:latest +``` + +:::tip +When using `` instead of a volume, use `chmod` to set the permissions of `` to 777. This allows the container to write logs properly. +::: + + +If you need to deliberately run PDP with static offline data (e.g. in a CI environment), first generate the 2 backup files (configuration & policy store) by running your PDP in an online environment. Then you can run the PDP again in the offline environment - just make sure to use the same configuration and have those backup files in the directory/volume you mount onto `/app/backup`. + +## How it works +By default, PDP starts in online mode, trying to fetch its configuration from Permit's cloud. +In case of `PDP_CONFIG_FETCH_MAX_RETRIES` failed fetching attempts, and if `PDP_ENABLE_OFFLINE_MODE` is set to true - the PDP will switch to offline mode and load its configuration from the backup file (if it exists). +Once PDP is up and running (whether loaded from cloud or from local backup) - it won't try to fetch or load its configuration again from cloud until it's restarted. + +If `PDP_OFFLINE_MODE_RESTORE_ONLY` is set to true and valid backup files are available, the PDP will start from the local backup and will not connect to Permit Cloud for configuration or policy updates. This effectively pins the PDP to the restored local snapshot until it is restarted without that flag. + +For backing up the policy store's state (both policy rules/code & data), PDP internally uses [OPAL's offline mode](https://docs.opal.ac/getting-started/running-opal/run-opal-client/opa-runner-parameters/#policy-store-backup) +(no need to explicitly enable OPAL's offline mode, PDP would do it automatically). +In the standard offline-mode flow, OPAL uses policy and data from a backup file (if it exists) to initially load the policy store, but it never gives up on syncing with cloud - so once Permit cloud is reachable again, the most updated policy data could be fetched. + +Policy store's backup is done periodically (See "Advanced Configuration" below for customizing the interval), and also on a graceful shutdown of the PDP. This backup file is written to the same directory as the PDP configuration backup. + +## Starting Disconnected from the Control Plane + +In some scenarios you may want the PDP to boot completely disconnected from the Permit control plane — for example, in air-gapped environments or during planned maintenance windows — and only reconnect later on your terms. + +To start the PDP disconnected, set both `PDP_ENABLE_OFFLINE_MODE` and `PDP_CONTROL_PLANE_CONNECTIVITY_DISABLED` to true. The PDP will load its configuration and policies entirely from local backup and will **not** attempt to connect to Permit's cloud on startup. + +```sh +docker run -it -p 7766:7000 \ + --env PDP_API_KEY= \ + --env PDP_ENABLE_OFFLINE_MODE=true \ + --env PDP_CONTROL_PLANE_CONNECTIVITY_DISABLED=true \ + -v :/app/backup \ + permitio/pdp-v2:latest +``` + +:::note +`PDP_CONTROL_PLANE_CONNECTIVITY_DISABLED` only takes effect when `PDP_ENABLE_OFFLINE_MODE` is also enabled. +::: + +You can later reconnect the PDP to the control plane at runtime using the connectivity API described below. + +## Runtime Connectivity Control + +When offline mode is enabled, the PDP exposes HTTP endpoints that let you toggle control plane connectivity at runtime — without restarting the container. + +All connectivity endpoints are authenticated with the PDP API key (the same `PDP_API_KEY` used to start the PDP). Pass it via the `Authorization: Bearer ` header. + +### Get Connectivity Status + +``` +GET /control-plane/connectivity +``` + +Returns the current connectivity state. + +**Response:** + +```json +{ + "control_plane_connectivity_disabled": true, + "offline_mode_enabled": true +} +``` + +| Field | Description | +|---|---| +| `control_plane_connectivity_disabled` | `true` when the PDP is disconnected from the control plane | +| `offline_mode_enabled` | `true` when offline mode is enabled on this PDP | + +### Enable Connectivity (Reconnect) + +``` +POST /control-plane/connectivity/enable +``` + +Reconnects the PDP to the control plane. This starts the policy and data updaters, triggering a full rehydration — the PDP will refetch policies and data from Permit's cloud. + +**Response:** + +```json +{ "status": "enabled" } +``` + +Returns `{ "status": "already_enabled" }` if connectivity is already active. + +Returns `400 Bad Request` if offline mode is not enabled. + +### Disable Connectivity (Disconnect) + +``` +POST /control-plane/connectivity/disable +``` + +Disconnects the PDP from the control plane. This stops the policy and data updaters. The policy store continues serving decisions from its current in-memory state. + +**Response:** + +```json +{ "status": "disabled" } +``` + +Returns `{ "status": "already_disabled" }` if connectivity is already disabled. + +Returns `400 Bad Request` if offline mode is not enabled. + +### Example: Reconnecting a Disconnected PDP + +```sh +# Check current status +curl -s http://localhost:7766/control-plane/connectivity \ + -H "Authorization: Bearer " + +# Reconnect to the control plane +curl -s -X POST http://localhost:7766/control-plane/connectivity/enable \ + -H "Authorization: Bearer " +``` + +## Backup and Restore Resiliency + +For stronger resilience, it is recommended to back up the volume or host directory mounted to the path configured by `PDP_OFFLINE_MODE_BACKUP_DIR` (default: `/app/backup`) frequently. This gives you an additional recovery point if the local backup files become corrupted or if policy data is deleted accidentally, allowing you to restore the PDP locally while the corresponding state is being restored in the Permit control plane. + +When restoring the backup directory to an earlier point in time, and the Permit control plane is still reachable, start the PDP with `PDP_OFFLINE_MODE_RESTORE_ONLY=true`. When this mode is enabled and valid backup files are present, the PDP will continue serving decisions from the restored local snapshot and will not connect to the control plane for further configuration or policy updates. This prevents the restored snapshot from being overwritten by newer state that still exists in the control plane. + +After the desired state has also been restored in the control plane, restart the PDP without `PDP_OFFLINE_MODE_RESTORE_ONLY` so normal synchronization can resume. + + +## Advanced Configuration + +| Variable | Description | Default | +|---|---|---| +| `PDP_ENABLE_OFFLINE_MODE` | Enables offline mode with local backup and restore | `false` | +| `PDP_CONTROL_PLANE_CONNECTIVITY_DISABLED` | When `true` (and offline mode is enabled), the PDP starts disconnected from the control plane and serves from local backup. Can be toggled at runtime via the `/control-plane/connectivity` endpoints. | `false` | +| `PDP_OFFLINE_MODE_BACKUP_DIR` | Directory path for the PDP's configuration backup file | `/app/backup` | +| `PDP_OFFLINE_MODE_BACKUP_FILENAME` | File name of the PDP's configuration backup file | `pdp_cloud_config_backup.json` | +| `PDP_OFFLINE_MODE_POLICY_BACKUP_FILENAME` | File name of the policy store's backup (holds both data & code) within the PDP's backup dir. This replaces OPAL's `OPAL_STORE_BACKUP_PATH`. | `policy_store_backup.json` | +| `PDP_OFFLINE_MODE_RESTORE_ONLY` | If set to `true` and valid backup files exist, forces the PDP to use the local backup as the active snapshot and skip synchronization with Permit Cloud. Useful for point-in-time restores and controlled recovery scenarios. | `false` | +| `PDP_CONFIG_FETCH_MAX_RETRIES` | Number of failed fetch attempts before the PDP switches to offline mode | `6` | +| `OPAL_STORE_BACKUP_INTERVAL` | How often the policy store backup is saved | `1m` | + +## Security Considerations + +PDP's configuration backup file is securely encrypted on disk using a key derived from your secret `PDP_API_KEY` token. +Currently OPAL's backup file of the policy store is not encrypted, so make sure to secure the mounted host directory / volume where the backup files are stored. (let us know if that's something you need). diff --git a/sidebars.js b/sidebars.js index 72d90cce..860abcd2 100644 --- a/sidebars.js +++ b/sidebars.js @@ -438,6 +438,7 @@ const sidebars = { label: "Deploy", link: { type: "doc", id: "how-to/deploy/deploy-to-production" }, items: [ + "how-to/deploy/offline-mode", "how-to/SDLC/CI-CD", { type: "category",