Merge pull request #19112 from adambkaplan/feature/contributing-docfix

openshift-merge-robot · web-flow · commit f53958623c0e · 2018-04-03T12:49:39.000-07:00
Updates to CONTRIBUTING documentation.
diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc
@@ -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
@@ -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
 
diff --git a/docs/cluster_up_down.md b/docs/cluster_up_down.md
@@ -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
 
@@ -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:
      ```
@@ -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`)
@@ -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
@@ -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`:
 
@@ -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
@@ -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`:
   ```
@@ -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.
