= OpenShift Ansible AWS Provisioner
This repository contains various Ansible playbooks, templates, and other support
files used to provision OpenShift environments onto AWS.

== Prerequisites

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

* AWS 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:./Preparing_your_workstation.adoc[Preparing Your Workstation] document.)
* Software required on provisioning workstation:
- [Python](https://www.python.org) version 2.7.x (3.x untested and may not work)
- [Python Boto](http://docs.pythonboto.org) version 2.41 or greater
- [Git](http://github.com) any version would do.
- [Ansible](https://github.com/ansible/ansible) version 2.1.2 or greater
- [awscli bundle](https://s3.amazonaws.com/aws-cli/awscli-bundle.zip) tested
 with version 1.11.32


== 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/opentlc-shared/README.adoc[README] file

== Cleanup

* S3 Bucket
- 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
- 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 script places entries into your `~/.ssh/config`. It is recommended
that you remove them once you are done with your environment.

== Troubleshooting

Information will be added here as problems are solved. So far it's pretty
vanilla, but quite slow. Expect at least an hour for deployment, if not two or
more if you are far from the system(s).

=== 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.

* You may also wish to skip the tag `bastion_proxy_config` when re-running, as
  the tasks associated with this play will re-write the same entries to your SSH
  config file, which could result in hosts becoming unexpectedly unreachable.