From a73ce43bb411d3b7602b4d0ffd0f46e81ca63acb Mon Sep 17 00:00:00 2001 From: eli Date: Wed, 23 Sep 2026 15:56:33 -0500 Subject: [PATCH 1/4] docs(nexus-pdp): the image is permitio/nexus-pdp, not permitio/pdp-v3 cloud-pdp#157 (PER-16042) publishes the Nexus PDP image as permitio/nexus-pdp only; the old repository is frozen. Merge before, or with, the first cloud-pdp release after #157 merges. Co-Authored-By: Claude Opus 5.5 (1M context) --- docs/concepts/pdp/nexus-pdp-configuration.mdx | 4 ++-- docs/concepts/pdp/nexus-pdp-deployment.mdx | 10 +++++----- docs/concepts/pdp/nexus-pdp-feature-parity.mdx | 4 ++-- docs/concepts/pdp/nexus-pdp-how-it-works.mdx | 4 ++-- docs/concepts/pdp/nexus-pdp.mdx | 2 +- docs/concepts/pdp/overview.mdx | 2 +- 6 files changed, 13 insertions(+), 13 deletions(-) diff --git a/docs/concepts/pdp/nexus-pdp-configuration.mdx b/docs/concepts/pdp/nexus-pdp-configuration.mdx index d8aec7c6..05f57d3a 100644 --- a/docs/concepts/pdp/nexus-pdp-configuration.mdx +++ b/docs/concepts/pdp/nexus-pdp-configuration.mdx @@ -1,11 +1,11 @@ --- title: Nexus PDP configuration reference sidebar_label: Configuration -description: "Look up the environment variables that configure Permit Nexus PDP (permitio/pdp-v3): credentials, storage, ports, logging, and storage-engine tuning." +description: "Look up the environment variables that configure Permit Nexus PDP (permitio/nexus-pdp): credentials, storage, ports, logging, and storage-engine tuning." sidebar_position: 6 --- -This reference lists the environment variables that configure Permit Nexus PDP (`permitio/pdp-v3`), a self-hosted policy decision point (PDP). It is for operators who deploy and tune Nexus PDP. The only required variable is `PDP_API_KEY`. For deployment requirements such as volumes, probes, and memory, see [Deploy Nexus PDP](/concepts/pdp/nexus-pdp-deployment). +This reference lists the environment variables that configure Permit Nexus PDP (`permitio/nexus-pdp`), a self-hosted policy decision point (PDP). It is for operators who deploy and tune Nexus PDP. The only required variable is `PDP_API_KEY`. For deployment requirements such as volumes, probes, and memory, see [Deploy Nexus PDP](/concepts/pdp/nexus-pdp-deployment). :::caution Nexus PDP configuration can change between early-access releases As of September 2026, Nexus PDP is in early access. Permit can rename, replace, or remove the variables and defaults on this page before general availability. Pin the Nexus PDP image to a specific tag, and check this page when you upgrade. If you depend on a specific variable, tell Permit support at [support@permit.io](mailto:support@permit.io). diff --git a/docs/concepts/pdp/nexus-pdp-deployment.mdx b/docs/concepts/pdp/nexus-pdp-deployment.mdx index b2ea83b4..6bd2d8da 100644 --- a/docs/concepts/pdp/nexus-pdp-deployment.mdx +++ b/docs/concepts/pdp/nexus-pdp-deployment.mdx @@ -5,7 +5,7 @@ description: "Run Permit Nexus PDP with Docker or Kubernetes, meet its storage, sidebar_position: 5 --- -Run Permit Nexus PDP (`permitio/pdp-v3`), a self-hosted policy decision point (PDP), with Docker or on Kubernetes, and verify that it answers permission checks. This page lists the storage, memory, port, probe, and shutdown requirements, gives a runnable command and a pod spec, and covers the Nexus PDP logs and security properties an operator needs. For what Nexus PDP is, see [Permit Nexus PDP](/concepts/pdp/nexus-pdp). +Run Permit Nexus PDP (`permitio/nexus-pdp`), a self-hosted policy decision point (PDP), with Docker or on Kubernetes, and verify that it answers permission checks. This page lists the storage, memory, port, probe, and shutdown requirements, gives a runnable command and a pod spec, and covers the Nexus PDP logs and security properties an operator needs. For what Nexus PDP is, see [Permit Nexus PDP](/concepts/pdp/nexus-pdp). ## Prerequisites @@ -19,7 +19,7 @@ Nexus PDP has operational requirements that the container PDP (the Edge PDP imag | Requirement | Setting | What happens if you skip it | | --- | --- | --- | -| Image | `permitio/pdp-v3`, pinned to a specific tag | An unpinned image can pull a release with renamed configuration variables. See [Nexus PDP configuration reference](/concepts/pdp/nexus-pdp-configuration). | +| Image | `permitio/nexus-pdp`, pinned to a specific tag | An unpinned image can pull a release with renamed configuration variables. See [Nexus PDP configuration reference](/concepts/pdp/nexus-pdp-configuration). | | One container per environment | Set `PDP_API_KEY` to the API key of one Permit environment | Nexus PDP has no multi-environment mode. The API key binds the container to exactly one environment. | | Persistent storage | Mount a persistent volume at `/var/lib/edge-pdp`, which holds the embedded database and the event store at default paths | On ephemeral storage, every restart runs a full cold start with a snapshot transfer of your whole data set. | | Memory | 4 GiB to start | At default storage-engine settings, a container with a few hundred MiB is killed for running out of memory (OOM) at startup. See [Nexus PDP resource footprint](/concepts/pdp/nexus-pdp-how-it-works#resource-footprint). | @@ -32,7 +32,7 @@ Nexus PDP has operational requirements that the container PDP (the Edge PDP imag ## Run Nexus PDP with Docker -Replace `` with a specific `permitio/pdp-v3` release tag, and set `PERMIT_API_KEY` in your shell to the API key of the environment this container serves. The command maps the authorization API to host port `7766`, keeps the health port on `7001`, and stores the embedded database in the named volume `nexus-data`: +Replace `` with a specific `permitio/nexus-pdp` release tag, and set `PERMIT_API_KEY` in your shell to the API key of the environment this container serves. The command maps the authorization API to host port `7766`, keeps the health port on `7001`, and stores the embedded database in the named volume `nexus-data`: ```bash docker run -d --name nexus-pdp \ @@ -40,7 +40,7 @@ docker run -d --name nexus-pdp \ -e PDP_API_KEY="$PERMIT_API_KEY" \ -v nexus-data:/var/lib/edge-pdp \ --memory 4g \ - permitio/pdp-v3: + permitio/nexus-pdp: ``` ## Kubernetes pod settings for Nexus PDP @@ -53,7 +53,7 @@ securityContext: fsGroup: 10001 containers: - name: nexus-pdp - image: permitio/pdp-v3: + image: permitio/nexus-pdp: ports: - containerPort: 7000 # authorization API - containerPort: 7001 # health diff --git a/docs/concepts/pdp/nexus-pdp-feature-parity.mdx b/docs/concepts/pdp/nexus-pdp-feature-parity.mdx index 070d25a3..c8bf0e91 100644 --- a/docs/concepts/pdp/nexus-pdp-feature-parity.mdx +++ b/docs/concepts/pdp/nexus-pdp-feature-parity.mdx @@ -1,11 +1,11 @@ --- title: Nexus PDP feature parity sidebar_label: Feature Parity -description: "Compare the endpoints and capabilities of the container PDP (permitio/pdp-v2) and Permit Nexus PDP (permitio/pdp-v3) before you choose one." +description: "Compare the endpoints and capabilities of the container PDP (permitio/pdp-v2) and Permit Nexus PDP (permitio/nexus-pdp) before you choose one." sidebar_position: 4 --- -Use this page to check whether Permit Nexus PDP, a self-hosted policy decision point (PDP), supports the endpoints and capabilities your application uses before you choose Nexus PDP or move to it. The page compares Nexus PDP (`permitio/pdp-v3`) with the [container PDP](/concepts/pdp/overview#run-an-edge-pdp-with-docker), the Edge PDP image `permitio/pdp-v2`. +Use this page to check whether Permit Nexus PDP, a self-hosted policy decision point (PDP), supports the endpoints and capabilities your application uses before you choose Nexus PDP or move to it. The page compares Nexus PDP (`permitio/nexus-pdp`) with the [container PDP](/concepts/pdp/overview#run-an-edge-pdp-with-docker), the Edge PDP image `permitio/pdp-v2`. :::info Nexus PDP support changes between releases This comparison describes Nexus PDP as of September 2026, during early access. The set of supported capabilities changes between releases, so check this page before you upgrade. diff --git a/docs/concepts/pdp/nexus-pdp-how-it-works.mdx b/docs/concepts/pdp/nexus-pdp-how-it-works.mdx index 8f4bedbb..32e9d0db 100644 --- a/docs/concepts/pdp/nexus-pdp-how-it-works.mdx +++ b/docs/concepts/pdp/nexus-pdp-how-it-works.mdx @@ -61,7 +61,7 @@ A Nexus PDP that restarts with a backlog of changes becomes ready and serves req Nexus PDP delivers a change to the PDP in fewer steps than the container PDP: -| | Container PDP (`pdp-v2`) | Nexus PDP (`pdp-v3`) | +| | Container PDP (`pdp-v2`) | Nexus PDP (`nexus-pdp`) | | --- | --- | --- | | Change notification | WebSocket notification | Push delivery on a durable subscription for each PDP | | Data fetch | A second request to the Permit API | None. The message contains the change. | @@ -117,7 +117,7 @@ Permit has not published measured throughput for Nexus PDP. The [Cloud PDP bench Nexus PDP stores authorization data in a different place than the container PDP, which changes how you size the container. -| | Container PDP (`pdp-v2`) | Nexus PDP (`pdp-v3`) | +| | Container PDP (`pdp-v2`) | Nexus PDP (`nexus-pdp`) | | --- | --- | --- | | Authorization data | In OPA's in-memory document | On disk, in an embedded database | | Memory as data grows | Grows with your data set | Limited by a cache size you configure | diff --git a/docs/concepts/pdp/nexus-pdp.mdx b/docs/concepts/pdp/nexus-pdp.mdx index 505a37e9..ea855bfc 100644 --- a/docs/concepts/pdp/nexus-pdp.mdx +++ b/docs/concepts/pdp/nexus-pdp.mdx @@ -11,7 +11,7 @@ import ProductOverviewLink from "@site/src/components/ProductOverviewLink"; Permit Nexus PDP is a self-hosted policy decision point (PDP) that keeps your environment's policy and authorization data in an embedded on-disk database. This page is for architects and platform engineers who decide whether to run Nexus PDP instead of, or next to, the container PDP. -Nexus PDP ships as the `permitio/pdp-v3` container image. You run one Nexus PDP container per Permit environment in your own network. Nexus PDP answers each authorization query from its local copy of the data, so no hop in the decision path leaves the container. +Nexus PDP ships as the `permitio/nexus-pdp` container image. You run one Nexus PDP container per Permit environment in your own network. Nexus PDP answers each authorization query from its local copy of the data, so no hop in the decision path leaves the container. :::note Early access and relationship to the container PDP Nexus PDP is an additional deployment option. It does not replace the container PDP (`permitio/pdp-v2`), which remains supported and is the PDP to use for the capabilities listed as unsupported in [Nexus PDP feature parity](/concepts/pdp/nexus-pdp-feature-parity). diff --git a/docs/concepts/pdp/overview.mdx b/docs/concepts/pdp/overview.mdx index 0b915c84..127b7114 100644 --- a/docs/concepts/pdp/overview.mdx +++ b/docs/concepts/pdp/overview.mdx @@ -21,7 +21,7 @@ Permit offers three PDP types. All three answer the same permission checks for t | --- | --- | --- | | **Managed Cloud PDP** | Hosted by Permit at `https://cloudpdp.api.permit.io` | Fast onboarding and production role-based access control (RBAC) or relationship-based access control (ReBAC) without running infrastructure | | **Edge PDP** (container PDP, `permitio/pdp-v2`) | Your VPC, Kubernetes cluster, or VMs, as a sidecar, a centralized service, or a cluster | Attribute-based access control (ABAC), custom data sources, read-your-own-writes, PDP-level callbacks and health checks, or low latency inside your own network | -| **Permit Nexus PDP** (`permitio/pdp-v3`) | Your network, one container per Permit environment | Large data sets, relationship-heavy ReBAC, and decisions that never depend on reaching Permit | +| **Permit Nexus PDP** (`permitio/nexus-pdp`) | Your network, one container per Permit environment | Large data sets, relationship-heavy ReBAC, and decisions that never depend on reaching Permit | Most teams start with the managed Cloud PDP, then add Edge PDPs for latency-sensitive workloads or for capabilities the Cloud PDP does not support. From 083fed81e34d4757df31460ecdd9f1c0cd7a8970 Mon Sep 17 00:00:00 2001 From: eli Date: Wed, 30 Sep 2026 08:57:54 -0500 Subject: [PATCH 2/4] PER-16042: address Zeev's review of the Nexus PDP image-name docs - PDP_API_KEY is the environment's Nexus PDP API key (Copy Nexus PDP API Key in the dashboard), not the ordinary environment API key, which fails at startup: prerequisites, requirements table, Docker and pod-spec intros, and the configuration reference. - permitio/nexus-pdp has no latest tag and no release tag yet: the image row now warns about moving tags such as 0-beta, and the Docker step says to pin an exact tag. - New 'Image name and tags' section on the overview: releases up to 0.6.1 are permitio/pdp-v3, which gets no new tags; don't reuse a pdp-v3 tag name under nexus-pdp. - The architecture diagram says Nexus PDP, not New Edge PDP. Co-Authored-By: Claude Opus 5.5 --- docs/concepts/pdp/nexus-pdp-configuration.mdx | 2 +- docs/concepts/pdp/nexus-pdp-deployment.mdx | 14 +++---- docs/concepts/pdp/nexus-pdp.mdx | 6 +++ static/images/pdp/nexus-pdp-architecture.svg | 42 +++++++++---------- 4 files changed, 35 insertions(+), 29 deletions(-) diff --git a/docs/concepts/pdp/nexus-pdp-configuration.mdx b/docs/concepts/pdp/nexus-pdp-configuration.mdx index 05f57d3a..66fdbdf5 100644 --- a/docs/concepts/pdp/nexus-pdp-configuration.mdx +++ b/docs/concepts/pdp/nexus-pdp-configuration.mdx @@ -17,7 +17,7 @@ The container PDP (the Edge PDP image `permitio/pdp-v2`) uses a different set of | Variable | Default | Description | | --- | --- | --- | -| `PDP_API_KEY` | Required | The API key of the Permit environment this Nexus PDP serves. | +| `PDP_API_KEY` | Required | The Nexus PDP API key of the Permit environment this Nexus PDP serves, from **Copy Nexus PDP API Key** in the Permit dashboard. The ordinary environment API key does not work. | `PDP_API_KEY` is the only credential Nexus PDP needs. The `PDP_API_KEY` value: diff --git a/docs/concepts/pdp/nexus-pdp-deployment.mdx b/docs/concepts/pdp/nexus-pdp-deployment.mdx index 6bd2d8da..791e6ccc 100644 --- a/docs/concepts/pdp/nexus-pdp-deployment.mdx +++ b/docs/concepts/pdp/nexus-pdp-deployment.mdx @@ -10,7 +10,7 @@ Run Permit Nexus PDP (`permitio/nexus-pdp`), a self-hosted policy decision point ## Prerequisites - Nexus PDP enabled for your Permit account. Nexus PDP is in early access as of September 2026; to request access, [book a call with Permit](https://www.permit.io/demo). -- The API key of the Permit environment the Nexus PDP serves. See [Get your API key](/overview/get-api-key). +- The Nexus PDP API key of the Permit environment the Nexus PDP serves. Once Permit activates Nexus PDP for an environment, select that environment in the Permit dashboard and choose **Copy Nexus PDP API Key** in the user menu. The ordinary environment API key from [Get your API key](/overview/get-api-key) does not work with Nexus PDP: the container fails at startup. - A container platform that provides persistent volumes, such as Kubernetes. ## Deployment requirements @@ -19,8 +19,8 @@ Nexus PDP has operational requirements that the container PDP (the Edge PDP imag | Requirement | Setting | What happens if you skip it | | --- | --- | --- | -| Image | `permitio/nexus-pdp`, pinned to a specific tag | An unpinned image can pull a release with renamed configuration variables. See [Nexus PDP configuration reference](/concepts/pdp/nexus-pdp-configuration). | -| One container per environment | Set `PDP_API_KEY` to the API key of one Permit environment | Nexus PDP has no multi-environment mode. The API key binds the container to exactly one environment. | +| Image | `permitio/nexus-pdp`, pinned to an exact, immutable tag | `permitio/nexus-pdp` has no `latest` tag, so a pull without a tag fails. Moving tags such as `0-beta` switch to new builds, which can rename configuration variables. See [Nexus PDP configuration reference](/concepts/pdp/nexus-pdp-configuration). | +| One container per environment | Set `PDP_API_KEY` to the Nexus PDP API key of one Permit environment | Nexus PDP has no multi-environment mode. The Nexus PDP API key binds the container to exactly one environment. | | Persistent storage | Mount a persistent volume at `/var/lib/edge-pdp`, which holds the embedded database and the event store at default paths | On ephemeral storage, every restart runs a full cold start with a snapshot transfer of your whole data set. | | Memory | 4 GiB to start | At default storage-engine settings, a container with a few hundred MiB is killed for running out of memory (OOM) at startup. See [Nexus PDP resource footprint](/concepts/pdp/nexus-pdp-how-it-works#resource-footprint). | | Volume permissions | The volume is writable by user ID and group ID `10001` | Nexus PDP runs as the non-root user `10001` and cannot write its database or event store. | @@ -32,12 +32,12 @@ Nexus PDP has operational requirements that the container PDP (the Edge PDP imag ## Run Nexus PDP with Docker -Replace `` with a specific `permitio/nexus-pdp` release tag, and set `PERMIT_API_KEY` in your shell to the API key of the environment this container serves. The command maps the authorization API to host port `7766`, keeps the health port on `7001`, and stores the embedded database in the named volume `nexus-data`: +Replace `` with an exact `permitio/nexus-pdp` tag, not a moving tag such as `0-beta` (see [Image name and tags](/concepts/pdp/nexus-pdp#image-name-and-tags)), and set `NEXUS_PDP_API_KEY` in your shell to the Nexus PDP API key of the environment this container serves. The command maps the authorization API to host port `7766`, keeps the health port on `7001`, and stores the embedded database in the named volume `nexus-data`: ```bash docker run -d --name nexus-pdp \ -p 7766:7000 -p 7001:7001 \ - -e PDP_API_KEY="$PERMIT_API_KEY" \ + -e PDP_API_KEY="$NEXUS_PDP_API_KEY" \ -v nexus-data:/var/lib/edge-pdp \ --memory 4g \ permitio/nexus-pdp: @@ -45,7 +45,7 @@ docker run -d --name nexus-pdp \ ## Kubernetes pod settings for Nexus PDP -This pod-spec excerpt sets the ports, probes, memory request, volume, and shutdown budget from the requirements table. `fsGroup: 10001` makes the mounted volume writable by the non-root user that Nexus PDP runs as. Create the `permit-env-api-key` secret with the environment API key, size the `nexus-pdp-data` claim for your data set, and add a startup probe with enough time for a cold start: +This pod-spec excerpt sets the ports, probes, memory request, volume, and shutdown budget from the requirements table. `fsGroup: 10001` makes the mounted volume writable by the non-root user that Nexus PDP runs as. Create the `nexus-pdp-api-key` secret with the environment's Nexus PDP API key, size the `nexus-pdp-data` claim for your data set, and add a startup probe with enough time for a cold start: ```yaml terminationGracePeriodSeconds: 40 @@ -64,7 +64,7 @@ containers: - name: PDP_API_KEY valueFrom: secretKeyRef: - name: permit-env-api-key + name: nexus-pdp-api-key key: PDP_API_KEY livenessProbe: httpGet: { path: /health, port: 7001 } diff --git a/docs/concepts/pdp/nexus-pdp.mdx b/docs/concepts/pdp/nexus-pdp.mdx index ea855bfc..013c7e59 100644 --- a/docs/concepts/pdp/nexus-pdp.mdx +++ b/docs/concepts/pdp/nexus-pdp.mdx @@ -19,6 +19,12 @@ Nexus PDP is an additional deployment option. It does not replace the container As of September 2026, Nexus PDP is in early access and Permit enables it per account. To request access, [book a call with Permit](https://www.permit.io/demo). ::: +## Image name and tags \{#image-name-and-tags} + +Nexus PDP releases up to 0.6.1 were published as `permitio/pdp-v3`. That repository receives no new tags; later builds are published only as `permitio/nexus-pdp`. To upgrade from `permitio/pdp-v3`, switch to `permitio/nexus-pdp` and pick a tag from it. Don't reuse a `pdp-v3` tag name: some tag names exist in both repositories and point to different images. + +`permitio/nexus-pdp` has no `latest` tag. Pin an exact tag, such as a numbered beta like `0.7.0-beta.12`, rather than a moving tag such as `0-beta`, which switches to each new build. + ## Terms used on this page | Term | Meaning | diff --git a/static/images/pdp/nexus-pdp-architecture.svg b/static/images/pdp/nexus-pdp-architecture.svg index 6d883b42..dee6411e 100644 --- a/static/images/pdp/nexus-pdp-architecture.svg +++ b/static/images/pdp/nexus-pdp-architecture.svg @@ -35,8 +35,8 @@ - New Edge PDP Architecture - Architecture of the New Edge PDP: the authorization API, OPA, health server, query and bundle loopbacks, embedded database, change ingest and NATS leaf inside one container, with Permit.io and your policy store outside it. + Nexus PDP Architecture + Architecture of the Nexus PDP: the authorization API, OPA, health server, query and bundle loopbacks, embedded database, change ingest and NATS leaf inside one container, with Permit.io and your policy store outside it. @@ -62,7 +62,7 @@ - + @@ -103,8 +103,8 @@ liveness & readiness probes - - Authorization API · :7000 — opens once ready · Your VPC / network › New Edge PDP — one container per Permit environment · bearer: PDP_API_KEY + + Authorization API · :7000 — opens once ready · Your VPC / network › Nexus PDP — one container per Permit environment · bearer: PDP_API_KEY - - OPA policy engine · supervised child · Your VPC / network › New Edge PDP — one container per Permit environment + + OPA policy engine · supervised child · Your VPC / network › Nexus PDP — one container per Permit environment - - Health & readiness · :7001 — 9 gating components · Your VPC / network › New Edge PDP — one container per Permit environment + + Health & readiness · :7001 — 9 gating components · Your VPC / network › Nexus PDP — one container per Permit environment - - Query loopback · 127.0.0.1:7002 — graph data · Your VPC / network › New Edge PDP — one container per Permit environment + + Query loopback · 127.0.0.1:7002 — graph data · Your VPC / network › Nexus PDP — one container per Permit environment - - Bundle loopback · 127.0.0.1:7003 — rego bundle · Your VPC / network › New Edge PDP — one container per Permit environment + + Bundle loopback · 127.0.0.1:7003 — rego bundle · Your VPC / network › Nexus PDP — one container per Permit environment - - Embedded database · SurrealDB + RocksDB, on disk · Your VPC / network › New Edge PDP — one container per Permit environment · persistent volume + + Embedded database · SurrealDB + RocksDB, on disk · Your VPC / network › Nexus PDP — one container per Permit environment · persistent volume - - WAL ingest & repair · applies changes; self-heals · Your VPC / network › New Edge PDP — one container per Permit environment + + WAL ingest & repair · applies changes; self-heals · Your VPC / network › Nexus PDP — one container per Permit environment - - NATS leaf · supervised child · Your VPC / network › New Edge PDP — one container per Permit environment · durable JetStream + + NATS leaf · supervised child · Your VPC / network › Nexus PDP — one container per Permit environment · durable JetStream - + - New Edge PDP — one container per Permit environment + Nexus PDP — one container per Permit environment From 28498fa1695ad6412602007c446cb0f9db41144b Mon Sep 17 00:00:00 2001 From: eli Date: Wed, 30 Sep 2026 09:51:47 -0500 Subject: [PATCH 3/4] PER-16042: address Zeev's second review of the Nexus PDP docs - Callers: services that query Nexus PDP send the Nexus PDP API key as their SDK token; the environment API key gets 401. Said in the prerequisites, the verify step, the request-authentication section, the feature-parity page and the AuthZen section. Permit API calls use a separate SDK client with the environment API key. - Tags are not immutable (Docker Hub immutability is off, and numbered beta names can be republished), so the docs pin by digest and show how to read it. - The dashboard label is the one production shows today, Copy PDP v3 API Key, until the frontend rename is deployed. - The pod-spec intro names the secret's PDP_API_KEY key and gives the kubectl command; the configuration caution points at Image name and tags. Co-Authored-By: Claude Opus 5.5 --- docs/concepts/pdp/nexus-pdp-configuration.mdx | 4 ++-- docs/concepts/pdp/nexus-pdp-deployment.mdx | 23 ++++++++++++------- .../concepts/pdp/nexus-pdp-feature-parity.mdx | 2 +- docs/concepts/pdp/nexus-pdp.mdx | 2 +- docs/concepts/pdp/overview.mdx | 2 +- 5 files changed, 20 insertions(+), 13 deletions(-) diff --git a/docs/concepts/pdp/nexus-pdp-configuration.mdx b/docs/concepts/pdp/nexus-pdp-configuration.mdx index 66fdbdf5..a2dba469 100644 --- a/docs/concepts/pdp/nexus-pdp-configuration.mdx +++ b/docs/concepts/pdp/nexus-pdp-configuration.mdx @@ -8,7 +8,7 @@ sidebar_position: 6 This reference lists the environment variables that configure Permit Nexus PDP (`permitio/nexus-pdp`), a self-hosted policy decision point (PDP). It is for operators who deploy and tune Nexus PDP. The only required variable is `PDP_API_KEY`. For deployment requirements such as volumes, probes, and memory, see [Deploy Nexus PDP](/concepts/pdp/nexus-pdp-deployment). :::caution Nexus PDP configuration can change between early-access releases -As of September 2026, Nexus PDP is in early access. Permit can rename, replace, or remove the variables and defaults on this page before general availability. Pin the Nexus PDP image to a specific tag, and check this page when you upgrade. If you depend on a specific variable, tell Permit support at [support@permit.io](mailto:support@permit.io). +As of September 2026, Nexus PDP is in early access. Permit can rename, replace, or remove the variables and defaults on this page before general availability. Pin the Nexus PDP image as described in [Image name and tags](/concepts/pdp/nexus-pdp#image-name-and-tags), not to a moving tag such as `0-beta`, and check this page when you upgrade. If you depend on a specific variable, tell Permit support at [support@permit.io](mailto:support@permit.io). ::: The container PDP (the Edge PDP image `permitio/pdp-v2`) uses a different set of variables. See the [container PDP configuration reference](/concepts/pdp/configuration). A variable with the same name can mean something different on each PDP type. @@ -17,7 +17,7 @@ The container PDP (the Edge PDP image `permitio/pdp-v2`) uses a different set of | Variable | Default | Description | | --- | --- | --- | -| `PDP_API_KEY` | Required | The Nexus PDP API key of the Permit environment this Nexus PDP serves, from **Copy Nexus PDP API Key** in the Permit dashboard. The ordinary environment API key does not work. | +| `PDP_API_KEY` | Required | The Nexus PDP API key of the Permit environment this Nexus PDP serves, from **Copy PDP v3 API Key** (the dashboard's current name for the Nexus PDP API key) in the Permit dashboard. The ordinary environment API key does not work. | `PDP_API_KEY` is the only credential Nexus PDP needs. The `PDP_API_KEY` value: diff --git a/docs/concepts/pdp/nexus-pdp-deployment.mdx b/docs/concepts/pdp/nexus-pdp-deployment.mdx index 791e6ccc..91c05085 100644 --- a/docs/concepts/pdp/nexus-pdp-deployment.mdx +++ b/docs/concepts/pdp/nexus-pdp-deployment.mdx @@ -10,7 +10,7 @@ Run Permit Nexus PDP (`permitio/nexus-pdp`), a self-hosted policy decision point ## Prerequisites - Nexus PDP enabled for your Permit account. Nexus PDP is in early access as of September 2026; to request access, [book a call with Permit](https://www.permit.io/demo). -- The Nexus PDP API key of the Permit environment the Nexus PDP serves. Once Permit activates Nexus PDP for an environment, select that environment in the Permit dashboard and choose **Copy Nexus PDP API Key** in the user menu. The ordinary environment API key from [Get your API key](/overview/get-api-key) does not work with Nexus PDP: the container fails at startup. +- The Nexus PDP API key of the Permit environment the Nexus PDP serves. Once Permit activates Nexus PDP for an environment, select that environment in the Permit dashboard and choose **Copy PDP v3 API Key** (the dashboard's current name for the Nexus PDP API key) in the user menu or the environment card's menu. The ordinary environment API key from [Get your API key](/overview/get-api-key) does not work with Nexus PDP: the container fails at startup. Services that query Nexus PDP send the same Nexus PDP API key as their SDK `token` (the `Authorization: Bearer` value); Nexus PDP rejects the environment API key with HTTP `401`. If a service also calls the Permit API (`permit.api`), give those calls a separate SDK client configured with the environment API key. - A container platform that provides persistent volumes, such as Kubernetes. ## Deployment requirements @@ -19,7 +19,7 @@ Nexus PDP has operational requirements that the container PDP (the Edge PDP imag | Requirement | Setting | What happens if you skip it | | --- | --- | --- | -| Image | `permitio/nexus-pdp`, pinned to an exact, immutable tag | `permitio/nexus-pdp` has no `latest` tag, so a pull without a tag fails. Moving tags such as `0-beta` switch to new builds, which can rename configuration variables. See [Nexus PDP configuration reference](/concepts/pdp/nexus-pdp-configuration). | +| Image | `permitio/nexus-pdp`, pinned by digest (`permitio/nexus-pdp@sha256:`) | `permitio/nexus-pdp` has no `latest` tag, so a pull without a tag fails. Tags can move: `0-beta` switches to each new build, and a numbered beta tag name can be published again for a later build. A new build can rename configuration variables. See [Nexus PDP configuration reference](/concepts/pdp/nexus-pdp-configuration). | | One container per environment | Set `PDP_API_KEY` to the Nexus PDP API key of one Permit environment | Nexus PDP has no multi-environment mode. The Nexus PDP API key binds the container to exactly one environment. | | Persistent storage | Mount a persistent volume at `/var/lib/edge-pdp`, which holds the embedded database and the event store at default paths | On ephemeral storage, every restart runs a full cold start with a snapshot transfer of your whole data set. | | Memory | 4 GiB to start | At default storage-engine settings, a container with a few hundred MiB is killed for running out of memory (OOM) at startup. See [Nexus PDP resource footprint](/concepts/pdp/nexus-pdp-how-it-works#resource-footprint). | @@ -32,7 +32,7 @@ Nexus PDP has operational requirements that the container PDP (the Edge PDP imag ## Run Nexus PDP with Docker -Replace `` with an exact `permitio/nexus-pdp` tag, not a moving tag such as `0-beta` (see [Image name and tags](/concepts/pdp/nexus-pdp#image-name-and-tags)), and set `NEXUS_PDP_API_KEY` in your shell to the Nexus PDP API key of the environment this container serves. The command maps the authorization API to host port `7766`, keeps the health port on `7001`, and stores the embedded database in the named volume `nexus-data`: +Replace `` with the digest of the `permitio/nexus-pdp` build you deploy (see [Image name and tags](/concepts/pdp/nexus-pdp#image-name-and-tags)), and set `NEXUS_PDP_API_KEY` in your shell to the Nexus PDP API key of the environment this container serves. The command maps the authorization API to host port `7766`, keeps the health port on `7001`, and stores the embedded database in the named volume `nexus-data`: ```bash docker run -d --name nexus-pdp \ @@ -40,12 +40,19 @@ docker run -d --name nexus-pdp \ -e PDP_API_KEY="$NEXUS_PDP_API_KEY" \ -v nexus-data:/var/lib/edge-pdp \ --memory 4g \ - permitio/nexus-pdp: + permitio/nexus-pdp@sha256: ``` ## Kubernetes pod settings for Nexus PDP -This pod-spec excerpt sets the ports, probes, memory request, volume, and shutdown budget from the requirements table. `fsGroup: 10001` makes the mounted volume writable by the non-root user that Nexus PDP runs as. Create the `nexus-pdp-api-key` secret with the environment's Nexus PDP API key, size the `nexus-pdp-data` claim for your data set, and add a startup probe with enough time for a cold start: +This pod-spec excerpt sets the ports, probes, memory request, volume, and shutdown budget from the requirements table. `fsGroup: 10001` makes the mounted volume writable by the non-root user that Nexus PDP runs as. Create the `nexus-pdp-api-key` secret with the environment's Nexus PDP API key under the key `PDP_API_KEY`, which the pod spec reads, reusing the shell variable from the Docker step: + +```bash +kubectl create secret generic nexus-pdp-api-key \ + --from-literal=PDP_API_KEY="$NEXUS_PDP_API_KEY" +``` + +Then size the `nexus-pdp-data` claim for your data set, and add a startup probe with enough time for a cold start: ```yaml terminationGracePeriodSeconds: 40 @@ -53,7 +60,7 @@ securityContext: fsGroup: 10001 containers: - name: nexus-pdp - image: permitio/nexus-pdp: + image: permitio/nexus-pdp@sha256: ports: - containerPort: 7000 # authorization API - containerPort: 7001 # health @@ -86,7 +93,7 @@ The macOS AirPlay Receiver uses port `7000`. Map the Nexus PDP authorization API ## Verify a Nexus PDP deployment 1. Send `GET /health/ready` to the health port, `7001`: `curl -i http://localhost:7001/health/ready`. Nexus PDP returns HTTP `200` when every component that gates readiness is up, and HTTP `503` while any of them is still starting. A cold start can take minutes on a large data set, so retry until the response is `200`. -2. Point an SDK at the authorization port and run a permission check. With the port mapping in [Run Nexus PDP with Docker](#run-nexus-pdp-with-docker), the PDP URL is `http://localhost:7766`. See [Check permissions](/how-to/enforce-permissions/check). A decision that matches your policy confirms that Nexus PDP has your policy and data. +2. Set the SDK's PDP URL to the authorization port and its `token` to the Nexus PDP API key, then run a permission check. With the port mapping in [Run Nexus PDP with Docker](#run-nexus-pdp-with-docker), the PDP URL is `http://localhost:7766`. See [Check permissions](/how-to/enforce-permissions/check), and use the Nexus PDP API key wherever that page uses the environment API key. A decision that matches your policy confirms that Nexus PDP has your policy and data. ## Health and readiness @@ -154,7 +161,7 @@ Nexus PDP compares the bearer token on each authorization request, in constant t ### One Nexus PDP container serves one environment \{#one-environment} -Nexus PDP fixes its environment at startup from `PDP_API_KEY`. A valid API key for a different environment does not authenticate against the container, and a caller cannot direct a request at data outside the container's environment. +Nexus PDP fixes its environment at startup from `PDP_API_KEY`, and accepts only that key. Any other key, including the environment API key of the same environment, does not authenticate against the container, and a caller cannot direct a request at data outside the container's environment. ### Child processes start with a cleared environment \{#child-process-environment} diff --git a/docs/concepts/pdp/nexus-pdp-feature-parity.mdx b/docs/concepts/pdp/nexus-pdp-feature-parity.mdx index c8bf0e91..d783fff0 100644 --- a/docs/concepts/pdp/nexus-pdp-feature-parity.mdx +++ b/docs/concepts/pdp/nexus-pdp-feature-parity.mdx @@ -13,7 +13,7 @@ This comparison describes Nexus PDP as of September 2026, during early access. T ## Nexus PDP compatibility with container PDP endpoints -Nexus PDP accepts the same paths, request bodies, and response bodies as the container PDP on the endpoints that Nexus PDP implements. SDK calls to those endpoints work without code changes when you point the SDK at a Nexus PDP. +Nexus PDP accepts the same paths, request bodies, and response bodies as the container PDP on the endpoints that Nexus PDP implements. SDK calls to those endpoints work without other code changes when you set the SDK's PDP URL to a Nexus PDP and its `token` to the Nexus PDP API key. Nexus PDP implements a subset of the container PDP's endpoints. Its capabilities match those of the managed [Cloud PDP](/concepts/pdp/cloud-pdp-capabilities), running in your own network. diff --git a/docs/concepts/pdp/nexus-pdp.mdx b/docs/concepts/pdp/nexus-pdp.mdx index 013c7e59..cd246918 100644 --- a/docs/concepts/pdp/nexus-pdp.mdx +++ b/docs/concepts/pdp/nexus-pdp.mdx @@ -23,7 +23,7 @@ As of September 2026, Nexus PDP is in early access and Permit enables it per acc Nexus PDP releases up to 0.6.1 were published as `permitio/pdp-v3`. That repository receives no new tags; later builds are published only as `permitio/nexus-pdp`. To upgrade from `permitio/pdp-v3`, switch to `permitio/nexus-pdp` and pick a tag from it. Don't reuse a `pdp-v3` tag name: some tag names exist in both repositories and point to different images. -`permitio/nexus-pdp` has no `latest` tag. Pin an exact tag, such as a numbered beta like `0.7.0-beta.12`, rather than a moving tag such as `0-beta`, which switches to each new build. +`permitio/nexus-pdp` has no `latest` tag, and its tags can move: `0-beta` switches to each new build, and a numbered beta tag name can be published again for a later build. Pin by digest. Pick a tag such as `0.7.0-beta.12`, read its digest with `docker buildx imagetools inspect permitio/nexus-pdp:0.7.0-beta.12`, and deploy `permitio/nexus-pdp@sha256:`. ## Terms used on this page diff --git a/docs/concepts/pdp/overview.mdx b/docs/concepts/pdp/overview.mdx index 127b7114..e719ef25 100644 --- a/docs/concepts/pdp/overview.mdx +++ b/docs/concepts/pdp/overview.mdx @@ -375,7 +375,7 @@ To turn on caching and set the TTL, see [Cache configuration](/concepts/pdp/conf The PDP implements the [OpenID AuthZen Authorization API 1.0](https://openid.github.io/authzen/), a standard API between policy enforcement points (PEPs) and PDPs. Any AuthZen client can send authorization requests to a Permit PDP. -Every AuthZen endpoint requires the header `Authorization: Bearer `. Each AuthZen example uses two placeholders: replace `YOUR_API_KEY` with your environment API key, and `http://localhost:7766` with your PDP URL. +Every AuthZen endpoint requires the header `Authorization: Bearer `. Each AuthZen example uses two placeholders: replace `YOUR_API_KEY` with your environment API key, and `http://localhost:7766` with your PDP URL. On Nexus PDP, the bearer token is the Nexus PDP API key. A request that omits a required field, or that carries invalid JSON such as a trailing comma before a closing brace, gets HTTP `400` with the AuthZen error code `invalid_request`. A request with a missing or wrong bearer token gets HTTP `401` with the code `unauthorized`. From 2913d96d35896ddf6ed5526258fca9516dd6631c Mon Sep 17 00:00:00 2001 From: eli Date: Wed, 30 Sep 2026 10:41:34 -0500 Subject: [PATCH 4/4] PER-16042: address Zeev's approving review of the Nexus PDP docs - The Permit API accepts the Nexus PDP API key with the same access as the environment API key (PER-15400), so one SDK client serves both; protect the key like the environment key (prerequisites, request authentication, configuration reference). - Digest step prints only the multi-platform index digest, explains the sha256: prefix, and 0-beta moves on beta or release builds only. - Date the dashboard label: As of September 2026 it is Copy PDP v3 API Key, in the user menu and environment card menu, and needs edit permission. Co-Authored-By: Claude Opus 5.5 --- docs/concepts/pdp/nexus-pdp-configuration.mdx | 5 +++-- docs/concepts/pdp/nexus-pdp-deployment.mdx | 6 +++--- docs/concepts/pdp/nexus-pdp.mdx | 2 +- 3 files changed, 7 insertions(+), 6 deletions(-) diff --git a/docs/concepts/pdp/nexus-pdp-configuration.mdx b/docs/concepts/pdp/nexus-pdp-configuration.mdx index a2dba469..1eb81925 100644 --- a/docs/concepts/pdp/nexus-pdp-configuration.mdx +++ b/docs/concepts/pdp/nexus-pdp-configuration.mdx @@ -17,14 +17,15 @@ The container PDP (the Edge PDP image `permitio/pdp-v2`) uses a different set of | Variable | Default | Description | | --- | --- | --- | -| `PDP_API_KEY` | Required | The Nexus PDP API key of the Permit environment this Nexus PDP serves, from **Copy PDP v3 API Key** (the dashboard's current name for the Nexus PDP API key) in the Permit dashboard. The ordinary environment API key does not work. | +| `PDP_API_KEY` | Required | The Nexus PDP API key of the Permit environment this Nexus PDP serves, from the Permit dashboard. As of September 2026, the dashboard labels this action **Copy PDP v3 API Key**. The ordinary environment API key does not work. | `PDP_API_KEY` is the only credential Nexus PDP needs. The `PDP_API_KEY` value: - binds the container to exactly one Permit environment, - authenticates the container to Permit's control plane, - carries the address of the control plane, so Nexus PDP connects without a separate URL setting, -- is the bearer token that the Nexus PDP authorization API accepts from your services. +- is the bearer token that the Nexus PDP authorization API accepts from your services, +- is accepted by the Permit API with the same access as the environment API key, so protect it the same way. :::tip No control-plane URL to set on Nexus PDP Leave `PDP_CONTROL_PLANE` unset unless Permit support asks you to set it. On the container PDP, `PDP_CONTROL_PLANE` is the Permit API URL. On Nexus PDP, `PDP_CONTROL_PLANE` overrides the control-plane address that `PDP_API_KEY` carries. diff --git a/docs/concepts/pdp/nexus-pdp-deployment.mdx b/docs/concepts/pdp/nexus-pdp-deployment.mdx index 91c05085..809a52a4 100644 --- a/docs/concepts/pdp/nexus-pdp-deployment.mdx +++ b/docs/concepts/pdp/nexus-pdp-deployment.mdx @@ -10,7 +10,7 @@ Run Permit Nexus PDP (`permitio/nexus-pdp`), a self-hosted policy decision point ## Prerequisites - Nexus PDP enabled for your Permit account. Nexus PDP is in early access as of September 2026; to request access, [book a call with Permit](https://www.permit.io/demo). -- The Nexus PDP API key of the Permit environment the Nexus PDP serves. Once Permit activates Nexus PDP for an environment, select that environment in the Permit dashboard and choose **Copy PDP v3 API Key** (the dashboard's current name for the Nexus PDP API key) in the user menu or the environment card's menu. The ordinary environment API key from [Get your API key](/overview/get-api-key) does not work with Nexus PDP: the container fails at startup. Services that query Nexus PDP send the same Nexus PDP API key as their SDK `token` (the `Authorization: Bearer` value); Nexus PDP rejects the environment API key with HTTP `401`. If a service also calls the Permit API (`permit.api`), give those calls a separate SDK client configured with the environment API key. +- The Nexus PDP API key of the Permit environment the Nexus PDP serves. Once Permit activates Nexus PDP for an environment, select that environment in the Permit dashboard and copy the Nexus PDP API key. As of September 2026, the action is named **Copy PDP v3 API Key**. It is in the user menu and the environment card's menu, and it needs edit permission on the environment. The ordinary environment API key from [Get your API key](/overview/get-api-key) does not work with Nexus PDP: the container fails at startup. Services that query Nexus PDP send the same Nexus PDP API key as their SDK `token` (the `Authorization: Bearer` value); Nexus PDP rejects the environment API key with HTTP `401`. The Permit API (`permit.api`) also accepts the Nexus PDP API key, with the same access as the environment API key, so one SDK client configured with the Nexus PDP API key runs both permission checks and Permit API calls. Protect the Nexus PDP API key as you protect the environment API key. - A container platform that provides persistent volumes, such as Kubernetes. ## Deployment requirements @@ -19,7 +19,7 @@ Nexus PDP has operational requirements that the container PDP (the Edge PDP imag | Requirement | Setting | What happens if you skip it | | --- | --- | --- | -| Image | `permitio/nexus-pdp`, pinned by digest (`permitio/nexus-pdp@sha256:`) | `permitio/nexus-pdp` has no `latest` tag, so a pull without a tag fails. Tags can move: `0-beta` switches to each new build, and a numbered beta tag name can be published again for a later build. A new build can rename configuration variables. See [Nexus PDP configuration reference](/concepts/pdp/nexus-pdp-configuration). | +| Image | `permitio/nexus-pdp`, pinned by digest (`permitio/nexus-pdp@sha256:`) | `permitio/nexus-pdp` has no `latest` tag, so a pull without a tag fails. Tags can move: `0-beta` moves to each new beta or release build, and a numbered beta tag name can be published again for a later build. A new build can rename configuration variables. See [Nexus PDP configuration reference](/concepts/pdp/nexus-pdp-configuration). | | One container per environment | Set `PDP_API_KEY` to the Nexus PDP API key of one Permit environment | Nexus PDP has no multi-environment mode. The Nexus PDP API key binds the container to exactly one environment. | | Persistent storage | Mount a persistent volume at `/var/lib/edge-pdp`, which holds the embedded database and the event store at default paths | On ephemeral storage, every restart runs a full cold start with a snapshot transfer of your whole data set. | | Memory | 4 GiB to start | At default storage-engine settings, a container with a few hundred MiB is killed for running out of memory (OOM) at startup. See [Nexus PDP resource footprint](/concepts/pdp/nexus-pdp-how-it-works#resource-footprint). | @@ -150,7 +150,7 @@ Four properties of the container decide how you place, scope, and isolate a Nexu | Property | What it means for your deployment | |---|---| -| [Request authentication](#request-authentication) | Every caller needs the container's own `PDP_API_KEY`. Treat the key as a shared secret between the container and the services that query it. | +| [Request authentication](#request-authentication) | Every caller needs the container's own `PDP_API_KEY`. The key also has environment-level access to the Permit API, so give it the same protection as the environment API key. | | [One environment per container](#one-environment) | Run one container per Permit environment, and route each service to the container for its environment. | | [Child process isolation](#child-process-environment) | Variables you set on the container do not all reach OPA and the NATS leaf node. Set Nexus PDP variables, not OPA or NATS variables. | | [Blast radius](#blast-radius) | A compromised container exposes one environment. Apply the network policy and secret scope of that environment to it. | diff --git a/docs/concepts/pdp/nexus-pdp.mdx b/docs/concepts/pdp/nexus-pdp.mdx index cd246918..a0eaa0c4 100644 --- a/docs/concepts/pdp/nexus-pdp.mdx +++ b/docs/concepts/pdp/nexus-pdp.mdx @@ -23,7 +23,7 @@ As of September 2026, Nexus PDP is in early access and Permit enables it per acc Nexus PDP releases up to 0.6.1 were published as `permitio/pdp-v3`. That repository receives no new tags; later builds are published only as `permitio/nexus-pdp`. To upgrade from `permitio/pdp-v3`, switch to `permitio/nexus-pdp` and pick a tag from it. Don't reuse a `pdp-v3` tag name: some tag names exist in both repositories and point to different images. -`permitio/nexus-pdp` has no `latest` tag, and its tags can move: `0-beta` switches to each new build, and a numbered beta tag name can be published again for a later build. Pin by digest. Pick a tag such as `0.7.0-beta.12`, read its digest with `docker buildx imagetools inspect permitio/nexus-pdp:0.7.0-beta.12`, and deploy `permitio/nexus-pdp@sha256:`. +`permitio/nexus-pdp` has no `latest` tag, and its tags can move: `0-beta` moves to each new beta or release build, and a numbered beta tag name can be published again for a later build. Pin by digest. Pick a tag such as `0.7.0-beta.12` and read its digest with `docker buildx imagetools inspect --format '{{.Manifest.Digest}}' permitio/nexus-pdp:0.7.0-beta.12`. The command prints `sha256:` followed by the digest of the multi-platform image, which runs on both `amd64` and `arm64`. Deploy `permitio/nexus-pdp@sha256:`, where `` is the part after `sha256:`. ## Terms used on this page