Merge pull request #81448 from cbippley/OSDOCS-5243

OSDOCS-5243 Adding CLI Manager docs

_attributes/common-attributes.adoc

@@ -56,6 +56,7 @@ endif::[]
 :secondary-scheduler-operator-full: Secondary Scheduler Operator for Red Hat OpenShift
 :secondary-scheduler-operator: Secondary Scheduler Operator
 :descheduler-operator: Kube Descheduler Operator
+:cli-manager: CLI Manager Operator
 // Backup and restore
 :velero-domain: velero.io
 :velero-version: 1.14

_topic_maps/_topic_map.yml

@@ -927,14 +927,24 @@ Topics:
     File: managing-cli-profiles
   - Name: Extending the OpenShift CLI with plugins
     File: extending-cli-plugins
-  - Name: Managing CLI plugins with Krew
-    File: managing-cli-plugins-krew
-    Distros: openshift-enterprise,openshift-origin
   - Name: OpenShift CLI developer command reference
     File: developer-cli-commands
   - Name: OpenShift CLI administrator command reference
     File: administrator-cli-commands
     Distros: openshift-enterprise,openshift-origin
+- Name: OpenShift CLI Manager
+  Dir: cli_manager
+  Topics:
+  - Name: OpenShift CLI Manager overview
+    File: index
+  - Name: OpenShift CLI Manager release notes
+    File: cli-manager-release-notes
+  - Name: Installing the Openshift CLI Manager
+    File: cli-manager-install
+  - Name: Using the OpenShift CLI Manager
+    File: cli-manager-using
+  - Name: Uninstalling the OpenShift CLI Manager
+    File: cli-manager-uninstall
 - Name: Developer CLI (odo)
   File: odo-important-update
   # Dir: developer_cli_odo

cli_reference/cli_manager/_attributes

@@ -0,0 +1 @@
+../../_attributes

cli_reference/cli_manager/cli-manager-install.adoc

@@ -0,0 +1,22 @@
+:_mod-docs-content-type: ASSEMBLY
+[id="cli-manager-install"]
+= Installing the {cli-manager}
+include::_attributes/common-attributes.adoc[]
+:context: cli-manager-install
+
+toc::[]
+
+//Brief explanation of what the cli manager is.
+You can run the {cli-manager} in both connected and disconnected environments. In particular, it eases the installation and management of CLI plugins in disconnected environments. The {cli-manager} makes Krew compatible with the `oc` CLI. Cluster administrators can use the {cli-manager} to add CLI plugin custom resources that can then be accessed in both connected and disconnected environments. Cluster administrators install and configure the {cli-manager}, and users then add the custom index to Krew and add CLI plugins to the {cli-manager}.
+
+:FeatureName: Using the {cli-manager} to install and manage plugins for the OpenShift CLI
+include::snippets/technology-preview.adoc[]
+
+// Installing the {cli-manager}
+include::modules/cli-manager-installing.adoc[leveloffset=+1]
+
+// Adding CLI Manager custom index to krew
+include::modules/cli-manager-custom-index-krew.adoc[leveloffset=+1]
+
+// Adding CLI plugins with YAML files
+include::modules/cli-manager-adding-plugin-yaml.adoc[leveloffset=+1]

cli_reference/cli_manager/cli-manager-release-notes.adoc

@@ -0,0 +1,32 @@
+:_mod-docs-content-type: ASSEMBLY
+[id="cli-manager-release-notes"]
+= {cli-manager} release notes
+include::_attributes/common-attributes.adoc[]
+:context: cli-manager-release-notes
+
+toc::[]
+
+With the {cli-manager}, you can install CLI plugins in both connected and disconnected environments.
+
+:FeatureName: Using the {cli-manager} to install and manage plugins for the OpenShift CLI
+include::snippets/technology-preview.adoc[]
+
+These release notes track the development of the {cli-manager} for {product-title}.
+
+For more information about the {cli-manager}, see xref:../../cli_reference/cli_manager/index.adoc#cli-manager-overview[About the {cli-manager}].
+
+[id="cli-manager-release-notes-0-1-0_{context}"]
+== {cli-manager} 0.1.0 (Technology Preview)
+
+Issued: 19 November 2024
+
+The following advisory is available for the {cli-manager} 0.1.0:
+
+* link:https://access.redhat.com/errata/RHEA-2024:8303[RHEA-2024:8303]
+
+[id="cli-manager-0-1-0-new-features-and-enhancements_{context}"]
+=== New features and enhancements
+
+* This version is the initial Technology Preview release of the {cli-manager}. For installation information, see xref:../../cli_reference/cli_manager/cli-manager-install.adoc#cli-manager-install[Installing the {cli-manager}].
+
+//* No bug fixes or known issues to list

cli_reference/cli_manager/cli-manager-uninstall.adoc

@@ -0,0 +1,18 @@
+:_content-type: ASSEMBLY
+[id="cli-manager-uninstall"]
+= Uninstalling the {cli-manager}
+include::_attributes/common-attributes.adoc[]
+:context: cli-manager-uninstall
+
+toc::[]
+
+You can remove the {cli-manager} from {product-title} by uninstalling the {cli-manager} and removing its related resources.
+
+:FeatureName: Using the {cli-manager} to install and manage plugins for the OpenShift CLI
+include::snippets/technology-preview.adoc[]
+
+// Uninstalling the {cli-manager}
+include::modules/cli-manager-uninstalling.adoc[leveloffset=+1]
+
+// Uninstalling the related resources
+include::modules/cli-manager-remove-resources.adoc[leveloffset=+1]

cli_reference/cli_manager/cli-manager-using.adoc

@@ -0,0 +1,21 @@
+:_mod-docs-content-type: ASSEMBLY
+[id="cli-manager-using"]
+= Using the {cli-manager}
+include::_attributes/common-attributes.adoc[]
+:context: cli-manager-using
+
+toc::[]
+
+After the cluster administrator sets up and configures the {cli-manager}, users can use it to install, update, and uninstall CLI plugins.
+
+:FeatureName: Using the {cli-manager} to install and manage plugins for the OpenShift CLI
+include::snippets/technology-preview.adoc[]
+
+// Installing a CLI plugin with the CLI Manager
+include::modules/cli-manager-installing-plugins.adoc[leveloffset=+1]
+
+// Updating a cli plugin with the CLI Manager
+include::modules/cli-manager-updating-plugin.adoc[leveloffset=+1]
+
+// Uninstalling a CLI plugin with the CLI Manager
+include::modules/cli-manager-uninstall-plugin.adoc[leveloffset=+1]

cli_reference/cli_manager/images

@@ -0,0 +1 @@
+../../images

cli_reference/cli_manager/index.adoc

@@ -0,0 +1,13 @@
+:_mod-docs-content-type: ASSEMBLY
+[id="cli-manager-overview"]
+= {cli-manager} overview
+include::_attributes/common-attributes.adoc[]
+:context: cli-manager-overview
+
+toc::[]
+
+:FeatureName: Using the {cli-manager} to install and manage plugins for the OpenShift CLI
+include::snippets/technology-preview.adoc[]
+
+// About the CLI Manager
+include::modules/cli-manager-about.adoc[leveloffset=+1]

cli_reference/cli_manager/modules

@@ -0,0 +1 @@
+../../modules

cli_reference/cli_manager/snippets

@@ -0,0 +1 @@
+../../snippets

modules/cli-manager-about.adoc

@@ -0,0 +1,9 @@
+// Module included in the following assemblies:
+//
+// * cli_reference/cli_manager/index.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="cli-manager-about_{context}"]
+= About the {cli-manager}
+
+The {cli-manager} makes it easier to install and update CLI plugins. It runs in both connected and disconnected environments, and it is particularly useful in disconnected environments. Cluster administrators can add CLI plugins and plugin updates to the {cli-manager}, and users can then install and update CLI plugins when needed regardless of whether or not the environment is disconnected.

modules/cli-manager-adding-plugin-yaml.adoc

@@ -0,0 +1,73 @@
+// Module included in the following assemblies:
+//
+// * cli_reference/cli_manager/cli-manager-install.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="cli-manager-adding-plugin-yamls_{context}"]
+= Adding a plugin to the {cli-manager}
+
+You can add a CLI plugin to the {cli-manager} by using the YAML View.
+
+.Prerequisites
+
+* You are logged in to {product-title} as a user with the `cluster-admin` role.
+* The {cli-manager} is installed.
+
+.Procedure
+
+. Log in to the {product-title} web console.
+
+. Navigate to *Operators* -> *Installed Operators*.
+
+. From the list, select *{cli-manager}*.
+
+. Select the *CLI Plugin* tab.
+
+. Click *Create Plugin*.
+
+. In the text box, enter the information for the plugin you are installing. See the following example YAML file.
++
+.Example YAML file to add a plugin
+
+[source,yaml]
+----
+apiVersion: config.openshift.io/v1alpha1
+kind: Plugin
+metadata:
+  name: <plugin_name> <1>
+spec:
+  description: <description_of_plugin>
+  homepage: <plugin_homepage>
+  platforms:
+  - bin: <2>
+    files:
+    - from: <plugin_file_path>
+      to: .
+    image: <plugin_image>
+    imagePullSecret: <3>
+    platform: <platform> <4>
+  shortDescription: <short_description_of_plugin>
+  version: <version> <5>
+----
+<1> The name of the plugin you plan to use in commands.
+<2> `Bin` specifies the path to the plugin executable.
+<3> Optional: If the registry is not public, add a pull secret to access your plugin image.
+<4> Add the architecture for your system; for example, `linux/amd64`, `darwin/arm64`, `windows/amd64`, or another architecture.
+<5> Version must be in v0.0.0 format.
+
+. Click *Save*.
+
+.Verification
+
+* Enter the following command to see if the plugin is listed and has been added successfully:
+
+[source,terminal]
+----
+$ oc get plugin/<plugin_name> -o yaml
+----
+
+.Example output
+[source,terminal]
+----
+<plugin_name> ready to be served.
+----

modules/cli-manager-custom-index-krew.adoc

@@ -0,0 +1,53 @@
+// Module included in the following assemblies:
+//
+// * cli_reference/cli_manager/cli-manager-install.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="cli-manager-custom-index_{context}"]
+= Adding the {cli-manager} custom index to Krew
+
+You can use the terminal to add the CLI manager custom index to Krew. This procedure is required for the {cli-manager} to function correctly and needs to be done only once.
+
+The custom index connects Krew to the {cli-manager} binaries and enables the {cli-manager} to work in disconnected environments.
+
+[NOTE]
+====
+If you use self-signed certificates, mark the certificate as trusted on your local operating system to use Krew.
+====
+
+.Prerequisites
+
+* link:https://krew.sigs.k8s.io/docs/user-guide/setup/install[Krew is installed].
+* The {cli-manager} is installed.
+
+.Procedure
+
+. To establish the `ROUTE` variable, enter the following command:
++
+[source,terminal]
+----
+$ ROUTE=$(oc get route/openshift-cli-manager -n openshift-cli-manager-operator -o=jsonpath='{.spec.host}')
+----
+
+. To add the custom index to Krew, enter the following command:
++
+[source,terminal]
+----
+$ oc krew index add <custom_index_name> https://$ROUTE/cli-manager
+----
+
+. To update Krew, enter the following command and check for any errors:
++
+[source,terminal]
+----
+$ oc krew update
+----
+
+.Example output
+[source,terminal]
+----
+Updated the local copy of plugin index.
+Updated the local copy of plugin index <custom_index_name>.
+New plugins available:
+* ocp/<plugin_name>
+----

modules/cli-krew-install-plugin.adoc → modules/cli-manager-installing-plugins.adoc

@@ -1,16 +1,19 @@
 // Module included in the following assemblies:
 //
-// * cli_reference/openshift_cli/installing-cli-plugins-krew.adoc
+// * cli_reference/cli_manager/cli-manager-using.adoc
 
 :_mod-docs-content-type: PROCEDURE
-[id="cli-krew-install-plugin_{context}"]
-= Installing a CLI plugin with Krew
+[id="cli-manager-adding-plugins_{context}"]
+= Installing CLI plugins with the {cli-manager}
 
-You can install a plugin for the OpenShift CLI (`oc`) with Krew.
+You can install CLI plugins using the {cli-manager}.
 
 .Prerequisites
 
 * You have installed Krew by following the link:https://krew.sigs.k8s.io/docs/user-guide/setup/install/[installation procedure] in the Krew documentation.
+* The CLI Manager is installed.
+* The CLI Manager custom index has been added to Krew.
+* You are using {product-title} 4.17 or later.
 
 .Procedure