diff --git a/_images/deliverables/scr_change_hostname.png b/_images/deliverables/scr_change_hostname.png new file mode 100644 index 000000000..0ad592102 Binary files /dev/null and b/_images/deliverables/scr_change_hostname.png differ diff --git a/_images/deliverables/scr_change_pass_ui.png b/_images/deliverables/scr_change_pass_ui.png new file mode 100644 index 000000000..e29c5af44 Binary files /dev/null and b/_images/deliverables/scr_change_pass_ui.png differ diff --git a/_images/deliverables/scr_fuel_log_in.png b/_images/deliverables/scr_fuel_log_in.png new file mode 100644 index 000000000..dbaa69811 Binary files /dev/null and b/_images/deliverables/scr_fuel_log_in.png differ diff --git a/_images/deliverables/scr_ironic_baremetal_nic_example.png b/_images/deliverables/scr_ironic_baremetal_nic_example.png new file mode 100644 index 000000000..393b6bd2c Binary files /dev/null and b/_images/deliverables/scr_ironic_baremetal_nic_example.png differ diff --git a/_images/deliverables/scr_partition-disks.png b/_images/deliverables/scr_partition-disks.png new file mode 100644 index 000000000..0cabd39ec Binary files /dev/null and b/_images/deliverables/scr_partition-disks.png differ diff --git a/index.rst b/index.rst index 4b54ca340..07711a113 100644 --- a/index.rst +++ b/index.rst @@ -21,6 +21,7 @@ OpenStack environments and manage them after deployment. :maxdepth: 1 userdocs/fuel-install-guide + userdocs/fuel-user-guide Developer documentation ~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/userdocs/fuel-user-guide.rst b/userdocs/fuel-user-guide.rst new file mode 100644 index 000000000..5cfa98b70 --- /dev/null +++ b/userdocs/fuel-user-guide.rst @@ -0,0 +1,22 @@ +.. index:: Fuel User Guide + +.. _fuel-user-guide: + +=============== +Fuel User Guide +=============== + +.. toctree:: + :maxdepth: 3 + + fuel-user-guide/introduction.rst + fuel-user-guide/create-environment.rst + fuel-user-guide/configure-environment.rst + fuel-user-guide/install-additional-components.rst + fuel-user-guide/deploy-environment.rst + fuel-user-guide/next-steps.rst + fuel-user-guide/configure-additional-components.rst + fuel-user-guide/verify-environment.rst + fuel-user-guide/maintain-environment.rst + fuel-user-guide/cli.rst + diff --git a/userdocs/fuel-user-guide/cli.rst b/userdocs/fuel-user-guide/cli.rst new file mode 100644 index 000000000..e712322d0 --- /dev/null +++ b/userdocs/fuel-user-guide/cli.rst @@ -0,0 +1,29 @@ +.. _cli: + +Use the Fuel CLI +================ + +Using the Fuel Command Line Interface (CLI) you can: + +* Operate your OpenStack environments using Fuel text commands, as well as + using standard Linux commands. +* Apply advanced configurations through configuration files that you cannot + modify using the Fuel Web UI. + +.. warning:: + We do not recommend to use Fuel CLi for unexperienced users. + Fuel CLI may break 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 +the Fuel CLI, Fuel displays the corresponding message in the Fuel web UI. + +This section includes the following topics: + +.. toctree:: + :maxdepth: 3 + + cli/cli_acronyms.rst + cli/cli_usage.rst + cli/cli_config_openstack.rst + cli/cli_change_ip_range.rst diff --git a/userdocs/fuel-user-guide/cli/cli_acronyms.rst b/userdocs/fuel-user-guide/cli/cli_acronyms.rst new file mode 100644 index 000000000..0af1f7e3e --- /dev/null +++ b/userdocs/fuel-user-guide/cli/cli_acronyms.rst @@ -0,0 +1,112 @@ + +.. _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. + + +.. 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: + +:: + + [root@fuel ~]# fuel nodes + + id | status | name | cluster | ip | mac | ... + ---|----------|------------------|---------|-----------|-------------------| ... + 4 | ready | Untitled (b0:77) | 1 | 10.20.0.6 | 56:40:fa:cc:cf:45 | ... + 1 | ready | Untitled (ca:9a) | 1 | 10.20.0.4 | ca:03:e6:b1:13:46 | ... + 3 | ready | Untitled (0e:64) | 2 | 10.20.0.7 | 26:1f:eb:91:d8:49 | ... + 2 | ready | Untitled (c1:ef) | 2 | 10.20.0.3 | 22:2a:45:36:5d:42 | ... + 5 | discover | Untitled (e1:c4) | None | 10.20.0.5 | 08:00:27:1a:e1:c4 | ... + + + id | status | name |...| roles | pending_roles | online | group_id + ---|----------|------------------|...|------------|---------------|--------|--------- + 4 | ready | Untitled (b0:77) |...| compute | | True | 1 + 1 | ready | Untitled (ca:9a) |...| controller | | True | 1 + 3 | ready | Untitled (0e:64) |...| compute | | True | 2 + 2 | ready | Untitled (c1:ef) |...| controller | | True | 2 + 5 | discover | Untitled (e1:c4) |...| | | True | None + + +The meaning of these fields is: + +:id: The node identifier, assigned incrementally + when the node is first discovered + (when the Fuel agent + sends its first request to the Fuel Master node). + + This ID is the Primary Key for this record in the database; + it is unique and is never reassigned; + when you delete a node from the environment, + that node's ID is deleted; + the next node added to the environment is assigned + a new ID that is higher than the highest-numbered ID in the database. + +:status: Current state of the node: + + :ready: Node is deployed and provisioned, ready to use + :discover: Node is not deployed and not provisioned + :provisioning: Node is in the process of being provisioned + (operating system is being installed) + :provisioned: Node is provisioned but not deployed + :deploying: Node is being deployed + (OpenStack is being installed and configured) + :error: Deployment/provisiong of the node has failed + +:name: Name of the node as displayed on the screen when you + assign roles. + By default, this is "Untitled" with the final digits + of the MAC address used by the Admin interface for that node. + You can double-click on that title to change the name. + +:cluster: ID of the environment to which the node is assigned. + +:ip: IP address of the admin interface, + which is the IP address for the default route. + +:mac: MAC address of the admin interface, + determined the same way as the IP address. + +:roles: A role of a node; + populated only after deployment. + +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 + + For Release 6.x and later, + 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. + +:online: Status of the node: + + :False: Node is offline. + + :True: Node is available via the Fuel admin network. + +: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. + + + diff --git a/userdocs/fuel-user-guide/cli/cli_change_ip_range.rst b/userdocs/fuel-user-guide/cli/cli_change_ip_range.rst new file mode 100644 index 000000000..50084b430 --- /dev/null +++ b/userdocs/fuel-user-guide/cli/cli_change_ip_range.rst @@ -0,0 +1,52 @@ + +.. _cli_change_ip_range: + + +Add network ranges +------------------ + +To add network ranges, edit the network configuration file: +add the IP network range to ``ip_ranges`` and change +``notation`` from ``cidr`` to ``ip_ranges``. + +Step-by-step: + +#. On the Fuel Master node, download the network configuration file:: + + fuel network --env -d + + where is the ID of the environment (a number) that you can + get by issuing the ``fuel env`` command. + + For example:: + + fuel network --env 1 -d + +#. Open the downloaded **/root/network_.yaml** file for editing. +#. Add your list of IP network ranges under the ``ip_ranges`` + parameter. + + Sample:: + + ip_ranges: + - - 192.168.0.1 + - 192.168.0.90 + - - 192.168.0.100 + - 192.168.0.254 + +#. In the same network configuration file, change ``notation: cidr`` + to ``notation: ip_ranges``. + + Sample:: + + meta: + cidr: 192.168.0.0/24 + configurable: true + map_priority: 2 + name: management + notation: ip_ranges + render_addr_mask: internal + +#. Upload the edited network configuration file:: + + fuel network --env -u diff --git a/userdocs/fuel-user-guide/cli/cli_config_openstack.rst b/userdocs/fuel-user-guide/cli/cli_config_openstack.rst new file mode 100644 index 000000000..441817f54 --- /dev/null +++ b/userdocs/fuel-user-guide/cli/cli_config_openstack.rst @@ -0,0 +1,169 @@ +.. _fuel-cli-config-openstack-services: + +Changing the configuration of Nova, Neutron, and Keystone ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +Using CLI, you can override the hardcoded, or provided by Nailgun, +configuration values, as well as introduce new configuration options +for OpenStack services. + +You can change the Nova, Neutron, and Keystone configuration for: + +- A single node +- All nodes with a certain role +- An environment + +You can change the configuration before or after the environment deployment. + +The services the configuration of which you change restart automatically +after applying the changes. + +The ``override_resources`` Puppet resource applies changes to the existing +configuration resources and creates the new ones that were not previously +defined. + +To change the configuration of OpenStack Services +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +#. Log in to the Fuel Master node. +#. Edit the YAML file with the configuration options of the services that + you are going to change. Example: + + .. 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 + +#. Upload the YAML file: + + * To upload the changes for the environment: + + .. code-block:: console + + fuel openstack-config --env 1 --upload file.yaml + + * To upload the changes for all nodes with a role: + + .. code-block:: console + + fuel openstack-config --env 1 --role compute --upload file.yaml + + * To upload the changes for certain nodes: + + .. code-block:: console + + fuel openstack-config --env 1 --node 1,2,3 --upload file.yaml + +#. Execute the changes: + + * To execute the changes for the environment: + + .. code-block:: console + + fuel openstack-config --env 1 --execute + + * To execute the changes for all nodes with a role: + + .. code-block:: console + + fuel openstack-config --env 1 --role compute --execute + + * To execute the changes for certain nodes: + + .. code-block:: console + + fuel openstack-config --env 1 --node 1,2,3 --execute + +The services will restart automatically. + +**Additional commands** + +* List the configuration changes history: + + .. code-block:: console + + fuel openstack-config --env 1 --list + + This command returns a list of configuration changes, each of them with + a respective ID record. + +* Download a previously uploaded YAML file with the configuration changes: + + .. code-block:: console + + fuel openstack-config --id 1 --download + + The ``id`` parameter is the record number from the changes history that + you can get with the :command:`fuel openstack-config --env 1 --list` command. + +**Workflow of the configuration change override** + +The ``override_resources`` Puppet resource overrides the already existing +resources and creates the previously not defined resources. + +.. note:: ``override_resources`` must always be used as the first resource + in manifests. + +Example: + +.. code-block:: puppet + + keystone_config { + 'DEFAULT/debug': {value => True} + } + override_resource {'keystone_config': + data => { + 'DEFAULT/debug': {'value' => False}, + 'DEFAULT/max_param_size': {'value' => 128} + } + } + +The Nova, Keystone, and Neutron top-level granular tasks use +``override_resources``. The new parameter hash used in the Puppet resources +is passed to ``override_resources`` from hiera. + +The three following hiera files cover the hierarchical configuration +overrides: + +- ``/etc/hiera/override/config/%{::fqdn}`` +- ``/etc/hiera/override/config/role`` +- ``/etc/hiera/override/config/cluster`` + +Hiera delivers the hierarchical structure of data. + +The top-level granular tasks used to override the configuration have +the ``refresh_on`` parameter. + +Example: + +.. code-block:: yaml + + - id: keystone + type: puppet + groups: [primary-controller, controller] + required_for: [openstack-controller] + requires: [openstack-haproxy, database, rabbitmq] + refresh_on: [keystone_config] + parameters: + puppet_manifest: + /etc/puppet/modules/osnailyfacter/modular/keystone/keystone.pp + puppet_modules: /etc/puppet/modules + timeout: 3600 + test_pre: + cmd: ruby + /etc/puppet/modules/osnailyfacter/modular/keystone/keystone_pre.rb + test_post: + cmd: ruby + /etc/puppet/modules/osnailyfacter/modular/keystone/keystone_post.rb + +Nailgun uses the ``refresh_on`` parameter to run the respective task when user changes the +OpenStack configuration. diff --git a/userdocs/fuel-user-guide/cli/cli_usage.rst b/userdocs/fuel-user-guide/cli/cli_usage.rst new file mode 100644 index 000000000..78add3733 --- /dev/null +++ b/userdocs/fuel-user-guide/cli/cli_usage.rst @@ -0,0 +1,699 @@ + +.. _cli_usage: + +Basic usage +----------- + +Fuel CLI has the following usage pattern: + +:: + + fuel [global optional args] [action] + +*Example*:: + + fuel --env-id=1 node set --node-id=1,4,5 --role=controller + +where ``--env-id=1`` is a global optional argument pointing to the specific +environment, ``node`` - is a namespace for all node control functions, ``set`` +is an action that assigns specific nodes to some environments in certain roles. + +To get the list of all global optional arguments and namespaces, run: +:: + + fuel --help + +To get the list of actions and optional arguments for a namespace, run: +:: + + fuel --help + +Release ++++++++ + +Get list of all available releases: + +:: + + fuel release + +or short version + +:: + + fuel rel + +for specific release + +:: + + fuel rel --rel + +Version ++++++++ + +To get all the details on the Fuel environment installed, run the +following command:: + + fuel fuel-version + +.. warning:: + The argument ``--fuel-version`` will be deprecated since the Fuel + 7.0 release. Please use :command:`fuel-version` command instead. + +Networks configuration +++++++++++++++++++++++ + +Download a network configuration for a specific environment: + +.. code-block:: console + + fuel --env network --download --dir + +where: + +* ```` - an environment ID +* ```` - a path to directory + +For example, download the network configuration for +the environment with ID ``1`` to the current directory: + +.. code-block:: console + + fuel --env 1 network --download + +Upload a network configuration for a specific environment: + +.. code-block:: console + + fuel --env network --upload --dir + +For example, upload the network configuration for +the environment with ID ``1`` from the current directory: + +.. code-block:: console + + fuel --env 1 network --upload + +.. note:: + + The :command:`fuel network` command can update a configuration + for all networks in an environment and Neutron parameters, + but it does not update VIPs and network templates. You have to + update VIPs and network templates additionally using + corresponding Fuel CLI commands. + +Verify a network configuration for a specific environment: + +.. code-block:: console + + fuel --env network --verify --dir + +For example, verify the network configuration for +the environment with ID ``1`` from the current directory: + +.. code-block:: console + + fuel --env 1 network --verify + +.. note:: + + Verification does not work for multiple cluster networks, when + an environment has more than one node group. + + +To see interaction with Nailgun API, run the commands with +the :option:`--debug` option: + +.. code-block:: console + + fuel --env network --download --dir --debug + fuel --env network --upload --dir --debug + fuel --env network --verify --dir --debug + + +Environment ++++++++++++ + +To list environments: + +:: + + fuel env + +To create an environment, run the following command using +``--name`` and ``--rel`` (release) options: + +:: + + fuel env create --name --rel + + +By default it creates environment in ``multinode`` mode, and ``nova`` network mode. +To specify other modes, you can add optional arguments; for example: + +:: + + 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 the environment; for example: + +:: + + fuel --env env set --name --mode ha_compact + +To delete the environment: + +:: + + fuel --env env delete + +To update the Mirantis OpenStack environment to a newer version +(available since Fuel 5.1): + +:: + + fuel env --update --env --rel + +To roll back a failed update, +use this same command but modify the release ID. + + +Node +++++ + +To list all available nodes run: + +:: + + fuel node list + +and filter them by environment: + +:: + + fuel --env-id node list + +Assign some nodes to environment with with specific roles + +:: + + fuel node set --node --role controller --env + fuel node set --node ,, \ + --role compute,cinder --env + +Remove some nodes from environment + +:: + + fuel node remove --node , --env + +Also you can do it without ``--env`` or ``--node`` to remove some nodes without knowing their environment and remove all nodes of some environment respectively. + +:: + + fuel node remove --node , + fuel node remove --env + +.. _remove-inv: + +Delete nodes from Fuel DB. + +* Remove offline nodes: + + :: + + fuel node --node-id --delete-from-db + fuel node --node-id --delete-from-db + +* Remove nodes with any status (``--force`` option forces deletion + of nodes regardless of their state): + + :: + + fuel node --node-id --delete-from-db --force + + +.. _fuel-cli-node-group: + +Node group +++++++++++ + +To list all available node groups: + +:: + + fuel nodegroup + +and filter them by environment: + +:: + + fuel --env nodegroup + +Create a new node group + +:: + + fuel --env nodegroup --create --name "group 1" + +Delete the specified node groups + +:: + + fuel --env nodegroup --delete --group + fuel --env nodegroup --delete --group ,, + +Assign nodes to the specified node group: + +:: + + fuel --env nodegroup --assign --node --group + fuel --env nodegroup --assign --node ,, --group + +.. _network_template_operations: + +Network Template +++++++++++++++++ + +To upload a network template, run the following +command on the Fuel Master node: + +.. code-block:: console + + fuel --env network-template --upload --dir + +where: + +* ```` - an ID of your OpenStack environment that you + can get by running the :command:`fuel environment` command +* ```` - a path to a directory where your template is located + +For example: + +.. code-block:: console + + fuel --env 1 network-template --upload --dir /home/stack/ + +Download a network template to the current directory: + +.. code-block:: console + + fuel --env network-template --download + +For example: + +.. code-block:: console + + fuel --env 1 network-template --download + +Delete an existing network template: + +.. code-block:: console + + fuel --env network-template --delete + +For example: + +.. code-block:: console + + fuel --env 1 network-template --delete + + +.. _network_group_operations: + +Network Group ++++++++++++++ + +List all available network groups: + +.. code-block:: console + + fuel network-group + +List network groups in a particular node group: + +.. code-block:: console + + fuel network-group --node-group + +For example: + +.. code-block:: console + + fuel network-group --node-group 1 + +Create a new network group: + +.. code-block:: console + + fuel network-group --create --node-group --name \ + --release --vlan --cidr --gateway \ + --meta + +where: + +* ```` - an ID of a node group +* ```` - a name of a new network group +* ```` - a release ID this network group belongs to +* ```` - a VLAN of a network +* ```` - a CIDR of a network +* ```` - a gateway of a network +* ```` - meta information in JSON format + +For example: + +.. code-block:: console + + fuel network-group --create --node-group 1 --name "new network" \ + --release 2 --vlan 100 --cidr 10.0.0.0/24 + + fuel network-group --create --node-group 2 --name "new network" \ + --release 2 --vlan 100 --cidr 10.0.0.0/24 --gateway 10.0.0.1 \ + --meta 'meta information in JSON format' + +Set parameters for the specified network group: + +.. code-block:: console + + fuel network-group --set --network -- + +where: + +* ```` - an ID of a network group +* ```` - a parameter you want to set or update. + See the ``fuel network-group --create`` command for the + list of parameters. +* ```` - a new value for the specified parameter + +For example: + +.. code-block:: console + + fuel network-group --set --network 1 --name new_name + +Delete network groups: + +.. code-block:: console + + fuel network-group --delete --network + +For example: + +.. code-block:: console + + fuel network-group --delete --network 1 + +You can also delete multiple groups: + +.. code-block:: console + + fuel network-group --delete --network 2,3,4 + + +.. _vip-operations: + +Virtual IP +++++++++++ + +Download a virtual IP (VIP) configuration for a specific environment to a specified file: + +.. code-block:: console + + fuel --env vip --download --file + +where: + +* ```` - an environment ID +* ```` - a name of the ``yaml`` file where to save a VIP configuration (optional) + +For example: + +.. code-block:: console + + fuel --env 1 vip --download --file vip.yaml + +Upload a VIP configuration for a specific environment from a specified file: + +.. code-block:: console + + fuel --env vip --upload --file + +For example: + +.. code-block:: console + + fuel --env 1 vip --upload --file vip.yaml + + + +.. _roles-operations: + +Roles operations +++++++++++++++++ + +CLI basically implements standard CRUD for operating on a role. + +* List a role: + + :: + + fuel role --rel 2 + + name | id + --------------|--- + controller | 9 + compute | 10 + cinder | 11 + cinder-vmware | 12 + ceph-osd | 13 + mongo | 14 + zabbix-server | 15 + base-os | 16 + + +* Create a new role. + + - In this example, + we first create a swift role in ``swift.yaml``: + + :: + + meta: + description: Installs swift server. + has_primary: true # we need primary-swift and swift during orchestration + name: Swift + name: swift + volumes_roles_mapping: + - allocate_size: min + id: os + + - Then use ``--create`` flag to proceed. When created, + you can start using a new role for your own tasks: + + :: + + fuel role --rel <2> --create --file + + fuel role --rel <2> + + name | id + -------- + swift | 17 + + +* Update role data: + + :: + + fuel role --rel <2> --update --file + +* Delete the role: + + :: + + fuel role --rel <2> --delete --role + + +.. _fuel-cli-config: + +Configuring ++++++++++++ + +Configuration of the environment or some node +is universal and done in three stages: + +1. Download current or default configuration. Works for +(``network``, ``settings``, ``node --disk``, ``node --network``). +Operations with ``deployment`` and ``provisioning`` can be node +specific. (e.g. ``fuel --env 1 deployment --node-id=1,2``) + +*Example*:: + + fuel --env 1 network download + fuel --env 1 settings download + fuel --env 1 deployment default + fuel --env 1 provisioning download + fuel node --node-id 2 --disk --download + +2. Modify the downloaded ``.yaml`` files + with your favorite text editor. +3. Upload files to Nailgun server + +After redeploying your environment with the new configuration, +you should create a new backup +of the Fuel Master node. +You may also want to delete the ``.yaml`` files +since you can easily regenerate them at any time. +Some of the generated ``yaml`` files +contain unencrypted passwords +whose presence on disk may constitute a security threat. + +*Example*:: + + fuel --env 1 provisioning upload + fuel node --node-id 2 --disk --upload + +.. note:: + + To protect yourself when using the Fuel CLI to modify configurations, + note the following: + + * Back up + all your configurations before you begin any modifications. + * If you remove something from a configuration file, + be sure you do not need it; + Fuel CLI overwrites the old data with the new + rather than merging new data with existing data. + * If you upload any changes for provisioning or deployment operations, + you freeze the configuration for the entire environment; + any changes you later make to the networks, cluster settings, + or disk configurations using the Fuel Web UI are not implemented. + To modify such parameters, + you must edit the appropriate section of each node's configuration + and apply the changes with Fuel CLI. + +Deployment +++++++++++ + +For acronyms meaning, +see :ref:`cli-acronyms`. + +You can deploy environment changes with: + +:: + + fuel --env deploy-changes + +Also, you can deploy and provision only some nodes like this + +:: + + fuel node --provision --node , + fuel node --deploy --node , + +.. _cli-fuel-password: + +Change and Set Fuel password +++++++++++++++++++++++++++++ + +You can change the Fuel Master Node password +with either of the following: + +:: + + fuel user --change-password --new-pass= + + +Note that **change-password** option +can also be used without preceding hyphens. + +You can use flags to provide username and password +to other fuel CLI commands: + +:: + + --user=admin --password=test + + +.. note: In Release 5.1 and earlier, the **--os-username** + and ``os-password`` options are used + rather than ``user`` and ``--change-password``. + These options are not supported in Releases 5.1.1 and later. + +.. _fuel-plugins-cli: + +Fuel Plugins CLI +++++++++++++++++ + +* To install a Fuel plugin: + +1. Select from the following options: + +* If you install a Fuel plugin from an `.fp` package, type: + + .. code-block:: bash + + fuel plugins --install + +* If you install a Fuel plugin from an `.rpm` package, select from the + following options: + + * Using ``yum install``: + + 1. Install the Fuel plugin: + + .. code-block:: bash + + yum install + + 2. Register the plugin in Nailgun: + + .. code-block:: bash + + fuel plugins --register == + + * Using the same command you used to install a Fuel plugin from the + `.fp` package: + + .. code-block:: bash + + fuel plugins --install + +2. View the list of installed plugins: + + .. code-block:: bash + + fuel plugins --list + + id | name | version | package_version + ---|---------------------------|----------|---------------- + 1 | | 1.0.0 | 2.0.0 + + +* To remove a plugin, type: + + .. code-block:: bash + + fuel plugins --remove == + + +* To upgrade a Fuel RPM plugin, type: + + .. code-block:: bash + + fuel plugins --update + + + .. note:: Upgradess are *not* supported for: + + * fp plugins + + * major versions of RPM plugins + + For example, you can only upgrade from version 1.0.0 to 1.0.1. + + +To see the list of all available options, use ``fuel plugins --help`` command. diff --git a/userdocs/fuel-user-guide/configure-additional-components.rst b/userdocs/fuel-user-guide/configure-additional-components.rst new file mode 100644 index 000000000..c882979bf --- /dev/null +++ b/userdocs/fuel-user-guide/configure-additional-components.rst @@ -0,0 +1,35 @@ +.. raw:: pdf + + PageBreak + +.. _configure-additional-components: + +Configure additional components +=============================== + +If you have installed additional components, such as the OpenStack application +catalog (Murano), the Telemetry service (Ceilometer), the Bare Metal service +(Ironic), or the Hadoop cluster (Sahara), you may need to complete post- +deployment steps that will ensure your OpenStack environment functions +correctly. + +If you installed any of these components, complete the steps described in the +corresponding sections. + +If you installed Ironic, complete the tasks described in the following +sections: + +.. toctree:: + :maxdepth: 3 + + configure-additional-components/ironic_configure.rst + configure-additional-components/ironic_prepare_image.rst + +If you installed Sahara, complete the tasks described in the following +sections: + +.. toctree:: + :maxdepth: 3 + + configure-additional-components/sahara_configure.rst + diff --git a/userdocs/fuel-user-guide/configure-additional-components/ironic_configure.rst b/userdocs/fuel-user-guide/configure-additional-components/ironic_configure.rst new file mode 100644 index 000000000..7ae93f7a4 --- /dev/null +++ b/userdocs/fuel-user-guide/configure-additional-components/ironic_configure.rst @@ -0,0 +1,88 @@ + +.. _ironic-configure: + +Configure the Bare Metal service +-------------------------------- + +After you deploy an OpenStack environment as described in +:ref:`ironic-install`, you must configure the components required for the +Ironic program. Execute all actions described in this +section as an OpenStack user with administrative privileges. + +**To configure the Bare Metal service:** + +#. Define the memory, CPU, and disk size of physical instances that you will + deploy by creating a nova flavor that matches the server hardware + on which you plan to run instances. Use the following command: + + :: + + nova flavor-create + +#. Optionally, specify additional parameters using the ``nova flavor-key`` + command. + + **Example:** + + :: + + nova flavor-key baremetal-flavor set cpu_arch=x86_64 + +#. View and remember the list of UUIDs for bootstrap images: + + :: + + glance image-list | grep + +#. Enroll the nodes on which you plan to boot instances into the + OpenStack Bare Metal service. + + :: + + ironic node-create [-c ] -d [-i ] [-p + ] [-e ] [-u ] [-n ] + + + .. list-table:: **Fuel drivers** + :widths: 10 25 + :header-rows: 1 + + * - Driver + - Description + * - ``fuel_ssh`` + - Enables communication between the Fuel Master node and other nodes. + * - ``fuel_ipmitool`` + - Enables communication through IPMI. Use with the nodes that require + IPMI, such as nodes that you use for bare-metal deployments. + * - ``fuel-libvirt`` + - Ensures operation of virtual ironic instances hosted on ``libvirt``. + * - ``fake`` + - Used for testing Fuel APIs. + + Use the values from step 1 and step 2. The following text is an example for the + ``fuel_ipmitool`` driver. + + **Example:** + + :: + + ironic node-create [-n ] [-u ] -d fuel_ipmitool + -p memory_mb= -p cpu_arch= + -p local_gb= -p cpus= + -i deploy_kernel= + -i deploy_ramdisk= + -i deploy_squashfs= + -i ipmi_address= + -i ipmi_username= + -i ipmi_password= + +#. Communicate the node's network interface cards to the Bare Metal service by + creating a port with MAC addresses of each network interface: + + :: + + ironic port-create -a -n + +#. Prepare images that you plan to use to deploy physical machines as + described in :ref:`ironic_prepare_image`. diff --git a/userdocs/fuel-user-guide/configure-additional-components/ironic_prepare_image.rst b/userdocs/fuel-user-guide/configure-additional-components/ironic_prepare_image.rst new file mode 100644 index 000000000..1eb0732ed --- /dev/null +++ b/userdocs/fuel-user-guide/configure-additional-components/ironic_prepare_image.rst @@ -0,0 +1,64 @@ +.. _ironic_prepare_image: + +Prepare a physical machine image +-------------------------------- + +If you use default Fuel drivers for Ironic, you must build and upload a +physical machine image into Glance, as well as configure the image with +specific parameters. + +**To prepare a physical machine image:** + +#. Build a physical machine image. + + You can build images for a physical machine using a method of your personal + preference. For example, using Disk Image builder (DIB): + + :: + + disk-image-create -a amd64 -p -o + + **Example:** + + :: + + disk-image-create -a amd64 -p grub2-common,grub-pc, \ + grub-gfxpayload-lists,emacs24-nox,parted baremetal ubuntu-minimal + +#. Upload the image to Glance using the ``glance image-create`` command. + + **Example:** + + :: + + glance image-create --name test --disk-format raw --container-format bare + --file test [--visibility public] + +#. Tag the image with the corresponding metadata. + + **Example:** + + :: + + glance image-update --property cpu_arch=x86_64 + --property hypervisor_type="baremetal" + --property fuel_disk_info=DISK_INFO + + The ``DISK_INFO`` value is a structure that describes the partition layout + required by the image. + + **Example:** + + :: + + ‘[{"name": "sda", "extra": [], "free_space": 11000, "type": "disk", + "id": "vda", "size": 11000, "volumes": [{"mount": "/", "type": + "partition", "file_system": "ext4", "size": 10000}]}]’ + + .. warning:: + Only extended file systems are supported! + +.. seealso:: + + - ``glance help image-create`` + - *Disk Image Builder Documentation* diff --git a/userdocs/fuel-user-guide/configure-additional-components/sahara_configure.rst b/userdocs/fuel-user-guide/configure-additional-components/sahara_configure.rst new file mode 100644 index 000000000..23084857a --- /dev/null +++ b/userdocs/fuel-user-guide/configure-additional-components/sahara_configure.rst @@ -0,0 +1,49 @@ +.. _sahara_configure: + +Configure the Hadoop cluster service +------------------------------------ + +After you deploy your OpenStack environment with +the Hadoop cluster service, upload the +Sahara image to Glance. You must use a +pre-built image for a corresponding Linux distribution. You can build +your own image as described +in the OpenStack Sahara documentation or use one of the pre-built images +available at +`docs.openstack.org/developer/Sahara +`_ +If you use a pre-built image, use the corresponding user name provided on +the same page. + +Sahara supports the following Hadoop platforms: + +- Vanilla Apache Hadoop +- Hortonworks Data Platform (HDP) +- Cloudera Hadoop Distribution (CDH) +- Apache Spark +- MapR + +Typically, the Sahara images are provided in the ``qcow2`` format that is +compatible with the default OpenStack hypervisor KVM. +If you install your environment with VMware vSphere, you must convert +the image to an appropriate format before you upload the image to Glance. + +**To configure the Hadoop cluster service:** + +#. Download or build an appropriate image for the Hadoop cluster. +#. Upload the image to Glance. +#. Log in to Horizon. +#. Register the image in the Sahara Image Registry: + + #. Click :menuselection:`Project --> Data processing --> Image Registry`. + #. Click :guilabel:`Register Image`. + #. Specify the username appropriate to the image you use. + #. Specify a correpsonding plugin and version. + #. Click :guilabel:`Add plugin tags`. + #. Add appropriate tags. + +#. Verify that you have an adequate pool of floating IP addresses available: + + - If you run Neutron networking with + **auto_assign_floating_ip** parameter set to ``False``, provide a + floating IP pool in each Node Group Template. diff --git a/userdocs/fuel-user-guide/configure-environment.rst b/userdocs/fuel-user-guide/configure-environment.rst new file mode 100644 index 000000000..67d1fc550 --- /dev/null +++ b/userdocs/fuel-user-guide/configure-environment.rst @@ -0,0 +1,38 @@ + +.. raw:: pdf + + PageBreak + +.. _configure-env-ug: + +Configure your Environment +========================== + +After you create an OpenStack environment as described in +:ref:`create-env-ug`, you must add nodes, assign roles, and verify your +network configuration. Additionally, you can modify some of the settings +you have already configured, as well as configure other important settings, +such as disk partitioning, network interface bonding, and so on. + +This section includes the following topics: + +.. raw:: pdf + + PageBreak + +.. toctree:: + :maxdepth: 3 + + configure-environment/add-nodes.rst + configure-environment/add-label.rst + configure-environment/change-roles.rst + configure-environment/change-hostname-slave-nodes.rst + configure-environment/network-settings.rst + configure-environment/nic-bonding-ui.rst + configure-environment/selectable-offload.rst + configure-environment/map-logical-to-physical-nic.rst + configure-environment/verify-networks.rst + configure-environment/customize-partitions.rst + configure-environment/settings.rst + configure-environment/dns-ntp-support.rst + diff --git a/userdocs/fuel-user-guide/configure-environment/add-label.rst b/userdocs/fuel-user-guide/configure-environment/add-label.rst new file mode 100644 index 000000000..8828d7894 --- /dev/null +++ b/userdocs/fuel-user-guide/configure-environment/add-label.rst @@ -0,0 +1,33 @@ + +.. _add-label-ug: + +Label an OpenStack node +----------------------- + +In large deployments, sorting nodes by roles may not be efficient. Therefore, +Fuel provides the capability to add custom labels to OpenStack nodes and later +sort and display the nodes with that label. For example, you can label nodes +located in one rack as *rack #1* and so on. Labels can be added and removed +before or after you deploy an OpenStack environment. + +**Label an OpenStack node:** + +#. Log in to the Fuel web UI. +#. Click :guilabel:`Nodes`. +#. Select a node or nodes that you want to label. +#. Click the label icon. +#. Click :guilabel:`Add label`. +#. Type a :guilabel:`Name` and :guilabel:`Value`. + + **Example:** + + * **Name:** Row + * **Value:** 1 + + .. note:: + You can have multiple labels with identical names and different + values. However, you cannot assign labels with identical names + and different values to one node. For example, you cannot assign + label *Row 1* and *Row 2* to one node, but you can assign them to + different nodes. +#. Click :guilabel:`Apply`. diff --git a/userdocs/fuel-user-guide/configure-environment/add-nodes.rst b/userdocs/fuel-user-guide/configure-environment/add-nodes.rst new file mode 100644 index 000000000..9156f2b48 --- /dev/null +++ b/userdocs/fuel-user-guide/configure-environment/add-nodes.rst @@ -0,0 +1,45 @@ + +.. _add-nodes-ug: + +Add a node to an OpenStack environment +-------------------------------------- + +To deploy an OpenStack environment using the Fuel web UI, you must add at +least one controller node. However, for a fully functional cloud you must +allocate a sufficient number of compute and storage nodes. + +An OpenStack node, or a node, is a physical or virtual server that you +provision to run a specific set of OpenStack services. + +A role is a functional set of services that Fuel installs as a whole on a +node, usually in its own disk partition. Some roles can be combined in one +node. + +The number of discovered unallocated and total nodes is displayed in the upper +right corner in the Fuel web UI. + +For more information, see +*System Requirements* in *Fuel Installation Guide*. + +**To add a node to an OpenStack environment:** + +#. Log in to the Fuel web UI. +#. In the :guilabel:`Dashboard` tab, click :guilabel:`Add nodes`. +#. Assign a role or roles to the node by selecting the corresponding option. +#. In the list of discovered nodes, select a physical or virtual node to + provision. +#. Optionally, display the node hardware configuration by clicking the + :guilabel:`Settings` icon next to the discovered node. +#. Click :guilabel:`Apply Changes`. +#. Repeat step 2 - step 6 for all nodes that you want to include into this + OpenStack environment. + + After you add nodes, Fuel enables you to deploy your OpenStack environment. + However, you may need to apply additional changes to fully address your + infrastructure requirements. + +.. seealso:: + + - *System requirements* in *Fuel Installation Guide* + - :ref:`add-label-ug` + - :ref:`change-hostname-slave-nodes` diff --git a/userdocs/fuel-user-guide/configure-environment/change-hostname-slave-nodes.rst b/userdocs/fuel-user-guide/configure-environment/change-hostname-slave-nodes.rst new file mode 100644 index 000000000..401954fca --- /dev/null +++ b/userdocs/fuel-user-guide/configure-environment/change-hostname-slave-nodes.rst @@ -0,0 +1,50 @@ + +.. _change-hostname-slave-nodes: + +Modify the Fuel Slave node host name +------------------------------------ + +You can modify host names of the Fuel Slave nodes before you deploy an +OpenStack environment. This functionality enables you to assign host names +that match your corporate standards or a naming convention of your choice. +You cannot change a host name of a Fuel Slave node after you deploy an +OpenStack environment. + +**To modify the Fuel Slave node host name using Fuel web UI:** + +#. Log in to the Fuel web UI. +#. Click the :guilabel:`Nodes` tab. +#. Click the settings icon next to the corresponding node. +#. Click the edit icon: + + .. image:: /_images/deliverables/scr_change_hostname.png + :width: 60% + +#. Type the new host name. +#. Click :guilabel:`Close`. + +**To modify the Fuel Slave node host name using Fuel CLI:** + +#. Log in to the Fuel Master node CLI. +#. Type: + + .. code-block:: console + + fuel node --node --hostname + + .. list-table:: + :widths: 10 25 + :header-rows: 1 + + * - Value + - Description + * - + - A specific node indentificator. You can get the information about the + node ID by typing: + + .. code-block:: console + + fuel nodes + + * - + - A new host name for the selected node. diff --git a/userdocs/fuel-user-guide/configure-environment/change-roles.rst b/userdocs/fuel-user-guide/configure-environment/change-roles.rst new file mode 100644 index 000000000..746c7f9c5 --- /dev/null +++ b/userdocs/fuel-user-guide/configure-environment/change-roles.rst @@ -0,0 +1,29 @@ + +.. _change-roles: + +Change the role of a node +-------------------------- + +If you have assigned a wrong role or want to add additional roles to a node, +you can modify this setting before you deploy an OpenStack environment, as +well as after the deployment. + +**To change the role of a node:** + +#. In the Fuel web UI, click :guilabel:`Nodes`. +#. Select a node. + + * If the OpenStack environment is not yet deployed: + + #. Click :guilabel:`Edit Roles`. + #. Modify the role as required. + + * If the OpenStack environment has been already deployed: + + #. Click :guilabel:`Delete`. + + Fuel changes the node's status to *Unallocated*. + + #. Click :guilabel:`Add Node`. + #. Select the node and assign a new role or roles to the node as + described in :ref:`add-nodes-ug`. diff --git a/userdocs/fuel-user-guide/configure-environment/customize-partitions.rst b/userdocs/fuel-user-guide/configure-environment/customize-partitions.rst new file mode 100644 index 000000000..9803a4985 --- /dev/null +++ b/userdocs/fuel-user-guide/configure-environment/customize-partitions.rst @@ -0,0 +1,58 @@ + +.. _customize-partitions-ug: + +Configure disk partitioning +--------------------------- + +By default, Fuel allocates a balanced amount of disk space for +all components that will be installed on the corresponding node. +After you assign a role or roles to a node, you can modify the +disk partition as needed. + +If you modify node roles, Fuel resets the disk partition to default settings. + +The following table describes the partition types that you can configure +for each node. + +.. list-table:: **Disk partition types** + :widths: 10 25 + :header-rows: 1 + + * - Type of partition + - Description + * - Base system + - Comprehensive of swap space, includes operating system and basic + software option. + * - Virtual storage + - Storage for virtual instances. + * - Image storage + - Glance stores virtual instance images in this partition. + * - Cinder + - Storage allocated for Cinder. + * - Ceph and Ceph Journal + - Storage allocated for Ceph. + * - MongoDB + - Storage used for Ceilometer information stored in MongoDB. + * - MySQL + - Storage for Zabbix statistics. + +**To configure disk partitioning:** + +#. In the Fuel web UI, click :guilabel:`Nodes`. +#. Select a node or nodes. + + .. note:: + You can select multiple nodes of the same role. The nodes with + the same role must have identical hardware configuration. You cannot + change configuration of multiple nodes with different roles or hardware + in one transaction. + +#. Click :guilabel:`Disk Configuration`. +#. Click on a partition that you want to modify. +#. In the :guilabel:`Volume Groups`, adjust the partition size using the + slider. +#. Alternatively, type the partition size in the corresponding field. + + Fuel adjusts the number you type to satisfy block size boundary + requirements. The display adjusts to show the new allocation. +#. Click :guilabel:`Apply`. diff --git a/userdocs/fuel-user-guide/configure-environment/dns-ntp-support.rst b/userdocs/fuel-user-guide/configure-environment/dns-ntp-support.rst new file mode 100644 index 000000000..b5d7fc3f3 --- /dev/null +++ b/userdocs/fuel-user-guide/configure-environment/dns-ntp-support.rst @@ -0,0 +1,21 @@ + +.. _dns-ntp-support-ug: + +Change the DNS and NTP server settings +-------------------------------------- + +If the Fuel Master node does not have access to the Internet +or if you plan to disable Internet access after deployment, you +may want to change the NTP and DNS servers for the nodes and omit +routing through the Fuel Master node. + +**To change the DNS and NTP server settings:** + +#. In the Fuel web UI, click the guilabel:`Networks` tab. +#. Click :guilabel:`Other`. +#. Type the DNS server IP address or NTP server IP address or FQDN. +#. Click :guilabel:`Save Settings`. + + .. note:: + Fuel does not verify if the specified DNS and NTP services are + available. Verify that you specify correct values. diff --git a/userdocs/fuel-user-guide/configure-environment/map-logical-to-physical-nic.rst b/userdocs/fuel-user-guide/configure-environment/map-logical-to-physical-nic.rst new file mode 100644 index 000000000..9450cc33b --- /dev/null +++ b/userdocs/fuel-user-guide/configure-environment/map-logical-to-physical-nic.rst @@ -0,0 +1,23 @@ + +.. _map-logical-to-physical: + +Map a logical network to a physical interface +--------------------------------------------- + +You may want to allocate specific network interfaces +to handle different types of network traffic to achieve better +performance in your OpenStack environment. +Fuel enables you to modify mappings for your entire network, except for the +*Admin* network for which you can make changes only during the Fuel +Master node installation. + +Network interface mapping can be modified after you deploy an OpenStack +environment. The ``net-config`` task updates the networking configuration. + +**To map a logical network to a physical interface:** + +#. In the Fuel web UI, click :guilabel:`Nodes`. +#. Select a node. +#. Click :guilabel:`Configure Interfaces`. +#. Drag and drop a logical network to the corresponding physical interface + or bond. diff --git a/userdocs/fuel-user-guide/configure-environment/network-settings.rst b/userdocs/fuel-user-guide/configure-environment/network-settings.rst new file mode 100644 index 000000000..3e6556483 --- /dev/null +++ b/userdocs/fuel-user-guide/configure-environment/network-settings.rst @@ -0,0 +1,50 @@ + +.. raw:: pdf + + PageBreak + +.. _network-settings-ug: + +Configure network settings +-------------------------- + +After you select a network topology in the deployment +wizard, you can further configure Neutron L2 and L3 settings, +as well as modify the node network group configuration. + +Fuel creates the *default* node network group that includes the Public, +Storage, Management, Private, and Baremetal networks if you installed +the OpenStack Bare Metal service. The ``default`` node group also uses +the shared Admin network. You can modify parameters of the +Admin network for all other node network groups, if any, except the ``default`` +node network group. + +If you configure multiple node network groups, Fuel configures a gateway +for all networks. + +.. note:: + + When you deploy an environment using Fuel, you can exclude + specific IP addresses so that Fuel does not assign them. + This helps to avoid network conflicts in + case these IP addresses were previously reserved by other + network entities. + + To prevent IP address collisions, set the IP address + range to be used by Fuel. For example, + for nodes and VIPs, excluding the reserved IPs. + In addition, you can specify multiple + IP address ranges. If you have an IP address in use in the middle + of the network IP address range, you can split the range to exclude + the IP addresses in use. + +**To configure network settings:** + +#. In the Fuel web UI, click the :guilabel:`Network` tab. +#. Select a setting and modify as needed. + +.. seealso:: + + - :ref:`nic-bonding-ui` + - :ref:`selectable-offload` + - :ref:`map-logical-to-physical` diff --git a/userdocs/fuel-user-guide/configure-environment/nic-bonding-ui.rst b/userdocs/fuel-user-guide/configure-environment/nic-bonding-ui.rst new file mode 100644 index 000000000..c60409910 --- /dev/null +++ b/userdocs/fuel-user-guide/configure-environment/nic-bonding-ui.rst @@ -0,0 +1,96 @@ + +.. _nic-bonding-ui: + +Configure network bonding +------------------------- + +Network bonding, or network aggregation, or NIC bonding is +a network technology that enables you to maximize throughput by +aggregating multiple physical links into a single high-speed aggregated +network interface. In addition to increasing bandwidth, network bonding +provides fault tolerance. + +You must configure NIC bonding before or in the scope of +mapping logical networks to physical network interfaces. + +The following tables describe the types of one-side and two-side bonding +that Fuel supports. + +.. list-table:: **Types of one-side bonding** + :widths: 10 25 + :header-rows: 1 + + * - Name + - Description + * - ``balance-rr`` + - Implements the round-robin policy. This mode provides load balancing + and fault tolerance. + * - ``Active-backup`` + - Implements the active-backup policy. In this mode, one network interface + is active and other network interface is passive. When an active network + interface fails, a failover occurs and the previously passive NIC + becomes active. + * - ``balance-xor`` + - Implements the XOR policy. Transmit network packets are based on the + selected transmit hash policy. This mode provides load balancing and + fault tolerance. + * - ``Broadcast`` + - Implements the broadcast policy. Transmits network traffic on all slave + interfaces. This mode provides fault tolerance. + * - ``balance-tlb`` + - Adaptive transmit load balancing based on the link + utilization. This mode provides load balancing and fault tolerance. + * - ``balance-alb`` + - Adaptive transmit and receive load balancing based on the + link utilization. This mode provides load balancing and fault + tolerance. + * - ``balance-slb`` + - Modification of the ``balance-alb`` mode. SLB bonding enables a limited + form of load balancing. The mode does not require + information about the remote switch. + SLB assigns each source MAC and VLAN pair to a link and transmits all + packets from the MAC and VLAN pair through that link. + * - ``balance-tcp`` + - Adaptive transmit load balancing among network interfaces. + +.. list-table:: **Types of one-side bonding** + :widths: 10 25 + :header-rows: 1 + + * - Name + - Description + * - ``layer2`` + - Uses XOR of hardware MAC addresses to generate the hash. + * - ``layer2+3`` + - Uses a combination of layer2 and layer3 protocol information to + generate the hash. + * - ``layer3+4`` + - Uses the upper layer protocol information, when available, to generate + the hash. + * - ``encap2+3`` + - Uses the same formula as ``layer2+3``, but relies on + ``skb_flow_dissect`` to obtain the header fields which may result in + the use of inner headers if an encapsulation protocol is used. + * - ``encap3+4`` + - Similar to ``encap2+3``, but uses``layer3+4``. + + +**To configure network interfaces:** + +#. In the Fuel web UI, click the :guilabel:`Nodes` tab. +#. Select nodes. +#. Click :guilabel:`Configure Interfaces` +#. Select network interfaces that you want to aggregate. +#. Click :guilabel:`Bond Network Interfaces`. +#. In the :guilabel:`Mode` drop-down list, select an appropriate bonding + mode. + + .. note:: When bonding an Admin interface, you can select the + ``balance-rr`` and ``Active Backup`` modes. Fuel + supports Admin interface bonding in LACP + mode as an experimental feature. For the ``802.3ad (LACP)`` bond, + you can also select an LACP rate. The values of the LACP + rate include: ``fast`` and ``slow``. + +#. Create and configure additional network interfaces, if needed. +#. Click :guilabel:`Apply`. diff --git a/userdocs/fuel-user-guide/configure-environment/selectable-offload.rst b/userdocs/fuel-user-guide/configure-environment/selectable-offload.rst new file mode 100644 index 000000000..b398225ae --- /dev/null +++ b/userdocs/fuel-user-guide/configure-environment/selectable-offload.rst @@ -0,0 +1,53 @@ + +.. raw:: pdf + + PageBreak + +.. _selectable-offload: + +Edit the offloading mode +------------------------ + +Fuel assigns the default offloading mode to all network interfaces +automatically. You may want to modify this setting to meet your +network requirements. The number of available offloading types +depends on network hardware and the kernel version that you use. + +Fuel automatically detects offloading modes for any physical network +interface. + +**To edit the offloading mode using Fuel web UI:** + +#. Log in to the Fuel web UI. +#. Click :guilabel:`Nodes`. +#. Select a node. +#. Click :guilabel:`Interface configuration`. +#. Click :guilabel:`Offloading Modes: Default` to disable offloading. + +**To edit the offloading mode using CLI:** + +#. Log in to the Fuel Master node CLI. +#. Verify the node ID: + + .. code-block:: console + + fuel nodes + +#. Download the information about network interfaces: + + .. code-block:: console + + fuel node --node --network --download + +#. Open the ``/root/node_/interfaces.yaml`` file for editing. +#. Disable or leave the default value next to the ``state`` field: + + * true - enable offloading modes + * false - disable offloading modes + * null - default offloading modes + +#. Upload the modified file: + + .. code-block:: console + + fuel node --node --network --upload diff --git a/userdocs/fuel-user-guide/configure-environment/settings.rst b/userdocs/fuel-user-guide/configure-environment/settings.rst new file mode 100644 index 000000000..08bd2320a --- /dev/null +++ b/userdocs/fuel-user-guide/configure-environment/settings.rst @@ -0,0 +1,135 @@ + +.. raw:: pdf + + PageBreak + +.. _settings-ug: + +Configure the OpenStack environment settings +-------------------------------------------- + +You can configure security, compute, storage, logging, and other +settings in the :guilabel:`Settings` tab. Most of these settings you have +already configured in the deployment wizard. + +Additionally, you can configure some of the advanced OpenStack settings +by editing the corresponding configuration files. + +**To configure the OpenStack environment settings:** + +#. In the Fuel web UI, click :guilabel:`Settings`. +#. Select a coresponding tab and edit as required: + + .. list-table:: **OpenStack environment settings** + :widths: 10 25 + :header-rows: 1 + + * - Name + - Description + * - **General settings** + - * Access + Enables you to modify access permissions for Horizon. + By default, Fuel assigns user name, password, and tenant *admin*. + * Repositories + Fuel includes default repositories from which it downloads the + packages required to install and update Fuel and OpenStack + components. If you do not have an Internet connection, you can + set + up a local repository and provide the URL to the repository on + this page. + * Kernel parameters + Enables you to modify kernel parameters. This field does not set + kernel + parameters for the Fuel Master node or for nodes that have + already been deployed. + + * - + - The kernel parameters for OpenStack and Fuel include: + + * ``ttys0=`` + Enables serial console for videoless servers. + * ``console=ttyS0,9600`` + Enables serial console. + * ``nofb`` + Disables Linux framebuffer. + * ``nomodeset`` + Disables the video card kernel handling. This parameter may be + required for old integrated server video chips. + * ``intel_iommu and amd_iommu`` + Enables/disables physical-to-virtual address translation for + peripheral devices. Some devices, such as Mellanox cards, + require + this parameter to be enabled. Other peripheral devices may be + incompatible with device virtual address space and may only + work + with real address space. If you are unable to boot a node or + the + node has a kernel panic soon after being booted, setting this + parameter to "off" may resolve the issue. + * ``unsupported_hardware`` + Instructs the operating system to boot even if it does not + recognize some of the configured hardware. Failure to set + this parameter may result in inability for Linux to boot. This + typically happens with the latest CPU models. Because most + hardware + provides backward compatibility with older versions, setting + this + kernel parameter may enable the system to boot. However, if no + backward compatibility is provided, the system may panic or + fail in other ways even with this parameter set. + * - **Security settings** + - Modify security access settings, such as TLS for OpenStack public + checkpoints, HTTPS for Horizon, SSH Public to access Fuel Slave + nodes. + You can use a self-signed certificate or upload a pre-generated key + and certificate. + * - **Compute settings** + - * Hypervisor + Enables you to modify the previously selected option. + * Nova quotas + Sets tenant quotas on CPU and memory usage. + * Resume guests state on host boot + Controls whether to preserve the state of virtual instances + across reboots. + * - **Storage settings** + - * Use qcow format for images + If you select this option, ephemeral volumes will be created as a + copy-on-write layer of the base image. If you do not select this + option, ephemeral volumes will be full copies of the base image. + The default setting is to use copy-on-write for ephemeral + volumes. + If you select to use Ceph RBD as a storage back end for ephemeral + volumes, this setting is ignored. + * Storage Backends + Modify storage options you have previously selected in the + deployment wizard. The storage options that you select must match + the roles you assign to a node. For example, if you select + Ceph as a storage back end, you must configure the appropriate + number of nodes with the *Storage - Ceph OSD* role. + * Ceph object replication factor + Determines the minimum number of Ceph OSD nodes that Fuel must + deploy. For a production environment, deploy at least three Ceph + OSD nodes. + * - **Logging settings** + - Configure the Puppet and OpenStack debug logging and syslog + settings. + + * Common + Typically, you do not need to enable debug logging. Enable debug + logging to analyze the problems in your system. + * Syslog + Fuel deploys an OpenStack environment with the standard Linux + syslog message logging tool. Syslog logs activity of all + OpenStack services. By default, ``rsyslog`` is + configured to use the Fuel Master node as a remote syslog server + that contains all logs generated on all nodes in the OpenStack + environment. If you want to use an external server for + ``rsyslog``, specify an IP address and port number of the server + in the :guilabel:`Syslog` field. + * - **OpenStack services** + - Select additional OpenStack services to deploy. Some OpenStack + services may have additional network and storage requirements. + For more information, see: + :ref:`configure-additional-components`. + +#. Click :guilabel:`Save Settings`. diff --git a/userdocs/fuel-user-guide/configure-environment/verify-networks.rst b/userdocs/fuel-user-guide/configure-environment/verify-networks.rst new file mode 100644 index 000000000..a312ca6b9 --- /dev/null +++ b/userdocs/fuel-user-guide/configure-environment/verify-networks.rst @@ -0,0 +1,31 @@ + +.. raw:: pdf + + PageBreak + +.. _verify-networks-ug: + +Verify network configuration +---------------------------- + +After you configure network settings, verify your network configuration. +Network verification tests connectivity between nodes through configured +VLANs on the configured host interfaces. +Additionally, Fuel verifies that no external DHCP servers interfere with +the OpenStack environment deployment. +If network verification fails, the possible reasons may include incorrect +network configuration, hardware misconfiguration, such as VLAN tagging +is disabled on the switch port, and so on. + +You must resolve all errors before you deploy an OpenStack environment. + +.. note:: + Network verification does not test bond network interfaces. + +**To verify network configuration:** + +#. In the Fuel web UI, click :guilabel:`Networks`. +#. Click :guilabel:`Connectivity Check`. +#. Click :guilabel:`Verify Networks`. +#. Resolve any network conflicts. +#. Run the network verification again. diff --git a/userdocs/fuel-user-guide/create-environment.rst b/userdocs/fuel-user-guide/create-environment.rst new file mode 100644 index 000000000..bc9e9c663 --- /dev/null +++ b/userdocs/fuel-user-guide/create-environment.rst @@ -0,0 +1,25 @@ + +.. raw:: pdf + + PageBreak + + +.. _create-env-ug: + +Create a new OpenStack environment +================================== + +After you install the Fuel Master node, +your Fuel Slave nodes appear as **Unallocated nodes** in the Fuel web UI. +You can now create, configure, and deploy your first OpenStack environment. +You can deploy and manage multiple OpenStack environments using one Fuel +Master node. However, you must create each environment separately. + +This section includes the following topics: + +.. toctree:: + :maxdepth: 3 + + create-environment/start-create-env.rst + create-environment/change-password.rst + diff --git a/userdocs/fuel-user-guide/create-environment/change-password.rst b/userdocs/fuel-user-guide/create-environment/change-password.rst new file mode 100644 index 000000000..01f5d9ad3 --- /dev/null +++ b/userdocs/fuel-user-guide/create-environment/change-password.rst @@ -0,0 +1,19 @@ +.. _change-fuel-passwd-ug: + +Change the Fuel Master node administrative password +--------------------------------------------------- + +We highly recommend that you change the default password for the *admin* +user to the one that meets your company's security requirements. + +**To change the Fuel Administrator password:** + +#. In the Fuel web UI, click the user icon: + +.. image:: /_images/deliverables/scr_change_pass_ui.png + +#. Click :guilabel:`Change Password`. +#. Type the current password, the new password, and then confirm the new + password. + To display what you type, click the eye icon. +#. Click :guilabel:`Apply`. diff --git a/userdocs/fuel-user-guide/create-environment/start-create-env.rst b/userdocs/fuel-user-guide/create-environment/start-create-env.rst new file mode 100644 index 000000000..73755efd1 --- /dev/null +++ b/userdocs/fuel-user-guide/create-environment/start-create-env.rst @@ -0,0 +1,75 @@ + +.. _start-create-env-ug: + +Create an OpenStack environment in the deployment wizard +-------------------------------------------------------- + +Before you deploy an OpenStack environment, you must decide and +prepare hardware for the network topology, types of storage, hypervisor, +OpenStack release version, additional OpenStack services, and other +components that you want to deploy. Additional OpenStack programs and +Fuel plugins may have additional hardware requirements and architectural +limitations. For more information, see: *System requirements* in the +*Fuel Installation Guide*. + +.. If you are deploying a Mirantis OpenStack environment + that is integrated with VMware vSphere, your environment must meet + the prerequisites listed in *Install VMware* in *Fuel Installation Guide*. + +**To create an OpenStack environment:** + +#. Access the Fuel web UI by pointing your web browser to + http://10.20.0.2:8443. + + The Fuel login screen appears: + + .. image:: /_images/deliverables/scr_fuel_log_in.png + :width: 35% + +#. Log in to the Fuel web UI as *admin*: + + #. If you did not change the default password for *admin*, use the + default password *admin*. + + #. If you changed the default password for *admin*, use that password. + + .. warning:: + For your security, change the default password. See: + :ref:`change-fuel-passwd-ug`. + +#. If you are logging in to the Fuel Web UI for the first time, select whether + you want to send usage statistics or not by clicking :guilabel:`Connect + now` or :guilabel:`Connect later`. + +#. Click :guilabel:`New OpenStack Environment`. + + The deployment wizard starts. + +#. In the :guilabel:`Name and Release` screen, type a name of the OpenStack + environment and select an OpenStack release and an operating system on which + you want to deploy your OpenStack environment. + +#. In the :guilabel:`Compute` screen, select a hypervisor. + + By default, Fuel uses QEMU with KVM acceleration. + +#. In the :guilabel:`Networking Setup` screen, select a network topology. + + By default, Fuel deploys Neutron with VLAN segmentation. + +#. In the :guilabel:`Storage Backends`, select options for the storage back + ends. + + By default, Fuel deploys Logical Volume Management (LVM) for Cinder, local + disk for Swift, and Swift for Glance. + +#. In the :guilabel:`Additional Services`, select additional OpenStack + programs that you want to deploy. + +#. In the :guilabel:`Finish` screen, click :guilabel:`Create`. + + Fuel creates an OpenStack environment. Before you can use the environment + you must add nodes, verify network settings, and complete other + configuration tasks. + +#. Proceed to :ref:`configure-env-ug`. diff --git a/userdocs/fuel-user-guide/deploy-environment.rst b/userdocs/fuel-user-guide/deploy-environment.rst new file mode 100644 index 000000000..d1f21e4d9 --- /dev/null +++ b/userdocs/fuel-user-guide/deploy-environment.rst @@ -0,0 +1,20 @@ + +.. raw:: pdf + + PageBreak + +.. _deploy-env: + +Deploy an Openstack Environment +=============================== + +After finishing configuration, you can deploy your OpenStack environment. + +This section includes the following topics: + +.. toctree:: + :maxdepth: 3 + + deploy-environment/deploy-changes.rst + deploy-environment/stop-deploy-ui.rst + deploy-environment/reset-environment.rst diff --git a/userdocs/fuel-user-guide/deploy-environment/deploy-changes.rst b/userdocs/fuel-user-guide/deploy-environment/deploy-changes.rst new file mode 100644 index 000000000..6f12004da --- /dev/null +++ b/userdocs/fuel-user-guide/deploy-environment/deploy-changes.rst @@ -0,0 +1,24 @@ +.. _deploy-changes: + +Deploy changes +-------------- + +When you have completed configuring your OpenStack environment as +described in :ref:`create-env-ug` and :ref:`configure-env-ug`, you +can start the deployment. + +.. warning:: + After you deploy an OpenStack environment, you will not be able to + modify many of the OpenStack parameters, such as network topology, + disk partitioning, and so on. Verify that you have applied correct + settings. + +**To deploy an OpenStack environment:** + +#. In the Fuel web UI, select the :guilabel:`Dashboard` tab. +#. Click :guilabel:`Deploy changes`. + + Fuel deploys your OpenStack environment. Depending on the configuration + of the environment, the deployment may take from fifteen minutes + to an hour. + diff --git a/userdocs/fuel-user-guide/deploy-environment/reset-environment.rst b/userdocs/fuel-user-guide/deploy-environment/reset-environment.rst new file mode 100644 index 000000000..cc2d5902a --- /dev/null +++ b/userdocs/fuel-user-guide/deploy-environment/reset-environment.rst @@ -0,0 +1,22 @@ +.. index:: Reset an environment after deployment + +.. contents :local: + +.. _reset_environment: + +Reset an OpenStack environment after deployment +----------------------------------------------- + +You may want to reset an OpenStack environment after it was +successfully deployed, failed to deploy with an error, or +you have interrupted the deployment to modify the settings. +After you reset an OpenStack environment, Fuel reboots all +Fuel Slave nodes and returns them to the *Unallocated* state. + +**To reset an OpenStack environment:** + +#. In the Fuel web UI, click the :guilabel:`Dashboard` tab. +#. Click :guilabel:`Reset`. +#. Wait while Fuel reboots the nodes. The nodes must have the + status :guilabel:`Online`. +#. Configure and deploy a new environment. diff --git a/userdocs/fuel-user-guide/deploy-environment/stop-deploy-ui.rst b/userdocs/fuel-user-guide/deploy-environment/stop-deploy-ui.rst new file mode 100644 index 000000000..5ba21dc8e --- /dev/null +++ b/userdocs/fuel-user-guide/deploy-environment/stop-deploy-ui.rst @@ -0,0 +1,37 @@ +.. _stop_deployment: + +Interrupt the OpenStack environment deployment +---------------------------------------------- + +You may need to interrupt the deployment of your OpenStack +environment if you have applied incorrect settings. + +Depending on the status of deployment, deployment interruption +may result in various outcomes. + +**To interrupt the OpenStack environment deployment:** + +#. In the Fuel web UI, click the :guilabel:`Dashboard` tab. +#. In the deployment progress bar area, click :guilabel:`Stop`. +#. Click the :guilabel:`Nodes` tab. + + * If no nodes have finished deployment, all nodes are rebooted + to the bootstrap state and appear as *Offline*. + Fuel resets the environment to the state before you have + started the deployment. + + #. Wait until Fuel reboots the nodes. + The nodes must appear as *Online*. All settings in all tabs + must be unlocked. + #. Apply any required changes to the OpenStack environment + configuration. + #. Deploy your OpenStack environment. + + * If some nodes have already been deployed and have the *Ready* status, + Fuel reboots only the nodes that have not finished deployment. + Settings remain locked. + + #. Reset the OpenStack environment as described in + :ref:`reset_environment`. + #. Configure your OpenStack environment. + #. Deploy your OpenStack environment. diff --git a/userdocs/fuel-user-guide/install-additional-components.rst b/userdocs/fuel-user-guide/install-additional-components.rst new file mode 100644 index 000000000..5e302a3c4 --- /dev/null +++ b/userdocs/fuel-user-guide/install-additional-components.rst @@ -0,0 +1,26 @@ +.. raw:: pdf + + PageBreak + +.. _install-additional-components: + +Install additional components +============================= + +If you want to install additional components, such as the OpenStack +Application Catalog service (Murano), the Telemetry service (Ceilometer), the +Bare Metal service (Ironic), or the Hadoop cluster (Sahara), you must +select a corresponding checkbox in the deployment wizard. However, +some components require additional configuration before +installation. This section describes the installation process for +the OpenStack programs that require additional attention. + +Follow the steps described in the corresponding sub-sections of this section. + +This section includes the following topics: + +.. toctree:: + :maxdepth: 3 + + install-additional-components/ironic-install.rst + install-additional-components/sahara-install.rst diff --git a/userdocs/fuel-user-guide/install-additional-components/ironic-install.rst b/userdocs/fuel-user-guide/install-additional-components/ironic-install.rst new file mode 100644 index 000000000..fdea8d1d4 --- /dev/null +++ b/userdocs/fuel-user-guide/install-additional-components/ironic-install.rst @@ -0,0 +1,70 @@ +.. _ironic-install: + +Install the OpenStack Bare Metal service +---------------------------------------- + +Before you install the OpenStack Bare Metal service (Ironic) verify that your +environment meets *Prerequisites for physical machines* and *Bare Metal +service limitations* in the +*Fuel Installation Guide*. + +You install the OpenStack Bare Metal service when you deploy an OpenStack +environment. Follow the steps described in :ref:`create-env-ug` and +:ref:`configure-env-ug` to configure other components and settings of your +OpenStack environment. Then, follow the steps described in this section to +configure Ironic in the deployment wizard. + +**To install the OpenStack Bare Metal service:** + +#. Configure the new environment as described in :ref:`create-env-ug`. + + For Ironic you must select: + + * In :guilabel:`Networking Setup` - :guilabel:`Neutron with VLAN + segmentation`. + * In :guilabel:`Additional Services` - :guilabel:`Install Ironic`. + +#. In the :guilabel:`Dashboard`, click :guilabel:`Add nodes`. +#. In the :guilabel:`Nodes` tab, add nodes with the *Ironic* role. + + We recommend that you assign separate nodes for the Ironic program and do + not combine the *Ironic* role with any other roles. However, if you do not + have sufficient hardware, you can combine the *Ironic* and *Controller* roles + in one node. +#. Add all other nodes required for your environment as described in + :ref:`configure-env-ug`. +#. Select nodes with the *Ironic* and *Controller* roles. +#. Click :guilabel:`Configure Interfaces`. +#. Assign network interfaces that will be used for *baremetal* network by + dragging the *baremetal* network to the required NIC. + + **Example:** + + .. image:: /_images/deliverables/scr_ironic_baremetal_nic_example.png + :width: 100% + +#. In the :guilabel:`Network` tab, configure the :guilabel:`Baremetal + network`. + + * For the OpenStack nodes: + + #. Click :guilabel:`Neutron L2`. + #. Specify CIDR of the *baremetal* network. + #. Type the IP range that will be assigned to OpenStack service nodes + in the *baremetal* network. + #. Specify whether to use VLAN tagging or not. + + * For the bare-metal nodes: + + #. Click :guilabel:`Neutron L3`. + #. Specify an IP range for the nodes on which you will deploy physical + machines. + + Assign the IP range from the CIDR you configured for of the + *baremetal* network in the previous step. + + #. Assign a gateway IP address. + +#. Configure other settings for your OpenStack environment as described in + :ref:`configure-env-ug`. +#. Proceed to :ref:`Configure the Bare Metal service `. diff --git a/userdocs/fuel-user-guide/install-additional-components/sahara-install.rst b/userdocs/fuel-user-guide/install-additional-components/sahara-install.rst new file mode 100644 index 000000000..f00fecdef --- /dev/null +++ b/userdocs/fuel-user-guide/install-additional-components/sahara-install.rst @@ -0,0 +1,20 @@ + +.. _sahara-install: + +Install the Hadoop cluster service +---------------------------------- + +You install the OpenStack Hadoop cluster service, or Sahara, when you +deploy an OpenStack +environment. Follow the steps described in :ref:`create-env-ug` and +:ref:`configure-env-ug` to configure other components and settings of your +OpenStack environment. Then, follow the steps described in this section to +configure Ironic in the deployment wizard. + +**To install the Hadoop cluster service:** + +#. Create and configure your environment as described in :ref:`create-env-ug`. +#. On the :guilabel:`Additional Services` page, select + :guilabel:`Install Sahara`. +#. Configure and deploy your environment. +#. Proceed to :ref:`sahara_configure`. diff --git a/userdocs/fuel-user-guide/introduction.rst b/userdocs/fuel-user-guide/introduction.rst new file mode 100644 index 000000000..93273979f --- /dev/null +++ b/userdocs/fuel-user-guide/introduction.rst @@ -0,0 +1,18 @@ + +.. index:: Introduction + +.. _User-Introduction: + +Introduction to the User Guide +============================== + +The Fuel User Guide provides instructions on how to configure, test, and +operate OpenStack environments using Fuel web UI and CLI. + +If you have already deployed OpenStack environments using earlier versions +of the Fuel software, see the *Upgrading Fuel* section in the Fuel Installation +Guide for instructions on upgrading your existing OpenStack distribution and +the Fuel software. + +Before you read this document, you must install the Fuel Master node as +described in the *Fuel Installation Guide*. diff --git a/userdocs/fuel-user-guide/maintain-environment.rst b/userdocs/fuel-user-guide/maintain-environment.rst new file mode 100644 index 000000000..1e45b5782 --- /dev/null +++ b/userdocs/fuel-user-guide/maintain-environment.rst @@ -0,0 +1,19 @@ +.. _maintain-environment: + +Maintain your environment +========================= + +After your deployed your OpenStack environment, you +manage many operations through the Horizon dashboard. +However, such operations as adding or removing nodes, +changing environment settings, and so on must be performed +in the Fuel UI or CLI. + +This section includes the following topics: + +.. toctree:: + :maxdepth: 3 + + maintain-environment/rollback-ug.rst + maintain-environment/use-shotgun.rst + maintain-environment/role-operations.rst diff --git a/userdocs/fuel-user-guide/maintain-environment/role-operations.rst b/userdocs/fuel-user-guide/maintain-environment/role-operations.rst new file mode 100644 index 000000000..4a41ba0bb --- /dev/null +++ b/userdocs/fuel-user-guide/maintain-environment/role-operations.rst @@ -0,0 +1,63 @@ + +Role object +------------ + +Beginning with Fuel 6.1, +you can create, update or delete roles +using Nailgun +REST API and Fuel Client. + +For Fuel CLI command reference, see +:ref:`Role operations `. + +This section provides the Controller +role example: + +:: + + id: 9 + meta: + conflicts: + - compute + description: The controller initiates orchestration activities and provides an external + API. Other components like Glance (image storage), Keystone (identity management), + Horizon (OpenStack dashboard) and Nova-Scheduler are installed on the controller + as well. + has_primary: true + limits: + min: 1 + overrides: + - condition: cluster:mode == 'multinode' + max: 1 + message: Multi-node environment can not have more than one controller node. + - condition: cluster:mode == 'ha_compact' + message: At least 3 controller nodes are recommended for HA deployment. + recommended: 3 + name: Controller + update_required: + - compute + - cinder + name: controller + volumes_roles_mapping: + - allocate_size: min + id: os + - allocate_size: all + id: image + +The following fields are mandatory: + +:: + + name: controller + meta: + name: Controller + description: Description goes here + + # at least one volume is required + volumes_roles_mapping: + - allocate_size: min + id: os + +Primary behaviour for node can be enabled with ``has_primary: true`` option. +If this option is set to ``during orchestration``, you will be able to assign separate +tasks for primary-controller and controller. diff --git a/userdocs/fuel-user-guide/maintain-environment/rollback-ug.rst b/userdocs/fuel-user-guide/maintain-environment/rollback-ug.rst new file mode 100644 index 000000000..246088ed2 --- /dev/null +++ b/userdocs/fuel-user-guide/maintain-environment/rollback-ug.rst @@ -0,0 +1,183 @@ + +.. _rollback-ug: + + +Rollback +======== + +You can use the rollback feature to return +a node to its original state (e.g. the state before the node failed). +This can be used to revert changes during a failed upgrade or other +node malfunction. + +The rollback is done in two major steps: + +#. Partition preservation -- prevent the node redeployment process + from deleting data on the partition. This way you will not have to + manually back up and restore the data to perform the rollback. + +#. Node reinstallation -- restore the node to its original state. + +Partition preservation +---------------------- + +With partition preservation you can keep any type of data that meets +the following criteria: + +* The data is stored on a dedicated partition. +* The partition is not a root partition. (The root partition is always + erased during deployment). + +The following data types are a good example of what can be preserved: + +* Ceph data +* Swift data +* Nova instances cache +* Database, custom partition types + +.. note:: Do not change the partition size as this will make the + the rollback impossible. + +#. On the Fuel Master node, dump the disks information: + + :: + + fuel node --node-id --disk --download + + where points to a specific node identified by its ID + (a number) that you can get by issuing the ``fuel nodes`` command. + + For example:: + + fuel node --node-id 1 --disk --download + +#. Edit the ``/root/node_1/disks.yaml`` file to enable partition + preservation by using the ``keep_data: true`` flag. Also note that + all partitions with the same name need to have the same flag value. + + Example of the flag in a ``disks.yaml`` file:: + + - extra: + - disk/by-id/scsi-SATA_QEMU_HARDDISK_QM00001 + - disk/by-id/ata-QEMU_HARDDISK_QM00001 + id: disk/by-path/pci-0000:00:01.1-scsi-0:0:0:0 + name: sdc + size: 101836 + volumes: + - name: mysql + size: 101836 + keep_data: true + +#. Upload the modified file:: + + fuel node --node-id --disk --upload + + where points to a specific node identified by its ID + (a number) that you can get by issuing the ``fuel nodes`` command. + + For example:: + + fuel node --node-id 1 --disk --upload + +Node reinstallation +------------------- + +#. On the Fuel Master node, issue the following command to reprovision + the node:: + + fuel node --node-id --provision + + where points to a specific node identified by its ID + (a number) that you can get by issuing the ``fuel nodes`` command. + + For example:: + + fuel node --node-id 1 --provision + +#. Then issue the following command to redeploy the node:: + + fuel node --node-id --deploy + + where points to a specific node identified by its ID + (a number) that you can get by issuing the ``fuel nodes`` command. + +Virt role reinstallation +------------------------ + +Follow the steps below to reinstall the virt role if you have the +Reduced Footprint feature enabled. + +#. On the Fuel Master node, dump the disks information: + + :: + + fuel node --node-id --disk --download + + where points to the node with virt role identified by its ID + (a number) that you can get by issuing the ``fuel nodes`` command. + For example:: + + fuel node --node-id 1 --disk --download + +#. Edit the `/root/node_1/disks.yaml` file to enable the partition + preservation of the volume with ``vm`` name using the ``keep_data: true`` + flag of the corresponding volumes. Note that all partitions with + the same name need to have the same flag value. + + Example of the flag in a `disks.yaml` file:: + + - extra: + - disk/by-id/wwn-0x5000c5007a287855 + - disk/by-id/scsi-SATA_ST2000DM001-1ER_Z4Z1WH2V + - disk/by-id/ata-ST2000DM001-1ER164_Z4Z1WH2V + id: disk/by-path/pci-0000:00:1f.2-scsi-0:0:0:0 + name: sda + size: 1907037 + volumes: + - keep_data: false + name: os + size: 67584 + - keep_data: false + name: cinder + size: 919726 + - keep_data: true + name: vm + size: 919727 + +#. Upload the modified file:: + + fuel node --node-id --disk --upload + + where points to a specific node identified by its ID + (a number) that you can get by issuing the ``fuel nodes`` command. + + For example:: + + fuel node --node-id 1 --disk --upload + +#. On the Fuel Master node, reprovision the node:: + + fuel node --node-id --provision + + where points to a specific node identified by its ID + (a number) that you can get by issuing the ``fuel nodes`` command. + + For example:: + + fuel node --node-id 1 --provision + +#. Provision the bare-metal node with the virtual role and spawn + virtual machines:: + + fuel2 env spawn-vms + + For example:: + + fuel2 env spawn-vms 1 + +#. Redeploy the spawned node:: + + fuel node --node-id --deploy + + where points to a specific node identified by its ID + (a number) that you can get by issuing the ``fuel nodes`` command. diff --git a/userdocs/fuel-user-guide/maintain-environment/use-shotgun.rst b/userdocs/fuel-user-guide/maintain-environment/use-shotgun.rst new file mode 100644 index 000000000..ed37d2a6f --- /dev/null +++ b/userdocs/fuel-user-guide/maintain-environment/use-shotgun.rst @@ -0,0 +1,51 @@ + +.. _shotgun-ug: + +Create diagnostic snapshot using shotgun +======================================== + +Shotgun is a tool that you can use to generate diagnostic snapshots +for Fuel. Although, Fuel API for diagnostic snapshots provides similar +functionality, you may prefer to use Shotgun due to the following limitations +of Fuel API: + +* When the size of log files is too big, Fuel drops a timeout exceptions. +* When you use Fuel API, you may run out of space in the */var/* partition. + +Therefore, use Shotgun from the Fuel Master node directly and fetch the +default configuration from the Fuel Client. + +Shotgun stores temporary snapshots in ``/var/www/nailgun/dump/fuel-snapshot``. +A symlink to the last compressed snapshot is located in +``/var/www/nailgun/dump/last``. + +With Shotgun you can use standard commands, such as :command:`dir`, +:command:`command`, and :command:`file`: + +.. code-block:: ini + + - command: brctl show + to_file: brctl_show.txt + type: command + - path: /etc/sysconfig/network-scripts + type: dir + +**To use Shotgun:** + +#. Install Shotgun on the Fuel Master node: + + .. code-block:: console + + yum install -y shotgun + +#. Fetch the default configuration: + + .. code-block:: console + + fuel snapshot --conf > dump_conf.yaml + +#. Provide the configuration to Shotgun and execute it: + + .. code-block:: console + + shotgun -c dump_conf.yaml diff --git a/userdocs/fuel-user-guide/next-steps.rst b/userdocs/fuel-user-guide/next-steps.rst new file mode 100644 index 000000000..690596f1d --- /dev/null +++ b/userdocs/fuel-user-guide/next-steps.rst @@ -0,0 +1,63 @@ + +.. _next-steps-ug: + +Next Steps +========== + +After you successfully deploy your OpenStack environment, +you must verify that your environment is operational, as well as configure +additional components. After completing the verification, log in to the +Horizon dashboard or the OpenStack CLI to operate your environment. + +Configure and verify the following: + +#. If you have installed additional OpenStack components, such as the + OpenStack application catalog (Murano), the Telemetry service (Ceilometer), + the Bare Metal Service (Ironic), or the Hadoop cluster (Sahara), complete + the tasks described in the corresponding sub-section in + :ref:`configure-additional-components`. + +#. Set up shell access to Fuel Master and Fuel Salve nodes to use OpenStack + CLI. + +#. Verify that the deployed environment is operational by running the following + tests: + + - Network configuration test in the :guilabel:`Networks` tab. + + Although you may have already run this test before you deployed + the OpenStack environment, you may want to verify the network + configuration once again. + + - Environment health checks described in :ref:`verify-environment` + + - Additional components verification. If you have installed any + additional components, prepare and run the corresponding tests: + + - :ref:`sahara-test-prepare` + - :ref:`murano-test-prepare` + + - Ceph configuration test: + + - If you have deployed Ceph as a storage back end, + follow the `Verifying the deployment + `_ + instructions to verify the Ceph configuration. + +#. Create a backup of your environment and store it in a safe location. +#. Log in to the Horizon dashboard by clicking :guilabel:`Go to Horizon` + or to the command-line interface to manage your OpenStack environment. + + .. note:: + After you deploy an OpenStack environment, manage the environment + from the Horizon dashboard. Use Fuel UI for testing, managing OpenStack + nodes, and troubleshooting. + +.. seealso:: + + - `Network Troubleshooting + `_ + - `OpenStack User Guide + `_ + - `Managing Projects and Users + `_ diff --git a/userdocs/fuel-user-guide/verify-environment.rst b/userdocs/fuel-user-guide/verify-environment.rst new file mode 100644 index 000000000..49222c3e9 --- /dev/null +++ b/userdocs/fuel-user-guide/verify-environment.rst @@ -0,0 +1,38 @@ +.. _verify-environment: + +Verify your OpenStack environment +================================= + +After you have successfully deployed your OpenStack environment, run +the build-in health tests to ensure your environment is +fully operational. + +Health tests have the following advantages: + +* Using post-deployment checks helps you identify potential issues which may + impact the health of a deployed system. +* All post-deployment checks provide detailed descriptions about failed + operations and tell you which component or components are not working + properly. +* Performing these checks manually would consumed a great deal of time, but it + only take a few minutes to run the full suite of tests from the Fuel console. +* Aside from verifying that everything is working correctly, the process also + determines how quickly your system works. +* Post-deployment checks continue to be useful after you initially deploy your + environment. For example, after sizable changes are made in the environment, + you can use the checks to determine if any new failure points have been + introduced. + +This section includes the following topics: + +.. toctree:: + :maxdepth: 3 + + verify-environment/intro-health-checks.rst + verify-environment/run-health-checks.rst + verify-environment/troubleshoot-health-checks.rst + verify-environment/murano-test-prepare.rst + verify-environment/murano-test-details.rst + verify-environment/sahara-test-prepare.rst + verify-environment/sahara-test-details.rst + verify-environment/heat-test-details.rst diff --git a/userdocs/fuel-user-guide/verify-environment/heat-test-details.rst b/userdocs/fuel-user-guide/verify-environment/heat-test-details.rst new file mode 100644 index 000000000..bb722eaba --- /dev/null +++ b/userdocs/fuel-user-guide/verify-environment/heat-test-details.rst @@ -0,0 +1,81 @@ + +.. _heat-test-details: + +Overview of the OpenStack Orchestration service platform tests +-------------------------------------------------------------- + +If you have installed the OpenStack Orchestration service (Heat) in +your OpenStack environment, Fuel provides the automatic tests to +verify its functionality. + +The following table describes the details of the Heat tests. + +.. list-table:: **Heat platform tests** + :widths: 10 10 20 + :header-rows: 1 + + * - Name + - Description + - Scenario + * - **Test basic stack operations.** + - The test verifies that the Heat service can create, update, and + delete a stack, as well as shows details of the stack and + its resources, events, and template. + - #. Create a stack. + #. Wait for the stack status to change to ``CREATE_COMPLETE``. + #. Get details of the created stack by its name. + #. Get the list of resources for the created stack. + #. Get details of the stack resources. + #. Get the list of events for the created stack. + #. Get the details of the stack event. + #. Update the stack. + #. Wait for the stack to update. + #. Get the stack template details. + #. Get the list of resources for the updated stack. + #. Delete the stack. + #. Wait for the stack to delete. + * - **Test the stack autoscaling.** + - The test verifies that the Heat service can scale the stack capacity + up and down automatically according to the changes in the + configuration. + Image with cfntools package should be imported. + - #. Create a flavor. + #. Create a keypair. + #. Save the generated private key to a file on the controller node. + #. Create a security group. + #. Create a stack. + #. Wait for the stack status to change to 'CREATE_COMPLETE'. + #. Create a floating IP. + #. Assign the floating IP to the instance of the stack. + #. Wait for the ``cloud_init`` procedure to complete on the instance. + #. Load CPU of the instance to initiate the stack scaling up. + #. Wait for the second instance to launch. + #. Release CPU of the instance to initiate the stack scaling down. + #. Wait for the second instance to be terminated. + #. Delete the file with the private key on the controller node. + #. Delete the stack. + #. Wait for the stack to delete. + * - **Test the stack rollback functionality.** + - The test verifies that the Heat service can rollback the stack + if its creation failed. + - #. Start stack creation with rollback enabled. + #. Verify that the stack appears with status ``CREATE_IN_PROGRESS``. + #. Wait for the stack to be deleted as a result of the rollback after + the expiration of the timeout defined in the ``WaitHandle`` resource + of the stack. + #. Verify that the instance of the stack has been deleted. + * - **Test advanced stack operations.** + - The test verifies that the Heat service can suspend and resume the + stack. + - #. Create a stack. + #. Wait until the stack status changes to ``CREATE_COMPLETE``. + #. Call the stack suspend action. + #. Wait until the stack status changes to ``SUSPEND_COMPLETE``. + #. Call the stack resume action. + #. Wait until the stack status changes to ``RESUME_COMPLETE``. + #. Call the stack check action. + #. Wail until the stack status changes to ``CHECK_COMPLETE``. + #. Delete the stack. + #. Wait for the stack to be deleted. + + diff --git a/userdocs/fuel-user-guide/verify-environment/intro-health-checks.rst b/userdocs/fuel-user-guide/verify-environment/intro-health-checks.rst new file mode 100644 index 000000000..c068a346b --- /dev/null +++ b/userdocs/fuel-user-guide/verify-environment/intro-health-checks.rst @@ -0,0 +1,87 @@ +.. raw:: pdf + + PageBreak + +.. index:: Fuel UI: Post-Deployment Check + +.. _intro-health-checks: + +Health checks +------------- + +Fuel provides capabilities to analyze your OpenStack environment +functionality through health checks. Fuel's health checks provide +status information about the most commonly used +components and the most recently performed actions. + +The following table describes the Fuel automated health checks. + +.. list-table:: **Fuel automated health checks** + :widths: 10 30 25 + :header-rows: 1 + + * - Category + - Description + - Tests + * - **Sanity tests** + - Verify overall system operability. If these tests fail, you may + need to restart some OpenStack services. Sanity tests will likely + be the point on which the success of your deployment pivots, but it is + critical to pay close attention to all information collected from + theses tests. + - Include multiple tests that requests the lists of various OpenStack + objects, configurations, and services. If you deploy additional + OpenStack services, include tests specific to these services. + * - **Functional tests** + - Reveal networking, system-requirements, and functionality issues. + Functional tests verify basic OpenStack operations in normal + conditions. + - Include multiple tests that create or launch various OpenStack + objects and virtual instances. + * - **High-availability tests** + - Verify that the high-availability architecture functions correctly. + These tests include verification of RabbitMQ availability, HAproxy + back ends status and so on. + - Include tests that verify that various components, such as RabbitMQ, + Pacemaker, the Galera cluster, and son on are highly-available and + operational. + * - **Platform services functional tests** + - Verify basic functionality of the Orchestration service (Heat), + Hadoop service (Sahara), Telemetry service (Ceilometer), + and Application Catalog service (Murano). + - Include multiple tests that verify functionality of additional + OpenStack components. Some services, such as Sahara and Murano, + require additional preparation before running a test. + + For more information, see: + + * :ref:`sahara-test-prepare` + * :ref:`sahara-test-details` + * :ref:`murano-test-prepare` + * :ref:`murano-test-details` + * :ref:`heat-test-details` + + * - **Cloud validation tests** + - Verify that your cloud functions correctly. These tests verify that + your + nodes have enough free space, as well as various cloud settings, such + as log rotation and so on. + - Cloud validation tests include: + + * Check the disk space outages on the Controller and Compute nodes. + * Check log rotation configuration on all nodes. + + * - **Configuration tests** + - Verify Fuel configuration. For example, one of the tests verifies that + you have changed the default password and suggests to change it if you + did not. + - Configuration tests include: + + * Check usage of the default credentials (password) for root user to + SSH on the Fuel Master node. If the default password has not been + not changed, the test fails with a recommendation to change it. + * Check usage of the default credentials for the OpenStack environment. + If you use the default values for the admin user, the test fails + with a recommendation to change the password and user name for the + OpenStack user with the admin role. + diff --git a/userdocs/fuel-user-guide/verify-environment/murano-test-details.rst b/userdocs/fuel-user-guide/verify-environment/murano-test-details.rst new file mode 100644 index 000000000..f9378ba30 --- /dev/null +++ b/userdocs/fuel-user-guide/verify-environment/murano-test-details.rst @@ -0,0 +1,45 @@ + +.. _murano-test-details: + +Murano platform test details +---------------------------- + +If you have installed the OpenStack Application Catalog (Murano) in your +OpenStack environment, you can test that Murano functions correctly by +running the Fuel platform tests. + +The following table describes the details of the OpenStack Application +Catalog tests. + +.. list-table:: **Murano platform tests** + :widths: 10 10 20 + :header-rows: 1 + + * - Name + - Description + - Scenario + * - **Murano environment with the WordPress application deployment** + - The test verifies that the user can deploy the WordPress application + in the Murano environment. + - #. Send a request to create an OpenStack environment. + #. Send a request to create a session for the OpenStack environment. + #. Send a request to create MySQL. + #. Send a request to create the Linux-based Apache service. + #. Send a request to create WordPress. + #. Request to deploy a session. + #. Check the environment status. + #. Check the deployment status. + #. Check ports availability. + #. Check the WordPress path. + #. Send a request to delete the OpenStack environment. + * - **Murano environment with the Linux Apache service deployment** + - The test verifies that the Murano service can create and deploy the + Linux Apache service. + - #. Verify the Linux image with Murano agent is installed in Glance. + #. Send a request to create an OpenStack environment. + #. Send a request to create a session for the OpenStack environment. + #. Send a request to create the Linux-based Apache service. + #. Request to deploy the session. + #. Check the environment status. + #. Check the deployment status. + #. Send a request to delete the OpenStack environment. diff --git a/userdocs/fuel-user-guide/verify-environment/murano-test-prepare.rst b/userdocs/fuel-user-guide/verify-environment/murano-test-prepare.rst new file mode 100644 index 000000000..0707b7832 --- /dev/null +++ b/userdocs/fuel-user-guide/verify-environment/murano-test-prepare.rst @@ -0,0 +1,52 @@ + +.. _murano-test-prepare: + +Preparing the OpenStack Application Catalog for testing +------------------------------------------------------- + +Fuel runs the platform tests in the tenant you have previously +specified in the :menuselection:`Settings --> OpenStack Settings`. +By default, Fuel selects the *admin* tenant. + +You must download and prepare a corresponding image to test Murano. +For example, for Linux-based services deployment testing, +add a Linux based image to Murano. + +To prepare the OpenStack Application Catalog for testing, +add a Linux-based image to Murano. You can download the `pre-built +Murano image +`_ +or build your own as described in `Murano documentation +`_. + +.. note:: + The base operating system of the Murano image does not have to + match the base operating system of the OpenStack environment. + +**Prepare the OpenStack Application Catalog for testing:** + +#. Download or build a Murano image for testing. + +#. Upload the image to the `admin` tenant + in the OpenStack Image Service (Glance). + +#. Open the :guilabel:`Murano` tab. + +#. Navigate to the :guilabel:`Manage` submenu. + +#. Click :guilabel:`Images`. + +#. Click :guilabel:`Mark Image`. + + The Image registration window displays. + +#. Select the Linux image with the Murano Agent. + +#. In the :guilabel:`Title` field, set the title for this image. + +#. Select the :guilabel:`Generic Linux` type. + +#. Click :guilabel:`Mark`. + + Proceed with testing the OpenStack Application Catalog. + diff --git a/userdocs/fuel-user-guide/verify-environment/run-health-checks.rst b/userdocs/fuel-user-guide/verify-environment/run-health-checks.rst new file mode 100644 index 000000000..08cf31388 --- /dev/null +++ b/userdocs/fuel-user-guide/verify-environment/run-health-checks.rst @@ -0,0 +1,26 @@ +.. _run-health-checks: + +Run a health check +------------------ + +We recommend that you run all health tests immediately after you +deploy your OpenStack environment, so you can promptly address any +issues with your environment configuration. + +Each test contains information on its estimated and actual duration. +Information about test processing time is based on the tests +conducted in our lab. Therefore, actual time for +the test to complete may vary for different environments. + +After a test is complete, the results appear in the +:guilabel:`Status` column. If a test fails, Fuel displays an +error message. To assist in troubleshooting, the test +scenario is displayed under the failure message and the failed step is +highlighted. + +**To run a health check:** + +#. In the Fuel web UI, click the :guilabel:`Health Check` tab. +#. Select the tests that you want to run. +#. Click :guilabel:`Run Tests`. + diff --git a/userdocs/fuel-user-guide/verify-environment/sahara-test-details.rst b/userdocs/fuel-user-guide/verify-environment/sahara-test-details.rst new file mode 100644 index 000000000..41e5d2958 --- /dev/null +++ b/userdocs/fuel-user-guide/verify-environment/sahara-test-details.rst @@ -0,0 +1,161 @@ + +.. _sahara-test-details: + +About the Hadoop cluster service test +------------------------------------- + +The Hadoop cluster service test verifies that Sahara can launch +a Hadoop cluster using the Vanilla plugin. + +The following table describes the details of the Hadoop cluster tests. + +.. list-table:: **Sahara platform tests** + :widths: 10 10 20 + :header-rows: 1 + + * - Name + - Description + - Scenario + * - **Test that Sahara can launch a Hadoop cluster using the Vanilla + plugin.** + - The test verifies successful launch of the Hadoop cluster. + - #. Log in to the OpenStack dashboard. + #. Register an image: + + #. Select :menuselection:`Project --> Data Processing --> Image + Registry`. + #. Click :guilabel:`Register Image`. + #. In the :guilabel:`Image` field, select an image. + #. Specify the ``User Name`` value for the selected OS. + #. Set the following values: + + * ``Plugin=vanilla`` + * ``Version=2.6.0`` + + #. Click :guilabel:`Add plugin tags`. + #. Click :guilabel:`Done`. + + * - + - + - #. Create a master node group template: + + #. Select :menuselection:`Project --> Data Processing --> Node + Group Templates`. + #. Click :guilabel:`Create Template`. + #. In the :guilabel:`Create Node Group template` dialog, set the + following values: + + * ``Plugin name=Vanilla Apache Hadoop`` + * ``Hadoop version=2.6.0`` + + #. Click `Create` to proceed. + #. In the second `Create Node Group template` dialog, set the + following values: + + * ``Template Name=vanilla2-master`` + * ``OpenStack Flavor=m1.small`` + * ``Floating IP pool=(external network)`` + + #. In the :guilabel:`Process` section, select: + + * ``namenode`` + * ``secondarynamenode`` + * ``resourcemanager`` + * ``historyserver`` + * ``oozie`` + + #. Click `Create`. + + * - + - + - #. Create a worker node group template: + + #. Select :menuselection: `Project --> Data Processing --> + Node Group Templates`. + + #. Click :guilabel:`Create Template`. + #. In the :guilabel:`Create Node Group template` dialog, + set the following values: + + * ``Plugin name=Vanilla Apache Hadoop`` + * ``Hadoop version=2.6.0`` + + #. Click `Create` to proceed. + #. In the second `Create Node Group template` dialog, set + the following values: + + * ``Template Name=vanilla2-worker`` + * ``OpenStack Flavor=m1.small`` + * ``Floating IP pool=(external network)`` + + #. In the :guilabel:`Process` section, select: + + * ``datanode`` + * ``nodemanager`` + + #. Click :guilabel:`Create`. + + * - + - + - #. Create a cluster template: + + #. Select :menuselection:`Project --> Data Processing --> + Cluster Templates`. + #. Click :guilabel:`Create Template`. + #. In the :guilabel:`Create Cluster Template` dialog, set the + following values: + + * ``Plugin name=Vanilla Apache Hadoop`` + * ``Hadoop version=2.6.0`` + + #. Click :guilabel:`Create`. + #. In the second :guilabel:`Create Cluster Template` dialog, set the + following values: + + * In the :guilabel:`Details` tab, specify + ``Template Name=vanilla2-template``. + + * In the :guilabel:`Node Groups` tab, specify ``vanilla2-master`` + and ``vanilla2-worker``. + + * In the :guilabel:`HDFS Parameters` tab, specify + ``dfs.replication=1``. + + #. Click :guilabel:`Create`. + + * - + - + - #. Launch the cluster: + + #. Select :guilabel:`Project --> Data Processing --> Clusters`. + #. Click :guilabel:`Launch Cluster`. + #. In the :guilabel:`Launch Cluster` dialog, set the following + values: + + * ``Plugin name=Vanilla Apache Hadoop`` + * ``Hadoop version=2.6.0`` + + #. Click `Create` to proceed. + #. In the second `Launch Cluster` dialog, set + :guilabel:``Cluster Name=vanilla2-cluster``. + #. Click :guilabel:`Create`. + #. Wait until the cluster has the ``Active`` status. + * - + - + - #. Delete the cluster: + + #. In the :guilabel:`Clusters` page, select the ``vanilla2-cluster`` + cluster. + #. Click :menuselection:`Delete Cluster`. + + #. Delete the templates: + + #. Select :menuselection:`Project --> Data Processing --> + Cluster Templates`. + #. Select the `vanilla2-template` template. + #. Click :guilabel:`Delete Templates`. + #. Select :guilabel:`Project --> Data Processing --> Node Group + Templates`. + #. Select `vanilla2-master` and `vanilla2-worker` templates. + #. Click :guilabel:`Delete Templates`. + diff --git a/userdocs/fuel-user-guide/verify-environment/sahara-test-prepare.rst b/userdocs/fuel-user-guide/verify-environment/sahara-test-prepare.rst new file mode 100644 index 000000000..4dfc092ff --- /dev/null +++ b/userdocs/fuel-user-guide/verify-environment/sahara-test-prepare.rst @@ -0,0 +1,61 @@ + +.. _sahara-test-prepare: + +Preparing the Hadoop cluster service for testing +------------------------------------------------ + +You can run the platform tests to verify that the Hadoop cluster (Sahara) +functions correctly. +To run the tests, Sahara must be deployed and configured. + +You run the tests in the tenant you specified in the `OpenStack Settings` tab +during the OpenStack installation. By default, the `admin` tenant is used for +the tests. + +You must have at least 4096 MB RAM available in the tenant +for Sahara platform tests. Otherwise, some tests may fail. + +.. note:: + Sahara uses auto-security groups for opening required ports for each + plugin. For more information, see the corresponding plugin documentation. + +**To prepare Hadoop cluster for testing** + +#. Download the `image with Hadoop for Sahara + `_ + +#. If you use VMware vSphere as a hypervisor for your OpenStack environment, + convert the `qcow2` image format to `vmdk`: + + .. code-block: console + + qemu-img convert -O vmdk .qcow2 .vmdk + +#. Register the image with Sahara: + + #. Upload the image into Glance into the `admin` tenant. + + #. Name the image `sahara`. + + #. In Horizon, navigate to :menuselection:`Projects --> Data Processing`. + + #. Switch to the `admin` tenant. + + #. Select :guilabel:`Image Registry`. + + #. Click :guilabel:`Register Image`. + + The `Image registration` dialog appears. + + #. Select the image you have just uploaded. + + #. Set username to ``ubuntu``. + + #. Select the tags: ``plugin=vanilla`` and ``version=``. + + #. Click :guilabel:`Add plugin tags`. + + #. Click :guilabel:`Done`. + +#. Proceed with testing the Hadoop cluster. + diff --git a/userdocs/fuel-user-guide/verify-environment/troubleshoot-health-checks.rst b/userdocs/fuel-user-guide/verify-environment/troubleshoot-health-checks.rst new file mode 100644 index 000000000..04c033958 --- /dev/null +++ b/userdocs/fuel-user-guide/verify-environment/troubleshoot-health-checks.rst @@ -0,0 +1,44 @@ +.. _troubleshoot-health-checks: + +Resolve a problem +----------------- + +If a test fails, there are several ways to investigate the problem. You can +search for the information about the problem in the logs of each OpenStack +component, as well as in the test logs. + +**To resolve a health check issue:** + +#. Verify that all OpenStack services are up and running. + + * In the Fuel web UI: + + #. Click :guilabel:`Health Check`. + #. Run the Sanity tests. + + * In the Fuel CLI: + + #. View the list of services: + + :: + + nova-manage service list + +#. If any of the services have the *XXX* status, restart these + services: + + :: + + service openstack- restart + +#. Analyze error messages in :guilabel:`Dashboard`, :guilabel:`Networks`, + and other tabs, if any. + + For example, a test may fail for the following reasons: + + * A quota has been exceeded + * Network configuration is incorrect + * A general lack of resources, such as memory or disk space. + +#. Analyze the log files. +