From 4fee63d13dc7e66dcc447f2a25c141e4f1509dc2 Mon Sep 17 00:00:00 2001 From: cbippley Date: Fri, 6 Sep 2024 14:05:47 -0400 Subject: [PATCH] OSDOCS-5243 Adding CLI Manager docs --- _attributes/common-attributes.adoc | 1 + _topic_maps/_topic_map.yml | 13 ++++ cli_reference/cli_manager/_attributes | 1 + .../cli_manager/cli-manager-install.adoc | 22 +++++++ .../cli-manager-release-notes.adoc | 33 ++++++++++ .../cli_manager/cli-manager-uninstall.adoc | 15 +++++ .../cli_manager/cli-manager-using.adoc | 21 +++++++ cli_reference/cli_manager/images | 1 + cli_reference/cli_manager/index.adoc | 0 cli_reference/cli_manager/modules | 1 + cli_reference/cli_manager/snippets | 1 + modules/cli-manager-about.adoc | 9 +++ modules/cli-manager-adding-plugins.adoc | 44 ++++++++++++++ modules/cli-manager-configuring.adoc | 19 ++++++ modules/cli-manager-custom-index-krew.adoc | 60 +++++++++++++++++++ modules/cli-manager-installing.adoc | 38 ++++++++++++ modules/cli-manager-overview.adoc | 7 +++ modules/cli-manager-plugin-list.adoc | 44 ++++++++++++++ modules/cli-manager-remove-resources.adoc | 24 ++++++++ modules/cli-manager-uninstall-plugin.adoc | 23 +++++++ modules/cli-manager-uninstalling.adoc | 24 ++++++++ modules/cli-manager-updating-plugin.adoc | 32 ++++++++++ 22 files changed, 433 insertions(+) create mode 120000 cli_reference/cli_manager/_attributes create mode 100644 cli_reference/cli_manager/cli-manager-install.adoc create mode 100644 cli_reference/cli_manager/cli-manager-release-notes.adoc create mode 100644 cli_reference/cli_manager/cli-manager-uninstall.adoc create mode 100644 cli_reference/cli_manager/cli-manager-using.adoc create mode 120000 cli_reference/cli_manager/images create mode 100644 cli_reference/cli_manager/index.adoc create mode 120000 cli_reference/cli_manager/modules create mode 120000 cli_reference/cli_manager/snippets create mode 100644 modules/cli-manager-about.adoc create mode 100644 modules/cli-manager-adding-plugins.adoc create mode 100644 modules/cli-manager-configuring.adoc create mode 100644 modules/cli-manager-custom-index-krew.adoc create mode 100644 modules/cli-manager-installing.adoc create mode 100644 modules/cli-manager-overview.adoc create mode 100644 modules/cli-manager-plugin-list.adoc create mode 100644 modules/cli-manager-remove-resources.adoc create mode 100644 modules/cli-manager-uninstall-plugin.adoc create mode 100644 modules/cli-manager-uninstalling.adoc create mode 100644 modules/cli-manager-updating-plugin.adoc diff --git a/_attributes/common-attributes.adoc b/_attributes/common-attributes.adoc index 28669a00b948..332bc9f59c23 100644 --- a/_attributes/common-attributes.adoc +++ b/_attributes/common-attributes.adoc @@ -54,6 +54,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: Openshift CLI Manager // Backup and restore :velero-domain: velero.io :velero-version: 1.14 diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml index 9a467065a0d9..1f6aa7aecae8 100644 --- a/_topic_maps/_topic_map.yml +++ b/_topic_maps/_topic_map.yml @@ -923,6 +923,19 @@ Topics: - 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 diff --git a/cli_reference/cli_manager/_attributes b/cli_reference/cli_manager/_attributes new file mode 120000 index 000000000000..5b32de1e01e7 --- /dev/null +++ b/cli_reference/cli_manager/_attributes @@ -0,0 +1 @@ +../../_attributes \ No newline at end of file diff --git a/cli_reference/cli_manager/cli-manager-install.adoc b/cli_reference/cli_manager/cli-manager-install.adoc new file mode 100644 index 000000000000..5cef49d06f9b --- /dev/null +++ b/cli_reference/cli_manager/cli-manager-install.adoc @@ -0,0 +1,22 @@ +:_content-type: ASSEMBLY +[id="cli-manager-install_{context}"] += Installing the {cli-manager} +include::_attributes/common-attributes.adoc[] +:context: cli-manager-install + +toc::[] + +//Brief explanation of what the cli manager is. +In disconnected environments it is difficult to install and manage CLI plugins. The CLI Manager was created to make installing and managing CLI plugins in disconnected environments easier. + +// About the CLI Manager +include::modules/cli-manager-about.adoc[leveloffset=+1] + +// 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] + +// Configuring the CLI Manager +include::modules/cli-manager-configuring.adoc[leveloffset=+1] \ No newline at end of file diff --git a/cli_reference/cli_manager/cli-manager-release-notes.adoc b/cli_reference/cli_manager/cli-manager-release-notes.adoc new file mode 100644 index 000000000000..0e742c2b88d0 --- /dev/null +++ b/cli_reference/cli_manager/cli-manager-release-notes.adoc @@ -0,0 +1,33 @@ +:_content-type: ASSEMBLY +[id="cli-manager-release-notes_{context}"] += {cli-manager} release notes +include::_attributes/common-attributes.adoc[] +:context: cli-manager-release-notes + +toc::[] + +//Add release notes overview + +These release notes track the development of the {cli-manager} for {product-title}. + +//For an overview of the {run-once-operator}, see xref :../../../nodes/pods/run_once_duration_override/index.adoc#run-once-about_run-once-duration-override-about[About the {run-once-operator}]. + +[id="cli-manager-release-notes-1-0-0_{context}"] +== {cli-manager} 1.0.0 + +Issued: 5 November 2024 + +The following advisory is available for the {cli-manager} 1.0.0: +//add correct link +* link:https://access.redhat.com/errata/RHEA-2023:2035[RHEA-2023:2035] + +[id="cli-manager-1-0-0-new-features-and-enhancements_{context}"] +=== New features and enhancements + +//* This is the initial, generally available release of the {cli-manager}. For installation information, see xref :../../../getting_started/cli_manager/cli-manager-install.adoc#run-once-duration-override-install[Installing the {run-once-operator}]. + +// No bug fixes or known issues to list + +//To update to the latest version of plugin; + +//$ oc krew update \ No newline at end of file diff --git a/cli_reference/cli_manager/cli-manager-uninstall.adoc b/cli_reference/cli_manager/cli-manager-uninstall.adoc new file mode 100644 index 000000000000..756aca51b1a1 --- /dev/null +++ b/cli_reference/cli_manager/cli-manager-uninstall.adoc @@ -0,0 +1,15 @@ +:_content-type: ASSEMBLY +[id="cli-manager-uninstall_{context}"] += 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. + +// 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] \ No newline at end of file diff --git a/cli_reference/cli_manager/cli-manager-using.adoc b/cli_reference/cli_manager/cli-manager-using.adoc new file mode 100644 index 000000000000..13f7e5b1f12f --- /dev/null +++ b/cli_reference/cli_manager/cli-manager-using.adoc @@ -0,0 +1,21 @@ +:_content-type: ASSEMBLY +[id="cli-manager-install_{context}"] += Using the {cli-manager} +include::_attributes/common-attributes.adoc[] +:context: cli-manager-using + +toc::[] + +//Brief explanation of what the cli manager is. + +// Available plugins table +include::modules/cli-manager-plugin-list.adoc[leveloffset=+1] + +// Adding a CLI plugin with the CLI Manager +include::modules/cli-manager-adding-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] \ No newline at end of file diff --git a/cli_reference/cli_manager/images b/cli_reference/cli_manager/images new file mode 120000 index 000000000000..5fa6987088da --- /dev/null +++ b/cli_reference/cli_manager/images @@ -0,0 +1 @@ +../../images \ No newline at end of file diff --git a/cli_reference/cli_manager/index.adoc b/cli_reference/cli_manager/index.adoc new file mode 100644 index 000000000000..e69de29bb2d1 diff --git a/cli_reference/cli_manager/modules b/cli_reference/cli_manager/modules new file mode 120000 index 000000000000..8b0e8540076d --- /dev/null +++ b/cli_reference/cli_manager/modules @@ -0,0 +1 @@ +../../modules \ No newline at end of file diff --git a/cli_reference/cli_manager/snippets b/cli_reference/cli_manager/snippets new file mode 120000 index 000000000000..7bf6da9a51d0 --- /dev/null +++ b/cli_reference/cli_manager/snippets @@ -0,0 +1 @@ +../../snippets \ No newline at end of file diff --git a/modules/cli-manager-about.adoc b/modules/cli-manager-about.adoc new file mode 100644 index 000000000000..7932182c4921 --- /dev/null +++ b/modules/cli-manager-about.adoc @@ -0,0 +1,9 @@ +// Module included in the following assemblies: +// +// * cli_reference/cli_manager/cli-manager-install.adoc + +:_mod-docs-content-type: CONCEPT +[id="cli-manager-about_{context}"] += About the CLI Manager + +The CLI Manager \ No newline at end of file diff --git a/modules/cli-manager-adding-plugins.adoc b/modules/cli-manager-adding-plugins.adoc new file mode 100644 index 000000000000..c072b378de41 --- /dev/null +++ b/modules/cli-manager-adding-plugins.adoc @@ -0,0 +1,44 @@ +// Module included in the following assemblies: +// +// * cli_reference/cli_manager/cli-manager-using.adoc + +:_mod-docs-content-type: PROCEDURE +[id="cli-manager-adding-plugins_{context}"] += Adding CLI plugins with 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 + +. To list all available plugins, run the following command: ++ +[source,terminal] +---- +$ oc krew search +---- + +. To get information about a plugin, run the following command: ++ +[source,terminal] +---- +$ oc krew info +---- + +. To install a plugin, run the following command: ++ +[source,terminal] +---- +$ oc krew install +---- + +. To list all plugins that were installed by Krew, run the following command: ++ +[source,terminal] +---- +$ oc krew list +---- diff --git a/modules/cli-manager-configuring.adoc b/modules/cli-manager-configuring.adoc new file mode 100644 index 000000000000..c4658c07f2b6 --- /dev/null +++ b/modules/cli-manager-configuring.adoc @@ -0,0 +1,19 @@ +// Module included in the following assemblies: +// +// * cli_reference/cli_manager/cli-manager-install.adoc + +:_mod-docs-content-type: PROCEDURE +[id="cli-manager-overview_{context}"] += Configuring the {cli-manager} + +In order to use the {cli-manager} to add plugins you will need to configure the + +.Prerequisites + +* You have +* link:https://krew.sigs.k8s.io/docs/user-guide/setup/install[Krew is installed] +* Custom index provided by OpenShift CLI Manager is defined in Krew + +.Procedure + +. \ No newline at end of file diff --git a/modules/cli-manager-custom-index-krew.adoc b/modules/cli-manager-custom-index-krew.adoc new file mode 100644 index 000000000000..4ea99b9c8c67 --- /dev/null +++ b/modules/cli-manager-custom-index-krew.adoc @@ -0,0 +1,60 @@ +// 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 + +Use the terminal to add the CLI manager custom index to Krew. + +.Prerequisites + +* link:https://krew.sigs.k8s.io/docs/user-guide/setup/install[Krew is installed]. +* The CLI Manager is installed. +* You are logged in to {product-title} as a user with the `cluster-admin` role. +* You are using {product-title} 4.17 or later. + +.Procedure + +. Execute the following command: + +[source,terminal] +---- +oc get route/openshift-cli-manager -n openshift-cli-manager-operator -o=jsonpath='{.spec.host}' +---- + +. Name the custom index. + +[source,terminal] +---- +# =ocp +---- + +. Add the custom index to Krew. + +[source,terminal] +---- +# oc krew index add $ https://$ROUTE/cli-manager +---- + +.. If you see certificate authority errors use the following command to get the certificate authority data and write it to your local machine. + +[source,terminal] +---- +# echo "$(oc config view --minify --flatten -o jsonpath='{.clusters[0].cluster.certificate-authority-data}' | base64 --decode)" | sudo tee /etc/pki/ca-trust/source/anchors/cli.crt > /dev/null +---- + +.. Update the certificate authority for it to be trusted. + +[source,terminal] +---- +# sudo update-ca-trust +---- + +.. Update Krew. + +[source,terminal] +---- +# oc krew update +---- \ No newline at end of file diff --git a/modules/cli-manager-installing.adoc b/modules/cli-manager-installing.adoc new file mode 100644 index 000000000000..24fcb3d37ab2 --- /dev/null +++ b/modules/cli-manager-installing.adoc @@ -0,0 +1,38 @@ +// Module included in the following assemblies: +// +// * cli_reference/cli_manager/cli-manager-install.adoc + +:_mod-docs-content-type: PROCEDURE +[id="cli-manager-installing_{context}"] += Installing the {cli-manager} + +.Prerequisites + +* link:https://krew.sigs.k8s.io/docs/user-guide/setup/install[Krew is installed]. +* You are logged in to {product-title} as a user with the `cluster-admin` role. +* You have access to the {product-title} web console. +* The CLI Manager is installed. +* You are using {product-title} 4.17 or later. + +.Procedure + +. Log in to the {product-title} web console. + +. Create the required namespace for the {cli-manager}. +.. Navigate to *Administration* -> *Namespaces* and click *Create Namespace*. +.. Enter `openshift-cli-manager-operator` in the *Name* field and click *Create*. ++ + +. Install the {cli-manager}. +.. Navigate to *Operators* -> *OperatorHub*. +.. Enter *{cli-manager}* into the filter box. +.. Select the *{cli-manager}* and click *Install*. +.. On the *Install Operator* page: +... The *Update channel* is set to *stable*, which installs the latest stable release of the {cli-manager}. +... Select *A specific namespace on the cluster* and select *openshift-cli-manager-operator* from the drop-down menu. +... Click *Install*. + +.Verification + +. Navigate to *Operators* -> *Installed Operators*. +. Verify that *{cli-manager}* is listed with a *Status* of *Succeeded*. \ No newline at end of file diff --git a/modules/cli-manager-overview.adoc b/modules/cli-manager-overview.adoc new file mode 100644 index 000000000000..d011b05f8684 --- /dev/null +++ b/modules/cli-manager-overview.adoc @@ -0,0 +1,7 @@ +// Module included in the following assemblies: +// +// * + +:_mod-docs-content-type: CONCEPT +[id="cli-manager-overview_{context}"] += CLI Manager overview \ No newline at end of file diff --git a/modules/cli-manager-plugin-list.adoc b/modules/cli-manager-plugin-list.adoc new file mode 100644 index 000000000000..a567ba0bebc0 --- /dev/null +++ b/modules/cli-manager-plugin-list.adoc @@ -0,0 +1,44 @@ +// Module included in the following assemblies: +// +// * cli_reference/cli_manager/cli-manager-using.adoc + +:_mod-docs-content-type: REFERENCE +[id="cli-manager-overview_{context}"] += Available plugins for the {cli-manager} + +//What other information should be included here? +// What do (kn) and (tkn) mean? +// These commands are guesses on my part. What are they actually? + +.{product-title} flags for `oc adm must-gather` +[cols="1,1",options="header"] +|==== +|CLI |Install command + +|oc +|`oc krew install ocp/oc-mirror` + +|Knative CLI (kn) +|`oc krew install knative` + +|Pipelines CLI (tkn) +|`oc krew install pipelines` + +|opm CLI +|`oc krew install opm` + +|ROSA +|`oc krew install rosa` + +|ccocli +|`oc krew install ccocli` + +|Red Hat OpenShift GitOps CLI +|`oc krew install gitops cli` + +|Virtualization (virtctl) +|`oc krew install virtctl` + +|Hypershift CLI +|`oc krew install hypershift cli` +|==== \ No newline at end of file diff --git a/modules/cli-manager-remove-resources.adoc b/modules/cli-manager-remove-resources.adoc new file mode 100644 index 000000000000..ba6318d88184 --- /dev/null +++ b/modules/cli-manager-remove-resources.adoc @@ -0,0 +1,24 @@ +// Module included in the following assemblies: +// +// * cli_reference/cli_manager/cli-manager-uninstall.adoc + +:_mod-docs-content-type: PROCEDURE +[id="cli-manager-remove-resources_{context}"] += Removing {cli-manager} resources + +Optionally, after uninstalling the {cli-manager}, you can remove its related resources from your cluster. + +.Prerequisites + +* You are logged in to {product-title} as a user with the `cluster-admin` role. +* You are logged in to {product-title} as a user with the `dedicated-admin` role. +* You have access to the {product-title} web console. + +.Procedure + +. Log in to the {product-title} web console. + +. Remove the `openshift-cli-manager-operator` namespace. +.. Navigate to *Administration* -> *Namespaces*. +.. Click the Options menu {kebab} next to the *openshift-cli-manager-operator* and select *Delete Namespace*. +.. In the confirmation dialog, enter `openshift-cli-manager-operator` in the field and click *Delete*. diff --git a/modules/cli-manager-uninstall-plugin.adoc b/modules/cli-manager-uninstall-plugin.adoc new file mode 100644 index 000000000000..f027a37ea175 --- /dev/null +++ b/modules/cli-manager-uninstall-plugin.adoc @@ -0,0 +1,23 @@ +// Module included in the following assemblies: +// +// * cli_reference/cli_manager/cli-manager-using.adoc + +:_mod-docs-content-type: PROCEDURE +[id="cli-manager-remove-plugin_{context}"] += Uninstalling a CLI plugin with the CLI Manager + +You can uninstall a plugin that was installed for the OpenShift CLI (`oc`) with 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. +* You have installed a plugin for the OpenShift CLI with the CLI Manager. + +.Procedure + +* To uninstall a plugin, run the following command: ++ +[source,terminal] +---- +$ oc krew uninstall +---- diff --git a/modules/cli-manager-uninstalling.adoc b/modules/cli-manager-uninstalling.adoc new file mode 100644 index 000000000000..86891009c2dd --- /dev/null +++ b/modules/cli-manager-uninstalling.adoc @@ -0,0 +1,24 @@ +// Module included in the following assemblies: +// +// * cli_reference/cli_manager/cli-manager-uninstall.adoc + +:_mod-docs-content-type: PROCEDURE +[id="cli-manager-uninstalling_{context}"] += Uninstalling the {cli-manager} + +You can uninstall the {cli-manager} by using the web console. + +.Prerequisites + +* You are logged in to {product-title} as a user with the `cluster-admin` role. +* You are logged in to {product-title} as a user with the `dedicated-admin` role. +* You have access to the {product-title} web console. +* The {cli-manager} is installed. + +.Procedure + +. Log in to the {product-title} web console. +. Uninstall the {cli-manager} Operator. +.. Navigate to *Operators* -> *Installed Operators*. +.. Click the Options menu {kebab} next to the *{cli-manager}* entry and click *Uninstall Operator*. +.. In the confirmation dialog, click *Uninstall*. diff --git a/modules/cli-manager-updating-plugin.adoc b/modules/cli-manager-updating-plugin.adoc new file mode 100644 index 000000000000..ef789c29a2c7 --- /dev/null +++ b/modules/cli-manager-updating-plugin.adoc @@ -0,0 +1,32 @@ +// Module included in the following assemblies: +// +// * cli_reference/cli_manager/cli-manager-using.adoc + +:_mod-docs-content-type: PROCEDURE +[id="cli-manager-updating-plugin_{context}"] += Updating CLI plugins with the {cli-manager} + +You can update a plugin that was installed for the OpenShift CLI (`oc`) with 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. +* You are running {product-title} 4.17 or later. +* The CLI Manager is installed. +* You've added the custom index to Krew. + +.Procedure + +* To update a single plugin, run the following command: ++ +[source,terminal] +---- +$ oc krew upgrade +---- + +* To update all plugins that were installed by Krew, run the following command: ++ +[source,terminal] +---- +$ oc krew upgrade +----