Chapter 7. Using OpenShift Container Platform

Use the install-cli command of the vagrant-service-manager plugin to install the oc binary on your host system.

For example:

~]$ vagrant service-manager install-cli openshift
# Binary now available at /home/joe/.vagrant.d/data/service-manager/bin/openshift/1.2.1/oc
# run binary as:
# oc <command>
export PATH=/home/joe/.vagrant.d/data/service-manager/bin/openshift/1.2.1:$PATH

# run following command to configure your shell:
# eval "$(VAGRANT_NO_COLOR=1 vagrant service-manager install-cli openshift | tr -d '\r')"

~]$ vagrant service-manager install-cli openshift --cli-version 1.3.1
# Binary now available at /home/joe/.vagrant.d/data/service-manager/bin/openshift/1.3.1/oc
# run binary as:
# oc <command>
export PATH=/home/joe/.vagrant.d/data/service-manager/bin/openshift/1.3.1:$PATH

# run following command to configure your shell:
# eval "$(VAGRANT_NO_COLOR=1 vagrant service-manager install-cli openshift --cli-version 1.3.1 | tr -d '\r')"

~]$ vagrant service-manager install-cli openshift --cli-version 1.3.1 --path ~/bin/oc
# Binary now available at /home/joe/bin/oc
# run binary as:
# oc <command>
export PATH=/home/joe/bin:$PATH

# run following command to configure your shell:
# eval "$(VAGRANT_NO_COLOR=1 vagrant service-manager install-cli openshift --path /home/joe/bin/oc --cli-version 1.3.1 | tr -d '\r')"

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

~]$ 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 to log in from your host system, you need 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 Container Development Kit from your host system, use the following command:

~]$ oc login -u openshift-dev -p devel https://10.1.2.2:8443
x509: certificate signed by 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
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"
- name: openshift-dev/10-1-2-2:8443
  user:
    token: THdHS4sw1qgzs95CnCf5ic6D8eOrZss1aT5jyGOmd2w

To log out, use the oc logout command:

~]$ 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"
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
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
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
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
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
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
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

There are also templates bundled with the Container Development Environment. Find them in the /opt/adb/openshift/templates/common directory:

~]$ ls -1 /opt/adb/openshift/templates/common/
cakephp.json
cakephp-mysql.json
eap64-basic-s2i.json
eap64-mysql-persistent-s2i.json
image-streams.json
jboss-image-streams.json
jenkins-ephemeral-template.json
jenkins-persistent-template.json
jenkins-slave-template.json
jws30-tomcat7-mysql-persistent-s2i.json
nodejs.json
nodejs-mongodb.json
wildfly-image-streams.json

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
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
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",
[...]

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
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
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
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 -
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.