Merge pull request #11460 from mtnbikenc/update-docs

Update docs for scaleup and upgrade

HOOKS.md

@@ -3,20 +3,16 @@
 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
-or modify custom infrastructure when installing/upgrading OpenShift.
+during upgrades. This can be very helpful to validate
+or modify custom infrastructure when upgrading RHEL nodes in OpenShift.
 
 It is important to remember that when a hook fails the operation fails. This
 means a good hook can run multiple times and provide the same results. A great
 hook is idempotent.
 
-**Note**: There is currently not a standard interface for hooks. In the future
-a standard interface will be defined and any hooks that existed previously will
-need to be updated to meet the new standard.
-
 ## Using Hooks
 
-Hooks are defined in the ``hosts`` inventory file under the ``nodes:vars``
+Hooks are defined in the ``hosts`` inventory file under the ``all:vars``
 section.
 
 Each hook should point to a yaml file which defines Ansible tasks. This file
@@ -25,11 +21,12 @@ a set of tasks. Best practice suggests using absolute paths to the hook file to
 
 ### Example inventory variables
 ```ini
-[nodes:vars]
+[all:vars]
 # <snip>
-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
+openshift_node_pre_cordon_hook=/usr/share/custom/pre_cordon.yml
+openshift_node_pre_upgrade_hook=/usr/share/custom/pre_upgrade.yml
+openshift_node_pre_uncordon_hook=/usr/share/custom/pre_uncordon.yml
+openshift_node_post_upgrade_hook=/usr/share/custom/post_upgrade.yml
 # <snip>
 ```
 
@@ -41,31 +38,35 @@ The file may **not** be a playbook.
 
 ---
 # Trivial example forcing an operator to ack the start of an upgrade
-# file=/usr/share/custom/pre_node.yml
+# file=/usr/share/custom/pre_cordon.yml
 
 - name: note the start of a node upgrade
   debug:
-      msg: "Node 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 node upgrade"
+    prompt: "Hit enter to start the node upgrade"
 ```
 
 ## Available Upgrade Hooks
 
-### openshift_node_upgrade_pre_hook
-- Runs **before** each node is upgraded.
+### openshift_node_pre_cordon_hook
+- Runs **before** each node is cordoned.
 - 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.
+### openshift_node_pre_upgrade_hook
+- Runs **after** each node is cordoned but **before** it 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_post_hook
-- Runs **after** each node is upgraded; it's the last node upgrade action.
+### openshift_node_pre_uncordon_hook
+- Runs **after** each node is upgraded but **before** it is uncordoned.
 - 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_post_upgrade_hook
+- Runs **after** each node is uncordoned; it's the last node upgrade action.
+- 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).

README.md

@@ -15,54 +15,57 @@ 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).
 
-For OpenShift 4.x, this repo only provides playbooks necessary for scaling up an
-existing 4.x cluster with RHEL hosts.
+For OpenShift 4.x, this repo only provides playbooks necessary for scaling up or
+upgrading RHEL hosts in an existing 4.x cluster.
 
 The [master branch](https://github.com/openshift/openshift-ansible/tree/master)
 tracks our current work **in development**.
 
-Requirements:
+Requirements: (localhost)
 
 - Ansible >= 2.7.8
+- OpenShift Client (oc)
 
 # Quickstart
 
 ## Install an OpenShift 4.x cluster
 Install a cluster using the [OpenShift Installer](https://www.github.com/openshift/installer).
 
-## Inventory
-Create an inventory file with the `new_workers` group to identify the hosts which
-should be added to the cluster.
-```yaml
+## Create an Ansible Inventory
+Create an inventory file with the appropriate groups and variables defined.
+An example inventory can be found in [inventory/hosts.example](inventory/hosts.example).
 
----
-[new_workers]
-mycluster-worker-0.example.com
-mycluster-worker-1.example.com
-mycluster-worker-2.example.com
+Required variables include:
+
+- `openshift_kubeconfig_path` - Path to the kubeconfig for the cluster
+- `openshift_pull_secret_path` - Path to the pull secret to the image registry
+
+## Run the RHEL node scaleup playbook
+
+```bash
+cd openshift-ansible
+ansible-playbook -i inventory/hosts playbooks/scaleup.yml
 ```
 
-## Run the scaleup playbook
+## Run the RHEL node upgrade playbook
+Custom tasks can be performed during upgrades at different stages of the upgrade.
+See the [hooks documentation](HOOKS.md) for more information.
 
 ```bash
-ansible-playbook playbooks/openshift_node/scaleup.yml
+cd openshift-ansible
+ansible-playbook -i inventory/hosts playbooks/upgrade.yml
 ```
 
 # Further reading
 
 ## Complete Production Installation Documentation:
-
-- [OpenShift Container Platform](https://docs.openshift.com/container-platform/3.11/install/running_install.html)
-- [OpenShift Origin](https://docs.okd.io/latest/install/index.html)
+- [OpenShift Container Platform](https://docs.openshift.com)
+- [OpenShift Origin](https://docs.okd.io)
 
 ## Containerized OpenShift Ansible
 
 See [README_CONTAINER_IMAGE.md](README_CONTAINER_IMAGE.md) for information on how to package openshift-ansible as a container image.
 
-## Installer Hooks
-
-See the [hooks documentation](HOOKS.md).
-
 ## Contributing
 
 See the [contribution guide](CONTRIBUTING.md).

docs/pull_requests.md

@@ -10,8 +10,8 @@ Whenever a
 [Pull Request is opened](../CONTRIBUTING.md#submitting-contributions), all
 automated test jobs must be successfully run before the PR can be merged.
 
-Some of these jobs are automatically triggered, e.g., Travis, PAPR, and
-Coveralls. Other jobs need to be manually triggered by a member of the
+Some of these jobs are automatically triggered, e.g., Travis.
+Other jobs need to be manually triggered by a member of the
 [Team OpenShift Ansible Contributors](https://github.com/orgs/openshift/teams/team-openshift-ansible-contributors).
 
 ## Triggering tests
@@ -22,15 +22,6 @@ can trigger test jobs by adding a comment containing
 `/ok-to-test`. For a full list of bot commands refer to the [Bot Command
 Help](https://deck-ci.svc.ci.openshift.org/command-help?repo=openshift%2Fopenshift-ansible).
 
-### Fedora tests
-
-There are a set of tests that run on Fedora infrastructure. They are started
-automatically with every pull request.
-
-They are implemented using the [`PAPR` framework](https://github.com/projectatomic/papr).
-
-To re-run tests, write a comment containing only `bot, retest this please`.
-
 ## Triggering merge
 
 After a PR is properly reviewed and all test are passing, it can be

inventory/hosts.example

@@ -1,4 +1,23 @@
+[all:vars]
+# SSH user, this user should allow ssh based auth without requiring a
+# password. If using ssh key based auth, then the key should be managed by an
+# ssh agent.
+ansible_user=root
+
+# If ansible_user is not root, ansible_become must be set to true and the
+# user must be configured for passwordless sudo
+#ansible_become=True
+
+###############################################################################
+# Required configuration variables                                            #
+###############################################################################
+openshift_kubeconfig_path="~/.kube/config"
+openshift_pull_secret_path="~/pull-secret.txt"
+
+# For running RHEL worker upgrades
+[workers]
+mycluster-worker-[1:3].example.com
+
+# For running RHEL worker scaleup
 [new_workers]
-mycluster-worker-0.example.com
-mycluster-worker-1.example.com
-mycluster-worker-2.example.com
+mycluster-worker-[4:6].example.com

roles/openshift_node/README.md

@@ -1,61 +0,0 @@
-OpenShift Node
-================================
-
-Node service installation
-
-Requirements
-------------
-
-* Ansible 2.2
-* One or more Master servers
-* A RHEL 7.1 host pre-configured with access to the rhel-7-server-rpms,
-rhel-7-server-extras-rpms, and rhel-7-server-ose-3.0-rpms repos
-
-Role Variables
---------------
-From this role:
-
-| Name                                     | Default value         |                                                          |
-|------------------------------------------|-----------------------|----------------------------------------------------------|
-| openshift_node_start_options             | UNDEF (Optional)      | Options to pass to node start cmdline                    |
-| oreg_url                                 | UNDEF (Optional)      | Default docker registry to use                           |
-| openshift_persistentlocalstorage_enabled | false                 | Enable the persistent local storage                      |
-
-openshift_node_start_options can be used for passing any start node option, e.g.:
-
---enable=kubelet,plugins
-
-Which would have a node running without kube-proxy and dns.
-
-Dependencies
-------------
-
-
-Example Playbook
-----------------
-
-Notes
------
-
-Currently we support re-labeling nodes but we don't re-schedule running pods nor remove existing labels. That means you will have to trigger the re-schedulling manually. To re-schedule your pods, just follow the steps below:
-
-```
-oc adm manage-node --schedulable=false ${NODE}
-oc adm manage-node --drain ${NODE}
-oc adm manage-node --schedulable=true ${NODE}
-````
-
-> If you are using version less than 1.5/3.5 you must replace `--drain` with `--evacuate`.
-
-
-TODO
-
-License
--------
-
-Apache License, Version 2.0
-
-Author Information
-------------------
-
-TODO