Service registry RHOAS CLI

[PaulRMellor]

Updates to the Getting Started CLI guides

• Creates three guides as follows:
  -- Installing and configuring the rhoas CLI
  -- Getting started with the rhoas CLI for OpenShift Streams for Apache Kafka
  -- Getting started with the rhoas CLI for OpenShift Service Registry
• Removes install steps from the getting tarted guides, replaced by prereq that goes to the new common _Install_guide
• Updates links and attributes to reflect the new structure
• Removes the Commands for... tables to replace with -h list and link to command reference guide
• Pushes the Using procedures for Kafka Getting Started up a level (==) and removes the discrete title flag

[wtrocki]

🤩

[wtrocki]

🤩 @PaulRMellor How I can verify/render this - I'm aware of the quickstart procedure. How to run/verify tutorials?

[wtrocki]

@PaulRMellor Amazing work! This is not only looking very good it will also:

• Remove content that was really hard for us to maintain and often get out of sync
• Provide clear path for future services.

Both instructions reviewed and verified.

#tech-ack

[wtrocki]

While changes look good there are some build issues related to duplicated keys.
We need to add -cli suffix to them:

[wtrocki]

Doesn't the context make a difference? I've changed these two. 👍

Tooling validates if id's are not the same and fails. We need to try to be as specific as possible to avoid clashes.

[wtrocki]

DO we know what this means:

asciidoctor: ERROR: modules/guides/proc-creating-kafka-instance-cli.adoc: line 2: level 0 sections can only be used when doctype is book
asciidoctor: ERROR: modules/guides/proc-creating-service-registry-instance-cli.adoc: line 2: level 0 sections can only be used when doctype is book

[PaulRMellor]

@bibryam - Hi Bilgin. This PR has the Getting started with the rhoas CLI for OpenShift Service Registry (rhoas-cli-service-registry/readme.adoc) and a (now) separate Installing and configuring the rhoas CLI guide (rhoas-cli/readme.adoc)

Would appreciate a review.

[bibryam]

@wtrocki @PaulRMellor this look very good. Great job Wojciech!

A few notes bellow:

1. "This example switches to the my-registry instance that was previously created." - is this needed? If there is a single instance, can that be selected by default?

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


   Do we need to specify the type? I was expecting the type to be auto detected?

3. After a schema is updated, can we use the command for setting the compatability level and demonstrate that?

4. @EricWittmann is RBAC feature in prod? I see role assigment demonstrated here? That will require also docs to be available IMO

[wtrocki]

"This example switches to the my-registry instance that was previously created." - is this needed? If there is a single instance, can that be selected by default?

I have followed up pattern we have in Kafka thinking that this was intentional to show user how to switch, but it in fact seems redundant and counterintuitive. @PaulRMellor Do you think we can remove it?

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


Do we need to specify the type? I was expecting the type to be auto detected?

Sadly we need to. Not sure why but the backend is not working well with AVRO schemas that are sent by CLI. It even has troubles with schemas that are provided in the service registry repository as examples:

https://github.com/Apicurio/apicurio-registry/tree/master/integration-tests/testsuite/src/test/resources/artifactTypes

This might be due to reliance on content type that comes from browser environment etc.?
We did not had issues with OpenAPI but for this guide we wanted to show Avro.

@EricWittmann is RBAC feature in prod? I see role assigment demonstrated here? That will require also docs to be available IMO

As solution for this I think we can have this step commented out for the moment and let team to uncomment it when this is there.

[PaulRMellor]

"This example switches to the my-registry instance that was previously created." - is this needed? If there is a single instance, can that be selected by default?

I have followed up pattern we have in Kafka thinking that this was intentional to show user how to switch, but it in fact seems redundant and counterintuitive. @PaulRMellor Do you think we can remove it?

[PAUL] I've removed as a step, but I think it's useful to point it out. Added as a note in prereqs.

rhoas service-registry artifact create --type=AVRO --artifact-id=my-artifact avro-userInfo.json
> 
>
Do we need to specify the type? I was expecting the type to be auto detected?

Sadly we need to. Not sure why but the backend is not working well with AVRO schemas that are sent by CLI. It even has troubles with schemas that are provided in the service registry repository as examples:

https://github.com/Apicurio/apicurio-registry/tree/master/integration-tests/testsuite/src/test/resources/artifactTypes

This might be due to reliance on content type that comes from browser environment etc.? We did not had issues with OpenAPI but for this guide we wanted to show Avro.

@EricWittmann is RBAC feature in prod? I see role assigment demonstrated here? That will require also docs to be available IMO

As solution for this I think we can have this step commented out for the moment and let team to uncomment it when this is there.

[PAUL] I've commented out the role creation step. We don't refer to role in the following tasks. Will we need it in the guide at all?

[wtrocki]

[PAUL] I've commented out the role creation step. We don't refer to role in the following tasks. Will we need it in the guide at all?

Yes.. That will be the only place in the docs that mention needs to apply separate role in service account.
Apart from that we going to also add that in CLI command result:
redhat-developer/app-services-cli#1118

[wtrocki]

@bhardesty Good for docs review

[bhardesty]

@PaulRMellor these changes look great. The break down into three separate guides is a big improvement.

Just one thing to keep in mind if you haven't verified this already: once this is merged, we'll need to verify that the splitter and downstream sync job(s) handle the new guides correctly.

[wtrocki]

I guess we good to merge?