Getting started with the rhoas CLI for OpenShift Service Registry

Guide
  • Red Hat OpenShift Service Registry 1
  • Updated 02 December 2021
  • Published 14 October 2021

Getting started with the rhoas CLI for OpenShift Service Registry

Guide
Red Hat OpenShift Service Registry 1
  • Updated 02 December 2021
  • Published 14 October 2021

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:

Prerequisites

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"
    }

    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 Service 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

    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 and saves the credentials in a JSON file.

    Creating a service account
    $ rhoas service-account create --short-description="rhoas-service-account" --file-format json
    
    ✔️ Service account 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.

    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.

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

  3. Create a role for the new service account that can read and write artifacts.

    This example creates a role called DEVELOPER for the service account.

    Creating a role for the service account
    $ rhoas service-registry role add --role DEVELOPER --service-account=srvc-acct-8c95ca5e1225-94a-41f1-ab97-aacf3df1

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.

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"
    }

    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