Installing Apicurio Registry storage on OpenShift
This chapter explains how to install and configure your chosen registry storage option:
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 Understanding OperatorHub.
-
You must have cluster administrator access to an OpenShift cluster
-
In the OpenShift Container Platform web console, log in using an account with cluster administrator privileges.
-
Change to the OpenShift project in which you want to install Strimzi. For example, from the Project drop-down, select
my-project
. -
In the left navigation menu, click Operators and then OperatorHub.
-
In the Filter by keyword text box, enter
Strimzi
to find the Strimzi Operator. -
Read the information about the Operator, and click Install to display the Operator subscription page.
-
Select your subscription settings, for example:
-
Update Channel and then stable
-
Installation Mode: Select one of the following:
-
All namespaces on the cluster (default)
-
A specific namespace on the cluster > my-project
-
-
Approval Strategy: Select Automatic or Manual
-
-
Click Install, and wait a few moments until the Operator is ready for use.
Configuring Apicurio Registry with Kafka storage on OpenShift
This section explains how to configure Kafka-based storage for Apicurio Registry using Strimzi on OpenShift. The kafkasql
storage option uses Kafka storage with an in-memory H2 database for caching. 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.
-
You must have an OpenShift cluster with cluster administrator access.
-
You must have already installed Apicurio Registry. See Installing Apicurio Registry on OpenShift.
-
You must have already installed Strimzi. See Installing Strimzi from the OpenShift OperatorHub.
-
In the OpenShift Container Platform web console, log in using an account with cluster administrator privileges.
-
If you do not already have a Kafka cluster configured, create a new Kafka cluster using Strimzi. For example, in the OpenShift OperatorHub:
-
Click Installed Operators and then Strimzi.
-
Under Provided APIs and then Kafka, click Create Instance to create a new Kafka cluster.
-
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 Deploying and Upgrading AMQ Streams on OpenShift.
-
-
After the cluster is ready, click Provided APIs > Kafka > my-cluster > YAML.
-
In the
status
block, make a copy of thebootstrapServers
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 ...
-
Click Installed Operators > Service Registry > ApicurioRegistry > Create ApicurioRegistry.
-
Paste in the following custom resource definition, but use your
bootstrapServers
value that you copied earlier:apiVersion: registry.apicur.io/v1 kind: ApicurioRegistry metadata: name: example-apicurioregistry-kafkasql spec: configuration: persistence: 'kafkasql' kafkasql: bootstrapServers: 'my-cluster-kafka-bootstrap.my-project.svc:9092'
-
Click Create and wait for the Apicurio Registry route to be created on OpenShift.
-
Click Networking > Route to access the new route for the Apicurio Registry web console. For example:
http://example-apicurioregistry-kafkasql.my-project.my-domain-name.com/
-
To configure the Kafka topic that Apicurio Registry uses to store data, click Installed Operators > Strimzi > Provided APIs > Kafka Topic > kafkasql-journal > YAML. For example:
apiVersion: kafka.strimzi.io/v1beta2 kind: KafkaTopic metadata: name: kafkasql-journal labels: strimzi.io/cluster: my-cluster namespace: ... spec: partitions: 3 replicas: 3 config: cleanup.policy: compact
You must configure the Kafka topic used by Apicurio Registry (named kafkasql-journal
by default) with a compaction cleanup policy, otherwise a data loss might occur.
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 name that Apicurio Registry uses to store data is kafkasql-journal
. This topic is created automatically by Apicurio Registry. However, you can override this behavior or the default topic name by setting the appropriate environment variable or Java system property:
Environment variable | Java system property | Default value |
---|---|---|
|
|
|
|
|
|
Configuring OAuth authentication for Kafka storage
When using Kafka-based storage in Strimzi, Apicurio Registry supports accessing a Kafka cluster that requires OAuth authentication. To enable this support, you must to set some environment variables in your Apicurio Registry deployment.
When you set these environment variables, the Kafka producer and consumer applications in Apicurio Registry will use this configuration to authenticate to the Kafka cluster over OAuth.
-
You must have already configured Kafka-based storage of Apicurio Registry data in Strimzi. See Configuring Apicurio Registry with Kafka storage on OpenShift.
-
Set the following environment variables in your Apicurio Registry deployment:
Environment variable Description Default value ENABLE_KAFKA_SASL
Enables SASL OAuth authentication for Apicurio Registry storage in Kafka. You must set this variable to
true
for the other variables to have effect.false
CLIENT_ID
The client ID used to authenticate to Kafka.
-
CLIENT_SECRET
The client secret used to authenticate to Kafka.
-
OAUTH_TOKEN_ENDPOINT_URI
The URL of the OAuth identity server.
http://localhost:8090
-
For an example of how to set Apicurio Registry environment variables on OpenShift, see Configuring Apicurio Registry health checks on OpenShift in Configuring your Apicurio Registry deployment
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 Understanding OperatorHub.
-
You must have cluster administrator access to an OpenShift cluster.
-
In the OpenShift Container Platform web console, log in using an account with cluster administrator privileges.
-
Change to the OpenShift project in which you want to install the PostgreSQL Operator. For example, from the Project drop-down, select
my-project
. -
In the left navigation menu, click Operators and then OperatorHub.
-
In the Filter by keyword text box, enter
PostgreSQL
to find an Operator suitable for your environment, for example, Crunchy PostgreSQL for OpenShift. -
Read the information about the Operator, and click Install to display the Operator subscription page.
-
Select your subscription settings, for example:
-
Update Channel: stable
-
Installation Mode: A specific namespace on the cluster and then my-project
-
Approval Strategy: Select Automatic or Manual
-
-
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 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.
-
You must have an OpenShift cluster with cluster administrator access.
-
You must have already installed Apicurio Registry. See Installing Apicurio Registry on OpenShift.
-
You must have already installed a PostgreSQL Operator on OpenShift. For example, see Installing a PostgreSQL database from the OpenShift OperatorHub.
-
In the OpenShift Container Platform web console, log in using an account with cluster administrator privileges.
-
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
. -
Create a PostgreSQL database for your Apicurio Registry storage. For example, click Installed Operators, PostgreSQL Operator by Dev4Ddevs.com, and then Create database.
-
Click YAML and edit the database settings as follows:
-
name
: Change the value toregistry
-
image
: Change the value tocentos/postgresql-12-centos7
-
-
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-12-centos7 size: 1
-
Click Create, and wait until the database is created.
-
Click Installed Operators > Apicurio Registry > ApicurioRegistry > Create ApicurioRegistry.
-
Paste in the following custom resource definition, 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>' # e.g. url: 'jdbc:postgresql://acid-minimal-cluster.my-project.svc:5432/registry' userName: 'postgres' password: '<password>' # Optional
-
Click Create and wait for the Apicurio Registry route to be created on OpenShift.
-
Click Networking > Route to access the new route for the Apicurio Registry web console. For example:
http://example-apicurioregistry-sql.my-project.my-domain-name.com/