72ff0732 |
= Contributing to OpenShift |
8fc6ff7b |
OpenShift Developers <dev@lists.openshift.redhat.com> |
9de7320d |
:data-uri:
:icons:
:toc2:
:sectanchors:
|
3dbf26a7 |
The OpenShift architecture builds upon the flexibility and scalability of https://docker.com/[Docker] and https://github.com/kubernetes/kubernetes[Kubernetes] to deliver a powerful new https://www.youtube.com/watch?v=aZ40GobvA1c[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. |
9de7320d |
|
72ff0732 |
To get started you can either: |
7bda5af7 |
|
6634ae0c |
* <<download-from-github>> |
72ff0732 |
Or if you are interested in development, start with:
|
8b95deb5 |
* <<openshift-development>> and choose between: |
72ff0732 |
|
8b95deb5 |
** <<develop-locally-on-your-host>>
** <<develop-on-virtual-machine-using-vagrant>> |
7bda5af7 |
|
6634ae0c |
== Download from GitHub
|
f820135f |
The OpenShift team periodically publishes binaries to GitHub on https://github.com/openshift/origin/releases[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 https://docs.docker.com/installation/[the installation page] if you've never installed Docker before). |
6634ae0c |
|
b4b63285 |
The tar file for each platform contains a single binary `openshift` which is the all-in-one OpenShift installation. |
c36cc7db |
|
3dbf26a7 |
* Use `sudo openshift start` to launch the server. Root access is required to create services due to the need to modify IPTables. See issue: https://github.com/kubernetes/kubernetes/issues/1859. |
8b95deb5 |
* Use `oc login <server> ...` to connect to an OpenShift server |
c36cc7db |
* Use `openshift help` to see more about the commands in the binary |
6634ae0c |
|
72ff0732 |
== OpenShift Development
|
f820135f |
To get started, https://help.github.com/articles/fork-a-repo[fork] the https://github.com/openshift/origin[origin repo]. |
72ff0732 |
=== Develop locally on your host |
7bda5af7 |
|
e8a6c7a3 |
You can develop OpenShift 3 on Windows, Mac, or Linux, but you'll need Docker installed on Linux to actually launch containers. |
9de7320d |
|
e8a6c7a3 |
* For OpenShift 3 development, install the http://golang.org/[Go] programming language
* To launch containers, install the https://docker.com/[Docker] platform |
9de7320d |
Here's how to get set up:
|
f4d11ab5 |
1. For Go, Git and optionally also Docker, follow the links below to get to installation information for these tools: + |
c82e4940 |
** http://golang.org/doc/install[Installing Go]. Currently, OpenShift supports building using Go 1.6.x. Do NOT use $HOME/go for Go installation, save that for the Go workspace below. |
f4d11ab5 |
** http://git-scm.com/book/en/v2/Getting-Started-Installing-Git[Installing Git] |
c6bca295 |
** https://docs.docker.com/installation/[Installing Docker] |
9e11e3be |
+ |
c82e4940 |
NOTE: As of now, OpenShift requires Docker 1.9 or higher. |
986b5d28 |
The exact version requirement is documented https://docs.openshift.org/latest/install_config/install/prerequisites.html#installing-docker[here].
|
9de7320d |
2. Next, create a Go workspace directory: +
+
----
$ mkdir $HOME/go
----
3. In your `.bashrc` file or `.bash_profile` file, set a GOPATH and update your PATH: +
+
----
export GOPATH=$HOME/go
export PATH=$PATH:$GOPATH/bin |
68f7d9e6 |
export OS_OUTPUT_GOPATH=1 |
9de7320d |
---- |
72ff0732 |
4. 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 |
e5562ee2 |
$ git remote add upstream git://github.com/openshift/origin |
72ff0732 |
|
bf0a1675 |
5. From here, you can generate the OpenShift binaries by running:
|
f820135f |
$ make clean build |
bf0a1675 |
|
55906386 |
6. 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. For more details on controlling Docker options with systemd, please refer https://docs.docker.com/engine/admin/systemd/[here]. |
34b25864 |
Otherwise, add "--insecure-registry 172.30.0.0/16" to the Docker daemon invocation, for example: |
bf0a1675 |
|
a137ae28 |
$ docker daemon --insecure-registry 172.30.0.0/16 |
bf0a1675 |
7. Then, the OpenShift firewalld rules are also a work in progress. For now it is easiest to disable firewalld altogether:
$ sudo systemctl stop firewalld
8. 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
9. Now change into the directory with the OpenShift binaries, and start the OpenShift server:
|
97036f78 |
$ cd _output/local/bin/linux/amd64 |
bf0a1675 |
$ sudo ./openshift start
|
97036f78 |
+
NOTE: Replace "linux/amd64" with the appropriate value for your platform/architecture.
|
641067b0 |
10. Launch another terminal, change into the same directory you started OpenShift, and deploy the private docker registry within OpenShift with the following commands: |
bf0a1675 |
$ sudo chmod +r openshift.local.config/master/admin.kubeconfig |
641067b0 |
$ ./oadm registry -n default --config=openshift.local.config/master/admin.kubeconfig |
bf0a1675 |
11. If it is not there already, add the current directory to the $PATH, so you can leverage the OpenShift commands elsewhere.
|
f820135f |
12. You are now ready to edit the source, rebuild and restart OpenShift to test your changes. |
bf0a1675 |
|
f820135f |
13. NOTE: to properly stop OpenShift and clean up, so that you can start fresh instance of OpenShift, execute: |
bf0a1675 |
|
107155bc |
$ sudo pkill -x openshift |
bf0a1675 |
$ 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.*
|
9de7320d |
|
72ff0732 |
=== Develop on virtual machine using Vagrant |
7bda5af7 |
|
57c5a628 |
To facilitate rapid development we've put together a Vagrantfile you can use to stand up a development environment. |
7bda5af7 |
|
9e11e3be |
1. http://www.vagrantup.com/downloads.html[Install Vagrant] |
7bda5af7 |
|
8b95deb5 |
2. https://www.virtualbox.org/wiki/Downloads[Install VirtualBox] (Ex: `yum install VirtualBox` from the RPM Fusion repository) |
7bda5af7 |
|
9e11e3be |
3. In your `.bashrc` file or `.bash_profile` file, set a GOPATH: +
+
----
export GOPATH=$HOME/go
----
4. Clone the project and change into the directory: |
5b3e3f59 |
$ mkdir -p $GOPATH/src/github.com/openshift
$ cd $GOPATH/src/github.com/openshift |
72ff0732 |
$ git clone git://github.com/<forkid>/origin # Replace <forkid> with the your github id |
7bda5af7 |
$ cd origin |
8b95deb5 |
$ git remote add upstream git://github.com/openshift/origin
|
7bda5af7 |
|
3c166567 |
5. Bring up the VM (If you are new to Vagrant, consider http://docs.vagrantup.com[Vagrant Docs] for help on items like provider selection. Also consider the enablement of your hardware's virtualization extensions, such as https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/6/html/Virtualization_Administration_Guide/sect-Virtualization-Troubleshooting-Enabling_Intel_VT_and_AMD_V_virtualization_hardware_extensions_in_BIOS.html[RHEL] for example.). Also note, for the `make clean build` in step 7 to work, a sufficient amount of memory needs to be allocated for the VM, where that amount of memory is not necessarily needed if you are not doing a compile, but simply running openshift (and hence is not set as the default): |
7bda5af7 |
|
fbde2c99 |
$ export OPENSHIFT_MEMORY=4192 |
7bda5af7 |
$ vagrant up |
9e11e3be |
+ |
fbde2c99 |
TIP: To ensure you get the latest image first run `vagrant box remove fedora_inst`. And if later on you employ a dev cluster, additionally run `vagrant box remove fedora_deps`.
|
e866e790 |
6. You are now ready to edit the source, rebuild and restart OpenShift to test your changes. SSH in: |
7bda5af7 |
$ vagrant ssh
|
9e11e3be |
7. Run a build: |
7bda5af7 |
|
5b3e3f59 |
$ cd /data/src/github.com/openshift/origin |
f820135f |
$ make clean build |
7bda5af7 |
|
e866e790 |
8. Now start the OpenShift server: |
5b3e3f59 |
|
e866e790 |
$ sudo systemctl start openshift |
fbde2c99 |
|
e866e790 |
Or: |
fbde2c99 |
|
e866e790 |
# must cd / to use prepopulated $KUBECONFIG
$ cd /
# redirect the logs to /home/vagrant/openshift.log for easier debugging
$ sudo `which openshift` start --public-master=localhost &> $HOME/openshift.log & |
fbde2c99 |
+ |
e866e790 |
NOTE: This will generate three directories in / (openshift.local.config, openshift.local.etcd, openshift.local.volumes) as well as create the /home/vagrant/openshift.log file. |
f820135f |
+ |
fbde2c99 |
NOTE: By default your origin directory (on your host machine) will be mounted as a vagrant synced folder into `/data/src/github.com/openshift/origin`. |
5b3e3f59 |
|
7bda5af7 |
|
e866e790 |
9. Deploy the private docker registry within OpenShift with the following command: |
f820135f |
|
e866e790 |
$ oadm registry |
f820135f |
|
e866e790 |
10. At this point it may be helpful to load some image streams and templates. These commands will make use of fixtures from the `openshift/origin/examples` dir: |
f820135f |
|
e866e790 |
# load image streams
$ oc create -f /data/src/github.com/openshift/origin/examples/image-streams/image-streams-centos7.json -n openshift |
fbde2c99 |
# load templates |
e866e790 |
$ oc create -f /data/src/github.com/openshift/origin/examples/sample-app/application-template-stibuild.json -n openshift
$ oc create -f /data/src/github.com/openshift/origin/examples/db-templates -n openshift |
fbde2c99 |
|
e866e790 |
11. At this point you can open a browser on your host system and navigate to https://localhost:8443/console to view the web console. You can log in with any username and password combination. |
fbde2c99 |
|
e866e790 |
12. NOTE: to properly stop OpenShift and clean up, so that you can start fresh instance of OpenShift, execute: |
72ff0732 |
|
aef84eb3 |
# shut down openshift
$ sudo pkill openshift
# stop the docker containers
$ docker ps | awk 'index($NF,"k8s_")==1 { print $1 }' | xargs -l -r docker stop
# deleting all the internal config files, etcd, etc and starting openshift fresh
$ sudo rm -rf openshift.local.*
# if you used the --volume-dir=/home/vagrant/volumes flag, then run these |
7bda5af7 |
|
72ff0732 |
TIP: See https://github.com/openshift/vagrant-openshift for more advanced options |
a18b01c3 |
|
72ff0732 |
==== Ensure virtual box interfaces are not managed by Network Manager |
d2e59476 |
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:
1. Check the status of Network Manager devices:
|
72ff0732 |
$ nmcli d |
d2e59476 |
2. If any devices whose name start with vboxnet* are not unmanaged, then they need to be added to
NetworkManager configuration to be ignored.
|
72ff0732 |
$ cat /etc/NetworkManager/NetworkManager.conf |
d2e59476 |
[keyfile]
unmanaged-devices=mac:0a:00:27:00:00:00;mac:0a:00:27:00:00:01;mac:0a:00:27:00:00:02
3. One can use the following command to help generate the configuration:
|
72ff0732 |
$ ip link list | grep vboxnet -A 1 | grep link/ether | awk '{print "mac:" $2}' | paste -sd ";" - |
d2e59476 |
|
01b52e45 |
4. Reload the Network Manager configuration:
$ sudo nmcli con reload
|
c16939e0 |
=== Develop and test using a docker-in-docker cluster
It's possible to run an OpenShift multinode cluster on a single host |
9897da95 |
thanks to docker-in-docker (dind). Cluster creation is cheaper since
each node is a container instead of a VM. This was initially
implemented to support multinode network testing, but has proven
useful for development as well. |
c16939e0 |
|
9897da95 |
Prerequisites: |
c16939e0 |
|
e4f4629d |
1. A host running docker and with SELinux disabled.
|
450224c7 |
2. It is acceptable to load some kernel modules (overlay and
openvswitch) on the docker host. |
e4f4629d |
|
450224c7 |
3. An environment with the tools necessary to build origin. |
e4f4629d |
|
450224c7 |
4. A clone of the origin repo. |
c16939e0 |
|
9897da95 |
From the root of the origin repo, run the following command to launch
a new cluster: |
c16939e0 |
|
9897da95 |
# -b to build origin, -i to build images
$ hack/dind-cluster.sh start -b -i
Once the cluster is up, source the cluster's rc file to configure the
environment to use it: |
c16939e0 |
|
9897da95 |
$ . dind-openshift.rc
Now the 'oc' command can be used to interact with the cluster: |
c16939e0 |
$ oc get nodes
It's also possible to login to the participating containers
(openshift-master, openshift-node-1, openshift-node-2, etc) via docker
exec:
$ docker exec -ti openshift-master bash
|
e4ee75cd |
While it is possible to manage the OpenShift daemon in the containers,
dind cluster management is fast enough that the suggested approach is
to manage at the cluster level instead. |
c16939e0 |
Invoking the dind-cluster.sh script without arguments will provide a
usage message:
Usage: hack/dind-cluster.sh {start|stop|restart|...}
Additional documentation of how a dind cluster is managed can be found
at the top of the dind-cluster.sh script.
Attempting to start a cluster when one is already running will result
in an error message from docker indicating that the named containers |
9897da95 |
already exist. To redeploy a cluster use the 'start' command with the
'-r' flag to remove an existing cluster.
|
c16939e0 |
==== Testing networking with docker-in-docker
|
630e7d0c |
It is possible to run networking tests against a running
docker-in-docker cluster (i.e. after 'hack/dind-cluster.sh start' has
been invoked): |
c16939e0 |
|
67b70c91 |
$ OPENSHIFT_CONFIG_ROOT=dind test/extended/networking.sh |
c16939e0 |
Since a cluster can only be configured with a single network plugin at
a time, this method of invoking the networking tests will only |
630e7d0c |
validate the active plugin. It is possible to target all plugins by |
67b70c91 |
invoking the same script in 'ci mode' by not setting a config root: |
c16939e0 |
$ test/extended/networking.sh
|
630e7d0c |
In ci mode, for each networking plugin, networking.sh will create a
new dind cluster, run the tests against that cluster, and tear down
the cluster. The test dind clusters are isolated from any
user-created clusters, and test output and artifacts of the most
recent test run are retained in
/tmp/openshift-extended-tests/networking. |
c16939e0 |
|
630e7d0c |
It's possible to override the default test regexes via the |
c16939e0 |
NETWORKING_E2E_FOCUS and NETWORKING_E2E_SKIP environment variables.
These variables set the '-focus' and '-skip' arguments supplied to the
https://github.com/onsi/ginkgo[ginkgo] test runner.
|
ce13b884 |
To debug a test run with https://github.com/derekparker/delve[delve],
make sure the dlv executable is installed in your path and run the |
993fb17a |
tests with DLV_DEBUG set: |
ce13b884 |
|
993fb17a |
$ DLV_DEBUG=1 test/extended/networking.sh |
ce13b884 |
|
630e7d0c |
==== Running networking tests against any cluster
It's possible to run networking tests against any cluster. To target
the default vm dev cluster:
|
67b70c91 |
$ OPENSHIFT_CONFIG_ROOT=dev test/extended/networking.sh |
630e7d0c |
To target an arbitrary cluster, the config root (parent of
openshift.local.config) can be supplied instead:
|
67b70c91 |
$ OPENSHIFT_CONFIG_ROOT=[cluster config root] test/extended/networking.sh |
630e7d0c |
|
1a6afc3d |
It's also possible to supply the path to a kubeconfig file:
$ OPENSHIFT_TEST_KUBECONFIG=./admin.kubeconfig test/extended/networking.sh
|
630e7d0c |
See the script's inline documentation for further details.
|
c16939e0 |
==== Running Kubernetes e2e tests
It's possible to target the Kubernetes e2e tests against a running
OpenShift cluster. From the root of an origin repo:
$ pushd ..
$ git clone http://github.com/kubernetes/kubernetes/
$ pushd kubernetes/build
$ ./run hack/build-go.sh
$ popd && popd
$ export KUBE_ROOT=../kubernetes
$ hack/test-kube-e2e.sh --ginkgo.focus="[regex]"
The previous sequence of commands will target a vagrant-based
OpenShift cluster whose configuration is stored in the default
location in the origin repo. To target a dind cluster, an additional
environment variable needs to be set before invoking test-kube-e2e.sh:
$ export OS_CONF_ROOT=/tmp/openshift-dind-cluster/openshift |
72ff0732 |
|
9de7320d |
== Development: What's on the Menu? |
a0d864e5 |
Right now you can see what's happening with OpenShift development at: |
9de7320d |
|
a0d864e5 |
https://github.com/openshift/origin[github.com/openshift/origin] |
9de7320d |
|
70cf5544 |
Ready to play with some code? Hop down and read up on our link:#the-roadmap[roadmap] for ideas on where you can contribute.
You can also try to take a stab at any issue tagged with the https://github.com/openshift/origin/issues?q=is%3Aissue+is%3Aopen+label%3Ahelp-wanted[help-wanted] label. |
9de7320d |
*If you are interested in contributing to Kubernetes directly:* + |
3dbf26a7 |
https://github.com/kubernetes/kubernetes#community-discussion-and-support[Join the Kubernetes community] and check out the https://github.com/kubernetes/kubernetes/blob/master/CONTRIBUTING.md[contributing guide]. |
9de7320d |
|
72ff0732 |
== Troubleshooting |
da3b06d1 |
If you run into difficulties running OpenShift, start by reading through the https://github.com/openshift/origin/blob/master/docs/debugging-openshift.md[troubleshooting guide].
|
72ff0732 |
== The Roadmap |
0b8e6dad |
The OpenShift project roadmap lives https://trello.com/b/nlLwlKoz/atomicopenshift-roadmap[on Trello]. A summary of the roadmap, releases, and other info can be found https://ci.openshift.redhat.com/roadmap_overview.html[here]. |
9de7320d |
== Stay in Touch
Reach out to the OpenShift team and other community contributors through IRC and our mailing list:
* IRC: Hop onto the http://webchat.freenode.net/?randomnick=1&channels=openshift-dev&uio=d4[#openshift-dev] channel on http://www.freenode.net/[FreeNode].
* E-mail: Join the OpenShift developers' http://lists.openshift.redhat.com/openshiftmm/listinfo/dev[mailing list]. |