$ oc <action> <object_type> <object_name>
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.
The developer CLI allows interaction with the various
objects that are managed by OpenShift Origin. 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.
|
Versions of |
The CLI supports the following object types, some of which have abbreviated syntax:
| Object Type | Abbreviated Version |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
The following table describes basic oc operations and their general syntax:
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/openshift/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
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>]
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>
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>
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>
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>
One of the fundamental capabilities of OpenShift Origin is the ability to build applications into a container from source.
OpenShift Origin provides CLI access to inspect and manipulate deployment
configurations using standard oc resource operations, such as get, create,
and describe.
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
View a deployment, or manually start, cancel, or retry a deployment:
$ oc deploy <deploymentconfig>
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/openshift/cakephp-ex
Create a build configuration based on a private remote git repository:
$ oc new-build https://github.com/youruser/yourprivaterepo --source-secret=yoursecret
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.
Import tag and image information from an external image repository:
$ oc import-image <image_stream>
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>
Parse a configuration file and create one or more OpenShift Origin 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>
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>
Transform a project template into a project configuration file:
$ oc process -f <template_file_path>
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 |
|
Pod |
|
Replication controller |
|
Deployment using |
|
Deployment using |
|
Job |
|
Cron job |
|
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]
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}}'
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.
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]
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>
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>
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>
Forward one or more local ports to a pod:
$ oc port-forward <pod> <local_port>:<remote_port>
Run a proxy to the Kubernetes API server:
$ oc proxy --port=<port> --www=<static_directory>
|
For security purposes, the
|