Merge pull request #2727 from rhcarvalho/contributing

Contribution guide

4 files changed, 153 insertions, 280 deletions

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 000000000..1145da495
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,111 @@
+# Contributing
+
+Thank you for contributing to OpenShift Ansible. This document explains how the
+repository is organized, and how to submit contributions.
+
+## Introduction
+
+Before submitting code changes, get familiarized with these documents:
+
+- [Core Concepts](https://github.com/openshift/openshift-ansible/blob/master/docs/core_concepts_guide.adoc)
+- [Best Practices Guide](https://github.com/openshift/openshift-ansible/blob/master/docs/best_practices_guide.adoc)
+- [Style Guide](https://github.com/openshift/openshift-ansible/blob/master/docs/style_guide.adoc)
+
+## Repository structure
+
+### Ansible
+
+```
+.
+├── inventory           Contains dynamic inventory scripts, and examples of
+│                       Ansible inventories.
+├── library             Contains Python modules used by the playbooks.
+├── playbooks           Contains Ansible playbooks targeting multiple use cases.
+└── roles               Contains Ansible roles, units of shared behavior among
+                        playbooks.
+```
+
+#### Ansible plugins
+
+These are plugins used in playbooks and roles:
+
+```
+.
+├── ansible-profile
+├── callback_plugins
+├── filter_plugins
+└── lookup_plugins
+```
+
+### Scripts
+
+```
+.
+├── bin                 [DEPRECATED] Contains the `bin/cluster` script, a
+│                       wrapper around the Ansible playbooks that ensures proper
+│                       configuration, and facilitates installing, updating,
+│                       destroying and configuring OpenShift clusters.
+│                       Note: this tool is kept in the repository for legacy
+│                       reasons and will be removed at some point.
+└── utils               Contains the `atomic-openshift-installer` command, an
+                        interactive CLI utility to install OpenShift across a
+                        set of hosts.
+```
+
+### Documentation
+
+```
+.
+└── docs                Contains documentation for this repository.
+```
+
+### Tests
+
+```
+.
+└── test                Contains tests.
+```
+
+### Others
+
+```
+.
+└── git                 Contains some helper scripts for repository maintenance.
+```
+
+## Building RPMs
+
+See the [RPM build instructions](BUILD.md).
+
+## Running tests
+
+We use [Nose](http://readthedocs.org/docs/nose/) as a test runner. Make sure it
+is installed along with other test dependencies:
+
+```
+pip install -r utils/test-requirements.txt
+```
+
+Run the tests with:
+
+```
+nosetests
+```
+
+## Submitting contributions
+
+1. Go through the guides from the [introduction](#Introduction).
+2. Fork this repository, and create a work branch in your fork.
+3. Make changes and commit. You may want to review your changes and run tests
+   before pushing your branch.
+4. Open a Pull Request.
+
+One of the repository maintainers will then review the PR and submit it for
+testing.
+
+The `default` test job is publicly accessible at
+https://ci.openshift.redhat.com/jenkins/job/openshift-ansible/. The other jobs
+are run on a different Jenkins host that is not publicly accessible, however the
+test results are posted to S3 buckets when complete.
+
+The test output of each job is also posted to the Pull Request as comments.
diff --git a/README.md b/README.md
index c3d78f5fe..950aea3ae 100644
--- a/README.md
+++ b/README.md
@@ -1,63 +1,56 @@
 [![Join the chat at https://gitter.im/openshift/openshift-ansible](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/openshift/openshift-ansible)
 
-#OpenShift Ansible
+# OpenShift Ansible
 
-This repo contains Ansible code for OpenShift. This repo and the origin RPMs
-that it installs currently require a package that provides `docker`. Currently
-the RPMs provided from dockerproject.org do not provide this requirement, though
-they may in the future.
+This repository contains [Ansible](https://www.ansible.com/) code to install,
+upgrade and manage [OpenShift](https://www.openshift.com/) clusters.
 
-##Branches and tags
+**Note**: the Ansible playbooks in this repository require an RPM package that
+provides `docker`. Currently, the RPMs from
+[dockerproject.org](https://dockerproject.org/) do not provide this requirement,
+though they may in the future. This limitation is being tracked by
+[#2720](https://github.com/openshift/openshift-ansible/issues/2720).
 
-The master branch tracks our current work and should be compatible with both
-Origin master branch and the most recent Origin stable release. Currently that's
-v1.4 and v1.3.x. In addition to the master branch we maintain stable branches
-corresponding to upstream Origin releases, ie: release-1.2. The most recent of
-branch will often receive minor feature backports and fixes. Older branches will
-receive only critical fixes.
+## Branches and tags
+
+The [master branch](https://github.com/openshift/openshift-ansible/tree/master)
+tracks our current work and should be compatible with both [Origin master
+branch](https://github.com/openshift/origin/tree/master) and the [most recent
+Origin stable release](https://github.com/openshift/origin/releases). Currently
+that's v1.4 and v1.3.x. In addition to the master branch, we maintain stable
+branches corresponding to upstream Origin releases, e.g.:
+[release-1.2](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.
 
 Releases are tagged periodically from active branches and are versioned 3.x
 corresponding to Origin releases 1.x. We unfortunately started with 3.0 and it's
 not practical to start over at 1.0.
 
-##Setup
-- Install base dependencies:
-  - Requirements:
-    - Ansible >= 2.1.0 though 2.2 is preferred for performance reasons.
+## Setup
+
+1. Install base dependencies:
+
+    ***
+    Requirements:
+    - Ansible >= 2.1.0 (>= 2.2 is preferred for performance reasons)
     - Jinja >= 2.7
+    ***
+
+    Fedora:
+    ```
+    dnf install -y ansible pyOpenSSL python-cryptography
+    ```
+
+2. Setup for a specific cloud:
 
-  - Fedora:
-  ```
-    dnf install -y ansible-2.1.0.0 pyOpenSSL python-cryptography
-  ```
-
-  - OSX:
-  ```
-    # Install ansible 2.1.0.0 and python 2
-    brew install ansible python
-  ```
-- Setup for a specific cloud:
   - [AWS](http://github.com/openshift/openshift-ansible/blob/master/README_AWS.md)
   - [GCE](http://github.com/openshift/openshift-ansible/blob/master/README_GCE.md)
   - [local VMs](http://github.com/openshift/openshift-ansible/blob/master/README_libvirt.md)
+  - Bring your own host deployments:
+      - [OpenShift Enterprise](https://docs.openshift.com/enterprise/latest/install_config/install/advanced_install.html)
+      - [OpenShift Origin](https://docs.openshift.org/latest/install_config/install/advanced_install.html)
+
+## Contributing
 
-- Bring your own host deployments:
-  - [OpenShift Enterprise](https://docs.openshift.com/enterprise/latest/install_config/install/advanced_install.html)
-  - [OpenShift Origin](https://docs.openshift.org/latest/install_config/install/advanced_install.html)
-  - [Atomic Enterprise](http://github.com/openshift/openshift-ansible/blob/master/README_AEP.md)
-
-- Build
-  - [How to build the openshift-ansible rpms](BUILD.md)
-
-- Directory Structure:
-  - [bin/cluster](https://github.com/openshift/openshift-ansible/tree/master/bin/cluster) - python script to easily create clusters
-  - [docs](https://github.com/openshift/openshift-ansible/tree/master/docs) - Documentation for the project
-  - [filter_plugins/](https://github.com/openshift/openshift-ansible/tree/master/filter_plugins) - custom filters used to manipulate data in Ansible
-  - [inventory/](https://github.com/openshift/openshift-ansible/tree/master/inventory) - houses Ansible dynamic inventory scripts
-  - [playbooks/](https://github.com/openshift/openshift-ansible/tree/master/playbooks) - houses host-type Ansible playbooks (launch, config, destroy, vars)
-  - [roles/](https://github.com/openshift/openshift-ansible/tree/master/roles) - shareable Ansible tasks
-
-##Contributing
-- [Best Practices Guide](https://github.com/openshift/openshift-ansible/blob/master/docs/best_practices_guide.adoc)
-- [Core Concepts](https://github.com/openshift/openshift-ansible/blob/master/docs/core_concepts_guide.adoc)
-- [Style Guide](https://github.com/openshift/openshift-ansible/blob/master/docs/style_guide.adoc)
+See the [contribution guide](CONTRIBUTING.md).
diff --git a/README_AEP.md b/README_AEP.md
deleted file mode 100644
index c588ebbd3..000000000
--- a/README_AEP.md
+++ /dev/null
@@ -1,233 +0,0 @@
-# Installing AEP from dev puddles using ansible
-
-* [Requirements](#requirements)
-* [Caveats](#caveats)
-* [Known Issues](#known-issues)
-* [Configuring the host inventory](#configuring-the-host-inventory)
-* [Creating the default variables for the hosts and host groups](#creating-the-default-variables-for-the-hosts-and-host-groups)
-* [Running the ansible playbooks](#running-the-ansible-playbooks)
-* [Post-ansible steps](#post-ansible-steps)
-* [Overriding detected ip addresses and hostnames](#overriding-detected-ip-addresses-and-hostnames)
-
-## Requirements
-* ansible 2.1.0.0
-  * Available in Fedora channels
-  * Available for EL with EPEL and Optional channel
-* One or more RHEL 7.1 VMs
-* Either ssh key based auth for the root user or ssh key based auth for a user
-  with sudo access (no password)
-* A checkout of openshift-ansible from https://github.com/openshift/openshift-ansible/
-
-  ```sh
-  git clone https://github.com/openshift/openshift-ansible.git
-  cd openshift-ansible
-  ```
-
-## Caveats
-This ansible repo is currently under heavy revision for providing OSE support;
-the following items are highly likely to change before the OSE support is
-merged into the upstream repo:
-  * the current git branch for testing
-  * how the inventory file should be configured
-  * variables that need to be set
-  * bootstrapping steps
-  * other configuration steps
-
-## Known Issues
-* Host subscriptions are not configurable yet, the hosts need to be
-  pre-registered with subscription-manager or have the RHEL base repo
-  pre-configured. If using subscription-manager the following commands will
-  disable all but the rhel-7-server rhel-7-server-extras and
-  rhel-server7-ose-beta repos:
-```sh
-subscription-manager repos --disable="*"
-subscription-manager repos \
---enable="rhel-7-server-rpms" \
---enable="rhel-7-server-extras-rpms" \
---enable="rhel-7-server-ose-3.0-rpms"
-```
-* Configuration of router is not automated yet
-* Configuration of docker-registry is not automated yet
-
-## Configuring the host inventory
-[Ansible docs](http://docs.ansible.com/intro_inventory.html)
-
-Example inventory file for configuring one master and two nodes for the test
-environment. This can be configured in the default inventory file
-(/etc/ansible/hosts), or using a custom file and passing the --inventory
-option to ansible-playbook.
-
-/etc/ansible/hosts:
-```ini
-# This is an example of a bring your own (byo) host inventory
-
-# Create an OSEv3 group that contains the masters and nodes groups
-[OSEv3:children]
-masters
-nodes
-
-# Set variables common for all OSEv3 hosts
-[OSEv3:vars]
-# SSH user, this user should allow ssh based auth without requiring a password
-ansible_ssh_user=root
-
-# If ansible_ssh_user is not root, ansible_become must be set to true
-#ansible_become=yes
-
-# See DEPLOYMENT_TYPES.md
-deployment_type=atomic-enterprise
-
-# Pre-release registry URL; note that in the future these images 
-# may have an atomicenterprise/aep- prefix or so.
-oreg_url=rcm-img-docker:5001/openshift3/ose-${component}:${version}
-
-# Pre-release additional repo
-openshift_additional_repos=[{'id': 'ose-devel', 'name': 'ose-devel', 'baseurl': 'http://buildvm/puddle/build/AtomicOpenShift/3.1/2015-10-27.1', 'enabled': 1, 'gpgcheck': 0}]
-
-# host group for masters
-[masters]
-aep3-master.example.com
-
-# host group for nodes
-[nodes]
-aep3-node[1:2].example.com
-```
-
-The hostnames above should resolve both from the hosts themselves and
-the host where ansible is running (if different).
-
-A more complete example inventory file ([hosts.aep.example](https://github.com/openshift/openshift-ansible/blob/master/inventory/byo/hosts.aep.example)) is available under the [`/inventory/byo`](https://github.com/openshift/openshift-ansible/tree/master/inventory/byo) directory.
-
-## Running the ansible playbooks
-From the openshift-ansible checkout run:
-```sh
-ansible-playbook playbooks/byo/config.yml
-```
-**Note:** this assumes that the host inventory is /etc/ansible/hosts, if using a different
-inventory file use the -i option for ansible-playbook.
-
-## Post-ansible steps
-#### Create the default router
-On the master host:
-```sh
-oadm router --create=true \
-  --service-account=router \
-  --credentials=/etc/origin/master/openshift-router.kubeconfig \
-  --images='rcm-img-docker01.build.eng.bos.redhat.com:5001/openshift3/ose-${component}:${version}'
-```
-
-#### Create the default docker-registry
-On the master host:
-```sh
-oadm registry --create=true \
-  --service-account=registry \
-  --credentials=/etc/origin/master/openshift-registry.kubeconfig \
-  --images='rcm-img-docker01.build.eng.bos.redhat.com:5001/openshift3/ose-${component}:${version}' \
-  --mount-host=/var/lib/openshift/docker-registry
-```
-
-## Overriding detected ip addresses and hostnames
-Some deployments will require that the user override the detected hostnames
-and ip addresses for the hosts. To see what the default values will be you can
-run the openshift_facts playbook:
-```sh
-ansible-playbook playbooks/byo/openshift_facts.yml
-```
-The output will be similar to:
-```
-ok: [10.3.9.45] => {
-    "result": {
-        "ansible_facts": {
-            "openshift": {
-                "common": {
-                    "hostname": "jdetiber-osev3-ansible-005dcfa6-27c6-463d-9b95-ef059579befd.os1.phx2.redhat.com",
-                    "ip": "172.16.4.79",
-                    "public_hostname": "jdetiber-osev3-ansible-005dcfa6-27c6-463d-9b95-ef059579befd.os1.phx2.redhat.com",
-                    "public_ip": "10.3.9.45",
-                    "use_openshift_sdn": true
-                },
-                "provider": {
-                  ... <snip> ...
-                }
-            }
-        },
-        "changed": false,
-        "invocation": {
-            "module_args": "",
-            "module_name": "openshift_facts"
-        }
-    }
-}
-ok: [10.3.9.42] => {
-    "result": {
-        "ansible_facts": {
-            "openshift": {
-                "common": {
-                    "hostname": "jdetiber-osev3-ansible-c6ae8cdc-ba0b-4a81-bb37-14549893f9d3.os1.phx2.redhat.com",
-                    "ip": "172.16.4.75",
-                    "public_hostname": "jdetiber-osev3-ansible-c6ae8cdc-ba0b-4a81-bb37-14549893f9d3.os1.phx2.redhat.com",
-                    "public_ip": "10.3.9.42",
-                    "use_openshift_sdn": true
-                },
-                "provider": {
-                  ...<snip>...
-                }
-            }
-        },
-        "changed": false,
-        "invocation": {
-            "module_args": "",
-            "module_name": "openshift_facts"
-        }
-    }
-}
-ok: [10.3.9.36] => {
-    "result": {
-        "ansible_facts": {
-            "openshift": {
-                "common": {
-                    "hostname": "jdetiber-osev3-ansible-bc39a3d3-cdd7-42fe-9c12-9fac9b0ec320.os1.phx2.redhat.com",
-                    "ip": "172.16.4.73",
-                    "public_hostname": "jdetiber-osev3-ansible-bc39a3d3-cdd7-42fe-9c12-9fac9b0ec320.os1.phx2.redhat.com",
-                    "public_ip": "10.3.9.36",
-                    "use_openshift_sdn": true
-                },
-                "provider": {
-                    ...<snip>...
-                }
-            }
-        },
-        "changed": false,
-        "invocation": {
-            "module_args": "",
-            "module_name": "openshift_facts"
-        }
-    }
-}
-```
-Now, we want to verify the detected common settings to verify that they are
-what we expect them to be (if not, we can override them).
-
-* hostname
-  * Should resolve to the internal ip from the instances themselves.
-  * openshift_hostname will override.
-* ip
-  * Should be the internal ip of the instance.
-  * openshift_ip will override.
-* public hostname
-  * Should resolve to the external ip from hosts outside of the cloud
-  * provider openshift_public_hostname will override.
-* public_ip
-  * Should be the externally accessible ip associated with the instance
-  * openshift_public_ip will override
-* use_openshift_sdn
-  * Should be true unless the cloud is GCE.
-  * openshift_use_openshift_sdn overrides
-
-To override the the defaults, you can set the variables in your inventory:
-```
-...snip...
-[masters]
-ose3-master.example.com openshift_ip=1.1.1.1 openshift_hostname=ose3-master.example.com openshift_public_ip=2.2.2.2 openshift_public_hostname=ose3-master.public.example.com
-...snip...
-```
diff --git a/setup.cfg b/setup.cfg
new file mode 100644
index 000000000..dd2913b35
--- /dev/null
+++ b/setup.cfg
@@ -0,0 +1,2 @@
+[nosetests]
+tests=test,utils