rhoas-cli-getting-started-registry

Managing Service Registry by using the OpenShift Application Services CLI

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.

Prerequisites

• You’ve installed the rhoas CLI. For more information, see Installing and configuring the OpenShift Application Services 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 current context is automatically updated so that the created Service Registry instance is set as the current instance.

   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 and optional Description for the Service Registry instance.

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

   Reviewing the Service Registry instance details

   $ rhoas context status service-registry

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

   Note	By default, many of the rhoas commands provide output in JSON format. You can use the -o option to specify a different output format. For more information, see Commands for managing Service Registry.

Specifying the default Service Registry instance

If you have multiple Service Registry instances, you can configure a default Service Registry instance.

Prerequisites

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

Procedure

1. Configure the default Service Registry instance in one of the following ways:

   • Use the rhoas context set-service-registry command:

     Selecting a Service Registry instance into the current context

     $ rhoas context set-service-registry --name=my-registry

   • Use the rhoas service-registry use command:

     Selecting a Service Registry instance to use

     $ rhoas service-registry use --name=my-registry

     Note	You can run the rhoas service-registry use command without specifying the instance name, and then select the instance name from the generated list of instances.

2. Verify that the specified Service Registry instance is set as the default instance.

   Reviewing the details of the default Service Registry instance

   $ rhoas context status service-registry

   This command shows the name of the default Service Registry instance for all rhoas service-registry commands.

   Note	You can override the default value by specifying a different target instance in the rhoas service-registry commands.

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, run the rhoas service-account create -h command to view the 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>

   Note	For more information about the different roles, run the rhoas service-registry role -h command to view the command help.

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 a REST API.

Prerequisites

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

• Your Service Registry instance is the default instance, as described in Specifying the default Service Registry instance.

Procedure

1. Upload the artifact in one of the following ways:

   • Upload the artifact from a file:

     1. Download an example schema.

        This example downloads an Apache Avro schema in JSON format.

        Downloading an example schema

        $ wget https://raw.githubusercontent.com/redhat-developer/app-services-cli/main/docs/resources/avro-userInfo.json

     2. Upload the schema as a Service Registry artifact.

        This example creates a Service Registry artifact called my-artifact from the Avro schema that you downloaded in the previous step, and uploads the artifact to the Service Registry instance.

        Creating and uploading an artifact from a file

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

   • Upload the artifact directly from a URL:

     Creating and uploading an artifact from a URL

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

2. Verify that the artifact was registered.

   This example lists all artifacts in the default group for the Service Registry instance.

   Listing artifact details for a Service Registry instance

   $ rhoas service-registry artifact list

   Note	You can use the -a option to list all artifacts in all groups for the Service Registry instance.

3. Check the version information for the artifact.

   This example lists information about each version of the artifact.

   Checking the version information of an artifact

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

4. Check the metadata information for the artifact.

   This example lists additional information about the latest version of 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 and --description, to modify the metadata of the artifact you’re creating. For more information about any of the options, run the rhoas service-registry artifact metadata-set -h command to view the command help.

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.

• Your Service Registry instance is the default instance, as described in Specifying the default Service Registry instance.

Procedure

1. Download the artifact in one of the following ways:

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

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

     Downloading an artifact by using the artifact ID

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

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

     To find the global ID, see the output of the rhoas service-registry artifact metadata-get --artifact-id=my-artifact command.

     Downloading an artifact by using the global ID

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

2. Verify that the artifact was downloaded.

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, run the rhoas service-registry artifact download -h command and the rhoas service-registry artifact get -h command to view the command help.

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.

• Your Service Registry instance is the default instance, as described in Specifying the default Service Registry instance.

• 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, run the rhoas service-registry artifact update -h command to view the command help.

Configuring Service Registry rules

To prevent invalid content from being added to Service Registry, you can configure optional rules to check the artifact content. Global rules apply to all artifacts in a particular Service Registry instance. Artifact rules apply to the specified artifact only, and cannot be configured until the artifact is created. Configured artifact rules override any configured global rules.

When you create an instance, the global rules are disabled by default. When you create an artifact, the artifact rules are disabled by default. To configure a global rule or artifact rule, you must ensure that the rule is enabled. An artifact cannot be updated if the new content violates any of the enabled rules; in such cases, the registration fails.

Prerequisites

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

• Your Service Registry instance is the default instance, as described in Specifying the default Service Registry instance.

Procedure

1. Identify the rule that you want to configure.

   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. Configure or update the rule in one of the following ways:

   • If the rule that you want to configure is disabled, use the rhoas service-registry rule enable command.

     When you enable a rule, you must specify the configuration value. If the rule is not currently enabled, you can enable the rule and specify its configuration in the same command.

     This example enables and configures the global compatibility rule for all artifacts in the current Service Registry instance:

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

     This example enables and configures the validity rule for a specific artifact:

     $ rhoas service-registry rule enable --rule-type=validity --config=full --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, run the rhoas service-registry rule enable -h command to view the command help.

   • If the rule is already enabled, use the rhoas service-registry rule update command.

     You can update a rule by specifying the rule type and the new 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=backward

     This example updates the validity rule for a specific artifact:

     $ rhoas service-registry rule update --rule-type=validity --config=syntax-only --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: If you no longer want to apply a rule, you can disable the rule.

   This example disables the global compatibility rule:

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

   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, run the rhoas service-registry rule disable -h command to view the command help.

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.

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

Procedure

1. Ensure that your Service Registry instance is the default instance, as described in Specifying the default Service Registry instance.

2. 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 that you can use to manage your Service Registry instance, run the following commands to view the 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

• rhoas service-registry role -h for Service Registry roles

• rhoas service-registry rule -h for Service Registry rules

• rhoas service-registry setting -h for Service Registry settings

Additional resources

• OpenShift Application Services CLI command reference