oo-install utility is designed to ease the experience of a trial or basic OpenShift installation by interactively gathering the data to run a simple deployment. The current iteration of
oo-install enables the configuration and deployment of OpenShift according to the following scenarios:
Deploy all OpenShift components to one or more hosts
Add a new node host to an existing OpenShift deployment
Do I Have To Read a Manual?
In short, no. One of the design goals of the
oo-install utility is to make this document completely unnecessary. If you are feeling bold, you are heartily encouraged to attempt to use the installer right now without any additionaly guidance. Check out https://install.openshift.com/ for the quick rundown on how to get started. If you run into problems, head back here or send your questions and feedback to the mailing lists or IRC channels mentioned on the oo-install web page.
The locations for the source code of this document and the
oo-install utility are as follows:
This section covers some topics that will help you to have a successful OpenShift deployment. If you have jumped straight in with https://install.openshift.com/ and are having problems, look over this section to make sure you’ve got the basics covered.
Note that it is not necessary to run oo-install on your target system(s) for the OpenShift installation. For instance, it is completely possible to run oo-install from your dekstop system against servers that you have provisioned in the cloud. Consequently the pre-requisities are split between the "installer host" requirements and the "target host" requirements.
The list of utilities required by the installer is as follows:
ruby(1.8.7 or greater)
ssh(if you are deploying OpenShift to systems other than the installer host)
Most operating systems that provide a bash shell will include these utilities (with the possible exception of Ruby).
The follow sections describe the system requirements for a host that will be part of an OpenShift deployment.
OpenShift Origin version 4 is supported on Red Hat Enterprise Linux (RHEL) 6.4 or higher and CentOS 6.4 or higher, 64 bit architecture only. This version is not supported on Fedora, RHEL 7.x or CentOS 7.x.
When you install Red Hat Enterprise Linux or CentOS, you will be given the option to select a starting set of packages:
Be sure to select the "Minimal" installation. This will ensure that the system does not contain any package incompatibilities with OpenShift.
There are no other utility prerequisites; oo-install will check for and offer to install the other utilities that it needs.
If you are running the installer locally, but your OpenShift deployment will be installed on a remote system, you will need passwordless SSH access to your target host(s). "Passwordless" here means that either you are using an SSH key pair that was generated without a password, or that you are using a password manager like ssh-agent to provide the password as necessary.
oo-install utility has been developed to function as a standalone application. However, the easiest way to run it is by using a "curl-to-shell" command to download and execute the latest version of the installer in a single step. This section describes running the curl-to-shell command and also how to run the installer from the source code.
The recommended method for installing OpenShift is via a "curl-to-shell" command. From your command line, just run
$ sh <(curl -s https://install.openshift.com/)
If you want to pass arguments to the installer, include them after the whole command:
$ sh <(curl -s https://install.openshift.com/) -e -s rhsm -u firstname.lastname@example.org
By default, the installer runs in Origin mode. If you want to install OpenShift Enterprise, you can either run:
$ sh <(curl -s https://install.openshift.com/) -e
$ sh <(curl -s https://install.openshift.com/ose/)
OpenShift Enterprise installations require access to Red Hat Subscription Manager or Red Hat Network, and are verified to succeed on hosts running under a current Red Hat Enterprise Linux subscription.
You can download a version of the online installer for use on a CD or USB drive. The latest versions of the portable packages are available at:
OpenShift Origin Portable: https://install.openshift.com/portable/oo-install-origin.zip
OpenShift Enterprise Portable: https://install.openshift.com/portable/oo-install-ose.zip
To use these portable installers:
Download and unzip the portable installer zip file.
Copy or burn the unzipped files to a USB drive or CD-ROM, respectively.
Refer to the included README for instructions on starting the installation from the provided launcher.
Be aware that even if you are using the portable installer, your target hosts systems may still require internet access for necessary OpenShift RPMs.
If you are working on
oo-install development, you can also run the installer directly from source:
Clone the openshift-extras repo from GitHub:
git clone https://github.com/openshift/openshift-extras.git
bundle install(You only need to do this the first time)
bundle exec bin/oo-install
oo-install is built to support remote deployments, you don’t need to set up a development environment on a target system in order to do this; you can clone the repo locally and run installations against remote systems directly from there.
The complete list of options is as follows:
-a, --advanced-mode Enable access to message server and db server customization. -c, --config-file FILEPATH The path to an alternate config file -w, --workflow WORKFLOW_ID The installer workflow for unattended deployment. --force Ignore workflow warnings and automatically install missing RPMs. -l, --list-workflows List the workflow IDs for use with unattended deployment. -e, --enterprise-mode Show OpenShift Enterprise options (ignored in unattended mode) -s, --subscription-type TYPE The software source for installation packages. -u, --username USERNAME Red Hat Login username -p, --password PASSWORD Red Hat Login password --use-existing-puppet For Origin; do not attempt to install the Puppet module -d, --debug Enable debugging messages
By default, the installation utility will automatically install MongoDB and ActiveMQ on the same system that you designate as the OpenShift Broker. If you would prefer to install these services on different hosts systems, pass the -a flag and you will br prompted to provide information on these other target systems. For more on "deployment roles", see the Roles Summarized below.
The installer will look for a configuration file at the default location
~/.openshift/oo-install-cfg.yml. If you want to use a different file, you can pass the filepath with this option. If the file that you specify does not exist, it will automatically be created with some basic settings.
If you have already configured a complete OpenShift deployment, you can run the installer without any user interaction by providing this argument and the ID of an installer workflow. For example, you can run the OpenShift full deployment workflow like this:
$ sh <(curl -s https://install.openshift.com/) -w origin_deploy
When you run the command this way, the installer will sanity check your deployment configuration, and if everything looks good it will run the specified workflow automatically.
When you are using the
-w flag, you can also include the
--force flag; this tells oo-install to automatically install required RPMs (like
puppet for Origin deployments) without asking the user.
In order to use the
-w option, you will need to see a list of the valid workflow IDs that are available. When you run the installer with this flag, it will print out the valid list of IDs and descriptions of each associated workflow.
The list of available workflow IDs will be different depending on if you are performing an OpenShift Origin installation or an OpenShift Enterprise installation. See the
In default mode, the installer will provide you with options for installing or extending an OpenShift Origin deployment. However, the same installer can be used to deploy OpenShift Enterprise by setting this switch.
Subscription refers to where your openshift component RPMs are coming from.
oo-install supports four options:
none - If you have manually configured yum repos on the target hosts, and those repos already include the OpenShift RPMs, the none value tells the installer to use what you have already set up.
yum - Indicates that you would like the installer to create new yum repo entries for you under
rhsm - (For OpenShift Enterprise) Tells the installer that you want to use Red Hat Subscription Manager to set up OpenShift software channels
rhn - (For OpenShift Enterprise) Tells the installer that you want to use Red Hat Network to set up OpenShift software channels
The -s option exists to enable you to override the installer config file from the command line. This would typically be done in concert with the -w option as part of the setup for an unattended installation. For more information on subscriptions see Subscription, below.
As indicated in the explanation of the -s option above, this option exists to enable you to override the installer config file from the command line. Currently, the -u setting is only meaningful in a scenario where you would be running an unattended installation (see -w) of OpenShift Enterprise (see -e) using the rhsm or rhn subscription methods.
See the comments on the -u option; this option would only be used under the same conditions.
When you run the installer for the first time, you will be asked to describe a number of items related to the OpenShift deployment that you want to set up. This whole process should be pretty self-explanatory, but here are some notes about the main facets of the configuration process.
When you use
oo-install to deploy OpenShift, the installer offers to configure a BIND server to run on one of the same hosts where a Broker will run. The primary function of this BIND instance is to provide lookup information for applications that are created by the users of your OpenShift system, but it can also be configured to support a separate zone for the openshift hosts themselves.
Depending on your lab setup, you may already have a DNS solution in place for your host systems. If not, you can opt to register your OpenShift hosts with the Broker’s BIND server. This enables the hosts to look each other up by name in an environment where they may not be able to do name lookups otherwise.
When the installer asks you:
Do you want to register DNS entries for your OpenShift hosts with the same OpenShift DNS service that will be managing DNS records for the hosted applications?
…answering yes will notify the installer that you want this registration to be done. If you do answer yes, you will be asked a followup question:
What domain do you want to use for the OpenShift hosts?
While it is possible for you to answer this question with the same domain that you are using for OpenShift-hosted applications, it is recommended that you use a different domain.
For instance, if your domain is "mycompany.com", you might use:
apps.mycompany.comfor your OpenShift applications domain and
openshift.mycompany.comfor your OpenShift hosts domain
After installation, the Broker-based DNS server can be used separately from a larger DNS infrastructure, or easily configured to work in concert with one. See the Appendix for more on this.
After you have set the DNS configuration, you will be guided through the process of describing the hosts where OpenShift will be installed.
oo-install sees OpenShift deployments as a collection of hosts that have been assigned to certain roles. All of the roles can be assigned to a single host (an "all-in-one" deployment), or they can be distributed to different hosts. Furthermore, all of the roles can be assigned to more than one host to configure a High Availability deployment. See the High Availability Deployments topic for more on this.
There are four roles that a host can perform in an OpenShift deployment: Broker, DBServer, MsgServer and Node.
The Broker role consists of the OpenShift Broker RPMs and an MCollective client. The Broker serves as a central hub of the OpenShift deployment, and provides a web interface where users can manage their hosted applications.
This role consists of the MongoDB database that the Broker uses to track users and applications.
The installer guides you through the process of gathering the following information about each host that you are going to use in your deployment.
This should be pretty self-explanatory. The installer is looking for the fully qualified domain name (FQDN) of the host. If you provided an OpenShift hosts domain during DNS configuration, you can get away with typing just the hostname here and the installer will append the rest for you.
Why can’t I use
If the host in question is not the host where you are running the installer, this field enables you to specify the name of the SSH target for remote installation. This value can be:
An IP address
A DNS name that already resolves to the host
Identical to the Host Name
An alias from your
When you set the value of the SSH Host Name to
localhost, you are telling the installer that you are running
oo-install on the host that you are currently describing. In this case,
oo-install will not use SSH to interact with this host instance, but will attempt to run the commands locally. Otherwise,
oo-install will use this value in conjunction with the User value to start SSH sessions with this host.
When the host that you are currently describing is a remote system, this value is used in conjunction with the SSH Host Name to establish SSH sessions with the target host. If you are running the installer on the target host itself (in other words, if you are using SSH Host Name
localhost for this host instance), then you will not be asked this question; the installation will run with whatever privileges your user account has.
In either case, the user in question must satisfy one of these two requirements:
Have passwordless sudo privileges on the target system
Under RHEL, passwordless sudo configuration may not succeeed unless you set the following in your
Try setting this if you see error messages like:
sudo: sorry, you must have a tty to run sudo
At this point, the installer will attempt to look up the IP addresses that have been assigned to the host that you are currently describing. In a situation where the host has multiple NICs, there may be multiple IP addresses to choose from.
The IP address that is provided here should be the one that would be used by other OpenShift hosts would use to connect with this host.
In the case of Node hosts, you will want to use the IP address that client systems would use to reach the host.
You also have the option of supplying a completely different IP address. This may be necessary in situations where one OpenShift host is separated from the others in a NAT environment.
IP Address and DNS Registration
This value is only collected for Node hosts in OpenShift Origin deployments. This is a requirement of the underlying Puppet infrastructure. If you select one of the IP address / IP interface combos that
oo-install finds on the host, you will not need to provide this at all. On the other hand, if you manually configure the IP address, you will also need to manually specify the interface. To see the available IP interfaces on a given host, you can run this command:
$ ip link show
Which will yield output like this:
1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN mode DEFAULT link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00 2: em1: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UP mode DEFAULT qlen 1000 link/ether f0:de:f1:de:88:0f brd ff:ff:ff:ff:ff:ff 3: wlp3s0: <BROADCAST,MULTICAST> mtu 1500 qdisc noop state DOWN mode DEFAULT qlen 1000 link/ether 24:77:03:64:a9:28 brd ff:ff:ff:ff:ff:ff
Or you can run:
$ ip addr list
Which will additionally provide each interfaces current IP address assignment (if applicable):
1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00 inet 127.0.0.1/8 scope host lo valid_lft forever preferred_lft forever inet6 ::1/128 scope host valid_lft forever preferred_lft forever 2: em1: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UP qlen 1000 link/ether f0:f0:f0:f0:f0:f0 brd ff:ff:ff:ff:ff:ff inet 220.127.116.11/23 brd 10.18.33.255 scope global em1 valid_lft forever preferred_lft forever inet6 1111:11:1:1111:1111:1111:1111:1111/64 scope global dynamic valid_lft 2591966sec preferred_lft 26sec inet6 1111::1111:1111:1111:1111/64 scope link valid_lft forever preferred_lft forever 3: wlp3s0: <BROADCAST,MULTICAST> mtu 1500 qdisc noop state DOWN qlen 1000 link/ether f1:f1:f1:f1:f1:f1 brd ff:ff:ff:ff:ff:ff
Finally, all hosts get configured with service account information. Unlike other settings that are unique to each host,
oo-install ensures that the service account parameters are identical across the deployment. The following items comprise the service account settings and their default values:
mcollective_password: (randomly generated)
mongodb_broker_password: (randomly generated)
mongodb_admin_password: (randomly generated)
openshift_password: (randomly generated)
Any time you modify a host in your deployment,
oo-install gives you an opportunity to revisit these values. Note however that once you have done an initial deployment,
oo-install is not capable of changing the values.
By default, the installer runs in basic mode. In basic mode, the installer automatically assigns the DBServer and MsgServer roles to the same host where the Broker is assigned. If you need more flexibility, you can override basic mode by passing the -a argument to the installer command.
Moving Roles Between Hosts
For low-volume and Proof-of-Concept Origin deployments, you can deploy OpenShift with a single Broker, DBServer and MsgServer role. However,
oo-install also supports thedeployment and configuration of High Availibility options for each of these roles. During your deployment configuration, if you specify more than one host as a Broker, DBServer or MsgServer,
oo-install will automatically configure the additional services and settings necessary for high availability.
Best Practices: The Rule of Three
When you use
oo-install to deploy OpenShift Enterprise, it is up to you to decide how to coordinate the Brokers to act as a highly available cluster. OpenShift Origin deployments solve this by deploying and configuring a simple web proxy to dynamically dispatch Broker requests to one of your Brokers.
You will be asked to provide a virtual Broker hostname and virtual Broker IP address to use. These values are used by an HAProxy server that is installed on the Broker host of your choice. If you are also using OpenShift’s DNS to do name resolution for your host systems, this virtual name / IP combination will be added to that configuration as well.
Picking a Virtual IP Address That Will Work
Installations that are deployed with
oo-install use basic HTTP-based authentication, which is driven by the
/etc/openshift/htpasswd file on the Broker host system. If you are deploying multiple Brokers, you will either need to ensure that all Broker
htpasswd files are kept in sync, or you may want to switch to a different authentication option after the installation is done. If you want a different authentication method from the outset, consider using the OpenShift Origin Puppet module directly.
OpenShift uses MongoDB to manage user and host application information. MongoDB has native replica set support, which
oo-install can configure for you. When you declare more than one DBServer system in an OpenShift deployment, the installer will ask you to choose which host will be the primary, and the rest of the work is done for you.
The installer will ask about three settings related to gear sizes. If you are not familiar with this concept, refer to the User Resource Management section of the Administrators Guide.
The installer configures these settings with the indicated defaults:
valid_gear_sizes- specifies all gear sizes that the current OpenShift Origin installation supports: "small,medium,large"
user_default_gear_sizes- specifies the sizes of gears available to all users upon user creation: "small,medium"
default_gear_size- specifies the size of gear that a new hosted app will get by default: "small"
The actual specifics about what each "gear size" means can be adjusted after installation is completed.
The installer also gathers information about the Node Districts that you would like to deploy. As of Origin version 4, it is no longer possible to deploy a Node host without associating it with a Node District. By default, the install will create a single Node District called "Default" that is associated with the "small" gear size.
At this point, all that remains to configure your OpenShift deployment is to tell
oo-install where you would like to get your OpenShift RPMs from. Refer to the notes on the -s / --subscription-type command-line argument for an explanation of your options.
The installer supports three different ways to set subscription preferences. This is great from a deployment flexibility perspective, but may be really confusing if this is your first time through an OpenShift deployment.
The first way to set subscription preferences is via the command line. This option works well if you are building an unattended installation system and you want to dyanamically set this information. The settings provided at the command line will trump any conflicting settings from the installer config file. But if you are not running an unattended installation, you’ll still have the opportunity to override these values. Bottom line: don’t set subscription information on the command line unless you are using it in conjunction with an unattended installation (see the -w command line argument for more information).
Most commonly, you will just want to store subscription information in the installer config file. The main advantage to this is that you can reuse the subscription settings every time you configure a deployment. The main disadvantage to this is that you could potentially end up storing a piece of sensitive information (your RHSM or RHN password) to a cleartext file. In these situations, you will want to use a combination of this pathway and pathway #3; read on for more info.
Information that is stored in the
After the installer gives you the opportunity to work with subscription settings in your configuration file, you will have the opportunity to set one-time values that are not stored in the configuration file. These values will be used during the current deployment and then forgotten by
oo-install. This is suitable in particular for passwords that you do not want to capture in the non-encrypted installer config file.
The most common subscription method for Origin is
yum, and the current known good repos to use are these:
repos_base- The base URL for the OpenShift repositories: https://mirror.openshift.com/pub/origin-server/release/4/rhel-6/
jenkins_repo_base- The base URL for the Jenkins repository: http://pkg.jenkins-ci.org/redhat
os_optional_repo- The EPEL repo: http://download.fedoraproject.org/pub/epel/6/$basearch
puppet_repo_rpm- The Puppet Labs repo RPM: http://yum.puppetlabs.com/puppetlabs-release-el-6.noarch.rpm
These values are provided by default in the configuration file that ships with the installer.
Once you’ve configured DNS, Hosts and Roles, and Subscription information, the installer will do a sanity check of the entire deployment. Specifically, for each host that you’ve described, the installer checks the following:
The installer will offer to install missing packages that are required for deployment. Most notably for OpenShift Origin, the installer will offer to install Puppet if puppet is not found on the target system(s).
If your deployment fails pre-flight, don’t panic. Have a look at what the error messages are telling you about missing utilities and SSH connection issues (these are the largest causes of preflight failure).
|It is completely safe to rerun the installer if it fails preflight, and if you are totally stumped, get in touch with us so that we can help!|
Once the pre-flight inspection is complete, the installer hands control of the installation off to a 'workflow executable'. The workflow executable’s job is to transform the configuration that you’ve described into instructions for deploying your OpenShift. The entire installation process can take anywhere from 10 to 45 minutes. During the process, you will see a fairly constant stream of information scrolling by in your command terminal. Additionally, once the installation work begins on each host, you can watch the progress from their perspective by tailing the installer log file:
$ tail -f /tmp/openshift-deploy.log
After the OpenShift installation is complete, the installer will attempt to perform several necessary post-install tasks for you:
Restarting services in the necessary order for inter-host communication
If appropriate, preforming the MongoDB replica set configuration on your speficied master DBServer
Configuring the Node District(s) that you sepcified
Registering the supported cartridges with your Broker(s)
If the installer encounters any failures at this point, they are most likely due to race conditions between services on separate hosts. In these cases the installer will instruct you about what post-install steps remain.
Rebooting OpenShift hosts is no longer necessary as a post-install action.
Once your system is up and running, your work with
oo-install is complete. You cannot use
oo-install to reconfigure your deployment, though you can use it to add Node hosts to your deployment.
From here, you can learn more about the management and operation of OpenShift from the following guides:
And don’t be afraid to reach out to the community for more help!
These instructions will enable you to set up temporary DNS integration on a Linux system. You can use this information as a guideline for accomplishing similar results on client systems running other operating systems.
On a client-by-client basis, you can do the following to work against the OpenShift DNS server:
On the client system, make a backup copy of
$ cp /etc/resolv.conf /etc/resolv.conf.bak
Open the file with a text editor
$ vi /etc/resolv.conf
In the editor you will see something similar to this:
domain mybu.mycorp.com search mybu.mycorp.com mybu.mycorp.com. mycorp.com. nameserver 18.104.22.168 nameserver 22.214.171.124
searchvalues to match the app domain (and optionally also the OpenShift host domain) that you specified.
searchline, insert a new
nameserverentry to point to the Broker host’s IP address.
Leave the other
No restart necessary; you should be able to point a web browser on this client system at the URL off an application in the app domain. If you’ve also registered the OpenShift hosts with OpenShift DNS, they should be reachable by name as well.
For a more permanent solution, here’s how to delegate the OpenShift application domain (and if applicable, host domain) from your main DNS service to the OpenShift DNS server. The gist of the work is that you will be telling your main DNS service to delegate to the OpenShift DNS service based on the domain of the name to be looked up.
|Keep in mind that DNS could be set up in one of a dozen different ways in your organization, so the best we can do is offer guidelines for what you are going to need to do.|
DNS services can be thought of as domain containerships. The DNS service that provides lookup information for
example.com may also contain records for hosts in the subdomain
corp.example.com. Alternately it may delegate the job of subdomain lookups to another server. Delegation is how you will set the OpenShift DNS service to provide the lookup information for the OpenShift-hosted applications, and possibly also the information for the OpenShift hosts.
First, you will need to determine the right DNS server or service layer where the delegation should be done. In a simple lab environment this may be pretty obvious, but in a large company this will probably involve the assistance of different members of your IT organization. Unfortunately, this guide can’t offer a lot of guidance there. The point is that whatever nameserver is the authority for the nearest containing subdomain, that’s generally the one where you’ll want to define the NS records that refer to your OpenShift nameserver for its domain(s).
Once you’ve identified where delegation should occur, you will need to configure the delegation itself. For a typical example, let’s say you own
example.com, and you want to delegate
openshift.example.com to your OpenShift BIND server:
The root nameservers delegate "com" to the .com nameservers.
The .com nameservers delegate "example.com" to your example.com nameservers.
On your example.com nameserver, you would define a record for the
openshift.example.com NS ns1.openshift.example.com
And then you would define that name with an IP that points to your OpenShift DNS server:
ns1.openshift.example.com A 10.x.x.x
The exact method/syntax for defining will vary by nameserver type, but the outcome should look the same when verified with
|Between you and us, we don’t know why you couldn’t just put the IP in the NS record and have done, but no one seems to do it that way. Levels of indirection and caching, perhaps?|
The OpenShift nameserver can then go on to define subdomains, for instance
apps.openshift.example.com, as it is the master of this (sub)domain.