MicroShift is Developer Preview software only.
For more information about the support scope of Red Hat Developer Preview software, see Developer Preview Support Scope.CLI tools
Learning how to use the command-line tools for MicroShift
Abstract
Chapter 1. Red Hat build of MicroShift CLI tools
A user builds, deploys, and manages boths applications and clusters while working with Red Hat build of MicroShift.
Red Hat build of MicroShift 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 OpenShift Container Platform and Kubernetes.
Chapter 2. Getting started with the OpenShift CLI
To use the OpenShift CLI (oc
) tool, you must download and install it separately from your {microshift-short} installation.
2.1. Installing the OpenShift CLI
You can install the OpenShift CLI (oc
) either by downloading the binary or by using Homebrew.
2.1.1. Installing the OpenShift CLI by downloading the binary
You can install the OpenShift CLI (oc
) to interact with Red Hat build of MicroShift from a command-line interface. You can install oc
on Linux, Windows, or macOS.
If you installed an earlier version of oc
, you cannot use it to complete all of the commands in Red Hat build of MicroShift 4.12. Download and install the new version of oc
.
Installing the OpenShift CLI on Linux
You can install the OpenShift CLI (oc
) binary on Linux by using the following procedure.
Red Hat build of MicroShift version numbering matches OpenShift Container Platform version numbering. Use the oc
binary that matches your {microshift-short} version and has the appropriate RHEL compatibility.
Procedure
- Navigate to the OpenShift Container Platform 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 v4.12 Linux Client entry and save the file.
Unpack the archive:
tar xvf <file>
$ tar xvf <file>
Copy to Clipboard Copied! Place the
oc
binary in a directory that is on yourPATH
.To check your
PATH
, execute the following command:echo $PATH
$ echo $PATH
Copy to Clipboard Copied!
After you install the OpenShift CLI, it is available using the oc
command:
oc <command>
$ oc <command>
Installing the OpenShift CLI on Windows
You can install the OpenShift CLI (oc
) binary on Windows by using the following procedure.
Red Hat build of MicroShift version numbering matches OpenShift Container Platform version numbering. Use the oc
binary that matches your {microshift-short} version and has the appropriate RHEL compatibility.
Procedure
- Navigate to the OpenShift Container Platform 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 v4.12 Windows Client entry and save the file.
- Unzip the archive with a ZIP program.
Move the
oc
binary to a directory that is on yourPATH
.To check your
PATH
, open the command prompt and execute the following command:path
C:\> path
Copy to Clipboard Copied!
After you install the OpenShift CLI, it is available using the oc
command:
oc <command>
C:\> oc <command>
Installing the OpenShift CLI on macOS
You can install the OpenShift CLI (oc
) binary on macOS by using the following procedure.
Red Hat build of MicroShift version numbering matches OpenShift Container Platform version numbering. Use the oc
binary that matches your {microshift-short} version and has the appropriate RHEL compatibility.
Procedure
- Navigate to the OpenShift Container Platform 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 v4.12 macOS Client entry and save the file.
- Unpack and unzip the archive.
Move the
oc
binary to a directory on your PATH.To check your
PATH
, open a terminal and execute the following command:echo $PATH
$ echo $PATH
Copy to Clipboard Copied!
After you install the OpenShift CLI, it is available using the oc
command:
oc <command>
$ oc <command>
2.1.2. Installing the OpenShift CLI by using Homebrew
For macOS, you can install the OpenShift CLI (oc
) by using the Homebrew package manager.
Prerequisites
-
You must have Homebrew (
brew
) installed.
Procedure
Run the following command to install the openshift-cli package:
brew install openshift-cli
$ brew install openshift-cli
Copy to Clipboard Copied!
2.1.3. Installing the OpenShift CLI by using an RPM
For Red Hat Enterprise Linux (RHEL), you can install the OpenShift CLI (oc
) as an RPM if you have an active Red Hat build of MicroShift subscription on your Red Hat account.
Prerequisites
- Must have root or sudo privileges.
Procedure
Register with Red Hat Subscription Manager:
subscription-manager register
# subscription-manager register
Copy to Clipboard Copied! Pull the latest subscription data:
subscription-manager refresh
# subscription-manager refresh
Copy to Clipboard Copied! List the available subscriptions:
subscription-manager list --available --matches '*OpenShift*'
# subscription-manager list --available --matches '*OpenShift*'
Copy to Clipboard Copied! In the output for the previous command, find the pool ID for an Red Hat build of MicroShift subscription and attach the subscription to the registered system:
subscription-manager attach --pool=<pool_id>
# subscription-manager attach --pool=<pool_id>
Copy to Clipboard Copied! Enable the repositories required by Red Hat build of MicroShift 4.12.
subscription-manager repos --enable="rhocp-4.12-for-rhel-8-x86_64-rpms"
# subscription-manager repos --enable="rhocp-4.12-for-rhel-8-x86_64-rpms"
Copy to Clipboard Copied! NoteIt is not supported to install the OpenShift CLI (
oc
) as an RPM for Red Hat Enterprise Linux (RHEL) 9. You must install the OpenShift CLI for {op-system-base} 9 by downloading the binary.Install the
openshift-clients
package:yum install openshift-clients
# yum install openshift-clients
Copy to Clipboard Copied!
After you install the CLI, it is available using the oc
command:
oc <command>
$ oc <command>
Chapter 3. Configuring the OpenShift CLI
Configure oc
based on your preferences for working with it.
3.1. Enabling tab completion
You can enable tab completion for the Bash or Zsh shells.
3.1.1. Enabling tab completion for Bash
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
-
You must have the OpenShift CLI (
oc
) installed. -
You must have the package
bash-completion
installed.
Procedure
Save the Bash completion code to a file:
oc completion bash > oc_bash_completion
$ oc completion bash > oc_bash_completion
Copy to Clipboard Copied! Copy the file to
/etc/bash_completion.d/
:sudo cp oc_bash_completion /etc/bash_completion.d/
$ sudo cp oc_bash_completion /etc/bash_completion.d/
Copy to Clipboard Copied! 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.
3.1.2. Enabling tab completion for Zsh
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
-
You must have the OpenShift CLI (
oc
) installed.
Procedure
To add tab completion for
oc
to your.zshrc
file, run the following command:cat >>~/.zshrc<<EOF if [ $commands[oc] ]; then source <(oc completion zsh) compdef _oc oc fi EOF
$ cat >>~/.zshrc<<EOF if [ $commands[oc] ]; then source <(oc completion zsh) compdef _oc oc fi EOF
Copy to Clipboard Copied!
Tab completion is enabled when you open a new terminal.
Chapter 4. Using the oc
tool
The optional OpenShift CLI (oc
) tool is available for you to use if you are already familiar with OpenShift Container Platform and Kubernetes.
4.1. About the OpenShift CLI
With the OpenShift command-line interface (CLI), the oc
command, you can deploy and manage Red Hat build of MicroShift projects from a terminal. The OpenShift CLI is ideal in the following situations:
- Working directly with project source code
- Scripting Red Hat build of MicroShift operations
- Managing projects while restricted by bandwidth resources
4.2. Using the OpenShift CLI in Red Hat build of MicroShift
Review the following sections to learn how to complete common tasks in Red Hat build of MicroShift using the oc
CLI.
4.2.1. Viewing pods
Use the oc get pods
command to view the pods for the current project.
When you run oc
inside a pod and do not specify a namespace, the namespace of the pod is used by default.
oc get pods -o wide
$ oc get pods -o wide
Example output
NAME READY STATUS RESTARTS AGE IP NODE NOMINATED NODE cakephp-ex-1-build 0/1 Completed 0 5m45s 10.131.0.10 ip-10-0-141-74.ec2.internal <none> cakephp-ex-1-deploy 0/1 Completed 0 3m44s 10.129.2.9 ip-10-0-147-65.ec2.internal <none> cakephp-ex-1-ktz97 1/1 Running 0 3m33s 10.128.2.11 ip-10-0-168-105.ec2.internal <none>
NAME READY STATUS RESTARTS AGE IP NODE NOMINATED NODE
cakephp-ex-1-build 0/1 Completed 0 5m45s 10.131.0.10 ip-10-0-141-74.ec2.internal <none>
cakephp-ex-1-deploy 0/1 Completed 0 3m44s 10.129.2.9 ip-10-0-147-65.ec2.internal <none>
cakephp-ex-1-ktz97 1/1 Running 0 3m33s 10.128.2.11 ip-10-0-168-105.ec2.internal <none>
4.2.2. Viewing pod logs
Use the oc logs
command to view logs for a particular pod.
oc logs cakephp-ex-1-deploy
$ oc logs cakephp-ex-1-deploy
Example output
--> Scaling cakephp-ex-1 to 1 --> Success
--> Scaling cakephp-ex-1 to 1
--> Success
4.2.3. Listing supported API resources
Use the oc api-resources
command to view the list of supported API resources on the server.
oc api-resources
$ oc api-resources
Example output
NAME SHORTNAMES APIGROUP NAMESPACED KIND bindings true Binding componentstatuses cs false ComponentStatus configmaps cm true ConfigMap ...
NAME SHORTNAMES APIGROUP NAMESPACED KIND
bindings true Binding
componentstatuses cs false ComponentStatus
configmaps cm true ConfigMap
...
4.3. Getting help
You can get help with CLI commands and Red Hat build of MicroShift resources in the following ways.
Use
oc help --flag
to get information about a specific CLI command:Example: Get help for the
oc create
commandoc create --help
$ oc create --help
Copy to Clipboard Copied! Example output
Create a resource by filename or stdin JSON and YAML formats are accepted. Usage: oc create -f FILENAME [flags] ...
Create a resource by filename or stdin JSON and YAML formats are accepted. Usage: oc create -f FILENAME [flags] ...
Copy to Clipboard Copied! Use the
oc explain
command to view the description and fields for a particular resource:Example: View documentation for the
Pod
resourceoc explain pods
$ oc explain pods
Copy to Clipboard Copied! Example output
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 <string> 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 ...
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 <string> 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 ...
Copy to Clipboard Copied!
4.4. oc command errors in Red Hat build of MicroShift
Not all OpenShift Container Platform CLI tool (oc
) commands are relevant for Red Hat build of MicroShift 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
For example, when the following new-project
command is run:
oc new-project test
$ oc new-project test
The error following error message can be generated:
Error from server (NotFound): the server could not find the requested resource (get projectrequests.project.openshift.io)
Error from server (NotFound): the server could not find the requested resource (get projectrequests.project.openshift.io)
And when the get projects
command is run, another error can be generated as follows:
oc get projects
$ oc get projects
error: the server doesn't have a resource type "projects"
Chapter 5. Using oc and kubectl commands
The Kubernetes command-line interface (CLI), kubectl
, can be used to run commands against a Kubernetes cluster. Because Red Hat build of MicroShift is a certified Kubernetes distribution, you can use the supported kubectl
binaries that ship with Red Hat build of MicroShift, or you can gain extended functionality by using the oc
binary.
5.1. The oc binary
The oc
binary offers the same capabilities as the kubectl
binary, but it extends to natively support additional Red Hat build of MicroShift features, including:
Route resource
The
Route
resource object is specific to Red Hat build of MicroShift 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.
If you installed an earlier version of the oc
binary, you cannot use it to complete all of the commands in Red Hat build of MicroShift 4.12. If you want the latest features, you must download and install the latest version of the oc
binary corresponding to your Red Hat build of MicroShift 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.
X.Y ( |
X.Y+N footnote:versionpolicyn[Where N is a number greater than or equal to 1.] ( | |
X.Y (Server) |
|
|
X.Y+N footnote:versionpolicyn[] (Server) |
|
|
Fully compatible.
oc
client might not be able to access server features.
oc
client might provide options and features that might not be compatible with the accessed server.
5.2. The kubectl binary
The kubectl
binary is provided as a means to support existing workflows and scripts for new Red Hat build of MicroShift 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 Red Hat build of MicroShift cluster.
The kubectl
binary is included in the archive if you download the oc
binary.
For more information, see the kubectl documentation.
Chapter 6. OpenShift CLI command reference
This reference provides descriptions and example commands for OpenShift CLI (oc
) commands. You must have cluster-admin
or equivalent permissions to use these commands.
Run oc adm -h
to list all administrator commands or run oc <command> --help
to get additional details for a specific command.
Using oc <command> --help
lists details for any oc
command. Not all oc
commands apply to using Red Hat build of MicroShift.
6.1. oc commands list for Red Hat build of MicroShift
The following lists a few examples of oc
commands you can use to administer, deploy, and observe a Red Hat build of MicroShift node.
6.1.1. oc apply
Apply a configuration to a resource by file name or stdin
Example usage
Apply the configuration in pod.json to a pod
# 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
6.1.2. oc delete
Delete resources by file names, stdin, resources and names, or by resources and label selector
Example usage
Delete a pod using the type and name specified in pod.json
# 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
6.1.3. oc get
Display one or many resources
Example usage
List all pods in ps output format
# 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