From f2c8361ee1dce1190f9ed4ad3cbc18fbfd68d1c9 Mon Sep 17 00:00:00 2001 From: Andrea Hoffer Date: Thu, 29 Jan 2026 15:48:29 -0500 Subject: [PATCH] OSDOCS#16913: CQA for oc CLI docs --- .../openshift_cli/getting-started-cli.adoc | 42 ++++-- .../openshift_cli/usage-oc-kubectl.adoc | 84 ++--------- .../microshift-cli-tools-introduction.adoc | 2 +- modules/cli-about-cli.adoc | 11 +- modules/cli-getting-help.adoc | 6 +- modules/cli-installing-cli-binary.adoc | 10 ++ modules/cli-installing-cli-brew.adoc | 9 +- modules/cli-installing-cli-linux.adoc | 2 +- modules/cli-installing-cli-macos.adoc | 2 +- .../cli-installing-cli-web-console-linux.adoc | 7 +- .../cli-installing-cli-web-console-macos.adoc | 7 +- ...li-installing-cli-web-console-windows.adoc | 7 +- modules/cli-installing-cli-web-console.adoc | 7 +- modules/cli-installing-cli-windows.adoc | 2 +- modules/cli-installing-cli.adoc | 17 +++ modules/cli-logging-in-web.adoc | 12 +- modules/cli-logging-in.adoc | 31 ++-- modules/cli-logging-out.adoc | 12 +- modules/cli-using-cli-current-project.adoc | 25 +++ modules/cli-using-cli-list-api-resources.adoc | 29 ++++ modules/cli-using-cli-new-app.adoc | 29 ++++ modules/cli-using-cli-pod-logs.adoc | 26 ++++ modules/cli-using-cli-pods.adoc | 33 ++++ modules/cli-using-cli-project-status.adoc | 32 ++++ modules/cli-using-cli-project.adoc | 25 +++ modules/cli-using-cli.adoc | 142 +----------------- modules/oc-usage-kubectl.adoc | 12 ++ modules/oc-usage-oc.adoc | 62 ++++++++ .../v1x/preparing-ossm-installation.adoc | 2 +- .../v2x/preparing-ossm-installation.adoc | 2 +- tutorials/dev-app-cli.adoc | 2 +- 31 files changed, 427 insertions(+), 264 deletions(-) create mode 100644 modules/cli-installing-cli-binary.adoc create mode 100644 modules/cli-installing-cli.adoc create mode 100644 modules/cli-using-cli-current-project.adoc create mode 100644 modules/cli-using-cli-list-api-resources.adoc create mode 100644 modules/cli-using-cli-new-app.adoc create mode 100644 modules/cli-using-cli-pod-logs.adoc create mode 100644 modules/cli-using-cli-pods.adoc create mode 100644 modules/cli-using-cli-project-status.adoc create mode 100644 modules/cli-using-cli-project.adoc create mode 100644 modules/oc-usage-kubectl.adoc create mode 100644 modules/oc-usage-oc.adoc diff --git a/cli_reference/openshift_cli/getting-started-cli.adoc b/cli_reference/openshift_cli/getting-started-cli.adoc index 180f97c80144..7711d6f53534 100644 --- a/cli_reference/openshift_cli/getting-started-cli.adoc +++ b/cli_reference/openshift_cli/getting-started-cli.adoc @@ -3,28 +3,32 @@ = Getting started with the OpenShift CLI include::_attributes/common-attributes.adoc[] include::_attributes/attributes-openshift-dedicated.adoc[] -:context: cli-developer-commands +:context: getting-started-cli toc::[] +[role="_abstract"] +Install and configure the {oc-first} to manage {product-title} clusters and deploy applications directly from a terminal. + // About the CLI include::modules/cli-about-cli.adoc[leveloffset=+1] -[id="installing-openshift-cli"] -== Installing the OpenShift CLI +// Installing the OpenShift CLI +include::modules/cli-installing-cli.adoc[leveloffset=+1] -You can install the OpenShift CLI (`oc`) either by downloading the binary or by using an RPM. +// Installing the OpenShift CLI by downloading the binary from the Customer Portal +include::modules/cli-installing-cli-binary.adoc[leveloffset=+2] // Installing the OpenShift CLI on Linux -include::modules/cli-installing-cli-linux.adoc[leveloffset=+1] +include::modules/cli-installing-cli-linux.adoc[leveloffset=+3] // Installing the OpenShift CLI on Windows -include::modules/cli-installing-cli-windows.adoc[leveloffset=+1] +include::modules/cli-installing-cli-windows.adoc[leveloffset=+3] // Installing the OpenShift CLI on macOS -include::modules/cli-installing-cli-macos.adoc[leveloffset=+1] +include::modules/cli-installing-cli-macos.adoc[leveloffset=+3] -// Installing the CLI by using the web console +// Installing the OpenShift CLI by downloading the binary from the web console include::modules/cli-installing-cli-web-console.adoc[leveloffset=+2] // Installing the CLI on Linux by using the web console @@ -39,7 +43,6 @@ include::modules/cli-installing-cli-web-console-macos.adoc[leveloffset=+3] ifndef::openshift-origin[] // Installing the CLI by using an RPM include::modules/cli-installing-cli-rpm.adoc[leveloffset=+2] - endif::[] // Installing the CLI by using Homebrew @@ -54,6 +57,27 @@ include::modules/cli-logging-in-web.adoc[leveloffset=+1] // Using the CLI include::modules/cli-using-cli.adoc[leveloffset=+1] +// Creating a project +include::modules/cli-using-cli-project.adoc[leveloffset=+2] + +// Creating a new application +include::modules/cli-using-cli-new-app.adoc[leveloffset=+2] + +// Viewing pods +include::modules/cli-using-cli-pods.adoc[leveloffset=+2] + +// Viewing pod logs +include::modules/cli-using-cli-pod-logs.adoc[leveloffset=+2] + +// Viewing the current project +include::modules/cli-using-cli-current-project.adoc[leveloffset=+2] + +// Viewing the status of the current project +include::modules/cli-using-cli-project-status.adoc[leveloffset=+2] + +// Listing supported API resources +include::modules/cli-using-cli-list-api-resources.adoc[leveloffset=+2] + // Getting help include::modules/cli-getting-help.adoc[leveloffset=+1] diff --git a/cli_reference/openshift_cli/usage-oc-kubectl.adoc b/cli_reference/openshift_cli/usage-oc-kubectl.adoc index 7ba04aadb83f..0d8f35133af1 100644 --- a/cli_reference/openshift_cli/usage-oc-kubectl.adoc +++ b/cli_reference/openshift_cli/usage-oc-kubectl.adoc @@ -4,78 +4,24 @@ include::_attributes/common-attributes.adoc[] :context: usage-oc-kubectl -The Kubernetes command-line interface (CLI), `kubectl`, can be used to run commands against a Kubernetes cluster. Because {product-title} is a certified Kubernetes distribution, you can use the supported `kubectl` binaries that ship with -{product-title}, or you can gain extended functionality by using the `oc` binary. +[role="_abstract"] +Because {product-title} is a certified Kubernetes distribution, you can use the Kubernetes CLI (`kubectl`) that ships with {product-title} to interact with your cluster. You can also gain extended functionality specific to {product-title} by using the {oc-first} binary. -== The oc binary +// The oc binary +include::modules/oc-usage-oc.adoc[leveloffset=+1] -The `oc` binary offers the same capabilities as the `kubectl` binary, but it extends to natively support additional -{product-title} features, including: +ifndef::openshift-rosa,openshift-rosa-hcp,openshift-dedicated[] +[role="_additional-resources"] +.Additional resources -* **Full support for {product-title} resources** -+ -Resources such as `DeploymentConfig`, `BuildConfig`, `Route`, `ImageStream`, and `ImageStreamTag` objects are specific to -{product-title} -distributions, and build upon standard Kubernetes primitives. -+ -* **Authentication** -+ -ifndef::microshift,openshift-rosa,openshift-rosa-hcp,openshift-dedicated[] -The `oc` binary offers a built-in `login` command for authentication and lets you work with projects, which map Kubernetes namespaces to authenticated users. -Read xref:../../authentication/understanding-authentication.adoc#understanding-authentication[Understanding authentication] for more information. -endif::microshift,openshift-rosa,openshift-rosa-hcp,openshift-dedicated[] -+ -ifdef::microshift[] -The `oc` binary offers a built-in `login` command for authentication to {product-title}. -endif::[] -+ -* **Additional commands** -+ -The additional command `oc new-app`, for example, makes it easier to get new applications started using existing source code or pre-built images. Similarly, the additional command `oc new-project` makes it easier to start a project that you can switch to as your default. +* xref:../../authentication/understanding-authentication.adoc#understanding-authentication[Understanding authentication] +endif::openshift-rosa,openshift-rosa-hcp,openshift-dedicated[] -[IMPORTANT] -==== -If you installed an earlier version of the `oc` binary, you cannot use it to complete all of the commands in -ifndef::openshift-rosa,openshift-rosa-hcp[] -{product-title} {product-version} -endif::openshift-rosa,openshift-rosa-hcp[] -ifdef::openshift-rosa,openshift-rosa-hcp[] -{product-title} -endif::openshift-rosa,openshift-rosa-hcp[] -. If you want the latest features, you must download and install the latest version of the `oc` binary corresponding to your {product-title} server version. -==== +// The kubectl binary +include::modules/oc-usage-kubectl.adoc[leveloffset=+1] -Non-security API changes will involve, at minimum, two minor releases (4.1 to 4.2 to 4.3, for example) to allow older `oc` binaries to update. Using new capabilities might require newer `oc` binaries. A 4.3 server might have additional capabilities that a 4.2 `oc` binary cannot use and a 4.3 `oc` binary might have additional capabilities that are unsupported by a 4.2 server. +[role="_additional-resources"] +.Additional resources -.Compatibility Matrix - -[cols="1,1,1"] -|=== - -| -|*X.Y* (`oc` Client) -|*X.Y+N* footnote:versionpolicyn[Where *N* is a number greater than or equal to 1.] (`oc` Client) - -|*X.Y* (Server) -|image:redcircle-1.png[] -|image:redcircle-3.png[] - -|*X.Y+N* footnote:versionpolicyn[] (Server) -|image:redcircle-2.png[] -|image:redcircle-1.png[] - -|=== -image:redcircle-1.png[] Fully compatible. - -image:redcircle-2.png[] `oc` client might not be able to access server features. - -image:redcircle-3.png[] `oc` client might provide options and features that might not be compatible with the accessed server. - -== The kubectl binary - -The `kubectl` binary is provided as a means to support existing workflows and scripts for new -{product-title} users coming from a standard Kubernetes environment, or for those who prefer to use the `kubectl` CLI. Existing users of `kubectl` can continue to use the binary to interact with Kubernetes primitives, with no changes required to the {product-title} cluster. - -You can install the supported `kubectl` binary by following the steps to xref:../../cli_reference/openshift_cli/getting-started-cli.adoc#cli-installing-cli-linux_cli-developer-commands[Install the OpenShift CLI]. The `kubectl` binary is included in the archive if you download the binary, or is installed when you install the CLI by using an RPM. - -For more information, see the link:https://kubernetes.io/docs/reference/kubectl/overview/[kubectl documentation]. +* link:https://kubernetes.io/docs/reference/kubectl/overview/[kubectl (Kubernetes documentation)] +* xref:../../cli_reference/openshift_cli/getting-started-cli.adoc#cli-installing-cli_getting-started-cli[Installing the OpenShift CLI] diff --git a/microshift_cli_ref/microshift-cli-tools-introduction.adoc b/microshift_cli_ref/microshift-cli-tools-introduction.adoc index e56ff4c32ba3..cc6961cf3631 100644 --- a/microshift_cli_ref/microshift-cli-tools-introduction.adoc +++ b/microshift_cli_ref/microshift-cli-tools-introduction.adoc @@ -25,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] +* link:https://docs.redhat.com/en/documentation/openshift_container_platform/{ocp-version}/html/cli_tools/openshift-cli-oc#cli-about-cli_getting-started-cli[About the OpenShift CLI] diff --git a/modules/cli-about-cli.adoc b/modules/cli-about-cli.adoc index c291fedaab6a..e76a2ac34775 100644 --- a/modules/cli-about-cli.adoc +++ b/modules/cli-about-cli.adoc @@ -6,13 +6,16 @@ [id="cli-about-cli_{context}"] = About the OpenShift CLI -With the {oc-first}, you can create applications and manage {product-title} projects from a terminal. The OpenShift CLI is ideal in the following situations: +[role="_abstract"] +With the {oc-first}, you can create applications and manage {product-title} projects from a terminal. -* Working directly with project source code. +The OpenShift CLI is ideal in the following situations: + +* Working directly with project source code * Scripting {product-title} operations ifndef::microshift[] -* Managing projects while restricted by bandwidth resources and the web console is unavailable. +* Managing projects while restricted by bandwidth resources and the web console is unavailable endif::microshift[] ifdef::microshift[] -* Managing projects while restricted by bandwidth resources. +* Managing projects while restricted by bandwidth resources endif::microshift[] diff --git a/modules/cli-getting-help.adoc b/modules/cli-getting-help.adoc index c7890631784d..6f1fb41437b0 100644 --- a/modules/cli-getting-help.adoc +++ b/modules/cli-getting-help.adoc @@ -6,8 +6,10 @@ [id="cli-getting-help_{context}"] = Getting help -You can get help with CLI commands and {product-title} -resources in the following ways: +[role="_abstract"] +Review the ways to get help with CLI commands and {product-title} resources. + +.Procedure * Use `oc help` to get a list and description of all available CLI commands: + diff --git a/modules/cli-installing-cli-binary.adoc b/modules/cli-installing-cli-binary.adoc new file mode 100644 index 000000000000..3ffb580352e2 --- /dev/null +++ b/modules/cli-installing-cli-binary.adoc @@ -0,0 +1,10 @@ +// Module included in the following assemblies: +// +// * cli_reference/openshift_cli/getting-started.adoc + +:_mod-docs-content-type: CONCEPT +[id="cli-installing-cli-binary_{context}"] += Installing the OpenShift CLI by downloading the binary from the Customer Portal + +[role="_abstract"] +You can download the {oc-first} from the Red{nbsp}Hat Customer Portal and install it to interact with {product-title} clusters from a terminal on Linux, Windows, or macOS. diff --git a/modules/cli-installing-cli-brew.adoc b/modules/cli-installing-cli-brew.adoc index 99194464ab20..75bc9e9271f3 100644 --- a/modules/cli-installing-cli-brew.adoc +++ b/modules/cli-installing-cli-brew.adoc @@ -8,7 +8,7 @@ = 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. +For macOS, you can install the OpenShift CLI (`oc`) by using the Homebrew package manager. .Prerequisites @@ -26,8 +26,13 @@ $ brew install openshift-cli .Verification * Verify your installation by using an `oc` command: - ++ [source,terminal] ---- $ oc ---- + +[role="_additional-resources"] +.Additional resources + +* link:https://brew.sh[Homebrew package manager] diff --git a/modules/cli-installing-cli-linux.adoc b/modules/cli-installing-cli-linux.adoc index 335f4f627917..8b1fa4a8f69d 100644 --- a/modules/cli-installing-cli-linux.adoc +++ b/modules/cli-installing-cli-linux.adoc @@ -57,7 +57,7 @@ endif::[] = Installing the OpenShift CLI on Linux [role="_abstract"] -To manage your cluster and deploy applications from the command line, install the {oc-first} binary on Linux. +To manage your cluster and deploy applications from the command line on Linux, install the {oc-first} binary. You can download the {oc-first} from the Red{nbsp} Customer Portal. [IMPORTANT] ==== diff --git a/modules/cli-installing-cli-macos.adoc b/modules/cli-installing-cli-macos.adoc index a85b4f9b399d..6668120f3dc7 100644 --- a/modules/cli-installing-cli-macos.adoc +++ b/modules/cli-installing-cli-macos.adoc @@ -57,7 +57,7 @@ endif::[] = Installing the OpenShift CLI on macOS [role="_abstract"] -To manage your cluster and deploy applications from the command line, install the {oc-first} binary on macOS. +To manage your cluster and deploy applications from the command line on macOS, install the {oc-first} binary. You can download the {oc-first} from the Red{nbsp} Customer Portal. [IMPORTANT] ==== diff --git a/modules/cli-installing-cli-web-console-linux.adoc b/modules/cli-installing-cli-web-console-linux.adoc index bbd2583633fb..86be90abe10c 100644 --- a/modules/cli-installing-cli-web-console-linux.adoc +++ b/modules/cli-installing-cli-web-console-linux.adoc @@ -6,7 +6,8 @@ endif::[] [id="cli-installing-cli-web-console-macos-linux_{context}"] = Installing the OpenShift CLI on Linux using the web console -You can install the OpenShift CLI (`oc`) binary on Linux by using the following procedure. +[role="_abstract"] +To manage your cluster and deploy applications from the command line on Linux, install the {oc-first} binary. You can download the {oc-first} from the web console. .Procedure ifndef::openshift-rosa,openshift-dedicated[] @@ -41,8 +42,10 @@ To check your `PATH`, execute the following command: $ echo $PATH ---- -After you install the OpenShift CLI, it is available using the `oc` command: +.Verification +* After you install the OpenShift CLI, it is available using the `oc` command: ++ [source,terminal] ---- $ oc diff --git a/modules/cli-installing-cli-web-console-macos.adoc b/modules/cli-installing-cli-web-console-macos.adoc index f2285cdb8913..afb2c1dbbe56 100644 --- a/modules/cli-installing-cli-web-console-macos.adoc +++ b/modules/cli-installing-cli-web-console-macos.adoc @@ -6,7 +6,8 @@ ifeval::["{context}" == "updating-restricted-network-cluster"] :restricted: endif::[] -You can install the OpenShift CLI (`oc`) binary on macOS by using the following procedure. +[role="_abstract"] +To manage your cluster and deploy applications from the command line on macOS, install the {oc-first} binary. You can download the {oc-first} from the web console. .Procedure ifndef::openshift-rosa,openshift-dedicated[] @@ -40,8 +41,10 @@ To check your `PATH`, open a terminal and execute the following command: $ echo $PATH ---- -After you install the OpenShift CLI, it is available using the `oc` command: +.Verification +* After you install the OpenShift CLI, it is available using the `oc` command: ++ [source,terminal] ---- $ oc diff --git a/modules/cli-installing-cli-web-console-windows.adoc b/modules/cli-installing-cli-web-console-windows.adoc index 475e51e06bf6..5c1440b4735c 100644 --- a/modules/cli-installing-cli-web-console-windows.adoc +++ b/modules/cli-installing-cli-web-console-windows.adoc @@ -6,7 +6,8 @@ endif::[] [id="cli-installing-cli-web-console-macos-windows_{context}"] = Installing the OpenShift CLI on Windows using the web console -You can install the OpenShift CLI (`oc`) binary on Windows by using the following procedure. +[role="_abstract"] +To manage your cluster and deploy applications from the command line on Windows, install the {oc-first} binary. You can download the {oc-first} from the web console. .Procedure ifndef::openshift-rosa,openshift-dedicated[] @@ -35,8 +36,10 @@ To check your `PATH`, open the command prompt and execute the following command: C:\> path ---- -After you install the OpenShift CLI, it is available using the `oc` command: +.Verification +* After you install the OpenShift CLI, it is available using the `oc` command: ++ [source,terminal] ---- C:\> oc diff --git a/modules/cli-installing-cli-web-console.adoc b/modules/cli-installing-cli-web-console.adoc index 0abac6a6af46..cfa366fe6570 100644 --- a/modules/cli-installing-cli-web-console.adoc +++ b/modules/cli-installing-cli-web-console.adoc @@ -2,11 +2,12 @@ ifeval::["{context}" == "updating-restricted-network-cluster"] :restricted: endif::[] -:_mod-docs-content-type: PROCEDURE +:_mod-docs-content-type: CONCEPT [id="cli-installing-cli-web-console_{context}"] -= Installing the OpenShift CLI by using the web console += Installing the OpenShift CLI by downloading the binary from the web console -You can install the {oc-first} to interact with {product-title} clusters from a web console. You can install `oc` on Linux, Windows, or macOS. +[role="_abstract"] +You can download the {oc-first} from the web {product-title} console and install it to interact with {product-title} clusters from a terminal on Linux, Windows, or macOS. [IMPORTANT] ==== diff --git a/modules/cli-installing-cli-windows.adoc b/modules/cli-installing-cli-windows.adoc index c2460133c155..e152a7516c73 100644 --- a/modules/cli-installing-cli-windows.adoc +++ b/modules/cli-installing-cli-windows.adoc @@ -57,7 +57,7 @@ endif::[] = Installing the OpenShift CLI on Windows [role="_abstract"] -To manage your cluster and deploy applications from the command line, install {oc-first} binary on Windows. +To manage your cluster and deploy applications from the command line on Windows, install the {oc-first} binary. You can download the {oc-first} from the Red{nbsp} Customer Portal. [IMPORTANT] ==== diff --git a/modules/cli-installing-cli.adoc b/modules/cli-installing-cli.adoc new file mode 100644 index 000000000000..d6c876052aa5 --- /dev/null +++ b/modules/cli-installing-cli.adoc @@ -0,0 +1,17 @@ +// Module included in the following assemblies: +// +// * cli_reference/openshift_cli/getting-started.adoc + +:_mod-docs-content-type: CONCEPT +[id="cli-installing-cli_{context}"] += Installing the OpenShift CLI + +ifndef::openshift-origin[] +[role="_abstract"] +To interact with a {product-title} cluster from the terminal, install the {oc-first}. Depending on your operating system, you can install {oc-first} by downloading the binary from the Customer Portal or web console, by using an RPM, or by using Homebrew. +endif::[] + +ifdef::openshift-origin[] +[role="_abstract"] +To interact with a {product-title} cluster from the terminal, install the {oc-first}. Depending on your operating system, you can install {oc-first} by downloading the binary from the Customer Portal or web console, or by using Homebrew. +endif::[] diff --git a/modules/cli-logging-in-web.adoc b/modules/cli-logging-in-web.adoc index 157aa21c7e77..4ed51c8cd207 100644 --- a/modules/cli-logging-in-web.adoc +++ b/modules/cli-logging-in-web.adoc @@ -6,6 +6,7 @@ [id="cli-logging-in-web_{context}"] = Logging in to the OpenShift CLI using a web browser +[role="_abstract"] You can log in to the OpenShift CLI (`oc`) with the help of a web browser to access and manage your cluster. This allows users to avoid inserting their access token into the command line. [WARNING] @@ -25,9 +26,10 @@ Logging in to the CLI through the web browser runs a server on localhost with HT + [source,terminal] ---- -$ oc login --web <1> +$ oc login --web ---- -<1> Optionally, you can specify the server URL and callback port. For example, `oc login --web --callback-port 8280 localhost:8443`. ++ +Optionally, you can specify the server URL and callback port. For example, `oc login --web --callback-port 8280 localhost:8443`. . The web browser opens automatically. If it does not, click the link in the command output. If you do not specify the {product-title} server `oc` tries to open the web console of the cluster specified in the current `oc` configuration file. If no `oc` configuration exists, `oc` prompts interactively for the server URL. + @@ -56,10 +58,10 @@ You don't have any projects. You can try to create a new project, by running oc new-project ---- - ++ [NOTE] ==== The web console defaults to the profile used in the previous session. To switch between Administrator and Developer profiles, log out of the {product-title} web console and clear the cache. ==== - -You can now create a project or issue other commands for managing your cluster. \ No newline at end of file ++ +You can now create a project or issue other commands for managing your cluster. diff --git a/modules/cli-logging-in.adoc b/modules/cli-logging-in.adoc index 1b5976c4ff38..48448a0dbfce 100644 --- a/modules/cli-logging-in.adoc +++ b/modules/cli-logging-in.adoc @@ -6,13 +6,9 @@ [id="cli-logging-in_{context}"] = Logging in to the OpenShift CLI +[role="_abstract"] You can log in to the OpenShift CLI (`oc`) to access and manage your cluster. -.Prerequisites - -* You must have access to a {product-title} cluster. -* The {oc-first} is installed. - [NOTE] ==== To access a cluster that is accessible only over an HTTP proxy server, you can set the `HTTP_PROXY`, `HTTPS_PROXY` and `NO_PROXY` variables. @@ -21,6 +17,11 @@ These environment variables are respected by the `oc` CLI so that all communicat Authentication headers are sent only when using HTTPS transport. ==== +.Prerequisites + +* You must have access to a {product-title} cluster. +* The {oc-first} is installed. + .Procedure . Enter the `oc login` command and pass in a user name: @@ -35,14 +36,14 @@ $ oc login -u user1 .Example output [source,terminal] ---- -Server [https://localhost:8443]: https://openshift.example.com:6443 <1> +Server [https://localhost:8443]: https://openshift.example.com:6443 The server uses a certificate signed by an unknown authority. You can bypass the certificate check, but any data you send to the server could be intercepted by others. -Use insecure connections? (y/n): y <2> +Use insecure connections? (y/n): y Authentication required for https://openshift.example.com:6443 (openshift) Username: user1 -Password: <3> +Password: Login successful. You don't have any projects. You can try to create a new project, by running @@ -51,14 +52,18 @@ You don't have any projects. You can try to create a new project, by running Welcome! See 'oc help' to get started. ---- -<1> Enter the {product-title} server URL. -<2> Enter whether to use insecure connections. -<3> Enter the user's password. - ++ +-- +** For the `Server` prompt, enter the {product-title} server URL. +** For the `Use insecure connections?` prompt, enter whether to use insecure connections. +** For the `Username` prompt, enter the username to log in with. +** For the `Password` prompt, enter the user's password. +-- ++ [NOTE] ==== If you are logged in to the web console, you can generate an `oc login` command that includes your token and server information. You can use the command to log in to the OpenShift CLI (`oc`) without the interactive prompts. To generate the command, select *Copy login command* from the username drop-down menu at the top right of the web console. ==== - ++ You can now create a project or issue other commands for managing your cluster. diff --git a/modules/cli-logging-out.adoc b/modules/cli-logging-out.adoc index 9c0046022b16..c7ba1741b5f6 100644 --- a/modules/cli-logging-out.adoc +++ b/modules/cli-logging-out.adoc @@ -6,9 +6,12 @@ [id="cli-logging-out_{context}"] = Logging out of the OpenShift CLI -You can log out the OpenShift CLI to end your current session. +[role="_abstract"] +You can log out the {oc-first} to end your current session. -* Use the `oc logout` command. +.Procedure + +* Log out of the OpenShift CLI by running the following command: + [source,terminal] ---- @@ -20,6 +23,5 @@ $ oc logout ---- Logged "user1" out on "https://openshift.example.com" ---- - -This deletes the saved authentication token from the server and removes it from -your configuration file. ++ +This deletes the saved authentication token from the server and removes it from your configuration file. diff --git a/modules/cli-using-cli-current-project.adoc b/modules/cli-using-cli-current-project.adoc new file mode 100644 index 000000000000..712686e0702e --- /dev/null +++ b/modules/cli-using-cli-current-project.adoc @@ -0,0 +1,25 @@ +// Module included in the following assemblies: +// +// * cli_reference/openshift_cli/getting-started.adoc + +:_mod-docs-content-type: PROCEDURE +[id="cli-using-cli-current-project_{context}"] += Viewing the current project + +[role="_abstract"] +Use the `oc project` command to view the current project. + +.Procedure + +* View the current project by running the following command: ++ +[source,terminal] +---- +$ oc project +---- ++ +.Example output +[source,terminal] +---- +Using project "my-project" on server "https://openshift.example.com:6443". +---- diff --git a/modules/cli-using-cli-list-api-resources.adoc b/modules/cli-using-cli-list-api-resources.adoc new file mode 100644 index 000000000000..12aa96e1d639 --- /dev/null +++ b/modules/cli-using-cli-list-api-resources.adoc @@ -0,0 +1,29 @@ +// Module included in the following assemblies: +// +// * cli_reference/openshift_cli/getting-started.adoc + +:_mod-docs-content-type: PROCEDURE +[id="cli-using-cli-list-api-resources_{context}"] += Listing supported API resources + +[role="_abstract"] +Use the `oc api-resources` command to view the list of supported API resources on the server. + +.Procedure + +* View the supported API resources by running the following 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/cli-using-cli-new-app.adoc b/modules/cli-using-cli-new-app.adoc new file mode 100644 index 000000000000..d56e98d5ab8e --- /dev/null +++ b/modules/cli-using-cli-new-app.adoc @@ -0,0 +1,29 @@ +// Module included in the following assemblies: +// +// * cli_reference/openshift_cli/getting-started.adoc + +:_mod-docs-content-type: PROCEDURE +[id="cli-using-cli-new-app_{context}"] += Creating a new application + +[role="_abstract"] +Use the `oc new-app` command to create a new application. + +.Procedure + +* Create a new application by running the following command: ++ +[source,terminal] +---- +$ oc new-app https://github.com/sclorg/cakephp-ex +---- ++ +.Example output +[source,terminal] +---- +--> Found image 40de956 (9 days old) in imagestream "openshift/php" under tag "7.2" for "php" + +... + + Run 'oc status' to view your app. +---- diff --git a/modules/cli-using-cli-pod-logs.adoc b/modules/cli-using-cli-pod-logs.adoc new file mode 100644 index 000000000000..827e6b5cb0c4 --- /dev/null +++ b/modules/cli-using-cli-pod-logs.adoc @@ -0,0 +1,26 @@ +// Module included in the following assemblies: +// +// * cli_reference/openshift_cli/getting-started.adoc + +:_mod-docs-content-type: PROCEDURE +[id="cli-using-cli-pod-logs_{context}"] += Viewing pod logs + +[role="_abstract"] +Use the `oc logs` command to view logs for a particular pod. + +.Procedure + +* View logs for a pod by running the following command: ++ +[source,terminal] +---- +$ oc logs cakephp-ex-1-deploy +---- ++ +.Example output +[source,terminal] +---- +--> Scaling cakephp-ex-1 to 1 +--> Success +---- diff --git a/modules/cli-using-cli-pods.adoc b/modules/cli-using-cli-pods.adoc new file mode 100644 index 000000000000..84d2b90aad29 --- /dev/null +++ b/modules/cli-using-cli-pods.adoc @@ -0,0 +1,33 @@ +// Module included in the following assemblies: +// +// * cli_reference/openshift_cli/getting-started.adoc + +:_mod-docs-content-type: PROCEDURE +[id="cli-using-cli-pods_{context}"] += Viewing pods + +[role="_abstract"] +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. +==== + +.Procedure + +* View pods for the current project by running the following 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 +---- diff --git a/modules/cli-using-cli-project-status.adoc b/modules/cli-using-cli-project-status.adoc new file mode 100644 index 000000000000..fa6dd5bda3b7 --- /dev/null +++ b/modules/cli-using-cli-project-status.adoc @@ -0,0 +1,32 @@ +// Module included in the following assemblies: +// +// * cli_reference/openshift_cli/getting-started.adoc + +:_mod-docs-content-type: PROCEDURE +[id="cli-using-cli-project-status_{context}"] += Viewing the status of the current project + +[role="_abstract"] +Use the `oc status` command to view information about the current project, such as services, deployments, and build configs. + +.Procedure + +* View the status of the current project by running the following command: ++ +[source,terminal] +---- +$ oc status +---- ++ +.Example output +[source,terminal] +---- +In project my-project on server https://openshift.example.com:6443 + +svc/cakephp-ex - 172.30.236.80 ports 8080, 8443 + dc/cakephp-ex deploys istag/cakephp-ex:latest <- + bc/cakephp-ex source builds https://github.com/sclorg/cakephp-ex on openshift/php:7.2 + deployment #1 deployed 2 minutes ago - 1 pod + +3 infos identified, use 'oc status --suggest' to see details. +---- diff --git a/modules/cli-using-cli-project.adoc b/modules/cli-using-cli-project.adoc new file mode 100644 index 000000000000..3fd5a96938be --- /dev/null +++ b/modules/cli-using-cli-project.adoc @@ -0,0 +1,25 @@ +// Module included in the following assemblies: +// +// * cli_reference/openshift_cli/getting-started.adoc + +:_mod-docs-content-type: PROCEDURE +[id="cli-using-cli-project_{context}"] += Creating a project + +[role="_abstract"] +Use the `oc new-project` command to create a new project. + +.Procedure + +* Create a new project by running the following command: ++ +[source,terminal] +---- +$ oc new-project my-project +---- ++ +.Example output +[source,terminal] +---- +Now using project "my-project" on server "https://openshift.example.com:6443". +---- diff --git a/modules/cli-using-cli.adoc b/modules/cli-using-cli.adoc index 8d6031b7b14d..ca5cd6fbe9e6 100644 --- a/modules/cli-using-cli.adoc +++ b/modules/cli-using-cli.adoc @@ -2,145 +2,9 @@ // // * cli_reference/openshift_cli/getting-started.adoc -:_mod-docs-content-type: PROCEDURE +:_mod-docs-content-type: CONCEPT [id="cli-using-cli_{context}"] = Using the OpenShift CLI -Review the following sections to learn how to complete common tasks using the CLI. - -ifndef::microshift[] -== Creating a project - -Use the `oc new-project` command to create a new project. - -[source,terminal] ----- -$ oc new-project my-project ----- - -.Example output -[source,terminal] ----- -Now using project "my-project" on server "https://openshift.example.com:6443". ----- -endif::microshift[] - -ifndef::microshift[] -== Creating a new app - -Use the `oc new-app` command to create a new application. - -[source,terminal] ----- -$ oc new-app https://github.com/sclorg/cakephp-ex ----- - -.Example output -[source,terminal] ----- ---> Found image 40de956 (9 days old) in imagestream "openshift/php" under tag "7.2" for "php" - -... - - Run 'oc status' to view your app. ----- -endif::microshift[] - -== 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 ----- - -== 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 ----- - -ifndef::microshift[] -== Viewing the current project - -Use the `oc project` command to view the current project. - -[source,terminal] ----- -$ oc project ----- - -.Example output -[source,terminal] ----- -Using project "my-project" on server "https://openshift.example.com:6443". ----- - -== Viewing the status for the current project - -Use the `oc status` command to view information about the current project, such -as services, deployments, and build configs. - -[source,terminal] ----- -$ oc status ----- - -.Example output -[source,terminal] ----- -In project my-project on server https://openshift.example.com:6443 - -svc/cakephp-ex - 172.30.236.80 ports 8080, 8443 - dc/cakephp-ex deploys istag/cakephp-ex:latest <- - bc/cakephp-ex source builds https://github.com/sclorg/cakephp-ex on openshift/php:7.2 - deployment #1 deployed 2 minutes ago - 1 pod - -3 infos identified, use 'oc status --suggest' to see details. ----- -endif::microshift[] - -== 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 -... ----- +[role="_abstract"] +Review how to complete common tasks with the {oc-first}. diff --git a/modules/oc-usage-kubectl.adoc b/modules/oc-usage-kubectl.adoc new file mode 100644 index 000000000000..7adb0d6d2991 --- /dev/null +++ b/modules/oc-usage-kubectl.adoc @@ -0,0 +1,12 @@ +// Module included in the following assemblies: +// +// * cli_reference/openshift_cli/usage-oc-kubectl.adoc + +:_mod-docs-content-type: CONCEPT +[id="oc-usage-kubectl_{context}"] += The kubectl binary + +[role="_abstract"] +The Kubernetes CLI (`kubectl`) binary is provided as a means to support existing workflows and scripts for new {product-title} users coming from a standard Kubernetes environment, or for those who prefer to use the `kubectl` CLI. Existing users of `kubectl` can continue to use the binary to interact with Kubernetes primitives, with no changes required to the {product-title} cluster. + +You can install the supported `kubectl` binary by following the steps to install the OpenShift CLI. The `kubectl` binary is included in the archive if you download the binary, or is installed when you install the CLI by using an RPM. diff --git a/modules/oc-usage-oc.adoc b/modules/oc-usage-oc.adoc new file mode 100644 index 000000000000..2c47cb1fbfca --- /dev/null +++ b/modules/oc-usage-oc.adoc @@ -0,0 +1,62 @@ +// Module included in the following assemblies: +// +// * cli_reference/openshift_cli/usage-oc-kubectl.adoc + +:_mod-docs-content-type: CONCEPT +[id="oc-usage-oc_{context}"] += The oc binary + +[role="_abstract"] +The {oc-first} binary offers the same capabilities as the `kubectl` binary, but it extends to natively support additional {product-title} features. + +Full support for {product-title} resources:: ++ +Resources such as `DeploymentConfig`, `BuildConfig`, `Route`, `ImageStream`, and `ImageStreamTag` objects are specific to {product-title} distributions, and build upon standard Kubernetes primitives. + +ifndef::openshift-rosa,openshift-rosa-hcp,openshift-dedicated[] +Authentication:: ++ +The `oc` binary offers a built-in `login` command for authentication and lets you work with projects, which map Kubernetes namespaces to authenticated users. +Read "Understanding authentication" for more information. +endif::openshift-rosa,openshift-rosa-hcp,openshift-dedicated[] + +Additional commands:: ++ +The additional command `oc new-app`, for example, makes it easier to get new applications started using existing source code or pre-built images. Similarly, the additional command `oc new-project` makes it easier to start a project that you can switch to as your default. + +[IMPORTANT] +==== +If you installed an earlier version of the `oc` binary, you cannot use it to complete all of the commands in +ifndef::openshift-rosa,openshift-rosa-hcp[] +{product-title} {product-version} +endif::openshift-rosa,openshift-rosa-hcp[] +ifdef::openshift-rosa,openshift-rosa-hcp[] +{product-title} +endif::openshift-rosa,openshift-rosa-hcp[] +. If you want the latest features, you must download and install the latest version of the `oc` binary corresponding to your {product-title} server version. +==== + +Non-security API changes will involve, at minimum, two minor releases (4.1 to 4.2 to 4.3, for example) to allow older `oc` binaries to update. Using new capabilities might require newer `oc` binaries. A 4.3 server might have additional capabilities that a 4.2 `oc` binary cannot use and a 4.3 `oc` binary might have additional capabilities that are unsupported by a 4.2 server. + +.Compatibility matrix +[cols="1,1,1"] +|=== + +| +|*X.Y* (`oc` Client) +|*X.Y+N* footnote:versionpolicyn[Where *N* is a number greater than or equal to 1.] (`oc` Client) + +|*X.Y* (Server) +|image:redcircle-1.png[Red circle 1] +|image:redcircle-3.png[Red circle 3] + +|*X.Y+N* footnote:versionpolicyn[] (Server) +|image:redcircle-2.png[Red circle 2] +|image:redcircle-1.png[Red circle 1] + +|=== +image:redcircle-1.png[Red circle 1] Fully compatible. + +image:redcircle-2.png[Red circle 2] `oc` client might not be able to access server features. + +image:redcircle-3.png[Red circle 3] `oc` client might provide options and features that might not be compatible with the accessed server. diff --git a/service_mesh/v1x/preparing-ossm-installation.adoc b/service_mesh/v1x/preparing-ossm-installation.adoc index 84a5693cc77a..c39eaa81acaf 100644 --- a/service_mesh/v1x/preparing-ossm-installation.adoc +++ b/service_mesh/v1x/preparing-ossm-installation.adoc @@ -32,7 +32,7 @@ endif::[] * Install the version of the {product-title} command-line utility (the `oc` client tool) that matches your {product-title} version and add it to your path. ifdef::openshift-enterprise[] -** If you are using {product-title} {product-version}, see xref:../../cli_reference/openshift_cli/getting-started-cli.adoc#cli-about-cli_cli-developer-commands[About the OpenShift CLI]. +** If you are using {product-title} {product-version}, see xref:../../cli_reference/openshift_cli/getting-started-cli.adoc#cli-about-cli_getting-started-cli[About the OpenShift CLI]. endif::[] include::modules/ossm-supported-configurations-v1x.adoc[leveloffset=+1] diff --git a/service_mesh/v2x/preparing-ossm-installation.adoc b/service_mesh/v2x/preparing-ossm-installation.adoc index 832c7eb76fa7..677bc58be5dd 100644 --- a/service_mesh/v2x/preparing-ossm-installation.adoc +++ b/service_mesh/v2x/preparing-ossm-installation.adoc @@ -25,7 +25,7 @@ endif::[] * Install the version of the {product-title} command-line utility (the `oc` client tool) that matches your {product-title} version and add it to your path. ifdef::openshift-enterprise[] -** If you are using {product-title} {product-version}, see xref:../../cli_reference/openshift_cli/getting-started-cli.adoc#cli-about-cli_cli-developer-commands[About the OpenShift CLI]. +** If you are using {product-title} {product-version}, see xref:../../cli_reference/openshift_cli/getting-started-cli.adoc#cli-about-cli_getting-started-cli[About the OpenShift CLI]. endif::[] For additional information about {SMProductName} lifecycle and supported platforms, refer to the link:https://access.redhat.com/support/policy/updates/openshift#ossm[Support Policy]. diff --git a/tutorials/dev-app-cli.adoc b/tutorials/dev-app-cli.adoc index a6254182f7c6..6921d57f5f8c 100644 --- a/tutorials/dev-app-cli.adoc +++ b/tutorials/dev-app-cli.adoc @@ -49,7 +49,7 @@ If you do not have the required permissions, contact your cluster administrator. + If you are using Developer Sandbox, a project is created for you with the required permissions. -* You have xref:../cli_reference/openshift_cli/getting-started-cli.adoc#cli-logging-in_cli-developer-commands[logged in to your cluster by using the {oc-first}]. +* You have xref:../cli_reference/openshift_cli/getting-started-cli.adoc#cli-logging-in_getting-started-cli[logged in to your cluster by using the {oc-first}]. // Creating a new project include::modules/getting-started-cli-creating-new-project.adoc[leveloffset=+1]