Conduktor Schema Registry Proxy configuration examples

Ready-to-adapt deployment examples and operational guidance for Schema Registry Proxy (SRP). For the full list of configuration options, see the Schema Registry Proxy environment variables reference. All deployments require a Conduktor Scale or Gateway license in CDK_LICENSE and an explicit AUTH_PROVIDER — SRP refuses to start without either.

Production deployment with full security

Reactive authorization (permissions managed in Console), JWT client authentication, HTTPS to clients, SASL/SSL to Kafka and mTLS to the backend registry. For the Self-service resources that authorize subjects for a service account, see grant schema permissions with an ApplicationInstance.

services:
  schema-registry-proxy:
    image: conduktor/conduktor-schema-registry-proxy:1.0.0
    hostname: srp-prod-1
    environment:
      # Core Configuration
      SCHEMA_REGISTRY_PROXY_APP_ID: srp-prod-cluster
      PORT: "8080"
      CDK_LICENSE: ${CDK_LICENSE}

      # SSL/TLS Server Configuration
      SSL_KEYSTORE_PATH: /opt/srp/certs/server.jks
      SSL_KEYSTORE_PASSWORD: ${SSL_KEYSTORE_PASSWORD}
      SSL_TRUSTSTORE_PATH: /opt/srp/certs/truststore.jks
      SSL_TRUSTSTORE_PASSWORD: ${SSL_TRUSTSTORE_PASSWORD}
      SSL_SECURE_PORT: "8443"
      SSL_INSECURE_ENABLED: "false"

      # Kafka Configuration with SASL/SSL
      KAFKA_BOOTSTRAP_SERVERS: kafka1:9093,kafka2:9093,kafka3:9093
      KAFKA_SECURITY_PROTOCOL: SASL_SSL
      KAFKA_SASL_MECHANISM: SCRAM-SHA-512
      KAFKA_SASL_JAAS_CONFIG: 'org.apache.kafka.common.security.scram.ScramLoginModule required username="${KAFKA_USER}" password="${KAFKA_PASSWORD}";'
      KAFKA_SSL_TRUSTSTORE_LOCATION: /opt/srp/certs/kafka-truststore.jks
      KAFKA_SSL_TRUSTSTORE_PASSWORD: ${KAFKA_TRUSTSTORE_PASSWORD}

      # Schema Registry Backend with mTLS
      CONFLUENT_SCHEMA_REGISTRY_URL: <https://schema-registry:8082>
      SCHEMA_REGISTRY_SSL_TRUSTSTORE_LOCATION: /opt/srp/certs/sr-truststore.jks
      SCHEMA_REGISTRY_SSL_TRUSTSTORE_PASSWORD: ${SR_TRUSTSTORE_PASSWORD}
      SCHEMA_REGISTRY_SSL_KEYSTORE_LOCATION: /opt/srp/certs/sr-client.jks
      SCHEMA_REGISTRY_SSL_KEYSTORE_PASSWORD: ${SR_KEYSTORE_PASSWORD}

      # JWT Authentication
      AUTH_PROVIDER: jwt
      JWT_JWKS_URL: <https://auth.company.com/realms/production/protocol/openid-connect/certs>
      JWT_VALIDATE_EXPIRATION: "true"
      JWT_SUBJECT_CLAIM_NAME: preferred_username

      # Authorization (reactive is the default; set explicitly for clarity)
      AUTHORIZATION_MODE: reactive

      # Observability
      OTEL_EXPORTER_OTLP_ENDPOINT: <http://otel-collector:4317>
      OTEL_TRACES_ENABLED: "true"
      OTEL_METRICS_ENABLED: "true"
      LOG_LEVEL: INFO
    volumes:
      - ./certs:/opt/srp/certs:ro
    ports:
      - "8443:8443"
      - "9464:9464"
    deploy:
      replicas: 3
      resources:
        limits:
          memory: 2G
          cpus: "2"
        reservations:
          memory: 1G
          cpus: "1"

Standalone deployment with topic ACL authorization

No Console and no Conduktor-specific Kafka topics: SRP authorizes against the topic ACLs already defined in your Kafka cluster, through the same Kafka connection settings. The authenticated identity (here, the JWT claim) has to match the Kafka ACL principal name.

services:
  schema-registry-proxy:
    image: conduktor/conduktor-schema-registry-proxy:1.0.0
    environment:
      PORT: "8080"
      CDK_LICENSE: ${CDK_LICENSE}

      # Kafka connection, used for ACL lookups via the Admin API
      KAFKA_BOOTSTRAP_SERVERS: kafka1:9093,kafka2:9093
      KAFKA_SECURITY_PROTOCOL: SASL_SSL
      KAFKA_SASL_MECHANISM: SCRAM-SHA-512
      KAFKA_SASL_JAAS_CONFIG: 'org.apache.kafka.common.security.scram.ScramLoginModule required username="${KAFKA_USER}" password="${KAFKA_PASSWORD}";'

      # Schema Registry backend
      CONFLUENT_SCHEMA_REGISTRY_URL: <YOUR_SCHEMA_REGISTRY_URL>

      # Client authentication
      AUTH_PROVIDER: jwt
      JWT_JWKS_URL: <YOUR_JWKS_ENDPOINT>
      JWT_SUBJECT_CLAIM_NAME: preferred_username

      # Authorization from Kafka topic ACLs
      AUTHORIZATION_MODE: topic-acl
      AUTHORIZATION_TOPIC_ACL_CACHE_TTL: 500ms
      AUTHORIZATION_TOPIC_ACL_LOOKUP_TIMEOUT: 5s

      # Observability (required for the Prometheus /metrics port)
      OTEL_EXPORTER_OTLP_ENDPOINT: <http://otel-collector:4317>
    ports:
      - "8080:8080"
      - "9464:9464"

In this mode Read requires a READ ACL on the subject’s topic and Write requires WRITE (ALL matches either). Write does not imply Read: a producer principal that also fetches schemas needs READ or ALL. Grant access with regular Kafka ACLs — nothing Conduktor-specific is involved. For example, to let the orders-app service account register and fetch schemas for every subject whose topic starts with orders:

kafka-acls --bootstrap-server <broker> \
  --command-config admin.properties \
  --add \
  --allow-principal User:orders-app \
  --operation READ \
  --operation WRITE \
  --topic orders \
  --resource-pattern-type PREFIXED

Both LITERAL and PREFIXED patterns apply, and a matching DENY always wins. The grant takes effect within the ACL cache TTL (500ms by default) — a producer that was getting 403 switches to successful schema registrations without a proxy restart.

Standalone read-only deployment with Basic authentication

The smallest possible deployment: just the proxy, a mounted credentials file and the backend registry. Every authenticated read passes through; every write is rejected with 403. No Kafka connection and no OAuth provider are needed.

services:
  schema-registry-proxy:
    image: conduktor/conduktor-schema-registry-proxy:1.0.0
    environment:
      PORT: "8080"
      CDK_LICENSE: ${CDK_LICENSE}

      # Schema Registry backend
      CONFLUENT_SCHEMA_REGISTRY_URL: <YOUR_SCHEMA_REGISTRY_URL>

      # Client authentication from a mounted credentials file
      AUTH_PROVIDER: basic
      BASIC_AUTH_LOCATION: /etc/srp/basic-auth.json
      BASIC_AUTH_RELOAD_INTERVAL: 30s

      # Reads pass through, writes return 403
      AUTHORIZATION_MODE: read-only

      # Optional break-glass identity allowed to write through the proxy
      AUTHORIZATION_SUPER_USERS: schema-admin@example.com

      # Observability (required for the Prometheus /metrics port)
      OTEL_EXPORTER_OTLP_ENDPOINT: <http://otel-collector:4317>
    volumes:
      - ./basic-auth.json:/etc/srp/basic-auth.json:ro
    ports:
      - "8080:8080"
      - "9464:9464"

The credentials file holds bcrypt-hashed passwords and is hot-reloaded on change, so you can rotate credentials without a restart:

[
  { "user": "schema-admin@example.com", "password": "$2a$12$...bcrypt hash..." },
  { "user": "consumer-app@example.com", "password": "$2a$12$...bcrypt hash..." }
]

Mount choice decides whether live reload survives your editor. Bind-mounting the single file (as above) binds the container to that file’s inode: only in-place writes (cat > file, tee, Ansible copy and most CD tooling) are seen. Editors like vim, VS Code and IntelliJ, plus sed -i, mv and git checkout, replace the file with a new inode — the container keeps reading the copy it started with, and nothing after that reaches the proxy until a restart rebinds it. Mounting the parent directory instead (- ./conf:/etc/srp:ro) re-resolves the filename on every read and survives any editor, at the cost of exposing everything else in that directory to the proxy.

Generate a hash with htpasswd (from Apache httpd, also available as a container image):

htpasswd -nbB -C 12 consumer-app@example.com '<password>' | cut -d: -f2
# or without a local install:
docker run --rm httpd:alpine htpasswd -nbB -C 12 consumer-app@example.com '<password>'

Verify the behavior split: a super user may register a schema, while every other authenticated user can read but not write:

# super user registers a schema (200)
curl -u schema-admin@example.com:<password> \
  -X POST -H "Content-Type: application/vnd.schemaregistry.v1+json" \
  --data '{"schema":"{\"type\":\"string\"}"}' \
  http://localhost:8080/subjects/orders-value/versions

# read-only user: read succeeds (200), the same write is denied (403)
curl -u consumer-app@example.com:<password> \
  http://localhost:8080/subjects/orders-value/versions/latest

Multi-node deployment

For high availability deployments with multiple SRP instances:

services:
  schema-registry-proxy-1:
    image: conduktor/conduktor-schema-registry-proxy:1.0.0
    environment:
      SCHEMA_REGISTRY_PROXY_APP_ID: srp-cluster
      CLUSTER_NODE_INDEX: "0"
      CLUSTER_MAX_NODE_INDEX: "2"
      # ... other configuration ...

  schema-registry-proxy-2:
    image: conduktor/conduktor-schema-registry-proxy:1.0.0
    environment:
      SCHEMA_REGISTRY_PROXY_APP_ID: srp-cluster
      CLUSTER_NODE_INDEX: "1"
      CLUSTER_MAX_NODE_INDEX: "2"
      # ... other configuration ...

  schema-registry-proxy-3:
    image: conduktor/conduktor-schema-registry-proxy:1.0.0
    environment:
      SCHEMA_REGISTRY_PROXY_APP_ID: srp-cluster
      CLUSTER_NODE_INDEX: "2"
      CLUSTER_MAX_NODE_INDEX: "2"
      # ... other configuration ...

Security configurations

Example: Confluent Cloud integration

environment:
  # Kafka connection to Confluent Cloud
  KAFKA_BOOTSTRAP_SERVERS: <pkc-xxxxx.region.provider.confluent.cloud:9092>
  KAFKA_SECURITY_PROTOCOL: SASL_SSL
  KAFKA_SASL_MECHANISM: PLAIN
  KAFKA_SASL_JAAS_CONFIG: 'org.apache.kafka.common.security.plain.PlainLoginModule required username="${CONFLUENT_API_KEY}" password="${CONFLUENT_API_SECRET}";'

  # Schema Registry connection
  CONFLUENT_SCHEMA_REGISTRY_URL: <https://psrc-xxxxx.region.provider.confluent.cloud>
  SCHEMA_REGISTRY_BASIC_AUTH_CREDENTIALS_SOURCE: USER_INFO
  SCHEMA_REGISTRY_BASIC_AUTH_USER_INFO: "${SR_API_KEY}:${SR_API_SECRET}"

Example: Keycloak integration

environment:
  AUTH_PROVIDER: jwt
  JWT_JWKS_URL: <https://keycloak.company.com/realms/production/protocol/openid-connect/certs>
  JWT_VALIDATE_EXPIRATION: "true"
  JWT_SUBJECT_CLAIM_NAME: preferred_username

Monitoring and operations

Health checks

Health check: GET http://host:${PORT}/health, on the API port (PORT, default 8080; SSL_SECURE_PORT when HTTPS is enabled)
Prometheus metrics: GET http://host:${OTEL_PROMETHEUS_PORT}/metrics

Logging

Structured JSON logging with configurable levels:

environment:
  LOG_LEVEL: INFO # DEBUG for troubleshooting
  JAVALIN_DEV_LOGGING_ENABLED: "false" # Never enable in production

Distributed tracing

When configured with OpenTelemetry, the service automatically creates spans for:

HTTP requests (parent spans)
Backend Schema Registry calls (child spans)
Kafka operations (consuming permissions, publishing heartbeats)
Authentication/authorization operations

Useful links

Schema Registry Proxy metrics reference

Conduktor in production

Deploy Console

Deploy Schema Registry Proxy

Deploy Gateway

Initial setup

Conduktor Schema Registry Proxy configuration examples

Production deployment with full security

Standalone deployment with topic ACL authorization

Standalone read-only deployment with Basic authentication

Multi-node deployment

Security configurations

Example: Confluent Cloud integration

Example: Keycloak integration

Monitoring and operations

Health checks

Logging

Distributed tracing

Useful links

​Production deployment with full security

​Standalone deployment with topic ACL authorization

​Standalone read-only deployment with Basic authentication

​Multi-node deployment

​Security configurations

​Example: Confluent Cloud integration

​Example: Keycloak integration

​Monitoring and operations

​Health checks

​Logging

​Distributed tracing

​Useful links

Production deployment with full security

Standalone deployment with topic ACL authorization

Standalone read-only deployment with Basic authentication

Multi-node deployment

Security configurations

Example: Confluent Cloud integration

Example: Keycloak integration

Monitoring and operations

Health checks

Logging

Distributed tracing

Useful links