This getting started experience walks you through the simplest way to get a sample project up and running on OKD. There are a few different ways to launch images within a project, but this topic focuses on the quickest and easiest method.
If this is the first part of the documentation you have read, and you are unfamiliar with the core concepts of OKD version 3 (v3), you might want to start by reading about what’s new. This version of OKD is significantly different from version 2 (v2).
OKD 3 provides out of the box a set of languages and databases for developers with corresponding implementations and tutorials that allow you to kickstart your application development. Language support centers around the Quickstart templates, which in turn leverage builder images.
|Language||Implementations and Tutorials|
Other images provided by OKD include:
To help illustrate constructing such applications, the following sections guide you through creating a project that contains a sample Node.js application that will serve a welcome page and the current hit count (stored in a database).
This topic discusses both Quickstart and Instant App templates and applications. Quickstarts provide a starting point for application development, but they rely on your development to create a useful application. In contrast, Instant Apps like Jenkins are instantly usable.
Before you can get started:
You must be able to access a running instance of OKD. If you do not have access, contact your cluster administrator.
Your instance must be pre-configured by a cluster administrator with the Instant App templates and builder images. If they are not available, direct your cluster administrator to the Loading the Default Image Streams and Templates topic.
You must have the OKD CLI downloaded and installed.
Visit the Ruby example page while you are logged in to GitHub.
This topic follows the Ruby example, but you can follow along using any of the language examples provided in the OKD GitHub project.
You are redirected to your new fork.
Copy the clone URL for your fork.
Clone the repository to your local machine.
To create an application, you must create a new project and specify the location of the source. From there, OKD begins the build process and creates a new deployment.
Log into OKD from the CLI:
With username and password:
$ oc login -u=<username> -p=<password> --server=<your-openshift-server> --insecure-skip-tls-verify
With oauth token:
$ oc login <https://api.your-openshift-server.com> --token=<tokenID>
To create a new project:
$ oc new-project <projectname> --description="<description>" --display-name="<display_name>"
After creating the new project, you will be automatically switched to the new project namespace.
To create a new application from the code in your forked repository:
Create the application by specifying the source of the code:
$ oc new-app openshift/ruby-20-centos7~https://github.com/<your_github_username>/ruby-ex
OKD finds the matching builder image (which in this case is ruby-20-centos7) and then creates resources for the application (image stream, build configuration, deployment configuration, service). It also schedules the build.
Track the progress of the build:
$ oc logs -f bc/ruby-ex
Once the build is complete and the resulting image has successfully pushed to your registry, check the status of your application:
$ oc status
Or you can view the build from the web console.
Creating your application might take some time. You can follow along on the Overview page of the web console to see the new
resources being created, and watch the progress of the build and deployment.
You can also use the
oc get pods command to check when the pod is up and
running, or the
oc get builds command to see build statistics.
While the Ruby pod is being created, its status is shown as pending. The Ruby pod then starts up and displays its newly-assigned IP address. When the Ruby pod is running, the build is complete.
oc status command tells you what IP address the service is running; the
default port it deploys to is 8080.
An OKD route exposes a service at a host name, so that external clients can reach it by name. To create a route to your new application:
Expose a service for
$ oc expose service ruby-ex
View your new route:
$ oc get route
Copy the route location, which will be something like
To view your new application, paste the route location that you copied (in the previous section) into the address bar of your web browser and hit enter.
ruby-ex application is a simple welcome screen, and contains details on how to deploy code changes, manage your application, and other development resources.
Next, configure automated builds via a GitHub webhook trigger, so that code changes in your forked repository cause your application to rebuild.
You forked the source code for this application from the OKD GitHub repository. Therefore, you can use a webhook to automatically trigger a rebuild of your application whenever you push code changes to your forked repository.
To set up a webhook for your application:
View the triggers section of the
BuildConfig to verify that a GitHub webhook trigger exists:
$ oc edit bc/ruby-ex
You should see something similar to this:
triggers - github: secret: Q1tGY0i9f1ZFihQbX07S type: GitHub
The secret ensures that only you and your repository can trigger the build.
Run the following command to display the webhook URLs associated with your
$ oc describe bc ruby-ex
Copy the GitHub webhook payload URL output by the above command.
Navigate to your forked repository on GitHub, then click Settings.
Click Webhooks & Services.
Click Add webhook.
Paste your webhook URL into the Payload URL field.
Click Add webhook to save.
GitHub now attempts to send a ping payload to your OKD server to ensure that communication is successful. If you see see a green check mark appear next to your webhook URL, then it is correctly configured. Hover your mouse over the check mark to see the status of the last delivery.
The next time you push a code change to your forked repository, your application will automatically rebuild.
To work locally and then push changes to your application:
On your local machine, use a text editor to change the sample application’s source for the file ruby-ex/config.ru
Make a code change that will be visible from within your application. For example: on line 229, change the title from
Welcome to your Ruby application on OpenShift to
This is my Awesome OpenShift Application, then save your changes.
Commit the change in git, and push the change to your fork.
If your webhook is correctly configured, your application will immediately rebuild itself based on your changes. Once the rebuild is successful, view your updated application using the route that was created earlier.
Now going forward, all you need to do is push code updates and OKD handles the rest.
You may find it useful to manually rebuild an image if your webhook is not working, or if a build fails and you do not want to change the code before restarting the build. To manually rebuild the image based on your latest committed change to your forked repository:
$ oc start-build ruby-ex
oc new-project command automatically sets your current project to
the one you’ve just created, you can always change projects by running:
$ oc project <project-name>
To view a list of projects:
$ oc get projects
Manually Triggering Builds
If the build does not start automatically, start a build and stream the logs:
$ oc start-build ruby-ex --follow
Alternatively, do not include
--follow in the above command, and instead issue
the following command after triggering the build, where
n is the number of the
build to track:
$ oc logs -f build/ruby-ex-n