Readme fixes

Capgemini · Mar 24, 2015 · 6665dcd · 6665dcd
1 parent 248e694
commit 6665dcd
Show file tree

Hide file tree

Showing 4 changed files with 83 additions and 89 deletions.
diff --git a/README.md b/README.md
@@ -1,98 +1,34 @@
-terraform-mesos-consul-ceph-weave
+Apollo
 =========
 
-#WARNING - THIS IS PURELY EXPERIMENTAL AND NOT TESTED FULLY ON ALL PROVIDERS YET
+Apollo is an open source project to aid with building and deploying IAAS and
+PAAS services. It is particularly geared towards managing containerized applications
+across multiple hosts, and hooks into other open source products to provide basic
+mehanisms for deployment, maintenance, and scaling of infrastructure and applications.
 
-A repo to test get 3 mesos master and 3 mesos slave on AWS, Rackspace or Google Compute Engine, with Consul keystore, weave, docker, ceph cluster and jenkins running.
+Apollo is built on top of the following components:
 
-# Prereqs
-## Basic stuff
-- AWS access and secret keys
-- [Terraform](http://terraform.io)
-- [Terraform Ceph Module] 
-First, you should download the module using terraform get
-terraform get
-Get: git::https://github.com/riywo/mesos-ceph.git
+* [Packer](https://packer.io)
+* [Terraform](https://www.terraform.io/)
+* [Apache Mesos](http://mesos.apache.org/)
+* [Consul](http://consul.io)
+* [Docker](http://docker.io)
+* [Weave](https://github.com/zettio/weave)
 
+Apollo is:
 
-Then, you can check terraform plan. To show resources in module, you have to provide -module-depth option.
-```terraform plan -module-depth -1```
-The Terraform execution plan has been generated and is shown below.
-Resources are shown in alphabetical order for quick scanning. Green resources
-will be created (or destroyed and then created if an existing resource
-exists), yellow resources are being changed in-place, and red resources
-will be destroyed.
+* **self-healing**: auto-placement, auto-restart, auto-replication
+* **portable**: public, private, hybrid, multi cloud
 
-- [Consul](http://consul.io)
-- ZoneID for Route53
+Apollo can run anywhere!
 
-## Things you need to do
-- Copy ```terraform.tfvars.example``` to ```terraform.tfvars``` and replace the values (or supply ```-var``` in your command line) 
-- Check ```variables.tf``` to ensure you are using the proper AMIs. Right now I have it set to Ubuntu Trusty (14.04) with an instance backed store.
-- mesos-master.tf has Availability Zones set to eu-ams-1a, b and c. Please change to meet your needs.
+However, initial development is happening on AWS so our instructions and scripts are built around that. Stayed tuned for more cloud provider support! If you make it work on other infrastructure please let us know and contribute instructions/code.
 
-- For this example, we use the Consul cluster to both read configuration and store information about a newly created EC2 instance. The size of the EC2 instance will be determined by the "tf_test/size" key in Consul, and will default to "m1.small" if that key does not exist. Once the instance is created the "tf_test/id" and "tf_test/public_dns" keys will be set with the computed values for the instance.
-Before we run the example, use the Web UI to set the "tf_test/size" key to "t1.micro". Once that is done, copy the configuration into a configuration file ("consul.tf" works fine). Either provide the AWS credentials as a default value in the configuration or invoke apply with the appropriate variables set.
-Once the apply has completed, we can see the keys in Consul by visiting the Web UI. We can see that the "tf_test/id" and "tf_test/public_dns" values have been set.
+Apollo is in alpha!
 
+While the concepts and base architectural components of Apollo are not expected to change drastically, the project is still under heavy development. Expect bugs, design and API changes as we bring it to a stable, production ready, multi-cloud available product.
 
-## Summary
-
-This Terraform module will spin up instances like below by default:
-
-- admin
-    - t2.micro
-    - ssh gateway
-    - run ceph-deploy
-- master1, master2, master3
-    - t2.micro
-    - mesos master
-    - marathon
-    - ceph mon
-    - ceph mds
-    - mount cephfs
-- slaves (default 3)
-    - t2.micro
-    - mesos slave
-    - ceph osd
-        - 1 EBS attached (default 30GB)
-    - mount cephfs
-
-## Fire it up
-The default will launch an m3.medium since this is the smallest instace that uses an instance back store. 
-```
-cd aws
-terraform apply 
-OR 
-cd rackspace
-terraform apply
-```
-
-# Helpful commands
-- Show info about the instances
-```terraform show terraform.tfstate```
-- Test your terraform config
-```terraform plan```
-- Delete everything
-```
-terraform plan -destroy -out=terraform.tfplan
-terraform apply terraform.tfplan
-```
-
-# Next steps
-- Packer template for AWS, Rackspace & GCE
-- Consul based backend
-- Integrate weave
-- Ceph Cluster
-- Setup Jenkins on Slave
-- Setup ASG, launch configuration and user-data for mesos-slave
-- Add the AZs as a variable
-- Security groups for AWS and Rackspace
-- Move to Ansible playbook for install
-
-# Thanks and Contributions
-- https://github.com/riywo/mesos-ceph
-- https://github.com/tonyjchong/terraform-mesos
-- https://github.com/hashicorp/terraform/tree/master/examples/consul
-- https://github.com/hashicorp/consul/blob/master/terraform/
-- https://github.com/hashicorp/consul/blob/master/terraform/aws/scripts/upstart-join.conf
+## Documentation
+ - **Getting Started Guides**
+    - for people who want to create an Apollo cluster
+    - in [docs/getting-started-guides](docs/getting-started-guides)
diff --git a/docs/getting-started-guides/README.md b/docs/getting-started-guides/README.md
@@ -0,0 +1,18 @@
+IaaS Provider  | Config. Mgmt | OS     | Networking  | Docs                                                   | Support Level                | Notes
+-------------- | ------------ | ------ | ----------  | ----------------------------------------------------   | ---------------------------- | -----
+AWS            | Custom    | Ubuntu | Weave         | [docs](../../docs/getting-started-guides/aws.md)       | Project                      |
+
+Definition of columns:
+
+  - **IaaS Provider** is who/what provides the virtual or physical machines (nodes) that Apollo runs on.
+  - **OS** is the base operating system of the nodes.
+  - **Config. Mgmt** is the configuration management system that helps install and maintain apollo software on the
+    nodes.
+  - **Networking** is what implements the networking model.  Those with networking type
+    _none_ may not support more than one node, or may support multiple VM nodes only in the same physical node.
+  - Support Levels
+    - **Project**:  Apollo Committers regularly use this configuration, so it usually works with the latest release
+      of Apollo.
+    - **Commercial**: A commercial offering with its own support arrangements.
+    - **Community**: Actively supported by community contributions. May not work with more recent releases of Apollo.
+    - **Inactive**: No active maintainer.  Not recommended for first-time Apollo users, and may be deleted soon.
diff --git a/docs/getting-started-guides/aws.md b/docs/getting-started-guides/aws.md
@@ -0,0 +1,39 @@
+## Getting started on AWS
+
+### Prerequisites
+
+1. You need an AWS account. Visit [http://aws.amazon.com](http://aws.amazon.com) to get started
+2. Install and configure [AWS Command Line Interface](http://aws.amazon.com/cli)
+3. You need an AWS [instance profile and role](http://docs.aws.amazon.com/IAM/latest/UserGuide/instance-profiles.html) with EC2 full access.
+4. You need an Atlas account. Visit [https://atlas.hashicorp.com](https://atlas.hashicorp.com) to get started.
+5. You need to have installed and configured Terraform. Visit [https://www.terraform.io/intro/getting-started/install.html](https://www.terraform.io/intro/getting-started/install.html) to get started.
+
+
+### Cluster Turnup
+
+#### Download Apollo
+
+##### Install from source at head
+1. ```git clone https://github.com/Capgemini/apollo.git```
+2. ```cd apollo/terraform/aws```
+
+#### Set config
+1. ```cp terraform.tfvars.example terraform.tfvars```
+
+Edit ```terraform.tfvars``` to include your AWS access/secret, keyfile/keyname and Atlas token.
+
+#### Checking you have the correct config
+```
+terraform plan
+```
+
+This should execute a dry-run indicating what Terraform will do when it is run. This should highlight any config issues from above steps.
+
+#### Turn up the cluster
+```
+terraform apply
+```
+
+NOTE: The script will provision a new VPC and a 3 node mesos master cluster in eu-west-1 (Ireland). It'll also try to create a mesos slave cluster and a NAT server for accessing via VPN and SSH.
+
+For instructions on how to configure the VPN to access the web interface of the tools see the [vpn guide](../aws/vpn.md).
diff --git a/docs/vpn.md → docs/getting-started-guides/aws/vpn.md b/docs/vpn.md → docs/getting-started-guides/aws/vpn.md
@@ -5,7 +5,7 @@ configuration to connect with the OpenVPN client from your workstation.
 This is required if you wish to access the web UI of machines running
 in the private VPC (e.g. consul UI / Mesos / Marathon)
 
-#### Pre-requisites
+### Pre-requisites
 
 * Install aws cli to generate key-pair - https://github.com/aws/aws-cli
 * Generate key-pair - http://www.dowdandassociates.com/blog/content/howto-create-an-amazon-ec2-key-pair-using-the-aws-cli/
@@ -15,6 +15,7 @@ in the private VPC (e.g. consul UI / Mesos / Marathon)
 ssh-add -K <key_file_path>
 ```
 
+### Steps
 
 1: Initialize PKI
 
@@ -63,7 +64,7 @@ $USER-cagpemini-mesos.ovpn file
    with Tunnelblick
 3. Connect to the VPN
 
-Once connected you should be able to access the following - 
+Once connected you should be able to access the following -
 
 * [Mesos Master UI] (http://10.0.1.11:5050)
 * [Marathon UI] (http://10.0.1.11:8080)