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

Commit

Permalink
Merge pull request #1217 from CiscoCloud/doc/Feb16update
Browse files Browse the repository at this point in the history 
Doc/feb16update
  • Loading branch information
@langston-barrett
langston-barrett committed Mar 14, 2016
2 parents 6696261 + 77de825 commit 705dbd6
Showing 1 changed file with 137 additions and 74 deletions.
211 changes: 137 additions & 74 deletions docs/getting_started/index.rst
View file
Expand Up @@ -6,111 +6,152 @@ Getting Started
continuing. This can be done simply by running ``pip install -r
requirements.txt`` from the root of the project.

It also assumes you have a working Terraform installation. You
can download Terraform from `Terraform downloads`_.

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.
3. a playbook to show which components should go where.
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`_.

Provisioning Cloud Hosts
------------------------
Preparing to provision Cloud Hosts
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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. However, here are some guides to get started on common
platforms:
equivalent.

.. toctree::
:maxdepth: 1
Your hosts will have to be accessible with your SSH key. If you're unfamiliar
with SSH keys, please read `DigitalOcean's guide to setting up SSH keys
<https://www.digitalocean.com/community/tutorials/how-to-set-up-ssh-keys--2>`_.

openstack.rst
gce.rst
aws.rst
digitalocean.rst
vsphere.rst
softlayer.rst
clc.rst
There are several preparatory steps to provisioning the cloud hosts that are
common to all providers:

Setting up DNS
--------------
Step 1: Copy .tf file
---------------------

You can set up your DNS records with Terraform:
You will 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.

.. toctree::
:maxdepth: 2
.. note::

dns.rst
More than one .tf file in the mantl directory will lead to errors upon
deployment. Since Mantl initially does not support multiple datacenters, extra .tf files will
need to be renamed or moved. If you would like to add multiple datacenters see the `Consul docs`_ for more information.

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

Running the ``security-setup`` script in the root directory will set
up passwords, authentication, and certificates. For more information, see the
`security-setup`_ documentation.

Setting up Authentication and Authorization
-------------------------------------------
Step 3: Set up DNS records
--------------------------

Before you begin, you'll want to run the ``security-setup`` script in the
root directory. This will create and set passwords, authentication, and
certificates. For more information, see the :doc:`security-setup
<../security/security_setup>` documentation.
You can set up your DNS records with Terraform: `dns.rst`_

Provisioning Cloud Hosts
^^^^^^^^^^^^^^^^^^^^^^^^

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

- `openstack.rst`_
- `gce.rst`_
- `aws.rst`_
- `digitalocean.rst`_
- `vsphere.rst`_
- `softlayer.rst`_
- `clc.rst`_

Deploying software via Ansible
------------------------------
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. note:: Ansible requres a Python 2 binary. If yours is not at /usr/bin/python,
please view the `Ansible FAQ <http://docs.ansible.com/faq.html>`_. You
can add an extra variable to the following commands, e.g.
``ansible -e ansible_python_interpreter=/path/to/python2``.

In the following examples, we're going to assume you deployed hosts using
Terraform. This project ships with a dynamic inventory file to read Terraform
``.tfstate`` files. If you are running ansible from the root directory of the
project, this inventory file will be used by default. If not, or 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:
The following steps assume that you have provisioned your cloud host by taking
the steps listed in one of the guides above.

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.

.. code-block:: shell
ansible-playbook -i path/to/inventory -e @security.yml mantl.yml
ansible-playbook -i path/to/inventory -e @security.yml mantl.yml
Step 1: Add password to the ssh-agent
-------------------------------------

First, ping the servers to ensure they are reachable via ssh:
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.

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

.. code-block:: shell
ansible all -m ping
ansible all -m ping
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 to view the errors in
more detail.

If any servers fail to connect, 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::

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
ansible-playbook playbooks/upgrade-packages.yml
.. code-block:: shell
If you neglect to upgrade packages, you will likely experience multiple
failures, particularly around Consul. See issues `907`_ and `927`_ for more
details.

ansible-playbook playbooks/upgrade-packages.yml
Step 4: Deploy the software
---------------------------

If you neglect to upgrade packages, you will likely experience multiple
failures, particularly around Consul. See issues `#907
<https://github.com/CiscoCloud/mantl/issues/907>`_ and
`#927
<https://github.com/CiscoCloud/mantl/issues/927>`_ for
more details.
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`_. You'll want to change
``consul_acl_datacenter`` to your preferred ACL datacenter. If you only have
one datacenter, you can remove this variable.

Next, deploy the software. First, you'll need to customize a playbook. A sample
can be found at ``sample.yml`` in the root directory, you can find
more about customizing this at :doc:`playbook`. 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
ansible-playbook -e @security.yml mantl.yml
ansible-playbook -e @security.yml mantl.yml
The deployment will probably take a while as all tasks are completed.

Checking your deployment
------------------------
^^^^^^^^^^^^^^^^^^^^^^^^

Once your deployment has completed, you will be able to access the Mantl UI
in your browser by connecting to one of the control nodes.
Expand All @@ -119,7 +160,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 @@ -132,11 +173,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 valid
certs. 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 @@ -151,18 +192,39 @@ Customizing your deployment

Below are guides customizing your deployment:

.. toctree::
:maxdepth: 1

ssh_users.rst
playbook.rst
dockerfile.rst
- `ssh_users.rst`_
- `playbook.rst`_
- `dockerfile.rst`_

.. _Mantl README: https://github.com/CiscoCloud/mantl/blob/master/README.md
.. _working Ansible installation: http://docs.ansible.com/intro_installation.html#installing-the-control-machine
.. _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
.. _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/
.. _generating ssh-keys: https://www.centos.org/docs/5/html/5.2/Deployment_Guide/s3-openssh-rsa-keys-v2.html
.. _secure copying: https://www.centos.org/docs/5/html/5.2/Deployment_Guide/s2-openssh-using-scp.html
.. _mantl/terraform/: https://github.com/CiscoCloud/mantl/tree/master/terraform
.. _openstack.rst: https://github.com/CiscoCloud/mantl/blob/master/docs/getting_started/openstack.rst
.. _gce.rst: https://github.com/CiscoCloud/mantl/blob/master/docs/getting_started/gce.rst
.. _aws.rst: https://github.com/CiscoCloud/mantl/blob/master/docs/getting_started/aws.rst
.. _digitalocean.rst: https://github.com/CiscoCloud/mantl/blob/master/docs/getting_started/digitalocean.rst
.. _vsphere.rst: https://github.com/CiscoCloud/mantl/blob/master/docs/getting_started/vsphere.rst
.. _softlayer.rst: https://github.com/CiscoCloud/mantl/blob/master/docs/getting_started/softlayer.rst
.. _dns.rst: https://github.com/CiscoCloud/mantl/blob/e53b7da545c1bdc71a5ceff7278ace5705117b41/docs/getting_started/dns.rst
.. _playbook: http://docs.ansible.com/playbooks.html
.. _working Ansible installation: http://docs.ansible.com/intro_installation.html#installing-the-control-machine
.. _GitHub project: https://github.com/CiscoCloud/nginx-mantlui
.. _security-setup: https://github.com/CiscoCloud/mantl/blob/master/docs/security/security_setup.rst
.. _Consul docs: https://www.consul.io/docs/guides/datacenters.html
.. _ssh_users.rst: https://github.com/CiscoCloud/mantl/blob/master/docs/getting_started/ssh_users.rst
.. _playbook.rst: https://github.com/CiscoCloud/mantl/blob/master/docs/getting_started/playbook.rst
.. _dockerfile.rst: https://github.com/CiscoCloud/mantl/blob/master/docs/getting_started/dockerfile.rst
.. _907: https://github.com/CiscoCloud/mantl/issues/907
.. _927: https://github.com/CiscoCloud/mantl/issues/927


Restarting your deployment
--------------------------
Expand All @@ -172,9 +234,10 @@ working correctly, use the ``playbooks/reboot-hosts.yml`` playbook.

.. code-block:: shell
ansible-playbook playbooks/reboot-hosts.yml
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 :doc:`dockerfile` for more information.
You can also provision your cluster by running a docker container. See
`dockerfile.rst`_ for more information.

0 comments on commit 705dbd6

Please sign in to comment.