From a297c4dbfd21571a12e83c82603278da93a2f270 Mon Sep 17 00:00:00 2001 From: Adam Kaplan Date: Tue, 27 Mar 2018 17:20:17 -0400 Subject: [PATCH] Updates to CONTRIBUTING Documentation * 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 --- CONTRIBUTING.adoc | 11 ++++- docs/cluster_up_down.md | 104 +++++++++++++++++----------------------- 2 files changed, 52 insertions(+), 63 deletions(-) diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc index b0919b62ab49..7680816b1962 100644 --- 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 index f3645d432118..7819963bfa04 100644 --- 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,10 +158,12 @@ 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 @@ -155,13 +171,13 @@ $ oc cluster down > 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: @@ -169,13 +185,7 @@ 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,21 +240,22 @@ 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: @@ -251,13 +263,7 @@ 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.