rhoas-cli-service-registry

Getting started with the rhoas CLI for OpenShift Service Registry

Important

The rhoas command-line interface (CLI) 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.

With the rhoas command-line interface (CLI), you can manage OpenShift Service Registry from a terminal.

As a developer of applications and services, you can use rhoas to create Service Registry instances and connect your applications and services to these instances. You can also manage artifacts. Artifacts are items stored in Service Registry, like schemas and API specifications.

This guide describes how to get started quickly by doing the following:

• Create a Service Registry instance

• Create a service account

• Upload Service Registry artifacts

• Download Service Registry artifacts

• Use rhoas to manage your Service Registry instance, service accounts, and artifacts

Prerequisites

• You’ve installed the rhoas CLI. For more information, see Installing the rhoas CLI.

Creating a Service Registry instance

A Service Registry instance serves as a central location for storing artifacts.

Prerequisites

• You are logged in to rhoas.

Procedure

1. Enter the following command to create a Service Registry instance with default values.

   This example creates a Service Registry instance called my-registry.

   Creating a Service Registry instance

   $ rhoas service-registry create --name my-registry
   Creating Service Registry instance with name: my-registry
   ✔️ Successfully created Service Registry instance
   {
     "browserUrl": "https://console.redhat.com/beta/application-services/service-registry/t/63620903-4a29-4ba4-8229-7ab793bf73f3",
     "created_at": "2021-09-27T15:35:01Z",
     "href": "/api/serviceregistry_mgmt/v1/registries/63620903-4a29-4ba4-8229-7ab793bf73f3",
     "id": "63620903-4a29-4ba4-8229-7ab793bf73f3",
     "instance_type": "eval",
     "kind": "ServiceRegistry",
     "name": "my-registry",
     "owner": "User",
     "status": "accepted",
     "updated_at": "2021-09-27T15:35:01Z"
   }

   Note	If you do not want to use the default values, enter the following command: rhoas service-registry create. You will be prompted to enter the Name for the Service Registry instance.

2. Enter the following command to verify that the Service Registry instance is ready to use.

   This command shows that the Service Registry instance is ready to use, because the Status field is ready.

   Reviewing details of a Registry instance

   $ rhoas status service-registry
   
     Service Registry
     -----------------------------------------------------------
     ID:                    63620903-4a29-4ba4-8229-7ab793bf73f3
     Name:                  my-registry
     Status:                ready
     Registry URL:          https://service-registry-service-registry-production.apps.app-sre-prod-04.i5h0.p1.openshiftapps.com/t/63620903-4a29-4ba4-8229-7ab793bf73f3

   Note	When you created the Service Registry instance, it was set as the current instance automatically. If you have multiple Service Registry instances, you can switch to a different instance by using the rhoas service-registry use command.

Creating a service account

To connect your applications or services to a Service Registry instance, you must first create a service account with credentials. The credentials are exported to a file on your computer, which you can use to authenticate your application with your Service Registry instance.

Prerequisites

• You have created a Service Registry instance, and it has a ready status.

Procedure

1. Enter the following command to create a service account.

   This example creates a service account called my-service-acct and saves the credentials in a JSON file.

   Creating a service account

   $ rhoas service-account create --name "my-service-acct" --file-format json
   
   ✔️ Service account "my-service-acct" created successfully with ID "04ba07d6-b08c-45fb-af53-3522c1b4c32f".
   Credentials saved to /home/developer/my-project/credentials.json

   Your service account credentials are created and saved to a JSON file.

   Note	When creating a service account, you can choose the file format and location to save the credentials. For more information, see the rhoas service-account create command help.

2. To verify your service account credentials, view the credentials.json file that you created.

   Verifying service account credentials

   $ cat credentials.json
   {
   	"clientID":"srvc-acct-8c95ca5e1225-94a-41f1-ab97-aacf3df1",
   	"clientSecret":"facf3df1-ab97-2253-aa87-ab97",
           "oauthTokenUrl": "https://identity.api.openshift.com/auth/realms/rhoas/protocol/openid-connect/token"
   }

   You’ll use these credentials and the Service Registry URL to connect your applications and services to your Service Registry instance.

   Note	By connecting your applications to your Service Registry instance, you can retrieve artifacts and use them directly in your service.

Uploading Service Registry artifacts

After creating a Service Registry instance, you can start uploading Service Registry artifacts. Artifacts might include, for example, schemas that define the structure of Kafka data or OpenAPI documents to define an API.

Prerequisites

• You have created a Service Registry instance, and it has a ready status.

Note	You can use rhoas service-registry use to switch to a specific Service Registry instance. Selecting a Service Registry instance to use $ rhoas service-registry use --name my-registry Service Registry instance "my-registry" has been set as the current instance.

Procedure

1. Upload a Service Registry artifact.

   This example uploads a Service Registry artifact called my-artifact to the Service Registry instance. The artifact is an Apache Kafka Avro schema in JSON format.

   Uploading an artifact

   $ wget https://raw.githubusercontent.com/redhat-developer/app-services-cli/main/docs/resources/avro-userInfo.json
   $ rhoas service-registry artifact create --type=AVRO --artifact-id=my-artifact avro-userInfo.json

2. Verify that the artifact was registered.

   This example lists all artifacts belonging to the Service Registry instance.

   Listing artifact details for a Service Registry instance

   $ rhoas service-registry artifact list
   Using default artifacts group.
   
     ID            NAME   CREATED ON                 CREATED BY   TYPE   STATE
    ------------- ------ -------------------------- ------------ ------ --------
     my-artifact          2021-09-27T16:17:35+0000   User         AVRO   ENABLED

3. Check the version and metadata information for the artifact.

   Checking the version information of an artifact

   $ rhoas service-registry artifact versions --artifact-id=my-artifact
   {
     "count": 1,
     "versions": [
       {
         "contentId": 29,
         "createdBy": "User",
         "createdOn": "2021-09-27T16:17:35+0000",
         "globalId": 28,
         "state": "ENABLED",
         "type": "AVRO",
         "version": "1"
       }
     ]
   }

   Checking the metadata information of an artifact

   $ rhoas service-registry artifact metadata-get --artifact-id=my-artifact
   Using default artifacts group.
   Fetching artifact metadata
   ✔️ Successfully fetched artifact metadata
   {
     "contentId": 29,
     "createdBy": "User",
     "createdOn": "2021-09-27T16:17:35+0000",
     "globalId": 28,
     "id": "my-artifact",
     "modifiedBy": "User",
     "modifiedOn": "2021-09-27T16:17:35+0000",
     "state": "ENABLED",
     "type": "AVRO",
     "version": "1"
   }

   Note	You can use additional options, such as --group, --version, and --description, to modify the metadata of the artifact you’re creating. For more information about any of the options, view the command help rhoas service-registry artifact metadata-set -h.

Downloading Service Registry artifacts

After registering Service Registry artifacts, you can download them to make updates.

Prerequisites

• You have created a Service Registry instance with at least one artifact.

Procedure

• Download the artifact by specifying Artifact ID that we specified when creating artifact using CLI

• Download the artifact by specifying Global ID retrieved from Kafka Message payload

  This example downloads the my-artifact artifact using its ID.

  Downloading an artifact using its ID

  $ rhoas service-registry artifact get --artifact-id my-artifact

  This example downloads the my-artifact artifact using its global ID.

  Downloading an artifact using its global ID

  $ rhoas service-registry artifact download --global-id=28

Commands for managing Service Registry

For more information about the rhoas commands you can use to manage your Service Registry instance, use the following command help:

• rhoas service-registry -h for Service Registry instances

• rhoas service-account -h for service accounts

• rhoas service-registry artifact -h for Service Registry artifacts

Additional resources

• CLI command reference (rhoas)