Merge pull request #55521 from ShaunaDiaz/OSDOCS-4971

OSDOCS-4971: Restructure CLI reference book

Author: skrthomas

_attributes/attributes-microshift.adoc

@@ -6,14 +6,13 @@
 :OCP: OpenShift Container Platform
 :ocp-version: 4.12
 :rhel-major: rhel-8
-:op-system-first: Red Hat Enterprise Linux (RHEL)
+:op-system-base-full: Red Hat Enterprise Linux (RHEL)
 :op-system: RHEL
 :op-system-ostree-first: Red Hat Enterprise Linux (RHEL) for Edge
 :op-system-ostree: RHEL for Edge
 :op-system-version: 8.7
 :op-system-version-major: 8
 :op-system-ram: 2GB RAM
-:op-system-chip: two-core AMD64 1.5GHz processor
 :op-system-bundle: Red Hat Device Edge
 :op-system-bundle-short: RHDE
-:VirtProductName: OpenShift Virtualization
+:VirtProductName: OpenShift Virtualization

_topic_maps/_topic_map_ms.yml

@@ -77,32 +77,21 @@ Topics:
     File: securitycontextconstraints-security-openshift-io-v1
 ---
 Name: CLI tools
-Dir: cli_reference
+Dir: microshift_cli_ref
 Distros: microshift
 Topics:
 - Name: CLI tools overview
-  File: index
-- Name: OpenShift CLI (oc)
-  Dir: openshift_cli
-  Topics:
-  - Name: Getting started with the OpenShift CLI
-    File: getting-started-cli
-  - Name: Configuring the OpenShift CLI
-    File: configuring-cli
-  # - Name: Managing CLI profiles
-  #   File: managing-cli-profiles
-  - Name: Extending the OpenShift CLI with plugins
-    File: extending-cli-plugins
-  # FIXME: auto-generated content in the next file includes commands
-  # not supported on MicroShift
-  - Name: OpenShift CLI developer command reference
-    File: developer-cli-commands
-  # FIXME: Review the commands we expect to support in this file
-  # - Name: OpenShift CLI administrator command reference
-  #   File: administrator-cli-commands
-  #   Distros: openshift-enterprise,openshift-origin
-  - Name: Usage of oc and kubectl commands
-    File: usage-oc-kubectl
+  File: microshift-cli-overview
+- Name: Installing the OpenShift CLI
+  File: microshift-oc-cli-install
+- Name: Configuring the OpenShift CLI
+  File: microshift-oc-config
+- Name: Using the OpenShift CLI
+  File: microshift-cli-using-oc
+- Name: Using oc and kubectl
+  File: microshift-usage-oc-kubectl
+- Name: List of oc CLI commands
+  File: microshift-oc-cli-commands-list
 ---
 Name: Configuring
 Dir: microshift_configuring

cli_reference/index.adoc

@@ -10,11 +10,9 @@ A user performs a range of operations while working on {product-title} such as t
 
 * Managing clusters
 * Building, deploying, and managing applications
-ifndef::microshift[]
 * Managing deployment processes
 * Developing Operators
 * Creating and maintaining Operator catalogs
-endif::[]
 
 {product-title} offers a set of command-line interface (CLI) tools that simplify these tasks by enabling users to perform various administration and development operations from the terminal.
 These tools expose simple commands to manage the applications, as well as interact with each component of the system.
@@ -24,17 +22,12 @@ These tools expose simple commands to manage the applications, as well as intera
 
 The following set of CLI tools are available in {product-title}:
 
-* xref:../cli_reference/openshift_cli/getting-started-cli.adoc#cli-getting-started[OpenShift CLI (oc)]: This is the most commonly used CLI tool by {product-title} users. It helps both cluster administrators and developers to perform end-to-end operations across {product-title} using the terminal. 
-ifndef::microshift[]
-Unlike the web console, it allows the user to work directly with the project source code using command scripts.
-endif::microshift[]
+* xref:../cli_reference/openshift_cli/getting-started-cli.adoc#cli-getting-started[OpenShift CLI (oc)]: This is the most commonly used CLI tool by {product-title} users. It helps both cluster administrators and developers to perform end-to-end operations across {product-title} using the terminal. Unlike the web console, it allows the user to work directly with the project source code using command scripts.
 
-ifndef::microshift[]
 * xref:../cli_reference/kn-cli-tools.adoc#kn-cli-tools[Knative CLI (kn)]: The Knative (`kn`) CLI tool provides simple and intuitive terminal commands that can be used to interact with OpenShift Serverless components, such as Knative Serving and Eventing.
 
 * xref:../cli_reference/tkn_cli/installing-tkn.adoc#installing-tkn[Pipelines CLI (tkn)]: OpenShift Pipelines is a continuous integration and continuous delivery (CI/CD) solution in {product-title}, which internally uses Tekton. The `tkn` CLI tool provides simple and intuitive commands to interact with OpenShift Pipelines using the terminal.
 
 * xref:../cli_reference/opm/cli-opm-install.adoc#cli-opm-install[opm CLI]: The `opm` CLI tool helps the Operator developers and cluster administrators to create and maintain the catalogs of Operators from the terminal.
 
 * xref:../cli_reference/osdk/cli-osdk-install.adoc#cli-osdk-install[Operator SDK]: The Operator SDK, a component of the Operator Framework, provides a CLI tool that Operator developers can use to build, test, and deploy an Operator from the terminal. It simplifies the process of building Kubernetes-native applications, which can require deep, application-specific operational knowledge.
-endif::microshift[]

cli_reference/openshift_cli/getting-started-cli.adoc

@@ -17,7 +17,6 @@ You can install the OpenShift CLI (`oc`) either by downloading the binary or by
 // Installing the CLI by downloading the binary
 include::modules/cli-installing-cli.adoc[leveloffset=+2]
 
-ifndef::microshift[]
 // Installing the CLI by using the web console
 include::modules/cli-installing-cli-web-console.adoc[leveloffset=+2]
 
@@ -29,7 +28,6 @@ include::modules/cli-installing-cli-web-console-windows.adoc[leveloffset=+3]
 
 // Installing the CLI on macOS by using the web console
 include::modules/cli-installing-cli-web-console-macos.adoc[leveloffset=+3]
-endif::microshift[]
 
 ifndef::openshift-origin[]
 // Installing the CLI by using an RPM
@@ -39,18 +37,14 @@ endif::[]
 // Installing the CLI by using Homebrew
 include::modules/cli-installing-cli-brew.adoc[leveloffset=+2]
 
-ifndef::microshift[]
 // Logging in to the CLI
 include::modules/cli-logging-in.adoc[leveloffset=+1]
-endif::[]
 
 // Using the CLI
 include::modules/cli-using-cli.adoc[leveloffset=+1]
 
 // Getting help
 include::modules/cli-getting-help.adoc[leveloffset=+1]
 
-ifndef::microshift[]
 // Logging out of the CLI
 include::modules/cli-logging-out.adoc[leveloffset=+1]
-endif::[]

microshift_cli_ref/_attributes

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

microshift_cli_ref/images

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

microshift_cli_ref/microshift-cli-overview.adoc

@@ -0,0 +1,26 @@
+:_content-type: ASSEMBLY
+[id="cli-tools-overview"]
+= {product-title} CLI tools
+include::_attributes/attributes-microshift.adoc[]
+:context: cli-tools-overview
+
+toc::[]
+
+A user builds, deploys, and manages boths applications and clusters while working with {product-title}.
+
+{product-title} can use different command-line interface (CLI) tools that simplify these tasks by enabling users to perform various administration and development operations from the terminal.
+These tools expose simple commands to manage the deployments, as well as interact with each component of the system.
+
+In addition to built-in `microshift` command types and Linux CLI tools, the optional OpenShift CLI (`oc`) tool with an enabled subset of commands is available for you to use if you are already familiar with {OCP} and Kubernetes.
+//more info on these tools is expected in the future, hence this overview assembly
+
+[role="_additional-resources"]
+[id="additional-resources_cli-tools-overview"]
+.Additional resources
+
+* link:https://access.redhat.com/documentation/en-us/microshift/4.12/html/microshift_cli_ref/microshift-cli-using-oc.adoc#microshift-cli-oc-about[Installing the `oc` tool for MicroShift].
+
+* link:https://access.redhat.com/documentation/en-us/openshift_container_platform/4.12/html/cli_tools/openshift-cli-oc[OpenShift CLI (oc)]: A full description of `oc` as provided by the {OCP} documentation. Commands focused on multi-node deployments, projects, and developer tooling are not supported by {product-title}.
+
+* link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/9[Red Hat Enterprise Linux (RHEL)]: The RHEL documentation for your specific use case.
+//NEED INFO: drill down to more specific links within RHEL docs

microshift_cli_ref/microshift-cli-using-oc.adoc

@@ -0,0 +1,84 @@
+:_content-type: ASSEMBLY
+[id="microshift-using-oc"]
+= Using the `oc` tool
+include::_attributes/attributes-microshift.adoc[]
+:context: microshift-using-oc
+
+toc::[]
+
+The optional OpenShift CLI (`oc`) tool is available for you to use if you are already familiar with {OCP} and Kubernetes.
+
+include::modules/microshift-cli-oc-about.adoc[leveloffset=+1]
+
+[id="cli-using-cli_{context}"]
+== Using the OpenShift CLI in {product-title}
+
+Review the following sections to learn how to complete common tasks in {product-title} using the `oc` CLI.
+
+[id="viewing-pods_{context}"]
+=== Viewing pods
+
+Use the `oc get pods` command to view the pods for the current project.
+
+[NOTE]
+====
+When you run `oc` inside a pod and do not specify a namespace, the namespace of the pod is used by default.
+====
+
+[source,terminal]
+----
+$ oc get pods -o wide
+----
+
+.Example output
+[source,terminal]
+----
+NAME                  READY   STATUS      RESTARTS   AGE     IP            NODE                           NOMINATED NODE
+cakephp-ex-1-build    0/1     Completed   0          5m45s   10.131.0.10   ip-10-0-141-74.ec2.internal    <none>
+cakephp-ex-1-deploy   0/1     Completed   0          3m44s   10.129.2.9    ip-10-0-147-65.ec2.internal    <none>
+cakephp-ex-1-ktz97    1/1     Running     0          3m33s   10.128.2.11   ip-10-0-168-105.ec2.internal   <none>
+----
+
+[id="viewing-pod-logs_{context}"]
+=== Viewing pod logs
+
+Use the `oc logs` command to view logs for a particular pod.
+
+[source,terminal]
+----
+$ oc logs cakephp-ex-1-deploy
+----
+
+.Example output
+[source,terminal]
+----
+--> Scaling cakephp-ex-1 to 1
+--> Success
+----
+
+[id="listing-supported-apis_{context}"]
+=== Listing supported API resources
+
+Use the `oc api-resources` command to view the list of supported API resources
+on the server.
+
+[source,terminal]
+----
+$ oc api-resources
+----
+
+.Example output
+[source,terminal]
+----
+NAME                                  SHORTNAMES       APIGROUP                              NAMESPACED   KIND
+bindings                                                                                     true         Binding
+componentstatuses                     cs                                                     false        ComponentStatus
+configmaps                            cm                                                     true         ConfigMap
+...
+----
+
+// Getting help
+include::modules/microshift-cli-oc-get-help.adoc[leveloffset=+1]
+
+//Errors when using oc commands not enabled in MicroShift
+include::modules/microshift-oc-apis-errors.adoc[leveloffset=+1]

microshift_cli_ref/microshift-oc-cli-commands-list.adoc

@@ -0,0 +1,20 @@
+:_content-type: ASSEMBLY
+[id="microshift-oc-cli-commands"]
+= OpenShift CLI command reference
+include::_attributes/attributes-microshift.adoc[]
+:context: cli-administrator-commands
+
+toc::[]
+
+This reference provides descriptions and example commands for OpenShift CLI (`oc`) commands. You must have `cluster-admin` or equivalent permissions to use these commands.
+
+Run `oc adm -h` to list all administrator commands or run `oc <command> --help` to get additional details for a specific command.
+
+[IMPORTANT]
+====
+Using `oc <command> --help` lists details for any `oc` command. Not all `oc` commands apply to using {product-title}.
+====
+
+// The OCP file is auto-generated from the openshift/oc repository; MicroShift is made manually
+// OpenShift CLI (oc) administrator commands
+include::modules/microshift-oc-by-example-content.adoc[leveloffset=+1]

microshift_cli_ref/microshift-oc-cli-install.adoc

@@ -0,0 +1,23 @@
+:_content-type: ASSEMBLY
+[id="cli-getting-started"]
+= Getting started with the OpenShift CLI
+include::_attributes/attributes-microshift.adoc[]
+:context: cli-oc-installing
+
+toc::[]
+
+To use the OpenShift CLI (`oc`) tool, you must download and install it separately from your {product-title} installation.
+
+[id="installing-the-openshift-cli_{context}"]
+== Installing the OpenShift CLI
+
+You can install the OpenShift CLI (`oc`) either by downloading the binary or by using Homebrew.
+
+// Installing the CLI by downloading the binary
+include::modules/cli-installing-cli.adoc[leveloffset=+2]
+
+// Installing the CLI by using Homebrew
+include::modules/cli-installing-cli-brew.adoc[leveloffset=+2]
+
+// Installing the CLI using RPM
+include::modules/cli-installing-cli-rpm.adoc[leveloffset=+2]