doc tweak

Bowe Strickland

2020-03-09 cb0b2619b9e8271f5a9b2f9b1a6b8d66ced3af9a

 README.adoc

@@ -1,221 +1,62 @@
image::https://travis-ci.org/sborenst/ansible_agnostic_deployer.svg?branch=development[link="https://travis-ci.org/sborenst/ansible_agnostic_deployer"]
== Overview

= Ansible Agnostic Deployer
Ansible Agnostic Deployer, AKA *AAD*, AKA *AgnosticD*, is a fully automated 2
 Phase deployer for building and deploying everything from basic infrastructure
  to fully configured running application environments running on either public
   Cloud Providers or OpenShift clusters.

Ansible Agnostic Deployer 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.

*AgnosticD* is not an OpenShift Deployer, though it can and does that, it is
 however also a deployer that just happens to be used to deploy a lot of
  OpenShift and OpenShift workloads, amongst other things.

=== Make your first Deployment

Check out this link:https://www.youtube.com/watch?v=lfHYwXJhKB0[Video Introduction to deploying with Ansible AgnosticD]!

There are many link:./ansible/configs[configs] you can choose from, here are three
 that you can start with and modify to fit your needs:

* link:./ansible/configs/three-tier-app/README.adoc[Three Tier App] - Relatively
 simple environment, which deploys by default just a bunch of Linux hosts ready
  to be configured.

* link:./ansible/configs/ocp-workshop/README.adoc[OCP Workshop] - If a fully
 installed OpenShift Cluster is what you are looking for then take a look here.

* link:./ansible/roles/ocp-workload-3scale-multitenant/readme.adoc[OpenShift 3Scale
 Deployment] - Want to deploy a workload onto your existing OpenShift Cluster?
  or local instance running on your laptop?  3Scale is an example of one of
   around *30* OpenShift workloads ready to go.

=== How AgnosticD Deploys

* For OpenShift _Workloads_ *AgnosticD* executes an ansible *role* against an
 existing OpenShift cluster. Roles can be found link:./ansible/roles/[here] and
  begin `ocp-workload-*`.

* For _Configs_ each contain 5 deployment playbooks and supporting files executed
 in sequence and combined with a Cloud Provider to deploy basic infrastructure
  through to fully configured applications.

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

=== Getting Started

This document gives a brief overview of the project structure and a guide to the
more comprehensive documentation set provides
The accompanying documentation explains how to achieve all this, extend it and
 add both your own environments, hereafter called _configs_ and a lot lot more.
Well designed _configs_, can be easily abstracted to allow deployment to multiple
 different Public and Private Clouds including AWS, Azure, and others.

* link:./docs/[The Documentation Set] Start Here
* link:./ansible/[./ansible] The working ansible directory
** link:./ansible/main.yml[main.yml] The main entry point for `ansible-playbook`
* link:./ansible/roles[Roles directory] Home to the `ocp-workload-*` roles
* link:./ansible/configs[Configs directory] Home to the _Configs_

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

:toc2::

== Structure


[source,bash]
----
.
├── LICENSE
├── README.adoc
├── ansible/
├── ansible.cfg
├── docs/
├── pytest.ini
├── requirements.txt
├── scripts/
├── setup.py
├── test-requirements.txt
├── test_oc.yml
├── tests/
└── tox.ini
----


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

== Overview of AgnosticD Flow

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


AgnosticD 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`



==== Stage 0 `pre_infra.yml`
==== Stage 1 Cloud Provider Deploy

In this stage AgnosticD 



== 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             # README Descri
├── 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. 
* link:docs/Creating_an_OpenShift_Workload.adoc[Creating an OpenShift Workload Guide]
* link:docs/Creating_a_config.adoc[Creating a Config Guide]
// * link:docs/Creating_a_cloud_deployer.adoc[Creating a Cloud Deployer Guide]