diff --git a/docs/registry/rhoas-cli-getting-started-registry/README.adoc b/docs/registry/rhoas-cli-getting-started-registry/README.adoc index e750aa17b..ff058b68d 100644 --- a/docs/registry/rhoas-cli-getting-started-registry/README.adoc +++ b/docs/registry/rhoas-cli-getting-started-registry/README.adoc @@ -102,16 +102,6 @@ you can use `rhoas` to create {registry} instances and connect your applications You can also manage artifacts. Artifacts are items stored in {registry}, such as schemas and API specifications. -You can get started with {product-long-registry} by doing the following tasks: - -* {base-url}{getting-started-rhoas-cli-url-registry}#proc-creating-service-registry-instance-cli_getting-started-rhoas-service-registry[Create a {registry} instance] -* {base-url}{getting-started-rhoas-cli-url-registry}#proc-creating-service-registry-account_getting-started-rhoas-service-registry[Create a service account] -* {base-url}{getting-started-rhoas-cli-url-registry}#proc-uploading-service-registry-artifacts_getting-started-rhoas-service-registry[Upload {registry} artifacts] -* {base-url}{getting-started-rhoas-cli-url-registry}#proc-downloading-service-registry-artifacts_getting-started-rhoas-service-registry[Download {registry} artifacts] -* {base-url}{getting-started-rhoas-cli-url-registry}#proc-updating-service-registry-artifacts_getting-started-rhoas-service-registry[Update {registry} artifacts] -* {base-url}{getting-started-rhoas-cli-url-registry}#proc-configuring-service-registry-rules_getting-started-rhoas-service-registry[Configure {registry} rules] -* {base-url}{getting-started-rhoas-cli-url-registry}#proc-generating-registry-configs_getting-started-rhoas-service-registry[Generating {registry} configurations] -* {base-url}{getting-started-rhoas-cli-url-registry}#proc-commands-managing-registry_getting-started-rhoas-service-registry[Use `rhoas` to manage your {registry} instance, service accounts, and artifacts] //Additional line break to resolve mod docs generation error @@ -119,7 +109,8 @@ You can get started with {product-long-registry} by doing the following tasks: == Prerequisites [role="_abstract"] -* You've installed the `rhoas` CLI. For more information, see {base-url}{installation-guide-url-cli}[_Installing and configuring the rhoas CLI_^]. +* You've installed the `rhoas` CLI. +For more information, see {base-url}{installation-guide-url-cli}[_Installing and configuring the {product-rhoas} CLI_^]. [id="proc-creating-service-registry-instance-cli_{context}"] == Creating a {registry} instance @@ -145,20 +136,19 @@ $ rhoas service-registry create --name my-registry ---- The CLI uses service contexts to group service instances against which commands are executed. -The created {registry} instance is set automatically in the current context. +The current context is automatically updated so that the created {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` for the {registry} instance. +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 {registry} instance. ==== -- . Verify that the {registry} instance is ready to use. + -- -.Reviewing details of a {registry} instance +.Reviewing the {registry} instance details [source,shell] ---- $ rhoas context status service-registry @@ -169,8 +159,64 @@ because the `Status` field is `ready`. [NOTE] ==== -If you have multiple {registry} instances, -you can change the context to a different instance by using the `rhoas context set-service-registry` command. +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 {base-url}{getting-started-rhoas-cli-url-registry}#proc-commands-managing-registry_getting-started-rhoas-service-registry[Commands for managing {registry}]. +==== +-- + + +[id="proc-specifying-default-service-registry-instance-cli_{context}"] +== Specifying the default {registry} instance + +[role="_abstract"] +If you have multiple {registry} instances, you can configure a default {registry} instance. + +.Prerequisites + +* You've created a {registry} instance, and it has a `ready` status. + +.Procedure + +. Configure the default {registry} instance in one of the following ways: + +** Use the `rhoas context set-service-registry` command: ++ +-- +.Selecting a {registry} instance into the current context +[source,shell] +---- +$ rhoas context set-service-registry --name=my-registry +---- +-- + +** Use the `rhoas service-registry use` command: ++ +-- +.Selecting a {registry} instance to use +[source,shell] +---- +$ 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. +==== +-- + +. Verify that the specified {registry} instance is set as the default instance. ++ +-- +.Reviewing the details of the default {registry} instance +[source,shell] +---- +$ rhoas context status service-registry +---- + +This command shows the name of the default {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. ==== -- @@ -202,7 +248,7 @@ $ rhoas service-account create --short-description="rhoas-service-account" --fil [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. +For more information, run the `rhoas service-account create -h` command to view the command help. ==== -- @@ -237,76 +283,100 @@ This example creates a role called `manager` for the service account. ---- $ rhoas service-registry role add --role=manager --service-account=__ ---- + +[NOTE] +==== +For more information about the different roles, run the `rhoas service-registry role -h` command to view the command help. +==== -- + [id="proc-uploading-service-registry-artifacts_{context}"] == Uploading {registry} artifacts [role="_abstract"] After creating a {registry} instance, you can start uploading {registry} artifacts. -Artifacts might include, for example, schemas that define the structure of Kafka data or OpenAPI documents to define an API. +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 {registry} instance, and it has a `ready` status. +* Your {registry} instance is the default instance, as described in {base-url}{getting-started-rhoas-cli-url-registry}#proc-specifying-default-service-registry-instance-cli_getting-started-rhoas-service-registry[Specifying the default {registry} instance]. -[NOTE] -==== -You can use `rhoas context set-service-registry` to switch to a specific {registry} instance. +.Procedure -.Selecting a {registry} instance to use -[source,shell] ----- -$ rhoas context set-service-registry --name=my-registry ----- -==== +. Upload the artifact in one of the following ways: -.Procedure +* Upload the artifact from a file: -. Upload a {registry} artifact. +.. Download an example schema. + -- -This example uploads a {registry} artifact called `my-artifact` to the {registry} instance. -The artifact is an Apache Kafka Avro schema in JSON format. +This example downloads an Apache Avro schema in JSON format. -.Uploading an artifact +.Downloading an example schema [source,shell] ---- $ wget https://raw.githubusercontent.com/redhat-developer/app-services-cli/main/docs/resources/avro-userInfo.json ---- -- -. Create the {registry} artifact from the Avro schema that you uploaded. +.. Upload the schema as a {registry} artifact. + -.Creating an artifact +-- +This example creates a {registry} artifact called `my-artifact` from the Avro schema that you downloaded in the previous step, and uploads the artifact to the {registry} instance. + +.Creating and uploading an artifact from a file [source,shell] ---- $ 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 +[source,shell] +---- +$ 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 +---- +-- . Verify that the artifact was registered. + -- -This example lists all artifacts belonging to the {registry} instance. +This example lists all artifacts in the default group for the {registry} instance. .Listing artifact details for a {registry} instance [source,shell] ---- $ rhoas service-registry artifact list ---- + +[NOTE] +==== +You can use the `-a` option to list all artifacts in _all_ groups for the {registry} instance. +==== -- . Check the version information for the artifact. + +-- +This example lists information about each version of the artifact. + .Checking the version information of an artifact [source,shell] ---- $ rhoas service-registry artifact versions --artifact-id=my-artifact ---- +-- . 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 [source,shell] ---- @@ -315,8 +385,8 @@ $ 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`. +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. ==== -- @@ -329,45 +399,42 @@ After you register a {registry} artifact, you can download the artifact to updat .Prerequisites * You've created a {registry} instance with at least one artifact. +* Your {registry} instance is the default instance, as described in {base-url}{getting-started-rhoas-cli-url-registry}#proc-specifying-default-service-registry-instance-cli_getting-started-rhoas-service-registry[Specifying the default {registry} instance]. .Procedure -* Download the artifact in one of the following ways: +. 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 [source,shell] ---- $ 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. + -- +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 [source,shell] ---- $ rhoas service-registry artifact download --global-id=28 ---- - -[NOTE] -==== -To find the global ID, see the Kafka message payload. -==== -- +. 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, view the command help `rhoas service-registry artifact download -h` and `rhoas service-registry artifact get -h`. +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. ==== [id="proc-updating-service-registry-artifacts_{context}"] @@ -379,6 +446,7 @@ You can update an artifact with content from a file or from standard input. .Prerequisites * You've created a {registry} instance with at least one artifact. +* Your {registry} instance is the default instance, as described in {base-url}{getting-started-rhoas-cli-url-registry}#proc-specifying-default-service-registry-instance-cli_getting-started-rhoas-service-registry[Specifying the default {registry} instance]. * The type of the updated content is compatible with the current artifact type. .Procedure @@ -396,7 +464,7 @@ $ rhoas service-registry artifact update --artifact-id=my-artifact my-artifact.j [NOTE] ==== -To update the artifact from standard input, use the `rhoas service-registry artifact update --artifact-id=my_artifact` command. +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. ==== @@ -414,7 +482,7 @@ $ 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`. +For more information about any of the options, run the `rhoas service-registry artifact update -h` command to view the command help. ==== -- @@ -422,15 +490,18 @@ For more information about any of the options, view the command help `rhoas serv == Configuring {registry} rules [role="_abstract"] -To prevent invalid content from being added to {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 {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. +To prevent invalid content from being added to {registry}, you can configure optional rules to check the artifact content. Global rules apply to all artifacts in a particular {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 {registry} instance with at least one artifact. +* Your {registry} instance is the default instance, as described in {base-url}{getting-started-rhoas-cli-url-registry}#proc-specifying-default-service-registry-instance-cli_getting-started-rhoas-service-registry[Specifying the default {registry} instance]. .Procedure -. Identify the rule that you want to update. +. Identify the rule that you want to configure. + -- To show a list of global rules, run the following command: @@ -448,21 +519,49 @@ $ rhoas service-registry rule list --artifact-id=my-artifact ---- -- -. Update the {registry} rule by specifying the rule type and configuration. +. 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 {registry} instance: + +[source,shell] +---- +$ rhoas service-registry rule enable --rule-type=compatibility --config=full +---- + +This example enables and configures the validity rule for a specific artifact: + +[source,shell] +---- +$ 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 {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 {registry} instance: [source,shell] ---- -$ rhoas service-registry rule update --rule-type=compatibility --config=full +$ rhoas service-registry rule update --rule-type=compatibility --config=backward ---- This example updates the validity rule for a specific artifact: [source,shell] ---- -$ rhoas service-registry rule update --rule-type=validity --config=full --artifact-id=my-artifact +$ rhoas service-registry rule update --rule-type=validity --config=syntax-only --artifact-id=my-artifact ---- [NOTE] @@ -490,14 +589,14 @@ $ rhoas service-registry rule describe --rule-type=validity --artifact-id=my-art ---- -- -. Optional: Enable or disable individual rules. When you enable a rule, you must specify the configuration value. +. Optional: If you no longer want to apply a rule, you can disable the rule. + -- -This example enables the global compatibility rule: +This example disables the global compatibility rule: [source,shell] ---- -$ rhoas service-registry rule enable --rule-type=compatibility --config=full +$ rhoas service-registry rule disable --rule-type=compatibility ---- This example disables the artifact validity rule: @@ -506,32 +605,33 @@ 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 {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`. +For more information about any of the options, run the `rhoas service-registry rule disable -h` command to view the command help. ==== +-- [id="proc-generating-registry-configs_{context}"] -== Generating configurations for Service Registry instance +== Generating configurations for {registry} instance [role="_abstract"] -After creating a Service Registry instance, you can generate a configuration file that your applications can use to connect to your Service Registry instance. +After creating a {registry} instance, you can generate a configuration file that your applications can use to connect to your {registry} instance. .Prerequisites -* You've created a Service Registry instance. -* The Service Registry instance is set in the current context. +* You've created a {registry} instance. * Your user account and org have quota for creating service accounts. .Procedure -* Generate a configuration file for the current service context. +. Ensure that your {registry} instance is the default instance, as described in {base-url}{getting-started-rhoas-cli-url-registry}#proc-specifying-default-service-registry-instance-cli_getting-started-rhoas-service-registry[Specifying the default {registry} instance]. + +. Generate a configuration file for the current service context. + -- -This example generates a JSON file with configurations for the Service Registry instance. +This example generates a JSON file with configurations for the {registry} instance. .Generating a configuration file [source,shell] @@ -545,13 +645,15 @@ $ rhoas generate-config --type json == Commands for managing {registry} [role="_abstract"] -For more information about the `rhoas` commands you can use to manage your {registry} instance, -use the following command help: +For more information about the `rhoas` commands that you can use to manage your {registry} instance, run the following commands to view the command help: * `rhoas service-registry -h` for {registry} instances * `rhoas service-account -h` for service accounts * `rhoas service-registry artifact -h` for {registry} artifacts +* `rhoas service-registry role -h` for {registry} roles +* `rhoas service-registry rule -h` for {registry} rules +* `rhoas service-registry setting -h` for {registry} settings [role="_additional-resources"] .Additional resources -* {base-url-cli}{command-ref-url-cli}[_CLI command reference (rhoas)_^] +* {base-url-cli}{command-ref-url-cli}[_{product-rhoas} CLI command reference_^]