There are two common approaches to running OpenShift with Docker:
Native Docker Install - If you are using a Linux Operating System that natively suppors Docker such as Fedora, Centos or RHEL, then you can install and run OpenShift using a local Docker install.
Non-Native Docker Install - If you are using an Operating System such as OSX or Windows that doesn't support Docker natively, you'll need to create a Virtual Machine to host Docker and subsequently OpenShift.
Even if your OS supports Docker natively it can be useful to use a Non-Native Install as you can then snapshot your Vm hosting OpenShift install in various states and restore.
Regardless of the approach taken you will need to:
You will need:
Update your Docker config - this differs slightly on different Linux distros:
On RHEL/Centos/Fedora:
Copy the following line into /etc/sysconfig/docker
OPTIONS="--selinux-enabled -H unix://var/run/docker.sock -H tcp://0.0.0.0:2375 --insecure-registry 172.0.0.0/8"
If you are on Ubuntu/Debian:
Copy the following line into /etc/default/docker
DOCKER_OPTS="--selinux-enabled -H unix://var/run/docker.sock -H tcp://0.0.0.0:2375 --insecure-registry 172.0.0.0/8"
Restart the docker service
service docker restart
If you are running on Fedora or other distro using firewalld, you will need to add docker0 interface to the trusted zone like this:
firewall-cmd --zone=trusted --add-interface=docker0
firewall-cmd --zone=trusted --add-interface=docker0 --permanent
Traditionally Mac and Windows users would use boot2docker, a lightweight VM designed to make it feel like users can run docker natively. This has been good in the past when working with a few containers however we have seen connectivity issues and problems related to low resources when working with more demanding technologies such as OpenShift & Kubernetes. Therefore, We do not recommend you use boot2docker to run OpenShift.
Alternatively, you could create a VM manually using VMWare or Virtual Box and install docker manually (using the Native Install Pre Requisites)
Instead, we recommend that the simplest way to get going is to use the Fabric8 VagrantFile, as detailed below:
Check out the Fabric8 Git Repo or download a repository snapshot zip:
git clone [email protected]:fabric8io/fabric8.git
Create a VM using the Fabric8 VagrantFile at the root of the repository:
cd fabric8
vagrant up
vagrant ssh
Note: There are alternative Vagrant images available in the Fabric8 Repo
We recommend priming the docker registry with the images used by Fabric8, and then using Vagrant to take a snapshot so we can revert back to a clean start without re-downloading gigabites of docker images.
First install the snapshot plugin from you host system (i.e. outside the VM):
vagrant plugin install vagrant-vbox-snapshot
After you have run the start script inside the VM in order to populate the Docker registry (see below), you can take a snapshot of the vagrant image (again, outside of the VM):
vagrant snapshot take default cleanstart
Now at any point you can reset to the cleanstart snapshot via:
vagrant snapshot go default cleanstart
We use a script downloaded via curl to configure and start OpenShift in a Docker container. This script will then schedule a number of further containers such as the Fabric8 console and optionally logging and metric dashboards in the form of Kibana and Grafana. If you are using the non-native approach, this script must be run as root from within the Vagrant VM.
Once you've run the script you'll need to complete some post-install steps before you can access Fabric8.
The first time you run fabric8 v2 it may take some time as there are a number of docker images to download, this may require some patience
If you are running fabric8 v2 for the first time we recommend you start with the basic script. This should be run from the machine hosting Docker.
If you fancy starting OpenShift V3 the super-easy way which includes the Fabric8 console and a Private Docker registry, run this one-liner.
bash <(curl -sSL https://bit.ly/get-fabric8)
If using a native install a Browser will automatically open on completion showing the Fabric8 console
If you would like to try out a fully-featured installation, including aggregated logs & metrics, you can pass in the -k ("kitchen sink") flag
warning: more images to download so longer to wait
bash <(curl -sSL https://bit.ly/get-fabric8) -k
If you want to start from scratch, deleting all previously created Kubernetes containers, you can pass in the -f flag:
bash <(curl -sSL https://bit.ly/get-fabric8) -f
To update all the relevant images (corresponds to docker pull latest docker images), you can pass the -u flag:
bash <(curl -sSL https://bit.ly/get-fabric8) -u
By default, OpenShift will create certificates for your master which will be valid for all local addresses of the
server you have deployed on. If you would like to add a public address that the master will be accessed on, you
can pass the -m flag & specify the public address:
bash <(curl -sSL https://bit.ly/get-fabric8) -m fabric8.local
To be save you can use the IP address of the VM here which is 172.28.128.4
By default, OpenShift uses an anypassword policy which means that you can use...any password. This is great for quick
setups, but not great for security obviously. If you want to set up a password for the default admin user, use the
-P flag:
bash <(curl -sSL https://bit.ly/get-fabric8) -P password123
And of course flags can be combined, to start from scratch & update all images at once:
bash <(curl -sSL https://bit.ly/get-fabric8) -kuf -m fabric8.local -P password123
You'll need to set the following environment variables on your host to be able use the Tools such as the Console, Maven Plugin, the Forge Addons and the java libraries:
FABRIC8_CONSOLE : used to interact with the faberic8 console to deploy and run appsDOCKER_REGISTRY : used to push images to the private docker registryKUBERNETES_TRUST_CERT : whether to trust the certs provided by Kubernetes service regardless of signing CADOCKER_IP : used by the docker client to connect to dockerDOCKER_HOST : standard specification how to reach the Docker host
(e.g. tcp://172.28.128.4:2375)KUBERNETES_MASTER : used to interact with the Kubernetes Rest APIThese environment variables are presented to you on successful completion of the start script, so the easiest thing to do is copy them from the output into your ~/.bashrc (linux) or ~/.profile (mac). Windows users will need to set them individually via the Environment Variables dialog.
Here's a sample output when the insallation script finishes:
Waiting for Docker registry
You're all up & running! Here are the available services:
Service | URL
------- | ---
Kubernetes master | https://127.0.0.1:8443
Fabric8 console | http://172.28.128.4
Docker Registry | 172.30.17.90:5000/TCP
Set these environment variables on your development machine:
export FABRIC8_CONSOLE=http://172.28.128.4
export DOCKER_REGISTRY=172.30.17.90:5000/TCP
export KUBERNETES_TRUST_CERT=true
export DOCKER_IP=172.28.128.4
export DOCKER_HOST=tcp://172.28.128.4:2375
export KUBERNETES_MASTER=https://172.28.128.4:8443
To make sure you can access the IP addresses of services and pods hosted in your Virtual Machine (e.g. the Fabric8 Console), you'll need to add a network route for the 172.X.X.X IP range:
sudo route -n delete 172.0.0.0/8
sudo route -n add 172.0.0.0/8 $DOCKER_IP
Or on Windows run the following from a DOS prompt as an Administrator:
route add 172.0.0.0 MASK 255.0.0.0 $DOCKER_IP
You should now be able to access the Fabric8 console using the address defined in the previously set $FABRIC8_CONSOLE environment variable.
The OpenShift container includes the OpenShift Command Line (osc). Therefore, you can use the osc via a docker 'run' command.
The easiest way to do this is to create an alias in your ~/.bashrc.
Note: In the aliases below you'll need to update the openshift/origin container tag to be whatever version Fabric8 is currently using. Run docker ps | grep openshift/origin: to find this out
Native Install
alias osc="docker run --rm -i --entrypoint=osc --net=host openshift/origin:v0.3.4 --insecure-skip-tls-verify"
Non-Native Install
alias osc="docker run --rm -i -e KUBERNETES_MASTER=https://$DOCKER_IP:8443 --entrypoint=osc --net=host openshift/origin:v0.3.4 --insecure-skip-tls-verify"
You can now use the osc command line to list pods, replication controllers and services; delete or create resources etc:
osc get pods
osc get replicationControllers
osc get services
To see all the available commands:
osc --help
Note that since we are using docker and you are typically running the docker commands from the host machine (your laptop), the osc command which itself runs in a linux container won't be able to access local files when supplying -c to create.
However you can pipe them into the command line via
cat mything.json | osc create -f -
If docker is restarted, you can restart openshift by starting the openshift container
docker start openshift
To remove untagged images
sudo docker rmi $(sudo docker images -qaf 'dangling=true')
Sometimes Docker containers are not removed completely. The lines below will stop and remove OpenShift and all containers created by Kubernetes.
docker kill openshift
docker rm -v openshift
docker kill $(docker ps -a | grep k8s | cut -c 1-12)
docker rm -v $(docker ps -a -q)
If you are developing and working with hawtio you might want to run a locally built hawtio docker image against OpenShift..
docker run -p 8484:8080 -it -e KUBERNETES_MASTER=https://$DOCKER_IP:8443 fabric8/hawtio
You can now access the web console at http://$DOCKER_IP:8484/hawtio/kubernetes/pods.