Revision 6d8a47d0 docs/admin-guide.rst
b/docs/admin-guide.rst | ||
---|---|---|
503 | 503 |
Compute/Network/Image Service (Cyclades) |
504 | 504 |
======================================== |
505 | 505 |
|
506 |
Introduction |
|
507 |
------------ |
|
508 |
|
|
509 |
Cyclades is the Synnefo component that implements Compute, Network and Image |
|
510 |
services and exposes the associated OpenStack REST APIs. By running Cyclades |
|
511 |
you can provide a cloud that can handle thousands of virtual servers and |
|
512 |
networks. |
|
513 |
|
|
514 |
Cyclades does not include any virtualization software and knows nothing about |
|
515 |
the low-level VM management operations, e.g. handling of VM creation or |
|
516 |
migrations among physical nodes. Instead, Cyclades is the component that |
|
517 |
handles multiple Ganeti backends and exposes the REST APIs. The administrator |
|
518 |
can expand the infrastructure dynamically either by adding more Ganeti nodes |
|
519 |
or by adding new Ganeti clusters. Cyclades issue VM control commands to Ganeti |
|
520 |
via Ganeti's remote API and receive asynchronous notifications from Ganeti |
|
521 |
backends whenever the state of a VM changes, due to Synnefo- or |
|
522 |
administrator-initiated commands. |
|
523 |
|
|
524 |
Cyclades is the action orchestrator and the API layer on top of multiple Ganeti |
|
525 |
clusters. By this decoupled design, Ganeti cluster are self-contained and |
|
526 |
the administrator has complete control on them without Cyclades knowing about |
|
527 |
it. For example a VM migration to a different physical node is transparent |
|
528 |
to Cyclades. |
|
529 |
|
|
530 |
|
|
506 | 531 |
Working with Cyclades |
507 | 532 |
--------------------- |
508 | 533 |
|
509 |
Managing Ganeti Backends |
|
510 |
~~~~~~~~~~~~~~~~~~~~~~~~ |
|
534 |
Flavors |
|
535 |
~~~~~~~ |
|
536 |
|
|
537 |
When creating a VM, the user must specify the `flavor` of the virtual server. |
|
538 |
Flavors are the virtual hardware templates, and provide a description about |
|
539 |
the number of CPUs, the amount of RAM, and the size of the disk of the VM. |
|
540 |
Besides the size of the disk, Cyclades flavors describe the storage backend |
|
541 |
that will be used for the virtual server. |
|
542 |
|
|
543 |
Flavors are created by the administrator and the user can select one of the |
|
544 |
available flavors. After VM creation, the user can dynamically resize his VM, |
|
545 |
by dynamically (hotplug-able) adding or removing CPU and RAM. |
|
546 |
|
|
547 |
Cyclades support different storage backends that are described by the disk |
|
548 |
template of the flavor, which is mapped to Ganeti's instance `disk template`. |
|
549 |
Currently the available disk templates are the following: |
|
550 |
|
|
551 |
* `file`: regulars file |
|
552 |
* `sharedfile`: regular files on a shared directory, e.g. NFS |
|
553 |
* `plain`: logical volumes |
|
554 |
* `drbd`: drbd on top of lvm volumes |
|
555 |
* `rbd`: rbd volumes residing inside a RADOS cluster |
|
556 |
* `ext`: disks provided by an external shared storage. |
|
557 |
|
|
558 |
- `ext_archipelago`: External shared storage provided by |
|
559 |
`Archipelago <http://www.synnefo.org/docs/archipelago/latest/index.html>`_. |
|
560 |
|
|
561 |
Flavors are created by the administrator using `snf-manage flavor-create` |
|
562 |
command. The command takes as argument number of CPUs, amount of RAM, the size |
|
563 |
of the disks and the disk templates and create the flavors that belong to the |
|
564 |
cartesian product of the specified arguments. For example, the following |
|
565 |
command will create two flavors of `40G` disk size with `drbd` disk template, |
|
566 |
`4G` RAM and `2` or `4` CPUs. |
|
567 |
|
|
568 |
.. code-block:: console |
|
569 |
|
|
570 |
snf-manage flavor-create 2,4 4096 40 drbd |
|
571 |
|
|
572 |
To see the available flavors, run `snf-manage flavor-list` command. Finally, |
|
573 |
the administrator can delete a flavor by using `flavor-modify` command: |
|
574 |
|
|
575 |
.. code-block:: console |
|
576 |
|
|
577 |
snf-manage flavor-modify --deleted=True <flavor_id> |
|
578 |
|
|
579 |
Images |
|
580 |
~~~~~~ |
|
581 |
|
|
582 |
When creating a VM the user must also specify the `image` of the virtual |
|
583 |
server. Images are the static templates from which VM instances are |
|
584 |
initiated. Cyclades uses Pithos to store system and user-provided images, |
|
585 |
taking advantage of all Pithos features, like deduplication and syncing |
|
586 |
protocol. An image is a file stored to Pithos with additional metadata that |
|
587 |
are describing the image, e.g. the OS family or the root partition. To create |
|
588 |
a new image, the administrator or the user has to upload it a file to Pithos, |
|
589 |
and then register it as an Image with Cyclades. Then the user can use this |
|
590 |
image to spawn new VMs from it. |
|
591 |
|
|
592 |
Images can be private, public or shared between users, exactly like Pithos |
|
593 |
files. Since user-provided public images can be untrusted, the administrator |
|
594 |
can denote which users are trusted by adding them to the |
|
595 |
`UI_SYSTEM_IMAGES_OWNERS` setting in the |
|
596 |
`/etc/synnefo/20-snf-cyclades-app-ui.conf` file. Images of those users are |
|
597 |
properly displayed in the UI. |
|
598 |
|
|
599 |
When creating a new VM, Cyclades pass the location of the image and it's |
|
600 |
metadata to Ganeti. After Ganeti creates the instance's disk, `snf-image` |
|
601 |
will copy the image to the new disk and perform the image customization |
|
602 |
phase. During the phase, `snf-image` sends notifications to Cyclades about |
|
603 |
the progress of the image deployment and customization. Customization includes |
|
604 |
resizing the root file system, file injection (e.g. SSH keys) and setting |
|
605 |
a custom hostname. For better understanding of `snf-image` read the |
|
606 |
corresponding `documentation |
|
607 |
<http://www.synnefo.org/docs/snf-image/latest/index.html>`_. |
|
608 |
|
|
609 |
For passing sensitive data about the image to Ganeti, like the VMs password, |
|
610 |
Cyclades keeps all sensitive data in memory caches (memcache) and never allows |
|
611 |
them to hit the disk. The data are exposed to `snf-image` via an one-time URL |
|
612 |
that is exposed from the `vmapi` application. So, instead of passing sensitive |
|
613 |
data to `snf-image` via Ganeti, Cyclades pass an one-time configuration URL |
|
614 |
that contains a random UUID. After `snf-image` gets the sensitive data, the |
|
615 |
URL is invalidated so no one else can access them. |
|
616 |
|
|
617 |
The administrator can register images, exactly like users, using a system user |
|
618 |
(a user that is defined in the `UI_SYSTEM_IMAGES_OWNERS` setting). For |
|
619 |
example, the following command will register the |
|
620 |
`pithos://u53r-un1qu3-1d/images/debian_base-6.0-7-x86_64.diskdump` as an |
|
621 |
image to Cyclades: |
|
622 |
|
|
623 |
.. code-block:: console |
|
624 |
|
|
625 |
kamaki image register "Debian Base" \ |
|
626 |
pithos://u53r-un1qu3-1d/images/debian_base-6.0-7-x86_64.diskdump \ |
|
627 |
--public \ |
|
628 |
--disk-format=diskdump \ |
|
629 |
--property OSFAMILY=linux --property ROOT_PARTITION=1 \ |
|
630 |
--property description="Debian Squeeze Base System" \ |
|
631 |
--property size=451 --property kernel=2.6.32 --property GUI="No GUI" \ |
|
632 |
--property sortorder=1 --property USERS=root --property OS=debian |
|
633 |
|
|
634 |
Deletion of an image is done via `kamaki image unregister` command, which will |
|
635 |
delete the Cyclades Images but will leave the Pithos file as is (unregister). |
|
636 |
|
|
637 |
Apart from using `kamaki` to see and hangle the available images, the |
|
638 |
administrator can use `snf-manage image-list` and `snf-manage image-show` |
|
639 |
commands to list and inspect the available public images. Also, the `--user-id` |
|
640 |
option can be used the see the images of a specific user. |
|
641 |
|
|
642 |
Virtual Servers |
|
643 |
~~~~~~~~~~~~~~~ |
|
644 |
|
|
645 |
As mentioned, Cyclades uses Ganeti for management of VMs. The administrator can |
|
646 |
handle Cyclades VMs just like any other Ganeti instance, via `gnt-instance` |
|
647 |
commands. All Ganeti instances that belong to Synnefo, are separated from |
|
648 |
others, by a prefix in their names. This prefix is defined in |
|
649 |
``BACKEND_PREFIX_ID`` setting in |
|
650 |
``/etc/synnefo/20-snf-cyclades-app-backend.conf``. |
|
651 |
|
|
652 |
Apart from handling Cyclades VM at the Ganeti level, the administrator can |
|
653 |
also use the `snf-manage server-*` commands. These command cover the most |
|
654 |
common tasks that are relative with VM handling. Below we describe come |
|
655 |
of them, but for more information you can use the `--help` option of all |
|
656 |
`snf-manage server-* commands`. These command cover the most |
|
657 |
|
|
658 |
The `snf-manage server-create` command can be used to create a new VM for some |
|
659 |
user. This command can be useful when the administrator wants to test Cyclades |
|
660 |
functionality without starting the API service, e.g. after an upgrade. Also, by |
|
661 |
using `--backend-id` option, the VM will be created in the specified backend, |
|
662 |
bypassing automatic VM allocation. |
|
663 |
|
|
664 |
.. code-block:: console |
|
665 |
|
|
666 |
snf-manage server-create --flavor-id=1 --image-id=fc0f6858-f962-42ce-bf9a-1345f89b3d5e \ |
|
667 |
--user-id=7cf4d078-67bf-424d-8ff2-8669eb4841ea --backend-id=2 \ |
|
668 |
--password='example_passw0rd' --name='test_vm' |
|
669 |
|
|
670 |
The above commnd will create a new VM for user |
|
671 |
`7cf4d078-67bf-424d-8ff2-8669eb4841ea` in the Ganeti backend with ID 2. By |
|
672 |
default this command will issue a Ganeti job to create the VM |
|
673 |
(`OP_INSTANCE_CREATE`) and return. As in other commands, the `--wait=True` |
|
674 |
option can be used in order to wait for the successful completion of the job. |
|
675 |
|
|
676 |
`snf-manage server-list` command can be used to list all the available servers. |
|
677 |
The command supports some useful options, like listing servers of a user, |
|
678 |
listing servers that exist in a Ganeti backend and listing deleted servers. |
|
679 |
Also, as in most of `*-list` commands, the `--filter-by` option can be used to |
|
680 |
filter the results. For example, the following command will only display the |
|
681 |
started servers of a specific flavor: |
|
682 |
|
|
683 |
.. code-block:: console |
|
684 |
|
|
685 |
snf-manage server-list --filter-by="operstate=STARTED,flavor=<flavor_id>" |
|
686 |
|
|
687 |
Another very useful command is the `server-inspect` command which will display |
|
688 |
all available information about the state of the server in DB and the state |
|
689 |
of the server in the Ganeti backend. The output will give you an easy overview |
|
690 |
about the state of the VM which can be useful for debugging. |
|
691 |
|
|
692 |
Also the administrator can `suspend` a user's VM, using the `server-modify` |
|
693 |
command: |
|
694 |
|
|
695 |
.. code-block:: console |
|
696 |
|
|
697 |
snf-manage server-modify --suspended=True <server_id> |
|
698 |
|
|
699 |
The user is forbidden to do any action on an administratively suspended VM, |
|
700 |
which is useful for abuse cases. |
|
701 |
|
|
702 |
Ganeti backends |
|
703 |
~~~~~~~~~~~~~~~ |
|
511 | 704 |
|
512 | 705 |
Since v0.11, Synnefo is able to manage multiple Ganeti clusters (backends) |
513 | 706 |
making it capable to scale linearly to tens of thousands of VMs. Backends |
... | ... | |
634 | 827 |
# snf-manage backend-remove <backend_id> |
635 | 828 |
|
636 | 829 |
|
830 |
Virtual Networks |
|
831 |
~~~~~~~~~~~~~~~~ |
|
832 |
|
|
833 |
Cyclades also implements the Network service and exposes the Quantum Openstack |
|
834 |
API. Cyclades supports full IPv4 and IPv6 connectivity to the public internet |
|
835 |
for it's VMs. Also, Cyclades provides L2 and L3 virtual private networks, |
|
836 |
giving the user freedom to create arbitraty network topologies of |
|
837 |
interconnected VMs. |
|
838 |
|
|
839 |
Public networking is desployment specific and must be customized based on the |
|
840 |
specific needs of the system administrator. Private virtual networks can be |
|
841 |
provided by different network technologies which are exposed as different |
|
842 |
network flavors. For better understanding of networking please refer to the |
|
843 |
:ref:`Network <networks>` section. |
|
844 |
|
|
845 |
A Cyclades virtual network is an isolated Layer-2 broadcast domain. A network |
|
846 |
can also have an associated IPv4 and IPv6 subnet representing the Layer-3 |
|
847 |
characteristics of the network. Each subnet represents an IP address block |
|
848 |
that is used in order to assign addresses to VMs. |
|
849 |
|
|
850 |
To connect a VM to a network, a port must be created, which represent a virtual |
|
851 |
port on a network switch. VMs are connected to networks by attaching a virtual |
|
852 |
interface to a port. |
|
853 |
|
|
854 |
Cyclades also supports `floating IPs`, which are public IPv4 addresses that |
|
855 |
can dynamically(hotplug-able) be added and removed to VMs. Floating IPs are |
|
856 |
a quotable resource that is allocated to each user. Unlike other cloud |
|
857 |
platforms, floating IPs are not implemented using 1-1 NAT to a ports private |
|
858 |
IP. Instead, floating IPs are directly assigned to virtual interfaces of VMs. |
|
859 |
|
|
860 |
Exactly like VMS, networks can be handled as Ganeti networks via `gnt-network` |
|
861 |
commands. All Ganeti networks that belong to Synnefo are named with the prefix |
|
862 |
`${BACKEND_PREFIX_ID}-net-`. Also, there are a number of `snf-manage` commands |
|
863 |
for handling of `networks`, `subnets`, `ports` and `floating IPs`. Below |
|
864 |
we will present a use case scenario using some of these commands. For better |
|
865 |
understanding of these commands, refer to their help messages. |
|
866 |
|
|
867 |
Create a virtual private network for user |
|
868 |
`7cf4d078-67bf-424d-8ff2-8669eb4841ea` using the `PHYSICAL_VLAN` flavor, which |
|
869 |
means that the network will be uniquely assigned a phsyical VLAN. The network |
|
870 |
is assigned an IPv4 subnet, described by it's CIDR and gateway. Also, |
|
871 |
the `--dhcp=True` option is used, to make `nfdhcpd` respone to DHCP queries |
|
872 |
from VMs. |
|
637 | 873 |
|
638 |
Managing Virtual Machines |
|
639 |
~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
874 |
.. code-block:: console |
|
640 | 875 |
|
641 |
As mentioned, Cyclades uses Ganeti for management of VMs. The administrator can |
|
642 |
handle Cyclades VMs just like any other Ganeti instance, via `gnt-instance` |
|
643 |
commands. All Ganeti instances that belong to Synnefo, are separated from |
|
644 |
others, by a prefix in their names. This prefix is defined in |
|
645 |
``BACKEND_PREFIX_ID`` setting in |
|
646 |
``/etc/synnefo/20-snf-cyclades-app-backend.conf``. |
|
876 |
snf-manage network-create --owner=7cf4d078-67bf-424d-8ff2-8669eb4841ea --name=prv_net-1 \ |
|
877 |
--subnet=192.168.2.0/24 --gateway=192.168.2.1 --dhcp=True --flavor=PHYSICAL_VLAN |
|
647 | 878 |
|
648 |
Apart from handling instances directly in the Ganeti level, a number of `snf-manage` |
|
649 |
commands are available: |
|
879 |
Inspect the state of the network in Cyclades DB and in all the Ganeti backends: |
|
650 | 880 |
|
651 |
* ``snf-manage server-list``: List servers |
|
652 |
* ``snf-manage server-show``: Show information about a server in the Cyclades DB |
|
653 |
* ``snf-manage server-inspect``: Inspect the state of a server both in DB and Ganeti |
|
654 |
* ``snf-manage server-modify``: Modify the state of a server in the Cycldes DB |
|
655 |
* ``snf-manage server-create``: Create a new server |
|
656 |
* ``snf-manage server-import``: Import an existing Ganeti instance to Cyclades |
|
881 |
.. code-block:: console |
|
657 | 882 |
|
883 |
snf-manage network-inspect <network_id> |
|
658 | 884 |
|
659 |
Managing Virtual Networks |
|
660 |
~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
885 |
Inspect the state of the network's subnet, containg an overview of the |
|
886 |
subnet's IPv4 address allocation pool: |
|
887 |
|
|
888 |
.. code-block:: console |
|
889 |
|
|
890 |
snf-manage subnet-inspect <subnet_id> |
|
891 |
|
|
892 |
Connect a VM to the created private network. The port will be automatically |
|
893 |
be assigned an IPv4 address from one of the network's available IPs. This |
|
894 |
command will result in sending an `OP_INSTANCE_MODIFY` Ganeti command and |
|
895 |
attaching a NIC to the specified Ganeti instance. |
|
661 | 896 |
|
662 |
Cyclades is able to create and manage Virtual Networks. Networking is |
|
663 |
desployment specific and must be customized based on the specific needs of the |
|
664 |
system administrator. For better understanding of networking please refer to |
|
665 |
the :ref:`Network <networks>` section. |
|
897 |
.. code-block:: console |
|
898 |
|
|
899 |
snf-manage port-create --network=<network_id> --server=<server_id> |
|
666 | 900 |
|
667 |
Exactly as Cyclades VMs can be handled like Ganeti instances, Cyclades Networks |
|
668 |
can also by handled as Ganeti networks, via `gnt-network commands`. All Ganeti |
|
669 |
networks that belong to Synnefo are named with the prefix |
|
670 |
`${BACKEND_PREFIX_ID}-net-`. |
|
901 |
Inspect the state of the the port in Cyclades DB and in the Ganeti backend: |
|
671 | 902 |
|
672 |
There are also the following `snf-manage` commands for managing networks:
|
|
903 |
.. code-block:: console
|
|
673 | 904 |
|
674 |
* ``snf-manage network-list``: List networks |
|
675 |
* ``snf-manage network-show``: Show information about a network in the Cyclades DB |
|
676 |
* ``snf-manage network-inspect``: Inspect the state of the network in DB and Ganeti backends |
|
677 |
* ``snf-manage network-modify``: Modify the state of a network in the Cycldes DB |
|
678 |
* ``snf-manage network-create``: Create a new network |
|
679 |
* ``snf-manage network-remove``: Remove an existing network |
|
905 |
snf-manage port-inspect <port_id> |
|
906 |
|
|
907 |
Disconnect the VM from the network and delete the network: |
|
908 |
|
|
909 |
.. code-block:: console |
|
910 |
|
|
911 |
snf-manage port-remove <port_id> |
|
912 |
snf-manage network-remove <network_id> |
|
680 | 913 |
|
681 | 914 |
Managing Network Resources |
682 | 915 |
`````````````````````````` |
... | ... | |
687 | 920 |
|
688 | 921 |
* IP addresses. Cyclades creates a Pool of IPs for each Network, and assigns a |
689 | 922 |
unique IP address to each VM, thus connecting it to this Network. You can see |
690 |
the IP pool of each network by running `snf-manage network-inspect
|
|
691 |
<network_ID>`. IP pools are automatically created and managed by Cyclades,
|
|
923 |
the IP pool of each network by running `snf-manage subnet-inspect
|
|
924 |
<subnet_ID>`. IP pools are automatically created and managed by Cyclades,
|
|
692 | 925 |
depending on the subnet of the Network. |
693 | 926 |
* Bridges corresponding to physical VLANs, which are required for networks of |
694 | 927 |
type `PRIVATE_PHYSICAL_VLAN`. |
... | ... | |
1515 | 1748 |
|
1516 | 1749 |
http://docs.python.org/release/2.7.1/library/logging.html#logging-config-dictschema |
1517 | 1750 |
|
1518 |
Note that this is a feature of Python 2.7 that we have backported for use in |
|
1519 |
Python 2.6. |
|
1520 |
|
|
1521 | 1751 |
The logging configuration dictionary is defined in |
1522 | 1752 |
``/etc/synnefo/10-snf-webproject-logging.conf`` |
1523 | 1753 |
|
1524 |
The administrator can have finer logging control by modifying the |
|
1525 |
``LOGGING_SETUP`` dictionary, and defining subloggers with different handlers |
|
1526 |
and log levels. e.g. To enable debug messages only for the API set the level |
|
1527 |
of 'synnefo.api' to ``DEBUG`` |
|
1528 |
|
|
1529 |
By default, the Django webapp and snf-manage logs to syslog, while |
|
1530 |
`snf-dispatcher` logs to `/var/log/synnefo/dispatcher.log`. |
|
1754 |
The administrator can have logging control by modifying the ``LOGGING_SETUP`` |
|
1755 |
dictionary, and defining subloggers with different handlers and log levels. |
|
1531 | 1756 |
|
1532 | 1757 |
|
1533 | 1758 |
.. _scale-up: |
Also available in: Unified diff