Skip to main content
Some workloads depend on custom Apache Pinot plugins — for example, a proprietary decoder for an internal data format — that can’t be contributed to open-source Pinot. StarTree Cloud lets you load your own plugin JARs into every Pinot component (broker, server, controller, and minion) at startup, without needing a custom StarTree Cloud image or build. Your plugin JARs are stored in your workspace’s deep store S3 bucket. At startup, each Pinot component downloads them and adds them to its runtime classpath — so a plugin registered this way behaves exactly like a built-in Pinot plugin, including for logging, metrics, and tracing.
This is a self-serve, GA feature — no support ticket required. It’s supported on the v2 operator (1.10.8+) and Vintner (2.0.8+).

​
Prerequisites

Enabling or changing custom plugins triggers a rolling restart of all Pinot components in the cluster. Plan the change accordingly.

​
Setting up a custom plugin

1

Upload your plugin JAR to S3

Place your plugin JAR(s) in your workspace’s deep store bucket, under a top-level custom-plugins directory:
For example:
<your-deep-store-bucket> is specific to your workspace — check your workspace’s Pinot deep store configuration if you don’t already know the bucket name.
2

Name your JAR with a semantic version

JAR filenames must follow <plugin-name>-<semver>.jar, for example:
If you place more than one version of the same plugin in S3, StarTree Cloud loads only the latest semantic version — older versions are left in place but ignored, so you can keep them around for rollback.

​
How it works

  • At startup, each Pinot component checks the custom-plugins S3 path and downloads any JARs it finds onto its local classpath.
  • If the path is empty or doesn’t exist, this is a no-op — Pinot starts up exactly as it would without the feature enabled.
  • Custom plugin JARs are given classloading priority over StarTree Cloud’s built-in Pinot libraries. If one of your classes shares a name with a built-in Pinot class, your version takes precedence — useful if you need to override built-in behavior, but worth knowing if you see unexpected behavior after adding a plugin.
  • All Pinot components load the same set of plugins. There is currently no way to target a plugin at only specific component types (for example, servers only).

​
Failure handling

A problem downloading or loading a custom plugin does not prevent a Pinot component from starting. The component comes up normally; functionality that specifically depends on the missing or broken plugin may be degraded (for example, a table configured to use a custom decoder may fail to ingest), but the rest of the deployment is unaffected.
If a plugin doesn’t seem to be loading, check the logs of the init container on the affected Pinot pod — this is the container responsible for downloading plugin JARs from S3, and it logs the outcome of that download.

​
Updating and rolling back plugins

  • Updating a plugin: Pinot does not pick up new or changed JARs at runtime. After uploading a new version to S3, restart the affected Pinot components to load it.
  • Rolling back: Remove or revert the JAR in S3, then restart the affected Pinot components.

​
Responsibility and support

  • You are responsible for building, testing, and certifying your own plugin JARs. StarTree does not validate, sign, or certify custom plugins through its own CI or certification process — test thoroughly in a non-production environment first.
  • StarTree Cloud only enforces the semantic-versioning file naming convention described above; it does not perform checksum verification or JAR signing.

​
Security

Only JARs placed at your workspace’s designated custom-plugins path in your deep store bucket are ever loaded. Plugins cannot be loaded from any other location.

​
Current limitations

  • No per-component targeting. Plugins load on every Pinot component type; you can’t restrict a plugin to, say, servers only.
  • No hot reload. Picking up a new or updated plugin requires restarting the affected Pinot components — there’s no dynamic reload mechanism.
  • No StarTree-side validation. StarTree does not check, sign, or certify plugin JARs before they’re loaded.