From 66a2dff9047d63aa5daf0cf22bb6b44efe56acaa Mon Sep 17 00:00:00 2001 From: xenolinux Date: Thu, 15 Jan 2026 14:52:42 +0530 Subject: [PATCH] OSDOCS#17273:CLI concepts and configuration --- .../microshift-cli-tools-introduction.adoc | 5 +- .../microshift-cli-using-oc.adoc | 69 +------------------ .../microshift-oc-cli-commands-list.adoc | 26 +------ .../microshift-oc-cli-install.adoc | 3 +- microshift_cli_ref/microshift-oc-config.adoc | 1 + .../microshift-usage-oc-kubectl.adoc | 1 + modules/cli-configuring-completion-zsh.adoc | 3 +- modules/cli-configuring-completion.adoc | 5 +- modules/cli-installing-cli-brew.adoc | 1 + modules/cli-installing-cli-rpm.adoc | 5 +- modules/microshift-cli-oc-about.adoc | 1 + modules/microshift-cli-oc-get-help.adoc | 1 + modules/microshift-cli-oc-logs.adoc | 62 +++++++++++++++++ modules/microshift-oc-apis-errors.adoc | 1 + modules/microshift-oc-cmd.adoc | 29 ++++++++ 15 files changed, 115 insertions(+), 98 deletions(-) create mode 100644 modules/microshift-cli-oc-logs.adoc create mode 100644 modules/microshift-oc-cmd.adoc diff --git a/microshift_cli_ref/microshift-cli-tools-introduction.adoc b/microshift_cli_ref/microshift-cli-tools-introduction.adoc index c433573938..e56ff4c32b 100644 --- a/microshift_cli_ref/microshift-cli-tools-introduction.adoc +++ b/microshift_cli_ref/microshift-cli-tools-introduction.adoc @@ -6,9 +6,10 @@ include::_attributes/attributes-microshift.adoc[] toc::[] +[role="_abstract"] You can use different command-line interface (CLI) tools to build, deploy, and manage a {microshift-short} node and workloads. With CLI tools, you can complete various administration and development operations from the terminal to manage deployments and interact with each component of the system. -CLI tools available for use with {microshift-short} are the following: +The following CLI tools are available to use with {microshift-short}: * Kubernetes CLI (`kubectl`) * The {oc-first} tool with an enabled subset of commands @@ -24,4 +25,4 @@ Commands for multi-node deployments, projects, and developer tools are not suppo == Additional resources * xref:../microshift_cli_ref/microshift-oc-cli-install.adoc#microshift-oc-cli-install[Getting started with the OpenShift CLI] -* link:https://docs.redhat.com/en/documentation/openshift_container_platform/{ocp-version}/html/cli_tools/openshift-cli-oc#cli-about-cli_cli-developer-commands[About the OpenShift CLI] ({OCP} documentation) +* link:https://docs.redhat.com/en/documentation/openshift_container_platform/{ocp-version}/html/cli_tools/openshift-cli-oc#cli-about-cli_cli-developer-commands[About the OpenShift CLI] diff --git a/microshift_cli_ref/microshift-cli-using-oc.adoc b/microshift_cli_ref/microshift-cli-using-oc.adoc index 4358acb59d..b95305b0d3 100644 --- a/microshift_cli_ref/microshift-cli-using-oc.adoc +++ b/microshift_cli_ref/microshift-cli-using-oc.adoc @@ -6,78 +6,15 @@ include::_attributes/attributes-microshift.adoc[] toc::[] +[role="_abstract"] The optional {oc-first} tool provides a subset of `oc` commands for {microshift-short} deployments. Using `oc` is convenient if you are familiar with {OCP} and Kubernetes. include::modules/microshift-cli-oc-about.adoc[leveloffset=+1] -[id="cli-using-cli_{context}"] -== Using oc with a {microshift-short} node - -Review the following sections to learn how to complete common tasks in {microshift-short} 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 -cakephp-ex-1-deploy 0/1 Completed 0 3m44s 10.129.2.9 ip-10-0-147-65.ec2.internal -cakephp-ex-1-ktz97 1/1 Running 0 3m33s 10.128.2.11 ip-10-0-168-105.ec2.internal ----- - -[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 -... ----- +include::modules/microshift-cli-oc-logs.adoc[leveloffset=+1] // 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] \ No newline at end of file +include::modules/microshift-oc-apis-errors.adoc[leveloffset=+1] diff --git a/microshift_cli_ref/microshift-oc-cli-commands-list.adoc b/microshift_cli_ref/microshift-oc-cli-commands-list.adoc index b5fd6d41da..378af0671d 100644 --- a/microshift_cli_ref/microshift-oc-cli-commands-list.adoc +++ b/microshift_cli_ref/microshift-oc-cli-commands-list.adoc @@ -6,30 +6,10 @@ include::_attributes/attributes-microshift.adoc[] toc::[] -Descriptions and example commands for {oc-first} commands are included in this reference document. You must have `cluster-admin` or equivalent permissions to use these commands. To list administrator commands and information about them, use the following commands: +[role="_abstract"] +Descriptions and example commands for {oc-first} commands are included in this reference document. You must have `cluster-admin` or equivalent permissions to use these commands. -* Enter the `oc adm -h` command to list all administrator commands: -+ -.Command syntax -+ -[source,terminal] ----- -$ oc adm -h ----- - -* Enter the `oc --help` command to get additional details for a specific command: -+ -.Command syntax -+ -[source,terminal] ----- -$ oc --help ----- - -[IMPORTANT] -==== -Using `oc --help` lists details for any `oc` command. Not all `oc` commands apply to using {product-title}. -==== +include::modules/microshift-oc-cmd.adoc[leveloffset=+1] // The OCP files are auto-generated from the openshift/oc repository; use the MicroShift-specific flags to generate MicroShift command files from the same repo include::modules/microshift-oc-by-example-content.adoc[leveloffset=+1] diff --git a/microshift_cli_ref/microshift-oc-cli-install.adoc b/microshift_cli_ref/microshift-oc-cli-install.adoc index 97a8c89cc0..d502481dce 100644 --- a/microshift_cli_ref/microshift-oc-cli-install.adoc +++ b/microshift_cli_ref/microshift-oc-cli-install.adoc @@ -6,6 +6,7 @@ include::_attributes/attributes-microshift.adoc[] toc::[] +[role="_abstract"] To use the {oc-first} tool, you must download and install it separately from your {microshift-short} installation. You can install `oc` by downloading the binary or by using Homebrew. // Installing the OpenShift CLI on Linux @@ -21,4 +22,4 @@ include::modules/cli-installing-cli-macos.adoc[leveloffset=+1] include::modules/cli-installing-cli-brew.adoc[leveloffset=+1] // Installing the CLI using RPM -include::modules/cli-installing-cli-rpm.adoc[leveloffset=+1] \ No newline at end of file +include::modules/cli-installing-cli-rpm.adoc[leveloffset=+1] diff --git a/microshift_cli_ref/microshift-oc-config.adoc b/microshift_cli_ref/microshift-oc-config.adoc index 6cdf1fe13d..a814678caf 100644 --- a/microshift_cli_ref/microshift-oc-config.adoc +++ b/microshift_cli_ref/microshift-oc-config.adoc @@ -6,6 +6,7 @@ include::_attributes/attributes-microshift.adoc[] toc::[] +[role="_abstract"] Configure {oc-first} based on your preferences for working with it. [id="cli-enabling-tab-completion"] diff --git a/microshift_cli_ref/microshift-usage-oc-kubectl.adoc b/microshift_cli_ref/microshift-usage-oc-kubectl.adoc index 2b1c3e6ce6..77bc0f9acc 100644 --- a/microshift_cli_ref/microshift-usage-oc-kubectl.adoc +++ b/microshift_cli_ref/microshift-usage-oc-kubectl.adoc @@ -6,6 +6,7 @@ include::_attributes/attributes-microshift.adoc[] toc::[] +[role="_abstract"] The Kubernetes command-line interface (CLI), `kubectl`, can be used to run commands against a Kubernetes cluster. Because {microshift-short} is a certified Kubernetes distribution, you can use the supported `kubectl` CLI tool or you can gain extended functionality by using the {oc-first}. [id="microshift-kubectl-binary_{context}"] diff --git a/modules/cli-configuring-completion-zsh.adoc b/modules/cli-configuring-completion-zsh.adoc index 47fa440c32..70925eb25e 100644 --- a/modules/cli-configuring-completion-zsh.adoc +++ b/modules/cli-configuring-completion-zsh.adoc @@ -6,6 +6,7 @@ [id="cli-enabling-tab-completion-zsh_{context}"] = Enabling tab completion for Zsh +[role="_abstract"] After you install the OpenShift CLI (`oc`), you can enable tab completion to automatically complete `oc` commands or suggest options when you press Tab. The following procedure enables tab completion for the Zsh shell. .Prerequisites @@ -27,5 +28,5 @@ if [ $commands[oc] ]; then fi EOF ---- - ++ Tab completion is enabled when you open a new terminal. diff --git a/modules/cli-configuring-completion.adoc b/modules/cli-configuring-completion.adoc index af3f61f1eb..e1695967dd 100644 --- a/modules/cli-configuring-completion.adoc +++ b/modules/cli-configuring-completion.adoc @@ -6,6 +6,7 @@ [id="cli-enabling-tab-completion_{context}"] = Enabling tab completion for Bash +[role="_abstract"] After you install the OpenShift CLI (`oc`), you can enable tab completion to automatically complete `oc` commands or suggest options when you press Tab. The following procedure enables tab completion for the Bash shell. .Prerequisites @@ -29,6 +30,4 @@ $ oc completion bash > oc_bash_completion $ sudo cp oc_bash_completion /etc/bash_completion.d/ ---- + -You can also save the file to a local directory and source it from your `.bashrc` file instead. - -Tab completion is enabled when you open a new terminal. +You can also save the file to a local directory and source it from your `.bashrc` file instead. Tab completion is enabled when you open a new terminal. diff --git a/modules/cli-installing-cli-brew.adoc b/modules/cli-installing-cli-brew.adoc index 90abc65fe4..99194464ab 100644 --- a/modules/cli-installing-cli-brew.adoc +++ b/modules/cli-installing-cli-brew.adoc @@ -7,6 +7,7 @@ [id="cli-installing-cli-brew_{context}"] = Installing the OpenShift CLI by using Homebrew +[role="_abstract"] For macOS, you can install the OpenShift CLI (`oc`) by using the link:https://brew.sh[Homebrew] package manager. .Prerequisites diff --git a/modules/cli-installing-cli-rpm.adoc b/modules/cli-installing-cli-rpm.adoc index e9956c6184..9e5ca1f470 100644 --- a/modules/cli-installing-cli-rpm.adoc +++ b/modules/cli-installing-cli-rpm.adoc @@ -7,6 +7,7 @@ [id="cli-installing-cli-rpm_{context}"] = Installing the OpenShift CLI by using an RPM +[role="_abstract"] For {op-system-base-full}, you can install the {oc-first} as an RPM if you have an active {product-title} subscription on your Red Hat account. [IMPORTANT] @@ -16,7 +17,7 @@ You must install `oc` for {op-system-base} 9 by downloading the binary. Installi .Prerequisites -* Must have root or sudo privileges. +* You must have root or sudo privileges. .Procedure @@ -78,7 +79,7 @@ endif::openshift-rosa[] .Verification * Verify your installation by using an `oc` command: - ++ [source,terminal] ---- $ oc diff --git a/modules/microshift-cli-oc-about.adoc b/modules/microshift-cli-oc-about.adoc index 80a345b3e8..2fd4da0066 100644 --- a/modules/microshift-cli-oc-about.adoc +++ b/modules/microshift-cli-oc-about.adoc @@ -6,6 +6,7 @@ [id="microshift-cli-oc-about_{context}"] = About the OpenShift CLI +[role="_abstract"] With the OpenShift command-line interface (CLI), the `oc` command, you can deploy and manage {microshift-short} projects from a terminal. The CLI `oc` tool is ideal in the following situations: * Working directly with project source code diff --git a/modules/microshift-cli-oc-get-help.adoc b/modules/microshift-cli-oc-get-help.adoc index cf2999bdea..e3d5126099 100644 --- a/modules/microshift-cli-oc-get-help.adoc +++ b/modules/microshift-cli-oc-get-help.adoc @@ -6,6 +6,7 @@ [id="cli-getting-help_{context}"] = Getting help +[role="_abstract"] You can get help with CLI commands and {microshift-short} resources in the following ways. * Use `oc help --flag` to get information about a specific CLI command: diff --git a/modules/microshift-cli-oc-logs.adoc b/modules/microshift-cli-oc-logs.adoc new file mode 100644 index 0000000000..7897d532a3 --- /dev/null +++ b/modules/microshift-cli-oc-logs.adoc @@ -0,0 +1,62 @@ +// Module included in the following assemblies: +// +// * microshift-cli-using-oc/microshift-oc-apis-errors.adoc + +:_mod-docs-content-type: CONCEPT +[id="cli-using-cli_{context}"] += Using oc with a {microshift-short} node + +[role="_abstract"] +You can complete common tasks in {microshift-short} by using the `oc` CLI. + +[NOTE] +==== +When you run `oc` inside a pod and do not specify a namespace, the namespace of the pod is used by default. +==== + +* To view the pods for the current project, run the `oc get pods` command: ++ +[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 +cakephp-ex-1-deploy 0/1 Completed 0 3m44s 10.129.2.9 ip-10-0-147-65.ec2.internal +cakephp-ex-1-ktz97 1/1 Running 0 3m33s 10.128.2.11 ip-10-0-168-105.ec2.internal +---- + +* To view logs for a particular pod, run the `oc logs` command: ++ +[source,terminal] +---- +$ oc logs cakephp-ex-1-deploy +---- ++ +.Example output +[source,terminal] +---- +--> Scaling cakephp-ex-1 to 1 +--> Success +---- + +* To view the list of supported API resources on the server, run the `oc api-resources` command: ++ +[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 +... +---- diff --git a/modules/microshift-oc-apis-errors.adoc b/modules/microshift-oc-apis-errors.adoc index 6cfbc618a8..7dd2c840ef 100644 --- a/modules/microshift-oc-apis-errors.adoc +++ b/modules/microshift-oc-apis-errors.adoc @@ -6,6 +6,7 @@ [id="microshift-oc-apis-errors_{context}"] = oc command errors in {microshift-short} +[role="_abstract"] Not all {oc-first} commands are relevant for {microshift-short} deployments. When you use `oc` to make a request call against an unsupported API, the `oc` binary usually generates an error message about a resource that cannot be found. * For example, when you run the following `new-project` command: diff --git a/modules/microshift-oc-cmd.adoc b/modules/microshift-oc-cmd.adoc new file mode 100644 index 0000000000..ea695b7794 --- /dev/null +++ b/modules/microshift-oc-cmd.adoc @@ -0,0 +1,29 @@ +// Module included in the following assemblies: +// +// * microshift_cli_ref/microshift-oc-cli-commands.adoc + +:_mod-docs-content-type: CONCEPT +[id="microshift-oc-cmd_{context}"] += OpenShift administrator commands + +[role="_abstract"] +If you have `cluster-admin` or equivalent permissions, you can list administrator commands. + +* Enter the `oc adm -h` command to list all administrator commands: ++ +[source,terminal] +---- +$ oc adm -h +---- + +* Enter the `oc --help` command to get additional details for a specific command: ++ +[source,terminal] +---- +$ oc --help +---- ++ +[IMPORTANT] +==== +Using `oc --help` lists details for any `oc` command. Not all `oc` commands apply to using {product-title}. +====