Getting Started
Getting Started with OpenShift Container Platform 3.9
Abstract
Chapter 1. Overview
1.1. Introduction
OpenShift Container Platform brings together Docker and Kubernetes, and provides an API to manage these services. OpenShift Container Platform allows you to create and manage containers.
1.1.1. Why Should I Use OpenShift?
Containers are standalone processes that run within their own environment, independent of the operating system and the underlying infrastructure. OpenShift helps you to develop, deploy, and manage container-based applications. It provides you with a self-service platform to create, modify, and deploy applications on demand, thus enabling faster development and release life cycles.
Think of images as cookie cutters and containers as the actual cookies.
Think of OpenShift as an operating system, images as applications that you run on them, and the containers as the actual running instances of those applications.
If you already have OpenShift Container Platform installed, find the appropriate topic based on your role to get started:
I am a… | Links to relevant topics |
---|---|
Platform administrator | Install basic OpenShift Container Platform environment or Install production OpenShift Container Platform environment. |
Developer | Step through the basics of how to Create and Build an Image Using the Web Console and create your first project and application. |
Chapter 2. Install OpenShift Container Platform
2.1. Overview
This guide introduces you to the basic concepts of OpenShift Container Platform, and helps you install a basic application. This guide is not suitable for deploying or installing a production environment of OpenShift Container Platform.
This guide uses the quick installer for the initial cluster installation; however, as of OpenShift Container Platform 3.9, the quick installation method is deprecated. In a future release, it will be removed completely, and the procedure in this guide will be updated accordingly. In addition, using the quick installer to upgrade from version 3.7 to 3.9 is not supported. The advanced installation method will continue to be supported for new installations and cluster upgrades.
2.1.1. Prerequisites
To install OpenShift Container Platform, you will need:
-
At least two physical or virtual RHEL 7+ machines, with fully qualified domain names (either real world or within a network) and password-less SSH access to each other. This guide uses
master.openshift.example.com
andnode.openshift.example.com
. These machines must be able to ping each other using these domain names. - A valid Red Hat subscription.
Wildcard DNS resolution that resolves your domain to the IP of the node. So, an entry like the following in your DNS server:
master.openshift.example.com. 300 IN A <master_ip> node.openshift.example.com. 300 IN A <node_ip> *.apps.openshift.example.com. 300 IN A <node_ip>
When using OpenShift Container Platform to deploy applications, an internal router needs to proxy incoming requests to the corresponding application pod. By using apps as part of the application domains, the application traffic is accurately marked to the right pod.
You can use anything other than apps.
*.cloudapps.openshift.example.com. 300 IN A <node_ip>
Once these are configured, use the following steps to set up a two-machine OpenShift Container Platform install.
2.1.2. Attach OpenShift Container Platform Subscription
As root on the target machines (both master and node), use
subscription-manager
to register the systems with Red Hat.$ subscription-manager register
Pull the latest subscription data from Red Hat Subscription Manager (RHSM):
$ subscription-manager refresh
List the available subscriptions.
$ subscription-manager list --available
Find the pool ID that provides OpenShift Container Platform subscription and attach it.
$ subscription-manager attach --pool=<pool_id>
-
Replace the string
<pool_id>
with the pool ID of the pool that provides OpenShift Container Platform. The pool ID is a long alphanumeric string.
These RHEL systems are now authorized to install OpenShift Container Platform. Now you need to tell the systems from where to get OpenShift Container Platform.
2.1.3. Set Up Repositories
On both master and node, use subscription-manager
to enable the repositories that are necessary in order to install OpenShift Container Platform. You may have already enabled the first two repositories in this example.
$ subscription-manager repos --enable="rhel-7-server-rpms" \ --enable="rhel-7-server-extras-rpms" \ --enable="rhel-7-server-ose-3.9-rpms" \ --enable="rhel-7-fast-datapath-rpms" \ --enable="rhel-7-server-ansible-2.4-rpms"
This command tells your RHEL system that the tools required to install OpenShift Container Platform will be available from these repositories. Now we need the OpenShift Container Platform installer that is based on Ansible.
2.1.4. Install the OpenShift Container Platform Package
The installer for OpenShift Container Platform is provided by the atomic-openshift-utils
package. Install it using yum
on both the master and the node, after running yum update
.
$ yum -y install wget git net-tools bind-utils iptables-services bridge-utils bash-completion kexec-tools sos psacct $ yum -y update $ yum -y install atomic-openshift-utils $ yum -y install docker
2.1.5. Set up Password-less SSH Access
Before running the installer on the master, set up password-less SSH access as this is required by the installer to gain access to the machines. On the master, run the following command.
$ ssh-keygen
Follow the prompts and just hit enter when asked for pass phrase.
An easy way to distribute your SSH keys is by using a bash
loop:
$ for host in master.openshift.example.com \ node.openshift.example.com; \ do ssh-copy-id -i ~/.ssh/id_rsa.pub $host; \ done
2.1.6. Run the Installer
Run the installer on the master.
$ atomic-openshift-installer install
This is an interactive install process that guides you through the various steps. In most cases, you want the default options. When it starts, select the option for OpenShift Container Platform. You are installing one master and one node and the domain name is the FQDN as mentioned at the start of this section, master.openshift.example.com
and node.openshift.example.com
.
At the step where the installer asks you for the FQDN for the routes, you must use apps.openshift.example.com
, or cloudapps.openshift.example.com
as discussed earlier, and NOT openshift.example.com
. If you make an error, you can edit the /etc/origin/master/master-config.yaml at the end of the install process and make this change yourself by looking for the subdomain
entry.
This install process takes approximately 5-10 minutes.
2.1.7. Start OpenShift Container Platform
After a successful install, use the following command to start OpenShift Container Platform.
# systemctl restart atomic-openshift-master-api atomic-openshift-master-controllers
Once installed and started, before you add a new project, you need to set up basic authentication, user access, and routes.
2.2. Interact with OpenShift Container Platform
OpenShift Container Platform provides two command line utilities to interact with it.
-
oc
: for normal project and application management oc adm
: for administrative tasksWhen running
oc adm
commands, you should run them only from the first master listed in the Ansible host inventory file, by default /etc/ansible/hosts.
Use oc --help
and oc adm --help
to view all available options.
In addition, you can use the web console to manage projects and applications. The web console is available at https://<master_fqdn>:8443/console
. In the next section, you will see how to create user accounts for accessing the console.
You can interact with your OpenShift Container Platform instance from a remote system as well, using these command line utilities. Bundled as the OpenShift CLI, you can download these utilities for Windows, Mac, or Linux environments here.
2.3. Understand Roles and Authentication
By default, when installed for the first time, there are no roles or user accounts created in OpenShift Container Platform, so you need to create them. You have the option to either create new roles or define a policy that allows anyone to log in (to start you off).
Before you do anything else, log in at least one time with the default system:admin user. On the master, run the following command:
$ oc login -u system:admin
All commands from now on should be executed on the master, unless otherwise indicated.
By logging in at least one time with this account, you will create the system:admin user’s configuration file, which will allow you to log in subsequently.
There is no password for this system account.
Run the following command to verify that OpenShift Container Platform was installed and started successfully. You will get a listing of the master and node, in the Ready
status.
$ oc get nodes
To continue configuring your basic OpenShift Container Platform environment, follow the steps outlined in Configure OpenShift Container Platform.
Chapter 3. Configure OpenShift Container Platform
3.1. Overview
This guide introduces you to the basic concepts of OpenShift Container Platform, and helps you configure a basic application. This guide provides the configuration steps following the installation of a basic OpenShift Container Platform environment, and is not suitable for deploying or installing a production environment of OpenShift.
3.2. Change Log In Identity Provider
The default behavior of a freshly installed OpenShift Container Platform instance is to deny any user from logging in. To change the authentication method to HTPasswd:
- Open the /etc/origin/master/master-config.yaml file in edit mode.
-
Find the
identityProviders
section. -
Change
DenyAllPasswordIdentityProvider
toHTPasswdPasswordIdentityProvider
provider. Change the value of the name label to
htpasswd_auth
and add a new linefile: /etc/origin/openshift-passwd
in the provider section.An example
identityProviders
section withHTPasswdPasswordIdentityProvider
would look like the following.oauthConfig: ... identityProviders: - challenge: true login: true name: htpasswd_auth provider provider: apiVersion: v1 kind: HTPasswdPasswordIdentityProvider file: /etc/origin/openshift-passwd
- Save the file.
3.3. Create User Accounts
Now that you are using the HTPasswdPasswordIdentityProvider
provider, you need to generate these user accounts.
You can use the httpd-tools package to obtain the htpasswd binary that can generate these accounts.
# yum -y install httpd-tools
Create a user account.
# touch /etc/origin/openshift-passwd # htpasswd -b /etc/origin/openshift-passwd admin redhat
You have created a user,
admin
, with the password,redhat
.Restart OpenShift before going forward.
# systemctl restart atomic-openshift-master-api atomic-openshift-master-controllers
Give this user account
cluster-admin
privileges, which allows it to do everything.$ oc adm policy add-cluster-role-to-user cluster-admin admin
When running
oc adm
commands, you should run them only from the first master listed in the Ansible host inventory file, by default /etc/ansible/hosts.You can use this username/password combination to log in via the web console or the command line. To test this, run the following command.
$ oc login -u admin
Before going forward, change to the default
project.
$ oc project default
For more details, see roles and authentication.
3.4. Deploy the OpenShift Router
The OpenShift router is the entry point for external network traffic destined for OpenShift services. It supports HTTP, HTTPS, and any TLS-enabled traffic that uses SNI, which enables the router to send traffic to the correct service.
Without the router, OpenShift services and pods are unable to communicate with any resource outside of the OpenShift instance.
The installer creates a default router.
Delete the default router using the following command.
$ oc delete all -l router=router
Create a new default router.
$ oc adm router --replicas=1 --service-account=router
The OpenShift documentation contains detailed information on Router Overview.
3.5. Deploy an Internal Registry
Openshift provides an internal, integrated Docker registry that can be deployed to locally manage images. OpenShift uses the docker-registry to store, retrieve, and build Docker images, as well as deploy and manage them throughout their lifecycle.
The installer creates a default registry.
Chapter 4. Create and Build an Image Using the Web Console
4.1. Overview
This getting started experience walks you through the simplest way to get a sample project up and running on OpenShift Container Platform. 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 OpenShift Container Platform version 3 (v3), you might want to start by reading about what’s new. This version of OpenShift Container Platform is significantly different from version 2 (v2).
OpenShift Container Platform 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 |
---|---|
Ruby | |
Python | |
Node.js | |
PHP | |
Perl | |
Java |
Other images provided by OpenShift Container Platform include:
In addition, JBoss Middleware has put together a broad range of OpenShift Container Platform templates.
The technologies available with the xPaaS services in particular include:
- Java EE 6 Application Server provided by JBoss EAP 6
- Integration and Messaging Services provided by JBoss Fuse and JBoss A-MQ
- Data Grid Service provided by JBoss Data Grid
- Real Time Decision Service provided by JBoss BRMS
- Java Web Server 3.0 provided by Tomcat 7 and Tomcat 8
With each of these offerings, a series of combinations are provided:
- HTTP only versus HTTP and HTTPS
- No database required, or the use of either MongoDB, PostgreSQL, or MySQL
- If desired, integration with A-MQ
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.
4.1.1. Browser Requirements
Review the browser versions and operating systems that can be used to access the web console.
4.2. Before You Begin
Before you can get started:
- You must be able to access a running instance of OpenShift Container Platform. 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 OpenShift Container Platform CLI downloaded and installed.
4.3. Forking the Sample Repository
Visit the Ruby example page while you are logged in to GitHub.
NoteThis topic follows the Ruby example, but you can follow along using any of the language examples provided in the OpenShift Container Platform GitHub project.
You are redirected to your new fork.
- Copy the clone URL for your fork.
- Clone the repository to your local machine.
4.4. Creating a Project
To create an application, you must first create a new project, then select an InstantApp template. From there, OpenShift Container Platform begins the build process and creates a new deployment.
- Visit the OpenShift Container Platform web console in your browser. The web console uses a self-signed certificate, so if prompted, continue past a browser warning.
- Log in using the username and password recommended to you by your administrator.
- To create a new project, click New Project.
- Type a unique name, display name, and description for the new project.
Click Create.
The web console’s welcome screen loads.
4.5. Creating an Application
The Select Image or Template page gives you the option to create from a publicly accessible git repository, or from a template:
- If creating a new project did not automatically redirect you to the Select Image or Template page, you might need to click Add to Project.
- Click Browse, then select ruby from the drop-down list.
- Click the ruby:latest builder image.
-
Type a name for your application, and specify the Git Repository URL, which is
https://github.com/<your_github_username>/ruby-ex.git
. - Optionally, click Show advanced routing, build, and deployment options, though by default this example application automatically creates a route, webhook trigger, and build change triggers.
Click Create.
NoteAfter creation, some of these settings can be modified from the web console by clicking Browse, Builds, select your build, then click Actions, and either Edit or Edit YAML.
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.
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.
4.6. Verify the Application is Running
If your DNS is correctly configured, then your new application can be accessed using a web browser. If you cannot access your application, then speak with your system administrator.
To view your new application:
-
In the web console, view the overview page to determine the web address for the application. For example, under SERVICE: RUBY-EX you should see something similar to:
ruby-ex-my-test.example.openshiftapps.com
. - Visit the web address for your new application.
4.7. Configuring Automated Builds
You forked the source code for this application from the OpenShift Container Platform 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:
- From the Web Console, navigate to the project containing your application.
- Click the Browse tab, then click Builds.
- Click your build name, then click the Configuration tab.
- Click next to GitHub webhook URL to copy your webhook payload URL.
- 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 OpenShift Container Platform server to ensure that communication is successful. If you 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.
4.8. Writing a Code Change
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
toThis 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 OpenShift Container Platform handles the rest.
4.8.1. Manually Rebuilding Images
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:
- Click the Browse tab, then click Builds.
- Find your build, then click Start Build.
Chapter 5. Create and Build an Image Using the CLI
5.1. Overview
This getting started experience walks you through the simplest way to get a sample project up and running on OpenShift Container Platform. 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 OpenShift Container Platform version 3 (v3), you might want to start by reading about what’s new. This version of OpenShift Container Platform is significantly different from version 2 (v2).
OpenShift Container Platform 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 |
---|---|
Ruby | |
Python | |
Node.js | |
PHP | |
Perl | |
Java |
Other images provided by OpenShift Container Platform include:
In addition, JBoss Middleware has put together a broad range of OpenShift Container Platform templates.
The technologies available with the xPaaS services in particular include:
- Java EE 6 Application Server provided by JBoss EAP 6
- Integration and Messaging Services provided by JBoss Fuse and JBoss A-MQ
- Data Grid Service provided by JBoss Data Grid
- Real Time Decision Service provided by JBoss BRMS
- Java Web Server 3.0 provided by Tomcat 7 and Tomcat 8
With each of these offerings, a series of combinations are provided:
- HTTP only versus HTTP and HTTPS
- No database required, or the use of either MongoDB, PostgreSQL, or MySQL
- If desired, integration with A-MQ
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.
5.2. Before You Begin
Before you can get started:
- You must be able to access a running instance of OpenShift Container Platform. 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 OpenShift Container Platform CLI downloaded and installed.
5.3. Forking the Sample Repository
Visit the Ruby example page while you are logged in to GitHub.
NoteThis topic follows the Ruby example, but you can follow along using any of the language examples provided in the OpenShift Container Platform GitHub project.
You are redirected to your new fork.
- Copy the clone URL for your fork.
- Clone the repository to your local machine.
5.4. Creating a Project
To create an application, you must create a new project and specify the location of the source. From there, OpenShift Container Platform begins the build process and creates a new deployment.
Log into OpenShift Container Platform 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.
5.5. Creating an Application
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
OpenShift Container Platform 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.
The oc status
command tells you what IP address the service is running; the default port it deploys to is 8080.
5.6. Create a Route
An OpenShift Container Platform 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
ruby-ex
:$ oc expose service ruby-ex
View your new route:
$ oc get route
-
Copy the route location, which will be something like
ruby-ex-my-test.example.openshiftapps.com
.
5.7. Verify the Application is Running
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.
The example 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.
5.8. Configuring Automated Builds
You forked the source code for this application from the OpenShift Container Platform 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
BuildConfig
:$ 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 OpenShift Container Platform server to ensure that communication is successful. If you 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.
5.9. Writing a Code Change
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
toThis 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 OpenShift Container Platform handles the rest.
5.9.1. Manually Rebuilding Images
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
5.10. Troubleshooting
Changing Projects
Although the 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