Apicurio Registry Operator configuration reference

ApicurioRegistry3 custom resource structure

The ApicurioRegistry3 custom resource defines the desired state of a Apicurio Registry instance. The resource is organized into two main sections under spec:

apiVersion: registry.apicur.io/v1
kind: ApicurioRegistry3
metadata:
  name: example-registry
spec:
  app:
    # Configuration for the Apicurio Registry backend (REST API) component.
  ui:
    # Configuration for the Apicurio Registry web console component.

Apicurio Registry backend (REST API) component configuration reference

The spec.app section configures the backend component, which provides the REST API.

Common component fields

The following fields are available for both spec.app and spec.ui components:

Field Description Type Default

replicas

Number of pod replicas for the component

Integer

1

env

List of environment variables to pass to the component’s container

Array of EnvVar

[]

ingress

Ingress configuration for the component

IngressSpec

See Ingress configuration reference

podTemplateSpec

Custom PodTemplateSpec for advanced pod configuration

PodTemplateSpec

Operator-generated defaults

podDisruptionBudget

PodDisruptionBudget configuration

PodDisruptionSpec

{ enabled: true }

networkPolicy

NetworkPolicy configuration

NetworkPolicySpec

{ enabled: true }

host (deprecated)

Use ingress.host instead

String

""

Application-specific fields

The following fields are specific to spec.app:

Field Description Type Default

storage

Storage configuration for the backend

StorageSpec

See Storage configuration reference

features

Feature flags for the backend

AppFeaturesSpec

See below

auth

Authentication and authorization configuration

AuthSpec

See Authentication and authorization configuration reference

tls

TLS configuration for the application

TLSSpec

See below

AppFeaturesSpec

Configure optional features for Apicurio Registry:

Field Description Type Default

resourceDeleteEnabled

Allow deletion of groups, artifacts, and artifact versions. By default, resources in Apicurio Registry are immutable.

Boolean

false

versionMutabilityEnabled

Allow artifact versions in DRAFT state to be mutable. Enabling this also unlocks Studio functionality in the UI.

Boolean

false

Example:

spec:
  app:
    features:
      resourceDeleteEnabled: true
      versionMutabilityEnabled: true

TLSSpec

Configure TLS certificates for the application:

Field Description Type Default

keystoreSecretRef

Reference to a Secret containing the keystore (PKCS12 format). Default key: keystore.p12

SecretKeyRef

None

keystorePasswordSecretRef

Reference to a Secret containing the keystore password. Default key: password

SecretKeyRef

None

Example:

spec:
  app:
    tls:
      keystoreSecretRef:
        name: registry-tls
        key: keystore.p12
      keystorePasswordSecretRef:
        name: registry-tls
        key: keystore.password

UI component configuration reference

The spec.ui section configures the Apicurio Registry web console component.

UI-specific fields

Field Description Type Default

enabled

Whether the operator should deploy the UI component

Boolean

true

The UI component also supports all common component fields listed in Apicurio Registry backend (REST API) component configuration reference.

Example:

spec:
  ui:
    enabled: true
    replicas: 2
    env:
      - name: REGISTRY_API_URL
        value: https://registry-api.example.com/apis/registry/v3
    ingress:
      host: registry-ui.example.com

Storage configuration reference

The spec.app.storage section configures the storage backend for Apicurio Registry.

StorageSpec

Field Description Type Default

type

Storage type: <empty> (in-memory), postgresql, or kafkasql

String

"" (in-memory)

sql

SQL database configuration. Required when type is postgresql

SqlSpec

None

kafkasql

KafkaSQL storage configuration. Required when type is kafkasql

KafkaSqlSpec

None
The default in-memory storage is not suitable for production environments.

SqlSpec

Configure SQL database storage (PostgreSQL or MySQL):

Field Description Type

dataSource

Data source configuration

DataSourceSpec

DataSourceSpec

Field Description Type Default

url

JDBC connection URL. Example: jdbc:postgresql://postgresql.my-ns.svc:5432/registry

String

None

username

Database username

String

None

password

Reference to a Secret containing the database password. Default key: password

SecretKeyRef

None

Example for PostgreSQL:

spec:
  app:
    storage:
      type: postgresql
      sql:
        dataSource:
          url: jdbc:postgresql://postgresql.my-project.svc:5432/registry
          username: registry_user
          password:
            name: postgresql-credentials
            key: password

Example for MySQL:

spec:
  app:
    storage:
      type: mysql
      sql:
        dataSource:
          url: jdbc:mysql://mysql.my-project.svc:3306/registry
          username: registry_user
          password:
            name: mysql-credentials
            key: password

KafkaSqlSpec

Configure KafkaSQL storage:

Field Description Type Default

bootstrapServers

Kafka bootstrap servers address. Required for KafkaSQL storage.

String

None

tls

TLS configuration for connecting to Kafka

KafkaSqlTLSSpec

None

auth

Authentication configuration for connecting to Kafka

KafkaSqlAuthSpec

None

Example:

spec:
  app:
    storage:
      type: kafkasql
      kafkasql:
        bootstrapServers: my-cluster-kafka-bootstrap.my-project.svc:9092

KafkaSqlTLSSpec

Configure TLS for KafkaSQL storage:

Field Description Type Default

truststoreSecretRef

Reference to a Secret containing the TLS truststore (PKCS12 format). Default key: ca.p12

SecretKeyRef

None

truststorePasswordSecretRef

Reference to a Secret containing the truststore password. Default key: ca.password

SecretKeyRef

None

Example:

spec:
  app:
    storage:
      type: kafkasql
      kafkasql:
        bootstrapServers: my-cluster-kafka-bootstrap.my-project.svc:9093
        tls:
          truststoreSecretRef:
            name: kafka-cluster-ca-cert
            key: ca.p12
          truststorePasswordSecretRef:
            name: kafka-cluster-ca-cert
            key: ca.password

KafkaSqlAuthSpec

Configure SASL authentication for KafkaSQL storage:

Field Description Type Default

mechanism

SASL mechanism. Examples: SCRAM-SHA-512, PLAIN, OAUTHBEARER

String

None

usernameSecretRef

Reference to a Secret containing the username. Default key: username

SecretKeyRef

None

passwordSecretRef

Reference to a Secret containing the password. Default key: password

SecretKeyRef

None

clientIdSecretRef

Reference to a Secret containing the OAuth client ID (for OAUTHBEARER). Default key: clientId

SecretKeyRef

None

clientSecretSecretRef

Reference to a Secret containing the OAuth client secret (for OAUTHBEARER). Default key: clientSecret

SecretKeyRef

None

tokenEndpointUri

OAuth token endpoint URI (for OAUTHBEARER)

String

None

Example with SCRAM-SHA-512:

spec:
  app:
    storage:
      type: kafkasql
      kafkasql:
        bootstrapServers: my-cluster-kafka-bootstrap.my-project.svc:9093
        auth:
          mechanism: SCRAM-SHA-512
          usernameSecretRef:
            name: kafka-credentials
            key: username
          passwordSecretRef:
            name: kafka-credentials
            key: password

Authentication and authorization configuration reference

The spec.app.auth section configures OIDC authentication and role-based authorization.

AuthSpec

Field Description Type Default

enabled

Enable authentication

Boolean

false

appClientId

OIDC client ID for the backend application

String

None

uiClientId

OIDC client ID for the UI application

String

None

authServerUrl

URL of the identity server (OIDC issuer)

String

None

redirectUri

Redirect URI after successful authentication

String

None

logoutUrl

Redirect URI after logout

String

None

anonymousReadsEnabled

Allow anonymous users to make read-only calls to the REST API

Boolean

false

authz

Authorization configuration

AuthzSpec

See below

basicAuth

Client credentials basic authentication configuration

BasicAuthSpec

See below

tls

TLS configuration for OIDC connections

AuthTLSSpec

See below

Example:

spec:
  app:
    auth:
      enabled: true
      appClientId: registry-client-api
      uiClientId: registry-client-ui
      authServerUrl: https://keycloak.example.com/realms/registry
      redirectUri: https://registry-ui.example.com
      logoutUrl: https://registry-ui.example.com
      anonymousReadsEnabled: false

AuthzSpec

Configure role-based authorization:

Field Description Type Default

enabled

Enable role-based authorization

Boolean

false

ownerOnlyEnabled

When enabled, only the user who created an artifact can modify or delete it

Boolean

false

groupAccessEnabled

When enabled with owner-only authorization, only the user who created an artifact group has write access

Boolean

false

readAccessEnabled

When enabled, grants at least read-only access to all authenticated users in the organization

Boolean

false

roles

Role configuration

AuthzRolesSpec

See below

adminOverride

Admin override configuration

AdminOverrideSpec

See below

Example:

spec:
  app:
    auth:
      authz:
        enabled: true
        ownerOnlyEnabled: true
        groupAccessEnabled: false
        readAccessEnabled: true
        roles:
          source: token
          admin: sr-admin
          developer: sr-developer
          readOnly: sr-readonly

AuthzRolesSpec

Configure authorization roles:

Field Description Type Default

source

Role source. Use token to extract roles from the authentication token

String

None

admin

Name of the admin role

String

None

developer

Name of the developer role

String

None

readOnly

Name of the read-only role

String

None

AdminOverrideSpec

Configure admin override functionality:

Field Description Type Default

enabled

Enable admin override

Boolean

false

from

Where to look for admin override information. Only token is currently supported

String

None

type

Type of information used to determine admin status: role or claim

String

None

role

Name of the role that indicates admin status (when type is role)

String

None

claimName

Name of the JWT claim to use for admin override (when type is claim)

String

None

claimValue

Required value of the JWT claim (when type is claim)

String

None

Example using role-based admin override:

spec:
  app:
    auth:
      authz:
        enabled: true
        adminOverride:
          enabled: true
          from: token
          type: role
          role: sr-admin

Example using claim-based admin override:

spec:
  app:
    auth:
      authz:
        enabled: true
        adminOverride:
          enabled: true
          from: token
          type: claim
          claimName: org-admin
          claimValue: "true"

BasicAuthSpec

Configure basic authentication for client credentials:

Field Description Type Default

enabled

Enable client credentials basic authentication

Boolean

false

cacheExpiration

Token cache expiration time (e.g., 25m, 1h)

String

None

Example:

spec:
  app:
    auth:
      basicAuth:
        enabled: true
        cacheExpiration: 25m

AuthTLSSpec

Configure TLS for OIDC connections:

Field Description Type Default

tlsVerificationType

TLS verification type: all, none

String

all

truststoreSecretRef

Reference to a Secret containing the TLS truststore (PKCS12 format). Default key: ca.p12

SecretKeyRef

None

truststorePasswordSecretRef

Reference to a Secret containing the truststore password. Default key: ca.password

SecretKeyRef

None

Example:

spec:
  app:
    auth:
      tls:
        tlsVerificationType: all
        truststoreSecretRef:
          name: keycloak-ca-cert
          key: ca.p12
        truststorePasswordSecretRef:
          name: keycloak-ca-cert
          key: ca.password

Ingress configuration reference

The ingress section is available for both spec.app and spec.ui components.

IngressSpec

Field Description Type Default

enabled

Whether the operator should manage an Ingress resource. Set to false to create your own Ingress

Boolean

true

host

Hostname for the Ingress. If empty, the operator will not create an Ingress resource

String

""

ingressClassName

IngressClass to use for the Ingress resource

String

None

annotations

Additional annotations for the Ingress resource

Map[String]String

{}

Example:

spec:
  app:
    ingress:
      host: registry-api.example.com
      ingressClassName: nginx
      annotations:
        nginx.org/proxy-connect-timeout: "30s"
  ui:
    ingress:
      host: registry-ui.example.com
      ingressClassName: nginx
      annotations:
        nginx.org/proxy-connect-timeout: "30s"

SecretKeyRef

Many configuration fields use SecretKeyRef to reference Kubernetes Secrets:

Field Description Type Default

name

Name of the Secret

String

Required

key

Key within the Secret containing the target data

String

Field-specific default (e.g., password, ca.p12)

Example:

password:
  name: db-credentials
  key: db-password

For Developers

Java model classes for the ApicurioRegistry3 custom resource are available as a Maven artifact:

<dependency>
    <groupId>io.apicurio</groupId>
    <artifactId>apicurio-registry-operator-model</artifactId>
    <version>3.1.0</version>
</dependency>

and can be used with the Fabric8 Kubernetes Client library to programmatically create and manage Apicurio Registry Operator resources.

Additional resources