.. _snf-deploy: snf-deploy tool ^^^^^^^^^^^^^^^ The `snf-deploy` tool allows you to automatically deploy Synnefo. You can use `snf-deploy` to deploy Synnefo, in two ways: 1. Create a virtual cluster on your local machine and then deploy on that cluster. 2. Deploy on a pre-existent cluster of physical nodes running Debian Squeeze. Currently, `snf-deploy` is mostly useful for testing/demo installations and is not recommended for production environment Synnefo deployments. If you want to deploy Synnefo in production, please read first the Admin's installation guide (:ref:`Debian `/:ref:`CentOS `) and then the :ref:`Admin's guide `. If you use `snf-deploy` you will setup an up-and-running Synnefo installation, but the end-to-end functionality will depend on your underlying infrastracture (e.g. is nested virtualization enabled in your PC, is the router properly configured, do nodes have fully qualified domain names, etc.). In any way, it will enable you to get a grasp of the Web UI/API and base funtionality of Synnefo and also provide a proper configuration that you can afterwards consult while reading the Admin guides to set up a production environment that will scale up and use all available features (e.g. RADOS, Archipelago, etc). `snf-deploy` is a debian package that should be installed locally and allows you to install Synnefo on remote nodes (if you go for (2)), or spawn a cluster of VMs on your local machine using KVM and then install Synnefo on this cluster (if you go for (1)). To this end, here we will break down our description into three sections: a. :ref:`snf-deploy configuration ` b. :ref:`Creating a virtual cluster ` (needed for (1)) c. :ref:`Synnefo deployment ` (either on virtual nodes created on section b, or on remote physical nodes) If you go for (1) you will need to walk through all the sections. If you go for (2), you should skip section `(b) `, since you only need sections `(a) ` and `(c) `. Before getting any further we should mention the roles that `snf-deploy` refers to. The Synnefo roles are described in detail :ref:`here `. Note that multiple roles can co-exist in the same node (virtual or physical). Currently, `snf-deploy` recognizes the following combined roles: * **accounts** = **WEBSERVER** + **ASTAKOS** * **pithos** = **WEBSERVER** + **PITHOS** * **cyclades** = **WEBSERVER** + **CYCLADES** * **db** = **ASTAKOS_DB** + **PITHOS_DB** + **CYCLADES_DB** the following independent roles: * **qh** = **QHOLDER** * **cms** = **CMS** * **mq** = **MQ** * **ns** = **NS** * **client** = **CLIENT** * **router**: The node to do any routing and NAT needed The above define the roles relative to the Synnefo components. However, in order to have instances up-and-running, at least one backend must be associated with Cyclades. Backends are Ganeti clusters, each with multiple **GANETI_NODE** s. Please note that these nodes may be the same as the ones used for the previous roles. To this end, `snf-deploy` also recognizes: * **cluster_nodes** = **G_BACKEND** = All available nodes of a specific backend * **master_node** = **GANETI_MASTER** Finally, it recognizes the group role: * **existing_nodes** = **SYNNEFO** + (N x **G_BACKEND**) In the future, `snf-deploy` will recognize all the independent roles of a scale out deployment as stated in the :ref:`scale up section `. When that's done, it won't need to introduce its own roles (stated here with lowercase) but rather use the scale out ones (stated with uppercase on the admin guide). .. _conf: Configuration (a) ================= All configuration of `snf-deploy` happens by editting the following files under ``/etc/snf-deploy``: ``nodes.conf`` -------------- This file reflects the hardware infrastucture on which Synnefo is going to be deployed and is the first to be set before running `snf-deploy`. Defines the nodes' hostnames and their IPs. Currently `snf-deploy` expects all nodes to reside in the same network subnet and domain, and share the same gateway and nameserver. Since Synnefo requires FQDNs to operate, a nameserver is going to be automatically setup in the cluster by `snf-deploy`. Thus, the nameserver's IP should appear among the defined node IPs. From now on, we will refer to the nodes with their hostnames. This implies their FQDN and their IP. Also, defines the nodes' authentication credentials (username, password). Furthermore, whether nodes have an extra disk (used for LVM/DRBD storage in Ganeti backends) or not. The VM container nodes should have three separate network interfaces (either physical or vlans) each in the same collision domain; one for the node's public network, one for VMs' public network and one for VMs' private networks. 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). The nodes defined in this file can reflect a number of physical nodes, on which you will deploy Synnefo (option (2)), or a number of virtual nodes which will get created by `snf-deploy` using KVM (option (1)), before deploying Synnefo. As we will see in the next sections, one should first set up this file and then tell `snf-deploy` whether the nodes on this file should be created, or treated as pre-existing. An example ``nodes.conf`` file looks like this: FIXME: example file here ``synnefo.conf`` ---------------- This file reflects the way Synnefo will be deployed on the nodes defined at ``nodes.conf``. The important section here is the roles. In this file we assing each of the roles described in the :ref:`introduction ` to a specific node. The node is one of the nodes defined at ``nodes.conf``. Note that we refer to nodes with their short hostnames. Here we also define all credentials related to users needed by the various Synnefo services (database, RAPI, RabbitMQ) and the credentials of a test end-user (`snf-deploy` simulates a user signing up). Furthermore, define the Pithos shared directory which will hold all the Pithos related data (maps and blocks). Finally, define the name of the bridge interfaces controlled by Synnefo, and a testing Image to register after everything is up and running. An example ``setup.conf`` file (based on the previous ``nodes.conf`` example) looks like this: FIXME: example file here ``ganeti.conf`` --------------- This file reflects the way Ganeti clusters will be deployed on the nodes defined at ``nodes.conf``. Here we include all info with regard to Ganeti backends. That is: the master node, its floating IP, the volume group name (in case of LVM support) and the VMs' 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. FIXME: example file here ``deploy.conf`` --------------- This file customizes `snf-deploy` itself. It defines some needed directories and also includes options that have to do with the source of the packages to be deployed. Specifically, whether to deploy using local packages found under a local directory or deploy using an apt repository. If deploying from local packages, there is also an option to first download the packages from a custom URL and save them under the local directory for later use. FIXME: example file here ``vcluster.conf`` ----------------- This file defines options that are relevant to the virtual cluster creationi, if one chooses to create one. There is an option to define the URL of the Image that will be used as the host OS for the VMs of the virtual cluster. Also, options for defining an LVM space or a plain file to be used as a second disk. Finally, networking options to define where to bridge the virtual cluster. .. _vcluster: Virtual Cluster Creation (b) ============================ As stated in the introduction, `snf-deploy` gives you the ability to create a local virtual cluster using KVM and then deploy Synnefo on top of this cluster. The number of cluster nodes is arbitrary and is defined in ``nodes.conf``. This section describes the creation of the virtual cluster, on which Synnefo will be deployed in the :ref:`next section `. If you want to deploy Synnefo on existing physical nodes, you should skip this section. The first thing you need to deploy a virtual cluster, is a Debian Base image, which will be used to spawn the VMs. We already provide an 8GB Debian Squeeze Base image with preinstalled keys and network-manager hostname hooks. This resides on our production Pithos service. Please see the corresponding ``squeeze_image_url`` variable in ``vcluster.conf``. The image can be fetched by running: .. code-block:: console snf-deploy vcluster image This will download the image from the URL defined at ``squeeez_image_url`` (Pithos by default) and save it locally under ``/var/lib/snf-deploy/images``. TODO: mention related options: --img-dir, --extra-disk, --lvg, --os Once you have the image, then you need to setup the local machine's networking appropriately. You can do this by running: .. code-block:: console snf-deploy vcluster network This will add a bridge (defined with the ``bridge`` option inside ``vcluster.conf``), iptables to allow traffic from/to the cluster, and enable forwarding and NAT for the selected network subnet (defined inside ``nodes.conf`` in the ``subnet`` option). To complete the preparation, you need a DHCP server that will provide the selected hostnames and IPs to the cluster (defined under ``[ips]`` in ``nodes.conf``). To do so, run: .. code-block:: console snf-deploy vcluster dhcp This will launch a dnsmasq instance, acting only as DHCP server and listening only on the cluster's bridge. Every time you make changes inside ``nodes.conf`` you should re-create the dnsmasq related files (under ``/etc/snf-deploy``) by passing --save-config option. After running all the above preparation tasks we can finally create the cluster defined in ``nodes.conf`` by running: .. code-block:: console snf-deploy vcluster create This will launch all the needed KVM virtual machines, snapshotting the image we fetched before. Their taps will be connected with the already created bridge and their primary interface will get the given address. Now that we have the nodes ready, we can move on and deploy Synnefo on them. .. _inst: Synnefo Installation (c) ======================== At this point you should have an up-and-running cluster, either virtual (created in the :ref:`previous section ` on your local machine) or physical on remote nodes. The cluster should also have valid hostnames and IPs. And all its nodes should be defined in ``nodes.conf``. You should also have set up ``synnefo.conf`` to reflect which Synnefo component will reside in which node. Node Requirements ----------------- - OS: Debian Squeeze - authentication: `root` with same password for all nodes - primary network interface: `eth0` - primary IP in the same IPv4 subnet and network domain - spare network interfaces: `eth1`, `eth2` (or vlans on `eth0`) In case you have created a virtual cluster as described in the :ref:`section (b) `, the above requirements are already taken care of. In case of a physical cluster, you need to set them up manually by yourself, before proceeding with the Synnefo installation. Preparing the Synnefo deployment -------------------------------- The following actions are mandatory and must run before the actual deployment. In the following we refer to the sub commands of ``snf-deploy prepare`` and what they actually do. Synnefo expects FQDNs and therefore a nameserver (BIND) should be setup in a node inside the cluster. All nodes along with your local machine should use 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): .. code-block:: console search synnefo.deploy.local nameserver 192.168.0.1 WARNING: In case you are running the installation on physical nodes please ensure that they have the same `resolv.conf` and it does not change during and after installation (because of NetworkManager hooks or something..) To actually setup the nameserver in the node specified as ``ns`` in ``synnefo.conf`` run: .. code-block:: console snf-deploy prepare ns To do some node tweaking and install correct `id_rsa/dsa` keys and `authorized_keys` needed for password-less intra-node communication run: .. code-block:: console snf-deploy prepare hosts At this point you should have a cluster with FQDNs and reverse DNS lookups ready for the Synnefo deployment. To sum up, we mention all the node requirements for a successful Synnefo installation, before proceeding. To check the network configuration (FQDNs, connectivity): .. code-block:: console snf-deploy prepare check WARNING: In case ping fails check ``/etc/nsswitch.conf`` hosts entry and put dns after files!!! To setup the apt repository and update each nodes' package index files: .. code-block:: console snf-deploy prepare apt Finally Synnefo needs a shared file system, so we need to setup the NFS server on node ``pithos`` defined in ``synnefo.conf``: .. code-block:: console snf-deploy prepare nfs If everything is setup correctly and all prerequisites are met, we can start the Synnefo deployment. Synnefo deployment ------------------ To install the Synnefo stack on the existing cluster run: .. code-block:: console snf-deploy synnefo -vvv This might take a while. If this finishes without errors, check for successful installation by visiting from your local machine (make sure you have already setup your local ``resolv.conf`` to point at the cluster's DNS): | https://accounts.synnefo.deploy.local/im/ and login with: | username: dimara@grnet.gr password: lala or the ``user_name`` and ``user_passwd`` defined in your ``synnefo.conf``. Take a small tour checking out Pithos and the rest of the Web UI. You can upload a sample file on Pithos to see that Pithos is working. Do not try to create a VM yet, since we have not yet added a Ganeti backend. If everything seems to work, we go ahead to the last step which is adding a Ganeti backend. Adding a Ganeti Backend ----------------------- Assuming that everything works as expected, you must have Astakos, Pithos, CMS, DB and RabbitMQ up and running. Cyclades should work too, but partially. That's because no backend is registered yet. Let's setup one. Currently, Synnefo supports only Ganeti clusters as valid backends. They have to be created independently with `snf-deploy` and once they are up and running, we register them to Cyclades. From version 0.12, Synnefo supports multiple Ganeti backends. `snf-deploy` defines them in ``ganeti.conf``. After setting up ``ganeti.conf``, run: .. code-block:: console snf-deploy backend create --backend-name ganeti1 -vvv where ``ganeti1`` should have previously been defined as a section in ``ganeti.conf``. This will create the ``ganeti1`` backend on the corresponding nodes (``cluster_nodes``, ``master_node``) defined in the ``ganeti1`` section of the ``ganeti.conf`` file. If you are an experienced user and want to deploy more than one Ganeti backend you should create multiple sections in ``ganeti.conf`` and re-run the above command with the corresponding backend names. After creating and adding the Ganeti backend, we need to setup the backend networking. To do so, we run: .. code-block:: console snf-deploy backend network --backend-name ganeti1 And finally, we need to setup the backend storage: .. code-block:: console snf-deploy backend storage --backend-name ganeti1 This command will first check the ``extra_disk`` in ``nodes.conf`` and try to find it on the nodes of the cluster. If the nodes indeed have that disk, `snf-deploy` will create a PV and the corresponding VG and will enable LVM and DRBD storage in the Ganeti cluster. If the option is blank or `snf-deploy` can't find the disk on the nodes, LVM and DRBD will be disabled and only Ganeti's ``file`` disk template will be enabled. To test everything went as expected, visit from your local machine: .. code-block:: console https://cyclades.synnefo.deploy.local/ui/ and try to create a VM. Also create a Private Network and try to connect it. If everything works, you have setup Synnefo successfully. Enjoy! snf-deploy as a DevTool ======================= For developers, a single node setup is highly recommended and `snf-deploy` is a very helpful tool. `snf-deploy` also supports updating packages that are locally generated. For this to work please add all \*.deb files in packages directory (see ``deploy.conf``) and set the ``use_local_packages`` option to ``True``. Then run: .. code-block:: console snf-deploy synnefo update --use-local-packages snf-deploy backend update --backend-name ganeti2 --use-local-packages For advanced users, `snf-deploy` gives the ability to run one or more times independently some of the supported actions. To find out which are those, run: .. code-block:: console snf-deploy run --help