Getting Started with Service Registry

Procedure

1. If you do not already have AMQ Streams installed, install AMQ Streams on your OpenShift cluster. For example, enter the following command from your AMQ Streams download directory:

   oc apply -f install/cluster-operator/

2. If you do not already have a Kafka cluster set up, create a new Kafka cluster with AMQ Streams. For example:

   $ cat << EOF | oc create -f -
   apiVersion: kafka.strimzi.io/v1beta1
   kind: Kafka
   metadata:
    name: my-cluster
   spec:
    kafka:
      replicas: 3
      listeners:
        external:
          type: route
      storage:
        type: ephemeral
    zookeeper:
      replicas: 3
      storage:
        type: ephemeral
    entityOperator:
      topicOperator: {}
   EOF

   This simple example creates a cluster with 3 Zookeeper nodes and 3 Kafka nodes using ephemeral storage. All data is lost when the Pods are no longer running on OpenShift.

3. Create the required storage-topic to store Service Registry artifacts in AMQ Streams. For example:

   $ cat << EOF | oc create -f -
   apiVersion: kafka.strimzi.io/v1beta1
   kind: KafkaTopic
   metadata:
     name: storage-topic
     labels:
       strimzi.io/cluster: my-cluster
   spec:
     partitions: 3
     replicas: 3
     config:
       cleanup.policy: compact
   EOF

4. Create the required global-id-topic to store Service Registry global IDs in AMQ Streams. For example:

   $ cat << EOF | oc create -f -
   apiVersion: kafka.strimzi.io/v1beta1
   kind: KafkaTopic
   metadata:
     name: global-id-topic
     labels:
       strimzi.io/cluster: my-cluster
   spec:
     partitions: 3
     replicas: 3
     config:
       cleanup.policy: compact
   EOF

Procedure

1. Get the Service Registry OpenShift template.

2. Enter the following command to get the name of the Kafka bootstrap service running in AMQ Streams on your OpenShift cluster:

   $ oc get services | grep .*kafka-bootstrap

3. Create a new OpenShift application using the oc new-app command. For example:

   $ oc new-app service-registry-template.yml \
      -p KAFKA_BOOTSTRAP_SERVERS=my-cluster-kafka-bootstrap:9092 \
      -p REGISTRY_ROUTE=my-cluster-service-registry-myproject.example.com \
      -p APPLICATION_ID=my-kafka-streams-app

   You must specify the following arguments:

   • service-registry-template.yml: The OpenShift template file for Service Registry.
   • KAFKA_BOOTSTRAP_SERVERS: The name of the Kafka bootstrap service on your OpenShift cluster, followed by the Kafka broker port. For example: my-cluster-kafka-bootstrap:9092.
   • REGISTRY_ROUTE: The name of the OpenShift route to expose Service Registry, which is based on your OpenShift cluster environment. For example: my-cluster-service-registry-myproject.example.com.

   • APPLICATION_ID: The name of your AMQ Streams application. For example: my-kafka-streams-app.

     You can also specify the following environment variables using the -e option:

   • APPLICATION_SERVER_HOST: The IP address of your Kafka Streams application server host, which is required in a multi-node Kafka configuration. Defaults to $(POD_IP).
   • APPLICATION_SERVER_PORT: The port number of your Kafka Streams application server, which is required in a multi-node Kafka configuration. Defaults to 9000.

4. Verify the command output when complete. For example:

   Deploying template "myproject/service-registry" for "service-registry-template.yml" to project myproject
   
    service-registry
    ---------
    Congratulations on deploying Service Registry into OpenShift!
   
    All components have been deployed and configured.
   
     * With parameters:
       * Registry Route Name=my-cluster-service-registry-myproject.example.com
       * Registry Max Memory Limit=1300Mi
       * Registry Memory Requests=600Mi
       * Registry Max CPU Limit=1
       * Registry CPU Requests=100m
       * Kafka Bootstrap Servers=my-cluster-kafka-bootstrap:9092
       * Kafka Application ID=my-kafka-streams-app
   
   --> Creating resources ...
       imagestream.image.openshift.io "registry" created
       service "service-registry" created
       deploymentconfig.apps.openshift.io "service-registry" created
       route.route.openshift.io "service-registry" created
   --> Success
       Access your application via route 'my-cluster-service-registry-myproject.example.com'

5. Enter oc status to view your Service Registry installation on OpenShift.

Procedure

1. Create an artifact in the registry using the /artifacts operation. The following example curl command creates a simple artifact for a share price application:

   $ curl -X POST -H "Content-type: application/json; artifactType=AVRO" -H "X-Registry-ArtifactId: share-price" --data '{"type":"record","name":"price","namespace":"com.example","fields":[{"name":"symbol","type":"string"},{"name":"price","type":"string"}]}' http://MY-REGISTRY-HOST/artifacts

   This example shows creating an Avro schema artifact with an artifact ID of share-price.

   MY-REGISTRY-HOST is the host name on which Service Registry is deployed. For example: my-cluster-service-registry-myproject.example.com.

2. Verify that the response includes the expected JSON body to confirm that the artifact was created. For example:

   {"createdOn":1578310374517,"modifiedOn":1578310374517,"id":"share-price","version":1,"type":"AVRO","globalId":8}

3. Retrieve the artifact from the registry using its artifact ID. For example, in this case the specified ID is share-price:

   $ curl https://MY-REGISTRY-URL/artifacts/share-price
   '{"type":"record","name":"price","namespace":"com.example","fields":[{"name":"symbol","type":"string"},{"name":"price","type":"string"}]}

Procedure

1. Update your Maven pom.xml file to use the apicurio-registry-maven-plugin to upload an artifact. The following example shows registering an Apache Avro schema artifact:

   <plugin>
   <groupId>io.apicurio</groupId>
   <artifactId>apicurio-registry-maven-plugin</artifactId>
   <version>${registry.version}</version>
   <executions>
     <execution>
       <phase>generate-sources</phase>
       <goals>
         <goal>register</goal> 1
       </goals>
       <configuration>
         <registryUrl>https://my-cluster-service-registry-myproject.example.com</registryUrl> 2
         <artifactType>AVRO</artifactType>
         <artifacts>
           <schema1>${project.basedir}/schemas/schema1.avsc</schema1> 3
         </artifacts>
       </configuration>
     </execution>
   </executions>
   </plugin>

   1

   Specify register as the execution goal to upload an artifact to the registry.

   2

   You must specify the Service Registry URL.

   3

   You can upload multiple artifacts using the artifact ID and location.

2. You can also update your Maven pom.xml file to download a previously registered artifact:

   <plugin>
   <groupId>io.apicurio</groupId>
   <artifactId>apicurio-registry-maven-plugin</artifactId>
   <version>${registry.version}</version>
   <executions>
     <execution>
       <phase>generate-sources</phase>
       <goals>
         <goal>download</goal> 1
       </goals>
       <configuration>
         <registryUrl>https://my-cluster-service-registry-myproject.example.com</registryUrl> 2
             <ids>
               <param1>schema1</param1> 3
             </ids>
         <outputDirectory>${project.build.directory}</outputDirectory>
      </configuration>
    </execution>
   </executions>
   </plugin>

   1

   Specify download as the execution goal.

   2

   You must specify the Service Registry URL.

   3

   You can download multiple artifacts to a specified directory using the artifact ID.