rhoas-cli-getting-started-registry

Getting started with the rhoas CLI for OpenShift Service Registry

With the OpenShift Application Services 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, such as schemas and API specifications.

You can get started with OpenShift Service Registry by doing the following tasks:

• Create a Service Registry instance

• Create a service account

• Upload Service Registry artifacts

• Download Service Registry artifacts

• Update Service Registry artifacts

• Configure Service Registry rules

• Generating Service Registry configurations

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

Prerequisites

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

Creating a Service Registry instance

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

Prerequisites

• You’re logged in to rhoas.

Procedure

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

   The CLI uses service contexts to group service instances against which commands are executed. The created Service Registry instance is set automatically in the current context.

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

2. Verify that the Service Registry instance is ready to use.

   Reviewing details of a Service Registry instance

   $ rhoas context status service-registry

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

   Note	If you have multiple Service Registry instances, you can change the context to a different instance by using the rhoas context set-service-registry 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’ve created a Service Registry instance, and it has a ready status.

Procedure

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

   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.

   Example credentials.json file

   {
   	"clientID":"<client-id>",
   	"clientSecret":"<client-secret>",
       "oauthTokenUrl": "https://sso.redhat.com/auth/realms/redhat-external/protocol/openid-connect/token"
   }

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

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

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

   Creating a role for the service account

   $ rhoas service-registry role add --role=manager --service-account=<client-id>

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’ve created a Service Registry instance, and it has a ready status.

Note	You can use rhoas context set-service-registry to switch to a specific Service Registry instance. Selecting a Service Registry instance to use $ rhoas context set-service-registry --name=my-registry

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

2. Create the Service Registry artifact from the Avro schema that you uploaded.

   Creating an artifact

   $ rhoas service-registry artifact create --type=AVRO --artifact-id=my-artifact avro-userInfo.json

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

4. Check the version information for the artifact.

   Checking the version information of an artifact

   $ rhoas service-registry artifact versions --artifact-id=my-artifact

5. Check the metadata information for the artifact.

   Checking the metadata information of an artifact

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

   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 you register a Service Registry artifact, you can download the artifact to update it.

Prerequisites

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

Procedure

• Download the artifact in one of the following ways:

  • Use the rhoas service-registry artifact get command and specify the artifact ID.

    Downloading an artifact by using the artifact ID

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

    Note	To find the artifact ID, use the rhoas service-registry artifact list command.

  • Use the rhoas service-registry artifact download command and specify the global ID.

    Downloading an artifact by using the global ID

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

    Note	To find the global ID, see the Kafka message payload.

Note	You can use additional options, such as --group and --instance-id, to specify the artifact to download. For more information about any of the options, view the command help rhoas service-registry artifact download -h and rhoas service-registry artifact get -h.

Updating Service Registry artifacts

You can update an artifact with content from a file or from standard input.

Prerequisites

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

• The type of the updated content is compatible with the current artifact type.

Procedure

1. Update a Service Registry artifact.

   This example updates a Service Registry artifact called my-artifact with content from a file in JSON format.

   Updating an artifact from a file

   $ rhoas service-registry artifact update --artifact-id=my-artifact my-artifact.json

   Note	To update the artifact from standard input, use the rhoas service-registry artifact update --artifact-id=my_artifact command. Paste the updated artifact content on the command line, and then press Ctrl+D to save.

2. Verify that the artifact was updated. The updated artifact is saved as a new version.

   Checking the version number and modified date of an artifact

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

   Note	You can use additional options, such as --group and --version, to specify the artifact to update. For more information about any of the options, view the command help rhoas service-registry artifact update -h.

Configuring Service Registry rules

To prevent invalid content from being added to Service Registry, you can configure optional rules to check the artifact content. Artifact rules apply to the specified artifact only. Global rules apply to all artifacts in a particular Service Registry instance. Configured artifact rules override any configured global rules. Before a new artifact version can be uploaded to the registry, all configured global rules or artifact rules must pass.

Prerequisites

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

Procedure

1. Identify the rule that you want to update.

   To show a list of global rules, run the following command:

   $ rhoas service-registry rule list

   To show a list of artifact rules, specify the artifact ID as shown in the following example:

   $ rhoas service-registry rule list --artifact-id=my-artifact

2. Update the Service Registry rule by specifying the rule type and configuration.

   This example updates the global compatibility rule for all artifacts in the current Service Registry instance:

   $ rhoas service-registry rule update --rule-type=compatibility --config=full

   This example updates the validity rule for a specific artifact:

   $ rhoas service-registry rule update --rule-type=validity --config=full --artifact-id=my-artifact

   Note	For more information about Service Registry rule types and rule maturity, see Supported Service Registry content and rules.

3. Verify that the rule updated correctly.

   This example displays the details of the global compatibility rule:

   $ rhoas service-registry rule describe --rule-type=compatibility

   This example displays the details of the artifact validity rule:

   $ rhoas service-registry rule describe --rule-type=validity --artifact-id=my-artifact

4. Optional: Enable or disable individual rules. When you enable a rule, you must specify the configuration value.

   This example enables the global compatibility rule:

   $ rhoas service-registry rule enable --rule-type=compatibility --config=full

   This example disables the artifact validity rule:

   $ rhoas service-registry rule disable --rule-type=validity --artifact-id=my-artifact

Note	You can use additional options, such as --group and --instance-id, to specify the Service Registry group or instance to which the updated rules apply. For more information about any of the options, view the command help rhoas service-registry rule -h.

Generating configurations for Service Registry instance

After creating a Service Registry instance, you can generate a configuration file that your applications can use to connect to your Service Registry instance.

Prerequisites

• You’ve created a Service Registry instance.

• The Service Registry instance is set in the current context.

• Your user account and org have quota for creating service accounts.

Procedure

• Generate a configuration file for the current service context.

  This example generates a JSON file with configurations for the Service Registry instance.

  Generating a configuration file

  $ rhoas generate-config --type json

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)