From 080e1c45974bb44cb30fec537703f401822a9f47 Mon Sep 17 00:00:00 2001 From: Shauna Diaz Date: Thu, 2 Feb 2023 17:01:58 -0500 Subject: [PATCH] OSDOCS-4971: Restructure CLI reference book --- _attributes/attributes-microshift.adoc | 5 +- _topic_maps/_topic_map_ms.yml | 35 ++---- cli_reference/index.adoc | 9 +- .../openshift_cli/getting-started-cli.adoc | 6 - microshift_cli_ref/_attributes | 1 + microshift_cli_ref/images | 1 + .../microshift-cli-overview.adoc | 26 ++++ .../microshift-cli-using-oc.adoc | 84 +++++++++++++ .../microshift-oc-cli-commands-list.adoc | 20 +++ .../microshift-oc-cli-install.adoc | 23 ++++ microshift_cli_ref/microshift-oc-config.adoc | 20 +++ .../microshift-usage-oc-kubectl.adoc | 62 ++++++++++ microshift_cli_ref/modules | 1 + microshift_cli_ref/snippets | 1 + .../microshift-architecture.adoc | 2 - .../microshift-embed-in-rpm-ostree.adoc | 6 +- .../microshift-install-rpm.adoc | 4 +- modules/cli-installing-cli-brew.adoc | 1 + modules/cli-installing-cli-rpm.adoc | 1 + modules/cli-installing-cli.adoc | 41 +++++-- modules/microshift-cli-oc-about.adoc | 13 ++ modules/microshift-cli-oc-get-help.adoc | 61 ++++++++++ modules/microshift-oc-apis-errors.adoc | 7 +- modules/microshift-oc-by-example-content.adoc | 114 ++++++++++++++++++ 24 files changed, 481 insertions(+), 63 deletions(-) create mode 120000 microshift_cli_ref/_attributes create mode 120000 microshift_cli_ref/images create mode 100644 microshift_cli_ref/microshift-cli-overview.adoc create mode 100644 microshift_cli_ref/microshift-cli-using-oc.adoc create mode 100644 microshift_cli_ref/microshift-oc-cli-commands-list.adoc create mode 100644 microshift_cli_ref/microshift-oc-cli-install.adoc create mode 100644 microshift_cli_ref/microshift-oc-config.adoc create mode 100644 microshift_cli_ref/microshift-usage-oc-kubectl.adoc create mode 120000 microshift_cli_ref/modules create mode 120000 microshift_cli_ref/snippets create mode 100644 modules/microshift-cli-oc-about.adoc create mode 100644 modules/microshift-cli-oc-get-help.adoc create mode 100644 modules/microshift-oc-by-example-content.adoc diff --git a/_attributes/attributes-microshift.adoc b/_attributes/attributes-microshift.adoc index cf762c6d02..4203d698db 100644 --- a/_attributes/attributes-microshift.adoc +++ b/_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 \ No newline at end of file +:VirtProductName: OpenShift Virtualization diff --git a/_topic_maps/_topic_map_ms.yml b/_topic_maps/_topic_map_ms.yml index 498e8689e0..cc085bbf26 100644 --- a/_topic_maps/_topic_map_ms.yml +++ b/_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 diff --git a/cli_reference/index.adoc b/cli_reference/index.adoc index 6034215d5d..6b4bbc18d6 100644 --- a/cli_reference/index.adoc +++ b/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,12 +22,8 @@ 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. @@ -37,4 +31,3 @@ ifndef::microshift[] * 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[] diff --git a/cli_reference/openshift_cli/getting-started-cli.adoc b/cli_reference/openshift_cli/getting-started-cli.adoc index 379dc3a070..bff334b936 100644 --- a/cli_reference/openshift_cli/getting-started-cli.adoc +++ b/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,10 +37,8 @@ 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] @@ -50,7 +46,5 @@ 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::[] diff --git a/microshift_cli_ref/_attributes b/microshift_cli_ref/_attributes new file mode 120000 index 0000000000..93957f0227 --- /dev/null +++ b/microshift_cli_ref/_attributes @@ -0,0 +1 @@ +../_attributes \ No newline at end of file diff --git a/microshift_cli_ref/images b/microshift_cli_ref/images new file mode 120000 index 0000000000..5e67573196 --- /dev/null +++ b/microshift_cli_ref/images @@ -0,0 +1 @@ +../images \ No newline at end of file diff --git a/microshift_cli_ref/microshift-cli-overview.adoc b/microshift_cli_ref/microshift-cli-overview.adoc new file mode 100644 index 0000000000..7804cae37c --- /dev/null +++ b/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 \ No newline at end of file diff --git a/microshift_cli_ref/microshift-cli-using-oc.adoc b/microshift_cli_ref/microshift-cli-using-oc.adoc new file mode 100644 index 0000000000..a7032fa09e --- /dev/null +++ b/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 +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 +... +---- + +// 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 diff --git a/microshift_cli_ref/microshift-oc-cli-commands-list.adoc b/microshift_cli_ref/microshift-oc-cli-commands-list.adoc new file mode 100644 index 0000000000..e3405e4333 --- /dev/null +++ b/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 --help` to get additional details for a specific command. + +[IMPORTANT] +==== +Using `oc --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] diff --git a/microshift_cli_ref/microshift-oc-cli-install.adoc b/microshift_cli_ref/microshift-oc-cli-install.adoc new file mode 100644 index 0000000000..c4288682ac --- /dev/null +++ b/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] \ No newline at end of file diff --git a/microshift_cli_ref/microshift-oc-config.adoc b/microshift_cli_ref/microshift-oc-config.adoc new file mode 100644 index 0000000000..166c16641d --- /dev/null +++ b/microshift_cli_ref/microshift-oc-config.adoc @@ -0,0 +1,20 @@ +:_content-type: ASSEMBLY +[id="cli-configuring-cli"] += Configuring the OpenShift CLI +include::_attributes/attributes-microshift.adoc[] +:context: cli-configuring-cli + +toc::[] + +Configure `oc` based on your preferences for working with it. + +[id="cli-enabling-tab-completion"] +== Enabling tab completion + +You can enable tab completion for the Bash or Zsh shells. + +// Enabling tab completion for Bash +include::modules/cli-configuring-completion.adoc[leveloffset=+2] + +// Enabling tab completion for Zsh +include::modules/cli-configuring-completion-zsh.adoc[leveloffset=+2] diff --git a/microshift_cli_ref/microshift-usage-oc-kubectl.adoc b/microshift_cli_ref/microshift-usage-oc-kubectl.adoc new file mode 100644 index 0000000000..d7e380a370 --- /dev/null +++ b/microshift_cli_ref/microshift-usage-oc-kubectl.adoc @@ -0,0 +1,62 @@ +:_content-type: ASSEMBLY +[id="microshift-usage-oc-kubectl"] += Using oc and kubectl commands +include::_attributes/attributes-microshift.adoc[] +:context: usage-oc-kubectl + +toc::[] + +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. + +[id="microshift-oc-binary_{context}"] +== The oc binary + +The `oc` binary offers the same capabilities as the `kubectl` binary, but it extends to natively support additional {product-title} features, including: + +* **Route resource** ++ +The `Route` resource object is specific to {product-title} distributions, and builds upon standard Kubernetes primitives. ++ +* **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. + +[IMPORTANT] +==== +If you installed an earlier version of the `oc` binary, you cannot use it to complete all of the commands in {product-title} {product-version}. 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[] +|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. + +[id="microshift-kubectl-binary_{context}"] +== 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. + +The `kubectl` binary is included in the archive if you download the `oc` binary. + +For more information, see the link:https://kubernetes.io/docs/reference/kubectl/overview/[kubectl documentation]. diff --git a/microshift_cli_ref/modules b/microshift_cli_ref/modules new file mode 120000 index 0000000000..464b823aca --- /dev/null +++ b/microshift_cli_ref/modules @@ -0,0 +1 @@ +../modules \ No newline at end of file diff --git a/microshift_cli_ref/snippets b/microshift_cli_ref/snippets new file mode 120000 index 0000000000..9d58b92e50 --- /dev/null +++ b/microshift_cli_ref/snippets @@ -0,0 +1 @@ +../snippets/ \ No newline at end of file diff --git a/microshift_getting_started/microshift-architecture.adoc b/microshift_getting_started/microshift-architecture.adoc index 38a58aa38d..905df497bc 100644 --- a/microshift_getting_started/microshift-architecture.adoc +++ b/microshift_getting_started/microshift-architecture.adoc @@ -74,6 +74,4 @@ In addition to the standard Kubernetes APIs, {product-title} includes a subset o | security.openshift.io/v1 |=== -include::modules/microshift-oc-apis-errors.adoc[leveloffset=+1] - include::modules/microshift-k8s-apis.adoc[leveloffset=+1] \ No newline at end of file diff --git a/microshift_install/microshift-embed-in-rpm-ostree.adoc b/microshift_install/microshift-embed-in-rpm-ostree.adoc index bf76f6a35b..425adfe232 100644 --- a/microshift_install/microshift-embed-in-rpm-ostree.adoc +++ b/microshift_install/microshift-embed-in-rpm-ostree.adoc @@ -31,7 +31,7 @@ Follow the instructions in https://access.redhat.com/documentation/en-us/red_hat include::modules/microshift-adding-repos-to-image-builder.adoc[leveloffset=+1] -[role="_additional-resources"] +[role="_additional-resources_microshift-embed-in-rpm-ostree"] .Additional resources * https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/composing_installing_and_managing_rhel_for_edge_images/setting-up-image-builder_composing-installing-managing-rhel-for-edge-images#edge-image-builder-system-requirements_setting-up-image-builder[Image Builder system requirements]. @@ -39,7 +39,7 @@ include::modules/microshift-adding-repos-to-image-builder.adoc[leveloffset=+1] include::modules/microshift-adding-service-to-blueprint.adoc[leveloffset=+2] -[role="_additional-resources"] +[role="_additional-resources_microshift-embed-in-rpm-ostree"] .Additional resources * For further customizations such as adding users, firewall rules, or kernel arguments to a blueprint, refer to link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/composing_installing_and_managing_rhel_for_edge_images/composing-a-rhel-for-edge-image-using-image-builder-command-line_composing-installing-managing-rhel-for-edge-images#image-customizations_composing-a-rhel-for-edge-image-using-image-builder-command-line[supported image customizations]. @@ -47,7 +47,7 @@ include::modules/microshift-adding-service-to-blueprint.adoc[leveloffset=+2] //include::modules/microshift-adding-containers-to-blueprint.adoc[leveloffset=+2] include::modules/microshift-provisioning-ostree.adoc[leveloffset=+1] -[role="_additional-resources"] +[role="_additional-resources_microshift-embed-in-rpm-ostree"] .Additional resources . https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html-single/composing_installing_and_managing_rhel_for_edge_images/index[{op-system-ostree} documentation]. diff --git a/microshift_install/microshift-install-rpm.adoc b/microshift_install/microshift-install-rpm.adoc index 2f1c661b6c..c742e0d84e 100644 --- a/microshift_install/microshift-install-rpm.adoc +++ b/microshift_install/microshift-install-rpm.adoc @@ -16,7 +16,7 @@ Red Hat does not support an update path from Developer Preview and Technology Pr include::modules/microshift-install-system-requirements.adoc[leveloffset=+1] include::modules/microshift-install-rpm-preparing.adoc[leveloffset=+1] -[role="_additional-resources"] +[role="_additional-resources_microshift-install-rpm"] .Additional resources * xref:../microshift_install/microshift-install-rpm.adoc#system-requirements-installing-microshift[System Requirements for Installing MicroShift] have been met. @@ -31,7 +31,7 @@ include::modules/microshift-install-rpm-preparing.adoc[leveloffset=+1] include::modules/microshift-installing-from-rpm.adoc[leveloffset=+1] -[role="_additional-resources"] +[role="_additional-resources_microshift-install-rpm"] .Additional resources * xref:../microshift_install/microshift-install-rpm.adoc#system-requirements-installing-microshift[System requirements for installing MicroShift] have been met. diff --git a/modules/cli-installing-cli-brew.adoc b/modules/cli-installing-cli-brew.adoc index 3bf72e2629..8315eeef2c 100644 --- a/modules/cli-installing-cli-brew.adoc +++ b/modules/cli-installing-cli-brew.adoc @@ -1,6 +1,7 @@ // Module included in the following assemblies: // // * cli_reference/openshift_cli/getting-started.adoc +// * microshift_cli_ref/microshift_oc_cli_install.adoc :_content-type: PROCEDURE [id="cli-installing-cli-brew_{context}"] diff --git a/modules/cli-installing-cli-rpm.adoc b/modules/cli-installing-cli-rpm.adoc index b835447fa8..a0067d2b72 100644 --- a/modules/cli-installing-cli-rpm.adoc +++ b/modules/cli-installing-cli-rpm.adoc @@ -1,6 +1,7 @@ // Module included in the following assemblies: // // * cli_reference/openshift_cli/getting-started.adoc +// * microshift_cli_ref/microshift_oc_cli_install.adoc :_content-type: PROCEDURE [id="cli-installing-cli-rpm_{context}"] diff --git a/modules/cli-installing-cli.adoc b/modules/cli-installing-cli.adoc index 07fa00be81..89c358a9c6 100644 --- a/modules/cli-installing-cli.adoc +++ b/modules/cli-installing-cli.adoc @@ -47,6 +47,7 @@ // * installing/installing_rhv/installing-rhv-customizations.adoc // * installing/installing_rhv/installing-rhv-default.adoc // * updating/updating-restricted-network-cluster/restricted-network-update.adoc +// * microshift_cli_ref/microshift-oc-cli-install.adoc // // AMQ docs link to this; do not change anchor @@ -63,9 +64,7 @@ command-line interface. You can install `oc` on Linux, Windows, or macOS. [IMPORTANT] ==== -If you installed an earlier version of `oc`, you cannot use it to complete all -of the commands in {product-title} {product-version}. Download and -install the new version of `oc`. +If you installed an earlier version of `oc`, you cannot use it to complete all of the commands in {product-title} {product-version}. Download and install the new version of `oc`. ifdef::restricted[] If you are upgrading a cluster in a disconnected environment, install the `oc` version that you plan to upgrade to. endif::restricted[] @@ -79,13 +78,19 @@ You can install the OpenShift CLI (`oc`) binary on Linux by using the following .Procedure ifdef::openshift-origin[] -. Navigate to link:https://mirror.openshift.com/pub/openshift-v4/clients/oc/latest/ and choose the folder for your operating system and architecture. +. Navigate to link:https://mirror.openshift.com/pub/openshift-v4/clients/oc/latest/[https://mirror.openshift.com/pub/openshift-v4/clients/oc/latest/] and choose the folder for your operating system and architecture. . Download `oc.tar.gz`. endif::[] -ifndef::openshift-origin[] +ifndef::openshift-origin,microshift[] . Navigate to the link:https://access.redhat.com/downloads/content/290[{product-title} downloads page] on the Red Hat Customer Portal. -. Select the architecture in the *Product Variant* drop-down menu. -. Select the appropriate version in the *Version* drop-down menu. +. Select the architecture from the *Product Variant* drop-down list. +. Select the appropriate version from the *Version* drop-down list. +. Click *Download Now* next to the *OpenShift v{product-version} Linux Client* entry and save the file. +endif::[] +ifdef::microshift[] +. Navigate to the link:https://access.redhat.com/downloads/content/290[{ocp} downloads page] on the Red Hat Customer Portal. +. Select the architecture from the *Product Variant* drop-down list. +. Select the appropriate version from the *Version* drop-down list. . Click *Download Now* next to the *OpenShift v{product-version} Linux Client* entry and save the file. endif::[] . Unpack the archive: @@ -118,12 +123,17 @@ You can install the OpenShift CLI (`oc`) binary on Windows by using the followin .Procedure ifdef::openshift-origin[] -. Navigate to link:https://mirror.openshift.com/pub/openshift-v4/clients/oc/latest/ and choose the folder for your operating system and architecture. +. Navigate to link:https://mirror.openshift.com/pub/openshift-v4/clients/oc/latest/[https://mirror.openshift.com/pub/openshift-v4/clients/oc/latest/] and choose the folder for your operating system and architecture. . Download `oc.zip`. endif::[] -ifndef::openshift-origin[] +ifndef::openshift-origin,microshift[] . Navigate to the link:https://access.redhat.com/downloads/content/290[{product-title} downloads page] on the Red Hat Customer Portal. -. Select the appropriate version in the *Version* drop-down menu. +. Select the appropriate version from the *Version* drop-down list. +. Click *Download Now* next to the *OpenShift v{product-version} Windows Client* entry and save the file. +endif::[] +ifdef::microshift[] +. Navigate to the link:https://access.redhat.com/downloads/content/290[{ocp} downloads page] on the Red Hat Customer Portal. +. Select the appropriate version from the *Version* drop-down list. . Click *Download Now* next to the *OpenShift v{product-version} Windows Client* entry and save the file. endif::[] . Unzip the archive with a ZIP program. @@ -151,12 +161,12 @@ You can install the OpenShift CLI (`oc`) binary on macOS by using the following .Procedure ifdef::openshift-origin[] -. Navigate to link:https://mirror.openshift.com/pub/openshift-v4/clients/oc/latest/ and choose the folder for your operating system and architecture. +. Navigate to link:https://mirror.openshift.com/pub/openshift-v4/clients/oc/latest/[https://mirror.openshift.com/pub/openshift-v4/clients/oc/latest/] and choose the folder for your operating system and architecture. . Download `oc.tar.gz`. endif::[] -ifndef::openshift-origin[] +ifndef::openshift-origin,microshift[] . Navigate to the link:https://access.redhat.com/downloads/content/290[{product-title} downloads page] on the Red Hat Customer Portal. -. Select the appropriate version in the *Version* drop-down menu. +. Select the appropriate version from the *Version* drop-down list. . Click *Download Now* next to the *OpenShift v{product-version} macOS Client* entry and save the file. + [NOTE] @@ -164,6 +174,11 @@ ifndef::openshift-origin[] For macOS arm64, choose the *OpenShift v{product-version} macOS arm64 Client* entry. ==== endif::[] +ifdef::microshift[] +. Navigate to the link:https://access.redhat.com/downloads/content/290[{ocp} downloads page] on the Red Hat Customer Portal. +. Select the appropriate version from the *Version* drop-down list. +. Click *Download Now* next to the *OpenShift v{product-version} macOS Client* entry and save the file. +endif::[] . Unpack and unzip the archive. . Move the `oc` binary to a directory on your PATH. + diff --git a/modules/microshift-cli-oc-about.adoc b/modules/microshift-cli-oc-about.adoc new file mode 100644 index 0000000000..694760e9ff --- /dev/null +++ b/modules/microshift-cli-oc-about.adoc @@ -0,0 +1,13 @@ +// Module included in the following assemblies: +// +// * microshift-cli_ref/microshift-cli-using-oc.adoc + +:_content-type: CONCEPT +[id="microshift-cli-oc-about_{context}"] += About the OpenShift CLI + +With the OpenShift command-line interface (CLI), the `oc` command, you can deploy and manage {product-title} projects from a terminal. The OpenShift CLI is ideal in the following situations: + +* Working directly with project source code +* Scripting {product-title} operations +* Managing projects while restricted by bandwidth resources diff --git a/modules/microshift-cli-oc-get-help.adoc b/modules/microshift-cli-oc-get-help.adoc new file mode 100644 index 0000000000..e28c3517ae --- /dev/null +++ b/modules/microshift-cli-oc-get-help.adoc @@ -0,0 +1,61 @@ +// Module included in the following assemblies: +// +// * microshift_cli_ref/microshift_cli_getting_help.adoc + +:_content-type: CONCEPT +[id="cli-getting-help_{context}"] += Getting help + +You can get help with CLI commands and {product-title} resources in the following ways. + +* Use `oc help --flag` to get information about a specific CLI command: ++ +.Example: Get help for the `oc create` command +[source,terminal] +---- +$ oc create --help +---- ++ +.Example output +[source,terminal] +---- +Create a resource by filename or stdin + +JSON and YAML formats are accepted. + +Usage: + oc create -f FILENAME [flags] + +... +---- + +* Use the `oc explain` command to view the description and fields for a particular resource: ++ +.Example: View documentation for the `Pod` resource +[source,terminal] +---- +$ oc explain pods +---- ++ +.Example output +[source,terminal] +---- +KIND: Pod +VERSION: v1 + +DESCRIPTION: + Pod is a collection of containers that can run on a host. This resource is + created by clients and scheduled onto hosts. + +FIELDS: + apiVersion + APIVersion defines the versioned schema of this representation of an + object. Servers should convert recognized schemas to the latest internal + value, and may reject unrecognized values. More info: + https://git.k8s.io/community/contributors/devel/api-conventions.md#resources + +... +---- +//removed reference to oc help, as I thought this would just create noise for the MicroShift user +//are these other two ways viable for MicroShift? +//are there better examples for MicroShift use cases? \ No newline at end of file diff --git a/modules/microshift-oc-apis-errors.adoc b/modules/microshift-oc-apis-errors.adoc index e0d9e83595..7b1a726d3f 100644 --- a/modules/microshift-oc-apis-errors.adoc +++ b/modules/microshift-oc-apis-errors.adoc @@ -1,11 +1,12 @@ // Module included in the following assemblies: // -// * // * microshift_architecture/microshift-openshift-apis.adoc +// * microshift-clie-using-oc/microshift-oc-apis-errors.adoc + :_content-type: CONCEPT [id="microshift-oc-apis-errors_{context}"] -= {OCP} CLI tool (`oc`) and {product-title} += oc command errors in {product-title} -Not all {OCP} CLI tool (`oc`) commands are relevant for {product-title} deployments. When you use `oc` to make a request call against an unsupported API, the `oc` binary can generate an error message about a resource that cannot be found. +Not all {OCP} CLI tool (`oc`) commands are relevant for {product-title} 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. .Example output diff --git a/modules/microshift-oc-by-example-content.adoc b/modules/microshift-oc-by-example-content.adoc new file mode 100644 index 0000000000..8db482eed2 --- /dev/null +++ b/modules/microshift-oc-by-example-content.adoc @@ -0,0 +1,114 @@ +// Module included in the following assemblies: +// +//* microshift-oc-cli-commands-list/microshift-oc-by-example-content.adoc + +:_content-type: REFERENCE +[id="microshift-oc-by-example-content"_{context}] += oc commands list for {product-title} + +The following lists a few examples of `oc` commands you can use to administer, deploy, and observe a {product-title} node. + +== oc apply +Apply a configuration to a resource by file name or stdin + +.Example usage +[source,bash,options="nowrap"] +---- + # Apply the configuration in pod.json to a pod + oc apply -f ./pod.json + + # Apply resources from a directory containing kustomization.yaml - e.g. dir/kustomization.yaml + oc apply -k dir/ + + # Apply the JSON passed into stdin to a pod + cat pod.json | oc apply -f - + + # Apply the configuration from all files that end with '.json' - i.e. expand wildcard characters in file names + oc apply -f '*.json' + + # Note: --prune is still in Alpha + # Apply the configuration in manifest.yaml that matches label app=nginx and delete all other resources that are not in the file and match label app=nginx + oc apply --prune -f manifest.yaml -l app=nginx + + # Apply the configuration in manifest.yaml and delete all the other config maps that are not in the file + oc apply --prune -f manifest.yaml --all --prune-whitelist=core/v1/ConfigMap +---- + +[id="oc-delete"_{context}] +== oc delete +Delete resources by file names, stdin, resources and names, or by resources and label selector + +.Example usage +[source,bash,options="nowrap"] +---- + # Delete a pod using the type and name specified in pod.json + oc delete -f ./pod.json + + # Delete resources from a directory containing kustomization.yaml - e.g. dir/kustomization.yaml + oc delete -k dir + + # Delete resources from all files that end with '.json' - i.e. expand wildcard characters in file names + oc delete -f '*.json' + + # Delete a pod based on the type and name in the JSON passed into stdin + cat pod.json | oc delete -f - + + # Delete pods and services with same names "baz" and "foo" + oc delete pod,service baz foo + + # Delete pods and services with label name=myLabel + oc delete pods,services -l name=myLabel + + # Delete a pod with minimal delay + oc delete pod foo --now + + # Force delete a pod on a dead node + oc delete pod foo --force + + # Delete all pods + oc delete pods --all +---- + +[id="oc-get"_{context}] +== oc get +Display one or many resources + +.Example usage +[source,bash,options="nowrap"] +---- + # List all pods in ps output format + oc get pods + + # List all pods in ps output format with more information (such as node name) + oc get pods -o wide + + # List a single replication controller with specified NAME in ps output format + oc get replicationcontroller web + + # List deployments in JSON output format, in the "v1" version of the "apps" API group + oc get deployments.v1.apps -o json + + # List a single pod in JSON output format + oc get -o json pod web-pod-13je7 + + # List a pod identified by type and name specified in "pod.yaml" in JSON output format + oc get -f pod.yaml -o json + + # List resources from a directory with kustomization.yaml - e.g. dir/kustomization. + oc get -k dir/ + + # Return only the phase value of the specified pod + oc get -o template pod/web-pod-13je7 --template={{.status.phase}} + + # List resource information in custom columns + oc get pod test-pod -o custom-columns=CONTAINER:.spec.containers[0].name,IMAGE:.spec.containers[0].image + + # List all replication controllers and services together in ps output format + oc get rc,services + + # List one or more resources by their type and names + oc get rc/web service/frontend pods/web-pod-13je7 + + # List status subresource for a single pod. + oc get pod web-pod-13je7 --subresource status +----