Soon, all Red Hat OpenShift documentation will only be available on docs.redhat.com, the official location of all Red Hat product documentation. Get familiar with the updated experience today!
  1. Documentation
×

Administrators: Setting Up a Cluster

Overview

OKD has multiple installation methods available, each of which allow you to quickly get your own OKD instance up and running. Depending on your environment, you can choose the installation method that works best for you.

For deploying a full OKD cluster, see the advanced installation guide.

Prerequisites

Before choosing an installation method, you must first satisfy the prerequisites on your hosts, which includes verifying system and environment requirements and installing and configuring Docker. After ensuring your hosts are properly set up, you can continue by choosing one of the following installation methods.

Docker and OKD must run on the Linux operating system. If you wish to run the server from a Windows or Mac OS X host, you should start a Linux VM first.

OKD and Docker use iptables to manage networking. Ensure that local firewall rules and other software making iptable changes do not alter the OKD and Docker service setup.

Installation Methods

Choose one of the following installation methods that works best for you.

Method 1: Running in a Container

You can quickly get OKD running in a container using images from Docker Hub on a Linux system. This method is supported on Fedora, CentOS, and Red Hat Enterprise Linux (RHEL) hosts only.

OKD listens on ports 53, 7001, and 8443. If another service is already listening on those ports you must stop that service before launching the OKD container.

Installing and Starting an All-in-One Server

  1. Launch the server in a container:

    $ sudo docker run -d --name "origin" \
        --privileged --pid=host --net=host \
        -v /:/rootfs:ro -v /var/run:/var/run:rw -v /sys:/sys -v /sys/fs/cgroup:/sys/fs/cgroup:rw \
        -v /var/lib/docker:/var/lib/docker:rw \
        -v /var/lib/origin/openshift.local.volumes:/var/lib/origin/openshift.local.volumes:rslave \ (1)
        openshift/origin start
    1 rslave only works if the Docker version is 1.10 or later and a Red Hat distribution.

    If you want to use OKD’s aggregated logging, you must add -v /var/log:/var/log to the docker command line. The origin container must have access to the host’s var/log/containers/ and /var/log/messages.

    This command:

    • starts OKD listening on all interfaces on your host (0.0.0.0:8443),

    • starts the web console listening on all interfaces at /console (0.0.0.0:8443),

    • launches an etcd server to store persistent data, and

    • launches the Kubernetes system components.

  2. After the container is started, you can open a console inside the container:

    $ sudo docker exec -it origin bash

If you delete the container, any configuration or stored application definitions will also be removed.

What’s Next?

Now that you have OKD successfully running in your environment, try it out by walking through a sample application lifecycle.

Method 2: Downloading the Binary

Red Hat periodically publishes binaries to GitHub, which you can download on the OKD repository’s Releases page. These are Linux, Windows, or Mac OS X 64-bit binaries; note that the Mac and Windows versions are for the CLI only.

The release archives for Linux and Mac OS X contain the server binary openshift which is an all-in-one {prodcut-title} installation. The archives for all platforms include the CLI (the oc command) and the Kubernetes client (the kubectl command).

Installing and Running an All-in-One Server

  1. Download the binary from the Releases page and untar it on your local system.

  2. Add the directory you untarred the release into to your path:

    $ export PATH=$(pwd):$PATH

  3. Launch the server:

    $ sudo ./openshift start

    This command:

    • starts OKD listening on all interfaces (0.0.0.0:8443),

    • starts the web console listening on all interfaces at /console (0.0.0.0:8443),

    • launches an etcd server to store persistent data, and

    • launches the Kubernetes system components.

    The server runs in the foreground until you terminate the process.

    This command requires root access to create services due to the need to modify iptables and mount volumes.

  4. OKD services are secured by TLS. In this path we generate a self-signed certificate on startup which must be accepted by your web browser or client. You must point oc and curl at the appropriate CA bundle and client key and certificate to connect to OKD. Set the following environment variables:

    $ export KUBECONFIG=`pwd`/openshift.local.config/master/admin.kubeconfig
$ export CURL_CA_BUNDLE=`pwd`/openshift.local.config/master/ca.crt
$ sudo chmod +r `pwd`/openshift.local.config/master/admin.kubeconfig
    This is just for example purposes; in a production environment, developers would generate their own keys and not have access to the system keys.

What’s Next?

Now that you have OKD successfully running in your environment, try it out by walking through a sample application lifecycle.

Try It Out

After starting an OKD instance, you can try it out by creating an end-to-end application demonstrating the full OKD concept chain.

When running OKD in a VM, you will want to ensure your host system can access ports 8080 and 8443 inside the container for the examples below.

  1. Log in to the server as a regular user:

    $ oc login
Username: test
Password: test

  2. Create a new project to hold your application:

    $ oc new-project test

  3. Create a new application based on a Node.js image on the Docker Hub:

    $ oc new-app openshift/deployment-example

    Note that a service was created and given an IP - this is an address that can be used within the cluster to access the application.

  4. Display a summary of the resources you created:

    $ oc status

  5. The container image for your application will be pulled to the local system and started. Once it has started it can be accessed on the host. If this is your laptop or desktop, open a web browser to the service IP and port that was displayed for the application:

    http://172.30.192.169:8080 (example)

    If you are on a separate system and do not have direct network access to the host, SSH to the system and perform a curl command:

    $ curl http://172.30.192.169:8080 # (example)

    You should see the v1 text displayed on the page.

Now that your application is deployed, you can trigger a new version of that image to be rolled out to your host by tagging the v2 image. The new-app command created an image stream which tracks which images you wish to use. Use the tag command to mark a new image as being desired for deployment:

$ oc tag --source=docker openshift/deployment-example:v2 deployment-example:latest

Your application’s deployment config is watching deployment-example:latest and will trigger a new rolling deployment when the latest tag is updated to the value from v2.

You can also use an alternate version of the command:

$ oc tag docker.io/openshift/deployment-example:v2 deployment-example:latest

Return to the browser or use curl again and you should see the v2 text displayed on the page.

For this next step we’ll need to ensure that Docker is able to pull images from the host system. Ensure you have completed the instructions about setting the --insecure-registry flag from Host Preparation.

As a developer, building new container images is as important as deploying them. OKD provides tools for running builds as well as building source code from within predefined builder images via the Source-to-Image toolchain.

For this procedure, ensure that Docker is able to pull images from the host system. Also, make sure you have completed the instructions about setting the --insecure-registry flag from Host Preparation.

  1. Switch to the administrative user and change to the default project:

    $ oc login -u system:admin
$ oc project default

  2. Set up an integrated Docker registry for the OKD cluster:

    $ oc adm registry

    It will take a few minutes for the registry image to download and start - use oc status to know when the registry is started.

  3. Change back to the test user and test project:

    $ oc login -u test
$ oc project test

  4. Create a new application that combines a builder image for Node.js with example source code to create a new deployable Node.js image:

    $ oc new-app openshift/nodejs-010-centos7~https://github.com/sclorg/nodejs-ex.git

    A build will be triggered automatically using the provided image and the latest commit to the master branch of the provided Git repository. To get the status of a build, run:

    $ oc status

    which will summarize the build. When the build completes, the resulting container image will be pushed to the Docker registry.

  5. Wait for the deployed image to start, then view the service IP using your browser or curl.

You can see more about the commands available in the CLI (the oc command) with:

$ oc help

Or connect to another system with:

$ oc -h <server_hostname_or_IP> [...]

OKD includes a web console which helps you visualize your applications and perform common creation and management actions. You can use the test user we created above to log in to the console via https://<server>:8443/console. For more information, see Getting Started for Developers: Web Console.

You can also see the OKD 3 Application Lifecycle Sample for a more in-depth walkthrough.