---
title: "PIP Operator Service"
slug: "pip-operator-service"
updated: 2025-12-08T14:39:47Z
published: 2025-12-08T14:39:47Z
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.plainid.io/llms.txt
> Use this file to discover all available pages before exploring further.

# PIP Operator Service

The **PIP Operator Service** manages, deploys, and maps data sources within the PlainID environment. It supports integration with multiple Data Sources, JDBC drivers, and logging/monitoring APIs while maintaining runtime stability across Kubernetes or standalone deployments.

This guide provides a complete reference for installation, environment configuration, health checks, JDBC integration, Docker customization, and logging.

---

## Configuration

Before starting, configure the required Environment Variables. The following table lists the minimum required Redis-related settings for running the PIP Operator Service:

| Variable | Description | Default / Notes |
| --- | --- | --- |
| `REDIS_HOST` | Redis host | Required |
| `REDIS_PORT` | Redis port | Required |
| `REDIS_PASS` | Redis password | Default: none |

For staging or production environments, use a managed Redis instance.

**Notice:** Redis must enable `notify-keyspace-events`. Either allow the application to modify Redis configuration or configure it manually.

For Users with Custom Deployments

When upgrading to `pip-operator` image `5.2448.4` or higher, configure the `PIP` service by adding `JAVA_OPTS` with the new Java system property: `-Dorg.apache.cxf.transport.http.forceVersion=1.1`

---

## Environment Variables

The following environment variables are required to manage and configure the PIP Operator Service. They are grouped by functionality for clarity.

### Management

These variables control server ports, authentication, transaction management, and Redis connections:

| Variable | Description | Default / Notes |
| --- | --- | --- |
| `SERVER_PORT` | Server port | Required |
| `MANAGEMENT_PORT` | Port for info & health checks | Required |
| `APP_AUTH_ENABLED` | Enable/disable JWT authentication | Default: false |
| `APP_AUTH_JWT` | JWT token | Required if auth enabled |
| `APP_AUTH_SECRET` | JWT secret key | Required if auth enabled |
| `APP_AUTH_ISS` | JWT issuer | Optional |
| `TRANSACTION_MANAGER_ENABLED` | Enable/disable transaction manager | Required |
| `TRANSACTION_MANAGER_COORDINATOR_ENVIRONMENT_BEAN_DEFAULT_TIMEOUT` | Transaction timeout (seconds) | Default: 300 |
| `REDIS_HOST` | Redis host | Required |
| `REDIS_PORT` | Redis port | Required |
| `REDIS_PASS` | Redis password | Default: none |
| `REDIS_SSL_ENABLED` | Enable SSL | Default: false |
| `REDIS_TIMEOUT_MIL` | Connection timeout (ms) | Default: 60000 |
| `REDIS_POOL_MAX_TOTAL` | Max number of connections | Required |
| `REDIS_POOL_MAX_IDLE` | Max idle connections | Required |
| `REDIS_POOL_MIN_IDLE` | Minimum warm connections | Required |
| `REDIS_POOL_MIN_EVIC_MI` | Min idle time before eviction | Required |
| `REDIS_POOL_TIME_BETWEEN_EVIC_MIL` | Interval between idle checks | Required |
| `REDIS_SETTINGS_KEY_NAME` | VDB deployed settings key | Default: VDBSettings |
| `MV_STATUS_LOGGING_FREQUENCY` | Materialized view logging frequency | Default: 60 min |
| `MV_STATUS_LOGGING_EXTERNAL_STATUS_TABLES` | Names of external materialized view status tables | Optional |
| `APP_MAX_THREADS` | Max threads for query engine | Default: 64 |
| `APP_MAX_ACTIVE_PLANS` | Number of active query plans | Default: 20 |
| `APP_USER_REQUEST_SOURCE_CONCURRENCY` | Concurrent source queries per request | Default: 0 |
| `QUERY_QUEUE_STATUS_LOGGING_FREQUENCY` | Frequency of logging query queue | Default: 1 min |
| `ENABLE_VDB_HEALTH_METRICS` | Enable new Prometheus metrics | Optional |

---

### VDB

These variables configure the Virtual Database (VDB) connection, protocol, and bind address:

| Variable | Description | Default / Notes |
| --- | --- | --- |
| `VDB_USERNAME` | JDBC connection username | Default: pip |
| `VDB_PASSWORD` | JDBC connection password | Default: pa33word |
| `TRANSPORT_PROTOCOL` | VDB transport protocol | Default: teiid |
| `TRANSPORT_BIND_ADDRESS` | Transport bind address | Default: 0.0.0.0 |

#### DDL Update Behavior

The `pip-operator` deploys the Virtual Database (VDB), which integrates data and builds dynamically from the **Data Source Tables** and **Virtual Views** structures. Users define these structures through the **PIP Management** capability in the Platform. For more information, see the Management section in the [PIP](/v1/docs/policy-information-point-pip-1) category.

The `pip-operator` determines the VDB structure (schema) based on the **Data Source DDLs’ foreign tables** defined in [Available Data Model Properties for JDBC](/docs/available-data-model-properties-for-jdbc) and [Creating Common View Queries](/docs/managing-views). The service collects and aggregates the DDLs, stores them in a **REDIS key**, validates, and then deploys the **virtual database** by running a `vdb restart` operation on the underlying PIP engine.

During the deployment procedure, especially when restarting the VDB, **the VDB does not process queries**. As a result, the `pip-operator` may return errors to clients.

Because the `pip-operator` becomes temporarily unavailable during these operations, **avoid changing DDLs, Data Source configurations, or Views in production environments** except during scheduled maintenance windows. These operations cause brief downtime and can interrupt active queries.

The unavailability period depends on how long the restart takes. In most cases, the process takes only a few seconds, but it can take longer if the VDB is large, the data sources are complex, or the configuration uses **PIP caching**, which loads data into materialized views.

---

### Logging

Use these variables to define log levels and formats for different components of the PIP Operator Service:

| Variable | Description | Default / Notes |
| --- | --- | --- |
| `LOGGING_FORMAT` | Format (JSON or text) | Default: JSON |
| `LOGGING_ROOT_LEVEL` | Root logging level | Default: error |
| `LOGGING_TOMCAT_LEVEL` | Tomcat logging level | Default: error |
| `LOGGING_WEB_LEVEL` | Web logging level | Default: error |
| `LOGGING_PLAINID_LEVEL` | PlainID components logging level | Default: debug |
| `LOGGING_TEIID_LEVEL` | Teiid logging level | Default: info |
| `LOGGING_TEIID_RUNTIME_LEVEL` | Teiid runtime logging level | Default: info |
| `LOGGING_TEIID_CONNECTOR_LEVEL` | Teiid connector logging level | Default: info |
| `LOGGING_TEIID_COMMAND_LOG_LEVEL` | Teiid command log level | Default: info |

---

### Proxy

These settings control the proxy server behavior:

| Variable | Description | Default / Notes |
| --- | --- | --- |
| `PROXY_SOCKET_TIMEOUT` | Socket timeout | Default: 2 hours |
| `PROXY_SOCKET_BUFFER_SIZE` | Input stream buffer size | Default: 8192 bytes |
| `PROXY_SERVER_PORT` | Tiied proxy server port | Default: 31350 |

---

### Agent

Variables used by the client-side PAA Agent:

| Variable | Description | Default / Notes |
| --- | --- | --- |
| `AGENT_URL` | Client-side Agent URL | Default: http://localhost:8761 |
| `PAA_PACKAGE_VERSION` | PAA version for deployment | Required for custom deployments |

---

### Health-check

#### URL

```
http://<host>:<port>/actuator/health
```

#### OK Response

```
{
  "status": "UP"
}
```

#### Command Line

```
java -jar pip-operator-1.0.jar
```

#### PIP Operator Service Health Check

The PIP Operator Service GET request retrieves the PAA's PIP Operator health status.

**K8:**

GET    `http://plainid-paa-pip-operator/actuator/health`

**Standalone:**

GET    `http://&lt;pip-operator_address&gt;:&lt;pip-operator_management_port&gt;/actuator/health`

Authorization

- None

Header

- None

**Standalone Parameters**

| Parameter | Value |
| --- | --- |
| <pip-operator_address> | Standalone - Server host name |
| <pip-operator_management_port> | 8089 (Default) |

**Service Response:**

```
{
  "status": "UP",
  "components": {
    "diskSpace": {
      "status": "UP",
      "details": {
        "total": 101203873792,
        "free": 92163268608,
        "threshold": 10485760,
        "exists": true
      }
    },
    "livenessState": {
      "status": "UP"
    },
    "ping": {
      "status": "UP"
    },
    "readinessState": {
      "status": "UP"
    },
    "vdbSettingsState": {
      "status": "UP"
    }
  },
  "groups": [
    "liveness",
    "readiness"
  ]
}
```

---

### Preloading JDBC Drivers

In some scenarios, you may need to integrate with external data sources that require JDBC drivers not included by default. This section explains how to load third-party drivers into the pip-operator by modifying the container's startup command.

#### Modifying pipOperator Start Command

**To pre-load JDBC drivers**:

```
pipOperator:
  command: [
    - /bin/sh
    - -ec
    - |
      curl -o /app/lib/sample.driver.one.jar https://www.provider-one.com/sample.driver.one.jar && \
      curl -o /app/lib/sample.driver.two.jar https://www.provider-two.com/sample.driver.two.jar && \
      java ${JVM_OPTS} -cp $JAR_NAME -Djava.net.preferIPv4Stack=true -Dloader.path=/app/lib/ -Dloader.main=com.plainid.pipoperator.Starter org.springframework.boot.loader.launch.PropertiesLauncher]
```

> The `java` command must be last, or the `pip-operator` will fail to start.

---

### Using a Custom Dockerfile

You can extend the default `plainid/pip-operator` image to include additional libraries or third-party drivers required for your deployment.

```
FROM plainid/pip-operator:5.0.16
ADD third-party-driver.jar /app/lib/
```

Build the new image:

```
docker build -t plainid/pip-operator:5.0.16-custom-drivers .
```

Run the container to verify:

```
docker run -it plainid/pip-operator:5.0.16-custom-drivers ls /app/lib
```

Expected output:

```
pip-auth-extensions-1.1.0.jar  third-party-driver.jar
```

Use this image in your deployment configuration (`values-custom.yaml`) to ensure drivers are available at runtime.

---

### PIP Operator Logging API

The PIP Operator Logger API lets you retrieve and update log levels for deployed PIP Operator services.

Important

Modify log levels only when troubleshooting. Do not leave lower log levels active in production environments.

### Logging Configuration

Temporary changes made with the API are reset on service restart. For persistent changes, configure log levels through Helm or Standalone settings:

- Helm: `.Values.pipOperator.logLevel`
- Standalone: PIP Operator Environment Variables
  - **Reach out to Support for more information**.

### Authentication

**These APIs require JWT authentication with Tenant Admin permissions.**

Security: Bearer Auth

For more details, see [Authentication for Management APIs](https://docs.plainid.io/apidocs/authentication-mgmt-apis).

Use your bearer token in the `Authorization` header: `Authorization: Bearer 123`

---

## PAA Logger Endpoints

**Retrieve loggers**

```
GET https://api.{region}.plainid.io/pip-mgmt/1.0/monitor/loggers/pip-operator/{PAA_ID}
GET https://api.{region}.plainid.io/pip-mgmt/1.0/monitor/loggers/pip-operator/{PAA_ID}/{LOGGER_NAME}
```

- Replace `{region}` with `us1`, `ca1`, or `eu1`
- `{PAA_ID}`: found in Policy Authorization Agent details
- `{LOGGER_NAME}`: optional, retrieves one specific logger

Append `?configured=false` to include **all loggers**, not just configured ones.

**Example GET response (PIP Operator):**

```
{
  "data": {
    "levels": ["OFF","TRACE","DEBUG","INFO","WARN","ERROR"],
    "loggers": {
      "org.teiid.RUNTIME": {
        "configuredLevel": "INFO",
        "effectiveLevel": "INFO"
      },
      "root": {
        "configuredLevel": "INFO",
        "effectiveLevel": "INFO"
      }
    }
  }
}
```

**Response Fields**

| Parameter | Type | Description |
| --- | --- | --- |
| configuredLevel | string | The level set explicitly via configuration or API. |
| effectiveLevel | string | The actual level applied (may be inherited from a parent logger). |

---

**Modify log levels**

```
POST https://api.{region}.plainid.io/pip-mgmt/1.0/monitor/loggers/pip-operator/{PAA_ID}/{LOGGER_NAME}
```

**Example Request**

```
{
  "configuredLevel": "TRACE"
}
```

**Example Response**

```
{
  "data": {
    "configuredLevel": "TRACE",
    "effectiveLevel": "TRACE"
  }
}
```