About Runtime Service Configuration
The PlainID PDP (Runtime service) has a large configuration file that enables fine-tuning and control over various service parameters. While service parameter default values typically suffice, certain scenarios may require adjustments to optimize the PDP's behavior for your organization's specific needs.
Although you can directly edit the JSON configuration file in a Standalone PAA deployment or inject a full configuration map in a Kubernetes (K8s) PAA deployment, maintaining updated keys is simpler using Environment Variables. The Runtime service supports a naming convention for ENV_VARs that allows you to adjust any configuration key as needed in the Runtime extraEnv
section in the values.yaml. Ensure that you add the values you want to adjust in the values-custom.yaml.
Environment Variables following the naming convention outlined below automatically load and override the default values of configuration keys.
Environment Variables Convention
Environment Variable Prefix
All Runtime configuration keys begin with the predefined prefix RTCONF_
Hierarchy Naming Syntax
After the prefix, the Environment Variable name reflects the hierarchical structure of the configuration file, using a double underscore (__
) as a separator between hierarchy levels.
This same double underscore (__
) is also used to denote array indices for configuration keys that are defined as arrays.
Note: A single underscore(_
) is used as a word separator within the ENV_VAR name.
Examples
The following table demonstrates the naming convention and hierarchical structure for ENV_VARs.
Config Key | The config key full JSON Path | ENV_VAR |
---|---|---|
refreshAssetTemplates (root) | $.refreshAssetTemplates | RTCONF_REFRESH_ASSET_TEMPLATES |
isSysLogEnable (audit) | $.audit.isSysLogEnable | RTCONF_AUDIT__IS_SYSLOG_ENABLE |
isHttps (ssl) | $.ssl.isHttps | RTCONF_SSL__IS_HTTPS |
type (asset provider) | $.assetProvider.connection.type | RTCONF_ASSET_PROVIDERS__0__CONNECTION__TYPE |
serviceMgmtPort | $.serviceMgmtPort | RTCONF_SERVICE_MGMT_PORT |
Note: Ensure that the serviceMgmtPort is set to 80 (default)
When enabling SSL (isHttps=true
), it's important to separate the management and application ports due to differences in how TLS validation behaves across endpoints. By default, both httpPort
and serviceMgmtPort
use port 8010, which works in both Kubernetes and Standalone modes.
To avoid conflicts or unexpected behavior—especially in environments with strict TLS validation—configure serviceMgmtPort
to be distinct from httpPort
. In Kubernetes, you can also override the health check ports independently to ensure proper probe functionality.
Logging
Loading Environment Variables and overriding configuration keys are logged in the Runtime service logs to facilitate troubleshooting.
Any configuration key replaced by a value defined with an Environment Variable according to this hierarchical structure is logged at the Info
level with message in this structure: config.json key <key-name> was overridden by <env-var-name> environment variable
.
Additional logging may also be present in cases of error handling and validation of the Environment Variables naming syntax.
List of Runtime Configuration Keys
The table below highlights common Runtime service configuration keys that are relevant for fine-tuning. For additional guidance on configuration, consult the PlainID Professional Services team.
Config Key | JSON Path | Default | ENV_VAR |
---|---|---|---|
Service Port | $.httpPort | 8010 | RTCONF_HTTP_PORT |
Inject request ID into PIP SQL | $.useIdentityPipSqlTraceability | true | RTCONF_USE_IDENTITY_PIP_SQL_TRACEABILITY |
Max connection pool size for PIP Assets connectivity | $.assetProviders[0].connection.jdbcMaxPoolSize | 20 | RTCONF_ASSET_PROVIDERS__0__CONNECTION__JDBC_MAX_POOL_SIZE |
Min connection pool size for PIP Assets connectivity | $.assetProviders[0].connection.jdbcMinPoolSize | 5 | RTCONF_ASSET_PROVIDERS__0__CONNECTION__JDBC_MIN_POOL_SIZE |
PIP Assets query timeout | $.assetProviders[0].connection.queryTimeoutInSeconds | 25 | RTCONF_ASSET_PROVIDESR__0__CONNECTION__QUERY_TIMOUT_IN_SECONDS |
Number of Asset provider instances | $.assetProviders[0].count | 20 | RTCONF_ASSET_PROVIDERS__0__COUNT |
Number of parallel thread workers for Asset providers | $.assetProviders[0].workerPool | 20 | RTCONF_ASSET_PROVIDERS__0__WORKER_POOL Note: The above Asset provider examples can also apply to identities. Replace ..ASSET_PROVIDERS.. with ..ENTITY_PROVIDERS.. . |
Enable auditing with a database | $.audit.isDataBaseEnable | false | RTCONF_AUDIT__IS_DATABASE_ENABLE |
Database driver for audit database | $.audit.connection.driverName | RTCONF_AUDIT__CONNECTION_DRIVER_NAME |
|
Audit database host URL | $.audit.connection.url | RTCONF_AUDIT__CONNECTION_URL |
|
Audit database user | $.audit.connection.user | RTCONF_AUDIT__CONNECTION_USER |
|
Audit database user password | $.audit.connection.password | RTCONF_AUDIT__CONNECTION_PASSWORD Note: If using a Secrets Manager integration you can utilize a password from a secret store. Specifically for AWS RDS DB, you can utilize RDS signed connection tokens by adding this Environment Variable like this: |- {{store=AWS_RDS_IAM_AUTH_STORE,key=test_user@shared-partner-mgmt-dev.cluster-g6wgs3hs1zff.eu-east-2.rds.amazonaws.com:5432/eu-east-2}} For more information, refer to our Secret Management Configuration article. |
|
Maximum number of Identities retrieved per Source in User List | $.identityAgentLimit | 1000 | RTCONF_IDENTITY_AGENT_LIMIT |
Metrics data refresh interval | $.runtimeRefreshSnapshot | 60000ms | RTCONF_RUNTIME_REFRESH_SNAPSHOT |
Enabling SSL for PDP
To enforce SSL for the PDP Runtime service, an SSL certificate is required as a prerequisite, along with updated service configurations. The steps below outline the process when working with the default Kubernetes deployment pattern using PlainID Helm files.
Note: If your deployment pattern is different, consult your administrator and adjust the steps accordingly. For additional assistance, contact PlainID Professional Services.
SSL Certificate Setup
- Prepare your private key and server certificate, and store them as a Kubernetes secret. This can be done as part of the Helm chart using
extraManifests
(see example below). - Configure Environment Variables for accessing your Java Keystore:
KEY_STORE_PATH
andPASSWORD
.
runtime:
extraEnv:
RTCONF_SSL__KEYSTORE_PATH: "/usr/lib/jvm/default-jvm/lib/security/cacerts"
extraEnvSecrets:
RTCONF_SSL__KEYSTORE_PASSWORD: "changeit"
- Mount the certificates from the secret created above:
runtime:
extraVolumes:
- name: runtime-ssl-certificate
secret:
secretName: runtime-ssl-certificate
extraVolumeMounts:
- mountPath: "/app/ssl"
name: runtime-ssl-certificate
readOnly: true
- Modify the Runtime service pod command to import the certificate into the Java keystore before starting the application:
runtime:
command:
- /bin/sh
- -ec
- |
openssl pkcs12 -export -out /tmp/placceholder.p12 -inkey /app/ssl/server.key -in /app/ssl/server.crt -password pass:${RTCONF_SSL__KEYSTORE_PASSWORD} keytool -importkeystore -deststorepass ${RTCONF_SSL__KEYSTORE_PASSWORD} -destkeystore ${RTCONF_SSL__KEYSTORE_PATH} -srckeystore /tmp/placceholder.p12 -srcstoretype PKCS12 -srcstorepass ${RTCONF_SSL__KEYSTORE_PASSWORD} java ${JVM_OPTS} --add-exports java.base/sun.security.util=ALL-UNNAMED -Dconf.file=${RUNTIME_CONFIG_PATH} -Dconf.format=json -Dlog4j.configurationFile=${RUNTIME_LOG4J_PATH} -Djava.net.preferIPv4Stack=true -jar theruntime.jar
In the example above, we assume that server.crt
and server.key
are injected from the secret.
Configure SSL for the PDP
Enable SSL in the Runtime service configuration:
runtime:
ssl:
enabled: true
Health Check and SSL
Even when SSL is enabled, health checks performed by Kubernetes will not attempt to validate the SSL certificate, even when using the HTTPS scheme. Refer to the Kubernetes documentation for more information.
Note: If you are accessing the Runtime health check endpoint externally, your client must either include SSL validation keys or be configured to ignore validation gracefully.
Port Definition and Separation
The SSL configuration applies to all service ports. However, if needed, you can separate the Application service port from the Health status port using the following optional configuration:
- Configure a custom port for the health check API endpoint (optional):
runtime:
extraEnv:
RUNTIME_STATUS_PORT: "3000"
You may also override the default application port with the following optional configuration:
runtime:
service:
port: 443
Note: If you configure a custom port and override the default setup, you must restart the service pods.
Full Configuration Example
Full configuration example that includes all the required changes:
runtime:
service:
port: 443
ssl:
enabled: true
extraEnv:
RTCONF_SSL__KEYSTORE_PATH: "/usr/lib/jvm/default-jvm/lib/security/cacerts"
extraEnvSecrets:
RTCONF_SSL__KEYSTORE_PASSWORD: "changeit"
command: - /bin/sh - -ec - | openssl pkcs12 -export -out /tmp/placceholder.p12 -inkey /app/ssl/server.key -in /app/ssl/server.crt -password pass:${RTCONF_SSL__KEYSTORE_PASSWORD} keytool -importkeystore -deststorepass ${RTCONF_SSL__KEYSTORE_PASSWORD} -destkeystore ${RTCONF_SSL__KEYSTORE_PATH} -srckeystore /tmp/placceholder.p12 -srcstoretype PKCS12 -srcstorepass ${RTCONF_SSL__KEYSTORE_PASSWORD} java ${JVM_OPTS} --add-exports java.base/sun.security.util=ALL-UNNAMED -Dconf.file=${RUNTIME_CONFIG_PATH} -Dconf.format=json -Dlog4j.configurationFile=${RUNTIME_LOG4J_PATH} -Djava.net.preferIPv4Stack=true -jar theruntime.jar
extraVolumes:
- name: runtime-ssl-certificate
secret:
secretName: runtime-ssl-certificate
extraVolumeMounts:
- mountPath: "/app/ssl"
name: runtime-ssl-certificate
readOnly: true
extraManifests:
- apiVersion: v1
kind: Secret
metadata:
name: runtime-ssl-certificate
namespace: manual-test
type: Opaque
stringData:
server.key: |
-----BEGIN PRIVATE KEY-----
...
-----END PRIVATE KEY-----
server.crt: |
-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----
Optimizing PDP Redis Utilization
The PDP (Runtime Service) uses Redis as a cache storage for managing the Identity Cache, Scope Authorization Requests, and Response Cache. Redis also stores deployed metadata such as Policies, Templates, Scopes, and other data required for Authorization calculations. To reduce connection load, network traffic, and data fetch overhead, the Runtime service retrieves metadata from Redis and maintains it in its own internal service cache.
You can configure specific Environment Variables to fine-tune the Runtime Service Cache behavior by controlling the dependency on Redis during Authorization Requests:
Configuration Key | Default Value | Description |
---|---|---|
SHOULD_READ_FROM_CACHE_BEFORE_DB |
false |
Determines if the PDP consumes the prefetched Policy and other metadata from the service cache or from the Redis storage. Setting the value to false keeps the current behavior and setting it to true uses additional prefetched data, reducing the Redis communication. |
SCOPE_SETTINGS_COOLDOWN_SECONDS |
60 |
Determines the refresh interval in seconds, in which the PDP refetches updated data from Redis, in case SHOULD_READ_FROM_CACHE_BEFORE_DB is set to true. |
When enabled there will be an delay in metadata freshness until updates made on PAP become effective in PAAs. The delay can be controlled by the SCOPE_SETTINGS_COOLDOWN_SECONDS
parameter.
PDP Logging
The PlainID PDP includes built-in logging to support observability, diagnostics, and performance monitoring. Logging captures key events such as Environment Variable overrides, configuration loading, request durations, and system behavior during policy evaluations. These logs help administrators validate configuration changes, trace issues, and optimize Runtime performance.
The logs also include Runtime entries for each Authorization requests like:
- Initiation of the request
- Request ID and context details
- Step-by-step calculation flow (logged at lower log levels)
- Completion of the request, including the total duration
The request duration appears at the end of a PDP request and shows the service and the time it took to complete. This information is useful for analyzing performance. This capability is currently available for the PIP Operator.
Example:
"duration": 2,
"type": "pip-operator"
Request duration logging is enabled by default. You can also choose to opt out of duration logging by adding and setting the key RTCONF_DETAILED_DURATIONS_LOGGING
to false
in the values-custom.yaml.