Skip to content

Updated CLI content with some restructuring [tech_review] #65

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
nhr merged 1 commit into from
Jan 14, 2015
Merged

Updated CLI content with some restructuring [tech_review] #65

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
209 changes: 132 additions & 77 deletions using_openshift/cli.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,60 +11,83 @@
toc::[]

== Overview
The OpenShift CLI enables you to create and manage OpenShift projects from a terminal. This is useful for situations where:
With the OpenShift command line interface (CLI), you can create and manage OpenShift projects from a terminal. The CLI is ideal in situations where you are:

* You are working directly with project source code
* You are scripting OpenShift operations
* You are bandwidth-constrained and can't use the web console
* Working directly with project source code
* Scripting OpenShift operations
* Restricted by bandwidth resources and cannot use the web console

The CLI commands are available directly from the OpenShift binary by running `openshift cli <command>`, but if `osc` is available on your system, you can treat it as a shortcut to the same commands available through `openshift cli` (`osc <command>`).
The CLI commands are available directly from the OpenShift binary with the following syntax:

NOTE: Throughout this document we will reference `osc`, but you can run the same commands with `openshift cli`.
----
openshift cli <command>
----

However, if `osc` is available on your workstation you can use it as a shortcut in place of `openshift cli` in the command syntax:

----
osc <command>
----

NOTE: Although `osc` is used in the command examples presented throughout this document, you can substitute `openshift cli` in the command syntax if `osc` is not available on your workstation.

== Configuring the CLI
Running `osc --help` reveals a large number of configuration options. These are well-documented, but some of the main ones you may need are:
There are many configuration options available for the OpenShift CLI, and you can access these with the `osc --help` command. The following table describes some of the more common options.

*-s, --server* +
This enables you to specify the hostname of the OpenShift server. You will need to provide this if the server is running on a different host from the CLI.
.Common CLI Configuration Options
[cols="4,8",options="header"]
|===

*--insecure-skip-tls-verify=true* +
This is the quick and dirty way to interact with a server that is using HTTPS. Note, however, that it is not secure.
|Option |Description

*--auth-path* +
*--certificate-authority* +
*--client-certificate* +
*--client-key* +
These settings are the _proper_ way to authenticate an OpenShift server that uses HTTPS. Connections set up this way will be secure.
.^|`-s, --server`
|This option allows you to specify the host name of the OpenShift server. You will need to provide this if the server is running on a different host from the CLI.

.^|`--insecure-skip-tls-verify=true`
|This option allows quick interaction with an HTTPS server; however, note that it is not secure.

a|`--auth-path`

`--certificate-authority`

`--client-certificate`

`--client-key`
.^|These settings are used to correctly and securely authenticate with an OpenShift server that uses HTTPS.
|===

[TIP]
====
*Can I just set these in a configuration file?* +
The ability to permanently set `osc` configuration details in a config file is forthcoming. For now you will need to pass these on the command line, or create a shell alias that sets the values that you need.
*Can I use a configuration file?* +
The ability to permanently configure `osc` options with a configuration file is planned for a future release and is not available at this time. The current workaround is to use the CLI, or you can create a shell alias to configure the required parameters.
====

== Object Types in the CLI
The supported OpenShift object types are:
== CLI Object Types
OpenShift supports the following object types, some of which have abbreviated syntax that you can use with `osc`.

.Supported Object Types
[options="header"]
|===

* build
* buildConfig
* event
* minion
* pod
* replicationController
* service
|Object Type |Abbreviated Version

Some of these objects also have shorthand equivalent codes for use with `osc`:
|build |
|buildconfig |
|event |`ev`
|minion |`mi`
|pod |`po`
|replicationController |`rc`
|service |`se`
|===

* `po` - pods
* `rc` - replication controllers
* `se` - services
* `mi` - minions
* `ev` - events
== Common CLI Operations
The CLI allows interaction with the various objects that are managed by OpenShift. The common `osc` operations are invoked by specifying the following:

== Common Operations
At its heart, the `osc` utility is just a mechanism for interacting with the various objects that OpenShift manages. The common `osc` commands are invoked by specifying an _action_, the _object type_ to perform the action on, and optionally a specific _object name or ID_ of the indicated object type.
* An _action_
* The _object type_ to perform the action on
* The _object name_ or _ID_ of the specified _object type_

For instance, running `osc get se` returns the complete list of currently defined services:
In the following example the `osc get` operation returns a complete list of services that are currently defined.

----
$ osc get se
Expand All @@ -74,64 +97,96 @@ kubernetes-ro component=apiserver,provider=kubernetes <none>
docker-registry <none> name=registrypod 172.30.17.158 5001
----

And running `osc get se kubernetes-ro` returns the same list filtered down to an individual object:
The following example operation returns the same list that is filtered down to an individual object:

----
$ osc get se kubernetes-ro
NAME LABELS SELECTOR IP PORT
kubernetes-ro component=apiserver,provider=kubernetes <none> 172.30.17.77 80
----

=== Get
*`osc get <object_type> _<object_id>_`* +
This command returns a list of objects of the indicated link:#object-types[object type]. If an object name or ID is optionally included in the request, the list of results will be filtered by that value.
The following table describes the common `osc` operations and provides the general syntax for them.

=== Describe
*`osc describe <object_type> <object_id>`* +
This command returns information about the specific object returned by the query; a specific object name or ID must be provided. The exact information available varies per link:#object-types[object type].
.Common CLI Operations
[cols=".^2,.^5,8",options="header"]
|===

=== Create / Create All
*`osc create -f <file_path>`* +
*`osc createall _-d <directory_path>_ _-f <file_path>_`* +
These commands perform the same central function, which is to parse a configuration file and create one or more OpenShift objects based on the file contents. In the `createall` case, you can specify a directory (`-d`) with multiple configuration files, a file (`-f`) that contains multiple configurations, or even pass configurations through STDIN.
|Operation |Syntax |Description

=== Update
*`osc update -f <file_path>`* +
This command attempts to modify an existing object based on the contents of the specified configuration file. If the object does not already exist, this function behaves exactly like link:#create-create-all[`osc create`].
|`get`
|`osc get _<object_type>_ _<object_id>_`
|This command returns a list of objects of the indicated link:#object-types[object type]. If the optional _object name_ or _ID_ is included in the request, the list of results will be filtered by that value.

=== Delete
*`osc delete -f <file_path>`* +
*`osc delete <object_type> <object_id>`* +
*`osc delete <object_type> -l <label>`* +
This command deletes the identified OpenShift object. An object configuration can also be passed in via STDIN.
|`describe`
|`osc describe _<object_type>_ _<object_id>_`
|This command returns information about the specific object returned by the query; a specific _object name_ or _ID_ must be provided. The actual information that is available varies as described in link:#object-types[object type].

=== Log
*`osc log _-f_ <pod_name> _<container_name>_`* +
This command retrieves the log output for a specific pod / container. This command does not work for other object types.
|`create`
|`osc create -f _<file_path>_`
|This command is used to parse a configuration file and create one or more OpenShift objects based on the file contents.

== Project Operations
|`create all`
|`osc createall -d _<dir_path>_ -f _<file_path>_`
|This command performs the same action as the `create` command. In addition, you can specify a directory with the `-d` option that contains multiple configuration files, a file with the `-f` option that contains multiple configurations, or you can pass configurations through STDIN

|`update`
|`osc update -f _<file_path>_`
|This command attempts to modify an existing object based on the contents of the specified configuration file. If the object does not already exist, this command performs the same function as link:#create-create-all[`osc create`].

|`delete`
a|`osc delete -f _<file_path>_`

`osc delete _<object_type>_ _<object_id>_`

`osc delete _<object_type>_ -l _<label>_`
.^|This command deletes the specified OpenShift object. An object configuration can also be passed in through STDIN.

|`log`
|`osc log -f _<pod_name>_ _<container_name>_`
|This command retrieves the log output for a specific pod or container. This command does not work for other object types.
|===

== Project CLI Operations
These advanced operations are used to define and instantiate OpenShift objects at the project level.

=== Process
*`osc process -f <template_file_path>`* +
This command transforms a project template into a project configuration file.
.Project CLI Operations
[cols=".^2,.^5,8",options="header"]
|===

|Operation |Syntax |Description

|`process`
|`osc process -f _<template_file_path>_`
|This command transforms a project template into a project configuration file.

|`apply`
|`osc apply -f _<config_file_path>_`
|This command creates all of the OpenShift objects for a given project based on the specified configuration file.
|===

== Build CLI Operations
One of the fundamental capabilities of OpenShift is the ability to build applications into a container from source. The following table describes the CLI operations for working with application builds.

.Build CLI Operations
[cols=".^2,.^5,8",options="header"]
|===

|Operation |Syntax |Description

=== Apply
*`osc apply -f <config_file_path>`* +
This command creates all of the OpenShift objects for a given project based on the supplied
|`start-build`
|`osc start-build _<buildConfig_name>_`
|This command is used to manually start the build process with the specified build configuration file.

== Build Operations
Being able to build your application into a container from source is a fundamental capability of the OpenShift system. These commands specifically enable you to work with builds.
|`start-build`
|`osc start-build --from-build=_<build_name>_`
|This command is used to manually start the build process by specifying the name of a previous build as a starting point.

=== Start Build
*`osc start-build <buildConfig_name>`* +
*`osc start-build --from-build=<build_name>`* +
This command enables you to manually trigger a build by specifying either a buildConfig or a previous build as the starting point.
|`cancel-build`
|`osc cancel-build _<build_name>_`
|This command stops a build that is in progress.

=== Cancel Build
*`osc cancel-build <build_name>`* +
This command enables you to manually stop a build in progress.
|`build-logs`
|`osc cancel-build _<build_name>_`
|This command retrieves the build logs for the specified build.
|===

=== Build Logs
*`osc build-logs <build_name>`* +
This command retrieves the log output for the specified build.