Getting Started with Red Hat OpenShift Service Registry

Guide
  • Red Hat OpenShift Service Registry 1
  • Updated 02 December 2021
  • Published 24 September 2021

Getting Started with Red Hat OpenShift Service Registry

Guide
Red Hat OpenShift Service Registry 1
  • Updated 02 December 2021
  • Published 24 September 2021

As a developer of applications and services, you can use Red Hat 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 the product documentation for Red Hat OpenShift Service Registry.

Prerequisites
  • You have a Red Hat account.

  • You have a subscription to Red Hat OpenShift Streams for Apache Kafka.

Creating a Service Registry instance

Use the Red Hat OpenShift Streams for Apache Kafka 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
Procedure
  1. In the Service Registry 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.

  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 client applications or to delete the instance as needed.

Image of Service Registry instance options menu
Figure 1. 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:

    Image of form to upload a schema
    Figure 2. 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.

      Specifying a group is optional when using the web console. If you do not specify a group, a default group is automatically created.
    • 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.

    • 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 Red Hat 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.

    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. Under Service Accounts, click Create service account to generate the credentials that you can use to connect applications to Service Registry and Kafka instances.

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

    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.

  7. For the Authentication method, copy the OAuth Token endpoint URL to a secure location. This is the endpoint that you’ll use with your service account credentials to authenticate the connection to this Service Registry instance.

    HTTP Basic authentication is also available for tools and libraries that don’t support OAuth, but OAuth is recommended whenever possible. With HTTP Basic, you use only the service account credentials to authenticate the connection to the Service Registry instance.

    You’ll use the service account information 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.

    For details on granting access to service accounts and user accounts, see Managing account access in Red Hat OpenShift Service Registry.
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