In the empty project, select the Add to Project button in the centre of the page.

You should be presented with the catalog browser.

For deploying an application from an existing Docker-formatted container image, you need to switch to the Deploy Image tab.

If applications had previously been deployed to the project, or you were not on the project Overview page, you can also use the Add to Project drop down menu in the top menu bar, selecting Deploy Image.

When you are deploying an application from an image, there are two choices.

The first choice is to select an image by specifying its Image Stream Tag. This option would be used where the image had previously been imported into the OpenShift cluster, or had been built within the OpenShift cluster from a Dockerfile or using Source-to-Image.

The second choice is to specify the Image Name, where the image resides on an external image registry. This can be the Docker Hub Registry, or any other accessible image registry.

For this example, the application image we are going to deploy is being hosted on the Docker Hub Registry. You should therefore select the Image Name option.

In the Image name or pull spec field enter:

openshiftkatacoda/blog-django-py

Press Enter, or click on the magnifying glass to the right of the field. This should trigger a query to pull down the details of the image from the Docker Hub Registry, including information on when the image was last updated, the size of the image and the number of layers.

From the name of the image, the Name field will be automatically populated. This name is used in OpenShift to identify the resources created when the application is deployed. This will include the internal Service name used by other applications in the same project to communicate with it, as well as being used as part of the default hostname for the application if exposed externally to the cluster via a Route.

In this example leave the Name field as blog-django-py. For your own application you would consider changing this name to something more appropriate.

When you are ready, at the bottom of the page click on Create. This will take you to a splash page confirming the application deployment is occurring.

Click on Continue to overview and you will be returned to the Overview page, where you can view the details of the application created and monitor progress as it is deployed. When deployment as finished you should see:

Whenever you deploy any application from an existing Docker-formatted container image using the Deploy Image page of the OpenShift web console, it will by default only be visible internally to the OpenShift cluster, and usually only to other applications within the same project.

If the application is a web application and you need to make it visible outside of the OpenShift cluster so users can access it, you will need to expose it via a Route.

That an application is not visible and may need to be exposed to be visible can be determined from the Overview page for a project and the details of the application displayed. In particular, if the application is not being exposed, then Create Route will be displayed to the right of the application name.

Routes can be used to expose any application which communicates over HTTP. OpenShift can handle termination for secure HTTP connections, or a secure connection can be tunnelled through direct to the application, with the application handling termination of the secure connection. Non HTTP applications can be exposed via a tunnelled secure connection if the client supports the SNI extension for a secure connection using TLS.

To expose the sample application you have deployed, click on Create Route. This will display a page for entering the route details.

If you do not modify any of the pre-populated values, OpenShift will automatically assign a hostname for the application as a sub domain of the hostname for the OpenShift cluster.

To override the hostname you can modify the Hostname field. For this to work you would need to control the DNS which has delegated authority for that hostname and be able to set up a CNAME for the hostname mapping to the hostname for the OpenShift cluster's router.

No matter what port the application listens to internally to the OpenShift cluster, port 8080 in this case, the external route will use the standard port 80 for the HTTP connection, and the standard port 443 for a secure HTTP connection.

Before creating the route, ensure that the app label is listed with value blog-django-py. Add this label if not present as we will be using it later.

Leaving all all other values as their defaults, click on Create and you will be returned to the Overview page for the project. Instead of Create Route, you should now see the URL by which the exposed application can be accessed from a web browser.

Click on the URL and a new browser window should open showing the sample application.

Instead of deploying the existing Docker-formatted container image from the web console, you can use the command line. Before we do that, lets delete the application we have already deployed.

To do this from the web console you could visit each resource type created and delete them one at a time. The simpler way to delete an application is from the command line using the oc program.

To see a list of all the resources that have been created in the project so far, you can run the command:

oc get all -o name

This will display output similar to:

imagestreams/blog-django-py
deploymentconfigs/blog-django-py
replicationcontrollers/blog-django-py-1
routes/blog-django-py
services/blog-django-py
pods/blog-django-py-1-9fshs

You have only created one application, so you would know that all the resources listed will relate to it. When you have multiple applications deployed, you need to identify those which are specific to the application you may want to delete. You can do this by applying a command to a subset of resources using a label selector.

To determine what labels may have been added to the resources, select one and display the details on it. To look at the Route which was created, you can run the command:

oc describe route/blog-django-py

This should display output similar to:

Name:                   blog-django-py
Namespace:              myproject
Created:                17 minutes ago
Labels:                 app=blog-django-py
Annotations:            openshift.io/host.generated=true
Requested Host:         blog-django-py-myproject.2886795279-80-ollie02.environments.katacoda.com
                          exposed on router router 17 minutes ago
Path:                   <none>
TLS Termination:        <none>
Insecure Policy:        <none>
Endpoint Port:          8080-tcp

Service:        blog-django-py
Weight:         100 (100%)
Endpoints:      172.18.0.3:8080

In this case when deploying the existing Docker-formatted container image via the OpenShift web console, OpenShift has applied automatically to all resources the label app=blog-django-py. You can confirm this by running the command:

oc get all --selector app=blog-django-py -o name

This should display the same list of resources as when oc get all -o name was run. To double check that this is doing what is being described, run instead:

oc get all --selector app=blog -o name

In this case, because there are no resources with the label app=blog, the result will be empty.

Having a way of selecting just the resources for the one application, you can now schedule them for deletion by running the command:

oc delete all --selector app=blog-django-py

To confirm that the resources have been deleted, run again the command:

oc get all -o name

If you do still see any resources listed, keep running this command until it shows they have all been deleted. You can find that resources may not be deleted immediately as you only scheduled them for deletion and how quickly they can be deleted will depend on how quickly the application can be shutdown.

Although label selectors can be used to qualify what resources are to be queried, or deleted, do be aware that it may not always be the app label that you need to use. When an application is created from a template, the labels applied and their names are dictated by the template. As a result, a template may use a different labelling convention. Always use oc describe to verify what labels have been applied and use oc get all --selector to verify what resources are matched before deleting any resources.

You now have a clean project again, so lets deploy the same existing Docker-formatted image, but this time using the oc command line program.

The name of the image you used previously was:

openshiftkatacoda/blog-django-py

If you have been given the name of an image to deploy and want to verify that it is valid from the command line, you can use the oc new-app --search command. For this image run:

oc new-app --search openshiftkatacoda/blog-django-py

This should display output similar to:

Docker images (oc new-app --docker-image=<docker-image> [--code=<source>])
-----
openshiftkatacoda/blog-django-py
  Registry: Docker Hub
  Tags:     latest

It confirms that the image is found on the Docker Hub Registry.

To deploy the image, you can run the command:

oc new-app openshiftkatacoda/blog-django-py

This will display out similar to:

--> Found Docker image d7eda0c (22 hours old) from Docker Hub for "openshiftkatacoda/blog-django-py"

    Python 3.5
    ----------
    ...

    Tags: builder, python, python35, rh-python35

    * An image stream will be created as "blog-django-py:latest" that will track this image
    * This image will be deployed in deployment config "blog-django-py"
    * Port 8080/tcp will be load balanced by service "blog-django-py"
      * Other containers can access this service through the hostname "blog-django-py"

--> Creating resources ...
    imagestream "blog-django-py" created
    deploymentconfig "blog-django-py" created
    service "blog-django-py" created
--> Success
    Run 'oc status' to view your app.

OpenShift will assign a default name based on the name of the image, in this case blog-django-py. You can specify a different name to be given to the application, and the resources created, by supplying the --name option along with the name you wish to use as an argument.

As with when deploying an existing Docker-formatted image from the web console, it is not exposed outside of the OpenShift cluster by default. To expose the application created so it is available outside of the OpenShift cluster, you can run the command:

oc expose service/blog-django-py

Switch to the OpenShift web console by selecting on Dashboard to verify that the application has been deployed. Select on the URL displayed on the Overview page for the project to visit the application.

Alternatively, to view the hostname assigned to the route created from the command line, you can run the command:

oc get route/blog-django-py

When you deploy an existing Docker-formatted container image which resides on an external image registry, the image will be pulled down and stored within the internal OpenShift image registry. The image will then be copied to any node in the OpenShift cluster where an instance of the application is run.

In order to track the image that is pulled down, an Image Stream resource will be created. You can list what image stream resources have been created within a project by running the command:

oc get imagestream -o name

This should yield the output:

imagestream/blog-django-py

To show further details about the image stream resource, run the command:

oc describe imagestream/blog-django-py

This should yield output similar to:

Name:                   blog-django-py
Namespace:              myproject
Created:                4 minutes ago
Labels:                 app=blog-django-py
Annotations:            openshift.io/generated-by=OpenShiftNewApp
                        openshift.io/image.dockerRepositoryCheck=2017-03-20T02:51:09Z
Docker Pull Spec:       172.30.125.109:5000/myproject/blog-django-py
Image Lookup:           local=false
Unique Images:          1
Tags:                   1

latest
  tagged from openshiftkatacoda/blog-django-py

  * openshiftkatacoda/[email protected]:43e78e610a3181a4b710f938598acaf43d511ab38c4e84a98e59f29dbdb62c62
      4 minutes ago

In the details of the image stream which was created, you will see that the label app=blog-django-py was applied, identifying the image as relating to this one deployment. Consequently, when the application was deleted by using a label selector with the same value, the image stream would also be deleted.

When you are deploying only a single instance of the application from the image, this is reasonable, but if you need to deploy multiple instances of an application from the same image, with different names, you should import the image as a separate step before attempting to deploy the image.

Once more, delete the application which was already deployed.

oc delete all --selector app=blog-django-py

Check that all the resource objects have been deleted by running:

oc get all -o name

Now import the existing Docker-formatted container image explicitly using the command:

oc import-image openshiftkatacoda/blog-django-py --confirm

This should yield the output:

The import completed successfully.

Name:                   blog-django-py
Namespace:              myproject
Created:                Less than a second ago
Labels:                 <none>
Annotations:            openshift.io/image.dockerRepositoryCheck=2017-03-20T03:20:35Z
Docker Pull Spec:       172.30.235.4:5000/myproject/blog-django-py
Image Lookup:           local=false
Unique Images:          1
Tags:                   1

latest
  tagged from openshiftkatacoda/blog-django-py

  * openshiftkatacoda/[email protected]:43e78e610a3181a4b710f938598acaf43d511ab38c4e84a98e59f29dbdb62c62
      Less than a second ago

...

This is the details of the image stream created.

Of note, no labels have been applied this time.

Verify that only the image stream has been created, and no other resource objects:

oc get all -o name

To deploy an instance of the application from the image stream which has been created, run the command:

oc new-app blog-django-py --name blog-1

This is using the image stream name, not the full name which identifies the image as being on the Docker Hub Registry.

This should yield output similar to:

--> Found image d29f1bb (2 days old) in image stream "myproject/blog-django-py" under tag "latest" for "blog-django-py"

    Python 3.5
    ----------
    ...

    Tags: builder, python, python35, rh-python35

    * This image will be deployed in deployment config "blog-1"
    * Port 8080/tcp will be load balanced by service "blog-1"
      * Other containers can access this service through the hostname "blog-1"

--> Creating resources ...
    deploymentconfig "blog-1" created
    service "blog-1" created
--> Success
    Run 'oc status' to view your app.

Jump back to the OpenShift web console, click on Add to project in the menu bar, then click on Deploy Image.

This time select Image Stream Tag and from the drop down menus select the project myproject, and the image stream blog-django-py with tag latest.

Change the Name to be used for the deployed application to blog-2. Click on Create at the bottom of the page to start the deployment.

From the command line, list all the resources which have been created.

oc get all -o name

This should yield output similar to:

imagestreams/blog-django-py
deploymentconfigs/blog-1
deploymentconfigs/blog-2
replicationcontrollers/blog-1-1
replicationcontrollers/blog-2-1
services/blog-1
services/blog-2
pods/blog-1-1-mzpbf
pods/blog-2-1-d2snt

You will see a deployment config, replication controller, service and pod for each instance of the application. Only the one image stream exists corresponding to the initial image import that was run.

Delete each application by running:

oc delete all --selector app=blog-1

oc delete all --selector app=blog-2

When the resource objects for each instance of the application have been deleted, you should be left with just the image stream object.

oc get all -o name

Importing the existing Docker-formatted container image before hand, therefore means that it is retained when any application instance using it is deleted.