diff --git a/userdocs/fuel-install-guide.rst b/userdocs/fuel-install-guide.rst index c0f25d4aa..cc0829954 100644 --- a/userdocs/fuel-install-guide.rst +++ b/userdocs/fuel-install-guide.rst @@ -13,5 +13,6 @@ Fuel Installation Guide fuel-install-guide/bootstrap_intro fuel-install-guide/plugins_intro fuel-install-guide/vsphere_intro + fuel-install-guide/update-fuel fuel-install-guide/upgrade_intro fuel-install-guide/preinstall_intro diff --git a/userdocs/fuel-install-guide/bootstrap/bootstrap_add_package.rst b/userdocs/fuel-install-guide/bootstrap/bootstrap_add_package.rst index 546644b8e..0e6130b40 100644 --- a/userdocs/fuel-install-guide/bootstrap/bootstrap_add_package.rst +++ b/userdocs/fuel-install-guide/bootstrap/bootstrap_add_package.rst @@ -25,6 +25,15 @@ the connected external repository through the ``fuel-bootstrap`` builder script. ... Bootstrap image a778efad-88ca-41fe-b592-f02101c11d22 has been built: /root/example1/a778efad-88ca-41fe-b592-f02101c11d22.tar.gz + You can also specify a path to a custom configuration file with parameters + for building a new bootstrap instead of using parameters from the default + configuration file. + + For example: + + .. code-block:: console + + $ fuel-bootstrap build --config /etc/fuel-bootstrap-cli/my-config-xenial.yaml #. After the build process is completed, you can import and activate the new bootstrap image: diff --git a/userdocs/fuel-install-guide/bootstrap/bootstrap_builder.rst b/userdocs/fuel-install-guide/bootstrap/bootstrap_builder.rst index 372dc656c..d57247624 100644 --- a/userdocs/fuel-install-guide/bootstrap/bootstrap_builder.rst +++ b/userdocs/fuel-install-guide/bootstrap/bootstrap_builder.rst @@ -20,12 +20,12 @@ You can configure Fuel bootstrap images using the ``fuel-bootstrap`` command: .. code-block:: console - usage: fuel-bootstrap [--version] [-v] [--log-file LOG_FILE] [-q] [-h] - [--debug] + usage: fuel-bootstrap [--version] [-v] [--log-file ] [-q] [-h] + [--debug] [--config ] .. list-table:: **Optional arguments** - :widths: 10 25 + :widths: 15 25 :header-rows: 0 * - Option @@ -34,7 +34,7 @@ You can configure Fuel bootstrap images using the ``fuel-bootstrap`` command: - Shows a program's version number and exits. * - ``-v``, ``--verbose`` - Increases a verbosity of output. Can be repeated. - * - ``--log-file LOG_FILE`` + * - ``--log-file `` - Specify a file to log output. Disabled by default. * - ``-q``, ``--quiet`` - Suppress output except for warnings and errors. @@ -42,6 +42,8 @@ You can configure Fuel bootstrap images using the ``fuel-bootstrap`` command: - Shows this help message and exits. * - ``--debug`` - Shows tracebacks on errors. + * - ``--config `` + - Specify a configuration file with bootstrap settings. .. list-table:: **Commands to operate with a bootstrap image** diff --git a/userdocs/fuel-install-guide/bootstrap/bootstrap_inject_cert.rst b/userdocs/fuel-install-guide/bootstrap/bootstrap_inject_cert.rst index ed5b4925c..35ef99b16 100644 --- a/userdocs/fuel-install-guide/bootstrap/bootstrap_inject_cert.rst +++ b/userdocs/fuel-install-guide/bootstrap/bootstrap_inject_cert.rst @@ -8,7 +8,7 @@ a bootstrap using ``fuel-bootstrap``. For example, you can add custom certificates to access an https repository. -** To inject certificate files:** +**To inject certificate files:** #. Add a certificate to the Fuel Master system to provide correct work of debootstrap run on the Fuel Master node: diff --git a/userdocs/fuel-install-guide/install/install_login_fuel_master_node.rst b/userdocs/fuel-install-guide/install/install_login_fuel_master_node.rst index 92e47ad98..7d6ad26fe 100644 --- a/userdocs/fuel-install-guide/install/install_login_fuel_master_node.rst +++ b/userdocs/fuel-install-guide/install/install_login_fuel_master_node.rst @@ -81,3 +81,4 @@ initial configuration. .. seealso:: - :ref:`Log in to the Fuel Master node with multiple NICs ` + - :ref:`update_fuel` \ No newline at end of file diff --git a/userdocs/fuel-install-guide/install/install_login_fuel_master_node_multiple_nics.rst b/userdocs/fuel-install-guide/install/install_login_fuel_master_node_multiple_nics.rst index 370d40cc9..b70599a44 100644 --- a/userdocs/fuel-install-guide/install/install_login_fuel_master_node_multiple_nics.rst +++ b/userdocs/fuel-install-guide/install/install_login_fuel_master_node_multiple_nics.rst @@ -23,4 +23,4 @@ NIC. .. seealso:: - :ref:`install_login_fuel_master_node` - + - :ref:`update_fuel` \ No newline at end of file diff --git a/userdocs/fuel-install-guide/install_install_fuel.rst b/userdocs/fuel-install-guide/install_install_fuel.rst index a6c580ce3..7d12f3ec8 100644 --- a/userdocs/fuel-install-guide/install_install_fuel.rst +++ b/userdocs/fuel-install-guide/install_install_fuel.rst @@ -29,3 +29,7 @@ This section includes the following topics: install/install_login_fuel_master_node install/install_login_fuel_master_node_multiple_nics install/install_boot_slave_nodes + +.. seealso:: + + * :ref:`update_fuel` \ No newline at end of file diff --git a/userdocs/fuel-install-guide/sysreq/sysreq_fuel_slave_node_hw_recs.rst b/userdocs/fuel-install-guide/sysreq/sysreq_fuel_slave_node_hw_recs.rst index 90c4e75ec..48c064dae 100644 --- a/userdocs/fuel-install-guide/sysreq/sysreq_fuel_slave_node_hw_recs.rst +++ b/userdocs/fuel-install-guide/sysreq/sysreq_fuel_slave_node_hw_recs.rst @@ -36,6 +36,16 @@ General guidelines for the Fuel Slave nodes: nodes. Therefore, the storage configuration for every deployment will vary significantly. +* Telemetry - MongoDB nodes + Fuel deploys MongoDB version 2.6 with a replica set. To install Telemetry + with the MongoDB database, we recommend that you add three dedicated nodes. + You can also configure one MongoDB role for each controller node. + + Since a MongoDB node is configured in the polling mode, you cannot add + more than seven MongoDB nodes. This is a MongoDB limitation for voting + replica set members, and it is not controlled by Fuel. For more details, + see `MongoDB documenation `_. + .. seealso:: - `OpenStack Architecture Design Guide diff --git a/userdocs/fuel-install-guide/sysreq/sysreq_network_requirements.rst b/userdocs/fuel-install-guide/sysreq/sysreq_network_requirements.rst index e0569e8c3..a3f5e0981 100644 --- a/userdocs/fuel-install-guide/sysreq/sysreq_network_requirements.rst +++ b/userdocs/fuel-install-guide/sysreq/sysreq_network_requirements.rst @@ -152,14 +152,15 @@ The requirements for Public, Storage, and Management networks are: Neutron L2 and L3 requirements are: -* Each project's network requires one unique VLAN ID. -* Internal network must be isolated from both private and public networks - for security reasons. +* Each project's network requires one unique VLAN ID (using VLAN segmentation) or + unique segmentation ID (using GRE or VxLAN) +* Admin project network is isolated from both private and public networks for + security reasons. * For floating network each defined project, including the Admin project, requires one IP address from the floating IP address range. This IP address goes to the virtual interface of the project's virtual router. -* Each VM instance connected to the external network requires one IP address - from the floating IP range. +* Direct connection to the external network requires one IP address from the + floating IP range for each VM. * The floating IP address range should not intersect with the Public network address ranges. * Specify addresses for the guest OS DNS servers if you do not want to use diff --git a/userdocs/fuel-install-guide/update-fuel.rst b/userdocs/fuel-install-guide/update-fuel.rst new file mode 100644 index 000000000..9031bb51e --- /dev/null +++ b/userdocs/fuel-install-guide/update-fuel.rst @@ -0,0 +1,73 @@ +.. _update_fuel: + +============================ +Update Fuel to latest Mitaka +============================ + +A number of the Fuel Newton features are back-ported to Mitaka after +the Fuel Mitaka release. You can update the Fuel Master node to consume +these features. + +**To update the Fuel Master node from the initially released Mitaka to the latest Mitaka version:** + +#. Log in to the Fuel Master node CLI as root. +#. Verify that the update repository, for example, ``mos-update``, is available + in the list of your repositories: + + .. code-block:: console + + cat /etc/yum.repos.d/mos-updates.repo + + If the update repository is unavailable, run: + + .. code-block:: console + + yum-config-manager --add-repo=http://mirror.fuel-infra.org/mos-repos/centos/mos9.0-centos7/updates/x86_64/ + rpm --import http://mirror.fuel-infra.org/mos-repos/centos/mos9.0-centos7/updates/RPM-GPG-KEY-mos9.0 + +#. Clean the YUM cache: + + .. code-block:: console + + yum clean all + +#. Install a code-based integrity check tool Cudet. This tool also includes + the necessary update commands for ``fuel2``: + + .. code-block:: console + + yum install python-cudet + +#. Prepare the Fuel Master node for the Noop run: + + .. code-block:: console + + update-prepare prepare master + + This command installs new ``fuel-nailgun`` and ``fuel-astute`` + packages on the Fuel Master node. Also, it executes Nailgun ``dbsync`` + and restarts the ``astute`` and ``nailgun`` services. + + If any ``fuel-nailgun`` extension is already installed on the Fuel Master node, the + ``update-prepare`` script does not restart the Nailgun services. + You should restart the Nailgun services manually using the following + command: + + .. code-block:: console + + systemctl restart assassind nailgun oswl_flavor_collectord \ + oswl_image_collectord oswl_keystone_user_collectord \ + oswl_tenant_collectord oswl_vm_collectord oswl_volume_collectord \ + receiverd statsenderd + +#. Update the Fuel Master node packages, services, and configuration: + + .. code-block:: console + + update-prepare update master + + .. warning:: During the update procedure, the Fuel Master node services + will be restarted automatically. + + The script calls ``yum update`` and then runs Puppet tasks to update + the Fuel Master node. \ No newline at end of file diff --git a/userdocs/fuel-install-guide/upgrade/upgrade-apply-patches.rst b/userdocs/fuel-install-guide/upgrade/upgrade-apply-patches.rst deleted file mode 100644 index 3c8cb7e94..000000000 --- a/userdocs/fuel-install-guide/upgrade/upgrade-apply-patches.rst +++ /dev/null @@ -1,179 +0,0 @@ -.. _upgrade_apply_patches: - -Apply patches -------------- - -You can apply only the patches you need one by one or you can -apply all accumulated patches in one go. - -The documentation for each patch is available in the corresponding -release notes. - -.. note:: Maintenance Updates are only available online. Currently - there is no option to run these updates from a local - repository. - -Check each patch item and proceed with the instructions. - -**To patch the Fuel Master node:** - -#. Log in to the Fuel Master node. - - * If you use a local repository, update it by typing:: - - fuel-createmirror -M - -#. Run the command specified in the documentation to download and install the patch. - -**To patch a Fuel Slave node:** - -#. Run the command specified in the documentation to download and - install the patch. - -**Apply all accumulated changes in one go:** - -Before starting the update, back up all sensitive data that -can be changed during the the whole lifetime of your environment -and the Fuel Master node. We recommend to apply the updates to one -node at a time, so that you can interrupt the update procedure whenever -an issue occurs. - -If you have configured any custom repositories, Fuel will use fetch -the upgrade packages from these repositories. - -.. note:: - This set of actions should be applied carefully and with - consideration. It is strongly recommended that you do this on your - test staging environment before applying the updates to production. - -Patch the Fuel Master node -++++++++++++++++++++++++++ - -#. Back up your data with dockerctl backup. This will save the data - to ``/var/backup/fuel/``. -#. Run ``yum update``. -#. Run ``dockerctl destroy all``. -#. Run ``dockerctl start all``. -#. Wait for the new containers deployment to finish. - -Patch an Ubuntu slave node -++++++++++++++++++++++++++ - -#. Run ``apt-get update``. -#. Run ``apt-get upgrade``. -#. Apply all the additional configuration options as described in the - supporting documentation. -#. Reboot the node. - -Apply Puppet changes on a slave node -++++++++++++++++++++++++++++++++++++ - -You may want to apply all changes on a slave node or run a single -granular task so that Fuel Puppet changes take effect. - -**To run a complete Puppet cycle on a Fuel Slave node:** - -#. Update fuel-libraryX.X on Fuel Master ``yum update`` -#. Run ``fuel node --node NODE_ID --deploy`` - -**To update Puppet manifests and apply a single task:** - -#. Update fuel-libraryX.X on Fuel Master ``yum update`` -#. Run ``fuel node --node node-XX --task rsync_core_puppet hiera globals TASK`` - -.. note:: - The tasks rsync_core_puppet, hiera, and globals are required for - processing any Puppet changes. - -**Verify a patch:** - -Verify a patch on the Fuel Master node -++++++++++++++++++++++++++++++++++++++ - -To verify the packages on the Fuel Master node: - -#. Log in to the Fuel Master node CLI. -#. Type: - -:: - - yum clean expire-cache - yum -y update - -Verify a patch on a Fuel slave node -+++++++++++++++++++++++++++++++++++ - -To verify the packages are up-to-date on the Fuel Slave nodes: - -#. Log in to the Fuel Master node CLI. -#. Update the list of available packages:: - - apt-get update - -#. Update all packages:: - - apt-get dist-upgrade - -#. Log in to the Fuel Master node GUI: -#. Click :guilabel:`Support`. -#. Generate and download a diagnostic snapshot by clicking - :guilabel:`Generate Diagnostic Snapshot`. - - The Fuel Master node generates ``ubuntu_installed_debs.txt``. - -#. Analyze ``ubuntu_installed_debs.txt`` to verify the versions of the packages. - - Additionally, you can analyze the ``ubuntu_repo_list.txt`` file to verify - the repositories. - -**Roll back a patch:** - -.. note:: - The rollback instructions listed here are for advanced administrators. - -Roll back the Fuel Master node -++++++++++++++++++++++++++++++ - -#. Roll back the packages on the Fuel Master node. - `Refer to this article `__ as an example. -#. Roll back all the changes to the configuration you made when applying - the patching instructions. -#. Run ``dockerctl destroy all``. -#. Run ``dockerctl start all``. -#. Wait for bootstrap to complete. - -Roll back an Ubuntu slave node -++++++++++++++++++++++++++++++ - -You must identify the packages to roll back and where to get -their specific versions, install the packages and roll back the -changes to the configuration. - -**To roll back an Ubuntu slave node:** - -#. Evacuate all the running resources from the node. -#. Make sure no new workloads are scheduled to the node: Put nova - services in maintenance, turn on Pacemaker maintenance mode. -#. Look up the packages you want to roll back in ``/var/log/apt/history.log`` - and ``/var/log/dpkg.log``. -#. Figure out where to get the old package version. Run ``apt-cache policy``. -#. Figure out if the old package version is available locally. -#. If it is, install these versions using dpkg. Otherwise, check the - snapshots of previous repositories on - `http://mirror.fuel-infra.org/mos/snapshots` and pick the - repository that contains the packages you need. -#. Add this repository to the environment configuration. -#. On the Fuel Master node run:: - - fuel node --node-id \ - --tasks upload_core_repos - - This will propagate the new repos configuration. - -#. Install the packages with specific versions:: - - apt-get install = = - -#. Roll back all the changes to the configuration you made when applying - the patching instructions. -#. Reboot the node. diff --git a/userdocs/fuel-install-guide/upgrade/upgrade-fuel.rst b/userdocs/fuel-install-guide/upgrade/upgrade-fuel.rst deleted file mode 100644 index 78b6b2663..000000000 --- a/userdocs/fuel-install-guide/upgrade/upgrade-fuel.rst +++ /dev/null @@ -1,123 +0,0 @@ - -.. _upgrade-patch-top-ug: - -Upgrade the Fuel Master node ----------------------------- - -If you have a functional Fuel installation, you can -upgrade the Fuel software to the latest version -without reinstalling your environments. - -.. note:: - Upgrades are not supported for Fuel 4.x or earlier. If you use Fuel 4.x - or earlier, you must install new instance of Fuel and deploy your - environments from scratch. - -After you upgrade Fuel, you can only deploy new environments of the -corresponding Fuel version. Environments deployed using older versions -of Fuel will remain operational. - -**To upgrade the Fuel Master node:** - -#. Verify that no installations are in progress in any of your OpenStack - environments. - -#. Download and install the ``fuel-octane`` package using the ``yum install`` - command: - - .. code-block:: console - - $ yum install fuel-octane - -#. Back up the configuration of - the Fuel Master node to an archive: - - .. code-block:: console - - octane fuel-backup --to - - **Example:** - - .. code-block:: console - - $ octane fuel-backup --to /tmp/fuel-backup.7.0.tar.gz - -#. Back up package repositories and other binary artifacts from the Fuel - Master node: - - **Example:** - - .. code-block:: console - - $ octane fuel-repo-backup --to /tmp/fuel-repo-backup.7.0.tar.gz - -#. Copy the backup files to a secure external location, such as - a removable USB drive or network server. If you copy the files to - a network server, use SSH. - - .. note:: - - When you reinstall the Fuel Master node, all configuration files are - deleted. Therefore, if you fail to back up the Fuel Master node and - repository configuration files, you will not be able to manage the - OpenStack environments created by the old version of Fuel. - -#. Power off the Fuel Master node. - -#. Install the latest version of the Fuel Master node as described in - :ref:`install_intro`. - - .. note:: - - The new Fuel Master node must have the same IP address as the original - Fuel Master node. Otherwise, you cannot restore the configuration from - the backup. - - -#. Copy the backup files to the location on the new Fuel Master node. - - For example, in the ``/tmp`` directory. - -#. Log in to the new Fuel Master node. - -#. Install the ``fuel-octane`` package: - - .. code-block:: console - - $ yum install fuel-octane - -#. Restore the configuration of the original Fuel Master node and the OpenStack - environments: - - .. code-block:: console - - $ octane fuel-restore --from /tmp/fuel-backup.7.0.tar.gz - --admin-password ADMIN_PASSWORD - -#. Restore repositories and binary artifacts from the old version: - - **Example:** - - .. code-block:: console - - $ octane fuel-repo-restore --from /tmp/fuel-repo-backup.7.0.tar.gz - - .. warning:: - - The Fuel Master node must have at least 2 GB of RAM - to decompress the ``gzip`` upgrade archive. - - When Fuel completes the upgrade, the *New Release available* message appears - in the :guilabel:`Releases` tab. - -#. If you want to use CentOS-based bootstrap, rebuild the bootstrap image: - - .. code-block:: console - - $ octane update-bootstrap-centos - -#. Reboot all nodes that are in the ``Discover`` status. - -.. seealso:: - - - :ref:`Configure a bootstrap image `. diff --git a/userdocs/fuel-install-guide/upgrade/upgrade-internals.rst b/userdocs/fuel-install-guide/upgrade/upgrade-internals.rst index 33ef92dfb..20b4dcb70 100644 --- a/userdocs/fuel-install-guide/upgrade/upgrade-internals.rst +++ b/userdocs/fuel-install-guide/upgrade/upgrade-internals.rst @@ -1,10 +1,10 @@ - .. _upgrade-internals: -Overview of the Fuel upgrade process ------------------------------------- +======== +Overview +======== -The upgrade is implemented with three upgrade engines, which are python +The upgrade is implemented with upgrade engines, which are python modules: * **Host system engine:** @@ -13,16 +13,6 @@ modules: #. Installs a package and all the required dependencies such as Puppet manifests, bootstrap images, provisioning images etc. -* **Docker engine:** - - #. Points the supervisor to a new directory with the configuration - files. No containers are started by the supervisor at this time. - #. Stops old containers. - #. Uploads new Docker images. - #. Runs containers one by one. - #. Generates new supervisor configuration files. - #. Verifies the services running in the containers. - * **OpenStack engine:** #. Installs all data required for OpenStack patching. diff --git a/userdocs/fuel-install-guide/upgrade/upgrade-liberty.rst b/userdocs/fuel-install-guide/upgrade/upgrade-liberty.rst new file mode 100644 index 000000000..b84da0150 --- /dev/null +++ b/userdocs/fuel-install-guide/upgrade/upgrade-liberty.rst @@ -0,0 +1,36 @@ +.. _upgrade_liberty: + +============================== +Upgrade Fuel Liberty to Mitaka +============================== + +You can upgrade the Fuel Master node from Liberty to Mitaka. +After you upgrade Fuel, you can only deploy new environments of the +corresponding Fuel version. Environments deployed using older versions +of Fuel will remain operational. + +**To upgrade the Fuel Master node:** + +#. Verify that no installations are in progress in any of your OpenStack + environments. +#. Back up the Fuel Master node as described in :ref:`back-up-fuel`. +#. Power off the Fuel Master node. +#. Restore the Fuel Master node as described in :ref:`restore-fuel`. +#. If you want to use CentOS-based bootstrap, rebuild the bootstrap image: + + .. code-block:: console + + $ octane update-bootstrap-centos + +#. Reboot all nodes that are in the ``Discover`` status. + +When Fuel completes the upgrade procedure, the *New Release available* +message appears in the :guilabel:`Releases` tab. + +Now, you can update to the latest Mitaka version that includes some features +back-ported from Newton after the Mitaka release. + +.. seealso:: + + * :ref:`update_fuel` + * :ref:`install_configure_bootstrap` \ No newline at end of file diff --git a/userdocs/fuel-install-guide/upgrade/upgrade-local-repo.rst b/userdocs/fuel-install-guide/upgrade/upgrade-local-repo.rst index a61b63e4a..ef1666b1f 100644 --- a/userdocs/fuel-install-guide/upgrade/upgrade-local-repo.rst +++ b/userdocs/fuel-install-guide/upgrade/upgrade-local-repo.rst @@ -35,7 +35,7 @@ or through Fuel CLI using the ``fuel-createmirror`` script. fuel-createmirror --password PASSWORD -#. Restart the the docker daemon +#. Restart the docker daemon :: diff --git a/userdocs/fuel-install-guide/upgrade_intro.rst b/userdocs/fuel-install-guide/upgrade_intro.rst index 02d10e20a..f5ab54cfb 100644 --- a/userdocs/fuel-install-guide/upgrade_intro.rst +++ b/userdocs/fuel-install-guide/upgrade_intro.rst @@ -1,87 +1,20 @@ -.. raw:: pdf - - PageBreak oneColumn - .. _upgrade_intro: +============ Upgrade Fuel -~~~~~~~~~~~~ +============ -You can upgrade the Fuel Master node to the latest Fuel version. - -The following table describes available upgrades for the Fuel software: - -+----------------------+------------------------+--------------------------+ -| Initial Fuel version | Fuel is upgraded to | Upgraded Fuel can manage | -+======================+========================+==========================+ -| 5.0 | 5.1, then to 5.1.1, | 2014.1-5.0 | -| | then to 6.0 | | -| | | 2014.1.1-5.0.2 | -| | | | -| | | 2014.1.1-5.1 | -| | | | -| | | 2014.1.3-5.1.1 | -| | | | -| | | 2014.2-6.0 | -+----------------------+------------------------+--------------------------+ -| 5.0 | 5.0.1, then to 5.1, | 2014.1-5.0 | -| | | | -| | then to 5.1.1 | 2014.1.1-5.0.1 | -| | | | -| | then to 6.0 | 2014.1.1-5.0.2 | -| | | | -| | | 2014.1.1-5.1 | -| | | | -| | | 2014.1.3-5.1.1 | -| | | | -| | | 2014.2-6.0 | -+----------------------+------------------------+--------------------------+ -| 5.0.1 | 5.1, then to 5.1.1 | 2014.1.1-5.0.1 | -| | | | -| | then to 6.0 | 2014.1.1-5.0.2 | -| | | | -| | | 2014.1.1-5.1 | -| | | | -| | | 2014.1.3-5.1.1 | -| | | | -| | | 2014.2-6.0 | -+----------------------+------------------------+--------------------------+ -| 5.1 | 5.1.1, then to 6.0 | 2014.1.1-5.1 | -| | | | -| | | 2014.1.3-5.1.1 | -| | | | -| | | 2014.2-6.0 | -+----------------------+------------------------+--------------------------+ -| 6.0 | 6.1, then apply all 6.1| 2014.2.6.0 | -| | updates, then to 7.0 | 2014.2.2-6.1 | -| | | 2015.x-7.0 | -| | | | -| | | | -| | | | -+----------------------+------------------------+--------------------------+ -| 6.1 | Apply all 6.1 updates, | 2014.2-6.0 | -| | | | -| | then to 7.0 | 2014.2.2-6.1 | -| | | | -| | | 2015.x-7.0 | -| | | | -+----------------------+------------------------+--------------------------+ -| 7.0 | Apply all 7.0 updates, | 2014.2.2-6.1 | -| | | | -| | then to 8.0 | 2015.1.0-7.0 | -| | | | -| | | liberty-8.0 | -+----------------------+------------------------+--------------------------+ +If you have a functional Fuel installation, you can upgrade the Fuel software +to the latest version without reinstalling your environments. This section includes the following topics. .. toctree:: - :maxdepth: 3 + :maxdepth: 1 - upgrade/upgrade-fuel upgrade/upgrade-internals + upgrade/upgrade-liberty upgrade/upgrade-local-repo - upgrade/upgrade-apply-patches .. note:: Fuel does not support upgrades for plugins. The old plugin versions may not be compatible with the new version of Fuel. diff --git a/userdocs/fuel-user-guide/cli.rst b/userdocs/fuel-user-guide/cli.rst index b58526bcc..7932a72e0 100644 --- a/userdocs/fuel-user-guide/cli.rst +++ b/userdocs/fuel-user-guide/cli.rst @@ -16,7 +16,7 @@ when you install Fuel. Using the Fuel CLI you can: your environment if not used carefully. Modifications that you make using the Fuel CLI take precedence over the -settings applied from the Fuel Web UI. If a change has been applied using +settings applied from the Fuel web UI. If a change has been applied using the Fuel CLI, Fuel displays the corresponding message in the Fuel web UI. This section includes the following topics: @@ -24,11 +24,13 @@ This section includes the following topics: .. toctree:: :maxdepth: 3 + cli/cli_comparison_matrix.rst cli/cli_acronyms.rst cli/cli_basic_usage.rst cli/cli_client_config_file.rst cli/cli_management.rst cli/cli_environment.rst + cli/cli_provision.rst cli/cli_deploy.rst cli/cli_network.rst cli/cli_network_group.rst @@ -37,9 +39,11 @@ This section includes the following topics: cli/cli_nodes.rst cli/cli_node_group.rst cli/cli_roles.rst + cli/cli_nodes_empty_role.rst cli/cli_plugins.rst cli/cli_graphs.rst cli/cli_config_openstack.rst cli/cli_config_openstack_services_workflow.rst cli/cli_change_ip_range.rst cli/cli_modify_environment.rst + cli/cli_noop.rst diff --git a/userdocs/fuel-user-guide/cli/cli_acronyms.rst b/userdocs/fuel-user-guide/cli/cli_acronyms.rst index 0af1f7e3e..6a088ee59 100644 --- a/userdocs/fuel-user-guide/cli/cli_acronyms.rst +++ b/userdocs/fuel-user-guide/cli/cli_acronyms.rst @@ -1,26 +1,23 @@ - .. _cli-acronyms: - +=========================================== Interpretation of acronyms in Fuel commands -------------------------------------------- +=========================================== -CLI commands contain a number -of acronyms. -For better understanding of those, -see the example command output below. +.. include:: /userdocs/snippets/notes/deprecated-cli-v1.rst +Fuel CLI commands contain a number of acronyms. For a better understanding of +those, see the example command output below. .. note:: Nailgun populates the database with hardware configuration information about all the managed nodes it discovers as well as the configuration and status of each node. -The ``fuel node list`` command is used on the Fuel Master node -to list out the current information about the nodes -for the environment: +The :command:`fuel node list` command is used on the Fuel Master node to list out +the current information about the nodes for the environment: -:: +.. code-block:: console [root@fuel ~]# fuel nodes @@ -87,13 +84,12 @@ The meaning of these fields is: The following two columns appear at the right end of this display; they are not shown here: -:pending_roles: Before deployment, lists the roles that have been assigned to this node. - When deployment is complete, - the contents of this field are moved to the **roles** column +:pending_roles: Before deployment, lists the roles that have been assigned + to this node. When deployment is complete, the contents + of this field are moved to the **roles** column. - For Release 6.x and later, - this field can also contain the **primary** value - to indicate that this node is the Primary Controller node. + This field can also contain the **primary** value + to indicate that this node is the primary controller node. The **primary** value is persisted in the database through the use of the **has_primary** field in the ``openstack.yaml`` file. @@ -106,7 +102,5 @@ they are not shown here: :group_id: The group node identifier. When you assign roles to your target nodes, - Fuel tries to automatically determine the node's group based on the DHCP address. - - - + Fuel tries to automatically determine the node's group based on + the DHCP address. diff --git a/userdocs/fuel-user-guide/cli/cli_basic_usage.rst b/userdocs/fuel-user-guide/cli/cli_basic_usage.rst index d23eee97d..89ea43ae2 100644 --- a/userdocs/fuel-user-guide/cli/cli_basic_usage.rst +++ b/userdocs/fuel-user-guide/cli/cli_basic_usage.rst @@ -1,7 +1,10 @@ .. _cli_basic_usage: +=========== Basic usage ------------ +=========== + +.. include:: /userdocs/snippets/notes/deprecated-cli-v1.rst Use the following usage pattern for Fuel commands: diff --git a/userdocs/fuel-user-guide/cli/cli_change_ip_range.rst b/userdocs/fuel-user-guide/cli/cli_change_ip_range.rst index 50084b430..874b67043 100644 --- a/userdocs/fuel-user-guide/cli/cli_change_ip_range.rst +++ b/userdocs/fuel-user-guide/cli/cli_change_ip_range.rst @@ -1,9 +1,10 @@ - .. _cli_change_ip_range: - +================== Add network ranges ------------------- +================== + +.. include:: /userdocs/snippets/notes/deprecated-cli-v1.rst To add network ranges, edit the network configuration file: add the IP network range to ``ip_ranges`` and change diff --git a/userdocs/fuel-user-guide/cli/cli_client_config_file.rst b/userdocs/fuel-user-guide/cli/cli_client_config_file.rst index 23802b417..34bbe80c7 100644 --- a/userdocs/fuel-user-guide/cli/cli_client_config_file.rst +++ b/userdocs/fuel-user-guide/cli/cli_client_config_file.rst @@ -1,7 +1,10 @@ .. _cli-client-config-file: +====================================== Modify the Fuel CLI configuration file --------------------------------------- +====================================== + +.. include:: /userdocs/snippets/notes/deprecated-cli-v1.rst The Fuel CLI uses the ``fuel_client.yaml`` file as a source for default settings. By default, Fuel stores the ``fuel_client.yaml`` file in the diff --git a/userdocs/fuel-user-guide/cli/cli_comparison_matrix.rst b/userdocs/fuel-user-guide/cli/cli_comparison_matrix.rst new file mode 100644 index 000000000..5602bf805 --- /dev/null +++ b/userdocs/fuel-user-guide/cli/cli_comparison_matrix.rst @@ -0,0 +1,118 @@ +.. _cli_comparison_matrix: + +=================================== +Fuel CLI commands comparison matrix +=================================== + +The Fuel command-line interface has been changed to simplify usage +and improve user experience. Some of the keys and options have been modified +as well. Although the old ``fuel`` commands are still available, we recommend that +you use the new ``fuel2`` commands instead. The following table describes +new ``fuel2`` commands and their alternatives in the ``fuel`` CLI. + +.. csv-table:: **Fuel CLI commands comparison matrix** + :header: Command in ``fuel2`` CLI, Description, Alternative in ``fuel`` CLI + :widths: 8, 7, 7 + + ``fuel2 complete``, Print the completion of a command in CLI, None + ``fuel2 help``, Print a detailed help for all commands, ``fuel --help`` + ``fuel2 env add nodes``, Add nodes to an environment with specified roles, ``fuel node --set`` + ``fuel2 env create``, Create an environment with given attributes, ``fuel env --create`` + ``fuel2 env delete``, Delete an environment with a given ID, ``fuel env --delete`` + ``fuel2 env deploy``, Deploy changes on a specified environment, ``fuel deploy-changes`` + ``fuel2 env deployment-facts delete``, Delete current deployment facts, ``fuel deployment --delete`` + ``fuel2 env deployment-facts download``, Download the user-defined deployment facts, ``fuel deployment --download`` + ``fuel2 env deployment-facts get-default``, Download the default deployment facts, ``fuel deployment --default`` + ``fuel2 env deployment-facts upload``, Upload deployment facts, ``fuel deployment --upload`` + ``fuel2 env extension disable``, Disable specified extensions for an environment with a given ID, None + ``fuel2 env extension enable``, Enable specified extensions for an environment with a given ID, None + ``fuel2 env extension list``, Show a list of all available extensions, None + ``fuel2 env extension show``, Show a list of enabled extensions for an environment with a given ID, None + ``fuel2 env list``, Show a list of all available environments, ``fuel env`` + ``fuel2 env network download``, Download and store network configuration of an environment, ``fuel network --download`` + ``fuel2 env network upload``, Upload network configuration and apply it to an environment, ``fuel network --upload`` + ``fuel2 env network verify``, Run network verification for a specified environment, ``fuel network --verify`` + ``fuel2 env nodes deploy``, Deploy specified nodes for a specified environment, ``fuel node --deploy`` + ``fuel2 env nodes provision``, Provision specified nodes for a specified environment, ``fuel node --provision`` + ``fuel2 env provisioning-facts delete``, Delete current provisioning facts, ``fuel provisioning --delete`` + ``fuel2 env provisioning-facts download``, Download the user-defined provisioning facts, ``fuel provisioning --download`` + ``fuel2 env provisioning-facts get-default``, Download the default provisioning facts, ``fuel provisioning --default`` + ``fuel2 env provisioning-facts upload``, Upload provisioning facts, ``fuel provisioning --upload`` + ``fuel2 env redeploy``, Redeploy changes on a specified environment, ``fuel redeploy-changes`` + ``fuel2 env remove nodes``, Remove nodes from an environment, ``fuel node remove`` + ``fuel2 env reset``, Reset a deployed environment, ``fuel reset`` + ``fuel2 env settings download``, Download and store an environment settings, ``fuel settings --download`` + ``fuel2 env settings upload``, Upload and apply an environment settings, ``fuel settings --upload`` + ``fuel2 env show``, Show information about environment with a given ID, None + ``fuel2 env spawn-vms``, Provision a specified environment, None + ``fuel2 env stop-deployment``, Stop deployment process for a specific environment, ``fuel stop`` + ``fuel2 env update``, Change given attributes for an environment, ``fuel env --set`` + ``fuel2 fuel-version``, Show the current version of Fuel, ``fuel --fuel-version`` + ``fuel2 graph download``, Download a deployment graph configuration, ``fuel env --deployment-tasks --download`` + ``fuel2 graph execute``, Start a deployment with a given graph type, None + ``fuel2 graph list``, List deployment graphs, None + ``fuel2 graph upload``, Upload a deployment graph configuration, ``fuel env --deployment-tasks --upload`` + ``fuel2 network-group create``, Create a new network group, ``fuel network-group --create`` + ``fuel2 network-group delete``, Delete a specified network group, ``fuel network-group --delete`` + ``fuel2 network-group list``, List all network groups, ``fuel network-group`` + ``fuel2 network-group show``, Show a specified network group, None + ``fuel2 network-group update``, Set parameters for a specified network group, ``fuel network-group --set`` + ``fuel2 network-template delete``, Delete the network template of a specified environment, ``fuel network-template --delete`` + ``fuel2 network-template download``, Download the network configuration for a specified environment, ``fuel network-template --download`` + ``fuel2 network-template upload``, Upload the network configuration for a specified environment, ``fuel network-template --upload`` + ``fuel2 node ansible-inventory``, Generate an ansible inventory file based on the nodes list, None + ``fuel2 node attributes-download``, Download attributes of a specified node, None + ``fuel2 node attributes-upload``, Upload attributes of a specified node, None + ``fuel2 node create-vms-conf``, Create the VMs configuration in metadata for a specified node, None + ``fuel2 node disks download``, Download and store configuration of disks for a node to a file, ``fuel node --disk --download`` + ``fuel2 node disks get-default``, Download the default configuration of disks for a node to a file, ``fuel node --disk --default`` + ``fuel2 node disks upload``, Upload a stored configuration of disks for a node from a file, ``fuel node --disk --upload`` + ``fuel2 node interfaces download``, Download and store a configuration of interfaces for a node to a file, ``fuel node --network --download`` + ``fuel2 node interfaces get-default``, Download the default configuration of interfaces for a node to a file, ``fuel node --network --default`` + ``fuel2 node interfaces upload``, Upload the stored configuration of interfaces for a node from a file, ``fuel node --network --download`` + ``fuel2 node label delete``, Delete specific labels on nodes, None + ``fuel2 node label list``, Show a list of all labels, None + ``fuel2 node label set``, Create or update specific labels on nodes, None + ``fuel2 node list``, Show a list of all available nodes, ``fuel node`` + ``fuel2 node list-vms-conf``, Show a list of VMs for a node, None + ``fuel2 node show``, Show information about a node with a given ID, None + ``fuel2 node undiscover``, Remove nodes from a database, ``fuel node --delete-from-db`` + ``fuel2 node update``, Change a node name and/or host name, ``fuel node --name `` and/or ``fuel node --hostname `` + ``fuel2 openstack-config delete``, Delete an OpenStack configuration with a given ID, ``fuel openstack-config --delete`` + ``fuel2 openstack-config download``, Download a specified OpenStack configuration file, ``fuel openstack-config --download`` + ``fuel2 openstack-config execute``, Execute an OpenStack configuration deployment, ``fuel openstack-config --execute`` + ``fuel2 openstack-config list``, List all OpenStack configurations, ``fuel openstack-config --list`` + ``fuel2 openstack-config upload``, Upload a new OpenStack configuration from file, ``fuel openstack-config --upload`` + ``fuel2 plugins list``, Show a list of all available plugins, ``fuel plugins --list`` + ``fuel2 plugins sync``, Synchronize plugins on a file system with plugins in the API service, ``fuel plugins --sync`` + ``fuel2 release component list``, Show a list of components for a given release, None + ``fuel2 release list``, Show a list of all available releases, ``fuel release`` + ``fuel2 release repos list``, Show repositories for a given release, None + ``fuel2 release repos update``, Update repositories for a given release, None + ``fuel2 role create``, Create a role from a file description, ``fuel role --rel 1 --create`` + ``fuel2 role delete``, Delete a role from an OpenStack release, ``fuel role --delete`` + ``fuel2 role download``, Download a full role description to a file, ``fuel role --file`` + ``fuel2 role list``, Show a list of all available roles for a release, ``fuel role`` + ``fuel2 role update``, Update a role description from a file, ``fuel role --update`` + ``fuel2 sequence create``, Create a new deployment sequence, None + ``fuel2 sequence upload``, Upload a new deployment sequence, None + ``fuel2 sequence download``, Download a deployment sequence data, None + ``fuel2 sequence delete``, Delete an existing sequence, None + ``fuel2 sequence update``, Update an existing sequence, None + ``fuel2 sequence list``, Show a list of all existing sequences, None + ``fuel2 sequence show``, Display information about a sequence, None + ``fuel2 sequence execute``, Execute a sequence on a specified environment, None + ``fuel2 snapshot create``, Generate a diagnostic snapshot, ``fuel snapshot`` + ``fuel2 snapshot create -c/--config``, Generate a diagnostic snapshot with a custom configuration, ``fuel snapshot < config_file.yml`` + ``fuel2 snapshot get-default-config``, Download the default configuration to generate a custom diagnostic snapshot, ``fuel snapshot --conf > config_file.yml`` + ``fuel2 snapshot get-link``, Show the link to download diagnostic snapshot, None + ``fuel2 task delete``, Delete a task with a given ID, ``fuel task --delete`` + ``fuel2 task deployment-info download``, Save a task deployment information to a file, None + ``fuel2 task history show``, Show a deployment history about a task with a given ID, None + ``fuel2 task list``, Show a list of all available tasks, None + ``fuel2 task network-configuration download``, Save a task network configuration to a file, None + ``fuel2 task settings download``, Download and save a task settings to a file, None + ``fuel2 task show``, Show information about a task with a given ID, None + ``fuel2 vip create``, Create a VIP, ``fuel vip --create`` + ``fuel2 vip download``, Download a configuration of VIPs, ``fuel vip --download`` + ``fuel2 vip upload``, Upload a new configuration of VIPs from a file, ``fuel vip --upload`` diff --git a/userdocs/fuel-user-guide/cli/cli_config_openstack.rst b/userdocs/fuel-user-guide/cli/cli_config_openstack.rst index 118e1e69b..d13789516 100644 --- a/userdocs/fuel-user-guide/cli/cli_config_openstack.rst +++ b/userdocs/fuel-user-guide/cli/cli_config_openstack.rst @@ -1,7 +1,10 @@ .. _cli-config-openstack-services: +================================================== Modify the configuration of the OpenStack services --------------------------------------------------- +================================================== + +.. include:: /userdocs/snippets/notes/deprecated-cli-v1.rst You can customize the hardcoded, or provided by Nailgun, configuration values, as well as introduce new configuration options @@ -23,30 +26,28 @@ defined. #. Log in to the Fuel Master node. #. Edit the ``.yaml`` file with the configuration options of the services that - you want to change. + you want to change. **Example:** - :: + .. code-block:: yaml - .. code-block:: yaml - - configuration: - nova_config: - DEFAULT/debug: - value: True - DEFAULT/amqp_durable_queues: - value: False - keystone_config: - DEFAULT/default_publisher_id: - ensure: absent - DEFAULT/crypt_strength: - value: 6000 + configuration: + nova_config: + DEFAULT/debug: + value: True + DEFAULT/amqp_durable_queues: + value: False + keystone_config: + DEFAULT/default_publisher_id: + ensure: absent + DEFAULT/crypt_strength: + value: 6000 #. Upload the ``.yaml`` file: * To upload the changes for an OpenStack environment: - + .. code-block:: console fuel openstack-config --env --upload file.yaml @@ -55,7 +56,7 @@ defined. .. code-block:: console - fuel openstack-config --env --role compute \ + fuel openstack-config --env --role compute \ --upload * To upload the changes for selected nodes: @@ -86,6 +87,7 @@ defined. fuel openstack-config --env --node 1,2,3 --execute The services will restart automatically. + #. Optionally, run these additional commands: #. List the configuration changes history: @@ -94,6 +96,9 @@ defined. fuel openstack-config --env --list + .. note:: The :option:`--list` parameter shows historical data only + for the active configuration. + #. Download the previously uploaded ``.yaml`` file with the configuration changes: @@ -103,7 +108,7 @@ defined. fuel openstack-config --env --list - #. Download the ``.yaml`` file: + #. Download the ``.yaml`` file: .. code-block:: console diff --git a/userdocs/fuel-user-guide/cli/cli_deploy.rst b/userdocs/fuel-user-guide/cli/cli_deploy.rst index 674c8f352..0d6161f5c 100644 --- a/userdocs/fuel-user-guide/cli/cli_deploy.rst +++ b/userdocs/fuel-user-guide/cli/cli_deploy.rst @@ -1,24 +1,31 @@ .. _cli-deploy: +=================== Deployment commands -------------------- +=================== -The following table describes the deployment commands -available in the Fuel CLI. +.. include:: /userdocs/snippets/notes/deprecated-cli-v1.rst + +The following table describes the usage of the :command:`fuel deployment` +command available in the Fuel CLI. .. list-table:: **Deployment commands** - :widths: 10 10 20 + :widths: 7 10 :header-rows: 1 * - Description - Command - - Example - * - Deploy an OpenStack environment. - - ``fuel --env deploy-changes`` - - - * - Deploy specific nodes. - - ``fuel node --deploy --node ,`` - - - * - Provision specific nodes. - - ``fuel node --provision --node ,`` - - + * - Delete current deployment data + - ``fuel --env deployment --delete`` + * - Download current deployment data + - ``fuel --env deployment --download`` + * - Download default deployment data + - ``fuel --env deployment --default`` + * - Get default deployment information for specific nodes + - ``fuel --env deployment --default --node `` + * - Upload provisioning deployment to a specific directory + - ``fuel --env deployment -u --dir path/to/directory`` + * - Download deployment information to a specific directory + - ``fuel --env deployment -d --dir path/to/directory`` + + diff --git a/userdocs/fuel-user-guide/cli/cli_environment.rst b/userdocs/fuel-user-guide/cli/cli_environment.rst index 4941e5d7d..d6ab5bd3f 100644 --- a/userdocs/fuel-user-guide/cli/cli_environment.rst +++ b/userdocs/fuel-user-guide/cli/cli_environment.rst @@ -1,7 +1,10 @@ .. _cli-environment: +==================== Environment commands --------------------- +==================== + +.. include:: /userdocs/snippets/notes/deprecated-cli-v1.rst The following table describes environment management commands available in the Fuel CLI. @@ -17,28 +20,27 @@ available in the Fuel CLI. - ``fuel env`` - * - Create an environment. - - ``fuel env create --name --rel `` + - ``fuel env create --name --rel `` - By default, Fuel creates an OpenStack environment in the ``multinode`` mode, and the ``nova`` network mode. To specify other modes, you can add optional arguments: - :: + .. code-block:: console - fuel env create --name --rel \ + fuel env create --name --rel \ --mode ha --network-mode neutron --net-segment-type vlan Use the ``set`` action to change the name, mode, or network mode for an OpenStack environment: - :: + .. code-block:: console - fuel --env env set --name --mode ha_compact + fuel --env env set --name --mode ha_compact * - Delete an OpenStack environment. - - ``fuel --env env delete`` + - ``fuel --env env delete`` - * - Update the OpenStack environment to a newer version. To roll back a failed update, use the same command with the previous release number. - - ``fuel env --update --env --rel `` + - ``fuel env --update --env --rel `` - - diff --git a/userdocs/fuel-user-guide/cli/cli_graphs.rst b/userdocs/fuel-user-guide/cli/cli_graphs.rst index 88f6b3c63..ec2b9eed4 100644 --- a/userdocs/fuel-user-guide/cli/cli_graphs.rst +++ b/userdocs/fuel-user-guide/cli/cli_graphs.rst @@ -1,13 +1,11 @@ .. _cli-graphs: +===================================== Deployment graphs management commands -------------------------------------- +===================================== The following table describes the deployment graphs management commands -supported by the Fuel CLI v2. To execute these commands, you need to have -the Fuel CLI installed as described in `Install the OpenStack -command-line clients `_. -No additional configuration is required. +supported by the Fuel CLI. .. list-table:: **Deployment graphs management commands** :widths: 15 20 @@ -25,7 +23,7 @@ No additional configuration is required. * ``fuel2 graph upload --release [--type graph_type] --file tasks.yaml`` * ``fuel2 graph upload --plugin [--type graph_type] --file tasks.yaml`` - | The ``--type`` parameter is optional. If not specified, the default graph is downloaded. + | The ``--type`` parameter is optional. If not specified, the default graph is uploaded. * - Download deployment graphs from a certain environment. Use the ``--all``, ``--cluster``, ``--release``, or ``plugins`` flag to specify the level of the graphs to download. - * ``fuel2 graph download --env --all [--type ] [--file ]`` @@ -35,7 +33,17 @@ No additional configuration is required. | The ``--type`` parameter is optional. If not specified, the default graph is downloaded. + | The graphs downloaded with the keys ``--all`` and ``--plugins`` are the + result of other graphs merge. They are not supposed to be edited and uploaded back, + because, in most cases, they will override further changes in source graphs. + * - Execute deployment graphs. Available for environments only. - ``fuel2 graph execute --env [--type ] [--node ]`` - | The ``--type`` parameter is optional. If not specified, the default graph is downloaded. \ No newline at end of file + | The ``--type`` parameter is optional. If not specified, the default graph is downloaded. + + * - Run any task graph in a ``noop`` mode to detect customizations. + - ``fuel2 graph execute --env [--type ] --noop --force`` + + | The ``--force`` parameter is optional and is necessary for previously + executed graphs or tasks to prevent tasks skipping by Fuel LCM engine. \ No newline at end of file diff --git a/userdocs/fuel-user-guide/cli/cli_management.rst b/userdocs/fuel-user-guide/cli/cli_management.rst index 5f2679c9d..49cd17ec0 100644 --- a/userdocs/fuel-user-guide/cli/cli_management.rst +++ b/userdocs/fuel-user-guide/cli/cli_management.rst @@ -1,7 +1,10 @@ .. _cli-management: +======================== Fuel management commands ------------------------- +======================== + +.. include:: /userdocs/snippets/notes/deprecated-cli-v1.rst The following table describes basic management commands available in the Fuel CLI. @@ -19,7 +22,7 @@ available in the Fuel CLI. .. code-block:: console - fuel --help + fuel --help * - View the list of all available releases - ``fuel release`` diff --git a/userdocs/fuel-user-guide/cli/cli_modify_environment.rst b/userdocs/fuel-user-guide/cli/cli_modify_environment.rst index 621dd1982..5645cc205 100644 --- a/userdocs/fuel-user-guide/cli/cli_modify_environment.rst +++ b/userdocs/fuel-user-guide/cli/cli_modify_environment.rst @@ -1,7 +1,10 @@ .. _cli-modify-env: +========================================= Modify an Openstack environment using CLI ------------------------------------------ +========================================= + +.. include:: /userdocs/snippets/notes/deprecated-cli-v1.rst You can modify your OpenStack environment after deployment by downloading the ``.yaml`` configuration files, editing settings, and @@ -9,7 +12,7 @@ then uploading the configuration files back to the Nailgun server. After uploading the files, you must redeploy your OpenStack environment. -Before modifying any settings, back up your OpenStack environment +Before modifying any settings, back up your OpenStack environment configuration. If you upload any changes for provisioning or deployment operations, @@ -22,15 +25,49 @@ each node's configuration file and then apply the changes using Fuel CLI. You can download the following configurations: * ``network`` -* ``settings`` +* ``settings`` * ``node --disk`` * ``node --network`` * ``provisioning`` * ``deployment`` -.. note:: - Operations with ``deployment`` and ``provisioning`` can be node - specific. For example: ``fuel --env 1 deployment --node-id=1,2``. +When performing operations with nodes using :command:`fuel deployment` and +:command:`fuel provisioning` commands, you can indicate specific nodes. +For example: + +.. code-block:: console + + fuel --env 1 deployment --node 1,2,3 + +When downloading configurations using :command:`fuel deployment` and +:command:`fuel provisioning` commands, Fuel automatically generates +the following files: + +* For deployment: + + ``master.yaml`` + Includes details about the Fuel Master node configuration for a specified + OpenStack environment. + + ``.yaml`` + Includes details about the node deployment. The ``.yaml`` file + contains deployment details and is identical to the ``astute.yaml`` file + stored on a specific node. The deployment tasks consume parameters + included in ``.yaml`` through hiera. + +* For provisioning: + + ``engine.yaml`` + Includes credentials for the provisioning service (Cobbler) engine. + + ``node-.yaml`` + Includes details about provisioning for each node. + +.. seealso:: + + * :ref:`file-ref` + * :ref:`cli-provision` + * :ref:`cli-deploy` **To modify an OpenStack environment using CLI:** diff --git a/userdocs/fuel-user-guide/cli/cli_network.rst b/userdocs/fuel-user-guide/cli/cli_network.rst index 74aea306e..95d093be7 100644 --- a/userdocs/fuel-user-guide/cli/cli_network.rst +++ b/userdocs/fuel-user-guide/cli/cli_network.rst @@ -1,7 +1,10 @@ .. _cli-network: +================ Network commands ----------------- +================ + +.. include:: /userdocs/snippets/notes/deprecated-cli-v1.rst You can manage network configurations using the following command: @@ -19,7 +22,7 @@ You can manage network configurations using the following command: - ID of an OpenStack environment * - ```` - Path to directory - * - + * - ```` - Action that will be performed for the network configuration. The following table describes network management commands @@ -46,9 +49,9 @@ available in the Fuel CLI. - Upload network configuration for the environment with ID ``1`` from the current directory: - .. code-block:: console + .. code-block:: console - fuel --env 1 network --upload + fuel --env 1 network --upload .. note:: The :command:`fuel network` command can update configuration of diff --git a/userdocs/fuel-user-guide/cli/cli_network_group.rst b/userdocs/fuel-user-guide/cli/cli_network_group.rst index ef8296136..ca04ba7b2 100644 --- a/userdocs/fuel-user-guide/cli/cli_network_group.rst +++ b/userdocs/fuel-user-guide/cli/cli_network_group.rst @@ -1,7 +1,10 @@ .. _cli-network-group: +================================= Network group management commands ---------------------------------- +================================= + +.. include:: /userdocs/snippets/notes/deprecated-cli-v1.rst The following table describes network group management commands available in the Fuel CLI. diff --git a/userdocs/fuel-user-guide/cli/cli_network_template.rst b/userdocs/fuel-user-guide/cli/cli_network_template.rst index cc384cdad..111a2d5c3 100644 --- a/userdocs/fuel-user-guide/cli/cli_network_template.rst +++ b/userdocs/fuel-user-guide/cli/cli_network_template.rst @@ -1,7 +1,10 @@ .. _cli-network-template: +==================================== Network template management commands ------------------------------------- +==================================== + +.. include:: /userdocs/snippets/notes/deprecated-cli-v1.rst The following table describes network template management commands available in the Fuel CLI. diff --git a/userdocs/fuel-user-guide/cli/cli_nodes.rst b/userdocs/fuel-user-guide/cli/cli_nodes.rst index 280bdbee8..fb802fd9c 100644 --- a/userdocs/fuel-user-guide/cli/cli_nodes.rst +++ b/userdocs/fuel-user-guide/cli/cli_nodes.rst @@ -1,7 +1,10 @@ .. _cli-nodes: +======================== Node management commands ------------------------- +======================== + +.. include:: /userdocs/snippets/notes/deprecated-cli-v1.rst The following table describes node management commands available in the Fuel CLI. diff --git a/userdocs/fuel-user-guide/cli/cli_nodes_empty_role.rst b/userdocs/fuel-user-guide/cli/cli_nodes_empty_role.rst new file mode 100644 index 000000000..ae90ca2a1 --- /dev/null +++ b/userdocs/fuel-user-guide/cli/cli_nodes_empty_role.rst @@ -0,0 +1,148 @@ +.. _cli-nodes-empty-role: + +================================ +Deploy a node with an empty role +================================ + +.. include:: /userdocs/snippets/notes/deprecated-cli-v1.rst + +You may need to deploy a node with an operating system installed only, +that is an empty role, where you can further deploy your own service +out of Fuel control. + +**To deploy a node with an empty role:** + +#. Verify available operating systems: + + .. code-block:: console + + fuel release + + **Example of system response:** + + .. code-block:: console + + id | name | state | operating_system | version + ---|----------------------------|-------------|------------------|----------- + 2 | Mitaka on Ubuntu 14.04 | available | Ubuntu | mitaka-9.0 + 3 | Mitaka on Ubuntu+UCA 14.04 | available | Ubuntu | mitaka-9.0 + 1 | Mitaka on CentOS 6.5 | unavailable | CentOS | mitaka-9.0 + + + Note down the operating system ``id`` you need to install on the node. + +#. Verify available nodes: + + .. code-block:: console + + fuel node + + **Example of system response:** + + .. code-block:: console + + id | status | name | cluster | ip | mac | roles | pending_roles | online | group_id + ---|----------|------------------|---------|-----------|-------------------|-------|---------------|--------|--------- + 2 | discover | Untitled (90:9b) | None | 10.20.0.4 | 08:00:27:f5:90:9b | | | True | None + 3 | discover | Untitled (53:f1) | None | 10.20.0.5 | 08:00:27:14:53:f1 | | | True | None + 1 | discover | Untitled (7c:11) | None | 10.20.0.3 | 08:00:27:72:7c:11 | | | True | None + + +#. Create a new environment if you do not have one: + + .. code-block:: console + + fuel env create --name --release 2 + + **Example of system response:** + + .. code-block:: console + + Environment `` with id=1 was created! + +#. Verify that the environment has been created: + + .. code-block:: console + + fuel env + + **Example of system response:** + + .. code-block:: console + + id | status | name | release_id + ---|--------|------------|----------- + 1 | new | | 2 + + Note down the ``id`` of the environment. + +#. Verify available roles: + + .. code-block:: console + + fuel role --release 2 + + **Example of system response:** + + .. code-block:: console + + name + ------------------- + compute-vmware + compute + cinder-vmware + virt + base-os + controller + ceph-osd + ironic + cinder + cinder-block-device + mongo + + The role that you need is ``base-os``. + +#. Add one of the discovered nodes to the environment with the ``base-os`` role assigned: + + .. code-block:: console + + fuel node set --env 1 --node 1 --role base-os + + **Example of system response:** + + .. code-block:: console + + Nodes [1] with roles ['base-os'] were added to environment 1 + +#. Verify the status of the nodes: + + .. code-block:: console + + fuel node + + **Example of system response:** + + .. code-block:: console + + id | status | name | cluster | ip | mac | roles | pending_roles | online | group_id + ---|----------|------------------|---------|-----------|-------------------|-------|---------------|--------|--------- + 1 | discover | Untitled (7c:11) | 1 | 10.20.0.3 | 08:00:27:72:7c:11 | | base-os | True | 1 + 2 | discover | Untitled (90:9b) | None | 10.20.0.4 | 08:00:27:f5:90:9b | | | True | None + 3 | discover | Untitled (53:f1) | None | 10.20.0.5 | 08:00:27:14:53:f1 | | | True | None + + +Your node with an empty role has been added to the environment. + +.. note:: + + By default, Fuel does not apply network configuration. + To set up network configuration, run the ``netconfig`` puppet manifests + that comes with ``fuel-library``. + Fuel automatically executes the following tasks on ``base-os`` nodes only: + + * ``hiera`` + * ``globals`` + * ``logging`` + + See the `tasks.yaml `__ + configuration file diff --git a/userdocs/fuel-user-guide/cli/cli_noop.rst b/userdocs/fuel-user-guide/cli/cli_noop.rst new file mode 100644 index 000000000..0a879e07d --- /dev/null +++ b/userdocs/fuel-user-guide/cli/cli_noop.rst @@ -0,0 +1,49 @@ +.. _cli_noop: + +======================================================== +Detect custom configurations in an OpenStack environment +======================================================== + +Before you redeploy, update, or upgrade your OpenStack environment, ensure +that next Fuel tasks run will not override important changes that had been +applied to a whole OpenStack environment or a particular OpenStack node. +This procedure should only be applied to OpenStack nodes with the ``ready`` +statuses or to OpenStack environments with the ``operational`` statuses. + +**To detect custom configurations using the Fuel task graphs:** + +#. Select from the following options: + + * If you want to check that an environment has customizations using + a specific graph, execute the graph in the ``noop`` mode: + + .. code-block:: console + + fuel2 graph execute --env --type --noop --force + + * If you want to check that particular OpenStack nodes have customizations + using a specific graph, execute this graph in the ``noop`` mode: + + .. code-block:: console + + fuel2 graph execute --env --type -n --noop --force + + .. note:: The Puppet Noop run for any OpenStack environment or node + does not change their statuses. The Noop run is an additional + check rather than a part of the deployment process. + + * If you want to view the Puppet Noop run reports for a particular task graph, + type one of the following: + + .. code-block:: console + + fuel deployment-tasks --tid --task-name --include-summary + + .. code-block:: console + + fuel2 task history show --include-summary + + Reports for each Puppet Noop run are stored on all OpenStack nodes in + the ``/var/lib/puppet/reports//.yaml`` directory + and include details about the changes that were applied to the Fuel task + graphs. \ No newline at end of file diff --git a/userdocs/fuel-user-guide/cli/cli_plugins.rst b/userdocs/fuel-user-guide/cli/cli_plugins.rst index bd1815d1d..803af762f 100644 --- a/userdocs/fuel-user-guide/cli/cli_plugins.rst +++ b/userdocs/fuel-user-guide/cli/cli_plugins.rst @@ -1,7 +1,10 @@ .. _cli_plugins: +========================== Plugin management commands --------------------------- +========================== + +.. include:: /userdocs/snippets/notes/deprecated-cli-v1.rst The following table describes the plugin management commands available in the Fuel CLI. @@ -18,12 +21,12 @@ available in the Fuel CLI. - Command - Example * - Install a Fuel plugin from an ``.fp`` package. - - `` fuel plugins --install `` + - ``fuel plugins --install `` - * - Install a Fuel plugin from an ``.rpm`` package. - ``yum install `` - - * - Register a Fuel plugin installed using + * - Register a Fuel plugin installed using ``yum install`` from an ``.rpm`` package in Nailgun. - ``fuel plugins --register ==`` - @@ -50,7 +53,7 @@ available in the Fuel CLI. Upgrades are not supported for major versions of plugins installed from the ``.rpm`` package, as well as for plugins installed from the ``.fp`` packages. For example, you can only upgrade a Fuel plugin - installed from an ``.rpm`` package from version + installed from an ``.rpm`` package from version 1.0.0 to 1.0.1. - - fuel plugins --update + - ``fuel plugins --update `` - diff --git a/userdocs/fuel-user-guide/cli/cli_provision.rst b/userdocs/fuel-user-guide/cli/cli_provision.rst new file mode 100644 index 000000000..9c7575d18 --- /dev/null +++ b/userdocs/fuel-user-guide/cli/cli_provision.rst @@ -0,0 +1,29 @@ +.. _cli-provision: + +===================== +Provisioning commands +===================== + +.. include:: /userdocs/snippets/notes/deprecated-cli-v1.rst + +The following table describes the usage of the :command:`fuel provisioning` +command available in the Fuel CLI usage. + +.. list-table:: **Provisioning commands** + :widths: 7 10 + :header-rows: 1 + + * - Description + - Command + * - Delete current provisioning data + - ``fuel --env provisioning --delete`` + * - Download current provisioning data + - ``fuel --env provisioning --download`` + * - Download default provisioning data + - ``fuel --env provisioning --default`` + * - Get default provisioning information for specific nodes + - ``fuel --env provisioning --default --node `` + * - Upload provisioning information to a specific directory + - ``fuel --env provisioning -u --dir path/to/directory`` + * - Download provisioning information to a specific directory + - ``fuel --env provisioning -d --dir path/to/directory`` \ No newline at end of file diff --git a/userdocs/fuel-user-guide/cli/cli_roles.rst b/userdocs/fuel-user-guide/cli/cli_roles.rst index 78f85fcf6..b6e254e42 100644 --- a/userdocs/fuel-user-guide/cli/cli_roles.rst +++ b/userdocs/fuel-user-guide/cli/cli_roles.rst @@ -1,7 +1,10 @@ .. _cli-roles: +======================== Role management commands ------------------------- +======================== + +.. include:: /userdocs/snippets/notes/deprecated-cli-v1.rst Fuel CLI implements standard CRUD for operations on a node role. The following table describes the role management commands @@ -74,7 +77,7 @@ available in the Fuel CLI. swift | 17 * - Update the role data - - `` fuel role --rel --update --file `` + - ``fuel role --rel --update --file `` - :: fuel role --rel <2> --update --file diff --git a/userdocs/fuel-user-guide/cli/cli_vip.rst b/userdocs/fuel-user-guide/cli/cli_vip.rst index c3ad40931..bf6ca297e 100644 --- a/userdocs/fuel-user-guide/cli/cli_vip.rst +++ b/userdocs/fuel-user-guide/cli/cli_vip.rst @@ -1,7 +1,10 @@ .. _cli-vip: +============================== Virtual IP management commands ------------------------------- +============================== + +.. include:: /userdocs/snippets/notes/deprecated-cli-v1.rst The following table describes virtual IP management commands available in the Fuel CLI. @@ -22,13 +25,13 @@ available in the Fuel CLI. * ```` - a name of the ``yaml`` file where to save a VIP configuration (optional). - - `` fuel --env vip --download --file `` + - ``fuel --env vip --download --file `` - .. code-block:: console fuel --env 1 vip --download --file vip.yaml * - Upload a VIP configuration for a specific environment from a specified file. - - `` fuel --env vip --upload --file `` + - ``fuel --env vip --upload --file `` - .. code-block:: console fuel --env 1 vip --upload --file vip.yaml diff --git a/userdocs/fuel-user-guide/configure-environment.rst b/userdocs/fuel-user-guide/configure-environment.rst index 02e68d73c..381cfd7cd 100644 --- a/userdocs/fuel-user-guide/configure-environment.rst +++ b/userdocs/fuel-user-guide/configure-environment.rst @@ -21,7 +21,7 @@ This section includes the following topics: PageBreak .. toctree:: - :maxdepth: 3 + :maxdepth: 1 configure-environment/add-nodes.rst configure-environment/add-label.rst @@ -33,9 +33,13 @@ This section includes the following topics: configure-environment/selectable-offload.rst configure-environment/map-logical-to-physical-nic.rst configure-environment/verify-networks.rst + configure-environment/network-templates.rst configure-environment/customize-partitions.rst configure-environment/config-drive-format.rst configure-environment/settings.rst configure-environment/dns-ntp-support.rst configure-environment/configure-multipath.rst configure-environment/nfv.rst + configure-environment/workflows.rst + configure-environment/enable-usb-discovery.rst + configure-environment/configure-vmware-vcenter-settings.rst \ No newline at end of file diff --git a/userdocs/fuel-user-guide/configure-environment/add-nodes.rst b/userdocs/fuel-user-guide/configure-environment/add-nodes.rst index 9156f2b48..62ef3aaae 100644 --- a/userdocs/fuel-user-guide/configure-environment/add-nodes.rst +++ b/userdocs/fuel-user-guide/configure-environment/add-nodes.rst @@ -43,3 +43,4 @@ For more information, see - *System requirements* in *Fuel Installation Guide* - :ref:`add-label-ug` - :ref:`change-hostname-slave-nodes` + - :ref:`cli-nodes-empty-role` diff --git a/userdocs/fuel-user-guide/configure-environment/configure-vmware-vcenter-settings.rst b/userdocs/fuel-user-guide/configure-environment/configure-vmware-vcenter-settings.rst new file mode 100644 index 000000000..37a5108b1 --- /dev/null +++ b/userdocs/fuel-user-guide/configure-environment/configure-vmware-vcenter-settings.rst @@ -0,0 +1,31 @@ +.. _configure-vmware-vcenter-settings: + +================================= +Configure VMware vCenter settings +================================= + +If your environment is integrated with VMware vCenter, you can specify a +Certificate Authority (CA) bundle file to use for verifying the VMware vCenter +server certificate for the OpenStack Compute service, OpenStack Block Storage +service, and OpenStack Image service. + +**To configure the VMware vCenter certificate verification:** + +#. Log in to the Fuel web UI. +#. Navigate to the :guilabel:`VMware` tab. +#. Configure the VMware vCenter certificate verification depending on your + environment needs: + + * If you plan to deploy an environment for testing purposes or want to + speed up the deployment process, disable the certificate + verification by selecting + :guilabel:`Bypass vCenter certificate verification` in the + :guilabel:`VMware vCenter Settings` section. + * If VMware vCenter is using a self-signed certificate: + + #. In the :guilabel:`CA file` section, upload a custom CA certificate. + #. Leave :guilabel:`Bypass vCenter certificate verification` unchecked. + * To use a VMware vCenter server certificate emitted by a known CA, for + example, GeoTrust, leave the :guilabel:`CA file` section empty and the + :guilabel:`Bypass vCenter certificate verification` unchecked. +#. Click :guilabel:`Save Changes`. \ No newline at end of file diff --git a/userdocs/fuel-user-guide/configure-environment/enable-usb-discovery.rst b/userdocs/fuel-user-guide/configure-environment/enable-usb-discovery.rst new file mode 100644 index 000000000..8288c992e --- /dev/null +++ b/userdocs/fuel-user-guide/configure-environment/enable-usb-discovery.rst @@ -0,0 +1,32 @@ +.. _enable-usb-discovery: + +Enable USB devices discovery +---------------------------- + +When Fuel discovers Fuel Slave nodes, it does not automatically detect USB +devices. However, for testing or other purposes you may need to enable +USB devices discovery. + +**To enable USB devices discovery:** + +#. Log in to Fuel Master node CLI. +#. Open the ``/etc/fuel-bootstrap-cli/fuel_bootstrap_cli.yaml`` file + for editing. +#. Add ``report_usb_block_devices`` to the ``extend_kopts`` string. + + **Example:** + + .. code-block:: console + + extend_kopts: "biosdevname=0 net.ifnames=1 debug ignore_loglevel + log_buf_len=10M print_fatal_signals=1 LOGLEVEL=8 report_usb_block_devices" + +#. Rebuild the bootstrap image: + + :: + + fuel-bootstrap build --activate + +#. Reboot all discovered Fuel Slave nodes. + + The nodes boot the new bootstrap image. diff --git a/userdocs/fuel-user-guide/configure-environment/network-templates.rst b/userdocs/fuel-user-guide/configure-environment/network-templates.rst new file mode 100644 index 000000000..a240e4ea4 --- /dev/null +++ b/userdocs/fuel-user-guide/configure-environment/network-templates.rst @@ -0,0 +1,31 @@ +.. _network-templates-intro: + +Deploy network configurations using network templates +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +By default, Fuel configures the following networks (Linux bridges): Public, +Private, Storage, Admin (PXE), and Management. In addition, if you install the +OpenStack Bare Metal service, Fuel creates the Baremetal network. If you need +to add a custom network or do not need any of the default networks, you can +configure or delete the required networks through network templates. + +Network templates enable you to: + +* Create a custom set of networks. +* Create mappings of network roles to networks. +* Use a network on a specific node only if a corresponding node role is + configured on the node +* Implement custom networking topologies, such as sub-interface bonding, + and so on. + +This section includes the following topics: + +.. toctree:: + :maxdepth: 1 + + network-templates/network-templates-overview.rst + network-templates/network-templates-limitations.rst + network-templates/network-templates-structure.rst + network-templates/network-templates-create.rst + network-templates/network-templates-delete.rst + network-templates/network-templates-examples.rst diff --git a/userdocs/fuel-user-guide/configure-environment/network-templates/examples/one-network.rst b/userdocs/fuel-user-guide/configure-environment/network-templates/examples/one-network.rst new file mode 100644 index 000000000..75bb5d66d --- /dev/null +++ b/userdocs/fuel-user-guide/configure-environment/network-templates/examples/one-network.rst @@ -0,0 +1,29 @@ +.. _one-network: + +Configure a single network topology +----------------------------------- + +Fuel supports a single network configuration where one network serves +all OpenStack traffic. This configuration is common in +proof of concept deployments where no additional networks are +available. + +**To configure a single network:** + +#. Save `network template for one network + `_ + as ``network_template_.yaml``. + +#. Upload the network template by typing: + + :: + + # fuel network-template --upload --env + +#. Deploy the OpenStack environment. +#. Allocate the correct floating IP pool to the network. + + #. Clear the gateway from `router04`. + #. Delete the `admin_floating_net__subnet` subnet. + #. Create a new subnet with the floating IP pool from the single network. + #. Set gateway on `router04`. diff --git a/userdocs/fuel-user-guide/configure-environment/network-templates/examples/two-networks.rst b/userdocs/fuel-user-guide/configure-environment/network-templates/examples/two-networks.rst new file mode 100644 index 000000000..3ca79b497 --- /dev/null +++ b/userdocs/fuel-user-guide/configure-environment/network-templates/examples/two-networks.rst @@ -0,0 +1,75 @@ +.. _two-networks: + +Configure the two-network topology +---------------------------------- + +Fuel supports two-network configuration where one network is +dedicated for PXE traffic and another network for +all other traffic. + +**To configure a two-network topology:** + +1. Create a new network for all non-PXE traffic: + + :: + + # fuel network-group --create --name everything --cidr + --gateway --nodegroup + +2. Set the ``render_addr_mask`` parameter to `internal` for this network by + typing: + + :: + + # fuel network-group --set --network 39 --meta '{"name": + "everything", "notation": "cidr", "render_type": null, "map_priority": 2, + "configurable": true, "use_gateway": true, "render_addr_mask": + "internal", "vlan_start": null, "cidr": "10.108.31.0/24"}' + + This parameter is required by the Fuel library. The Fuel library requires + a value called ``internal_address`` for each node. + This value is set to the node's IP address from a network group which has + ``render_addr_mask`` set to `internal` in its metadata. Therefore, update + ``render_addr_mask`` for this network. + +3. Save `network template for two networks + `_ + as ``network_template_.yaml``. + + .. note:: + Verify that ``nic_mapping`` matches your configuration. + +4. Upload the network template by typing: + + :: + + # fuel network-template --upload --env + +5. Deploy the environment. +6. After Fuel completes the deployment, verify that only one bridge is + configured by typing: + + :: + + # ip -4 a + + **Example of system output:** + + :: + + 1: lo: mtu 65536 qdisc noqueue state UNKNOWN group + default + inet 127.0.0.1/8 scope host lo + valid_lft forever preferred_lft forever + 8: br-fw-admin: mtu 1500 qdisc noqueue + state UP group default + inet 10.108.5.3/24 brd 10.108.5.255 scope global br-fw-admin + valid_lft forever preferred_lft forever + 16: vr-host-base: mtu 1500 qdisc + pfifo_fast state UP group default qlen 1000 + inet 240.0.0.5/30 scope global vr-host-base + valid_lft forever preferred_lft forever + 30: hapr-host: mtu 1500 qdisc pfifo_fast + state UP group default qlen 1000 + inet 240.0.0.1/30 scope global hapr-host + valid_lft forever preferred_lft forever diff --git a/userdocs/fuel-user-guide/configure-environment/network-templates/network-templates-create.rst b/userdocs/fuel-user-guide/configure-environment/network-templates/network-templates-create.rst new file mode 100644 index 000000000..d201247e8 --- /dev/null +++ b/userdocs/fuel-user-guide/configure-environment/network-templates/network-templates-create.rst @@ -0,0 +1,128 @@ +.. _network-templates-create: + +Create a network template +------------------------- + +You can use one of the network templates provided in +:ref:`network-templates-examples`. +However, if these templates do not meet your networking requirements, +you can create your own. We strongly recommend that you use the +``default.yaml`` network template provided in this documentation to +build your own network template. + +.. note:: + When you configure a network using a network template, you cannot apply + changes to the nodes network configuration using the Fuel web UI. For + example, if you configure an OpenStack environment using network + templates, deploy the OpenStack environment, and later decide to add + new nodes to that environment, you must update network configuration + of these nodes using a network template and do not use the Fuel web UI. + + However, templates do not describe the level 2 and level 3 network + settings. Therefore, you must set them using Fuel web UI, CLI, or API. + +After uploading a network template, you must create and/or +delete networks and node groups using the Fuel CLI to reflect the uploaded +network configuration. Otherwise, the configuration specified in the network +template will not take effect and may result in a malfunction. + +**To create a network template:** + +#. Create a ``.yaml`` file. +#. Specify your network configuration in the ``.yaml`` file following + the conventions described in :ref:`network-templates-structure`. +#. Log in to the Fuel Master node CLI. +#. Display the ID of the environment in which you want to upload the + template: + + :: + + fuel environment + +#. Upload the network template to Fuel: + + :: + + fuel --env network-template --upload --dir + + **Example:** + + :: + + fuel --env 1 network-template --upload --dir /home/stack/ + +#. Add or delete custom networks that you have introduced through + the network template: + + * If you need to delete a network: + + #. View the ID of the network by typing: + + :: + + fuel network-group + + **Example of system response:** + + :: + + id | name | vlan_start | cidr | gateway |group_id + ---+---------------+------------+--------------+----------+-------- + 24 | private | | | | 4 + 23 | private | | | | 5 + 22 | storage | 102 | 10.10.1.0/24 | 10.1.1.1 | 5 + 25 | management | 101 | 10.10.0.0/24 | 10.0.0.1 | 4 + 21 | public | | 10.10.0.0/24 | 10.10.0.1| 4 + + #. Delete the required network using the network ID. + + :: + + fuel network-group --delete --env --network + + + * If you need to add a new network, type: + + :: + + fuel network-group --create --node-group --name + --vlan --cidr + +#. Add or delete custom networks as described in + :ref:`cli-network-group`. + +#. Configure L2 and L3 network settings: + + .. note:: You cannot modify VLAN settings through the Fuel web UI or CLI + Configure VLAN settings in the network template. + + * Using Fuel web UI: + + #. Log in to the Fuel web UI. + #. Click :guilabel:`Networks`. + #. Configure :guilabel:`Network Settings` as required. + + .. note:: If you add additional node network group with different from the + default node network group settings, update the network template + with the required changes. + + * Using Fuel CLI: + + #. Log in to the Fuel CLI. + #. Download network configuration: + + :: + + fuel --env network --download + + #. Make the required changes in the network ``.yaml`` file. + #. Upload the configuration to the Fuel Master node: + + :: + + fuel --env network --upload + +.. seealso:: + + - :ref:`cli-network-group` + - :ref:`cli-network-template` diff --git a/userdocs/fuel-user-guide/configure-environment/network-templates/network-templates-delete.rst b/userdocs/fuel-user-guide/configure-environment/network-templates/network-templates-delete.rst new file mode 100644 index 000000000..f4c920fc5 --- /dev/null +++ b/userdocs/fuel-user-guide/configure-environment/network-templates/network-templates-delete.rst @@ -0,0 +1,32 @@ +.. _network-template-delete: + +Delete a network template +------------------------- + +You can delete a network template that you have previously uploaded. + +.. warning:: + + Do not delete network templates that are used in your OpenStack + environment as it may result in a failure of the whole network + configuration. + +**To delete a network template:** + +#. Log in to the Fuel Master node CLI. +#. Type: + + :: + + fuel --env network-template --delete + + **Example:** + + :: + + fuel --env 1 network-template --delete + +.. seealso:: + + - :ref:`cli-network-group` + - :ref:`cli-network-template` diff --git a/userdocs/fuel-user-guide/configure-environment/network-templates/network-templates-examples.rst b/userdocs/fuel-user-guide/configure-environment/network-templates/network-templates-examples.rst new file mode 100644 index 000000000..24e46d09d --- /dev/null +++ b/userdocs/fuel-user-guide/configure-environment/network-templates/network-templates-examples.rst @@ -0,0 +1,35 @@ +.. _network-templates-examples: + +Network template examples +========================= + +This section provides examples of network configurations +using network templates. You can use the default template +and modify it for your requirements or use any of the templates provided +in the `network templates folder `_. + +The following table describes network template examples: + +.. list-table:: **Examples of network templates** + :widths: 10 10 + :header-rows: 1 + + * - Template + - Description + * - ``default.yaml`` + - The default network template deploys the basic configuration that you + can deploy using the Fuel web UI. You can use this template to create + your own network template. Additional information about network + configuration using network templates provided in the file. + * - ``one_network.yaml`` + - A network template that describes a configuration in which one network + serves all traffic. + * - ``two_networks.yaml`` + - A network template that describes a configuration in which all traffic + is served by two networks. + +.. toctree:: + :maxdepth: 1 + + examples/one-network.rst + examples/two-networks.rst diff --git a/userdocs/fuel-user-guide/configure-environment/network-templates/network-templates-limitations.rst b/userdocs/fuel-user-guide/configure-environment/network-templates/network-templates-limitations.rst new file mode 100644 index 000000000..2b383ec12 --- /dev/null +++ b/userdocs/fuel-user-guide/configure-environment/network-templates/network-templates-limitations.rst @@ -0,0 +1,18 @@ +.. _network-templates-limitations: + +Network template limitations +---------------------------- + +When using network templates, consider the following limitations: + +* All operations with templates must be performed through CLI or API. + The Fuel web UI does not support network templates. +* The Public network which maps to the External network in OpenStack + cannot be removed. +* When you use network templates, do not download and modify Fuel + deployment configurations using the ``fuel download`` and + ``fuel upload`` commands as it may result in a system malfunction. +* Mapping of network roles to networks, as well as network topology cannot + be configured for individual nodes. They can only be set for a node role + or/and node group. +* Network verification in the Fuel web UI has limited support. diff --git a/userdocs/fuel-user-guide/configure-environment/network-templates/network-templates-overview.rst b/userdocs/fuel-user-guide/configure-environment/network-templates/network-templates-overview.rst new file mode 100644 index 000000000..e6c932585 --- /dev/null +++ b/userdocs/fuel-user-guide/configure-environment/network-templates/network-templates-overview.rst @@ -0,0 +1,17 @@ +.. _network-templates-overview: + +Overview of network templates +----------------------------- + +A network template is a ``.yaml`` file that contains network configuration +for an OpenStack environment. To apply custom network +configurations, create and configure +the template according to your environment requirements. For your convenience, +use the following :ref:`network-templates-examples`. + +The name of the network template +must follow this convention: ``network_template_.yaml``. Verify the +ID of your OpenStack environment by running the ``fuel environment`` command. + +For example, if the ID of an OpenStack environment is ``1``, the name of the +template is ``network_template_1.yaml``. diff --git a/userdocs/fuel-user-guide/configure-environment/network-templates/network-templates-structure.rst b/userdocs/fuel-user-guide/configure-environment/network-templates/network-templates-structure.rst new file mode 100644 index 000000000..ad3843b79 --- /dev/null +++ b/userdocs/fuel-user-guide/configure-environment/network-templates/network-templates-structure.rst @@ -0,0 +1,19 @@ +.. _network-templates-structure: + +Structure of network templates +------------------------------ + +You can use the structure described in this section, as well +as the default template, to create a template that meets the +requirements of your configuration. + +Network parameters are defined in the ``adv_net_template`` +section in the ``network_template_.yaml`` file. + +.. toctree:: + :maxdepth: 1 + + network-templates-structure/network_scheme.rst + network-templates-structure/nic_mapping.rst + network-templates-structure/templates_for_node_role.rst + network-templates-structure/network_assignment.rst diff --git a/userdocs/fuel-user-guide/configure-environment/network-templates/network-templates-structure/network_assignment.rst b/userdocs/fuel-user-guide/configure-environment/network-templates/network-templates-structure/network_assignment.rst new file mode 100644 index 000000000..03c730f72 --- /dev/null +++ b/userdocs/fuel-user-guide/configure-environment/network-templates/network-templates-structure/network_assignment.rst @@ -0,0 +1,27 @@ +.. _network-assignment: + +network_assignment +------------------ + +**Description** + +Describes mapping between endpoints and network names. The **Example** +section describes the mapping that Fuel configures by default +without using templates. The set of networks can be changed +using API. + +**Example** + +:: + + network_assignments: + storage: + ep: br-storage + private: + ep: br-prv + public: + ep: br-ex + management: + ep: br-mgmt + fuelweb_admin: + ep: br-fw-admin diff --git a/userdocs/fuel-user-guide/configure-environment/network-templates/network-templates-structure/network_scheme.rst b/userdocs/fuel-user-guide/configure-environment/network-templates/network-templates-structure/network_scheme.rst new file mode 100644 index 000000000..26bbefdab --- /dev/null +++ b/userdocs/fuel-user-guide/configure-environment/network-templates/network-templates-structure/network_scheme.rst @@ -0,0 +1,200 @@ +.. _network-scheme: + +network_scheme +-------------- + +**Description** + +Defines the name of the network template as well as the following +parameters that are applied to each network that needs to be +configured: + +* ``priority`` - defines the order in which the network templates will + be applied to a node. The values range 0 to 64000. + For example, you can set ``100``, ``200``, ``300`` with ``100`` + being the highest priority template. + +* ``transformations`` - a sequence of actions that builds the required + network configuration. For example: ``add-br`` - add a network + bridge, ``add-port`` - add a network port. The Puppet L23network + module creates network objects described in the ``transformations`` + section that connect physical interfaces with logical endpoints. Order + of commands specified in this section is significant. + + The sequence of commands that create network configuration must + be reflected in the transformation section: + + * For service networks: + + #. Create a Linux bridge. By default, if you do not specify a + provider a Linux bridge is created. + #. Create a network port that connects the Linux bridge and the + physical network interface. + + * For workload networks: + + #. Create an OVS bridge as a first point of connection between + the OpenStack Networking service and the physical network + interface. + + #. Create a Linux bridge. Since an OVS bridge cannot directly connect + to a physical interface, a Linux bridge is required. + + #. Create a patch that connects Linux and OVS bridges. + + #. Create a network port that connects the Linux bridge and the + physical network interface. + + You can specify the following commands in the ``transformation`` + section: + + * ``add-br`` - creates a bridge. By default, creates a Linux + bridge. You can specify the following parameters for this command: + + * ``name`` - name of the network bridge. For example, ``br-admin``. + + * ``provider`` - a network technology such as Open vSwitch (OVS) or + Linux Bridge, that connects physical interface with + the OpenStack Networking service. Default provider is Linux + Bridge. The options are: ``linux``, ``ovs``. + + * ``mtu`` - (optional) enables you to specify MTU for this network bridge. + + * ``add-port`` - create a port that connects a Linux bridge with a + physical network interface. You can specify the following parameters + for this command: + + * ``name`` - name of the network port. + + * ``bridge`` - name of the bridge for which the port is created. + + * ``type`` - (optional) A type of the OVS interface for the port. + Default value is ``internal``. Available options include: + ``internal``, ``system``, ``tap``, ``gre``, ``null``. + See the OVS documentation for more details. Specify + + * ``trunks`` - (optional) a set of 802.1q tags in the form of integers + from 0 to 4095) that are allowed to pass through if the "tag" + option equals 0. Available options include: + + * Empty list - all traffic passes + * 0 - untagged traffic only. + * 2-4095 - traffic with the specified tag passes. + For example, 10,10,20. + + * ``port_properties`` - (optional) a list of additional OVS port + properties to modify them in OVS database. + + * ``interface_properties`` (optional) a list of additional OVS interface + properties to modify them in OVS database. + + * ``add-patch`` - connects network bridges. Available parameters include: + + * ``bridges`` - a pair of bridges to connect. You can specify either + bridges of the same type or of different types. + + * ``peers`` - (optional) abstract names for each end of the patch. + + * ``tags`` - (optional) a pair of integers that represent an + 802.1q tag of traffic that is captured from a corresponding + OVS bridge. Available values include: + + * 0 - only the untagged traffic passes through + * 1-4094 - the bond allows only the traffic with the specific tag. + Specify the tags in the ``trunks`` parameter. + + * ``trunks`` - (optional) a set of 802.1q tags in a form of + integers from 2 to 4095 which are allowed to pass through if the + ``tag`` parameter is set to ``0``. Available values include: + + * Empty list - all traffic passes (default) + * 0 - untagged traffic only + * 2-4095 - traffic with the specified tag passes). For example, 0,10,20. + + * ``add-bond`` - combines two or more network interfaces for redundancy + and creates a network object called bond. You can specify + the following parameters for this command: + + * ``name`` - name of the network port. + + * ``interfaces`` - a set of two or more network interfaces that you + want to bind. For example, ``eth1, eth2``. + + * ``bridge`` - name of the bridge on which the bond must be created. + + * ``tag`` - (optional) a 802.1q tag of traffic which + received from an OVS bridge. Available values include: + + * 0 - the bond ignores the tag and allows all traffic to pass + through. + + * 1 - 4094 - the bond allows only the traffic with the specific tag. + Specify the tags in the ``trunks`` parameter. + + * ``trunks`` - (optional) a set of 802.1q tags in a form of + integers from 2 to 4095 which are allowed to pass through if the + ``tag`` parameter is set to ``0``. Available values include: + + * Empty list - all traffic passes (default) + * 0 - untagged traffic only + * 2-4095 - traffic with the specified tag passes). For example, 0,10,20. + + * ``properties`` - (optional) a list of additional OVS bonded port + properties to modify them in the OVS database. Use this parameter + to set the aggregation mode and balancing strategy, to configure LACP, + and so on. For more informations, see the OVS documentation. + +* ``endpoints`` - lists logical interfaces or bridges + with assigned IP addresses to which you can map one or more network + roles. + +* ``roles`` - mapping of a network traffic to a logical endpoint. When you + apply multiple templates to one node, verify that this parameter + in one template does not contradict this parameter in other templates. + The list of supported network traffics (network roles) is available in the + ``openstack.yaml`` file on the Fuel Master node. If you have Fuel plugins + installed in your environment, you can also map network traffic related + to the plugin. For the list of types of network traffic related to the + plugin, see the corresponding ``network_roles.yaml`` file in the plugin + repository. + The ``roles`` section cannot be empty. If you do not want to specify any + mappings, you must create one fake mapping. For example: + + **Example:** + + :: + + roles: + fake/ext: br-pub-ext + + +**Example** + +:: + + network_scheme: + storage: