| commit | author | age | ||
| 062d29 | 1 | = OpenShift Ansible AWS Provisioner |
| S | 2 | This repository contains various Ansible playbooks, templates, and other support |
| 3 | files used to provision OpenShift environments onto AWS. | |
| 4 | ||
| 5 | == Prerequisites | |
| 6 | ||
| 7 | There are several prerequisites for using this repository, scripted and detailed | |
| 8 | instructions for usage are available in the following the | |
| 9 | link:./Preparing_your_workstation.adoc[Preparing Your Workstation] document. | |
| 10 | [estimated effort 5-10 minutes] | |
| 11 | ||
| 12 | * AWS Credentials and Policies: | |
| 13 | - AWS user account with credentials to provision resources | |
| 14 | - A route53 link:http://docs.aws.amazon.com/Route53/latest/DeveloperGuide/CreatingHostedZone.html[public hosted zone] | |
| 15 | is required for the scripts to create the various DNS entries for the | |
| 16 | resources it creates. The "HostedZoneId" will need to be provided in the | |
| 17 | variable file. | |
| 18 | - An EC2 SSH keypair should be created in advance and you should save the key | |
| 19 | file to your system. (command line instructions can be found in the | |
| 20 | link:./Preparing_your_workstation.adoc[Preparing Your Workstation] document.) | |
| 21 | * Software required on provisioning workstation: | |
| 22 | - [Python](https://www.python.org) version 2.7.x (3.x untested and may not work) | |
| 23 | - [Python Boto](http://docs.pythonboto.org) version 2.41 or greater | |
| 24 | - [Git](http://github.com) any version would do. | |
| 25 | - [Ansible](https://github.com/ansible/ansible) version 2.1.2 or greater | |
| 26 | - [awscli bundle](https://s3.amazonaws.com/aws-cli/awscli-bundle.zip) tested | |
| 27 | with version 1.11.32 | |
| 28 | ||
| 29 | ||
| 30 | == Standard Configurations | |
| 31 | ||
| 32 | * Several "Standard Configurations" are included in this repository. | |
| 33 | * A "Standard Configurations" or "Config" are a predefined deployment examples | |
| 34 | that can be used or copied and modified by anyone. | |
| 35 | * A "Config" will include all the files, templates, pre and post playbooks that | |
| 36 | a deployment example requires to be deployed. | |
| 37 | * "Config" specific Variable files will be included in the "Config" directory as | |
| 38 | well. | |
| 39 | ||
| 40 | NOTE: Until we implement using Ansible Vault, each "Config" has two vars files | |
| 41 | `_vars` and `_secret_vars`. The `example_secret_vars` file shows the format for | |
| 42 | what to put in your `CONFIGNAME_secret_vars` file. | |
| 43 | ||
| 44 | ||
| 45 | == Running the Ansible Playbooks | |
| 46 | ||
| 47 | Once you have installed your prerequisites and have configured all settings and | |
| 48 | files, simply run Ansible like so: | |
| 49 | ||
| 50 | ---- | |
| 51 | ansible-playbook -i 127.0.0.1 ansible/main.yml -e "env_type=config-name" -e "aws_region=ap-southeast-2" -e "guid=youruniqueidentifier" | |
| 52 | ||
| 53 | ---- | |
| 54 | ||
| 55 | NOTE: Be sure to exchange `guid` for a sensible prefix of your choosing. | |
| 56 | ||
| f18240 | 57 | For "opentlc-shared" standard config, check out the link:./ansible/configs/opentlc-shared/README.adoc[README] file |
| 062d29 | 58 | |
| S | 59 | == Cleanup |
| 60 | ||
| 61 | * S3 Bucket | |
| 62 | - An S3 bucket is used to back the Docker registry. AWS will not let you delete a | |
| 63 | non-empty S3 bucket, so you must do this manually. The `aws` CLI makes this | |
| 64 | easy: | |
| 65 | + | |
| 66 | ---- | |
| 67 | aws s3 rm s3://bucket-name --recursive | |
| 68 | ---- | |
| 69 | ||
| 70 | - Your bucket name is named `{{ env_type }}-{{ guid }}`. So, in the case of a | |
| 71 | `bu-workshop` environment where you provided the `guid` of "Atlanta", your S3 | |
| 72 | bucket is called `bu-workshop-atlanta`. | |
| 73 | ||
| 74 | * CloudFormation Template | |
| 75 | - Just go into your AWS account to the CloudFormation section in the region where | |
| 76 | you provisioned, find the deployed stack, and delete it. | |
| 77 | ||
| 78 | * SSH config | |
| 79 | - This Ansible script places entries into your `~/.ssh/config`. It is recommended | |
| 80 | that you remove them once you are done with your environment. | |
| 81 | ||
| 82 | == Troubleshooting | |
| 83 | ||
| 84 | Information will be added here as problems are solved. So far it's pretty | |
| 85 | vanilla, but quite slow. Expect at least an hour for deployment, if not two or | |
| 86 | more if you are far from the system(s). | |
| 87 | ||
| 88 | === EC2 instability | |
| 89 | It has been seen that, on occasion, EC2 is generally unstable. This manifests in | |
| 90 | various ways: | |
| 91 | ||
| 92 | * The autoscaling group for the nodes takes an extremely long time to deploy, or | |
| 93 | will never complete deploying | |
| 94 | ||
| 95 | * Individual EC2 instances may have terrible performance, which can result in | |
| 96 | nodes that seem to be "hung" despite being reachable via SSH. | |
| 97 | ||
| 98 | There is not much that can be done in this circumstance besides starting over | |
| 99 | (in a different region). | |
| 100 | ||
| 101 | === Re-Running | |
| 102 | While Ansible is idempotent and supports being re-run, there are some known | |
| 103 | issues with doing so. Specifically: | |
| 104 | ||
| 105 | * You should skip the tag `nfs_tasks` with the `--skip-tags` option if you | |
| 106 | re-run the playbook **after** the NFS server has been provisioned and | |
| 107 | configured. The playbook is not safe for re-run and will fail. | |
| 108 | ||
| 109 | * You may also wish to skip the tag `bastion_proxy_config` when re-running, as | |
| 110 | the tasks associated with this play will re-write the same entries to your SSH | |
| 111 | config file, which could result in hosts becoming unexpectedly unreachable. | |
