Chapter 3. Deploying Apicurio Registry storage in AMQ Streams This chapter explains how to install and configure Apicurio Registry data storage in AMQ Streams. Section 3.1, "Installing AMQ Streams from the OpenShift OperatorHub" Section 3.2, "Configuring Apicurio Registry with Kafka storage on OpenShift" Section 3.3, "Configuring Kafka storage with TLS security" Section 3.4, "Configuring Kafka storage with SCRAM security" Section 3.5, "Configuring OAuth authentication for Kafka storage" Prerequisites Chapter 2, Installing Apicurio Registry on OpenShift 3.1. Installing AMQ Streams from the OpenShift OperatorHub If you do not already have AMQ Streams installed, you can install the AMQ Streams 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 . Prerequisites You must have cluster administrator access to an OpenShift cluster See Deploying and Managing AMQ Streams on OpenShift for detailed information on installing AMQ Streams. This section shows a simple example of installing using the OpenShift OperatorHub. Procedure 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 AMQ Streams. 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 AMQ Streams to find the Red Hat Integration - AMQ Streams 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 amq-streams-2.6.x 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. Additional resources Adding Operators to an OpenShift cluster Deploying and Managing AMQ Streams on OpenShift 3.2. Configuring Apicurio Registry with Kafka storage on OpenShift This section explains how to configure Kafka-based storage for Apicurio Registry using AMQ Streams 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. Prerequisites You must have an OpenShift cluster with cluster administrator access. You must have already installed Apicurio Registry. See Chapter 2, Installing Apicurio Registry on OpenShift . You must have already installed AMQ Streams. See Section 3.1, "Installing AMQ Streams from the OpenShift OperatorHub" . Procedure 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 AMQ Streams. For example, in the OpenShift OperatorHub: Click Installed Operators and then Red Hat Integration - AMQ Streams . 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 . Warning 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 Managing AMQ Streams on OpenShift . After the cluster is ready, click Provided APIs > Kafka > my-cluster > YAML . 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 ... Click Installed Operators > Red Hat Integration - 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: To configure the Kafka topic that Apicurio Registry uses to store data, click Installed Operators > Red Hat Integration - AMQ Streams > 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 Warning 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. Additional resources For more details on creating Kafka clusters and topics using AMQ Streams, see Deploying and Managing AMQ Streams on OpenShift . 3.3. Configuring Kafka storage with TLS security You can configure the AMQ Streams 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 AMQ Streams Operator or have Kafka accessible from your OpenShift cluster. Note This section assumes that the AMQ Streams 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 In the OpenShift web console, click Installed Operators , select the AMQ Streams Operator details, and then the Kafka tab. Click Create Kafka to provision a new Kafka cluster for Apicurio Registry storage. 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 step. 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 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 Note 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 Click Workloads and then Secrets to find two secrets that AMQ Streams 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 Note The name of the secret can vary based on your cluster or user name. 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 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 Important 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. 3.4. Configuring Kafka storage with SCRAM security You can configure the AMQ Streams 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 AMQ Streams Operator or have Kafka accessible from your OpenShift cluster. Note This section assumes that AMQ Streams 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 In the OpenShift web console, click Installed Operators , select the AMQ Streams Operator details, and then the Kafka tab. Click Create Kafka to provision a new Kafka cluster for Apicurio Registry storage. 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 step. 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 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 Note 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 Click Workloads and then Secrets to find two secrets that AMQ Streams 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 Note The name of the secret can vary based on your cluster or user name. 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 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 Important 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. 3.5. Configuring OAuth authentication for Kafka storage When using Kafka-based storage in AMQ Streams, 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. Prerequisites You must have already configured Kafka-based storage of Apicurio Registry data in AMQ Streams. See Section 3.2, "Configuring Apicurio Registry with Kafka storage on OpenShift" . Procedure 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 Additional resources For an example of how to set Apicurio Registry environment variables on OpenShift, see Section 6.1, "Configuring Apicurio Registry health checks on OpenShift"

Commands:
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
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'
http://example-apicurioregistry-kafkasql.my-project.my-domain-name.com/
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
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
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
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
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
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
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
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
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
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
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