Docs update for 4.1

Author: mtnbikenc

BUILD.md

@@ -32,22 +32,3 @@ To build a container image of `openshift-ansible` using standalone **Docker**:
 
         cd openshift-ansible
         docker build -f images/installer/Dockerfile -t openshift-ansible .
-
-## Build the Atomic System Container
-
-A system container runs using runC instead of Docker and it is managed
-by the [atomic](https://github.com/projectatomic/atomic/) tool.  As it
-doesn't require Docker to run, the installer can run on a node of the
-cluster without interfering with the Docker daemon that is configured
-by the installer itself.
-
-The first step is to build the [container image](#build-an-openshift-ansible-container-image)
-as described before.  The container image already contains all the
-required files to run as a system container.
-
-Once the container image is built, we can import it into the OSTree
-storage:
-
-```
-atomic pull --storage ostree docker:openshift-ansible:latest
-```

CONTRIBUTING.md

@@ -74,27 +74,6 @@ If you are new to Git, these links might help:
 
 ---
 
-## Simple all-in-one localhost installation
-```
-git clone https://github.com/openshift/openshift-ansible
-cd openshift-ansible
-sudo ansible-playbook -i inventory/hosts.localhost playbooks/prerequisites.yml
-sudo ansible-playbook -i inventory/hosts.localhost playbooks/deploy_cluster.yml
-```
-
-## Development process
-Most changes can be applied by re-running the config playbook. However, while
-the config playbook will run faster the second time through it's still going to
-take a very long time. As such, you may wish to run a smaller subsection of the
-installation playbooks. You can for instance run the node, master, or hosted
-playbooks in playbooks/openshift-node/config.yml,
-playbooks/openshift-master/config.yml, playbooks/openshift-hosted/config.yml
-respectively.
-
-We're actively working to refactor the playbooks into smaller discrete
-components and we'll be documenting that structure shortly, for now those are
-the most sensible logical units of work.
-
 ## Running tests and other verification tasks
 
 We use [`tox`](http://readthedocs.org/docs/tox/) to manage virtualenvs where
@@ -171,13 +150,6 @@ be reinstalled.
 
 Here are some useful tips that might improve your workflow while working on this repository.
 
-#### Git Hooks
-
-Git hooks are included in this repository to aid in development. Check
-out the README in the
-[hack/hooks](http://github.com/openshift/openshift-ansible/blob/master/hack/hooks/README.md)
-directory for more information.
-
 #### Activating a virtualenv managed by tox
 
 If you want to enter a virtualenv created by tox to do additional debugging, you

DEPLOYMENT_TYPES.md

@@ -1,6 +1,6 @@
 # Hooks
 
-The ansible installer allows for operators to execute custom tasks during
+OpenShift Ansible allows for operators to execute custom tasks during
 specific operations through a system called hooks. Hooks allow operators to
 provide files defining tasks to execute before and/or after specific areas
 during installations and upgrades. This can be very helpful to validate
@@ -16,21 +16,17 @@ need to be updated to meet the new standard.
 
 ## Using Hooks
 
-Hooks are defined in the ``hosts`` inventory file under the ``OSEv3:vars``
+Hooks are defined in the ``hosts`` inventory file under the ``nodes:vars``
 section.
 
 Each hook should point to a yaml file which defines Ansible tasks. This file
 will be used as an include meaning that the file can not be a playbook but
 a set of tasks. Best practice suggests using absolute paths to the hook file to avoid any ambiguity.
 
-### Example
+### Example inventory variables
 ```ini
-[OSEv3:vars]
+[nodes:vars]
 # <snip>
-openshift_master_upgrade_pre_hook=/usr/share/custom/pre_master.yml
-openshift_master_upgrade_hook=/usr/share/custom/master.yml
-openshift_master_upgrade_post_hook=/usr/share/custom/post_master.yml
-
 openshift_node_upgrade_pre_hook=/usr/share/custom/pre_node.yml
 openshift_node_upgrade_hook=/usr/share/custom/node.yml
 openshift_node_upgrade_post_hook=/usr/share/custom/post_node.yml
@@ -40,46 +36,31 @@ openshift_node_upgrade_post_hook=/usr/share/custom/post_node.yml
 Hook files must be a yaml formatted file that defines a set of Ansible tasks.
 The file may **not** be a playbook.
 
-### Example
+### Example hook task file
 ```yaml
+
 ---
 # Trivial example forcing an operator to ack the start of an upgrade
-# file=/usr/share/custom/pre_master.yml
+# file=/usr/share/custom/pre_node.yml
 
-- name: note the start of a master upgrade
+- name: note the start of a node upgrade
   debug:
-      msg: "Master upgrade of {{ inventory_hostname }} is about to start"
+      msg: "Node upgrade of {{ inventory_hostname }} is about to start"
 
 - name: require an operator agree to start an upgrade
   pause:
-      prompt: "Hit enter to start the master upgrade"
+      prompt: "Hit enter to start the node upgrade"
 ```
 
-## Upgrade Hooks
-
-### openshift_master_upgrade_pre_hook
-- Runs **before** each master is upgraded.
-- This hook runs against **each master** in serial.
-- If a task needs to run against a different host, said task will need to use [``delegate_to`` or ``local_action``](http://docs.ansible.com/ansible/playbooks_delegation.html#delegation).
-
-### openshift_master_upgrade_hook
-- Runs **after** each master is upgraded but **before** it's service/system restart.
-- This hook runs against **each master** in serial.
-- If a task needs to run against a different host, said task will need to use [``delegate_to`` or ``local_action``](http://docs.ansible.com/ansible/playbooks_delegation.html#delegation).
-
-
-### openshift_master_upgrade_post_hook
-- Runs **after** each master is upgraded and has had it's service/system restart.
-- This hook runs against **each master** in serial.
-- If a task needs to run against a different host, said task will need to use [``delegate_to`` or ``local_action``](http://docs.ansible.com/ansible/playbooks_delegation.html#delegation).
+## Available Upgrade Hooks
 
 ### openshift_node_upgrade_pre_hook
 - Runs **before** each node is upgraded.
 - This hook runs against **each node** in serial.
 - If a task needs to run against a different host, said task will need to use [``delegate_to`` or ``local_action``](http://docs.ansible.com/ansible/playbooks_delegation.html#delegation).
 
 ### openshift_node_upgrade_hook
-- Runs **after** each node is upgraded but **before** it's marked schedulable again..
+- Runs **after** each node is upgraded but **before** it's marked schedulable again.
 - This hook runs against **each node** in serial.
 - If a task needs to run against a different host, said task will need to use [``delegate_to`` or ``local_action``](http://docs.ansible.com/ansible/playbooks_delegation.html#delegation).
 

HOOKS.md

@@ -1,172 +1,55 @@
 [![Join the chat at https://gitter.im/openshift/openshift-ansible](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/openshift/openshift-ansible)
 [![Build Status](https://travis-ci.org/openshift/openshift-ansible.svg?branch=master)](https://travis-ci.org/openshift/openshift-ansible)
-[![Coverage Status](https://coveralls.io/repos/github/openshift/openshift-ansible/badge.svg?branch=master)](https://coveralls.io/github/openshift/openshift-ansible?branch=master)
-
-NOTICE
-======
-
-Master branch is closed! A major refactor is ongoing in devel-40.
-Changes for 3.x should be made directly to the latest release branch they're
-relevant to and backported from there.
-
-WARNING
-=======
-
-This branch is under heavy development.  If you are interested in deploying a
-working cluster, please utilize a release branch.
 
 # OpenShift Ansible
-
 This repository contains [Ansible](https://www.ansible.com/) roles and
-playbooks to install, upgrade, and manage
-[OpenShift](https://www.openshift.com/) clusters.
-
-## Getting the correct version
-When choosing an openshift release, ensure that the necessary origin packages
-are available in your distribution's repository.  By default, openshift-ansible
-will not configure extra repositories for testing or staging packages for
-end users.
-
-We recommend using a release branch. We maintain stable branches
-corresponding to upstream Origin releases, e.g.: we guarantee an
-openshift-ansible 3.2 release will fully support an origin
-[1.2 release](https://github.com/openshift/openshift-ansible/tree/release-1.2).
-
-The most recent branch will often receive minor feature backports and
-fixes. Older branches will receive only critical fixes.
-
-In addition to the release branches, the master branch
-[master branch](https://github.com/openshift/openshift-ansible/tree/master)
-tracks our current work **in development** and should be compatible
-with the
-[Origin master branch](https://github.com/openshift/origin/tree/master)
-(code in development).
-
+playbooks for [OpenShift](https://www.openshift.com/) clusters.
 
+## Previous OpenShift Ansible 3.x releases
+For 3.x releases of OpenShift Ansible please reference the release branch for
+specific versions.  The last 3.x release is 
+[3.11 release](https://github.com/openshift/openshift-ansible/tree/release-3.11).
 
-**Getting the right openshift-ansible release**
+## OpenShift 4.x
+Installation of OpenShift 4.x uses a command-line installation wizard instead of
+Ansible playbooks.  Learn more about the OpenShift Installer in this
+[overview](https://github.com/openshift/installer/blob/master/docs/user/overview.md#installer-overview).
 
-Follow this release pattern and you can't go wrong:
+For OpenShift 4.x, this repo only provides playbooks necessary for scaling up an
+existing 4.x cluster with RHEL hosts.
 
-| Origin/OCP    | OpenShift-Ansible version | openshift-ansible branch |
-| ------------- | ----------------- |----------------------------------|
-| 1.3 / 3.3          | 3.3               | release-1.3 |
-| 1.4 / 3.4          | 3.4               | release-1.4 |
-| 1.5 / 3.5          | 3.5               | release-1.5 |
-| 3.*X*         | 3.*X*             | release-3.x |
-
-If you're running from the openshift-ansible **master branch** we can
-only guarantee compatibility with the newest origin releases **in
-development**. Use a branch corresponding to your origin version if
-you are not running a stable release.
-
-
-## Setup
-
-Install base dependencies:
+The [master branch](https://github.com/openshift/openshift-ansible/tree/master)
+tracks our current work **in development**.
 
 Requirements:
 
 - Ansible >= 2.7.8
-- Jinja >= 2.7
 - pyOpenSSL
-- python-lxml
-
-----
-
-Fedora:
-
-```
-dnf install -y ansible pyOpenSSL python-cryptography python-lxml
-```
-
-## Simple all-in-one localhost Installation
-This assumes that you've installed the base dependencies and you're running on
-Fedora or RHEL
-```
-git clone https://github.com/openshift/openshift-ansible
-cd openshift-ansible
-sudo ansible-playbook -i inventory/hosts.localhost playbooks/prerequisites.yml
-sudo ansible-playbook -i inventory/hosts.localhost playbooks/deploy_cluster.yml
-```
+- python2-openshift
 
 # Quickstart
 
-Install the new installer from https://www.github.com/openshift/installer
-
-Construct a proper install-config.yml, and make a copy called
-install-config-ansible.yml.
-
-## Hosts
-You will need the following hosts
-
-### Boostrap host
-This is a special host that is not part of the cluster but is required to be
-available to help the cluster bootstrap itself.  This is not a bastion host,
-it will initially be part of the cluster and should be able to communicate with
-the masters in the cluster.
-
-### Masters
-You need 1 or 3 masters.
-
-### Workers
-You need 0 or more workers.  Note, by default, masters are unschedulable so
-you will need one or more workers if you want to schedule workloads.
-
-## DNS
-4.x installs require specific dns records to be in place, and there is no way
-to complete an install without working DNS.  You are in charge of ensuring the
-following DNS records are resolvable from your cluster, the openshift-ansible
-installer will not make any attempt to do any of this for you.
-
-First, the output of ```hostname``` on each host must be resolvable to other hosts.
-The nodes will communicate with each other based on this value.
-
-install-config.yml value of 'baseDomain' must be a working domain.
-
-### A records
-```sh
-<clustername>-api.<baseDomain> # ex: mycluster-api.example.com
-<clustername>-master-0.<baseDomain> # ex: mycluster-master-0.example.com
-<clustername>-etcd-0.<baseDomain> # ex: mycluster-etcd-0.example.com
-<clustername>-bootstrap.<baseDomain> # ex: mycluster-bootstrap.example.com
-```
-
-Note: There should be a master/etcd record for each master host in your cluster
-(either 1 or 3).  etcd hosts must be master hosts, and the records must resolve
-to the same host for each master/etcd record, respectively.
-
-### SRV records
-```sh
-SRV _etcd-client-ssl._tcp.<clustername>.<baseDomain> '1 1 2379 <clustername>-etcd-0.<baseDomain>'
-SRV _etcd-server-ssl._tcp.<clustername>.<baseDomain> '1 1 2380 <clustername>-etcd-0.<baseDomain>'
-...
-SRV _etcd-client-ssl._tcp.<clustername>.<baseDomain> '1 1 2379 <clustername>-etcd-<N-1>.<baseDomain>'
-SRV _etcd-server-ssl._tcp.<clustername>.<baseDomain> '1 1 2380 <clustername>-etcd-<N-1>.<baseDomain>'
-
-# ex: _etcd-client-ssl._tcp.mycluster.example.com '1 1 2379 mycluster-etcd-0.example.com'
-```
-
-Consult with your DNS provider about the proper way to create SRV records.  In
-any case, there should be a client and server SRV record for each etcd backend,
-and you MUST use the etcd FQDN you created earlier, not the master or any other
-record.
+## Install an OpenShift 4.x cluster
+Install a cluster using the [OpenShift Installer](https://www.github.com/openshift/installer).
 
 ## Inventory
-Check out inventory/40_basic_inventory.ini for an example.
+Create an inventory file with the `new_workers` group to identify the hosts which
+should be added to the cluster.
+```yaml
+
+---
+[new_workers]
+mycluster-worker-0.example.com
+mycluster-worker-1.example.com
+mycluster-worker-2.example.com
+```
 
-## Generate ignition configs
-Use the openshift-install command to generate ignition configs utilizing the
-install-config.yml you created earlier.  This will consume the install-config.yml
-file, so ensure you have copied the file as mentioned previously.
+## Run the scaleup playbook
 
-```sh
-openshift-install create ignition-configs
+```bash
+ansible-playbook playbooks/openshift_node/scaleup.yml
 ```
 
-## Run playbook
-playbooks/deploy_cluster_40.yml
-
 # Further reading
 
 ## Complete Production Installation Documentation: