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:

  • 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.

  • Infinispan - data is stored in an embedded Infinispan cache.

  • Apache Kafka - data is stored using plain Apache Kafka.

  • Apache Kafka Steams - data is stored using Apache Kafka Streams. This option is recommended for most production deployments.

  • Java Persistence API (PostgreSQL) - data is stored in a relational database, in this case PostgreSQL 12+.

Storage requiring installation

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

  • Apache Kafka

  • Apache Kafka Streams

  • Java Persistence API (PostgreSQL)

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: apicur.io/v1alpha1
kind: ApicurioRegistry
metadata:
  name: example-apicurioregistry
# spec:
# No config required for dev deployment
# NOTE: In-memory storage option is not suitable for production environment
Prerequisites

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

  • You must have already installed the Apicurio Registry Operator.

Procedure

  1. Deploy the example CR using following commands:

    export REF="0.0.4" &&
curl -sSL "https://raw.githubusercontent.com/Apicurio/apicurio-registry-operator/$REF/docs/modules/ROOT/examples/in-memory_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 Apicurio Registry Infinispan storage

The Apicurio Registry Infinispan storage option uses RAM to store the data on nodes where Apicurio Registry is deployed. This is achieved using an embedded Infinispan in-memory data grid, which also provides data replication between nodes. This configuration is simple, with an optional field to provide a name for the Infinispan cluster.

Prerequisites

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

  • You must have already installed the Apicurio Registry Operator.

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 is installed. For example, from the Project drop-down, select my-project.

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

  4. Use the following example ApicurioRegistry CR:

apiVersion: apicur.io/v1alpha1
kind: ApicurioRegistry
metadata:
  name: example-apicurioregistry
spec:
  configuration:
    persistence: "infinispan"
    infinispan: # Currently, registry uses an embedded version of Infinispan
      clusterName: "example-apicurioregistry"
      # ^ Optional

Configuring plain Kafka storage

You can configure the Strimzi Operator and Apicurio Registry Operator to use plain Kafka (without Kafka Streams) and with no security.

Prerequisites

  • You must install the Apicurio Registry Operator using the OperatorHub or command line.

  • You must install 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/v1beta1
kind: Kafka
metadata:
  name: my-cluster
  namespace: registry-example-kafka
spec:
  kafka:
    version: 2.5.0
    replicas: 3
    listeners:
      plain: {}
      tls: {}
    config:
      offsets.topic.replication.factor: 3
      transaction.state.log.replication.factor: 3
      transaction.state.log.min.isr: 2
      log.message.format.version: '2.5'
    storage:
      type: ephemeral
  zookeeper:
    replicas: 3
    storage:
      type: ephemeral
  entityOperator:
    topicOperator: {}
    userOperator: {}
    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-kafka.svc
          port: 9092
      bootstrapServers: 'my-cluster-kafka-bootstrap.registry-example-kafka.svc:9092'
      type: plain
  ...

  4. Click the Kafka Topic tab, and then Create Kafka Topic to create the required global-id-topic:

    apiVersion: kafka.strimzi.io/v1beta1
kind: KafkaTopic
metadata:
  name: global-id-topic
  labels:
    strimzi.io/cluster: my-cluster
  namespace: registry-example-kafka
spec:
  partitions: 2
  replicas: 1
  config:
    retention.ms: 604800000
    segment.bytes: 1073741824

  5. Change the topic name to global-id-topic, and optionally decrease the partition and replica count to minimum, which is sufficient for an example deployment.

  6. Perform the same steps to create the required storage-topic topic.

  7. 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: apicur.io/v1alpha1
kind: ApicurioRegistry
metadata:
  name: example-apicurioregistry
spec:
  configuration:
    persistence: "kafka"
    kafka:
      bootstrapServers: "my-cluster-kafka-bootstrap.registry-example-kafka.svc:9092"

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

Configuring plain Kafka Streams storage with no security

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

Prerequisites

  • You must install the Apicurio Registry Operator using the OperatorHub or command line.

  • You must install 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/v1beta1
kind: Kafka
metadata:
  name: my-cluster
  namespace: registry-example-streams-plain
spec:
  kafka:
    version: 2.5.0
    replicas: 3
    listeners:
      plain: {}
      tls: {}
    config:
      offsets.topic.replication.factor: 3
      transaction.state.log.replication.factor: 3
      transaction.state.log.min.isr: 2
      log.message.format.version: '2.5'
    storage:
      type: ephemeral
  zookeeper:
    replicas: 3
    storage:
      type: ephemeral
  entityOperator:
    topicOperator: {}
    userOperator: {}
    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-streams-plain.svc
          port: 9092
      bootstrapServers: 'my-cluster-kafka-bootstrap.registry-example-streams-plain.svc:9092'
      type: plain
  ...

  4. Click the Kafka Topic tab, and then Create Kafka Topic to create the required global-id-topic:

    apiVersion: kafka.strimzi.io/v1beta1
kind: KafkaTopic
metadata:
  name: global-id-topic
  labels:
    strimzi.io/cluster: my-cluster
  namespace: registry-example-streams-plain
spec:
  partitions: 2
  replicas: 1
  config:
    retention.ms: 604800000
    segment.bytes: 1073741824

  5. Change the topic name to global-id-topic, and optionally decrease the partition and replica count to minimum, which is sufficient for an example deployment.

  6. Perform the same steps to create the required storage-topic topic.

  7. 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: apicur.io/v1alpha1
kind: ApicurioRegistry
metadata:
  name: example-apicurioregistry
spec:
  configuration:
    persistence: "streams"
    streams:
      bootstrapServers: "my-cluster-kafka-bootstrap.registry-example-streams-plain.svc:9092"

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

Configuring Kafka Streams 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 must install the Apicurio Registry Operator using the OperatorHub or command line.

  • You must install 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/v1beta1
kind: Kafka
metadata:
  name: my-cluster
  namespace: registry-example-streams-tls
spec:
  kafka:
    authorization:
      type: simple
    version: 2.5.0
    replicas: 3
    listeners:
      plain: {}
      tls:
        authentication:
          type: tls
    config:
      offsets.topic.replication.factor: 3
      transaction.state.log.replication.factor: 3
      transaction.state.log.min.isr: 2
      log.message.format.version: '2.5'
    storage:
      type: ephemeral
  zookeeper:
    replicas: 3
    storage:
      type: ephemeral
  entityOperator:
    topicOperator: {}
    userOperator: {}

  4. Click the Kafka Topic tab, and then Create Kafka Topic to create the required global-id-topic:

    apiVersion: kafka.strimzi.io/v1beta1
kind: KafkaTopic
metadata:
  name: global-id-topic
  labels:
    strimzi.io/cluster: my-cluster
  namespace: registry-example-streams-plain
spec:
  partitions: 2
  replicas: 1
  config:
    retention.ms: 604800000
    segment.bytes: 1073741824

  5. Change the topic name to global-id-topic, and optionally decrease the partition and replica count to minimum, which is sufficient for an example deployment.

  6. Perform the same steps to create the required storage-topic topic.

  7. Create a Kafka User resource to configure authentication and authorization for the Apicurio Registry user. For example, in the spec block, you can specify a user name in the metadata section or use the default my-user.

    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
    You must configure the authorization specifically for the topics and resources that the Apicurio Registry requires. This is a simple example.

  8. 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.

  9. 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

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

    apiVersion: apicur.io/v1alpha1
kind: ApicurioRegistry
metadata:
  name: example-apicurioregistry
spec:
  configuration:
    persistence: "streams"
    streams:
      bootstrapServers: "my-cluster-kafka-bootstrap.registry-example-streams-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 Streams 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 must install the Apicurio Registry Operator using the OperatorHub or command line.

  • You must install 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/v1beta1
kind: Kafka
metadata:
  name: my-cluster
  namespace: registry-example-streams-tls
spec:
  kafka:
    authorization:
      type: simple
    version: 2.5.0
    replicas: 3
    listeners:
      plain: {}
      tls:
        authentication:
          type: scram-sha-512
    config:
      offsets.topic.replication.factor: 3
      transaction.state.log.replication.factor: 3
      transaction.state.log.min.isr: 2
      log.message.format.version: '2.5'
    storage:
      type: ephemeral
  zookeeper:
    replicas: 3
    storage:
      type: ephemeral
  entityOperator:
    topicOperator: {}
    userOperator: {}

  4. Click the Kafka Topic tab, and then Create Kafka Topic to create the required global-id-topic:

    apiVersion: kafka.strimzi.io/v1beta1
kind: KafkaTopic
metadata:
  name: global-id-topic
  labels:
    strimzi.io/cluster: my-cluster
  namespace: registry-example-streams-plain
spec:
  partitions: 2
  replicas: 1
  config:
    retention.ms: 604800000
    segment.bytes: 1073741824

  5. Change the topic name to global-id-topic, and optionally decrease the partition and replica count to minimum, which is sufficient for an example deployment.

  6. Perform the same steps to create the required storage-topic topic.

  7. Create a Kafka User resource to configure SCRAM authentication and authorization for the Apicurio Registry user. For example, in the spec block, see the authentication section.

    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

  8. 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.

  9. 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

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

    apiVersion: apicur.io/v1alpha1
kind: ApicurioRegistry
metadata:
  name: example-apicurioregistry
spec:
  configuration:
    persistence: "streams"
    streams:
      bootstrapServers: "my-cluster-kafka-bootstrap.registry-example-streams-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.

Configuring Java Persistence API (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: apicur.io/v1alpha1
kind: ApicurioRegistry
metadata:
  name: example-apicurioregistry
spec:
  configuration:
    persistence: "jpa"
    dataSource:
      url: "jdbc:postgresql://SERVICE_NAME.NAMESPACE.svc:5432/"
      # e.g. url: "jdbc:postgresql://acid-minimal-cluster.my-project.svc:5432/"
      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