Skip to content

Commit

Permalink
Updates to CONTRIBUTING Documentation
Browse files Browse the repository at this point in the history 
* Specify supported versions of golang and Docker for macOS and Windows.
* Updates to `cluster_up_down.md`:
** List supported versions of Docker for each oc client release.
** Remove references to `--create-machine`.
* Identify issue with plain Docker for Mac and oc client v3.7
  • Loading branch information
@adambkaplan
adambkaplan committed Apr 3, 2018
1 parent 8a2f52d commit a297c4d
Show file tree
Hide file tree
Showing 2 changed files with 52 additions and 63 deletions.
11 changes: 9 additions & 2 deletions CONTRIBUTING.adoc
View file
Expand Up @@ -50,8 +50,9 @@ can be built locally or in the `openshift/origin-release` container environment.
http://golang.org/[Go] programming language is only necessary for building on
the local host.

Currently, OpenShift is built with `go` 1.8 and uses Docker 1.12. The exact
requirement for Docker is documented
Currently, OpenShift is built with `go` 1.9 and uses Docker 1.13 on Fedora/CentOS/RHEL.
MacOS supports builds with `go` 1.9 and Docker CE 17.09.1 - newer versions of go and Docker are not supported.
The exact requirement for Docker is documented
https://docs.openshift.org/latest/install_config/install/prerequisites.html#installing-docker[here].

==== Installing Prerequisites
Expand All @@ -65,17 +66,23 @@ $ brew install git
----

Then, follow the instructions to install https://docs.docker.com/docker-for-mac/install/[`docker`].
Search the https://docs.docker.com/docker-for-mac/release-notes/[Docker for Mac releases] to find a link:/docs/cluster_up_down.md#prerequisites[supported
version] to download.
You will need to build `linux/amd64` binaries for the OpenShift server; if you
want to do the builds locally, you will need to follow the instructions to
install https://golang.org/doc/install#install[the `go` programming language].
Go `pkg` installers can be downloaded https://golang.org/dl/[here].

===== Windows

Follow the installation steps to install https://git-for-windows.github.io/[`git` for Windows]
and https://docs.docker.com/docker-for-windows/install/[`docker`].
Search the https://docs.docker.com/docker-for-windows/release-notes/[Docker for Windows releases] to find a link:/docs/cluster_up_down.md#prerequisites[supported
version] to download.
You will need to build `linux/amd64` binaries for the OpenShift server; if you
want to do the builds locally, you will need to follow the instructions to
install https://golang.org/doc/install#windows[the `go` programming language].
Go `msi` installers can be downloaded https://golang.org/dl/[here].

===== Fedora

Expand Down
104 changes: 43 additions & 61 deletions docs/cluster_up_down.md
View file
Expand Up @@ -2,30 +2,39 @@

- [Overview](#overview)
- [Getting Started](#getting-started)
- [Prerequisities](#prerequisites)
- [Linux](#linux)
- [MacOS with Docker for Mac](#macos-with-docker-for-mac)
- [Mac OS X with Docker Toolbox](#mac-os-x-with-docker-toolbox)
- [Mac OS X with Docker Machine](#mac-os-x-with-docker-machine)
- [Windows with Docker for Windows](#windows-with-docker-for-windows)
- [Windows with Docker Toolbox](#windows-with-docker-toolbox)
- [Windows with Docker Machine](#windows-with-docker-machine)
- [Persistent Volumes](#persistent-volumes)
- [Using a Proxy](#using-a-proxy)
- [Installing Metrics](#installing-metrics)
- [Installing Logging Aggregation](#installing-logging-aggregation)
- [Installing the Service Catalog](#installing-the-service-catalog)
- [Administrator Access](#administrator-access)
- [Docker Machine](#docker-machine)
- [Configuration](#configuration)
- [Etcd Data](#etcd-data)
- [Routing](#routing)
- [Specifying Images to Use](#specifying-images-to-use)
- [Accessing the OpenShift Registry Directly](#accessing-the-openshift-registry-directly)

## Pre-requisites
## Prerequisites

| NOTE |
| ---- |
| This command was released with the 1.3+ version of oc client tools, so you must be using version 1.3+ or newer for this command to work. |

To run an OpenShift cluster locally, you must have a compatible version of Docker installed in your environment.
OpenShift officially supports the following versions of Docker:

| OpenShift Version | Docker Version |
| ----------------- | -------------- |
| 3.9 | 1.13 |
| 3.6-3.7 | 1.12 |
| 1.4-1.5 | 1.12 |
| 1.3 | 1.10 |

## Overview

Expand All @@ -46,7 +55,7 @@ a URL to access the management console for your cluster.
| The default Firewalld configuration on Fedora blocks access to ports needed by containers running on an OpenShift cluster. Make sure you grant access to these ports. See step 3 below. |
| Check that `sysctl net.ipv4.ip_forward` is set to 1. |

1. Install Docker with your platform's package manager.
1. Install Docker with your platform's package manager. Consult the [compatibility table](#prerequisites) to select a supported version of Docker.
2. Configure the Docker daemon with an insecure registry parameter of `172.30.0.0/16`
- In RHEL and Fedora, edit the `/etc/containers/registries.conf` file and add the following lines:
```
Expand Down Expand Up @@ -112,7 +121,12 @@ $ oc cluster down

### MacOS with Docker for Mac

1. Install [Docker for Mac](https://docs.docker.com/docker-for-mac/) making sure you meet the [prerequisites](https://docs.docker.com/docker-for-mac/#/what-to-know-before-you-install).
> `oc cluster up` with Docker for Mac does not work with versions 3.7.1 and earlier.
We recommend using [Mac OS X with Docker Machine](#mac-os-x-with-docker-machine) with these versions of the openshift cli.
See [issue #17570](https://github.com/openshift/origin/issues/17570).

1. Install [Docker for Mac](https://docs.docker.com/docker-for-mac/release-notes/) making sure you meet the [prerequisites](https://docs.docker.com/docker-for-mac/#/what-to-know-before-you-install)
and download a [compatible version of Docker](#prerequisites).
2. Once Docker is running, add an insecure registry of `172.30.0.0/16`:
- From the Docker menu in the toolbar, select `Preferences...`
- Click on `Daemon` in the preferences dialog (note: on some older versions of Docker for Mac this is under `Advanced`)
Expand All @@ -133,7 +147,7 @@ $ oc cluster down
Download the Mac OS `oc` binary from [openshift-origin-client-tools-VERSION-mac.zip](https://github.com/openshift/origin/releases) and place it in your path.

> Please be aware that the 'oc cluster' set of commands are only available in the 1.3+ or newer releases.
3. Open Terminal and run
```
$ oc cluster up
Expand All @@ -144,38 +158,34 @@ To stop your cluster, run:
$ oc cluster down
```

### Mac OS X with Docker Toolbox
### Mac OS X with Docker Machine

1. Install [Docker Toolbox](https://www.docker.com/products/docker-toolbox) and ensure that it is functional.
2. Install the oc binary using homebrew with: `brew install openshift-cli`
1. Install [Docker for Mac](https://docs.docker.com/docker-for-mac/release-notes/) making sure you meet the [prerequisites](https://docs.docker.com/docker-for-mac/#/what-to-know-before-you-install)
and download a [compatible version of Docker](#prerequisites).
2. Install [VirtualBox for OSX Hosts](https://www.virtualbox.org/wiki/Downloads)
3. Install the oc binary using homebrew with: `brew install openshift-cli`

OR

Download the OS X `oc` binary from [openshift-origin-client-tools-VERSION-mac.zip](https://github.com/openshift/origin/releases) and place it in your path.

> Please be aware that the 'oc cluster' set of commands are only available in the 1.3+ or newer releases.
3. Open Terminal and run
4. Create a new docker machine named `openshift` with appropriate resource constraints. See [Getting Started with Docker Machine](https://docs.docker.com/machine/get-started/#create-a-machine) for instructions.
5. Open Terminal and run
```
$ oc cluster up --create-machine
$ oc cluster up --docker-machine=openshift
```

A Docker machine named `openshift` will be created using the VirtualBox driver and the OpenShift cluster
will be started on it.
OpenShift will start cluster on the docker machine you specified.

To stop the cluster, run:

```
$ oc cluster down --docker-machine=openshift
```

To create a machine with a different name, specify the `--docker-machine` argument with `--create-machine`:

```
$ oc cluster up --create-machine --docker-machine=mymachine
```

Once the machine has been created, the `--create-machine` argument is no longer needed. To start/stop OpenShift again, either:
To start/stop OpenShift again, either:

* Setup the Docker environment for the machine you wish to use, and then run `oc cluster up` and `oc cluster down`:

Expand All @@ -202,7 +212,8 @@ Once the machine has been created, the `--create-machine` argument is no longer

### Windows with Docker for Windows

1. Install [Docker for Windows](https://docs.docker.com/docker-for-windows/) making sure you meet the [prerequisites](https://docs.docker.com/docker-for-windows/#/what-to-know-before-you-install).
1. Install [Docker for Windows](https://docs.docker.com/docker-for-windows/relase-notes/) making sure you meet the [prerequisites](https://docs.docker.com/docker-for-windows/#/what-to-know-before-you-install)
and download a [compatible version of Docker](#prerequisites).
2. Once Docker is running, add an insecure registry of `172.30.0.0/16`:
- Right click on the Docker icon in the notification area and select `Settings...`
- Click on `Docker Daemon` in the settings dialog
Expand All @@ -229,35 +240,30 @@ To stop the cluster, run:
C:\> oc cluster down
```

### Windows with Docker Toolbox
### Windows with Docker Machine

1. Install [Docker Toolbox](https://www.docker.com/products/docker-toolbox) and ensure that it is functional.
2. Download the Windows `oc.exe` binary from [openshift-origin-client-tools-VERSION-windows.zip](https://github.com/openshift/origin/releases) and place it in your path.
1. Install [Docker for Windows](https://docs.docker.com/docker-for-windows/release-notes/) making sure you meet the [prerequisites](https://docs.docker.com/docker-for-windows/#/what-to-know-before-you-install)
and download a [compatible version of Docker](#prerequisites).
2. Review the [prerequisite instructions](https://docs.docker.com/machine/get-started/#prerequisite-information) to set up Docker Machine on Windows.
3. Download the Windows `oc.exe` binary from [openshift-origin-client-tools-VERSION-windows.zip](https://github.com/openshift/origin/releases) and place it in your path.

> Please be aware that the 'oc cluster' set of commands are only available in the 1.3+ or newer releases.
3. Open a Command window as Administrator (for most drivers, docker-machine on Windows requires administrator privileges)
4. Create a new docker machine named `openshift` with appropriate resource constraints. See [Getting Started with Docker Machine](https://docs.docker.com/machine/get-started/#create-a-machine) for instructions.
5. Open a Command window as Administrator (for most drivers, docker-machine on Windows requires administrator privileges)
and run:
```
C:\> oc cluster up --create-machine
C:\> oc cluster up --docker-machine=openshift
```

A Docker machine named `openshift` will be created using the VirtualBox driver and the OpenShift cluster
will be started on it.
OpenShift will start cluster on the docker machine you specified.

To stop the cluster, run:

```
C:\> oc cluster down --docker-machine=openshift
```

To create a machine with a different name, specify the `--docker-machine` argument with `--create-machine`:

```
C:\> oc cluster up --create-machine --docker-machine=mymachine
```

Once the machine has been created, the `--create-machine` argument is no longer needed. To start/stop OpenShift again, either:
To start/stop OpenShift again, either:

* Setup the Docker environment for the machine you wish to use, and then run `oc cluster up` and `oc cluster down`:
```
Expand Down Expand Up @@ -367,30 +373,6 @@ To return to the regular `developer` user, login as that user:
oc login -u developer
```

## Docker Machine

By default, when `--create-machine` is used to create a new Docker machine, the `oc cluster up` command will use the
VirtualBox driver. In order to use a different driver, you must create the Docker machine beforehand
and either specify its name with the `--docker-machine` argument, or set its environment using the `docker-machine env`
command. When creating a Docker machine manually, you must specify the `--engine-insecure-registry` argument with the
value expected by OpenShift.

Following are examples of creating a new Docker machine in OS X using the [xhyve](https://github.com/zchee/docker-machine-driver-xhyve) driver,
and in Windows, using the [hyper-v](https://docs.docker.com/machine/drivers/hyper-v/) driver.

OS X:
```
$ docker-machine create --driver xhyve --engine-insecure-registry 172.30.0.0/16 mymachine
```

Windows (running a command window as Administrator):
```
C:\> docker-machine create --driver hyperv --engine-insecure-registry 172.30.0.0/16 mymachine
```

When the `--docker-machine` argument is specified on `oc cluster up`, the machine's environment does not need to be configured
on the current shell. Also if the machine exists but is not started, `oc cluster up` will attempt to start it.

## Configuration

`oc cluster up` creates its configuration by default in `/var/lib/origin/openshift.local.config` on the Docker host.
Expand Down

0 comments on commit a297c4d

Please sign in to comment.