INTRODUCTION
============

Autocluster is a script for building virtual clusters to test
clustered Samba.

It uses Vagrant (with the libvirt plugin) and Ansible to build and
configure a cluster.

CONTENTS
========

* SUPPORTED PLATFORMS

* INSTALLING AUTOCLUSTER

* HOST MACHINE SETUP

* CREATING A CLUSTER

* DESTROYING A CLUSTER

* DEVELOPMENT HINTS


SUPPORTED_PLATFORMS
===================

Tested host platforms:

* CentOS 7

Tested guest platforms:

* CentOS 7

Tested cluster filesystems:

* GPFS

INSTALLING AUTOCLUSTER
======================

Before you start, make sure you have the latest version of
autocluster. To download autocluster do this:

  git clone git://git.samba.org/autocluster.git

You probably want to add the directory where autocluster is installed
to your PATH, otherwise things may quickly become tedious.

Packages can also be built and installed.


HOST MACHINE SETUP
==================

1. Install Ansible

2. Run: autocluster host <platform> setup

   Currently the only supported <platform> is "centos7"

   This will

   * Install and configure several packages, including Vagrant

   * Assume you want to serve repositories to guests from /home/mediasets/.

   * Create a libvirt storage pool at /virtual/autocluster/ for VM
     images/files.

   * Create an SSH key for autocluster

   For speed, you may wish to mirror the guest distribution somewhere
   under /home/mediasets/ or on another nearby machine.

Depending on how your host machine is setup, you may need to run
autocluster commands as root.

CREATING A CLUSTER
==================

Configuration file
------------------

The configuration file is a YAML file.  If your cluster is to be
called "foo" then the configuration file must be "foo.yml" in the
current directory.

To see what options to set, try this:

    # autocluster cluster foo defaults

This will show default the default configuration.  This is the only
cluster command that doesn't need a cluster configuration.

It may also be worth looking at the file defaults.yml, which
includes some useful comments.

Add updated settings foo.yml.  Try to set the minimum number of
options to keep the configuration file small.  See example.yml.

Most items are fairly obvious.  However, here are some details:

* networks

  Default: 10.0.0.0/24 10.0.1.0/24 10.0.2.0/24

  There should be at least 2 networks.  The first network is a
  private network, while the others can be used for CTDB public IP
  addresses.

* firstip

  Default: 20

  This is the final octet of the first IP address used on each network.

* node_list

  Default: [nas, nas, nas, nas, test]

  Each node is offset from firstip by its position in the list.

  The above default will result in 5 nodes.

  - The first 4 will be Clustered Samba NAS nodes (running CTDB,
    Samba, NFS) with addresses on the first network from 10.0.0.20
    to 10.0.0.23 (with similar static addresses on the other
    networks).

  - The 5th node will be a minimally installed/configured test node
    that can be used as a CTDB test client, with address 10.0.0.24.

  Valid node types are:

  nas:     Clustered Samba node with cluster filesystem, smbd, nfsd
  ad:      Samba Active Directory Domain Controller node
  base:    Base operaing system node
  build:   Build node for CTDB packages
  cbuild:  Build node for Samba, with cluster filesystem installed
  storage: Cluster filesystem node that doesn't directly provide NAS services
  test:    CTDB test node, with CTDB packages installed

Cluster creation
----------------

In theory this is easy:

    # autocluster cluster foo build

This runs several internal steps:

1. `destroy` - Destroy any existing cluster of the same name
2. `generate` - Generate metadata (for Vagrant, Ansible, SSH) from the
   configuration
3. `create` - Create the cluster nodes (using Vagrant)
4. `ssh_config` - Configure SSH to allow direct access to nodes as root
5. `setup` - Setup each node according to its type (using Ansible)

DESTROYING A CLUSTER
====================

    # autocluster cluster foo destroy

DEVELOPMENT HINTS
=================

The Ansible playbook for nodes has been structured in a way that
should make it easy to add new platforms and cluster filesystems.  Try
to follow the pattern and keep task names as generic as possible.