getting-started-registry

Getting started with OpenShift Service Registry

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. OpenShift 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, see the OpenShift Service Registry user documentation.

Creating a Service Registry instance

Use the OpenShift Service Registry 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/application-services/service-registry/.

Procedure

1. In the Service Registry web console, 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 on the Service Registry Instances page.

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 1. Service Registry instance options menu

Note	You can see all Service Registry instances created by other users in your organization, but you might not have permission to connect to those instances. Only instance owners or users with permission can connect to the instance, access associated service accounts, or delete the instance.

Verification

1. Verify that the new Service Registry instance is listed on the Service Registry Instances page.

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

Uploading a schema or API to Service Registry

After you create a Service Registry instance, you can upload schema or API content to the instance. The following examples show how to upload a simple Apache Avro schema file for serializing and deserializing Kafka messages in client applications, and how to upload the Petstore sample API from an HTTPS URL.

Note	Uploading an artifact from an HTTP URL is not supported for security reasons.

Prerequisites

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

Procedure

1. On the Service Registry Instances page of the web console, select the Service Registry instance that you want to upload the artifact to.

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

   

   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.

     Note	Specifying a group is optional when using the web console, and 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 list, for example, Avro Schema or OpenAPI.

   • Artifact: Specify the artifact location using either of the following options:

     • From file: Click Browse, and select a file, or drag and drop a file. Alternatively, enter the file contents in the text box. For 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"
           }
         ]
       }

     • From URL: Enter a valid and accessible HTTPS URL, and click Fetch. For example: https://petstore3.swagger.io/api/v3/openapi.json.

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

   • Overview tab:

     • Version metadata: Displays details such as the artifact name, artifact ID, global ID, content ID, labels, properties, and so on.

     • Content rules: Displays artifact content rules that you can enable and configure. You can configure a Validity rule or Compatibility rule by enabling the rule and then selecting the appropriate rule configuration from the list. For details on supported rules, see Supported Service Registry content and rules.

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

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

   You can now use this schema or API artifact with your client applications.

4. 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.

6. To show the list of artifacts on the Artifacts tab, click the instance-name breadcrumb.

Verification

• Verify that the new artifact is listed on the Artifacts tab.

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. On 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, choose the API for your needs:

   • Core Registry API is the most powerful API 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. On 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. You’ll use this server endpoint to connect to this Service Registry instance.

   The remainder of this section describes how to create a service account and copy the generated credentials. If you want to use the credentials of an existing service account, you can skip to the next section.

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.

   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.

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

   Note	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 kcat 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.

   To review your service account information, reset your credentials, or delete the service account, use the left navigation menu to go to the Service Accounts page.

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.

3. Verify that your service account was successfully created on the Service Accounts page.

Assigning a role for a service account to access a Service Registry instance

After you create a service account for applications to connect to a Service Registry instance, you must also set the appropriate level of access for the new account on the Access tab of the Service Registry instance. Service Registry uses role-based access to enable you to manage how other user accounts and service accounts can interact with the Service Registry instance that you create.

Prerequisites

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

• You’ve created a service account that you want to allow to access the running Service Registry instance.

Procedure

1. On the Service Registry Instances page of the web console, click the name of the Service Registry instance that you want the service account to access.

2. Click the Access tab to view the accounts and roles already assigned for this instance.

3. Click Grant access to assign a role to the service account.

4. In the Account field, select or enter the service account name that you want to assign the role to.

5. Select the Role that you want to assign to the account, for example, Manager for write access to this instance.

6. Click Save to finish.

Verification

• Verify that the new role for the service account is listed on the Access page of the Service Registry instance.

Additional resources

• Managing account access in OpenShift Service Registry

• OpenShift Service Registry user documentation

• OpenShift Streams for Apache Kafka user documentation