getting-started-service-registry

Getting Started with OpenShift Service Registry

Important

OpenShift Service Registry is currently available for Development Preview. Development Preview releases provide early access to a limited set of features that might not be fully tested and that might change in the final GA version. Users should not use Development Preview software in production or for business-critical workloads. Limited documentation is available for Development Preview releases and is typically focused on fundamental user goals.

As a developer of applications and services, you can use OpenShift Service Registry to create and set up Service Registry instances and connect your applications and services to these instances. Service Registry is a managed cloud service that enables you to manage schema and API definitions in your applications without having to install, configure, run, and maintain your own Service Registry clusters.

For more overview information about Service Registry, see https://access.redhat.com/documentation/en-us/red_hat_openshift_service_registry/.

Creating a Service Registry instance

Use the Application Services web console to create and configure a Service Registry instance for your applications or services. A Service Registry instance is an isolated virtual tenant in a multi-tenanted deployment with its own unique instance URL and configuration to connect to producer and consumer applications.

Prerequisites

• You’re logged in to the Service Registry web console at https://console.redhat.com/beta/application-services/service-registry/.

Procedure

1. In the Application Services web console, go to Service Registry > Service Registry Instances, and click Create Service Registry instance.

2. Enter a unique Instance name, such as my-service-registry-instance. Optionally, you can add a longer text description for this instance.

   

   Figure 1. Create Service Registry instance details

3. Click Create to start the creation process for your Service Registry instance. The new Service Registry instance is listed in the instances table.

4. When the Status is Ready, you can start using this Service Registry instance. You can use the options icon (three vertical dots) to connect to or delete the instance as needed.

Figure 2. Service Registry instance options menu

Verification

1. Verify that the new Service Registry instance is listed in the instances table.

2. Verify that the state of the new Service Registry instance is shown as Ready.

Uploading a schema to Service Registry

After you create a Service Registry instance, you can upload schema or API content to the instance. The following example shows uploading an Apache Avro schema for serializing and deserializing Kafka messages in client applications.

Prerequisites

• You’ve created a Service Registry instance and the instance is in Ready state.

Procedure

1. In the Service Registry instances page of the web console, select the Service Registry instance that you want to upload a schema to.

2. Click Upload artifact and complete the form to define the schema details:

   

   Figure 3. Guided steps to define artifact details

   • Group: Enter an optional unique group name such as my-org to organize the artifact in a named collection. Each group contains a logically related set of schemas or API designs, typically managed by a single entity, belonging to a particular application or organization.

     Note	Specifying a group is optional when using the web console, and a default group is automatically created. When using the REST API or Maven plug-in, you can specify the default group in the API path if you do not want to create a unique group.

   • ID: Enter an optional unique ID for this artifact such as my-ID. If you do not specify a unique artifact ID, Service Registry generates one automatically as a UUID.

   • Type: Use the default Auto-Detect setting to automatically detect the artifact type, or select the artifact type from the drop-down, for example, Avro Schema or OpenAPI.

   • Artifact: Drag and drop or click Browse to upload a file. For this example, copy and paste the following simple Avro schema:

     {
     "type": "record",
     "namespace": "com.example",
     "name": "FullName",
     "fields": [
     { "name": "first", "type": "string" },
     { "name": "last", "type": "string" }
     ]}

3. Click Upload to complete the operation and display the new artifact details:

   • Info: Displays the artifact name, group, description, lifecycle status, when created, and last modified. Click the Edit Artifact Metadata pencil icon to edit the artifact name and description or add labels, or click Download to download the artifact file locally.

   • Content: Displays a read-only view of the full artifact content.

   • Documentation: (OpenAPI only): Displays automatically-generated REST API documentation.

   • Content Rules: Displays artifact content rules that you can enable and configure. You can configure a Validity Rule or Compatibility Rule by selecting the appropriate rule configuration from the drop-down. For details on supported rules, see the OpenShift Service Registry user documentation.

     You can now use this schema to serialize and deserialize messages from Kafka client applications.

4. On the right of the screen, you can click Upload new version to add a new artifact version.

5. You can click Delete to delete an artifact as needed.

   Important

   Deleting an artifact deletes the artifact and all of its versions, and cannot be undone. Artifact versions are immutable and cannot be deleted individually.

Verification

• Verify that the new schema is listed in the Artifacts table.

Connecting client applications to Service Registry

To connect your applications or services to a Service Registry instance in the web console, you must copy and save the Service Registry instance URL, create a service account, and copy and save the generated credentials. You’ll use these details later when you configure your application for Service Registry.

Prerequisites

• You’ve created a Service Registry instance and the instance is in Ready state.

Procedure

1. In the Service Registry instances page of the web console, for the instance that you want to connect to, select the options icon (three vertical dots), and click Connection.

2. Depending on the client libraries that you want to use, chose the API for your needs:

   • Core Registry API is the most powerful and works with Apicurio client libraries

   • Schema Registry compatibility API provides compatibility with the Confluent Schema Registry API

   • CNCF Schema Registry API provides compatibility with the CNCF specification

3. In the Connection page, copy the Core Registry API URL, or one of the other API URLs if you are using a different client, to a secure location. This is the server endpoint that you’ll need to connect to this Service Registry instance.

4. In the web console left menu, go to Service Accounts, and click Create service account to generate the credentials that you can use to connect to Service Registry and Kafka instances.

5. Copy the generated Client ID and Client Secret to a secure location.

   Important

   The generated credentials are displayed only one time. Ensure that you’ve successfully and securely saved the copied credentials before closing the credentials window.

6. After you save the generated credentials to a secure location, select the confirmation check box in the credentials window and close the window.

   You’ll use the details that you saved to configure your applications to connect to your Service Registry instances later when you’re ready.

   For example, if you plan to use Kafkacat to interact with your Kafka instance and deserialize Avro messages using Service Registry, you’ll use this information to set your Service Registry URL in the client environment variables.

Verification

1. Verify that the Service Registry instance URL is saved to a secure location.

2. Verify that the client credentials are saved to a secure location.

Additional resources

• OpenShift Service Registry user documentation

• OpenShift Streams for Apache Kafka user documentation