Configuring Apicurio Registry storage

This chapter explains how to configure the available Apicurio Registry storage options:

This chapter mostly focuses on storage configuration procedures for OpenShift using OperatorHub UI. If you are deploying to Kubernetes, you can use command line tools to perform the equivalent steps. The Apicurio Registry Operator supports the same configuration options on OpenShift and Kubernetes.

Apicurio Registry storage options

The main decision to make when deploying Apicurio Registry is which storage backend to use.

The following storage options are available:

Table 1. Apicurio Registry data storage options
Storage option Description

In-memory

Data is stored in RAM on each Apicurio Registry node. This is the easiest deployment to use, but is not recommended for production environment. All data is lost when restarting Apicurio Registry with this storage option, which is suitable for a development environment only.

SQL database

Data is stored in a relational database, in this case PostgreSQL 12+. This is the recommended storage option in a production environment for performance, stability, and data management (backup/restore, and so on).

Apache Kafka

Data is stored using Apache Kafka, with the help of a local SQL database on each node. This storage option is provided for production environments where database management expertise is not available, or where storage in Kafka is a specific requirement.
Storage requiring installation

The following options require that the storage is already installed as a prerequisite:

  • SQL (PostgreSQL)

  • Apache Kafka

Additional resources

Configuring Apicurio Registry In-Memory storage using CLI

The in-memory storage option uses RAM to store the data on nodes where Apicurio Registry is deployed, and it is the simplest persistence option to use. The Apicurio Registry Operator will deploy Apicurio Registry in this way if you do not provide any configuration in the ApicurioRegistry CR:

apiVersion: registry.apicur.io/v1
kind: ApicurioRegistry
metadata:
  name: example-apicurioregistry-mem
spec:
  configuration:
    persistence: "mem" # Optional (default value)
    # NOTE: No additional configuration required for *dev* deployment
Prerequisites

  • You must have an Kubernetes cluster with cluster administrator access.

  • You must have already installed the Apicurio Registry Operator.

Procedure

  1. Deploy the example CR using following commands:

    export NAMESPACE="default"
curl -sSL "https://raw.githubusercontent.com/Apicurio/apicurio-registry-operator/main/docs/modules/ROOT/examples/apicurioregistry_mem_cr.yaml" | kubectl apply -f - -n $NAMESPACE
This persistence option does not support data distribution across Apicurio Registry nodes. Therefore, it is only recommended for development environments using a single replica (Pod). Use embedded Infinispan persistence option when deploying multiple replicas.

Configuring SQL (PostgreSQL) storage

Prerequisites
Procedure

  1. In the OpenShift Container Platform web console, log in with cluster administrator privileges.

  2. Change to the OpenShift project in which Apicurio Registry and your PostgreSQL Operator are installed. For example, from the Project drop-down, select my-project.

  3. Click Installed Operators > Apicurio Registry > ApicurioRegistry > Create ApicurioRegistry.

  4. Paste in the following ApicurioRegistry CR, and edit the values for the database url and credentials to match your environment:

    apiVersion: registry.apicur.io/v1
kind: ApicurioRegistry
metadata:
  name: example-apicurioregistry-sql
spec:
  configuration:
    persistence: "sql"
    sql:
      dataSource:
        url: "jdbc:postgresql://<service name>.<namespace>.svc:5432/<database name>"
        userName: "postgres"
        password: "<password>" # Optional

  5. Click Create and wait for the Apicurio Registry route to be created on OpenShift.

  6. Click Networking > Route to access the new route for the Apicurio Registry web console.

Additional resources

Configuring plain Kafka storage with no security

You can configure the Strimzi Operator and Apicurio Registry Operator to use a default connection with no security.

Prerequisites

  • You have installed the Apicurio Registry Operator using the OperatorHub or command line.

  • You have installed the Strimzi Operator or have Kafka accessible from your OpenShift cluster.

Procedure

  1. In the OpenShift web console, click Installed Operators, select the Strimzi Operator details, and then the Kafka tab.

  2. Click Create Kafka to provision a new Kafka cluster for Apicurio Registry storage. You can use the default value, for example:

    apiVersion: kafka.strimzi.io/v1beta2
kind: Kafka
metadata:
  name: my-cluster
  namespace: registry-example-kafkasql-plain
  # Change or remove the explicit namespace
spec:
  kafka:
    config:
      offsets.topic.replication.factor: 3
      transaction.state.log.replication.factor: 3
      transaction.state.log.min.isr: 2
      log.message.format.version: '2.7'
      inter.broker.protocol.version: '2.7'
    version: 2.7.0
    storage:
      type: ephemeral
    replicas: 3
    listeners:
      - name: plain
        port: 9092
        type: internal
        tls: false
      - name: tls
        port: 9093
        type: internal
        tls: true
  entityOperator:
    topicOperator: {}
    userOperator: {}
  zookeeper:
    storage:
      type: ephemeral
    replicas: 3
    Your OpenShift project namespace might be different.

  3. When the cluster is ready, open the Kafka resource, examine the status block, and copy the bootstrapServers value for later use when deploying Apicurio Registry. For example:

    status:
  conditions:
    ...
  listeners:
    - addresses:
        - host: my-cluster-kafka-bootstrap.registry-example-kafkasql-plain.svc
          port: 9092
      bootstrapServers: 'my-cluster-kafka-bootstrap.registry-example-kafkasql-plain.svc:9092'
      type: plain
  ...

    The default Kafka topic name automatically created by Apicurio Registry to store data is kafkasql-journal. You can override this behavior or the default topic name by setting environment variables. The default values are as follows:

    • REGISTRY_KAFKASQL_TOPIC_AUTO_CREATE=true

    • REGISTRY_KAFKASQL_TOPIC=kafkasql-journal

    If you decide not to create the Kafka topic manually, skip the next step.

  4. Click the Kafka Topic tab, and then Create Kafka Topic to create the kafkasql-journal topic:

    apiVersion: kafka.strimzi.io/v1beta1
kind: KafkaTopic
metadata:
  name: kafkasql-journal
  labels:
    strimzi.io/cluster: my-cluster
  namespace: registry-example-kafkasql-plain
spec:
  partitions: 2
  replicas: 1
  config:
    cleanup.policy: compact

  5. Select the Apicurio Registry Operator, and in the ApicurioRegistry tab, click Create ApicurioRegistry, using the following example, but replace your value in the bootstrapServers field.

    apiVersion: registry.apicur.io/v1
kind: ApicurioRegistry
metadata:
  name: example-apicurioregistry-kafkasql
spec:
  configuration:
    persistence: "kafkasql"
    kafkasql:
      bootstrapServers: "my-cluster-kafka-bootstrap.registry-example-kafkasql-plain.svc:9092"

  6. Wait a few minutes to see the Route being created, where you can access the application.

Configuring Kafka storage with TLS security

You can configure the Strimzi Operator and Apicurio Registry Operator to use an encrypted Transport Layer Security (TLS) connection.

Prerequisites

  • You have installed the Apicurio Registry Operator using the OperatorHub or command line.

  • You have installed the Strimzi Operator or have Kafka accessible from your OpenShift cluster.

This section assumes that the Strimzi Operator is available, however you can use any Kafka deployment. In that case, you must manually create the Openshift secrets that the Apicurio Registry Operator expects.
Procedure

  1. In the OpenShift web console, click Installed Operators, select the Strimzi Operator details, and then the Kafka tab.

  2. Click Create Kafka to provision a new Kafka cluster for Apicurio Registry storage.

  3. Configure the authorization and tls fields to use TLS authentication for the Kafka cluster, for example:

    apiVersion: kafka.strimzi.io/v1beta2
kind: Kafka
metadata:
  name: my-cluster
  namespace: registry-example-kafkasql-tls
  # Change or remove the explicit namespace
spec:
  kafka:
    config:
      offsets.topic.replication.factor: 3
      transaction.state.log.replication.factor: 3
      transaction.state.log.min.isr: 2
      log.message.format.version: '2.7'
      inter.broker.protocol.version: '2.7'
    version: 2.7.0
    storage:
      type: ephemeral
    replicas: 3
    listeners:
      - name: tls
        port: 9093
        type: internal
        tls: true
        authentication:
          type: tls
    authorization:
      type: simple
  entityOperator:
    topicOperator: {}
    userOperator: {}
  zookeeper:
    storage:
      type: ephemeral
    replicas: 3

    The default Kafka topic name automatically created by Apicurio Registry to store data is kafkasql-journal. You can override this behavior or the default topic name by setting environment variables. The default values are as follows:

    • REGISTRY_KAFKASQL_TOPIC_AUTO_CREATE=true

    • REGISTRY_KAFKASQL_TOPIC=kafkasql-journal

    If you decide not to create the Kafka topic manually, skip the next step.

  4. Click the Kafka Topic tab, and then Create Kafka Topic to create the kafkasql-journal topic:

    apiVersion: kafka.strimzi.io/v1beta1
kind: KafkaTopic
metadata:
  name: kafkasql-journal
  labels:
    strimzi.io/cluster: my-cluster
  namespace: registry-example-kafkasql-tls
spec:
  partitions: 2
  replicas: 1
  config:
    cleanup.policy: compact

  5. Create a Kafka User resource to configure authentication and authorization for the Apicurio Registry user. You can specify a user name in the metadata section or use the default my-user.

    apiVersion: kafka.strimzi.io/v1beta1
kind: KafkaUser
metadata:
  name: my-user
  labels:
    strimzi.io/cluster: my-cluster
  namespace: registry-example-kafkasql-tls
spec:
  authentication:
    type: tls
  authorization:
    acls:
      - operation: All
        resource:
          name: '*'
          patternType: literal
          type: topic
      - operation: All
        resource:
          name: '*'
          patternType: literal
          type: cluster
      - operation: All
        resource:
          name: '*'
          patternType: literal
          type: transactionalId
      - operation: All
        resource:
          name: '*'
          patternType: literal
          type: group
    type: simple
    This simple example assumes admin permissions and creates the Kafka topic automatically. You must configure the authorization section specifically for the topics and resources that the Apicurio Registry requires.

    The following example shows the minimum configuration required when the Kafka topic is created manually:

     ...
  authorization:
    acls:
    - operations:
        - Read
        - Write
      resource:
        name: kafkasql-journal
        patternType: literal
        type: topic
    - operations:
        - Read
        - Write
      resource:
        name: apicurio-registry-
        patternType: prefix
        type: group
    type: simple

  6. Click Workloads and then Secrets to find two secrets that Strimzi creates for Apicurio Registry to connect to the Kafka cluster:

    • my-cluster-cluster-ca-cert - contains the PKCS12 truststore for the Kafka cluster

    • my-user - contains the user’s keystore

      The name of the secret can vary based on your cluster or user name.

  7. If you create the secrets manually, they must contain the following key-value pairs:

    • my-cluster-ca-cert

      • ca.p12 - truststore in PKCS12 format

      • ca.password - truststore password

    • my-user

      • user.p12 - keystore in PKCS12 format

      • user.password - keystore password

  8. Configure the following example configuration to deploy the Apicurio Registry.

    apiVersion: registry.apicur.io/v1
kind: ApicurioRegistry
metadata:
  name: example-apicurioregistry-kafkasql-tls
spec:
  configuration:
    persistence: "kafkasql"
    kafkasql:
      bootstrapServers: "my-cluster-kafka-bootstrap.registry-example-kafkasql-tls.svc:9093"
      security:
        tls:
          keystoreSecretName: my-user
          truststoreSecretName: my-cluster-cluster-ca-cert
You must use a different bootstrapServers address than in the plain insecure use case. The address must support TLS connections and is found in the specified Kafka resource under the type: tls field.

Configuring Kafka storage with SCRAM security

You can configure the Strimzi Operator and Apicurio Registry Operator to use Salted Challenge Response Authentication Mechanism (SCRAM-SHA-512) for the Kafka cluster.

Prerequisites

  • You have installed the Apicurio Registry Operator using the OperatorHub or command line.

  • You have installed the Strimzi Operator or have Kafka accessible from your OpenShift cluster.

This section assumes that Strimzi Operator is available, however you can use any Kafka deployment. In that case, you must manually create the Openshift secrets that the Apicurio Registry Operator expects.
Procedure

  1. In the OpenShift web console, click Installed Operators, select the Strimzi Operator details, and then the Kafka tab.

  2. Click Create Kafka to provision a new Kafka cluster for Apicurio Registry storage.

  3. Configure the authorization and tls fields to use SCRAM-SHA-512 authentication for the Kafka cluster, for example:

    apiVersion: kafka.strimzi.io/v1beta2
kind: Kafka
metadata:
  name: my-cluster
  namespace: registry-example-kafkasql-scram
  # Change or remove the explicit namespace
spec:
  kafka:
    config:
      offsets.topic.replication.factor: 3
      transaction.state.log.replication.factor: 3
      transaction.state.log.min.isr: 2
      log.message.format.version: '2.7'
      inter.broker.protocol.version: '2.7'
    version: 2.7.0
    storage:
      type: ephemeral
    replicas: 3
    listeners:
      - name: tls
        port: 9093
        type: internal
        tls: true
        authentication:
          type: scram-sha-512
    authorization:
      type: simple
  entityOperator:
    topicOperator: {}
    userOperator: {}
  zookeeper:
    storage:
      type: ephemeral
    replicas: 3

    The default Kafka topic name automatically created by Apicurio Registry to store data is kafkasql-journal. You can override this behavior or the default topic name by setting environment variables. The default values are as follows:

    • REGISTRY_KAFKASQL_TOPIC_AUTO_CREATE=true

    • REGISTRY_KAFKASQL_TOPIC=kafkasql-journal

    If you decide not to create the Kafka topic manually, skip the next step.

  4. Click the Kafka Topic tab, and then Create Kafka Topic to create the kafkasql-journal topic:

    apiVersion: kafka.strimzi.io/v1beta1
kind: KafkaTopic
metadata:
  name: kafkasql-journal
  labels:
    strimzi.io/cluster: my-cluster
  namespace: registry-example-kafkasql-scram
spec:
  partitions: 2
  replicas: 1
  config:
    cleanup.policy: compact

  5. Create a Kafka User resource to configure SCRAM authentication and authorization for the Apicurio Registry user. You can specify a user name in the metadata section or use the default my-user.

    apiVersion: kafka.strimzi.io/v1beta1
kind: KafkaUser
metadata:
  name: my-user
  labels:
    strimzi.io/cluster: my-cluster
  namespace: registry-example-kafkasql-scram
spec:
  authentication:
    type: scram-sha-512
  authorization:
    acls:
      - operation: All
        resource:
          name: '*'
          patternType: literal
          type: topic
      - operation: All
        resource:
          name: '*'
          patternType: literal
          type: cluster
      - operation: All
        resource:
          name: '*'
          patternType: literal
          type: transactionalId
      - operation: All
        resource:
          name: '*'
          patternType: literal
          type: group
    type: simple
    This simple example assumes admin permissions and creates the Kafka topic automatically. You must configure the authorization section specifically for the topics and resources that the Apicurio Registry requires.

    The following example shows the minimum configuration required when the Kafka topic is created manually:

     ...
  authorization:
    acls:
    - operations:
        - Read
        - Write
      resource:
        name: kafkasql-journal
        patternType: literal
        type: topic
    - operations:
        - Read
        - Write
      resource:
        name: apicurio-registry-
        patternType: prefix
        type: group
    type: simple

  6. Click Workloads and then Secrets to find two secrets that Strimzi creates for Apicurio Registry to connect to the Kafka cluster:

    • my-cluster-cluster-ca-cert - contains the PKCS12 truststore for the Kafka cluster

    • my-user - contains the user’s keystore

      The name of the secret can vary based on your cluster or user name.

  7. If you create the secrets manually, they must contain the following key-value pairs:

    • my-cluster-ca-cert

      • ca.p12 - the truststore in PKCS12 format

      • ca.password - truststore password

    • my-user

      • password - user password

  8. Configure the following example settings to deploy the Apicurio Registry:

    apiVersion: registry.apicur.io/v1
kind: ApicurioRegistry
metadata:
  name: example-apicurioregistry-kafkasql-scram
spec:
  configuration:
    persistence: "kafkasql"
    kafkasql:
      bootstrapServers: "my-cluster-kafka-bootstrap.registry-example-kafkasql-scram.svc:9093"
      security:
        scram:
          truststoreSecretName: my-cluster-cluster-ca-cert
          user: my-user
          passwordSecretName: my-user
You must use a different bootstrapServers address than in the plain insecure use case. The address must support TLS connections, and is found in the specified Kafka resource under the type: tls field.