Apicurio Studio

Installing Apicurio Registry storage on OpenShift

Installing Strimzi from the OpenShift OperatorHub

If you do not already have Strimzi installed, you can install the Strimzi Operator on your OpenShift cluster from the OperatorHub. The OperatorHub is available from the OpenShift Container Platform web console and provides an interface for cluster administrators to discover and install Operators. For more details, see the OpenShift documentation.

Prerequisites
  • You must have cluster administrator access to an OpenShift cluster

Procedure
  1. In the OpenShift Container Platform web console, log in using an account 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. In the left navigation menu, click Operators > OperatorHub.

  4. In the Filter by keyword text box, enter Strimzi to find the Strimzi Operator.

  5. Read the information about the Operator, and click Install to display the Operator subscription page.

  6. Select your subscription settings, for example:

    • Update Channel > stable

    • Installation Mode > A specific namespace on the cluster > my-project

    • Approval Strategy > Manual

  7. Click Install, and wait a few moments until the Operator is ready for use.

Configuring Apicurio Registry with Strimzi storage on OpenShift

This section explains how to configure Kafka-based storage for Apicurio Registry using Strimzi on OpenShift. This storage option is suitable for production environments when persistent storage is configured for the Kafka cluster on OpenShift. You can install Apicurio Registry in an existing Kafka cluster or create a new Kafka cluster, depending on your environment.

Prerequisites
Procedure
  1. In the OpenShift Container Platform web console, log in using an account with cluster administrator privileges.

  2. If you do not already have a Kafka cluster configured, create a new Kafka cluster using Strimzi. For example, in the OpenShift OperatorHub:

    1. Click Installed Operators > Strimzi.

    2. Under Provided APIs > Kafka, click Create Instance to create a new Kafka cluster.

    3. Edit the custom resource definition as appropriate, and click Create.

      The default example creates a cluster with 3 Zookeeper nodes and 3 Kafka nodes with ephemeral storage. This temporary storage is suitable for development and testing only, and not for production. For more details, see Using AMQ Streams on OpenShift.
  3. After the cluster is ready, click Provided APIs > Kafka > my-cluster > YAML.

  4. In the status block, make a copy of the bootstrapServers value, which you will use later to deploy Apicurio Registry. For example:

    status:
      conditions:
      ...
      listeners:
        - addresses:
            - host: my-cluster-kafka-bootstrap.my-project.svc
              port: 9092
          bootstrapServers: 'my-cluster-kafka-bootstrap.my-project.svc:9092'
          type: plain
      ...
  5. Create a Kafka topic to store the Apicurio Registry artifacts:

    1. Under Provided APIs > Kafka Topic, click Create topic.

    2. Change the default topic name from my-topic to the required storage-topic.

  6. Create a Kafka topic to store the Apicurio Registry global IDs:

    1. Under Provided APIs > Kafka Topic, click Create topic.

    2. Change the default topic name from my-topic to the required global-id-topic.

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

  8. Paste in the following custom resource definition, but use your bootstrapServers value that you copied earlier:

    apiVersion: apicur.io/v1alpha1
    kind: ApicurioRegistry
    metadata:
      name: example-apicurioregistry
    spec:
      configuration:
        persistence: "streams"
        streams:
          bootstrapServers: "my-cluster-kafka-bootstrap.my-project.svc:9092"
  9. Click Create and wait for the Apicurio Registry route to be created on OpenShift.

  10. Click Networking > Route to access the new route for the Apicurio Registry web console. For example:

    http://example-apicurioregistry.my-project.my-domain-name.com/
Additional resources

For more details on installing Strimzi and on creating Kafka clusters and topics, see https://strimzi.io/docs/overview/latest/

Kafka topic name configuration

The default Kafka topic names that Apicurio Registry uses to store data in Kafka are storage-topic and global-id-topic. You might be required to change these topic names if you are sharing your Kafka cluster with other applications that already use topics named storage-topic or global-id-topic.

You can override the default topic names by setting the appropriate environment variables or Java system properties:

Table 1. Kafka topic name configuration
Default topic name Environment variable Java system property

storage-topic

REGISTRY_STREAMS_TOPOLOGY_STORAGE_TOPIC

registry.streams.topology.storage.topic

global-id-topic

REGISTRY_STREAMS_TOPOLOGY_GLOBAL_ID_TOPIC

registry.streams.topology.global.id.topic

Configuring Apicurio Registry with embedded Infinispan storage on OpenShift

This section explains how to configure Infinispan cache-based storage for Apicurio Registry on OpenShift. This storage option is based on Infinispan community Java libraries embedded in the Quarkus-based Apicurio Registry server. You do not need to install a separate Infinispan server using this storage option. This option is suitable for development or demonstration only, and is not suitable for production environments.

Prerequisites
Procedure
  1. In the OpenShift Container Platform web console, log in using an account with cluster administrator privileges.

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

  3. Paste in the following custom resource definition:

    apiVersion: apicur.io/v1alpha1
    kind: ApicurioRegistry
    metadata:
      name: example-apicurioregistry
    spec:
      configuration:
        persistence: "infinispan"
        infinispan: # Currently uses embedded version of Infinispan
          clusterName: "example-apicurioregistry"
          # ^ Optional
  4. Click Create and wait for the Apicurio Registry route to be created on OpenShift.

  5. Click Networking > Route to access the new route for the Apicurio Registry web console. For example:

    http://example-apicurioregistry.my-project.my-domain-name.com/
Additional resources

Installing a PostgreSQL database from the OpenShift OperatorHub

If you do not already have a PostgreSQL database Operator installed, you can install a PostgreSQL Operator on your OpenShift cluster from the OperatorHub. The OperatorHub is available from the OpenShift Container Platform web console and provides an interface for cluster administrators to discover and install Operators. For more details, see the OpenShift documentation.

Prerequisites
  • You must have cluster administrator access to an OpenShift cluster.

Procedure
  1. In the OpenShift Container Platform web console, log in using an account 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. In the left navigation menu, click Operators > OperatorHub.

  4. In the Filter by keyword text box, enter PostgreSQL to find an Operator suitable for your environment, for example, Crunchy PostgreSQL for OpenShift or PostgreSQL Operator by Dev4Ddevs.com.

  5. Read the information about the Operator, and click Install to display the Operator subscription page.

  6. Select your subscription settings, for example:

    • Update Channel > stable

    • Installation Mode > A specific namespace on the cluster > my-project

    • Approval Strategy > Manual

  7. Click Install, and wait a few moments until the Operator is ready for use.

    You must read the documentation from your chosen PostgreSQL Operator for details on how to create and manage your database.

Configuring Apicurio Registry with PostgreSQL database storage on OpenShift

This section explains how to configure Java Persistence API-based storage for Apicurio Registry on OpenShift using a PostgreSQL database Operator. You can install Apicurio Registry in an existing database or create a new database, depending on your environment. This section shows a simple example using the PostgreSQL Operator by Dev4Ddevs.com.

Prerequisites
Procedure
  1. In the OpenShift Container Platform web console, log in using an account 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. Create a PostgreSQL database for your Apicurio Registry storage. For example, click Installed Operators > PostgreSQL Operator by Dev4Ddevs.com > Create database > YAML.

  4. Edit the database settings as follows:

    • name: Change the value to registry

    • image: Change the value to centos/postgresql-10-centos7

  5. Edit any other database settings as needed depending on your environment, for example:

    apiVersion: postgresql.dev4devs.com/v1alpha1
    kind: Database
    metadata:
      name: registry
      namespace: my-project
    spec:
      databaseCpu: 30m
      databaseCpuLimit: 60m
      databaseMemoryLimit: 512Mi
      databaseMemoryRequest: 128Mi
      databaseName: example
      databaseNameKeyEnvVar: POSTGRESQL_DATABASE
      databasePassword: postgres
      databasePasswordKeyEnvVar: POSTGRESQL_PASSWORD
      databaseStorageRequest: 1Gi
      databaseUser: postgres
      databaseUserKeyEnvVar: POSTGRESQL_USER
      image: centos/postgresql-10-centos7
      size: 1
  6. Click Create Database, and wait until the database is created.

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

  8. Paste in the following custom resource definition, 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
  9. Click Create and wait for the Apicurio Registry route to be created on OpenShift.

  10. Click Networking > Route to access the new route for the Apicurio Registry web console. For example:

    http://example-apicurioregistry.my-project.my-domain-name.com/