Commit 5956d044 authored by Dimitris Aragiorgis's avatar Dimitris Aragiorgis
Browse files

Add snf-deploy tool doc

Signed-off-by: default avatarDimitris Aragiorgis <>
parent b0cf0f3c
......@@ -34,6 +34,8 @@ There are also the following tools:
kamaki: Command-line client <>
snf-image-creator: Image bundling/uploading/registering tool <>
snf-image: Secure image deployment tool <snf-image>
snf-deploy: Synnefo deployment tool <snf-deploy>
Synnefo is designed to be as simple, scalable and production ready as possible.
Furthermore, although it can be deployed in small configurations, its prime
......@@ -62,7 +64,15 @@ Synnefo running with two different storage backends.
Synnefo Guides
There are 4 guides for Synnefo.
There are 5 guides for Synnefo.
For the really impatient snf-deploy tool allows you to install all software
components from scratch (creating locally kvm based Virtual Machines) or to an
existing cluster (in the same network subnet and domain, same network
configuration, vanilla debian squeeze and installed ssh keys). Please note that
this should be used only for testing or demo installations because most of the
times the prerequisites cannot be satisfied due to the underlying
infrastructure complexity (especially as far as networks is conserned).
The quick installation guide describes how to install the whole Synnefo stack
in just two physical nodes, for testing purposes. This guide is useful to those
......@@ -83,6 +93,12 @@ external world. The Integrator's Guide targets developers, who want to actually
extend/modify/change Synnefo itself, so describes Synnefo's indepth
architecture and the internals of Synnefo components (currently out-of-date!).
.. toctree::
:maxdepth: 2
snf-deploy tool <snf-deploy>
.. toctree::
:maxdepth: 1
.. _snf-deploy:
snf-deploy tool
This tool allows you to deploy all Synnefo components from scratch
or to an existing cluster.
This is useful mostly for testing/demo installation and is not suggested for
production environments. At the end you will have an up-and-running Synnefo but
the end-to-end functionallity will depend from your underlying infrastracture
(e.g. is nested virtualization enabled in your PC, is the router properly
configured, do node have fully qualified domain names, etc.). Nevertheless you
will be able to experience the API/UI and base funtionality the Synnefo IaaS
provides and you 'll get a proper configuration that will guide you through
setting a production environment that will scale up and use all available
features (e.g. rados, archipelagos, etc).
snf-deploy is a debian package that should be installed locally and allow you
install Synnefo on remote nodes (either already existing or not). To this
end this guide will break the whole procedure into three; the configuration,
the virtual cluster creation (optional) and finally the Synnefo installation.
Before getting any further we should mention the roles that snf-deploy refers
to. Note that more than one roles can co-exist in the same node (except for few)
but it is highy recommended to dedicate one node (VM or physical) to each role:
- existing nodes: All available nodes in the cluster
- accounts: Identity Management
- pithos: Storage Service
- cms: Content Management System
- cyclades: Compute Service to manage Instances, Networks, etc.
- mq: Asynchronous Message Queue System for inter-service communication
- qh: Quota Holder to keep track of resources utilization
- ns: Nameserver to resolve Synnefo FQDN
- router: The node to do any routing and NAT needed
- client: The node to setup a command line tool to manage a user account
All these define the synnefo components. In order to have instances up-and-running,
at least a backend must be associated with Cyclades. Backends are
Ganeti clusters each with multiple nodes. Please note that these nodes may be the
same as the ones used before. To this end we refer to:
- ganeti nodes: All available nodes for a specific backend
- master: The master node in each ganeti backend
The configuration files to edit are under /etc/snf-deploy:
Defines all existing hostnames and their ips. Currently snf-deploy expects all
nodes to reside in the same network subnet and domain, will share the same
gateway and nameserver. Synnefo needs fqdn for its services. Therefore a
nameserver is setup in the cluster by snf-deploy so the nameserver IP should be
among the existing ones. From now on we refer to the nodes based on their
hostnames. This implies their fqdn and their IP.
Additionally here we define the available ganeti clusters as far as the
nodes is concerned. Additionaly info is provided in backends.conf
The important section here is the roles. Based on the aforementioned, we
assing each role to a certain role. Note that we refer to nodes with their
short hostnames and they should be previously defined in nodes.conf
Here we define also the authentication details for the nodes (user, password),
various credentials for the synnefo installation, whether nodes have an extra
disk (used for lvm/drbd storage in Ganeti backends) or not. The VMCs should
have three separate network interfaces (either physical or not -vlans) each
in the same collition domain; one for the node's public network, one
for VM's public network and one for VM's private network. In order to
support the most common case, a router is setup on the VMs' public interface
and does NAT (hoping the node has itself internet access).
Here we include all info regarding Ganeti backends. That is the master node,
its floating IP, the volume group name (in case of lvm support) and the VM's
public network associated to it. Please note that currently Synnefo expects
different public networks per backend but still can support multiple public
networks per backend.
Here we define all necessary info for customizing snf-deploy; whether to use
local packages or not (this is used primarily by developers), which bridge
to use (if you create a virtual cluster from scratch), and where are the
necessary local directories (packages, templates, images, etc..)
Virtual Cluster Creation
Supposing you want to install Synnefo from scratch the best way is to launch
a couple of VM's locally. To this end you need a debian base image. An 8GB one
with preinstalled keys and network-manager hostname hooks exists in
and can be fetched with:
.. code-block:: console
snf-deploy image
This will save locally the image under /var/lib/snf-deploy/images. TODO: mention
related options: --img-dir, --extra-disk, --lvg, --os
To have a functional networking setup for the instances please run:
.. code-block:: console
snf-deploy prepare
This will add a bridge, iptables to allow traffic from/to it, enable forwarding and
NAT for the given network subnet.
To provide the configured hostnames and IPs to the cluster please run:
.. code-block:: console
snf-deploy dhcp
This will launch a dnsmasq instance acting only as dhcp server and listening only on
the cluster's bridge. In case you have changes the nodes.conf you should re-create
the dnsmasq related files (in /etc/snf-deploy) only by extra passing --save-config.
At this point you can create the virtual cluster defined in nodes.conf with:
.. code-block:: console
snf-deploy cluster
This will launch KVM Virtual Machines snapshoting the base image you fetched
before. Their taps will be connected with the already created bridge and their
primary interface should get the given address.
Setting up the Synnefo DNS
At this point you should have an up-and-running cluster (either virtual or not)
with valid hostnames and IPs. Synnefo expects fqdn and therefore a nameserver
(bind) should be setup in a node inside the cluster. All nodes along with your
PC should uses this nameserver and search in the corresponding network domain.
To this end add to your local resolv.conf (please change the default values with
the ones of your custom configuration):
| search <your_domain> synnefo.deploy.local
| nameserver
To setup the nameserver in the node specified in setup.conf please run:
.. code-block:: console
snf-deploy dns
Synnefo Installation
At this point you should have a cluster with fqdns and reverse DNS lookups ready
for synnefo deployment. To sum up we mention all the node requirements for a
successful synnefo installation:
Node Requirements
- OS: Debian Squeeze
- authentication: `root` with known password
- primary network interface: `eth0`
- primary IP in the same IPv4 subnet and network domain
- spare network interfaces: `eth1`, `eth2` (or vlans on `eth0`)
- password-less intra-node communication: same `id_rsa/dsa` keys and `authorized_keys`
Those are met already in the case of virtual cluster.
To check the network configuration (fqdns, connectivity):
.. code-block:: console
snf-deploy check
WARNING: In case ping fails check ``/etc/nsswitch.conf`` hosts entry and put dns after files!!!
To setup the NFS needed among the cluster:
.. code-block:: console
snf-deploy nfs
To install the Synnefo stack on the existing cluster please run:
.. code-block:: console
snf-deploy synnefo -vvv
and wait a few seconds.
To check for successful installation you can visit from your local PC:
| https://accounts.synnefo.deploy.local/im/
and login with:
| username: password: lala
or whatever you gave in setup.conf and get a small taste of your private cloud setup.
Adding a Ganeti Backend
Assuming that all have worked out fine as expected, you must have astakos,
pithos, cms, db and mq up and running. Cyclades work too but partially. No
backend is registered yet. Let's setup one. Currently synnefo supports only
Ganeti clusters for backends. They have to be created offline and once they
are up and running must be registered to Cyclades. After 0.12, synnefo supports
multiple backends. snf-deploy defines backend nodes in nodes.conf and backend
info in backends.conf.
To deploy a backend please use:
.. code-block:: console
snf-deploy backend --backend-name ganeti1 -vvv
where ganeti1 or whatever refers to the corresponding entry in conf files.
To setup backend storage (lvm, drbd or file) and network (bridges, iptables,
.. code-block:: console
snf-deploy backend-storage --backend-name ganeti1
snf-deploy backend-network --backend-name ganeti1
To test deployment state please visit:
.. code-block:: console
and try to create a VM.
snf-deploy as DevTool
For developers who want to contribute a single node setup is highly recommended.
snf-deploy tools also supports updating packages that are localy generated. This
to work please add all \*.deb files in packages directory (see deploy.conf) and
.. code-block:: console
snf-deploy synnefo --update --use-local-packages
snf-deploy backend --backend-name ganeti2 --update --use-local-packages
For advanced users there is a possibility to individually run one or more of the
supported actions. To find out which are those run:
.. code-block:: console
snf-deploy run --help
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment