README

   1 INTRODUCTION
   2 ============
   3
   4 Autocluster is a script for building virtual clusters to test
   5 clustered Samba.
   6
   7 It uses Vagrant (with the libvirt plugin) and Ansible to build and
   8 configure a cluster.
   9
  10 This software is freely distributable under the GNU public license, a
  11 copy of which you should have received with this software (in a file
  12 called COPYING).
  13
  14 CONTENTS
  15 ========
  16
  17 * SUPPORTED PLATFORMS
  18
  19 * INSTALLING AUTOCLUSTER
  20
  21 * HOST MACHINE SETUP
  22
  23 * CREATING A CLUSTER
  24
  25 * DESTROYING A CLUSTER
  26
  27 * DEVELOPMENT HINTS
  28
  29
  30 SUPPORTED_PLATFORMS
  31 ===================
  32
  33 Tested host platforms:
  34
  35 * CentOS 7
  36
  37 Tested guest platforms:
  38
  39 * CentOS 7
  40
  41 Tested cluster filesystems:
  42
  43 * GPFS
  44
  45 INSTALLING AUTOCLUSTER
  46 ======================
  47
  48 Before you start, make sure you have the latest version of
  49 autocluster. To download autocluster do this:
  50
  51   git clone git://git.samba.org/autocluster.git
  52
  53 You probably want to add the directory where autocluster is installed
  54 to your PATH, otherwise things may quickly become tedious.
  55
  56 Packages can also be built and installed.
  57
  58
  59 HOST MACHINE SETUP
  60 ==================
  61
  62 1. Install Ansible
  63
  64 2. Run: autocluster host <platform> setup
  65
  66    Currently the only supported <platform> is "centos7"
  67
  68    This will
  69
  70    * Install and configure several packages, including Vagrant
  71
  72    * Assume you want to serve repositories to guests from /home/mediasets/.
  73
  74    * Create a libvirt storage pool at /virtual/autocluster/ for VM
  75      images/files.
  76
  77    * Create an SSH key for autocluster
  78
  79    For speed, you may wish to mirror the guest distribution somewhere
  80    under /home/mediasets/ or on another nearby machine.
  81
  82 Depending on how your host machine is setup, you may need to run
  83 autocluster commands as root.
  84
  85 CREATING A CLUSTER
  86 ==================
  87
  88 Configuration file
  89 ------------------
  90
  91 The configuration file is a YAML file.  If your cluster is to be
  92 called "foo" then the configuration file must be "foo.yml" in the
  93 current directory.
  94
  95 To see what options to set, try this:
  96
  97     # autocluster cluster foo defaults
  98
  99 This will show default the default configuration.  This is the only
 100 cluster command that doesn't need a cluster configuration.
 101
 102 It may also be worth looking at the file defaults.yml, which
 103 includes some useful comments.
 104
 105 Add updated settings foo.yml.  Try to set the minimum number of
 106 options to keep the configuration file small.  See example.yml.
 107
 108 Most items are fairly obvious.  However, here are some details:
 109
 110 * networks
 111
 112   Default: 10.0.0.0/24 10.0.1.0/24 10.0.2.0/24
 113
 114   There should be at least 2 networks.  The first network is a
 115   private network, while the others can be used for CTDB public IP
 116   addresses.
 117
 118 * firstip
 119
 120   Default: 20
 121
 122   This is the final octet of the first IP address used on each network.
 123
 124 * node_list
 125
 126   Default: [nas, nas, nas, nas, test]
 127
 128   Each node is offset from firstip by its position in the list.
 129
 130   The above default will result in 5 nodes.
 131
 132   - The first 4 will be Clustered Samba NAS nodes (running CTDB,
 133     Samba, NFS) with addresses on the first network from 10.0.0.20
 134     to 10.0.0.23 (with similar static addresses on the other
 135     networks).
 136
 137   - The 5th node will be a minimally installed/configured test node
 138     that can be used as a CTDB test client, with address 10.0.0.24.
 139
 140   Valid node types are:
 141
 142   nas:     Clustered Samba node with cluster filesystem, smbd, nfsd
 143   ad:      Samba Active Directory Domain Controller node
 144   base:    Base operaing system node
 145   build:   Build node for CTDB packages
 146   cbuild:  Build node for Samba, with cluster filesystem installed
 147   storage: Cluster filesystem node that doesn't directly provide NAS services
 148   test:    CTDB test node, with CTDB packages installed
 149
 150 Cluster creation
 151 ----------------
 152
 153 In theory this is easy:
 154
 155     # autocluster cluster foo build
 156
 157 This runs several internal steps:
 158
 159 1. `destroy` - Destroy any existing cluster of the same name
 160 2. `generate` - Generate metadata (for Vagrant, Ansible, SSH) from the
 161    configuration
 162 3. `create` - Create the cluster nodes (using Vagrant)
 163 4. `ssh_config` - Configure SSH to allow direct access to nodes as root
 164 5. `setup` - Setup each node according to its type (using Ansible)
 165
 166 DESTROYING A CLUSTER
 167 ====================
 168
 169     # autocluster cluster foo destroy
 170
 171 DEVELOPMENT HINTS
 172 =================
 173
 174 The Ansible playbook for nodes has been structured in a way that
 175 should make it easy to add new platforms and cluster filesystems.  Try
 176 to follow the pattern and keep task names as generic as possible.
 177
 178 To see facts about <node>:
 179
 180   ansible -i <node>, all -m setup