The OpenShift architecture builds upon the flexibility and scalability of Docker and Kubernetes to deliver a powerful new Platform-as-a-Service system. This article explains how to set up a development environment and get involved with this latest version of OpenShift. Kubernetes is included in this repo for ease of development, and the version we include is periodically updated.
To get started you can either:
Or if you are interested in development, start with:
The OpenShift team periodically publishes binaries to GitHub on the Releases page. These are Linux, Windows, or Mac OS X 64bit binaries (note that Mac and Windows are client only). You’ll need Docker installed on your local system (see the installation page if you’ve never installed Docker before).
The tar file for each platform contains a single binary openshift
which is the all-in-one OpenShift installation.
-
Use
sudo openshift start
to launch the server. Root access is required to create services due to the need to modify IPTables. See issue: kubernetes/kubernetes#1859. -
Use
oc login <server> …
to connect to an OpenShift server -
Use
openshift help
to see more about the commands in the binary
To get started, fork the origin repo.
You can develop OpenShift 3 on Windows, Mac, or Linux, but you’ll need Docker installed on Linux to actually launch containers.
Here’s how to get set up:
-
For Go, Git and optionally also Docker, follow the links below to get to installation information for these tools:
-
Installing Go. You must install Go 1.4 and NOT use $HOME/go directory for Go installation.
-
Installing Docker. NOTE: OpenShift requires Docker 1.6 or higher or 1.6.2 on CentOS/RHEL.
-
-
Next, create a Go workspace directory:
$ mkdir $HOME/go
-
In your
.bashrc
file or.bash_profile
file, set a GOPATH and update your PATH:export GOPATH=$HOME/go export PATH=$PATH:$GOPATH/bin
-
Open up a new terminal or source the changes in your current terminal. Then clone this repo:
$ mkdir -p $GOPATH/src/github.com/openshift $ cd $GOPATH/src/github.com/openshift $ git clone git://github.com/<forkid>/origin # Replace <forkid> with the your github id $ cd origin $ git remote add upstream git://github.com/openshift/origin
-
From here, you can generate the OpenShift binaries by running:
$ make clean build
-
Next, assuming you have not changed the kubernetes/openshift service subnet configuration from the default value of 172.30.0.0/16, you need to instruct the Docker daemon to trust any Docker registry on the 172.30.0.0/16 subnet. If you are running Docker as a service via
systemd
, add the--insecure-registry 172.30.0.0/16
argument to the options value in/etc/sysconfig/docker
and restart the Docker daemon. Otherwise, add "--insecure-registry 172.30.0.0/16" to the Docker daemon invocation, eg:$ docker -d --insecure-registry 172.30.0.0/16
-
Then, the OpenShift firewalld rules are also a work in progress. For now it is easiest to disable firewalld altogether:
$ sudo systemctl stop firewalld
-
Firewalld will start again on your next reboot, but you can manually restart it with this command when you are done running OpenShift:
$ sudo systemctl start firewalld
-
Now change into the directory with the OpenShift binaries, and start the OpenShift server:
$ cd _output/local/go/bin $ sudo ./openshift start
-
Launch another terminal, change into the same directory you started OpenShift, and deploy the private docker registry within OpenShift with the following commands (note, the --credentials option allows secure communication between the internal OpenShift Docker registry and the OpenShift server, and the --config option provides your identity (in this case, cluster-admin) to the OpenShift server):
$ sudo chmod +r openshift.local.config/master/openshift-registry.kubeconfig $ sudo chmod +r openshift.local.config/master/admin.kubeconfig $ oadm registry --create --credentials=openshift.local.config/master/openshift-registry.kubeconfig --config=openshift.local.config/master/admin.kubeconfig
-
If it is not there already, add the current directory to the $PATH, so you can leverage the OpenShift commands elsewhere.
-
You are now ready to edit the source, rebuild and restart OpenShift to test your changes.
-
NOTE: to properly stop OpenShift and clean up, so that you can start fresh instance of OpenShift, execute:
$ sudo killall openshift $ docker ps | awk 'index($NF,"k8s_")==1 { print $1 }' | xargs -l -r docker stop $ mount | grep "openshift.local.volumes" | awk '{ print $3}' | xargs -l -r sudo umount $ cd <to the dir you ran openshift start> ; sudo rm -rf openshift.local.*
To facilitate rapid development we’ve put together a Vagrantfile you can use to stand up a development environment.
-
Install VirtualBox (Ex:
yum install VirtualBox
from the RPM Fusion repository) -
Clone the project and change into the directory:
$ mkdir -p $GOPATH/src/github.com/openshift $ cd $GOPATH/src/github.com/openshift $ git clone git://github.com/<forkid>/origin # Replace <forkid> with the your github id $ cd origin $ git remote add upstream git://github.com/openshift/origin
-
Bring up the VM (If you are new to Vagrant, consider Vagrant Docs for help on items like provider selection. Also consider the enablement of your hardware’s virtualization extensions, such as RHEL for example.):
$ vagrant up
-
SSH in:
$ vagrant ssh
-
Run a build in SSH:
$ cd /data/src/github.com/openshift/origin $ make clean build
-
Now change into the directory with the OpenShift binaries, and start the OpenShift server:
$ cd _output/local/go/bin $ sudo ./openshift start --public-master=localhost &> logs/openshift.log &
Notewhen using vagrant synced folder (by default your origin directory is mounted using synced folder into /data/src/github.com/openshift/origin
) it is advised to use a different directory for volume storage than the one in the synced folder. This can be achieved by passing--volume-dir=/absolute/path
toopenshift start
command. -
On your host system, try browsing to: https://localhost:8443/console
-
Deploy the private docker registry within OpenShift with the following commands (note, the --credentials option allows secure communication between the internal OpenShift Docker registry and the OpenShift server, and the --config option provides your identity (in this case, cluster-admin) to the OpenShift server):
$ sudo chmod +r openshift.local.config/master/openshift-registry.kubeconfig $ sudo chmod +r openshift.local.config/master/admin.kubeconfig $ oadm registry --create --credentials=openshift.local.config/master/openshift-registry.kubeconfig --config=openshift.local.config/master/admin.kubeconfig
-
You are now ready to edit the source, rebuild and restart OpenShift to test your changes.
-
NOTE: to properly stop OpenShift and clean up, so that you can start fresh instance of OpenShift, execute:
$ sudo killall openshift $ docker ps | awk 'index($NF,"k8s_")==1 { print $1 }' | xargs -l -r docker stop $ mount | grep "openshift.local.volumes" | awk '{ print $3}' | xargs -l -r sudo umount $ cd <to the dir you ran openshift start> ; sudo rm -rf openshift.local.*
Tip
|
To ensure you get the latest image. First run vagrant box remove fedora_inst and vagrant box remove fedora_deps .
|
Tip
|
See https://github.com/openshift/vagrant-openshift for more advanced options |
If you are developing on a Linux host, then you need to ensure that Network Manager is ignoring the virtual box interfaces, otherwise they cause issues with multi-vm networking.
Follow these steps to ensure that virtual box interfaces are unmanaged:
-
Check the status of Network Manager devices:
$ nmcli d
-
If any devices whose name start with vboxnet* are not unmanaged, then they need to be added to NetworkManager configuration to be ignored.
$ cat /etc/NetworkManager/NetworkManager.conf
[keyfile] unmanaged-devices=mac:0a:00:27:00:00:00;mac:0a:00:27:00:00:01;mac:0a:00:27:00:00:02
-
One can use the following command to help generate the configuration:
$ ip link list | grep vboxnet -A 1 | grep link/ether | awk '{print "mac:" $2}' | paste -sd ";" -
-
Reload the Network Manager configuration:
$ sudo nmcli con reload
Right now you can see what’s happening with OpenShift development at:
Ready to play with some code? Hop down and read up on our roadmap for ideas on where you can contribute.
If you are interested in contributing to Kubernetes directly:
Join the Kubernetes community and check out the contributing guide.
If you run into difficulties running OpenShift, start by reading through the troubleshooting guide.
The OpenShift project roadmap lives on Trello. Of particular interest to those who want to get involved with the OpenShift 3 architecture are the following topics:
These link to active and backlog tasks that the OpenShift team is planning or working on for Kubernetes development.
Reach out to the OpenShift team and other community contributors through IRC and our mailing list:
-
IRC: Hop onto the #openshift-dev channel on FreeNode.
-
E-mail: Join the OpenShift developers' mailing list.