검색

이 콘텐츠는 선택한 언어로 제공되지 않습니다.

Chapter 4. Developer CLI Operations

download PDF

4.1. Overview

This topic provides information on the developer CLI operations and their syntax. You must setup and login with the CLI before you can perform these operations.

The developer CLI uses the oc command, and is used for project-level operations. This differs from the administrator CLI, which uses the oc adm command for more advanced, administrator operations.

4.2. Common Operations

The developer CLI allows interaction with the various objects that are managed by OpenShift Container Platform. Many common oc operations are invoked using the following syntax:

$ oc <action> <object_type> <object_name>

This specifies:

  • An <action> to perform, such as get or describe.
  • The <object_type> to perform the action on, such as service or the abbreviated svc.
  • The <object_name> of the specified <object_type>.

For example, the oc get operation returns a complete list of services that are currently defined:

$ oc get svc
NAME              LABELS                                    SELECTOR                  IP              PORT(S)
docker-registry   docker-registry=default                   docker-registry=default   172.30.78.158   5000/TCP
kubernetes        component=apiserver,provider=kubernetes   <none>                    172.30.0.2      443/TCP
kubernetes-ro     component=apiserver,provider=kubernetes   <none>                    172.30.0.1      80/TCP

The oc describe operation can then be used to return detailed information about a specific object:

$ oc describe svc docker-registry
Name:			docker-registry
Labels:			docker-registry=default
Selector:		docker-registry=default
IP:			172.30.78.158
Port:			<unnamed>	5000/TCP
Endpoints:		10.128.0.2:5000
Session Affinity:	None
No events.
Warning

Versions of oc prior to 3.0.2.0 did not have the ability to negotiate API versions against a server. So if you are using oc up to 3.0.1.0 with a server that only supports v1 or higher versions of the API, make sure to pass --api-version in order to point the oc client to the correct API endpoint. For example: oc get svc --api-version=v1.

4.3. Object Types

The CLI supports the following object types, some of which have abbreviated syntax:

Object TypeAbbreviated Version

build

 

buildConfig

bc

deploymentConfig

dc

deployments (Technology Preview)

deploy

event

ev

imageStream

is

imageStreamTag

istag

imageStreamImage

isimage

job

 

LimitRange

limits

node

 

pod

po

ResourceQuota

quota

replicationController

rc

replicaSet

rs

secrets

 

service

svc

ServiceAccount

sa

persistentVolume

pv

persistentVolumeClaim

pvc

4.4. Basic CLI Operations

The following table describes basic oc operations and their general syntax:

4.4.1. whoami

Return information about the current session:

$ oc whoami [--options]

4.4.2. types

Display an introduction to some core OpenShift Container Platform concepts:

$ oc types

4.4.3. login

Log in to the OpenShift Container Platform server:

$ oc login

4.4.4. logout

End the current session:

$ oc logout

4.4.5. new-project

Create a new project:

$ oc new-project <project_name>

4.4.6. new-app

Creates a new application based on the source code in the current directory:

$ oc new-app

Creates a new application based on the source code in a remote repository:

$ oc new-app https://github.com/sclorg/cakephp-ex

Creates a new application based on the source code in a private remote repository:

$ oc new-app https://github.com/youruser/yourprivaterepo --source-secret=yoursecret

4.4.7. status

Show an overview of the current project:

$ oc status

4.4.8. project

Switch to another project. Run without options to display the current project. To view all projects you have access to run oc projects.

$ oc project <project_name>

4.4.9. explain

See the documentation of a resource and its fields:

$ oc explain <resource_name>

4.4.10. cluster

Start or stop a OpenShift Container Platform cluster:

$ oc cluster [--options]

4.4.11. completion

Output shell completion code for the specified shell:

$ oc completion [--options]

4.4.12. help

Get help about any command:

$ oc <command> --help

4.4.13. plugin

Run a command line plug-in:

$ oc plugin [--options]

4.4.14. version

Display client and server versions:

$ oc version [--options]

4.5. Application Modification CLI Operations

4.5.1. get

Return a list of objects for the specified object type. If the optional <object_name> is included in the request, then the list of results is filtered by that value.

$ oc get <object_type> [<object_name>]

You can use the -o or --output option to modify the output format.

$ oc get <object_type> [<object_name>]-o|--output=json|yaml|wide|custom-columns=...|custom-columns-file=...|go-template=...|go-template-file=...|jsonpath=...|jsonpath-file=...]

The output format can be a JSON or YAML, or an extensible format like custom columns, golang template, and jsonpath.

For example, the following command lists the name of the pods running in a specific project:

$ oc get pods -n default -o jsonpath='{range .items[*].metadata}{"Pod Name: "}{.name}{"\n"}{end}'

Pod Name: docker-registry-1-wvhrx
Pod Name: registry-console-1-ntq65
Pod Name: router-1-xzw69

4.5.2. describe

Returns information about the specific object returned by the query. A specific <object_name> must be provided. The actual information that is available varies as described in object type.

$ oc describe <object_type> <object_name>

4.5.3. edit

Edit the desired object type:

$ oc edit <object_type>/<object_name>

Edit the desired object type with a specified text editor:

$ OC_EDITOR="<text_editor>" oc edit <object_type>/<object_name>

Edit the desired object in a specified format (eg: JSON):

$ oc edit <object_type>/<object_name> \
    --output-version=<object_type_version> \
    -o <object_type_format>

4.5.4. config

Change configuration files for the client:

$ oc config  --config=""

4.5.5. volume

Modify a volume:

$ oc volume <object_type>/<object_name> [--option]

4.5.6. label

Update the labels on a object:

$ oc label <object_type> <object_name> <label>

4.5.7. annotate

Update the annotations on a resource:

$ oc annotate [--options]

4.5.8. expose

Look up a service and expose it as a route. There is also the ability to expose a deployment configuration, replication controller, service, or pod as a new service on a specified port. If no labels are specified, the new object will re-use the labels from the object it exposes.

If you are exposing a service, the default generator is --generator=route/v1. For all other cases the default is --generator=service/v2, which leaves the port unnamed. Generally, there is no need to set a generator with the oc expose command. A third generator, --generator=service/v1, is available with the port name default.

$ oc expose <object_type> <object_name>

4.5.9. delete

Delete the specified object. An object configuration can also be passed in through STDIN. The oc delete all -l <label> operation deletes all objects matching the specified <label>, including the replication controller so that pods are not re-created.

$ oc delete -f <file_path>
$ oc delete <object_type> <object_name>
$ oc delete <object_type> -l <label>
$ oc delete all -l <label>

4.5.10. set

Modify a specific property of the specified object.

4.5.10.1. set env

Sets an environment variable on a deployment configuration or a build configuration:

$ oc set env dc/mydc VAR1=value1

4.5.10.2. set build-secret

Sets the name of a secret on a build configuration. The secret may be an image pull or push secret or a source repository secret:

$ oc set build-secret --source bc/mybc mysecret

4.6. Build and Deployment CLI Operations

One of the fundamental capabilities of OpenShift Container Platform is the ability to build applications into a container from source.

OpenShift Container Platform provides CLI access to inspect and manipulate deployment configurations using standard oc resource operations, such as get, create, and describe.

4.6.1. start-build

Manually start the build process with the specified build configuration file:

$ oc start-build <buildconfig_name>

Manually start the build process by specifying the name of a previous build as a starting point:

$ oc start-build --from-build=<build_name>

Manually start the build process by specifying either a configuration file or the name of a previous build and retrieve its build logs:

$ oc start-build --from-build=<build_name> --follow
$ oc start-build <buildconfig_name> --follow

Wait for a build to complete and exit with a non-zero return code if the build fails:

$ oc start-build --from-build=<build_name> --wait

Set or override environment variables for the current build without changing the build configuration. Alternatively, use -e.

$ oc start-build --env <var_name>=<value>

Set or override the default build log level output during the build:

$ oc start-build --build-loglevel [0-5]

Specify the source code commit identifier the build should use; requires a build based on a Git repository:

$ oc start-build --commit=<hash>

Re-run build with name <build_name>:

$ oc start-build --from-build=<build_name>

Archive <dir_name> and build with it as the binary input:

$ oc start-build --from-dir=<dir_name>

Use existing archive as the binary input; unlike --from-file the archive will be extracted by the builder prior to the build process:

$ oc start-build --from-archive=<archive_name>

Use <file_name> as the binary input for the build. This file must be the only one in the build source. For example, pom.xml or Dockerfile.

$ oc start-build --from-file=<file_name>

Download the binary input using HTTP or HTTPS instead of reading it from the file system:

$ oc start-build --from-file=<file_URL>

Download an archive and use its contents as the build source:

$ oc start-build --from-archive=<archive_URL>

The path to a local source code repository to use as the binary input for a build:

$ oc start-build --from-repo=<path_to_repo>

Specify a webhook URL for an existing build configuration to trigger:

$ oc start-build --from-webhook=<webhook_URL>

The contents of the post-receive hook to trigger a build:

$ oc start-build --git-post-receive=<contents>

The path to the Git repository for post-receive; defaults to the current directory:

$ oc start-build --git-repository=<path_to_repo>

List the webhooks for the specified build configuration or build; accepts all, generic, or github:

$ oc start-build --list-webhooks

Override the Spec.Strategy.SourceStrategy.Incremental option of a source-strategy build:

$ oc start-build --incremental

Override the Spec.Strategy.DockerStrategy.NoCache option of a docker-strategy build:

$ oc start-build --no-cache

4.6.2. rollout

Manage a Kubernetes deployment or an OpenShift deployment configuration. Start a new rollout, view its status or history, or rollback to a previous revision of your application:

$ oc rollout [--options]

4.6.3. rollback

Perform a rollback:

$ oc rollback <deployment_name>

4.6.4. new-build

Create a build configuration based on the source code in the current Git repository (with a public remote) and a container image:

$ oc new-build .

Create a build configuration based on a remote git repository:

$ oc new-build https://github.com/sclorg/cakephp-ex

Create a build configuration based on a private remote git repository:

$ oc new-build https://github.com/youruser/yourprivaterepo --source-secret=yoursecret

4.6.5. cancel-build

Stop a build that is in progress:

$ oc cancel-build <build_name>

Cancel multiple builds at the same time:

$ oc cancel-build <build1_name> <build2_name> <build3_name>

Cancel all builds created from the build configuration:

$ oc cancel-build bc/<buildconfig_name>

Specify the builds to be canceled:

$ oc cancel-build bc/<buildconfig_name> --state=<state>

Example values for state are new or pending.

4.6.6. image

Useful commands for managing images.

$ oc image [--options]

4.6.7. import

Commands that import applications into OpenShift Container Platform.

$ oc import [--options]

4.6.8. import-image

Import tag and image information from an external image repository:

$ oc import-image <image_stream>

4.6.9. scale

Set the number of desired replicas for a replication controller or a deployment configuration to the number of specified replicas:

$ oc scale <object_type> <object_name> --replicas=<#_of_replicas>

4.6.10. tag

Take an existing tag or image from an image stream, or a container image "pull spec", and set it as the most recent image for a tag in one or more other image streams:

$ oc tag <current_image> <image_stream>

4.7. Advanced Commands

4.7.1. adm

Administrative commands. Tools for managing a cluster:

$ oc adm [--options]

4.7.2. create

Parse a configuration file and create one or more OpenShift Container Platform objects based on the file contents. The -f flag can be passed multiple times with different file or directory paths. When the flag is passed multiple times, oc create iterates through each one, creating the objects described in all of the indicated files. Any existing resources are ignored.

$ oc create -f <file_or_dir_path>

4.7.3. replace

Attempt to modify an existing object based on the contents of the specified configuration file. The -f flag can be passed multiple times with different file or directory paths. When the flag is passed multiple times, oc replace iterates through each one, updating the objects described in all of the indicated files.

$ oc replace -f <file_or_dir_path>

4.7.4. apply

Apply a configuration to a resource by file name or stdin:

$ oc apply [--options]

4.7.5. process

Transform a project template into a project configuration file:

$ oc process -f <template_file_path>

4.7.6. run

Create and run a particular image, possibly replicated. By default, create a deployment configuration to manage the created container(s). You can choose to create a different resource using the --generator flag:

API Resource--generator Option

Deployment configuration

deploymentconfig/v1 (default)

Pod

run-pod/v1

Replication controller

run/v1

Deployment using extensions/v1beta1 endpoint

deployment/v1beta1

Deployment using apps/v1beta1 endpoint

deployment/apps.v1beta1

Job

job/v1

Cron job

cronjob/v2alpha1

You can choose to run in the foreground for an interactive container execution.

$ oc run NAME --image=<image> \
    [--generator=<resource>] \
    [--port=<port>] \
    [--replicas=<replicas>] \
    [--dry-run=<bool>] \
    [--overrides=<inline_json>] \
    [options]

4.7.7. patch

Updates one or more fields of an object using strategic merge patch:

$ oc patch <object_type> <object_name> -p <changes>

The <changes> is a JSON or YAML expression containing the new fields and the values. For example, to update the spec.unschedulable field of the node node1 to the value true, the json expression is:

$ oc patch node node1 -p '{"spec":{"unschedulable":true}}'

4.7.8. export

Export resources to be used elsewhere:

$ oc export <object_type> [--options]

See Creating a Template from Existing Objects for more information on exporting existing objects from your project in template form.

4.7.9. extract

Extract secrets or config maps to disk:

$ oc extract [--options]

4.7.10. idle

Idle scalable resources:

$ oc idle [--options]

4.7.11. observe

Observe changes to resources and react to them:

$ oc observe [--options]

4.7.12. auth

Inspect authorization:

$ oc auth [--options]

4.7.13. policy

Manage authorization policies:

$ oc policy [--options]

4.7.14. convert

Convert configuration files between different API versions:

$ oc convert [--options]

4.7.15. secrets

Configure secrets:

$ oc secrets [--options]

4.7.16. serviceaccounts

Manage service accounts in your project. Service accounts allow system components to access the API.

$ oc serviceaccounts [--options]

4.7.17. autoscale

Setup an autoscaler for your application. Requires metrics to be enabled in the cluster. See Enabling Cluster Metrics for cluster administrator instructions, if needed.

$ oc autoscale dc/<dc_name> [--options]

4.8. Troubleshooting and Debugging CLI Operations

4.8.1. debug

Launch a command shell to debug a running application.

$ oc debug -h

When debugging images and setup problems, you can get an exact copy of a running pod configuration and troubleshoot with a shell. Since a failing pod may not be started and not accessible to rsh or exec, running the debug command creates a carbon copy of that setup.

The default mode is to start a shell inside of the first container of the referenced pod, replication controller, or deployment configuration. The started pod will be a copy of your source pod, with labels stripped, the command changed to /bin/sh, and readiness and liveness checks disabled. If you just want to run a command, add -- and a command to run. Passing a command will not create a TTY or send STDIN by default. Other flags are supported for altering the container or pod in common ways.

A common problem running containers is a security policy that prohibits you from running as a root user on the cluster. You can use this command to test running a pod as non-root (with --as-user) or to run a non-root pod as root (with --as-root).

The debug pod is deleted when the remote command completes or you interrupt the shell.

4.8.1.1. Usage

$ oc debug RESOURCE/NAME [ENV1=VAL1 ...] [-c CONTAINER] [options] [-- COMMAND]

4.8.1.2. Examples

To debug a currently running deployment:

$ oc debug dc/test

To test running a deployment as a non-root user:

$ oc debug dc/test --as-user=1000000

To debug a specific failing container by running the env command in the second container:

$ oc debug dc/test -c second -- /bin/env

To view the pod that would be created to debug:

$ oc debug dc/test -o yaml

4.8.2. logs

Retrieve the log output for a specific build, deployment, or pod. This command works for builds, build configurations, deployment configurations, and pods.

$ oc logs -f <pod>

4.8.3. exec

Execute a command in an already-running container. You can optionally specify a container ID, otherwise it defaults to the first container.

$ oc exec <pod> [-c <container>] <command>
Important

For security purposes, the oc exec command does not work when accessing privileged containers except when the command is executed by a cluster-admin user. Administrators can SSH into a node host, then use the docker exec command on the desired container.

4.8.4. rsh

Open a remote shell session to a container:

$ oc rsh <pod>

4.8.5. rsync

Copy the contents to or from a directory in an already-running pod container. If you do not specify a container, it defaults to the first container in the pod.

To copy contents from a local directory to a directory in a pod:

$ oc rsync <local_dir> <pod>:<pod_dir> -c <container>

To copy contents from a directory in a pod to a local directory:

$ oc rsync <pod>:<pod_dir> <local_dir> -c <container>

4.8.6. port-forward

Forward one or more local ports to a pod:

$ oc port-forward <pod> <local_port>:<remote_port>

4.8.7. proxy

Run a proxy to the Kubernetes API server:

$ oc proxy --port=<port> --www=<static_directory>

4.8.8. attach

Attach to a running container:

$ oc attach [--options]

4.8.9. cp

Copy files and directories to and from containers:

$ oc cp [--options]
Red Hat logoGithubRedditYoutubeTwitter

자세한 정보

평가판, 구매 및 판매

커뮤니티

Red Hat 문서 정보

Red Hat을 사용하는 고객은 신뢰할 수 있는 콘텐츠가 포함된 제품과 서비스를 통해 혁신하고 목표를 달성할 수 있습니다.

보다 포괄적 수용을 위한 오픈 소스 용어 교체

Red Hat은 코드, 문서, 웹 속성에서 문제가 있는 언어를 교체하기 위해 최선을 다하고 있습니다. 자세한 내용은 다음을 참조하세요.Red Hat 블로그.

Red Hat 소개

Red Hat은 기업이 핵심 데이터 센터에서 네트워크 에지에 이르기까지 플랫폼과 환경 전반에서 더 쉽게 작업할 수 있도록 강화된 솔루션을 제공합니다.

© 2024 Red Hat, Inc.