Get started with OpenShift
Chapter 1. Overview
OpenShift Enterprise 3 is a platform as a service (PaaS) offering from Red Hat that brings together Docker, Kubernetes, and an API to manage these services. OpenShift Enterprise 3 (OSE) allows you to create and manage containers. Containers are standalone processes that run within their own environment.
1.1. About This Guide
This guide introduces you to the basic concepts of OSE3, and helps you install and configure a basic application from an xPaaS image. This guide is not suitable for deploying or installing a production environment of OpenShift. For that, please refer to the official OpenShift documentation.
1.2. Why Should I Use OpenShift?
Containers are standalone processes that run within their own environment, independent of 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.
The most relatable example is that of a web server. The developer creates, for example, a JBoss Web Server image with a specific configuration and you download this image from the registry. You then run this image as a container within your own OpenShift install, then use this web server for running your own website. This whole process of downloading and running your web server takes no more than a few minutes.
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.
Chapter 2. Get Started
To get started, you will need to:
- Install OpenShift on a physical or virtual RHEL 7+ system
- Understand the various ways to interact with OpenShift
- Understand authentication and set up a basic account
- Set up the Router and the Registry (with storage)
- Get a base image and run it as a container
Chapter 3. Install OpenShift Enterprise 3
To install OpenShift Enterprise, 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 and node.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 <IP of the master> node.openshift.example.com. 300 IN A <IP of the node> *.apps.openshift.example.com. 300 IN A <IP of the node>
When using OpenShift 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. For example,
*.cloudapps.openshift.example.com. 300 IN A <IP of the node>
will work just as well.
Once you have acquired these items, use these steps to set up a two-machine OpenShift Enterprise install.
3.1. Attach OpenShift Subscription
On the target machines (both master and node), as root, use
subscription-managerto register the systems with Red Hat:
$ subscription-manager register
List the available subscriptions:
$ subscription-manager list --available
Find the pool ID that provides OpenShift Subscription and attach it:
$ subscription-manager attach --pool=<pool_id>
Replace the string
<pool_id>with the pool ID of the pool that provides OSE 3. The pool ID is a long alphanumeric string.
These RHEL systems are now authorized to install OpenShift. Now you need to tell the systems where to get OpenShift from.
3.2. Set Up Repositories
On both master and node, use
subscription-manager to enable the repositories that are necessary in order to install OpenShift (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.2-rpms"
rhel-7-server-ose-3.3-rpms for OpenShift Container Platform 3.3 and
rhel-7-server-ose-3.4-rpms for OpenShift Container Platform 3.4
This command tells your RHEL system that the tools required to install OpenShift will be available from these repositories. Now we need the OpenShift installer that is based on Ansible.
3.3. Install the OpenShift Enterprise Package
The installer for OpenShift Enterprise is provided by the
atomic-openshift-utils package. Install it using
yum on both the master and the node, after running
$ yum update $ yum install atomic-openshift-utils
3.4. Run the Installer
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:
Follow the prompts and just hit enter when asked for passphrase. Once done:
for host in master.openshift.example.com node.openshift.example.com; do ssh-copy-id -i ~/.ssh/id_rsa.pub $host; done
Then, 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 Enterprise 3.2 (or OpenShift Container Platform 3.3/3.4). Also, 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
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
This install process takes about 5-10 minutes.
3.5. Start OpenShift
After a successful install, use the following command to start OpenShift:
systemctl start atomic-openshift-master
Run the following command to verify that OpenShift Enterprise was installed and started successfully. You will get a listing of the master and node, in the
oc get nodes
Once installed and started, before you add a new project, you need to set up basic authentication, user access, and routes.
Chapter 4. Interact with OpenShift Enterprise 3
OpenShift provides two command line utilities to interact with it.
oc: for normal project and application management
oadm: for administrative tasks
oc --help and
oadm --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 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.
Chapter 5. Understand Roles and Authentication
By default, when installed for the first time, there are no roles or user accounts created in OSE, 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:
$ 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.
5.1. Change Log In Identity Provider
The default behavior of a freshly installed OSE 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 editing mode.
Change the value of the name label to
htpasswd_authand add a new line
file: /etc/origin/openshift-passwdin the provider section.
HTPasswdPasswordIdentityProviderwould look like this:
identityProviders: - challenge: true login: true name: htpasswd_auth provider: apiVersion: v1 file: /etc/origin/openshift-passwd kind: HTPasswdPasswordIdentityProvider
- Save the file.
5.2. 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
Note that you have created a user with the username of
adminand password of
Restart OpenShift before going forward.
systemctl restart atomic-openshift-master
Give this user account
cluster-adminprivileges (which allows it to do everything):
oadm policy add-cluster-role-to-user cluster-admin admin
Now, you can use this username/password combination to log in via the web console or the command line. To test this:
oc login -u admin
Before going forward, change to the
oc project default
Chapter 6. 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.
From OpenShift 3.2 onwards, 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:
$ oadm router --replicas=1 --service-account=router
The OpenShift documentation contains detailed information on router deployment.
Chapter 7. Deploy a Docker 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.
From OpenShift 3.2 and onwards, the installer creates a default registry.
Delete the default registry using the following command:
oc delete all -l docker-registry=default
Create the docker-registry service in the default project using the registry service account:
$ oadm registry
The OpenShift documentation contains detailed information on docker registry.
Chapter 8. Create Persistent Storage for the Registry
The registry that you created in the previous step stores images and metadata, and uses an ephemeral volume for any pod deployment if persistent storage is not configured. This ephemeral volume is destroyed when the pod exits, losing all data, including any images built or pushed into the registry.
To configure persistent storage for the registry:
- provision a volume that points to a storage server on your network (we will just create it on the master)
- create a volume claim.
- manually add the claim to the registry service.
The following steps to configure persistent storage for the registry apply to storage for any image that requires persistent data and not just for the registry. The registry is just another image in the OpenShift environment.
8.1. Provision the Persistent Volume
Create a registry volume file on your master, as shown here, and call it registry-volume.yaml;
apiVersion: v1 kind: PersistentVolume metadata: name: registry-volume spec: capacity: storage: 3Gi accessModes: - ReadWriteMany nfs: path: /root/storage server: master.openshift.example.com
The folder /root/storage must exist. Make sure to change the server entry to point to your master.
Create the registry persistent volume in OpenShift:
$ oc create -f registry-volume.yaml
8.2. Create the Persistent Volume Claim
Create a claim to bind the persistent volume created earlier. This claim is what ties the registry service to the persistent volume.
Create another file called registry-volume-claim.yaml:
apiVersion: v1 kind: PersistentVolumeClaim metadata: name: registry-volume-claim spec: accessModes: - ReadWriteMany resources: requests: storage: 3Gi
Create the claim:
$ oc create -f registry-volume-claim.yaml
You have now created the Persistent Volume and the Persistent Volume Claim, and now need to add this claim to the registry.
8.3. Add the Claim to the Registry
$ oc volume dc/docker-registry --add --overwrite -t persistentVolumeClaim --claim-name=registry-volume-claim --name=registry-storage
The docker-registry will now use the 3 GB persistent volume created above for storing image and metadata.
Chapter 9. Deploy your first Image
At this stage, you are ready to get a basic Hello World image deployed and running in your OpenShift instance.
- Log in to the OpenShift web console at https://master.openshift.example.com:8443/console/. Use the username and password that you created in the roles and authentication section.
Click on New Project and enter the name of the project as
hello-openshift. The next screen will show you the available images to add to your project. Since we only set up storage for the registry image, we will only be able to add those images that don’t require persistence.
- Click on a desired image. For testing purposes, select jenkins-ephemeral.
- You don’t need to change any details for this image. Click Create to create the image and start the deployment of this image as a pod.
- Click Continue to Overview and wait for the Jenkins pod to be deployed. The pod is deployed once the pod’s outline becomes blue and 1 appears in the middle of it. This may take a few minutes.
- The pod, once deployed, will allow you to play with your Jenkins instance. The link to this instance is displayed in the Overview page, next to the pod and will be similar to https://jenkins-hello-openshift.apps.openshift.example.com/.
You have successfully installed OpenShift and deployed your first pod!