pletorco/apicurio-registry repository overview

⁠Pletor Apicurio Registry for Kubernetes

pletorco/apicurio-registry extends the official Apicurio Registry⁠ application image while preserving the upstream runtime, launcher, UID, health endpoints, storage providers, REST API, and ApicurioRegistry3 custom resource behavior.

The primary reason to use this image instead of the upstream app image is the Pletor node metrics agent⁠. It is attached automatically and publishes process, cgroup, filesystem, and agent-health MBeans. The bundled JMX Exporter converts those MBeans into Prometheus pletor_* metrics on port 9404.

Each immutable release tag is a multi-architecture image supporting linux/amd64 and linux/arm64 nodes. The upstream Apicurio Registry Operator and UI image are not rebuilt or replaced.

⁠What this image adds

Added files:

/opt/pletor/agents/jmx_prometheus_javaagent-<version>.jar
/opt/pletor/agents/node-metrics-agent-<version>-all.jar
/opt/pletor/config/jmx-exporter.yml
/opt/pletor/config/node-metrics.yml
/opt/pletor/licenses/

Both agents are attached through JAVA_TOOL_OPTIONS. Operator-generated JAVA_OPTIONS, the upstream command, and the application working directory are preserved. Do not replace JAVA_TOOL_OPTIONS in the custom resource unless both Pletor agents are intentionally being disabled.

⁠Image tags

Tags identify the Apicurio Registry version and Pletor release:

<apicurio-version>-pletor.<release>

Example:

pletorco/apicurio-registry:3.2.6-pletor.1

Pull an exact tag:

docker pull pletorco/apicurio-registry:3.2.6-pletor.1

Mutable tags such as latest are not published. Production deployments should use an exact tag and preferably pin the multi-architecture manifest digest reported by the release pipeline.

⁠Use with the Apicurio Registry Operator

Select the Pletor image per Registry through spec.app.podTemplateSpec. The Operator recognizes the container name apicurio-registry-app and merges that declaration with the application container it generates.

Upstream permits this image override but does not recommend arbitrary images because compatibility becomes the deployer's responsibility. Pletor images are derived from the matching official application image, so keep the Apicurio version in the Pletor tag aligned with the installed Operator.

⁠ApicurioRegistry3 custom resource

The following KafkaSQL example uses a service-binding Secret generated by the Strimzi Kafka Access Operator. It also mounts the node metrics and JMX Exporter configuration used by the Pletor agents:

apiVersion: registry.apicur.io/v1
kind: ApicurioRegistry3
metadata:
  name: schema
spec:
  app:
    replicas: 2
    podTemplateSpec:
      spec:
        containers:
          - name: apicurio-registry-app
            image: pletorco/apicurio-registry:3.2.6-pletor.1
            ports:
              - name: pletor-jmx
                containerPort: 9404
                protocol: TCP
            volumeMounts:
              - name: pletor-metrics-config
                mountPath: /opt/pletor/config
                readOnly: true
        volumes:
          - name: pletor-metrics-config
            configMap:
              name: pletor-apicurio-registry-metrics
    storage:
      type: kafkasql
      kafkasql:
        kafkaAccessSecretName: schema-kafka-access
  ui:
    replicas: 2

The complete example also sets customer-approved KafkaSQL topic names. Registry authentication, authorization, ingress, resources, replicas, and storage must be configured for the target environment. Keep image selection in the custom resource so it remains visible, independently deployable, and reversible.

⁠Node metrics agent deployment

Selecting the Pletor image is sufficient to start node-metrics-agent with the safe configuration embedded in the image. The Operator example deliberately mounts metrics-configmap.yaml as well so the active configuration is visible in the deployment source and can be adjusted for customer-visible filesystems.

The metrics path is:

node-metrics-agent
  -> co.pletor.node / co.pletor.proc / co.pletor.cgroup / co.pletor.agent MBeans
  -> bundled JMX Exporter
  -> http://<app-pod>:9404/metrics

node-metrics.yml controls filesystem collection. Only paths mounted and visible inside the app container can be observed. The default / path is a portable baseline; add customer-approved mounted data or log paths when they exist. jmx-exporter.yml must retain the co.pletor.* include names and rules or the agent MBeans will not appear as pletor_* metrics.

Because the example mounts the whole /opt/pletor/config directory, its ConfigMap contains both node-metrics.yml and jmx-exporter.yml. Mounting only one file over that directory would hide the other image default.

Render and apply the Operator examples after changing all example names, listeners, ACLs, topic settings, and paths:

kubectl kustomize deploy/operator
kubectl apply -k deploy/operator

If the Prometheus Operator is installed, review the namespace and selector in pod-monitor.yaml, then apply it separately:

kubectl apply -f deploy/operator/pod-monitor.yaml

Verify the actual Pletor metrics instead of checking only that port 9404 is open:

pod="$(kubectl get pod \
  -l app.kubernetes.io/instance=schema,app.kubernetes.io/component=app \
  -o jsonpath='{.items[0].metadata.name}')"
kubectl port-forward "pod/$pod" 9404:9404
curl -fsS http://127.0.0.1:9404/metrics \
  | grep -E '^pletor_(node|proc|cgroup|agent)'

⁠KafkaSQL and Strimzi integration

For Kafka clusters using SCRAM/TLS, kafkaAccessSecretName is preferred. The strimzi-kafka-access.yaml example shows the KafkaUser ACL and KafkaAccess binding shape. Change the cluster, listener, user, topic prefix, group prefix, and ACLs to match the customer environment.

KafkaSQL uses journal, snapshot, and events topics. The journal and snapshot topics must use cleanup.policy: delete with infinite retention.ms and retention.bytes. Review replication factor and min.insync.replicas before applying kafkasql-topics.yaml.

⁠Metrics configuration

The upstream application and management interfaces remain on ports 8080 and 9000. Pletor JMX Exporter listens on 9404 in the application pod and is the Prometheus bridge for node-metrics-agent MBeans.

The example declares a named pletor-jmx container port, but using the image does not automatically create a Service or PodMonitor for port 9404. Configure the monitoring stack to scrape the application pod at /metrics on that port. The Operator health endpoints remain available on the management interface:

http://<pod-ip>:9000/health/ready
http://<pod-ip>:9000/health/live
http://<pod-ip>:9404/metrics

Mount customer-specific files over /opt/pletor/config/jmx-exporter.yml and /opt/pletor/config/node-metrics.yml when different JMX rules or filesystem paths are required.

⁠Scope

The Apicurio Registry Operator remains responsible for application and UI Deployments, Services, ingress, health probes, storage configuration, secrets, and rolling updates. Strimzi remains responsible for Kafka, listeners, certificates, users, ACLs, and Kafka Access bindings.

The image intentionally does not contain:

• customer-specific configuration or credentials
• private keys, certificates, or pre-generated certificate authorities
• the Apicurio Registry UI or Operator runtime
• a PostgreSQL or Kafka server
• VM/bare-metal installation scripts or systemd units

VM/bare-metal packages are separate release artifacts generated by this project.

⁠Security and build properties

• The official Apicurio Registry base image is pinned by digest during build.
• JMX Exporter and node metrics agent artifacts are verified with SHA-256.
• Release tags contain both linux/amd64 and linux/arm64 manifests.
• The final application container runs as upstream UID 1001.
• No customer secrets are embedded in the image.
• Release images are built and pushed from matching Git tags.

⁠Deployment examples

These manifests demonstrate image integration and must be reviewed before production use.