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.