:toc2:
|
image::https://travis-ci.org/redhat-cop/agnosticd.svg?branch=development[link="https://travis-ci.org/redhat-cop/agnosticd"]
|
|
= Ansible Agnostic Deployer
|
|
Ansible Agnostic Deployer (AAD) 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.
|
|
image::docs/images/agnosticd_flow.png[width=100%]
|
|
|
This document gives a brief overview of the project function, and structure.
|
It also provides a guide to the more comprehensive documentation set provided in the `docs/` directory.
|
|
== Basic Structure
|
|
The repository contains various Ansible playbooks, templates, and other support
|
files used to provision different software (OpenShift, Ansible Tower, ...) onto
|
Cloud Infrastructure (AWS, Ravello, ...). The key files and directories include:
|
|
|
* `./docs/` Start here
|
* `./ansible` The execution environment
|
* `./ansible/main.yml` The entry point for a deployment
|
* `./ansible/configs` Home to the _configs_ to deploy
|
|
The Contributors Guides explore the relevant structures in significantly more detail:
|
|
* link:docs/Creating_a_config.adoc[Creating a Config]
|
* link:docs/Creating_a_cloud_deployer.adoc[Creating a Cloud Deployer]
|
|
== Overview of Ansible Agnostic Deployer Flow
|
|
image::docs/images/agnosticd_flow.png[width=100%]
|
|
|
AAD 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 -e "env_type=three-tier-app cloud_provider=aws"`
|
|
.*Simplified execution flow of `main.yml`
|
[source,bash]
|
----
|
- import_playbook: "configs/{{ env_type }}/pre_infra.yml"
|
- import_playbook: "cloud_providers/{{ cloud_provider }}_infrastructure_deployment.yml"
|
- import_playbook: "configs/{{ env_type }}/post_infra.yml"
|
- import_playbook: "configs/{{ env_type }}/pre_software.yml"
|
- import_playbook: "configs/{{ env_type }}/software.yml"
|
- import_playbook: "configs/{{ env_type }}/post_software.yml"
|
----
|
|
For _config_ developers the above stages provide 5 _hooks_ for customizing the configuration of your environment and 1 _hook_ for customizing it for one or more cloud providers (e.g. AWS, Azure, etc).
|
|
An _Example config_ is provided by `ansible/configs/just-some-nodes-example`
|
|
[TIP]
|
====
|
To understand the 6 stages in depth and how to create your own _config_ or copy and modify an existing _config_ please see the link:docs/Creating_a_config.adoc[Creating a Config Developers Guide] for more detail.
|
====
|
|
== 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.
|