Deploy Permit to Production

When deploying to production, you might want to work with a local PDP (A Policy-Decision-Point microservice) within your VPC. The PDP is easy to install via Docker, and will ensure zero-latency, great performance, high availability, and improved security. Like all Permit customer deployed components, the Permit PDP is open-source.

Architecture diagram

Installing the PDP

Pull our PDP container from Docker Hub (Click here to install Docker):

docker pull permitio/pdp-v2:latest

Run the container & replace the PDP_API_KEY environment variable with your API key.

docker run -it \
  -p 7766:7000 \
  --env PDP_API_KEY=<YOUR_API_KEY> \
  --env PDP_DEBUG=True \
  permitio/pdp-v2:latest

Running the PDP with Organization/Project API Key

In some cases, you might want to use an Organization or Project API Key to authenticate with the PDP - instead of using the Environment API Key. That's useful when you want to have a single API Key for all your environments, or when you want to have a separate API Key for each of your projects - which is also great to reduce operations around Secrets management, one API Key (or few) to rule them all.

To do that, you can set the PDP_ORG_API_KEY or PDP_PROJECT_API_KEY environment variable instead of PDP_API_KEY. In addition -

• When setting Organization API Key, you'll need to set the PDP_ACTIVE_ENV and PDP_ACTIVE_PROJECT environment variables with the ID or Key of the environment and project you want to use.
• When setting Project API Key, you'll need to set the PDP_ACTIVE_ENV environment variable with the ID or Key of the environment you want to use.

For example, to run the PDP with an Organization API Key:

docker run -it \
  -p 7766:7000 \
  --env PDP_ORG_API_KEY=<YOUR_ORG_API_KEY> \
  --env PDP_ACTIVE_PROJECT=<YOUR_PROJECT_ID_OR_KEY> \
  --env PDP_ACTIVE_ENV=<YOUR_ENVIRONMENT_ID_OR_KEY> \
  --env PDP_DEBUG=True \
  permitio/pdp-v2:latest

And here's an example of running the PDP with a Project API Key:

docker run -it \
  -p 7766:7000 \
  --env PDP_PROJECT_API_KEY=<YOUR_PROJECT_API_KEY> \
  --env PDP_ACTIVE_ENV=<YOUR_ENVIRONMENT_ID_OR_KEY> \
  --env PDP_DEBUG=True \
  permitio/pdp-v2:latest

Using the PDP

The PDP will listen on port 7766 by default, so all you have to do is to set your PDP_URL in our SDK initialization to http://localhost:7766 and you're good to go.

For example in Node.js:

const permit = new Permit({
  pdp: "http://localhost:7766",
  token: "<YOUR_API_KEY>",
});

Exposing OPA within the PDP

Similar to a regular run of the PDP, with the addition of a single port mapping (-p 8181:8181) Run the container & replace the PDP_API_KEY environment variable with your API key.

docker run -it \
  -p 7766:7000 \
  -p 8181:8181 \
  --env PDP_API_KEY=<YOUR_API_KEY> \
  --env PDP_DEBUG=True \
  permitio/pdp-v2:latest

Reviews OPA's docs here for accessing its API.

System Requirements and Performance Optimization

When deploying your PDP in production, consider the following system requirements and performance tips to ensure optimal operation:

Where to start

CPU & memory requirements would obviously deeply depend on the scale of your application, but here are some good values to start with:

• CPU: ~200 mcores. but enable upper limit of at least ~1000 mcores to enable short CPU spikes and keep the PDP responsive
• Memory: ~512Mb

Scaling CPU

Processing demands of PDP would depend on the number of requests it has to handle, as well as the complexity of the queried policies. When CPU usage becomes a bottleneck, you can scale the PDP horizontally by deploying multiple instances behind a load balancer (e.g. scale replicas of Kubernetes deployment), thus distributing the load and increasing the number of requests the PDP can handle.

Scaling Memory

Memory usage of the PDP would depend on the volume of data in your environment. PDP makes use of OPA to achieve very fast policy evaluation, this speed of evaluation is achieved by:

• Storing the environment's policy data in its entirety in local process's memory.
• Using redundant data structures and caches. This means that scaling of your environment's policy data requires vertical scaling of the PDP's memory. And while exact requirements would depend on many factors (e.g. what attributes your objects have, complexity of relations between objects when ReBAC is used), we can suggest using the formula of # of policy objects X 6kb (where policy objects include: users, resource instances & tenants) as a rough estimate. For example: For environment of 100k users, 500k resource instances and 100 tenants, you'll need ~3.5Gb of memory.

For multi-tenant environments, data / memory can be scaled horizontally by using tenant based sharding.

General Performance Tips

To achieve high throughput and low latency:

• Use a Local PDP: Deploy the PDP in the same VPC as your application to minimize network latency.
• Disable Decision Debug Info: In production, you can turn off decision debug information to enhance performance. Disable debug logging by adding --env PDP_DEBUG=False to the PDP command line.
• Optimize Base Policy: Tailor the base policy to your specific use case. For example, disabling ReBAC checks (if not used) can speed up policy execution (this requires our tech support). With these optimizations, you can expect several thousand RPS with less than 10ms latency per request.

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.

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.

docker run -it -p 7766:7000 -p 8181:8181 
  --env PDP_API_KEY=<YOUR_API_KEY> \
  --env PDP_ENABLE_OFFLINE_MODE=true \
  -v <HOST_BACKUP_DIR_OR_NAMED_VOLUME>:/app/backup
  permitio/pdp-v2:latest

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.

How it works

PDP always 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.

For backing up the policy store's state (both policy rules/code & data), PDP internally uses OPAL's offline mode (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.

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.

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_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).