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.

  • Apache Kafka (Kafka + SQL) - data is stored using Apache Kafka, with the help of local SQL database on each node.

  • SQL (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

  • SQL (PostgreSQL)

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/v1.0.0/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 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 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/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 that Apicurio Registry uses to store data is kafkasql-journal. This topic is created automatically by Apicurio Registry. You can override this behavior or the default topic name by setting the appropriate environment variables (default values):

    • 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:
        retention.ms: 604800000
        segment.bytes: 1073741824
  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 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/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 that Apicurio Registry uses to store data is kafkasql-journal. This topic is created automatically by Apicurio Registry. You can override this behavior or the default topic name by setting the appropriate environment variables (default values):

    • 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:
        retention.ms: 604800000
        segment.bytes: 1073741824
  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
    You must configure the authorization specifically for the topics and resources that the Apicurio Registry requires. This is a simple permissive example.
  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
    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 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/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 that Apicurio Registry uses to store data is kafkasql-journal. This topic is created automatically by Apicurio Registry. You can override this behavior or the default topic name by setting the appropriate environment variables (default values):

    • 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:
        retention.ms: 604800000
        segment.bytes: 1073741824
  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
    You must configure the authorization specifically for the topics and resources that the Apicurio Registry requires. This is a simple permissive example.
  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
    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.

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.