view | history | commit | commitdiff
Patrick T. Rutledge III
2018-11-05 bf2be91407fc8d4eb26d0a38472710ccf3697452
commit | author | age
878874 1 :toc2:
b45606 2 image::https://travis-ci.org/sborenst/ansible_agnostic_deployer.svg?branch=development[link="https://travis-ci.org/sborenst/ansible_agnostic_deployer"]
GC 3
d90850 4 = Ansible Agnostic Deployer
894780 5
37136f 6 Ansible Agnostic Deployer (AAD) is a 6 Stage Cloud Deployer for deploying application
894780 7 environments, labs, workshops etc. Well designed environments, called _configs_,
109188 8 can be easily abstracted to allow deployment to multiple different Public and 
894780 9 Private Clouds including AWS, Azure, and others.
T 10
11 image::docs/images/agnosticd_flow.png[width=100%]
12
13
878874 14 This document gives a brief overview of the project function, and structure. It
T 15 also provides a guide to the more comprehensive documentation set provided in 
16 the `docs/` direcorry.
17
18 == Basic Structure
19
20 The repository contains various Ansible playbooks, templates, and other support
21 files used to provision different software (OpenShift, Ansible Tower, ...) onto 
22 Cloud Infrastructure (AWS, Ravello, ...). The key files and directories include:
109188 23
T 24
37136f 25 * `./docs/` Start here
878874 26 * `./ansible` The execution environment
T 27 * `./ansible/main.yml` The entry point for a deployment
28 * `./ansible/configs` Home to the _configs_ to deploy
109188 29
37136f 30 The Contributors Guides explore the relevant structures in more detail:
894780 31
37136f 32 * link:docs/Creating_a_config.adoc[Creating a Config]
T 33 * link:docs/Creating_a_cloud_deployer.adoc[Creating a Cloud Deployer]
894780 34
37136f 35 == Overview of Ansible Agnostic Deployer Flow
894780 36
T 37 image::docs/images/agnosticd_flow.png[width=100%]
38
39
37136f 40 AAD deployments start by invoking a common `main.yml` with environmental
894780 41 variables identifying the _config_ and the cloud platform to deploy plus other 
T 42 meta-data.
43
37136f 44 e.g. `ansible-playbook main.yml -e "env_type=three-tier-app cloud_provider=aws"`
894780 45
37136f 46 .*Simplified execution flow of `main.yml`
T 47 [source,bash]
48 ----
49 - import_playbook: "configs/{{ env_type }}/pre_infra.yml"
50 - import_playbook: "cloud_providers/{{ cloud_provider }}_infrastructure_deployment.yml"
51 - import_playbook: "configs/{{ env_type }}/post_infra.yml"
52 - import_playbook: "configs/{{ env_type }}/pre_software.yml"
53 - import_playbook: "configs/{{ env_type }}/software.yml"
54 - import_playbook: "configs/{{ env_type }}/post_software.yml"
55 ----
894780 56
37136f 57 For _config_ developers the above stages provide 5 _hooks_ for customizing the 
T 58 configuration of your environemnet and 1 _hook_ for customizing it for one or
59 more cloud providers (e.g. AWS, Azure, etc).
894780 60
e17520 61 An _Example config_ is provided by `ansible/configs/just-some-nodes-example`
T 62
894780 63 ==== Stage 0 `pre_infra.yml`
e17520 64
T 65
66 In this stage *AAD* is the entry playbook and is typical used for setting up any
67 infrastucture etc prior to launching a cloud deployemnt. Typical tasks would include:
68
69 * Creating necessary ssh keys
70 * Moving any ssh keys into place, setting permissions etc
71 * Creating any payloads to be used in later stages e.g. repo files etc
72 * Ensuring cloud credentials are avaialble 
73
74
894780 75 ==== Stage 1 Cloud Provider Deploy
T 76
e17520 77 This stage is unique in the flow in that the _config_ creator doesn't supply a 
T 78 playbook but typically has to provide cloud specfic configuration data.
894780 79
e17520 80 Clouds are selected via the value of the `cloud_provider` variable and supported
T 81 clouds can be found in `ansible/cloud_providers`. Currently supported are:
82
83 * Amazon Web Services (AWS)
84 * Microsfoft Azure
85
86 Example: *AWS* configs use CloudFormations templates to deploy their infrastructure 
87 so this can be provied 
88
89 [NOTE]
90 ====
91 A Cloud Creators document exists to faciliate adding further clouds to *AAD*. Wish
92 list items include:
93
94 * OpenShift
95 * OpenStack
96 * Google Cloud Engine (GCE)
97 ====
98
99
100 ==== Stage 2 `post_infra.yml`
101
102 In this stage *AAD*
103
104 ==== Stage 3 `pre_software.yml`
105
106 At this point the infrastucure should be up and running but typically in a totally
107 unconfugured state. 
108
109 Typical tasks:
110
111 * Setup yum repos or equivilent
112 * `ssh` key housekeeping - for example inserting additional keys and configuration
113 * Prepare `bastion` hosts or `jumpboxes`
114
115
116 ==== Stage 4 `software.yml`
117
118 In this stage *AAD*
119
120 ==== Stage 5 `post_software.yml`
894780 121
T 122
123 == Overview of a _Config_
124
109188 125 Documnetation: `docs/Creating_congfigs
T 126 _Configs_ are located in the `ansible/configs/` directory
127
128 [source,bash]
129 ----
130 README.adoc              linklight                 ocp-ha-disconnected-lab   quay-enterprise
131 ans-tower-lab            linklight-demo            ocp-ha-lab                rhte-ansible-net
132 ansible-cicd-lab         linklight-engine          ocp-implementation-lab    rhte-lb
133 ansible-provisioner      linklight-foundations     ocp-multi-cloud-example   rhte-oc-cluster-vms
134 archive                  linklight-networking      ocp-storage-cns           rhte-ocp-workshop
135 bu-workshop              linklight-networking-all  ocp-workloads             simple-multi-cloud
136 just-some-nodes-example  ocp-clientvm              ocp-workshop              three-tier-app
137 lightbulb                ocp-gpu-single-node       openshift-demos
138 ----
139 _Above configs subject to change over time_
140
141 A typical _Config_ is 
142
143
144 [source,bash]
145 ----
146 three-tier-app
878874 147 ├── README.adoc             
109188 148 ├── destroy_env.yml
T 149 ├── env_vars.yml
150 ├── files
151 ├── post_infra.yml
152 ├── post_software.yml
153 ├── pre_infra.yml
154 ├── pre_software.yml
155 └── software.yml
156 ----
157
158
159
894780 160
062d29 161 == Prerequisites
S 162
163 There are several prerequisites for using this repository, scripted and detailed
164  instructions for usage are available in the following the
a0eb56 165   link:./docs/Preparing_your_workstation.adoc[Preparing Your Workstation] document.
062d29 166    [estimated effort 5-10 minutes]
S 167
168 * Software required on provisioning workstation:
70f46b 169 - https://www.python.org[Python] version 2.7.x (3.x untested and may not work)
E 170 - http://docs.pythonboto.org[Python Boto] version 2.41 or greater
171 - http://github.com[Git] any version would do.
172 - https://github.com/ansible/ansible[Ansible] version 2.1.2 or greater
400a88 173  with version 1.11.32
GC 174 * AWS
175 ** https://s3.amazonaws.com/aws-cli/awscli-bundle.zip[awscli bundle] tested
176 ** Credentials and Policies:
177 *** AWS user account with credentials to provision resources
178 *** A route53 link:http://docs.aws.amazon.com/Route53/latest/DeveloperGuide/CreatingHostedZone.html[public hosted zone]
062d29 179   is required for the scripts to create the various DNS entries for the
400a88 180   resources it creates. The "HostedZoneId" will need to be provided in the
GC 181   variable file.
182 *** An EC2 SSH keypair should be created in advance and you should save the key
062d29 183     file to your system. (command line instructions can be found in the
a0eb56 184        link:./docs/Preparing_your_workstation.adoc[Preparing Your Workstation] document.)
062d29 185
S 186 == Standard Configurations
187
188 * Several "Standard Configurations" are included in this repository.
189 * A "Standard Configurations" or "Config" are a predefined deployment examples
190  that can be used or copied and modified by anyone.
191 * A "Config" will include all the files, templates, pre and post playbooks that
192  a deployment example requires to be deployed.
193 * "Config" specific Variable files will be included in the "Config" directory as
194  well.
195
196 NOTE: Until we implement using Ansible Vault, each "Config" has two vars files
197  `_vars` and `_secret_vars`. The `example_secret_vars` file shows the format for
198   what to put in your `CONFIGNAME_secret_vars` file.
199
200
201 == Running the Ansible Playbooks
202
203 Once you have installed your prerequisites and have configured all settings and
204 files, simply run Ansible like so:
205
206 ----
47b910 207 ansible-playbook -i 127.0.0.1, ansible/main.yml -e "env_type=config-name" -e "aws_region=ap-southeast-2" -e "guid=youruniqueidentifier"
062d29 208
S 209 ----
210
211 NOTE: Be sure to exchange `guid` for a sensible prefix of your choosing.
212
703f66 213 For "opentlc-shared" standard config, check out the link:./ansible/configs/ocp-workshop/README.adoc[README] file
062d29 214
400a88 215 == Cleanup (Reference Only)
GC 216
ea156f 217 NOTE: S3 Buckets are now part of a CloudFormation stack and are properly deleted before the stack in the destroy playbooks.
062d29 218
S 219 * S3 Bucket
400a88 220 - (Reference Only) An S3 bucket is used to back the Docker registry. AWS will not let you delete a
062d29 221 non-empty S3 bucket, so you must do this manually. The `aws` CLI makes this
S 222 easy:
223 +
224 ----
225 aws s3 rm s3://bucket-name --recursive
226 ----
227
228 - Your bucket name is named `{{ env_type }}-{{ guid }}`. So, in the case of a
229 `bu-workshop` environment where you provided the `guid` of "Atlanta", your S3
230 bucket is called `bu-workshop-atlanta`.
231
232 * CloudFormation Template
400a88 233 - If `destroy_env.yml` playbook failed, just go into your AWS account to the CloudFormation section in the region where
062d29 234 you provisioned, find the deployed stack, and delete it.
S 235
236 * SSH config
400a88 237 - 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.
062d29 238
S 239 == Troubleshooting
240
241 Information will be added here as problems are solved. So far it's pretty
400a88 242 vanilla, but quite slow. Expect at least 40 min for a full OpenShift deployment. Some configs are faster.
GC 243
244 === Use stable tags
245 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`.
246
247 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:
248
249 ----
250 git checkout ocp-workshop-prod-1.8
251 ----
062d29 252
S 253 === EC2 instability
254 It has been seen that, on occasion, EC2 is generally unstable. This manifests in
255 various ways:
256
257 * The autoscaling group for the nodes takes an extremely long time to deploy, or
258   will never complete deploying
259
260 * Individual EC2 instances may have terrible performance, which can result in
261   nodes that seem to be "hung" despite being reachable via SSH.
262
263 There is not much that can be done in this circumstance besides starting over
264 (in a different region).
265
266 === Re-Running
267 While Ansible is idempotent and supports being re-run, there are some known
268 issues with doing so. Specifically:
269
270 * You should skip the tag `nfs_tasks` with the `--skip-tags` option if you
271   re-run the playbook **after** the NFS server has been provisioned and
272   configured. The playbook is not safe for re-run and will fail.
273
400a88 274 == FAQ
GC 275
276 * Is this a replacement for openshift-ansible playbook ? Why ?
277
278 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.