Skip to content
This repository has been archived by the owner on Jul 27, 2023. It is now read-only.

Commit

Permalink
[skip ci] Copy editing the getting started guide
Browse files Browse the repository at this point in the history
  • Loading branch information
@langston-barrett
langston-barrett committed Mar 3, 2016
1 parent 56fcef7 commit 1bc04be
Showing 1 changed file with 74 additions and 56 deletions.
130 changes: 74 additions & 56 deletions docs/getting_started/index.rst
View file
Expand Up @@ -15,9 +15,13 @@ General Information about Mantl with Ansible
The Mantl project uses Ansible to bring up
nodes and clusters. This generally means that you need three things:

1. hosts to use as the base for your cluster
2. an `inventory file`_ with the hosts you want to be modified. Mantl includes ansible inventory within its `Dynamic inventory for Terraform.py`_.
3. a playbook to show which components should go where. Mantl organizes its components in `sample.yml`_, which we recommend copying to ``mantl.yml`` for the possibility of later customization. You can read more about `playbooks`_ in the `Ansible docs`_.
1. Hosts to use as the base for your cluster
2. An `inventory file`_ with the hosts you want to be modified. Mantl includes
an Ansible inventory for terraformed hosts, `terraform.py`_.
3. A playbook matching Ansible roles to hosts. Mantl organizes its components
in `sample.yml`_, which we recommend copying to ``mantl.yml`` for the
possibility of later customization. You can read more about `playbooks`_ in
the `Ansible docs`_.

Preparing to provision Cloud Hosts
>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
Expand All @@ -26,38 +30,44 @@ The playbooks and roles in this project will work on whatever provider
(or metal) you care to spin up, as long as it can run CentOS 7 or
equivalent.

There are several preparatory steps to provisioning the cloud hosts that are common to all providers:
Your hosts will have to be accessible with your SSH key. If you're unfamiliar
with SSH keys, please read `this blog post
<https://www.digitalocean.com/community/tutorials/how-to-set-up-ssh-keys--2>`_.

Step 1: SSH and SSL
-------------------
There are several preparatory steps to provisioning the cloud hosts that are
common to all providers:

The first step for provisioning, if you have not already, is `generating ssh-keys`_.

.. code-block:: shell
ssh-keygen -t rsa -f /path/to/project/sshkey -C "sshkey"
Step 2: Copy .tf file
Step 1: Copy .tf file
---------------------

You will also need to copy the .tf file of the platform you are using from `mantl/terraform/`_ to the root of the project. For example, ``mantl/terraform/openstack-modules.sample.tf`` will need to be copied to ``mantl/openstack-module-sample.tf``. The variables in the copied .tf file will need to be changed to your configuration.
You will also need to copy the .tf file of the platform you are using from
`mantl/terraform/`_ to the root of the project. For example,
``mantl/terraform/openstack-modules.sample.tf`` will need to be copied to
``mantl/openstack-module-sample.tf``. The variables in the copied .tf file will
need to be changed to your configuration.

.. note::

.. note:: Greater than one .tf file in existance in the mantl directory will lead to errors upon deployment. If you work with more than one provider, extra .tf files will need to be renamed or moved.
More than one .tf file in the mantl directory will lead to errors upon
deployment. If you work with more than one provider, extra .tf files will
need to be renamed or moved.

Step 3: Run security-setup
Step 2: Run security-setup
--------------------------

You'll want set up authentication and authorization by running the ``security-setup`` script in the root directory. This will create and set passwords, authentication, and certificates. For more information, see the `security-setup`_ documentation.
Running the ``security-setup`` script in the root directory will create and set
up passwords, authentication, and certificates. For more information, see the
`security-setup`_ documentation.

Step 4: Set up DNS records
Step 3: Set up DNS records
--------------------------

You can set up your DNS records with Terraform: `dns.rst`_

Provisioning Cloud Hosts
>>>>>>>>>>>>>>>>>>>>>>>>

Here are some guides specific to each of the common platforms that mantl supports:
Here are some guides specific to each of the platforms that Mantl supports:

- `openstack.rst`_
- `gce.rst`_
Expand All @@ -74,71 +84,78 @@ Deploying software via Ansible
can add an extra variable to the following commands, e.g.
``ansible -e ansible_python_interpreter=/path/to/python2``.

The following steps assume that you have provisioned your cloud host by taking the steps listed in one of the guides listed above. We're going to assume you deployed hosts using
Terraform (all the way through terraform apply).
The following steps assume that you have provisioned your cloud host by taking
the steps listed in one of the guides listed above. We're going to assume you
deployed hosts using Terraform.

This project ships with a dynamic inventory file to read Terraform``.tfstate`` files. The steps below include the inventory file, but if you are running ansible from the root directory of the project and leave out the ``-i`` argument, this inventory file will be used by default. If you are not running ansible from the root directory, or would like to use a custom inventory file, you can use the ``-i`` argument of ``ansible`` or ``ansible-playbook`` to specify the inventory file path.
This project ships with a dynamic inventory file to read Terraform ``.tfstate``
files, `terraform.py`_. If you are not running Ansible from the root directory,
or would like to use a custom inventory file, you can use the ``-i`` argument
of ``ansible`` or ``ansible-playbook`` to specify the inventory file path.

For example:

.. code-block:: shell
.. code-block:: shell
ansible-playbook -i path/to/inventory -e @security.yml mantl.yml
Steps to deploying via ansible:
Steps to deploying via Ansible:
>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>

Step 1: Add password to the ssh-agent
-------------------------------------

For the next steps, you may want to add your password to the ssh-agent to maintain a continuous login with your host.

One way to do this:
For the next steps, you may want to `add your password to the ssh-agent
<https://wiki.archlinux.org/index.php?title=SSH_keys&redirect=no#SSH_agents>`_
avoid re-entering your password.

.. code-block:: shell
.. code-block:: shell
eval $(ssh-agent) && ssh-add ~/.ssh/id_rsa
You will be prompted for you host login password.

Step 2: Ping the servers to ensure they are reachable via ssh
-------------------------------------------------------------

.. code-block:: shell
.. code-block:: shell
ansible all -i plugins/inventory/terraform.py -m ping
It may take a few minutes after terraform for the servers to be reachable. If any servers fail to connect, you can check your connection by adding ``-vvvv`` for verbose SSH debugging and try again to view the errors in more detail.
It may take a few minutes after running terraform for the servers to be
reachable. If any servers fail to connect, you can check your connection by
adding ``-vvvv`` for verbose SSH debugging and try again to view the errors in
more detail.

Step 3: Upgrade packages
------------------------

.. warning::
.. warning::

Due to updated packages in the recent CentOS-7 (1511) release, it is critical
that you upgrade operating system packages on all server before proceeding
with deployment:
Due to updated packages in the recent CentOS 7 (1511) release, it is
critical that you upgrade operating system packages on all servers
before proceeding with the deployment:

.. code-block:: shell
.. code-block:: shell
ansible-playbook -e 'serial=0' playbooks/upgrade-packages.yml
If you neglect to upgrade packages, you will likely experience multiple
failures, particularly around Consul. See issues `907`_ and
`927`_ for more details.
If you neglect to upgrade packages, you will likely experience multiple
failures, particularly around Consul. See issues `907`_ and `927`_ for more
details.

Step 4: Deploy the software
---------------------------

First, you will need to customize a playbook. A sample can be found at ``sample.yml`` in the root directory which you can copy to ``mantl.yml``. You can find more about customizing this at `playbooks`_. The main change you'll want to make is changing ``consul_acl_datacenter`` to your preferred ACL datacenter. If you only have one datacenter, you can remove this variable.
First, you will need to customize a playbook. A sample can be found at
``sample.yml`` in the root directory which you can copy to ``mantl.yml``. You
can find more about customizing this at `playbooks`_. The main change you'll
want to make is changing ``consul_acl_datacenter`` to your preferred ACL
datacenter. If you only have one datacenter, you can remove this variable.

Next, assuming you've placed the filled-out template at ``mantl.yml``:
Next, assuming you've placed the filled-out template at ``mantl.yml``:

.. code-block:: shell
.. code-block:: shell
ansible-playbook -i plugins/inventory/terraform.py -e @security.yml mantl.yml
ansible-playbook -e @security.yml mantl.yml
The deployment will probably take a while as all tasks are completed.
The deployment will probably take a while as all tasks are completed.

Checking your deployment
>>>>>>>>>>>>>>>>>>>>>>>>
Expand All @@ -150,7 +167,7 @@ If you need the IP address of your nodes, you can use ``terraform.py``:

.. code-block:: shell
$ plugins/inventory/terraform.py --hostfile
$ python2 plugins/inventory/terraform.py --hostfile
## begin hosts generated by terraform.py ##
xxx.xxx.xxx.xxx mantl-control-01
xxx.xxx.xxx.xxx mantl-control-02
Expand All @@ -163,11 +180,11 @@ If you need the IP address of your nodes, you can use ``terraform.py``:
## end hosts generated by terraform.py ##
When you enter a control node's IP address into your browser, you'll likely get
prompted about invalid security certificates if you have SSL/TLS turned on.
(Follow your browser's instructions on how to access a site without a valid
cert.) Then, you will be presented with a basic access authentication prompt.
The username and password for this is based upon the ``security.yml`` file that
you generated earlier with the ``security-setup`` script.
prompted about invalid security certificates (if you have SSL/TLS turned on).
Follow your browser's instructions on how to access a site without a valid
cert. Then, you will be presented with a basic access authentication prompt.
The username and password for this are the ones generated by ``security-setup``,
and are stored in ``security.yml`` if you forgot them.

Here is what you should be looking at after you connect and authenticate:

Expand All @@ -191,7 +208,7 @@ Below are guides customizing your deployment:
.. _generated dynamically: http://docs.ansible.com/intro_dynamic_inventory.html
.. _Terraform downloads: https://www.terraform.io/downloads.html
.. _inventory file: http://docs.ansible.com/intro_inventory.html
.. _Dynamic inventory for Terraform.py: https://github.com/CiscoCloud/mantl/blob/master/plugins/inventory/terraform.py
.. _terraform.py: https://github.com/CiscoCloud/mantl/blob/master/plugins/inventory/terraform.py
.. _sample.yml: https://github.com/CiscoCloud/mantl/blob/master/sample.yml
.. _playbooks: http://docs.ansible.com/ansible/playbooks.html
.. _Ansible docs: http://docs.ansible.com/ansible/
Expand Down Expand Up @@ -221,11 +238,12 @@ Restarting your deployment
To restart your deployment and make sure all components are restarted and
working correctly, use the ``playbooks/reboot-hosts.yml`` playbook.

.. code-block:: shell
.. code-block:: shell
ansible-playbook playbooks/reboot-hosts.yml
Using a Docker Container to Provision your Cluster
---------------------------------------------------

You can also provision your cluster by running a docker container. See `dockerfile.rst`_ for more information.
You can also provision your cluster by running a docker container. See
`dockerfile.rst`_ for more information.

0 comments on commit 1bc04be

Please sign in to comment.