Agent

The PlainID Agent is a core service in the Policy Authorization Agent (PAA). It connects the PAA to the Platform, retrieving configurations and Policies from the cloud and applying them at runtime.

Configuration

The PlainID Agent is configured through Environment Variables. These variables control connectivity, authentication, runtime behavior, and logging.
The following Environment Variables must be set. These values can be found in the Tenant Settings screen of the Platform.

Client Variables

Management Variables

Agent Communications

These parameters configure the connection between the PlainID Agent and the Policy Administration Point (PAP).

Tunnel Endpoints (set tunnel.serverUrl):

Health and Logging

The PlainID Agent provides operational APIs that allow administrators to monitor service health and adjust runtime logging without restarting the Agent. These APIs are designed to support both Kubernetes and standalone deployments, making it easier to verify availability, track dependencies, and fine-tune logging for troubleshooting.

• Health Checks – Verify Agent status and dependent services.
• Logging API – Dynamically update log levels for troubleshooting.

Use these APIs to maintain service reliability, streamline debugging, and integrate the Agent into your monitoring workflows.

Health

The Agent includes a built-in health endpoint that reports on service status. This can be used for monitoring and integration with orchestration systems (e.g., Kubernetes, Docker health checks).

Typical health checks include:

• Connectivity to the Platform
• Redis availability
• Communication channel status

Health Check

Check the basic availability of the Agent.

Endpoint

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

Example Response

{
  "status": "UP"
}

Java Runtime

The Agent runs on Java and requires version 21 or later.

Command Line

java -jar plainid-agent.jar
```x

---

## Agent Health Checks

Monitor the Agent’s service status and its connected components.

### Endpoints

* **Kubernetes (K8s):**
  `GET http://plainid-paa-agent/actuator/health`

* **Standalone:**
  `GET http://<plainid-agent_address>:<plainid-agent_port>/actuator/health`

| Parameter                 | Default Value | Description             |
| ------------------------- | ------------- | ----------------------- |
| `<plainid-agent_address>` | —             | Standalone host address |
| `<plainid-agent_port>`    | `8081`        | Agent management port   |

### Example Response

```json
{
  "status": "UP",
  "components": {
    "connectedToRemoteWarp": { "status": "UP" },
    "diskSpace": {
      "status": "UP",
      "details": { "total": 133003395072, "free": 103323860992 }
    },
    "livenessState": { "status": "UP" },
    "piggiesStatus": { "status": "UP" },
    "ping": { "status": "UP" },
    "readinessState": { "status": "UP" },
    "redis": { "status": "UP", "details": { "version": "6.0.14" } }
  },
  "groups": ["liveness","readiness"]
}

Logging

The PlainID Agent supports configurable log levels and formatting. Logging can be tuned to control verbosity and assist with troubleshooting.

The following log levels are supported: error, warn, info, trace, debug.

Change logging levels dynamically without restarting the Agent.

The Agent Logger API allows dynamic log level updates without restarting the Agent.
Use it to review or adjust logger verbosity for troubleshooting.

Logging Configuration Persistence

Control whether log level changes reset on restart or persist through configuration.

• Temporary changes (API): Reset after Agent restart.

• Permanent changes:

  • Helm: .Values.agent.logLevel
  • Standalone: Agent Environment Variables

Authentication

All API requests require secure authentication using JWT tokens.

These APIs require JWT authentication with Tenant Admin permissions.

Authorization: Bearer <TOKEN>

PAA Logger Endpoints

Access or update Agent logger configurations through the management API.

Retrieve Loggers

Fetch the available loggers and their configured levels.

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

Example Response

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

Modify Log Levels

Change the logging level of a specific logger at runtime.

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

Example Request

{
  "configuredLevel": "DEBUG"
}

Example Response

{
  "data": {
    "configuredLevel": "DEBUG",
    "effectiveLevel": "DEBUG"
  }
}