Add docs about Backup & Restore of offline mode#617
Open
Conversation
…egies - 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.
✅ Deploy Preview for permitio-docs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
Contributor
There was a problem hiding this comment.
Pull request overview
Updates the production deployment documentation to better explain PDP offline mode behavior, including backup/restore workflows and a restore-only startup flag.
Changes:
- Fixes spelling and clarifies PDP’s online-to-offline startup flow.
- Documents
PDP_OFFLINE_MODE_RESTORE_ONLYand adds guidance for point-in-time restore scenarios. - Expands backup resiliency guidance and updates the advanced configuration parameter list.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| 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. |
There was a problem hiding this comment.
The doc uses inconsistent naming/capitalization for the same service ("Permit's cloud", "Permit Cloud", and "Permit cloud") within this section. Please standardize the term (and casing) to match the rest of the docs and keep it consistent within this page.
Suggested change
| 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. | |
| 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. |
|
|
||
| ### 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. |
There was a problem hiding this comment.
This section now references PDP_OFFLINE_MODE_BACKUP_DIR, but earlier in "Using Offline Mode" the doc still instructs mounting specifically to /app/backup. Since the backup directory is configurable, consider updating the earlier instructions (or clarify here) to mount to the directory configured by PDP_OFFLINE_MODE_BACKUP_DIR (defaulting to /app/backup) to avoid confusing readers.
Suggested change
| 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. | |
| For stronger resilience, it is recommended to back up the volume or host directory that you mounted into the container at 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. |
|
|
||
| ### Advanced Configuration | ||
|
|
||
| * `PDP_OFFLINE_MODE_BACKUP_DIR` Sets the directory path of the PDP's configuration backup file (default "/app/backup") |
There was a problem hiding this comment.
PDP_OFFLINE_MODE_BACKUP_DIR is described as a directory path of the configuration backup file, but this variable appears to represent the backup directory used for multiple backup files (and is a directory, not a file path). Please reword to reflect that it sets the backup directory for PDP offline-mode files.
Suggested change
| * `PDP_OFFLINE_MODE_BACKUP_DIR` Sets the directory path of the PDP's configuration backup file (default "/app/backup") | |
| * `PDP_OFFLINE_MODE_BACKUP_DIR` Sets the directory used to store PDP offline-mode backup files (default "/app/backup") |
Comment on lines
+189
to
191
| * `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) |
There was a problem hiding this comment.
Bullet formatting is inconsistent with the surrounding items: this entry adds a dash after the env var name and uses (default: false) while adjacent bullets omit the dash and use (default "..."). Please align formatting with the rest of this list for consistency.
Suggested change
| * `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) | |
| * `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` Determines after how many retries (to fetch cloud configuration) the PDP should switch to offline mode (default "6") | |
| * `OPAL_STORE_BACKUP_INTERVAL` Determines how often the policy store backup is saved. (default "1m") |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
PDP_OFFLINE_MODE_RESTORE_ONLYflag for restoring from local backups.