= Ansible Agnostic Deployer
|
This repository contains various Ansible playbooks, templates, and other support
|
files used to provision different software (OpenShift, Ansible Tower, ...) onto Cloud Infrastructure (AWS, Ravello, ...).
|
|
== 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.
|
