diff --git a/devdocs/develop/nailgun/customization/partitions.rst b/devdocs/develop/nailgun/customization/partitions.rst index dd079a381..d3bfc1489 100644 --- a/devdocs/develop/nailgun/customization/partitions.rst +++ b/devdocs/develop/nailgun/customization/partitions.rst @@ -1,3 +1,5 @@ +.. _dev-create-partition: + Creating Partitions on Nodes ============================ diff --git a/plugindocs/fuel-plugin-sdk-guide/create-plugin/plugin-node-roles.rst b/plugindocs/fuel-plugin-sdk-guide/create-plugin/plugin-node-roles.rst index 09816bec0..7a1dec001 100644 --- a/plugindocs/fuel-plugin-sdk-guide/create-plugin/plugin-node-roles.rst +++ b/plugindocs/fuel-plugin-sdk-guide/create-plugin/plugin-node-roles.rst @@ -22,6 +22,7 @@ separate nodes: :maxdepth: 3 plugin-node-roles/define-new-role.rst + plugin-node-roles/volume-allocation.rst plugin-node-roles/hot-pluggable.rst plugin-node-roles/modify-ui.rst plugin-node-roles/plugin-repos.rst \ No newline at end of file diff --git a/plugindocs/fuel-plugin-sdk-guide/create-plugin/plugin-node-roles/volume-allocation.rst b/plugindocs/fuel-plugin-sdk-guide/create-plugin/plugin-node-roles/volume-allocation.rst index 282831bc2..d34cc105b 100644 --- a/plugindocs/fuel-plugin-sdk-guide/create-plugin/plugin-node-roles/volume-allocation.rst +++ b/plugindocs/fuel-plugin-sdk-guide/create-plugin/plugin-node-roles/volume-allocation.rst @@ -1,8 +1,143 @@ -:orphan: - .. _volume-allocation: Volume allocation ----------------- -TBD \ No newline at end of file +Fuel defines a set of rules for existing roles. The rules determine disk space +usage on the nodes with the specified role. Fuel partitions the disk drives +assigned to the node in accordance with these rules. + +Using the Fuel web UI, you can also tweak the disk size for a predetermined +partition on the node before the deployment. + +The plugin framework allows you to change the predefined rules and to specify +new rules for the plugin-specific roles using the file ``volumes.yaml`` in the +plugin root directory. + +The syntax of the ``volumes.yaml`` file follows the same conventions used to +define volumes for the standard Fuel roles. For reference, +see :ref:`Creating Partitions on Nodes` and +`an example of partitioning rules `_. + +.. note:: The plugin framework only allows changing disk partitioning to + an extent; you can always use some of a plugin's tasks to partition + disks with a sophisticated scheme. The main purpose of specifying + partitions with definitions in ``volumes.yaml`` is to allow + interactive resizing of partitions, which are defined by the plugin, + from the Fuel web UI before environment deployment. + +There are two primary use cases with ``volumes.yaml``: + +* Defining the disk allocation for a new role. +* Redefining the disk allocation for the existing role. + +**Define disk allocation for a new role** + +An example of an automatically generated ``volumes.yaml``: + +.. code-block:: ini + + volumes_roles_mapping: + # Default role mapping + fuel-plugin-example_role: + - {allocate_size: "all", id: "os"} + + # Set here new volumes for your role + volumes: [] + +The two sections are: + +* ``volumes_roles_mapping`` -- defines which volumes the nodes with the + given role will contain; the volumes are Fuel-defined and plugin-specific. + In the given example, there is only one rule: all the disk size is assigned + to one volume named ``"os"``. This is also the default rule, which means that + even if you define a new role but do not provide volume mapping for it, + it will be used implicitly. + +* ``volumes`` -- contains the definition of plugin-specific volumes. In the + given example, there are no plugin-specific volumes defined. + +To assign a minimal size to the OS VG and create a raw partition on all of +the remaining space: + +#. Edit ``volumes.yaml``: + + .. code-block:: ini + + volumes_roles_mapping: + fuel-plugin-example_role: + - {allocate_size: "min", id: "os"} + - {allocate_size: "all", id: "fuel-plugin-example-raw_partition"} + + volumes: + - id: fuel-plugin-example-raw_partition + type: partition + min_size: + generator: calc_gb_to_mb + generator_args: [10] + label: "Example Plugin raw partition" + mount: none + disk_label: "example" + file_system: none + +#. Synchronize the edited ``volumes.yaml`` using :command:`fuel plugins --sync`. +#. In the Fuel web UI, add a new node with the plugin's role. + +.. note:: The definitions in ``volumes.yaml`` are not retroactive. The + definitions will affect only the nodes created after + synchronization. The nodes created before synchronization + keep their previous disk partitioning. + +**Redefine disk allocation for an existing role** + +An example of adding two plugin-specific volume groups to the standard +controller role: + +.. code-block:: ini + + volumes_roles_mapping: + compute: + - {allocate_size: "min", id: "os"} + - {allocate_size: "all", id: "vm"} + - {allocate_size: "min", id: "example1"} + - {allocate_size: "min", id: "example2"} + + # Set here new volumes for your role + volumes: + - id: "example1" + type: "vg" + min_size: + generator: "calc_gb_to_mb" + generator_args: [5] + label: "Example 1" + volumes: + - mount: "/example1" + type: "lv" + name: "example1" + size: + generator: "calc_total_vg" + generator_args: ["example1"] + file_system: "ext4" + - id: "example2" + type: "vg" + min_size: + generator: "calc_gb_to_mb" + generator_args: [10] + label: "Example 2" + volumes: + - mount: "/example2" + type: "lv" + name: "example2" + size: + generator: "calc_total_vg" + generator_args: ["example2"] + file_system: "xfs" + +Although allocation of volumes for existing roles can be redefined by +a plugin, existing volumes definition cannot be changed; there will be +no error message, but you will not be able to open the settings for the +environment. If you need to redefine the partitioning for the already +existing roles, the only way to do that is to define your own volumes +and replace the standard one with them in the mappings. We do not +recommend this approach, though, as it makes the plugin incompatible +with other plugins, as well as with any updates. \ No newline at end of file