|
@@ -3,6 +3,274 @@
|
|
|
Usage
|
|
|
=====
|
|
|
|
|
|
Majic Ansible Roles is targeted at sysadmins who wish to deploy services for
|
|
|
their own, small-scale use. This chapter covers some basic steps on how to get
|
|
|
going using them for your own infrastructure.
|
|
|
Majic Ansible Roles are targeted at sysadmins who wish to deploy services for
|
|
|
their own, small-scale use. This chapter gives a simple tutorial-like set of
|
|
|
instructions for using all of the roles available.
|
|
|
|
|
|
|
|
|
Overview
|
|
|
--------
|
|
|
|
|
|
There is a number of different roles that can prove useful for setting-up a
|
|
|
small infrastructure of your own.
|
|
|
|
|
|
Some roles are suited for one-off operations during installation, like the
|
|
|
``preseed`` and ``bootstrap``, while some are better suited for periodic runs
|
|
|
for maintaining the users and integrity of the system.
|
|
|
|
|
|
By the end of the instructions you will have the following:
|
|
|
|
|
|
* Ansible server, used for configuring the remaining servers.
|
|
|
* Communications server, providing the LDAP, mail, and XMPP services.
|
|
|
* Web server, providing the web services.
|
|
|
|
|
|
|
|
|
Pre-requisites
|
|
|
--------------
|
|
|
|
|
|
For the set-up outlined in this usage guide you'll need the following:
|
|
|
|
|
|
* One server where Ansible will be installed at. Debian Jessie will be installed
|
|
|
on top of this server. The server will be set-up manually (this is currently
|
|
|
out of scope for the *Majic Ansible Roles* automated set-up).
|
|
|
* Two servers where the services will be set-up. Both servers must be able to
|
|
|
communicate over network with each-other, the Ansible servers, and with
|
|
|
Internet. Debian Jessie will be installed on top of this server as part of the
|
|
|
usage instructions.
|
|
|
* Debian Jessie network install CD.
|
|
|
* All servers should be on the same network.
|
|
|
* IP addresses for all three servers should be known.
|
|
|
* Netmask for all three servers should be known.
|
|
|
* Gateway for all three servers should be known.
|
|
|
|
|
|
In case of the three servers above, it might be safest to have three VMs
|
|
|
available and handy.
|
|
|
|
|
|
Usage instructions assume the following:
|
|
|
|
|
|
* Domain used for all three servers is ``example.com``. If you wish to use a
|
|
|
different domain, adjust the instructions accordingly.
|
|
|
* Server hostnames are ``ansible``, ``comms``, and ``www`` (for Ansible server,
|
|
|
communications server, and web server respectively).
|
|
|
|
|
|
|
|
|
Installing the OS on Ansible server
|
|
|
-----------------------------------
|
|
|
|
|
|
Start-off by installing the operating system on the Ansible server:
|
|
|
|
|
|
1. Fire-up the ``ansible`` server, and boot from the network installation CD.
|
|
|
|
|
|
2. Select the **Install** option.
|
|
|
|
|
|
3. Pick **English** as language.
|
|
|
|
|
|
4. Pick the country you are living in (or whatever else you want).
|
|
|
|
|
|
5. Pick the **en_US.UTF-8** locale.
|
|
|
|
|
|
6. Pick the **American English** keymap.
|
|
|
|
|
|
7. Configure the network if necessary.
|
|
|
|
|
|
8. Set the hostname to ``ansible``.
|
|
|
|
|
|
9. Set the domain to ``example.com``.
|
|
|
|
|
|
10. Set the root password.
|
|
|
|
|
|
11. Create a new user. For simplicity, call the user **Ansible user**, with
|
|
|
username **ansible**.
|
|
|
|
|
|
12. Set-up partitioning in any way you want. You can go for **Guided - use
|
|
|
entire disk** if you want to keep it simple and are just testing things.
|
|
|
|
|
|
13. Wait until the base system has been installed.
|
|
|
|
|
|
14. Pick whatever Debian archive mirror is closest to you.
|
|
|
|
|
|
15. If you have an HTTP proxy, provide its URL.
|
|
|
|
|
|
16. Pick if you want to participate in package survey or not.
|
|
|
|
|
|
17. Make sure that at least the **standard system utilities** and **SSH server**
|
|
|
options are selected on task selection screen.
|
|
|
|
|
|
18. Wait for packages to be installed.
|
|
|
|
|
|
19. Install the GRUB boot loader on MBR.
|
|
|
|
|
|
20. Finalise the server install, and remove the installation media from server.
|
|
|
|
|
|
|
|
|
Installing required packages
|
|
|
----------------------------
|
|
|
|
|
|
With the operating system installed, it is necessary to install a couple of
|
|
|
packages, and to prepare the environment a bit on the Ansible server:
|
|
|
|
|
|
1. Install the necessary system packages (using the ``root`` account)::
|
|
|
|
|
|
apt-get install -y virtualenv virtualenvwrapper git python-pip python-dev
|
|
|
|
|
|
2. Set-up the virtual environment (using the ``ansible`` account)::
|
|
|
|
|
|
mkdir ~/mysite/
|
|
|
mkvirtualenv -a ~/mysite/ mysite
|
|
|
pip install ansible
|
|
|
|
|
|
|
|
|
Cloning the *Majic Ansible Roles*
|
|
|
---------------------------------
|
|
|
|
|
|
With most of the software pieces in place, the only missing thing is the Majic
|
|
|
Ansible Roles:
|
|
|
|
|
|
1. Clone the git repository::
|
|
|
|
|
|
git clone http://code.majic.rs/majic-ansible-roles ~/majic-ansible-roles
|
|
|
|
|
|
2. Checkout the correct version of the roles::
|
|
|
|
|
|
cd ~/majic-ansible-roles/
|
|
|
git checkout -b 1.0.0 1.0.0
|
|
|
|
|
|
|
|
|
Preparing the basic site configuration
|
|
|
--------------------------------------
|
|
|
|
|
|
Phew... Now that was a bit tedious and boring... But at least you are now ready
|
|
|
to set-up your own site :)
|
|
|
|
|
|
First of all, let's set-up some basic directory structure and configuration:
|
|
|
|
|
|
1. Create Ansible configuration file.
|
|
|
|
|
|
:file:`~/mysite/ansible.cfg`::
|
|
|
|
|
|
[defaults]
|
|
|
|
|
|
roles_path=/home/ansible/majic-ansible-roles/roles
|
|
|
force_handlers = True
|
|
|
retry_files_save_path = /home/ansible/mysite/retry
|
|
|
inventory = /home/ansible/mysite/hosts
|
|
|
|
|
|
2. Create directory where retry files will be stored at (so they woudln't
|
|
|
pollute your home directory)::
|
|
|
|
|
|
mkdir ~/mysite/retry
|
|
|
|
|
|
3. Create the hosts file.
|
|
|
|
|
|
:file:`~/mysite/hosts`::
|
|
|
|
|
|
[preseed]
|
|
|
localhost ansible_connection=local
|
|
|
|
|
|
[communications]
|
|
|
comms.example.com
|
|
|
|
|
|
[web]
|
|
|
www.example.com
|
|
|
|
|
|
4. Create directory where playbooks files will be stored at (the top-level
|
|
|
ones)::
|
|
|
|
|
|
mkdir ~/mysite/playbooks/
|
|
|
|
|
|
5. Create directory where variables will be stored at::
|
|
|
|
|
|
mkdir ~/mysite/group_vars/
|
|
|
|
|
|
6. Before moving ahead, we should also create SSH private/public key pair that
|
|
|
will be used by Ansible for connecting to destination servers, as well as
|
|
|
for some roles::
|
|
|
|
|
|
ssh-keygen -f ~/.ssh/id_rsa -N ''
|
|
|
|
|
|
|
|
|
Preseed files
|
|
|
-------------
|
|
|
|
|
|
The ``preseed`` role is useful for generating Debian preseed files. Preseed
|
|
|
files can be used for automating the Debian installation process.
|
|
|
|
|
|
Preseed files are commonly created on the Ansible host, and then in some way
|
|
|
served to the servers using them during install.
|
|
|
|
|
|
So, let's set this up for start:
|
|
|
|
|
|
1. First of all, create the playbook for generating the preseed files locally.
|
|
|
|
|
|
:file:`~/mysite/playbooks/preseed.yml`::
|
|
|
|
|
|
---
|
|
|
- hosts: preseed
|
|
|
roles:
|
|
|
- preseed
|
|
|
|
|
|
2. And that is about it to be able to actually use this particular role! So
|
|
|
let's try running it::
|
|
|
|
|
|
workon mysite
|
|
|
ansible-playbook playbooks/preseed.yml
|
|
|
|
|
|
3. If all went well, you should have two files now:
|
|
|
|
|
|
* :file:`~/mysite/preseed_files/comms.example.com.cfg` and
|
|
|
* :file:`~/mysite/preseed_files/www.example.com.cfg`
|
|
|
|
|
|
4. You can have a look at them, but you might notice the settings in the file
|
|
|
might not be to your liking. In particular, it could be using wrong timezone,
|
|
|
defaulting to DHCP for network configuration etc. Let's concentrate on making
|
|
|
the network configuration changes - this is the main thing that will probably
|
|
|
differ in your environment. Create a new configuration file:
|
|
|
|
|
|
:file:`~/mysite/group_vars/preseed.yml`::
|
|
|
|
|
|
---
|
|
|
|
|
|
# Set your default (initial) root password.
|
|
|
preseed_root_password: changeit
|
|
|
# Use manual network configuration (no DHCP).
|
|
|
preseed_network_auto: no
|
|
|
# Set the gateway for all servers.
|
|
|
preseed_gateway: 10.32.64.1
|
|
|
# Set the netmask for all servers.
|
|
|
preseed_netmask: 255.255.255.0
|
|
|
# Set the DNS for all servers.
|
|
|
preseed_dns: 10.32.64.1
|
|
|
# Set the domain for all servers.
|
|
|
preseed_domain: example.com
|
|
|
# Set the server-specific options.
|
|
|
preseed_server_overrides:
|
|
|
comms.example.com:
|
|
|
hostname: comms
|
|
|
ip: 10.32.64.19
|
|
|
www.example.com:
|
|
|
hostname: www
|
|
|
ip: 10.32.64.20
|
|
|
|
|
|
5. Now re-run the preseed playbook::
|
|
|
|
|
|
ansible-playbook playbooks/preseed.yml
|
|
|
|
|
|
6. The preseed files should have been updated now, and you should have the new
|
|
|
customised configuration files in the ``preseed_files`` directory. You can
|
|
|
now use these to install the servers.
|
|
|
|
|
|
|
|
|
Installing the servers with preseed files
|
|
|
-----------------------------------------
|
|
|
|
|
|
You have your preseed files now, so you can go ahead and install the servers
|
|
|
``comms.example.com`` and ``www.example.com`` using them with network
|
|
|
install CD. Have a look at `Debian
|
|
|
<https://www.debian.org/releases/stable/amd64/apbs02.html.en>`_ instructions for
|
|
|
more details.
|
|
|
|
|
|
If you need to, you can easily serve the preseed files from the Ansible server
|
|
|
with Python's built-in HTTP server::
|
|
|
|
|
|
cd ~/mysite/preseed_files/
|
|
|
python -m SimpleHTTPServer 8000
|