Chapter 5. Using OpenShift Enterprise

Download an archive with the executable for your operating system (Linux, Mac OS X, or Windows) from the Red Hat Customer Portal: Red Hat OpenShift Enterprise (you need to log in to the Customer Portal and have an active OpenShift Enterprise subscription to be able to access the download page).

Note that downloading this archive is not necessary if you use Red Hat Enterprise Linux as your host system because the oc executable can be installed from system repositories using yum. See Installing the oc Executable on Red Hat Enterprise Linux for details.

Install the atomic-openshift-clients package, which provides the oc executable. The package is available from the rhel-7-server-ose-3.1-rpms (Red Hat OpenShift Enterprise 3.1) repository. Use the following command as root to enable the repository (you need to have an active OpenShift Enterprise subscription to be able to access the repository):

subscription-manager repos --enable=rhel-7-server-ose-3.1-rpms

~]# subscription-manager repos --enable=rhel-7-server-ose-3.1-rpms

Install the atomic-openshift-clients package using the following command as root:

yum install -y atomic-openshift-clients

~]# yum install -y atomic-openshift-clients

Unpack the oc executable from the archive obtained using instructions in Obtaining the oc Executable to a directory of your choice and add that directory to your PATH, so that the oc command can be used without specifying its location.

For example, to unpack the executable to the ~/openshift directory and configure the PATH variable accordingly, run the following commands from the directory to which you downloaded the archive:

mkdir ~/openshift
tar xvzf oc-3.1.1.6-linux.tar.gz --strip=8 -C ~/openshift
export PATH=$PATH:~/openshift

~]$ mkdir ~/openshift

~]$ tar xvzf oc-3.1.1.6-linux.tar.gz --strip=8 -C ~/openshift
mnt/redhat/staging-cds/ose-clients-3.1.1.6/usr/share/atomic-openshift/linux/oc

~]$ export PATH=$PATH:~/openshift

Unpack the oc executable from the archive obtained using instructions in Obtaining the oc Executable to a directory of your choice and add that directory to your PATH, so that the oc command can be used without specifying its location.

For example, to unpack the executable to the ~/openshift directory and configure the PATH variable accordingly, run the following commands from the directory to which you downloaded the archive:

mkdir ~/openshift
tar xvzf oc-3.1.1.6-macosx.tar.gz --strip=8 -C ~/openshift
export PATH=$PATH:~/openshift

~]$ mkdir ~/openshift

~]$ tar xvzf oc-3.1.1.6-macosx.tar.gz --strip=8 -C ~/openshift
mnt/redhat/staging-cds/ose-clients-3.1.1.6/usr/share/atomic-openshift/macosx/oc

~]$ export PATH=$PATH:~/openshift

Unpack the oc.exe executable from the archive obtained using instructions in Obtaining the oc Executable to a folder of your choice and add that folder to your PATH, so that the oc command can be used without specifying its location.

For example, to unpack the executable to the C:\Program Files (x86)\openshift folder and configure the PATH variable accordingly, run the following commands (using the Command Prompt or other terminal emulator) from the folder to which you downloaded the archive:

mkdir C:\Program Files (x86)\openshift
cd C:\Program Files (x86)\openshift

C:\Downloads> mkdir C:\Program Files (x86)\openshift

C:\Downloads> cd C:\Program Files (x86)\openshift

C:\Program Files (x86)\openshift> unzip -j oc-3.1.1.6-windows.zip
Archive:  oc-3.1.1.6-windows.zip
  inflating: oc.exe

C:\Program Files (x86)\openshift> set PATH=%PATH%;"C:\Program Files (x86)\openshift"

Use the oc version command to display the version of OpenShift Enterprise and the Kubernetes service currently in use:

oc version

~]$ oc version
oc v3.1.0.4-16-g112fcc4
kubernetes v1.1.0-origin-1107-g4c8e6f4

Use the oc login command to log into the OpenShift server. If you want top log in from your hosty system, you to specify a host address (10.1.2.2:8443). The command asks for the username and password interactively, but you can also supply this information on the command line using the -u (--username) and -p (--password) options respectively. For example, to log into the default OpenShift instance in CDK from your host system, use the following command:

oc login -u openshift-dev -p devel https://10.1.2.2:8443

~]$ oc login -u openshift-dev -p devel https://10.1.2.2:8443
The server uses a certificate signed by an unknown authority.
You can bypass the certificate check, but any data you send to the server could be intercepted by others.
Use insecure connections? (y/n): y

Authentication required for https://10.1.2.2:8443 (openshift)
Username: openshift-dev
Password:
Login successful.

You have access to the following projects and can switch between them with 'oc project <projectname>':

  * sample-project (current)

Using project "sample-project".
Welcome! See 'oc help' to get started.

Use the oc whoami command to check the user account to which you are currently logged:

oc whoami

~]$ oc whoami
openshift-dev

To display the configuration values for the command-line environment, use the oc config view. For example, to show the part of the configuration pertaining to the default user name (openshift-dev), issue the following command:

oc config view | grep -A2 "name: openshift-dev"

~]$ oc config view | grep -A2 "name: openshift-dev"
- name: openshift-dev/10-1-2-2:8443
  user:
    token: THdHS4sw1qgzs95CnCf5ic6D8eOrZss1aT5jyGOmd2w

To log out, use the oc logout command:

oc logout

~]$ oc logout
Logged "openshift-dev" out on "https://10.1.2.2:8443"

Use the oc new-project command to create a new project on the OpenShift server you are currently logged in to. The following example uses the optional --display-name option to set a user-friendly name for the project:

oc new-project testing --display-name="Test Project"

~]$ oc new-project testing --display-name="Test Project"
Now using project "testing" on server "https://127.0.0.1:8443".

You can add applications to this project with the 'new-app' command. For example, try:

    $ oc new-app centos/ruby-22-centos7~https://github.com/openshift/ruby-hello-world.git

to build a new hello-world application in Ruby.

Use the oc project <project-name> command to switch to another project on the OpenShift server you are currently logged in to. The following switches to the default sample-project project:

oc project sample-project

~]$ oc project sample-project
Now using project "sample-project" on server "https://10.1.2.2:8443".

To list projects available on the server and their status, use the oc get projects command. Note that the oc get command can be used to display information about a number of other resources besides projects (pods, builds, services, etc.). In the following example, only the project created in the preceeding example is shown:

oc get project

~]$ oc get project
NAME      DISPLAY NAME   STATUS
testing   Test Project   Active

Run the oc status command to display information about the currently used project and about activities (services, builds, deployments, etc.) within that project. When executed in a new (empty) project, the output looks like the following:

oc status

~]$ oc status
In project Test Project (testing) on server https://10.1.2.2:8443

You have no services, deployment configs, or build configs.
Run 'oc new-app' to create an application.

Alternatively, you can also use the oc project command to display project information:

oc project

~]$ oc project
Using project "testing" from context named "testing/10-1-2-2:8443/openshift-dev" on server "https://10.1.2.2:8443".

To remove a project from the server, use the oc delete project command and specify the name of the project you want deleted. To remove all projects, include the --all option. Note that the oc delete command can be used to delete other resources (pods, services, etc.) as well. For example, to delete the project created in this section, run the following command:

oc delete project testing

~]$ oc delete project testing
project "testing" deleted

To display the templates available in a project, issue the oc get templates command and use the -n option to specify the project from which you wish to list the templates. For example, to list the templates available in the global openshift project, run:

oc get templates -n openshift

~]$ oc get templates -n openshift
NAME                                DESCRIPTION                        PARAMETERS     OBJECTS
cakephp-example                     An example CakePHP application...  15 (8 blank)   5
cakephp-mysql-example               An example CakePHP application...  16 (3 blank)   7
eap64-basic-s2i                     Application template for EAP 6...  12 (3 blank)   5
eap64-mysql-persistent-s2i          Application template for EAP 6...  34 (16 blank)  10
jws30-tomcat7-mysql-persistent-s2i  Application template for JWS M...  28 (11 blank)  10
nodejs-example                      An example Node.js application...  12 (8 blank)   5
nodejs-mongodb-example              An example Node.js application...  13 (3 blank)   7

To obtain a template definition file, which can be used for uploading to your project, use the oc get templates command and specify the project in which the template is located (using the -n or --namespace option), choose the format in which you wish to store the template (typically JSON or YAML — use the -o or --output option), and supply the name of the requested template. Note that by default, the oc get command outputs the requested data to the standard output. To store the template in a file, redirect the output of the command to a file.

For example, to download the nodejs-mongodb-example template from the global openshift project and save it in the JSON format on your local syastem, use the following command:

oc get templates -o json -n openshift nodejs-mongodb-example \ > nodejs-mongodb-example.json
ls

~]$ oc get templates -o json -n openshift nodejs-mongodb-example \ > nodejs-mongodb-example.json

~]$ ls
nodejs-mongodb-example.json

When you download an InstantApp template from the default openshift project, the namespace (project name) in the template is set to openshift. To be able to upload the template to your project, you need to modify the template accordingly. If you do not do that, the upload fails with the following error message:

oc create -f nodejs-mongodb-example.json -n testing

~]$ oc create -f nodejs-mongodb-example.json -n testing
the namespace from the provided object "openshift" does not match the namespace "testing". You must pass '--namespace=openshift' to perform this operation.

To modify the namespace, edit the file using a text editor, such as vi, and in the metadata section, replace the value of the namespace parameter with the name of your project. For example, to use the name testing, the beginning of the nodejs-mongodb-example.json template file would look like this:

{
    "kind": "Template",
    "apiVersion": "v1",
    "metadata": {
        "name": "nodejs-mongodb-example",
        "namespace": "testing",
[...]

{
    "kind": "Template",
    "apiVersion": "v1",
    "metadata": {
        "name": "nodejs-mongodb-example",
        "namespace": "testing",
[...]

For a template to be available for use in your project, it must be first uploaded to it. Use the oc create command to do this and specify the template file using the -f or --filename option. For example, to upload the nodejs-mongodb-example InstantApp template obtained from the openshift project, run the following command:

oc create -f nodejs-mongodb-example.json

~]$ oc create -f nodejs-mongodb-example.json
template "nodejs-mongodb-example" created

To verify that the template has been successfully uploaded, use the oc get templates command. Optionally, you can specify the namespace from which you wish to list by using the -n or --namespace option. By default, templates from the currently used project are listed:

oc get templates

~]$ oc get templates
NAME                     DESCRIPTION                                              PARAMETERS     OBJECTS
nodejs-mongodb-example   An example Node.js application with a MongoDB database   11 (3 blank)   7

To list the parameters that a template specifies along with short descriptions and predefined values, use the oc process command with the --parameters option. For example, to list the parameters used by the nodejs-mongodb-example template, use the following command:

oc process --parameters nodejs-mongodb-example

~]$ oc process --parameters nodejs-mongodb-example
NAME                     DESCRIPTION                              GENERATOR   VALUE
SOURCE_REPOSITORY_URL    The URL of the repository with your...               https://github.com/openshift/nodejs-ex.git
SOURCE_REPOSITORY_REF    Set this to a branch name, tag or ot...
CONTEXT_DIR              Set this to the relative path to you...
APPLICATION_DOMAIN       The exposed hostname that will route...
GITHUB_WEBHOOK_SECRET    A secret string used to configure th...  expression  [a-zA-Z0-9]{40}
GENERIC_WEBHOOK_SECRET   A secret string used to configure th...  expression  [a-zA-Z0-9]{40}
DATABASE_SERVICE_NAME    Database service name                                         mongodb
DATABASE_USER            Username for MongoDB user that will...   expression  user[A-Z0-9]{3}
DATABASE_PASSWORD        Password for the MongoDB user            expression  [a-zA-Z0-9]{16}
DATABASE_NAME            Database name                                        sampledb
DATABASE_ADMIN_PASSWORD  Password for the database admin user...  expression  [a-zA-Z0-9]{16}

To process a template and use it to create the objects it defines in your project, use a combination of the oc process and oc create commands. The template processed by the oc process command can be piped to the oc create command.

Note that in most cases, the template parameters need to be modified, so that the resulting application can be useful in a real-world scenario. To modify the template parameters when creating the objects, use the -v or --value option.

For example, to create objects using the nodejs-mongodb-example template and to set a different source repository for the application (the original repository would need to be forked to the repository specified on the command line), use the following combination of commands:

oc process nodejs-mongodb-example \
-v SOURCE_REPOSITORY_URL=https://github.com/username/nodejs-ex.git | \
oc create -f -

~]$ oc process nodejs-mongodb-example \
-v SOURCE_REPOSITORY_URL=https://github.com/username/nodejs-ex.git | \
oc create -f -
service "nodejs-mongodb-example" created
route "nodejs-mongodb-example" created
imagestream "nodejs-mongodb-example" created
buildconfig "nodejs-mongodb-example" created
deploymentconfig "nodejs-mongodb-example" created
service "mongodb" created
deploymentconfig "mongodb" created

In the above example, substitute username for the name of the GitHub account into which the original repository was forked.