RedHatTraining/agnosticd.git

parent: 19d6bff0 | patch | commit | ignore whitespace

Simplified root README.adoc - config in-depth moving to config writing guide

Tok

2018-12-04 2d10c09563f99751a791b3c7063526ff902a3013

Simplified root README.adoc - config in-depth moving to config writing guide

1 files added

1 files modified

	README.adoc	128 ●●●●● patch \| view \| raw \| blame \| history
	docs/archive/README.adoc	278 ●●●●● patch \| view \| raw \| blame \| history

 README.adoc

@@ -3,17 +3,14 @@

= Ansible Agnostic Deployer

Ansible Agnostic Deployer (AAD) is a 6 Stage Cloud Deployer for deploying application
environments, labs, workshops etc. Well designed environments, called _configs_,
can be easily abstracted to allow deployment to multiple different Public and 
Private Clouds including AWS, Azure, and others.
Ansible Agnostic Deployer (AAD) is a 6 Stage Cloud Deployer for deploying application environments, labs, workshops etc.
Well designed environments, called _configs_, can be easily abstracted to allow deployment to multiple different Public and Private Clouds including AWS, Azure, and others.

image::docs/images/agnosticd_flow.png[width=100%]


This document gives a brief overview of the project function, and structure. It
also provides a guide to the more comprehensive documentation set provided in 
the `docs/` direcorry.
This document gives a brief overview of the project function, and structure.
It also provides a guide to the more comprehensive documentation set provided in the `docs/` directory.

== Basic Structure

@@ -27,7 +24,7 @@
* `./ansible/main.yml` The entry point for a deployment
* `./ansible/configs` Home to the _configs_ to deploy

The Contributors Guides explore the relevant structures in more detail:
The Contributors Guides explore the relevant structures in significantly more detail:

* link:docs/Creating_a_config.adoc[Creating a Config]
* link:docs/Creating_a_cloud_deployer.adoc[Creating a Cloud Deployer]
@@ -38,8 +35,7 @@


AAD deployments start by invoking a common `main.yml` with environmental
variables identifying the _config_ and the cloud platform to deploy plus other 
meta-data.
variables identifying the _config_ and the cloud platform to deploy plus other meta-data.

e.g. `ansible-playbook main.yml -e "env_type=three-tier-app cloud_provider=aws"`

@@ -54,115 +50,18 @@
- import_playbook: "configs/{{ env_type }}/post_software.yml"
----

For _config_ developers the above stages provide 5 _hooks_ for customizing the 
configuration of your environemnet and 1 _hook_ for customizing it for one or
more cloud providers (e.g. AWS, Azure, etc).
For _config_ developers the above stages provide 5 _hooks_ for customizing the configuration of your environment and 1 _hook_ for customizing it for one or more cloud providers (e.g. AWS, Azure, etc).

An _Example config_ is provided by `ansible/configs/just-some-nodes-example`

==== Stage 0 `pre_infra.yml`


In this stage *AAD* is the entry playbook and is typical used for setting up any
infrastucture etc prior to launching a cloud deployemnt. Typical tasks would include:

* Creating necessary ssh keys
* Moving any ssh keys into place, setting permissions etc
* Creating any payloads to be used in later stages e.g. repo files etc
* Ensuring cloud credentials are avaialble 


==== Stage 1 Cloud Provider Deploy

This stage is unique in the flow in that the _config_ creator doesn't supply a 
playbook but typically has to provide cloud specfic configuration data.

Clouds are selected via the value of the `cloud_provider` variable and supported
clouds can be found in `ansible/cloud_providers`. Currently supported are:

* Amazon Web Services (AWS)
* Microsfoft Azure

Example: *AWS* configs use CloudFormations templates to deploy their infrastructure 
so this can be provied 

[NOTE]
[TIP]
====
A Cloud Creators document exists to faciliate adding further clouds to *AAD*. Wish
list items include:

* OpenShift
* OpenStack
* Google Cloud Engine (GCE)
To understand the 6 stages in depth and how to create your own _config_ or copy and modify an existing _config_ please see the link:docs/Creating_a_config.adoc[Creating a Config Developers Guide] for more detail.
====


==== Stage 2 `post_infra.yml`

In this stage *AAD*

==== Stage 3 `pre_software.yml`

At this point the infrastucure should be up and running but typically in a totally
unconfugured state. 

Typical tasks:

* Setup yum repos or equivilent
* `ssh` key housekeeping - for example inserting additional keys and configuration
* Prepare `bastion` hosts or `jumpboxes`


==== Stage 4 `software.yml`

In this stage *AAD*

==== Stage 5 `post_software.yml`


== Overview of a _Config_

Documnetation: `docs/Creating_congfigs
_Configs_ are located in the `ansible/configs/` directory

[source,bash]
----
README.adoc              linklight                 ocp-ha-disconnected-lab   quay-enterprise
ans-tower-lab            linklight-demo            ocp-ha-lab                rhte-ansible-net
ansible-cicd-lab         linklight-engine          ocp-implementation-lab    rhte-lb
ansible-provisioner      linklight-foundations     ocp-multi-cloud-example   rhte-oc-cluster-vms
archive                  linklight-networking      ocp-storage-cns           rhte-ocp-workshop
bu-workshop              linklight-networking-all  ocp-workloads             simple-multi-cloud
just-some-nodes-example  ocp-clientvm              ocp-workshop              three-tier-app
lightbulb                ocp-gpu-single-node       openshift-demos
----
_Above configs subject to change over time_

A typical _Config_ is 


[source,bash]
----
three-tier-app
├── README.adoc             
├── destroy_env.yml
├── env_vars.yml
├── files
├── post_infra.yml
├── post_software.yml
├── pre_infra.yml
├── pre_software.yml
└── software.yml
----




== Prerequisites

There are several prerequisites for using this repository, scripted and detailed
 instructions for usage are available in the following the
  link:./docs/Preparing_your_workstation.adoc[Preparing Your Workstation] document.
There are several prerequisites for using this repository, scripted and detailed instructions for usage are available in the following the link:./docs/Preparing_your_workstation.adoc[Preparing Your Workstation] document.
   [estimated effort 5-10 minutes]

* Software required on provisioning workstation:
@@ -197,11 +96,9 @@
 `_vars` and `_secret_vars`. The `example_secret_vars` file shows the format for
  what to put in your `CONFIGNAME_secret_vars` file.


== Running the Ansible Playbooks

Once you have installed your prerequisites and have configured all settings and
files, simply run Ansible like so:
Once you have installed your prerequisites and have configured all settings and files, simply run Ansible like so:

----
ansible-playbook -i 127.0.0.1, ansible/main.yml -e "env_type=config-name" -e "aws_region=ap-southeast-2" -e "guid=youruniqueidentifier"
@@ -214,8 +111,7 @@

== Cleanup (Reference Only)

NOTE: S3 Buckets are now part of a CloudFormation stack and are properly deleted before the stack in the destroy playbooks.

NOTE: S3 Buckets are now part of a CloudFormation stack and are properly deleted before the stack in the destroy playbooks.  
* S3 Bucket
- (Reference Only) An S3 bucket is used to back the Docker registry. AWS will not let you delete a
non-empty S3 bucket, so you must do this manually. The `aws` CLI makes this

 docs/archive/README.adoc

New file
@@ -0,0 +1,278 @@
:toc2:
image::https://travis-ci.org/sborenst/ansible_agnostic_deployer.svg?branch=development[link="https://travis-ci.org/sborenst/ansible_agnostic_deployer"]

= Ansible Agnostic Deployer

Ansible Agnostic Deployer (AAD) is a 6 Stage Cloud Deployer for deploying application
environments, labs, workshops etc. Well designed environments, called _configs_,
can be easily abstracted to allow deployment to multiple different Public and 
Private Clouds including AWS, Azure, and others.

image::docs/images/agnosticd_flow.png[width=100%]


This document gives a brief overview of the project function, and structure. It
also provides a guide to the more comprehensive documentation set provided in 
the `docs/` direcorry.

== Basic Structure

The repository contains various Ansible playbooks, templates, and other support
files used to provision different software (OpenShift, Ansible Tower, ...) onto 
Cloud Infrastructure (AWS, Ravello, ...). The key files and directories include:


* `./docs/` Start here
* `./ansible` The execution environment
* `./ansible/main.yml` The entry point for a deployment
* `./ansible/configs` Home to the _configs_ to deploy

The Contributors Guides explore the relevant structures in more detail:

* link:docs/Creating_a_config.adoc[Creating a Config]
* link:docs/Creating_a_cloud_deployer.adoc[Creating a Cloud Deployer]

== Overview of Ansible Agnostic Deployer Flow

image::docs/images/agnosticd_flow.png[width=100%]


AAD deployments start by invoking a common `main.yml` with environmental
variables identifying the _config_ and the cloud platform to deploy plus other 
meta-data.

e.g. `ansible-playbook main.yml -e "env_type=three-tier-app cloud_provider=aws"`

.*Simplified execution flow of `main.yml`
[source,bash]
----
- import_playbook: "configs/{{ env_type }}/pre_infra.yml"
- import_playbook: "cloud_providers/{{ cloud_provider }}_infrastructure_deployment.yml"
- import_playbook: "configs/{{ env_type }}/post_infra.yml"
- import_playbook: "configs/{{ env_type }}/pre_software.yml"
- import_playbook: "configs/{{ env_type }}/software.yml"
- import_playbook: "configs/{{ env_type }}/post_software.yml"
----

For _config_ developers the above stages provide 5 _hooks_ for customizing the 
configuration of your environemnet and 1 _hook_ for customizing it for one or
more cloud providers (e.g. AWS, Azure, etc).

An _Example config_ is provided by `ansible/configs/just-some-nodes-example`

==== Stage 0 `pre_infra.yml`


In this stage *AAD* is the entry playbook and is typical used for setting up any
infrastucture etc prior to launching a cloud deployemnt. Typical tasks would include:

* Creating necessary ssh keys
* Moving any ssh keys into place, setting permissions etc
* Creating any payloads to be used in later stages e.g. repo files etc
* Ensuring cloud credentials are avaialble 


==== Stage 1 Cloud Provider Deploy

This stage is unique in the flow in that the _config_ creator doesn't supply a 
playbook but typically has to provide cloud specfic configuration data.

Clouds are selected via the value of the `cloud_provider` variable and supported
clouds can be found in `ansible/cloud_providers`. Currently supported are:

* Amazon Web Services (AWS)
* Microsfoft Azure

Example: *AWS* configs use CloudFormations templates to deploy their infrastructure 
so this can be provied 

[NOTE]
====
A Cloud Creators document exists to faciliate adding further clouds to *AAD*. Wish
list items include:

* OpenShift
* OpenStack
* Google Cloud Engine (GCE)
====


==== Stage 2 `post_infra.yml`

In this stage *AAD*

==== Stage 3 `pre_software.yml`

At this point the infrastucure should be up and running but typically in a totally
unconfugured state. 

Typical tasks:

* Setup yum repos or equivilent
* `ssh` key housekeeping - for example inserting additional keys and configuration
* Prepare `bastion` hosts or `jumpboxes`


==== Stage 4 `software.yml`

In this stage *AAD*

==== Stage 5 `post_software.yml`


== Overview of a _Config_

Documnetation: `docs/Creating_congfigs
_Configs_ are located in the `ansible/configs/` directory

[source,bash]
----
README.adoc              linklight                 ocp-ha-disconnected-lab   quay-enterprise
ans-tower-lab            linklight-demo            ocp-ha-lab                rhte-ansible-net
ansible-cicd-lab         linklight-engine          ocp-implementation-lab    rhte-lb
ansible-provisioner      linklight-foundations     ocp-multi-cloud-example   rhte-oc-cluster-vms
archive                  linklight-networking      ocp-storage-cns           rhte-ocp-workshop
bu-workshop              linklight-networking-all  ocp-workloads             simple-multi-cloud
just-some-nodes-example  ocp-clientvm              ocp-workshop              three-tier-app
lightbulb                ocp-gpu-single-node       openshift-demos
----
_Above configs subject to change over time_

A typical _Config_ is 


[source,bash]
----
three-tier-app
├── README.adoc             
├── destroy_env.yml
├── env_vars.yml
├── files
├── post_infra.yml
├── post_software.yml
├── pre_infra.yml
├── pre_software.yml
└── software.yml
----




== Prerequisites

There are several prerequisites for using this repository, scripted and detailed
 instructions for usage are available in the following the
  link:./docs/Preparing_your_workstation.adoc[Preparing Your Workstation] document.
   [estimated effort 5-10 minutes]

* Software required on provisioning workstation:
- https://www.python.org[Python] version 2.7.x (3.x untested and may not work)
- http://docs.pythonboto.org[Python Boto] version 2.41 or greater
- http://github.com[Git] any version would do.
- https://github.com/ansible/ansible[Ansible] version 2.1.2 or greater
 with version 1.11.32
* AWS
** https://s3.amazonaws.com/aws-cli/awscli-bundle.zip[awscli bundle] tested
** Credentials and Policies:
*** AWS user account with credentials to provision resources
*** A route53 link:http://docs.aws.amazon.com/Route53/latest/DeveloperGuide/CreatingHostedZone.html[public hosted zone]
  is required for the scripts to create the various DNS entries for the
  resources it creates. The "HostedZoneId" will need to be provided in the
  variable file.
*** An EC2 SSH keypair should be created in advance and you should save the key
    file to your system. (command line instructions can be found in the
       link:./docs/Preparing_your_workstation.adoc[Preparing Your Workstation] document.)

== Standard Configurations

* Several "Standard Configurations" are included in this repository.
* A "Standard Configurations" or "Config" are a predefined deployment examples
 that can be used or copied and modified by anyone.
* A "Config" will include all the files, templates, pre and post playbooks that
 a deployment example requires to be deployed.
* "Config" specific Variable files will be included in the "Config" directory as
 well.

NOTE: Until we implement using Ansible Vault, each "Config" has two vars files
 `_vars` and `_secret_vars`. The `example_secret_vars` file shows the format for
  what to put in your `CONFIGNAME_secret_vars` file.


== Running the Ansible Playbooks

Once you have installed your prerequisites and have configured all settings and
files, simply run Ansible like so:

----
ansible-playbook -i 127.0.0.1, ansible/main.yml -e "env_type=config-name" -e "aws_region=ap-southeast-2" -e "guid=youruniqueidentifier"

----

NOTE: Be sure to exchange `guid` for a sensible prefix of your choosing.

For "opentlc-shared" standard config, check out the link:./ansible/configs/ocp-workshop/README.adoc[README] file

== Cleanup (Reference Only)

NOTE: S3 Buckets are now part of a CloudFormation stack and are properly deleted before the stack in the destroy playbooks.

* S3 Bucket
- (Reference Only) An S3 bucket is used to back the Docker registry. AWS will not let you delete a
non-empty S3 bucket, so you must do this manually. The `aws` CLI makes this
easy:
+
----
aws s3 rm s3://bucket-name --recursive
----

- Your bucket name is named `{{ env_type }}-{{ guid }}`. So, in the case of a
`bu-workshop` environment where you provided the `guid` of "Atlanta", your S3
bucket is called `bu-workshop-atlanta`.

* CloudFormation Template
- If `destroy_env.yml` playbook failed, just go into your AWS account to the CloudFormation section in the region where
you provisioned, find the deployed stack, and delete it.

* SSH config
- This Ansible playbook creates a SSH config for the environment you are provisioning. It is created in `ansible/workdir` directory. The file is then used by ansible to access the environment.

== Troubleshooting

Information will be added here as problems are solved. So far it's pretty
vanilla, but quite slow. Expect at least 40 min for a full OpenShift deployment. Some configs are faster.

=== Use stable tags
Configs are tested on a regular basis. Once it works, a release (tag) for this config is created. You can list all tag by running `git tag -l`.

Make sure you are using a stable tag for the config you want to provision. For example, if you are provisioning ocp-workshop, use a tag like `ocp-workshop-prod-1.8`. This is done by simply running:

----
git checkout ocp-workshop-prod-1.8
----

=== EC2 instability
It has been seen that, on occasion, EC2 is generally unstable. This manifests in
various ways:

* The autoscaling group for the nodes takes an extremely long time to deploy, or
  will never complete deploying

* Individual EC2 instances may have terrible performance, which can result in
  nodes that seem to be "hung" despite being reachable via SSH.

There is not much that can be done in this circumstance besides starting over
(in a different region).

=== Re-Running
While Ansible is idempotent and supports being re-run, there are some known
issues with doing so. Specifically:

* You should skip the tag `nfs_tasks` with the `--skip-tags` option if you
  re-run the playbook **after** the NFS server has been provisioned and
  configured. The playbook is not safe for re-run and will fail.

== FAQ

* Is this a replacement for openshift-ansible playbook ? Why ?

No! First, this repository is a set of playbooks and roles, it is not only about OpenShift and AWS. A run is organized in several steps: pre_infra, infra, post_infra, pre_software, software, post_software. If  you choose to use a config that installs OpenShift, it will **actually use** the openshift-ansible playbook, also known as `byo/config.yml`, during the Software step.

			@@ -3,17 +3,14 @@

			= Ansible Agnostic Deployer

			Ansible Agnostic Deployer (AAD) is a 6 Stage Cloud Deployer for deploying application
			environments, labs, workshops etc. Well designed environments, called _configs_,
			can be easily abstracted to allow deployment to multiple different Public and
			Private Clouds including AWS, Azure, and others.
			Ansible Agnostic Deployer (AAD) is a 6 Stage Cloud Deployer for deploying application environments, labs, workshops etc.
			Well designed environments, called _configs_, can be easily abstracted to allow deployment to multiple different Public and Private Clouds including AWS, Azure, and others.

			image::docs/images/agnosticd_flow.png[width=100%]


			This document gives a brief overview of the project function, and structure. It
			also provides a guide to the more comprehensive documentation set provided in
			the `docs/` direcorry.
			This document gives a brief overview of the project function, and structure.
			It also provides a guide to the more comprehensive documentation set provided in the `docs/` directory.

			== Basic Structure

			@@ -27,7 +24,7 @@
			* `./ansible/main.yml` The entry point for a deployment
			* `./ansible/configs` Home to the _configs_ to deploy

			The Contributors Guides explore the relevant structures in more detail:
			The Contributors Guides explore the relevant structures in significantly more detail:

			* link:docs/Creating_a_config.adoc[Creating a Config]
			* link:docs/Creating_a_cloud_deployer.adoc[Creating a Cloud Deployer]
			@@ -38,8 +35,7 @@


			AAD deployments start by invoking a common `main.yml` with environmental
			variables identifying the _config_ and the cloud platform to deploy plus other
			meta-data.
			variables identifying the _config_ and the cloud platform to deploy plus other meta-data.

			e.g. `ansible-playbook main.yml -e "env_type=three-tier-app cloud_provider=aws"`

			@@ -54,115 +50,18 @@
			- import_playbook: "configs/{{ env_type }}/post_software.yml"
			----

			For _config_ developers the above stages provide 5 _hooks_ for customizing the
			configuration of your environemnet and 1 _hook_ for customizing it for one or
			more cloud providers (e.g. AWS, Azure, etc).
			For _config_ developers the above stages provide 5 _hooks_ for customizing the configuration of your environment and 1 _hook_ for customizing it for one or more cloud providers (e.g. AWS, Azure, etc).

			An _Example config_ is provided by `ansible/configs/just-some-nodes-example`

			==== Stage 0 `pre_infra.yml`


			In this stage AAD is the entry playbook and is typical used for setting up any
			infrastucture etc prior to launching a cloud deployemnt. Typical tasks would include:

			* Creating necessary ssh keys
			* Moving any ssh keys into place, setting permissions etc
			* Creating any payloads to be used in later stages e.g. repo files etc
			* Ensuring cloud credentials are avaialble


			==== Stage 1 Cloud Provider Deploy

			This stage is unique in the flow in that the _config_ creator doesn't supply a
			playbook but typically has to provide cloud specfic configuration data.

			Clouds are selected via the value of the `cloud_provider` variable and supported
			clouds can be found in `ansible/cloud_providers`. Currently supported are:

			* Amazon Web Services (AWS)
			* Microsfoft Azure

			Example: AWS configs use CloudFormations templates to deploy their infrastructure
			so this can be provied

			[NOTE]
			[TIP]
			====
			A Cloud Creators document exists to faciliate adding further clouds to AAD. Wish
			list items include:

			* OpenShift
			* OpenStack
			* Google Cloud Engine (GCE)
			To understand the 6 stages in depth and how to create your own _config_ or copy and modify an existing _config_ please see the link:docs/Creating_a_config.adoc[Creating a Config Developers Guide] for more detail.
			====


			==== Stage 2 `post_infra.yml`

			In this stage AAD

			==== Stage 3 `pre_software.yml`

			At this point the infrastucure should be up and running but typically in a totally
			unconfugured state.

			Typical tasks:

			* Setup yum repos or equivilent
			* `ssh` key housekeeping - for example inserting additional keys and configuration
			* Prepare `bastion` hosts or `jumpboxes`


			==== Stage 4 `software.yml`

			In this stage AAD

			==== Stage 5 `post_software.yml`


			== Overview of a _Config_

			Documnetation: `docs/Creating_congfigs
			_Configs_ are located in the `ansible/configs/` directory

			[source,bash]
			----
			README.adoc linklight ocp-ha-disconnected-lab quay-enterprise
			ans-tower-lab linklight-demo ocp-ha-lab rhte-ansible-net
			ansible-cicd-lab linklight-engine ocp-implementation-lab rhte-lb
			ansible-provisioner linklight-foundations ocp-multi-cloud-example rhte-oc-cluster-vms
			archive linklight-networking ocp-storage-cns rhte-ocp-workshop
			bu-workshop linklight-networking-all ocp-workloads simple-multi-cloud
			just-some-nodes-example ocp-clientvm ocp-workshop three-tier-app
			lightbulb ocp-gpu-single-node openshift-demos
			----
			_Above configs subject to change over time_

			A typical _Config_ is


			[source,bash]
			----
			three-tier-app
			├── README.adoc
			├── destroy_env.yml
			├── env_vars.yml
			├── files
			├── post_infra.yml
			├── post_software.yml
			├── pre_infra.yml
			├── pre_software.yml
			└── software.yml
			----




			== Prerequisites

			There are several prerequisites for using this repository, scripted and detailed
			instructions for usage are available in the following the
			link:./docs/Preparing_your_workstation.adoc[Preparing Your Workstation] document.
			There are several prerequisites for using this repository, scripted and detailed instructions for usage are available in the following the link:./docs/Preparing_your_workstation.adoc[Preparing Your Workstation] document.
			[estimated effort 5-10 minutes]

			* Software required on provisioning workstation:
			@@ -197,11 +96,9 @@
			`_vars` and `_secret_vars`. The `example_secret_vars` file shows the format for
			what to put in your `CONFIGNAME_secret_vars` file.


			== Running the Ansible Playbooks

			Once you have installed your prerequisites and have configured all settings and
			files, simply run Ansible like so:
			Once you have installed your prerequisites and have configured all settings and files, simply run Ansible like so:

			----
			ansible-playbook -i 127.0.0.1, ansible/main.yml -e "env_type=config-name" -e "aws_region=ap-southeast-2" -e "guid=youruniqueidentifier"
			@@ -214,8 +111,7 @@

			== Cleanup (Reference Only)

			NOTE: S3 Buckets are now part of a CloudFormation stack and are properly deleted before the stack in the destroy playbooks.

			NOTE: S3 Buckets are now part of a CloudFormation stack and are properly deleted before the stack in the destroy playbooks.
			* S3 Bucket
			- (Reference Only) An S3 bucket is used to back the Docker registry. AWS will not let you delete a
			non-empty S3 bucket, so you must do this manually. The `aws` CLI makes this

New file
			@@ -0,0 +1,278 @@
			:toc2:
			image::https://travis-ci.org/sborenst/ansible_agnostic_deployer.svg?branch=development[link="https://travis-ci.org/sborenst/ansible_agnostic_deployer"]

			= Ansible Agnostic Deployer

			Ansible Agnostic Deployer (AAD) is a 6 Stage Cloud Deployer for deploying application
			environments, labs, workshops etc. Well designed environments, called _configs_,
			can be easily abstracted to allow deployment to multiple different Public and
			Private Clouds including AWS, Azure, and others.

			image::docs/images/agnosticd_flow.png[width=100%]


			This document gives a brief overview of the project function, and structure. It
			also provides a guide to the more comprehensive documentation set provided in
			the `docs/` direcorry.

			== Basic Structure

			The repository contains various Ansible playbooks, templates, and other support
			files used to provision different software (OpenShift, Ansible Tower, ...) onto
			Cloud Infrastructure (AWS, Ravello, ...). The key files and directories include:


			* `./docs/` Start here
			* `./ansible` The execution environment
			* `./ansible/main.yml` The entry point for a deployment
			* `./ansible/configs` Home to the _configs_ to deploy

			The Contributors Guides explore the relevant structures in more detail:

			* link:docs/Creating_a_config.adoc[Creating a Config]
			* link:docs/Creating_a_cloud_deployer.adoc[Creating a Cloud Deployer]

			== Overview of Ansible Agnostic Deployer Flow

			image::docs/images/agnosticd_flow.png[width=100%]


			AAD deployments start by invoking a common `main.yml` with environmental
			variables identifying the _config_ and the cloud platform to deploy plus other
			meta-data.

			e.g. `ansible-playbook main.yml -e "env_type=three-tier-app cloud_provider=aws"`

			.*Simplified execution flow of `main.yml`
			[source,bash]
			----
			- import_playbook: "configs/{{ env_type }}/pre_infra.yml"
			- import_playbook: "cloud_providers/{{ cloud_provider }}_infrastructure_deployment.yml"
			- import_playbook: "configs/{{ env_type }}/post_infra.yml"
			- import_playbook: "configs/{{ env_type }}/pre_software.yml"
			- import_playbook: "configs/{{ env_type }}/software.yml"
			- import_playbook: "configs/{{ env_type }}/post_software.yml"
			----

			For _config_ developers the above stages provide 5 _hooks_ for customizing the
			configuration of your environemnet and 1 _hook_ for customizing it for one or
			more cloud providers (e.g. AWS, Azure, etc).

			An _Example config_ is provided by `ansible/configs/just-some-nodes-example`

			==== Stage 0 `pre_infra.yml`


			In this stage AAD is the entry playbook and is typical used for setting up any
			infrastucture etc prior to launching a cloud deployemnt. Typical tasks would include:

			* Creating necessary ssh keys
			* Moving any ssh keys into place, setting permissions etc
			* Creating any payloads to be used in later stages e.g. repo files etc
			* Ensuring cloud credentials are avaialble


			==== Stage 1 Cloud Provider Deploy

			This stage is unique in the flow in that the _config_ creator doesn't supply a
			playbook but typically has to provide cloud specfic configuration data.

			Clouds are selected via the value of the `cloud_provider` variable and supported
			clouds can be found in `ansible/cloud_providers`. Currently supported are:

			* Amazon Web Services (AWS)
			* Microsfoft Azure

			Example: AWS configs use CloudFormations templates to deploy their infrastructure
			so this can be provied

			[NOTE]
			====
			A Cloud Creators document exists to faciliate adding further clouds to AAD. Wish
			list items include:

			* OpenShift
			* OpenStack
			* Google Cloud Engine (GCE)
			====


			==== Stage 2 `post_infra.yml`

			In this stage AAD

			==== Stage 3 `pre_software.yml`

			At this point the infrastucure should be up and running but typically in a totally
			unconfugured state.

			Typical tasks:

			* Setup yum repos or equivilent
			* `ssh` key housekeeping - for example inserting additional keys and configuration
			* Prepare `bastion` hosts or `jumpboxes`


			==== Stage 4 `software.yml`

			In this stage AAD

			==== Stage 5 `post_software.yml`


			== Overview of a _Config_

			Documnetation: `docs/Creating_congfigs
			_Configs_ are located in the `ansible/configs/` directory

			[source,bash]
			----
			README.adoc linklight ocp-ha-disconnected-lab quay-enterprise
			ans-tower-lab linklight-demo ocp-ha-lab rhte-ansible-net
			ansible-cicd-lab linklight-engine ocp-implementation-lab rhte-lb
			ansible-provisioner linklight-foundations ocp-multi-cloud-example rhte-oc-cluster-vms
			archive linklight-networking ocp-storage-cns rhte-ocp-workshop
			bu-workshop linklight-networking-all ocp-workloads simple-multi-cloud
			just-some-nodes-example ocp-clientvm ocp-workshop three-tier-app
			lightbulb ocp-gpu-single-node openshift-demos
			----
			_Above configs subject to change over time_

			A typical _Config_ is


			[source,bash]
			----
			three-tier-app
			├── README.adoc
			├── destroy_env.yml
			├── env_vars.yml
			├── files
			├── post_infra.yml
			├── post_software.yml
			├── pre_infra.yml
			├── pre_software.yml
			└── software.yml
			----




			== Prerequisites

			There are several prerequisites for using this repository, scripted and detailed
			instructions for usage are available in the following the
			link:./docs/Preparing_your_workstation.adoc[Preparing Your Workstation] document.
			[estimated effort 5-10 minutes]

			* Software required on provisioning workstation:
			- https://www.python.org[Python] version 2.7.x (3.x untested and may not work)
			- http://docs.pythonboto.org[Python Boto] version 2.41 or greater
			- http://github.com[Git] any version would do.
			- https://github.com/ansible/ansible[Ansible] version 2.1.2 or greater
			with version 1.11.32
			* AWS
			** https://s3.amazonaws.com/aws-cli/awscli-bundle.zip[awscli bundle] tested
			** Credentials and Policies:
			*** AWS user account with credentials to provision resources
			*** A route53 link:http://docs.aws.amazon.com/Route53/latest/DeveloperGuide/CreatingHostedZone.html[public hosted zone]
			is required for the scripts to create the various DNS entries for the
			resources it creates. The "HostedZoneId" will need to be provided in the
			variable file.
			*** An EC2 SSH keypair should be created in advance and you should save the key
			file to your system. (command line instructions can be found in the
			link:./docs/Preparing_your_workstation.adoc[Preparing Your Workstation] document.)

			== Standard Configurations

			* Several "Standard Configurations" are included in this repository.
			* A "Standard Configurations" or "Config" are a predefined deployment examples
			that can be used or copied and modified by anyone.
			* A "Config" will include all the files, templates, pre and post playbooks that
			a deployment example requires to be deployed.
			* "Config" specific Variable files will be included in the "Config" directory as
			well.

			NOTE: Until we implement using Ansible Vault, each "Config" has two vars files
			`_vars` and `_secret_vars`. The `example_secret_vars` file shows the format for
			what to put in your `CONFIGNAME_secret_vars` file.


			== Running the Ansible Playbooks

			Once you have installed your prerequisites and have configured all settings and
			files, simply run Ansible like so:

			----
			ansible-playbook -i 127.0.0.1, ansible/main.yml -e "env_type=config-name" -e "aws_region=ap-southeast-2" -e "guid=youruniqueidentifier"

			----

			NOTE: Be sure to exchange `guid` for a sensible prefix of your choosing.

			For "opentlc-shared" standard config, check out the link:./ansible/configs/ocp-workshop/README.adoc[README] file

			== Cleanup (Reference Only)

			NOTE: S3 Buckets are now part of a CloudFormation stack and are properly deleted before the stack in the destroy playbooks.

			* S3 Bucket
			- (Reference Only) An S3 bucket is used to back the Docker registry. AWS will not let you delete a
			non-empty S3 bucket, so you must do this manually. The `aws` CLI makes this
			easy:
			+
			----
			aws s3 rm s3://bucket-name --recursive
			----

			- Your bucket name is named `{{ env_type }}-{{ guid }}`. So, in the case of a
			`bu-workshop` environment where you provided the `guid` of "Atlanta", your S3
			bucket is called `bu-workshop-atlanta`.

			* CloudFormation Template
			- If `destroy_env.yml` playbook failed, just go into your AWS account to the CloudFormation section in the region where
			you provisioned, find the deployed stack, and delete it.

			* SSH config
			- This Ansible playbook creates a SSH config for the environment you are provisioning. It is created in `ansible/workdir` directory. The file is then used by ansible to access the environment.

			== Troubleshooting

			Information will be added here as problems are solved. So far it's pretty
			vanilla, but quite slow. Expect at least 40 min for a full OpenShift deployment. Some configs are faster.

			=== Use stable tags
			Configs are tested on a regular basis. Once it works, a release (tag) for this config is created. You can list all tag by running `git tag -l`.

			Make sure you are using a stable tag for the config you want to provision. For example, if you are provisioning ocp-workshop, use a tag like `ocp-workshop-prod-1.8`. This is done by simply running:

			----
			git checkout ocp-workshop-prod-1.8
			----

			=== EC2 instability
			It has been seen that, on occasion, EC2 is generally unstable. This manifests in
			various ways:

			* The autoscaling group for the nodes takes an extremely long time to deploy, or
			will never complete deploying

			* Individual EC2 instances may have terrible performance, which can result in
			nodes that seem to be "hung" despite being reachable via SSH.

			There is not much that can be done in this circumstance besides starting over
			(in a different region).

			=== Re-Running
			While Ansible is idempotent and supports being re-run, there are some known
			issues with doing so. Specifically:

			* You should skip the tag `nfs_tasks` with the `--skip-tags` option if you
			re-run the playbook after the NFS server has been provisioned and
			configured. The playbook is not safe for re-run and will fail.

			== FAQ

			* Is this a replacement for openshift-ansible playbook ? Why ?

			No! First, this repository is a set of playbooks and roles, it is not only about OpenShift and AWS. A run is organized in several steps: pre_infra, infra, post_infra, pre_software, software, post_software. If you choose to use a config that installs OpenShift, it will actually use the openshift-ansible playbook, also known as `byo/config.yml`, during the Software step.