Fuel Installation Guide

version 8.0

Fuel v8.0
Installation Guide

Contents
Preface

Intended Audience

Documentation History

Introduction to Fuel Installation

Introduction to Fuel

Overview of the installation process

Planning your environment

System requirements

Hardware requirements

Fuel Master node hardware requirements

Fuel Slave nodes hardware recommendations

Network requirements

Fuel Master Node network requirements

Storage requirements

Additional components

Prerequisites for the OpenStack bare-metal service

Bare Metal service limitations

10

Sample hardware configuration for Fuel Slave nodes

11

Controller nodes

12

Compute nodes

12

Storage nodes

13

Install Fuel

14

Before you install Fuel

14

Download the ISO image

15

Prepare an installation media

15

Create a DVD drive

15

Create a USB drive with the Fuel ISO on a UNIX system

16

Install the Fuel Master node

17

Set up Fuel

17

Change the Admin (PXE) network interface

19

Configure a network interface for the Fuel web UI

21

2016, Mirantis Inc.

Page i

Fuel v8.0
Installation Guide

Log in to the Fuel Master node

21

Log in to the Fuel Master node with multiple NICs

23

Boot the Fuel Slave nodes

23

Boot workflow of a Fuel Slave node

24

Configure a bootstrap image

24

Overview of the Fuel bootstrap builder

25

The fuel-bootstrap container format

26

View available bootstraps

27

Select a bootstrap image

28

Build a bootstrap image with an additional package

29

Install a custom kernel

32

Install the latest kernel

32

Install an old kernel

33

Inject custom SSL certificates

36

Inject a driver from .deb packages

36

Enable advanced debugging

40

Troubleshoot custom bootstrap building

41

Fuel Plugins

45

Fuel plugins overview

45

Prerequisites

46

Install a Fuel plugin

46

View Fuel plugins

47

Uninstall a plugin

47

Install Fuel on VMware vSphere

49

VMware vSphere prerequisites

49

Configure ESXi host networking

49

Upload the Fuel ISO to the VMware vSphere datastore

50

Configure networks

50

Configure a network for Fuel Admin (PXE) traffic

50

Create a vCenter Port Group network

50

Create the Fuel Master node virtual machine

51

Mount the Fuel ISO

51

2016, Mirantis Inc.

Page ii

Fuel v8.0
Installation Guide

Install the Fuel Master node on VMware vSphere

52

Boot the Fuel Master node

52

Verify the Fuel Master node operation

52

Upgrade Fuel

53

Upgrade the Fuel Master node

54

Set up a local repository

56

About the fuel-createmirror script

57

Apply patches

57

Patch the Fuel Master node

58

Patch an Ubuntu slave node

58

Apply Puppet changes on a slave node

58

Verify a patch on the Fuel Master node

59

Verify a patch on a Fuel slave node

59

Roll back the Fuel Master node

60

Roll back an Ubuntu slave node

60

Pre-installation checklists
Hardware checklist
Index

2016, Mirantis Inc.

62
62
63

Page iii

Fuel v8.0
Installation Guide

Preface

Preface
This documentation provides information on how to use Fuel to deploy OpenStack environments. The
information is for reference purposes and is subject to change.

Intended Audience
This documentation is intended for OpenStack administrators and developers; it assumes that you have
experience with network and cloud concepts.

Documentation History
The following table lists the released revisions of this documentation:
Revision Date
February, 2016

2016, Mirantis Inc.

Description
8.0 GA

Page 1

Fuel v8.0
Installation Guide

Introduction to Fuel

Introduction to Fuel Installation

This section provides an overview of the Fuel installation process. You can install Fuel on a server with an
Internet connection or on a server that is isolated from the Internet for security reasons. Depending on your
choice, the workflow differs.
This section includes the following topics:
Introduction to Fuel
Overview of the installation process
Planning your environment

Introduction to Fuel
Fuel is an open-source software application that simplifies the deployment of highly available OpenStack
environments, as well as enables you to manage your OpenStack environments after deployment.
Fuel provides a web user interface (WUI), as well as a command-line user interface (CLI) and RESTful API for
provisioning, configuration, and management of OpenStack environments. A link to the Horizon OpenStack
Dashboard appears in the Fuel web UI after you deploy an OpenStack environment.
Using Fuel you can:
Deploy multiple highly-available OpenStack environments on virtual or bare metal hardware.
Configure and verify network configurations.
Test interoperability between the OpenStack components.
Easily scale your OpenStack environment by adding and removing nodes.
Fuel architecture includes:
Fuel Master node
A server with the installed Fuel application that performs initial configuration, provisioning, and PXE booting
of the Fuel Slave nodes, as well as assigning the IP addresses to the Fuel Slave nodes.
Fuel Slave node
In the Fuel project terminology, a generic term that describes a server that is provisioned by the Fuel Master
node. A Fuel Slave node can be a controller, compute, or storage node, among others. These terms are
interchangeable with the OpenStack terminology.

Seealso
Fuel Architecture

Overview of the installation process

2016, Mirantis Inc.

Page 2

Fuel v8.0
Installation Guide

Planning your environment

Deployment of an OpenStack environment requires extensive planning. To ensure a successful deployment,

review and understand the following requirements and sequence of tasks that you must complete.
1. Plan your OpenStack environment according to the official OpenStack guidelines and Planning your
environment.
2. Verify that your environment meets the recommendations in System requirements.
3. Verify your hardware using the Hardware checklist.
4. Determine whether the server on which you plan to install the Fuel Master node is connected to the
Internet.
If the server does not have an Internet connection, then you must configure a local repository. For
more information, see: Set up a local repository.
5. If you plan to install Fuel on VMware vSphere, verify that your environment meets the VMware vSphere
prerequisites
6. Download and install Fuel as described in Install Fuel or if you are installing on VMware vSphere in Install
Fuel on VMware vSphere.
7. Install the Fuel plug-ins, if needed. See: Plug-ins.

Planning your environment

Before you install Fuel and OpenStack, determine what type of configuration addresses your business needs. You
must understand how OpenStack will integrate and communicate with existing components in your IT
infrastructure, as well as calculate resources required to process estimated workloads.
If you are testing Fuel and OpenStack in a lab environment, you can skip the planning and deploy the default
configuration. However, for a production environment, you must decide on the following:
Network topology and IP address management plan
Storage
Number, type, and flavor of compute, controller, storage, and other nodes
Monitoring facilities
Additional components: Sahara and Murano
Fuel plug-ins
This guide explains what OpenStack configurations you can deploy using Fuel, as well as briefly describes
guidelines and examples on how to plan resources for your environment. However, we recommend that you read
OpenStack Architecture Design Guide, so you can better estimate your network, storage, and compute
requirements.

Seealso
System requirements

System requirements
2016, Mirantis Inc.

Page 3

Fuel v8.0
Installation Guide

Hardware requirements

This section describes how to configure hardware nodes to accommodate your OpenStack workloads. Since there
are many possible use cases for an OpenStack environment, the number and configurations of your servers will
also vary. While this section provides clear hardware requirements for the Fuel Master node, it can only provide
guidelines on how to configure the Fuel Slave nodes. For reference, a sample hardware configuration of a
medium-sized OpenStack environment is described at the end of this section.
This section includes the following topics:
Hardware requirements
Network requirements
Storage requirements
Additional components
Sample hardware architecture

Hardware requirements
Planning hardware requirements for an OpenStack environment is a complex task that requires analysis of the
applications that you plan to run in your cloud, as well as understanding how your cloud will expand over time.
Therefore, the hardware requirements for Fuel Slave nodes will differ for each use case. However, hardware
requirements for Fuel Master node are identical for all deployments.

Seealso
Fuel Master node hardware requirements
Fuel Slave nodes hardware recommendations

Fuel Master node hardware requirements

When planning hardware for the Fuel Master node, verify that your hardware meets the following minimum
requirements:
For a production environment:
Quad-core CPU
4 GB RAM
10 Gigabit network port
128 GB SAS Disk
IPMI access through an independent management network
For a testing environment:
Dual-core CPU
2 GB RAM
2016, Mirantis Inc.

Page 4

Fuel v8.0
Installation Guide

Fuel Slave nodes hardware recommendations

1 Gigabit network port

50 GB disk
Physical console access

Fuel Slave nodes hardware recommendations

Determining the appropriate hardware for the slave nodes depends on the node type, the workloads that you
plan to run on the nodes, and whether you combine different OpenStack components on one node or run them
separately. Typically, you need a two-socket server with the CPU, memory, and disk space that meet your project
requirements. Read the OpenStack Architecture Design Guide for recommendations on how to plan an OpenStack
deployment.
General guidelines for the Fuel Slave nodes:
Controller nodes
Use at least three controller nodes for high availability. High availability is recommended for all
production environments. However, you can start with a single controller node for testing purposes and
add more nodes later. The controller nodes must form a quorum. Therefore, for all deployments, the
total number of controller nodes must be odd. Further resource scaling depends on your use case and
requires extensive assessment of your environment and business needs.
Compute nodes
The number and hardware configuration of the compute nodes depend on the following:
Number of virtual machines
Applications that you plan to run on these virtual machines
Types of workloads
Storage nodes
The number and capacity of the storage nodes highly depend on the type of the storage, redundancy,
and workloads that you run on the compute nodes. Therefore, the storage configuration for every
deployment will vary significantly.

Seealso
OpenStack Architecture Design Guide
OpenStack Operations Guide
Sample hardware configuration for Fuel Slave nodes

Network requirements
Your OpenStack environment must have an efficient, scalable, and manageable network infrastructure that
addresses your immediate business needs and future growth. All nodes must communicate with each other

2016, Mirantis Inc.

Page 5

Fuel v8.0
Installation Guide

Fuel Slave nodes hardware recommendations

through allocated networks. Network configuration of your Fuel Slave nodes depends significantly on the
network topology that you select.
Fuel can deploy the following network topologies:
Nova-network
Nova-network is a simple network manager that provides layer 3 network virtualization. Use
nova-network only if you use VMware vCenter as a hypervisor. To configure nova-network, you must
have at least 1 NIC on each Fuel Slave node. Capacity and number of network interfaces depends on
the workloads that you plan to run in your environment and requires extensive planning that is out of
scope for this document.

Note
Since the introduction of Neutron, nova-network development efforts have been gradually
reduced and may be deprecated in the future OpenStack releases. Neutron is recommended in
all new deployments.

If you select nova-network, you can configure the following using Fuel:
Nova-network FlatDHCP Manager
Nova-network FlatDHCP Manager is the simplest network configuration that Fuel can create.
FlatDHCP Manager ensures that each virtual machine instance is connected to the network bridge
on the compute node. FlatDHCP Manager also provides a DHCP server (dnsmasq) that allocates IP
addresses from the subnetwork assigned by a network administrator to virtual machine instances.
You must configure switch ports as tagged (trunk) to use this network configuration.
Nova-network VLAN Manager
Nova-network VLAN Manager enables you to isolate traffic that flows in one tenant from the
traffic that flows inside other tenants by tagging IP frames. VLAN Manager creates a network
bridge, a VLAN, and a subnetwork for each tenant. Use this option if you plan to have multiple
tenants in your environment. Configure switch ports as tagged.
Neutron
Neutron is a flexible network manager that enables you to create complex network configurations.
Neutron provides both level 2 and 3 network virtualization, as well as IP address management (IPAM).
In addition, Neutron has multiple open-source and enterprise-class plugins that enable interoperability
with such networking technologies as virtual switches and software defined networking (SDN).
If you select Neutron, you can configure the following using Fuel:
Neutron with VLAN segmentation
Similar to nova-network VLAN Manager, in Neutron's VLAN segmentation topology a VLAN is
assigned to each tenant. IP subnets and ranges in different tenants can overlap. This is the
default networking option in Fuel. The disadvantage of this option is that you must configure
your networking equipment, as well as provide the total number of tenants, before configuring
the network.

2016, Mirantis Inc.

Page 6

Fuel v8.0
Installation Guide

Fuel Slave nodes hardware recommendations

If you select Neutron with VLAN segmentation, you must have at least 3 network interfaces (NICs).
Neutron with VLAN segmentation examples:
3 NICs

4 NICs

eth0

Untagged port for Administrative

network

Port for Administrative network

eth1 (br-eth1)

Port for the following networks:

Port for the following networks:

eth2 (br-eth2)

eth3 (br-eth3)

Public/Floating

Public/Floating

Management

Management

Storage
Port for Private network. The number
of VLANs depends on the number of
tenant networks with a continuous
range.

Port for Private network with defined

VLAN ID range

N/A

Port for Storage network

Neutron with tunneling segmentation

You can choose between VXLAN and GRE segmentation, with VXLAN being a default and
preferred option. In both VXLAN and GRE segmentations, tenant traffic is isolated by
encapsulation the traffic in tunnels. Both VXLAN and GRE segmentation is more flexible in terms
of the number of tenants (supports up to 65534 tenants). Network hardware configuration is
significantly simpler compared to the VLAN segmentation and does not need to be synchronized
with your L2 switch configuration. Both VXLAN and GRE support subnet overlapping in different
tenants. However, the disadvantage of using GRE segmentation is that GRE encapsulation
decreases the network speed between the instances, as well as increases the CPU usage on the
compute and controller nodes.

Note
To use VXLAN segmentation, your network hardware must support VXLAN segmentation.

You can configure GRE segmentation using CLI. For more information, see: Fuel CLI Reference.
Neutron with GRE segmentation examples:

eth0

2016, Mirantis Inc.

2 NICs

3 NICs

4 NICs

Untagged port for

Administrative network

Untagged port for

Administrative network

Untagged port for

Administrative network

Page 7

Fuel v8.0
Installation Guide

eth1
(br-eth1)

eth2
(br-eth2)
eth3
(br-eth3)

Fuel Master Node network requirements

Port for the following

networks:

Port for the following

networks:

Public/Floating

Public/Floating

Management

Management

Port for Management

network

Storage
N/A

Port for Storage network

Port for Public/ Floating

network

N/A

N/A

Port for Storage network

Routing recommendations:
Public network: use the default routing through the router.
Management network: use management network to access your management infrastructure (L3
connectivity, if necessary).
Administrative network or only Fuel Master node: must have the Internet access through a
dedicated NIC.
Storage and Private networks (VLANs): isolate from other networks.

Fuel Master Node network requirements

To deploy the Fuel Slave nodes on which you will run your Controller, Compute, Storage or other nodes, the Fuel
Master node must have access to the Internet.
When you deploy the Fuel Slave nodes, the Fuel Master node connects to the preconfigured repositories through
the Internet and installs the selected operating system and the OpenStack packages on the nodes.
For security reasons, you may not want to connect the Fuel Master node to the Internet. In this case, set up a
local repository with the required installation packages and configure these repositories on the Fuel Master node.

Seealso
Set up a local repository

Storage requirements
When planning storage for your OpenStack environment, understand the difference between the two types of
storage that OpenStack uses: persistent and ephemeral.
The nova-compute service manages ephemeral storage that is used as temporary storage for the operating
system of virtual machine instances. When you delete an instance, nova-compute deletes the ephemeral storage
as well. If you do not select any additional storage options, the virtual machine volumes will be stored on the

2016, Mirantis Inc.

Page 8

Fuel v8.0
Installation Guide

Additional components

local disks of the compute nodes, in the virtual storage partition. However, if you enable Ceph RBD back end for
ephemeral volumes, nova-compute stores virtual machine volumes in Ceph.
Persistent storage is the storage that exists outside an instance, in contrast to ephemeral storage.
Fuel deploys storage for the following types of persistent data:
Glance, for image data, which can use either Swift or Ceph RBD as a storage back end.
Cinder, for block data, which can use either LVM or Ceph RBD as a storage back end.
Ceph RadosGW, for object storage, with Ceph RBD as storage back end.

Note
Fuel plugins may provide additional storage options. For more information, see the OpenStack Driverlog
for the Fuel project.

Seealso
Storage Decisions

Additional components
If you plan to install additional OpenStack programs, see the system requirements for additional components:
Prerequisites for the OpenStack bare-metal service

Prerequisites for the OpenStack bare-metal service

Before you deploy an OpenStack environment, you must verify that your environment meets the following
network, hardware, and software prerequisites required to succesfully deploy and use the OpenStack Bare Metal
service.
Network prerequisites:
Configure a flat network that you will use for the nodes on which you run ironic. This network will appear
as baremetal in the Fuel web UI.
Prepare the nodes on which you plan to deploy ironic by configuring the following:
A separate network interface for the baremetal network.
You must assign a separate network interface or a VLAN for the baremetal network on the controller
node. If you need to configure this network interface only on some nodes, such as nodes with
ironic and controller roles, use network templates.

2016, Mirantis Inc.

Page 9

Fuel v8.0
Installation Guide

Bare Metal service limitations

Access to the IPMI network

Since Ironic provides out-of-band management through Intelligent Platform Management Interface
(IPMI), the nodes on which you deploy Ironic must have access to the IPMI network with bare-metal
servers that you will use for provisioning.
Verify that the network interfaces of the physical servers that connect to the IPMI network have either static
IP addresses or, if you use DHCP, the DNS service is enabled in the IPMI network and the physical servers
have stable FQDN host names.
Hardware prerequisites:
Follow the general guidelines for hardware prerequisites described in the System Prerequisites section in the Fuel
Installation Guide.
Fuel includes special drivers for Ironic and the default bootstrap images that Fuel uploads to Glance when you
create an OpenStack environment. If you plan to use these default configurations, the bootstrap images are based
on the image Fuel uses to provision the OpenStack nodes. However, if you plan to use different drivers and
bootstrap images, you must verify that the bootstrap image contains drivers that support your hardware.
Software prerequisites:
Each Ironic driver has requirements for the images that you will use to provision instances on physical machines.
If you use default Fuel drivers, see Image requirements in the Fuel User Guide.

Seealso
Bare Metal service limitations
Using networking templates in Fuel User Guide

Bare Metal service limitations

When you deploy your environment using Fuel with Ironic, the OpenStack environment has the following
limitations:
Limitation for an OpenStack environment with Ironic
Category
Network
Storage

Description
Neutron with VLAN segmentation is the only supported networking
option.
Ironic does not support attaching or booting from the volumes stored in
Cinder.
Ironic requires a swift-compatible object storage. You can use Swift or
RADOS Gateway.

2016, Mirantis Inc.

Page 10

Fuel v8.0
Installation Guide

Security

Virtualization platform
Fuel plug-ins

Management

Sample hardware configuration for Fuel Slave nodes

No tenant-level network separation is supported for physical machines

on which you deploy instances. All physical machines are visible to all
tenants and to each other on the physical network level.
Neutron security groups do not apply to instances deployed on physical
machines.
VMware vCenter as a hypervisor is not supported.
Ironic supports all Fuel plug-ins as long as their requirements do not interfere
with ironic limitations. For example, if a plug-in requires you to configure any
other networking option but Neutron with VLAN segmentation, you cannot
use this plug-in with ironic.
Auto-discovery is not supported.
Ironic cannot automatically discover the physical machines that you will
use to create instances. Therefore, you must have description of the
server hardware available including CPU, RAM, disks, MAC addresses,
and so on to manually discover them. You must also have information
required to configure power and BIOS settings, such as IPMI address or
FQDN, as well as the IPMI user name and password with administrator
privileges for IPMI.
Horizon is partially supported.
Although you can launch an instance on a physical machine using
Horizon, you must perform all other operations with physical nodes
through APIs or CLI. Many operations that are typically supported for
virtual machines, such as pausing and resuming, are not supported for
physical machines. However, they are still present in the Horizon UI.
Only admin can manage operations with Ironic.
Only an OpenStack user with the admin role can operate the Ironic
service.

Sample hardware configuration for Fuel Slave nodes

The example provided in this section is a general-purpose medium-size hardware configuration that you can use
for a variety of OpenStack installations and later moderately scale to accommodate growing requirements of your
environment.

Note
This example is not a best practice document of how to design an OpenStack environment. The purpose
of the example is to help OpenStack administrators to understand how to plan an installation and
demonstrate how an OpenStack environment may look.

2016, Mirantis Inc.

Page 11

Fuel v8.0
Installation Guide

Controller nodes

The sample OpenStack environment includes:

Number of servers

12 The servers include:

1 Fuel Master node
3 Controller nodes
3 Storage nodes
5 Compute nodes
Neutron, using VLAN or GRE topology

Network
Storage

Ceph as back end for Cinder Glance and Nova

(ephemeral storage)

Additional Components

No additional components. If you want to install

Ceilometer with the MongoDB database, you must add
three more servers.

Controller nodes
In this example, we use Ceph as a back end for ephemeral storage. Therefore, in addition to the basic OpenStack
components and a MySQL database, controller nodes require sufficient resources to run Ceph monitors.
Each controller node must include:
CPU
RAM

2 CPUs with at least six physical cores each

For testing: 2 GB
For production:
24 GB (minimum)

Network

Storage

64 GB for deployments of 1000 VMs or more

For testing: 2 x 1 Gbit/s NICs
For production: 2 x 10 Gbit/s NICs
Hardware RAID 1 with at least 1 TB formatted capacity for the host host
operating system disk
Larger disks may be warranted depending on the expected database and log
storage requirements.

Compute nodes
Your virtual machines are hosted on the compute nodes; therefore, you must allocate enough resources to run
these virtual machines.
Each compute node must include:
CPU

2016, Mirantis Inc.

Dual-socket CPU with a minimum of 4 cores per socket

Page 12

Fuel v8.0
Installation Guide

Storage nodes

RAM

64 GB

Storage

Hardware RAID 1 controller with at least 500 GB capacity for the host
operating system disk

Network

For testing: 2 x 1 Gbit/s NICs

For production: 2 x 10 Gbit/s NICs

Storage nodes
We recommend that you separate Ceph nodes for scalability and robustness. The hardware estimate provided
below is based on the requirement of 0.5 cores per Ceph-OSD CPU and 1 GB of RAM per 1 TB of Ceph-OSD space.
You can configure all Ceph storage and journal hard disks in JBOD (Just a Bunch of Disks) mode on the RAID
controller or plug them directly to the available SATA or SAS ports on the mainboard.
Each storage node must include:
CPU

Single-socket CPU with at least 4 physical cores

RAM

24 GB

Storage

RAID 1 controller with at least 500 GB capacity for the host

operating system disk
For production installations, set the Ceph object replication
factor to 3 or greater.

Network

For testing: 2 x 1 Gbit/s NICs

For production: 2 x 10 Gbit/s NICs

Storage

18 TB for Ceph storage (6 x 3 TB)

1-2 x 64 GB SSDs or more, for the Ceph journal

2016, Mirantis Inc.

Page 13

Fuel v8.0
Installation Guide

Before you install Fuel

Install Fuel
You can install Fuel on bare-metal or virtual hardware. For information about specific virtual machine and
network configurations on VMware vSphere, see: Install Fuel on VMware vSphere.
This section includes the following topics:
Before you install Fuel
Download the ISO image
Prepare an installation media
Install the Fuel Master node
Set up Fuel
Log in to the Fuel Master node
Log in to the Fuel Master node with multiple NICs
Boot the Fuel Slave nodes
Configure a bootstrap image

Before you install Fuel

Before you install Fuel, verify that you have completed the following tasks:
1. Read and complete the tasks described in the following sections:
Overview of the installation process
System requirements
1. If you use bare-metal hardware, set up and connect all hardware.
2. If you use virtual hardware, configure all required virtual machines, network, and storage parameters.
3. Select a workflow:
If you install Fuel on a server with an Internet connection, follow this workflow:

If you install Fuel on a server without an Internet connection, you must configure a local repository and
modify the default Fuel repositories, so that Fuel installs the operating system packages from the local
repositories. Therefore, follow this workflow:
2016, Mirantis Inc.

Page 14

Fuel v8.0
Installation Guide

Download the ISO image

Download the ISO image

The Fuel ISO image includes Fuel software components, as well as the latest release of OpenStack which is
required to create your OpenStack environment. Therefore, if you use Fuel, you do not need to download any
additional OpenStack components.
However, the Fuel ISO does not include the operating system packages. The Fuel Master node dynamically
downloads the packages from the configured software repository.
To download the ISO image:
1. Go to the Fuel project page.
2. Download the ISO to your computer.
3. Proceed to Prepare an installation media.

Prepare an installation media

After downloading the Fuel ISO image, you must prepare the installation media by mounting the ISO or burning a
DVD/USB drive.

Create a DVD drive

You can create a DVD with the Fuel ISO to install Fuel on a virtual or bare-metal hardware.
To create a DVD drive:
1. Select from the following options:
For a remote installation, use a remote control utility to mount the ISO image directly to the server's
virtual DVD drive. For example:
IPMItool
HP Integrated Lights Out (iLO)
Dell iDRAC
For a bare-metal installation, burn the ISO image to a DVD drive using any standard software. For
example:
Linux:
2016, Mirantis Inc.

Page 15

Fuel v8.0
Installation Guide

Create a USB drive with the Fuel ISO on a UNIX

system

Xfburn
Brasero
Mac OS X:
Disk Utility (a commonly pre-installed application)
Burn
Windows:
ImgBurn
InfraRecorder
2. Proceed to the Fuel Master node installation.

Create a USB drive with the Fuel ISO on a UNIX system

After downloading the Fuel ISO image, you can use a USB flash drive to install Fuel on your machine.

Note
Write the Fuel ISO image to the USB drive itself and not to one of its partitions, if any. For example, if you
have a USB /dev/sdc with the /dev/sdc1 and /dev/sdc2 partititions, write the ISO to /dev/sdc.

To create a USB drive on a UNIX system:

1. Plug in a USB drive to your machine.
2. Run the following command:
# dd if=/path-to-your-ISO of=/path-to-your-USB
Example:
# dd if=/home/user/fuel-isos/fuel-7.0.iso of=/dev/sdc

Warning
This operation wipes all the data you have on the USB drive and places a bootable Fuel ISO on it.

3. Proceed to Install the Fuel Master node.

2016, Mirantis Inc.

Page 16

Fuel v8.0
Installation Guide

Install the Fuel Master node

Install the Fuel Master node

Before you install the Fuel Master node, complete the steps described in Before you install Fuel, Download the ISO
image, and Preparing an installation media.
To install the Fuel Master node:
1. Insert or mount through IPMI (or using any other remote control utility supported by your hardware) the
media with the Fuel ISO on the server that will be your Fuel Master node.
2. Verify that the Fuel installation media is the first device in the boot order.
3. Power on the server. The Welcome to Fuel Installer screen appears.
4. Select the installation media. If necessary, modify the boot settings by pressing the Tab key to display the
loader command line. Using this command line, configure the IP address, default gateway, and DNS server
settings of the Fuel Master node.
5. Proceed to Configure network parameters.

Note
You can install the Fuel Master node on VMware vSphere. For more information, see: Before you install
Fuel on VMware vSphere.

Set up Fuel
During installation, Fuel prompts you to access the Fuel setup screen where you can modify the default network
and authentication parameters.

Typically, you want to modify network settings to meet the requirements of your existing network infrastructure.
Also, you must change the default Fuel administrator password. Although you can change some of the network
interface settings after you install the Fuel Master node, we recommend that you finalize network configuration
before you install the Fuel Master node.

2016, Mirantis Inc.

Page 17

Fuel v8.0
Installation Guide

Install the Fuel Master node

Warning
Do not modify settings of the Admin (PXE) network after you deploy the Fuel Master node, because Fuel
will lose the ability to PXE boot and manage OpentStack environments.

If you are installing Fuel for testing purposes, you can keep the default settings and proceed to Install the Fuel
Master node.
To set up Fuel:
1. Configure the following settings as required:
1. Change the Fuel administrator password.

For security purposes, we strongly recommend

that you change the Fuel administrator
password during installation.

2. Modify the network interface settings.

By default, Fuel assigns the following network

parameters to the Admin (PXE) network (eth0):
Subnetwork: 10.20.0.2/24
Gateway: 10.20.0.1
Modify these settings according to the
requirements of your existing network
infrastructure.

3. Configure the Admin (PXE) network and a DHCP

pool for the Fuel Slave nodes.

By default, Fuel configures the Admin (PXE)

network on eth0 and configures the following
DHP pool settings:
DHCP pool start: 10.20.0.3
DHCP pool end: 10.20.0.254
DHCP gateway: 10.20.0.2
Modify these settings as needed.

4. Configure DNS and hostname.

2016, Mirantis Inc.

Configure the DNS and hostname settings, if

needed. If your Fuel Master node is not
connected to the Internet, leave the External
DNS field blank.

Page 18

Fuel v8.0
Installation Guide

5. Configure the bootstrap image that Fuel will use

to discover the Fuel Slave nodes through PXE.

6. Configure the network time protocol.

7. Change the root password.

8. Configure network settings using shell.

Change the Admin (PXE) network interface

Fuel ISO includes the CentOS bootstrap image

that Fuel uses to discover the Fuel Slave nodes.
Although CentOS is the default and preferred
option, it may not include drivers for your
hardware, therefore, you may want to use the
Ubuntu bootstrap image instead.
Some organizations may configure the Fuel
Master node in a network protected by a
firewall, so that the Fuel Master node may not
have an access to the Internet. In this case, you
can specify a repository located in the
accessible network, HTTP or HTTPS, by adding
proxy parameters in the Ubuntu repository
field. To configure the Ubuntu repository mirror
on a local host, use the
fuel-createmirror script shipped with the
Fuel ISO.
For more information, see: Set up a local
repository.
To avoid issues with the time settings
inconsistency on the Fuel Master node and
other servers in your IT environment, verify that
the Fuel Master node uses correct NTP settings.
For security reasons, change the default root
password. Fuel will apply this password to all
new OpenStack nodes. Existing OpenStack
nodes will continue to use the old password.
You can configure all settings available on the
Fuel Setup screen using shell. Particularly, use
shell to apply complex network configurations.

2. Proceed to Install the Fuel Master node.

Seealso
Configure a network interface for the Fuel web UI
Change the Admin (PXE) network interface

Change the Admin (PXE) network interface

By default, Fuel assigns eth0 as a network interface for the Admin (PXE) network. If you want to use the default
network settings, skip this section.

2016, Mirantis Inc.

Page 19

Fuel v8.0
Installation Guide

Change the Admin (PXE) network interface

However, some environments may require you to configure other network interfaces for the Admin (PXE)
network. If you plan to use a network interface that is differnt from the default setting, change it before you
install the Fuel Master node.

Warning
Do not change the network interface assigned for the Admin (PXE) network after you install the Fuel
Master node.

To change the Admin (PXE) network interface:

1. In the Fuel Setup screen, select Network Setup.
2. Select eth0.
3. Change Enable interface to No.
4. Click Apply.
Fuel disables eth0.
5. Select a network interface that you want to use for Admin (PXE) network traffic.
For example: eth1.
6. Change Enable interface to Yes.
7. Configure network parameters for eth1.
Default network parameters are:
IP address: 10.20.0.2
Netmask: 255.255.255.0
Gateway: 10.20.0.1
8. Click Apply.
Fuel will now use eth1 as a network interface for the Admin (PXE) network.
9. In Menu, select PXE Setup.
10. Set the DHCP pool range and gateway.
11. Verify your configuration by clicking Check.
12. Proceed to Log in to the Fuel Master node.

Seealso
Configure a network interface for the Fuel web UI

2016, Mirantis Inc.

Page 20

Fuel v8.0
Installation Guide

Configure a network interface for the Fuel web UI

Configure a network interface for the Fuel web UI

You can configure a specific network interface through which users will access the Fuel web UI.
To configure a network interface for the Fuel web UI:
1. In the Fuel Setup screen, select Network Setup.
2. Select an unassigned network interface.
3. Change Enable interface to Yes.
4. Enable DHCP.
5. Verify that the IP address, netmask, and gateway fields are empty.
6. Click Apply.
Fuel now uses the selected interface for the Fuel web UI.
7. Proceed to Log in to the Fuel Master node.

Seealso
Log in to the Fuel Master node with multiple NICs

Log in to the Fuel Master node

When Fuel completes the installation of the Fuel Master node, the Fuel Master node boots automatically and the
Welcome to the Fuel server message displays. The message contains Fuel web UI and Fuel command-line interface
default login credentials.

Warning
Remove the installation media before booting the system. You may damage or delete the entire
environment by booting the installation media once again accidentally. This is especially important if you
set the boot order so that the USB or DVD drive boots before the hard disk.

Log in to the Fuel Master node for further configuration using one of the following options:
Log in to the Fuel web UI.
Log in to the Fuel CLI.
You can perform most of the operations in both Fuel web UI and Fuel CLI. However, for your convenience, we
recommend that you use the Fuel web UI for initial configuration.
To log in to the Fuel web UI:

2016, Mirantis Inc.

Page 21

Fuel v8.0
Installation Guide

Configure a network interface for the Fuel web UI

1. In a web browser, type the IP address and port number that you have assigned for the Fuel web UI in Set up
Fuel.
Fuel prompts you for the login credentials.
2. In a web browser, enter the Fuel UI login and password that you have set for the Fuel web UI in Set up Fuel.
If you use the default network settings, use the following values:
IP address: https://10.20.0.2:8443/
Fuel UI login: admin
Fuel UI password: admin

Note
The IP address must be reachable from the machine on which you open the Fuel web UI URL.

Warning
For security reasons, change the default credentials for the administrator account.

The Fuel web UI initial screen displays.

3. Proceed to Boot the Fuel Slave nodes.
To log in to the Fuel CLI:
1. In the Fuel Master node console, type the root login and password that you have assigned in Set up Fuel.
If you use the default settings, type the following login credentials:
Login: root
Password: r00tme
You can change the password using the passwd command after you log in.

Warning
For security reasons, change the default credentials for the root account.

2. Alternatively, connect to the Fuel Master node using SSH.

3. Proceed to Boot the Fuel Slave nodes.

2016, Mirantis Inc.

Page 22

Fuel v8.0
Installation Guide

Log in to the Fuel Master node with multiple NICs

Seealso
Log in to the Fuel Master node with multiple NICs

Log in to the Fuel Master node with multiple NICs

If the server on which the Fuel Master node is installed has more than one network interface card (NIC), you can
access the Fuel web UI with a particular NIC.
To access the Fuel web UI with a particular NIC:
1. Connect the NIC to the appropriate switch.
2. On the Fuel Master node, set an IP address for the NIC.
3. Use the IP address that you assigned
https://IP_YOU_ASSIGN:8443/

to

log

in

to

the

Fuel

web

UI.

For

example:

Note
The tasks above do not change the default administrator network settings. You can access the Fuel web
UI using the URL displayed on the Fuel boot screen.

Seealso
Log in to the Fuel Master node

Boot the Fuel Slave nodes

Before you boot the Fuel Slave nodes, verify that you have completed the following tasks:
1. Install the Fuel Master node.
2. If you plan using RAID arrays, configure you RAID-attached devices first.
3. Configure the network:
If you use bare-metal servers, verify that the Fuel Slave nodes are physically connected to the same
network as the Fuel Master node.

2016, Mirantis Inc.

Page 23

Fuel v8.0
Installation Guide

Boot workflow of a Fuel Slave node

If you use virtual servers, verify that the Fuel Slave nodes are bridged to the same network as the Fuel
Master node. The Fuel Master node and the Fuel Slave nodes must be in the same L2 network
segment.
To boot the Fuel Slave nodes:
1. Power on a Fuel Slave node.
2. Boot the Fuel Slave node through PXE using one of the following options:
Modify the boot order in BIOS to PXE boot.
Press the appropriate key to initiate a PXE boot.

Warning
If the Fuel Slave node has several network interfaces, enable the PXE boot on the interface that is
on the same network as Admin (PXE) network on the Fuel Master node.

3. Repeat the procedure for all the Fuel Slave nodes you will use for your OpenStack environment.

Boot workflow of a Fuel Slave node

The boot workflow of a Fuel Slave node does not require any user interaction. For general understanding of the
processes that take place in the system when the Fuel Slave node is booting, get acquainted with the boot
procedure:
1. The Fuel Slave node sends out a DHCP discovery request and gets the response from the Fuel Master node
that runs the DHCP server.
2. On receiving the response, the Fuel Slave node fetches the PXELINUX bootloader and the bootstrap image
from the Fuel Master node's TFTP server, and boots into it.
3. On loading the image, the Fuel Slave node reports readiness and configuration to the Fuel Master node.
The number of discovered Fuel Slave nodes appears in the Fuel web UI. When all nodes boot, you can create an
OpenStack environment.

Seealso
Create a new OpenStack environment

Configure a bootstrap image

You can build a custom Ubuntu bootstrap image with the Fuel bootstrap builder that Fuel Master will use to boot
Fuel Slave nodes.

2016, Mirantis Inc.

Page 24

Fuel v8.0
Installation Guide

Overview of the Fuel bootstrap builder

You can include additional packages, custom drivers, and even change the default Ubuntu kernel to be deployed
on Fuel Slave nodes.
This section includes the following topics:
Overview of the Fuel bootstrap builder
The fuel-bootstrap container format
View available bootstraps
Select a bootstrap
Build a bootstrap image with an additional package
Install a custom kernel
Inject custom SSL certificates
Inject a driver (from .deb packages)
Enable advanced debugging
Troubleshoot custom bootstrap building

Overview of the Fuel bootstrap builder

The bootstrap generator creates bootstrap images for the Fuel Master node that Fuel will use to boot the Fuel
Slave nodes. The bootstrap generator uses default configurations, however, you can modify these settings.
You can customize a Fuel bootstrap image using one of the following options:
Set additional packages for the installation.
Copy custom files into the root bootstrap.
Run a user script at the bootstrap file system during the image creation.
You can configure Fuel bootstrap images using the fuel-bootstrap command:
usage: fuel-bootstrap [--version] [-v] [--log-file LOG_FILE] [-q] [-h]
[--debug]

Optional arguments
Option

Description

--version

Shows a program's version number and exits.

-v, --verbose

Increases a verbosity of output. Can be repeated.

--log-fileLOG_FILE

Specify a file to log output. Disabled by default.

-q, --quiet

Suppress output except for warnings and errors.

-h, --help

Shows this help message and exits.

2016, Mirantis Inc.

Page 25

Fuel v8.0
Installation Guide

The fuel-bootstrap container format

Shows tracebacks on errors.

--debug

Commands to operate with a bootstrap image

Command

Description

activate

Activates the specified bootstrap image.

build

Builds a new bootstrap image with the specified parameters.

delete

Deletes the specified bootstrap image from the system.

help

Print the detailed help information for the corresponding command.

import

Imports an already created bootstrap image to the system.

list

Lists all available bootstrap images.

The fuel-bootstrap container format

To simplify bootstrap sharing and delivery, pack all files required for the bootstrap image in a tar.gz archive.
You can also create and archive manually without using the fuel-bootstrap script.
The bootstrap archive must include:
metadata.yaml - a .yaml file that describes the configuration
initrd.img - an initial RAM file system
vmlinuz - a kernel image

Warning
You cannot modify file names. This limitation is planned to be removed in future releases.

Optionally, you can add extra files:

root.squashfs - a root file system
Mandatory data fields for metadata.yaml are:
extend_kopts : 'key=value net.ifnames=1 debug ignore_loglevel'
# kernel command line opts will be extended with Fuel default opts.
# But, its also possible to re-write default params - w\o any
# guarantee of work.
uuid: 244782c1-7343-43f7-9ee3-8989c252eb2e
# Uuid for identify bootstrap.
Generate UUID

2016, Mirantis Inc.

Page 26

Fuel v8.0
Installation Guide

View available bootstraps

In the case of the manually built bootstrap you can generate UUID with the following command:
python -c "import uuid; print str(uuid.uuid4())"

To connect (discover) and work correctly, fuel-bootstrap requires runtime system to have installed and
properly
configured
packages.
The
list
of
packages
is
specified
in
the
/etc/fuel-bootstrap-cli/fuel_bootstrap_cli.yaml file.

View available bootstraps

You can view bootstrap images available in your system.
1. Each bootstrap image has a unique ID which identifies it:
$ fuel-bootstrap

list

System response:

+--------------------------------------+--------------------------------------+-------| uuid
| label
| status
+--------------------------------------+--------------------------------------+-------| 2b7fe334-4ef7-4a9d-8fcb-e0d7cc009d0c | 2b7fe334-4ef7-4a9d-8fcb-e0d7cc009d0c | active
| centos
| deprecated
|
+--------------------------------------+--------------------------------------+-------2. To check, which exactly bootstrap image is currently loaded on a discovered node:
# fuel nodes
System response:

id | status
| name
| cluster | ip
| mac
| roles | p
---|----------|------------------|---------|------------|-------------------|-------|-1 | discover | Untitled (29:bb) | None
| 10.109.0.3 | 64:26:37:0b:29:bb |
|
3. Connect to a node by SSH and check the file:
ssh 10.109.0.3 cat /etc/nailgun-agent/config.yaml

System response:

2016, Mirantis Inc.

Page 27

Fuel v8.0
Installation Guide

Select a bootstrap image

{runtime_uuid: 2b7fe334-4ef7-4a9d-8fcb-e0d7cc009d0c}
4. You can use Fuel web UI as well:
Go to Nodes tab of your environment.
Locate the node and click on gear button in front of the node name.
Expand the System tab and find runtimeuuid record.
As you can see, Fuel loaded the discovered node with the bootstrap image marked as Active in the bootstrap
list.

Select a bootstrap image

You can select a bootstrap image from the list of available bootstraps and activate it. The discovered nodes will
be loaded with a new bootstrap after reboot.
To switch between bootstrap images:
1. Print the list of available bootstrap images:
# fuel-bootstrap list
System response

+--------------------------------------+--------------------------------------+-------| uuid
| label
| status
+--------------------------------------+--------------------------------------+-------| a778efad-88ca-41fe-b592-f02101c11d22 | bs1
|
| 244782c1-7343-43f7-9ee3-8989c252eb2e | bs2
| active
| 2b7fe334-4ef7-4a9d-8fcb-e0d7cc009d0c | 2b7fe334-4ef7-4a9d-8fcb-e0d7cc009d0c |
| centos
| deprecated
|
+--------------------------------------+--------------------------------------+-------2. Activate a new bootstrap image:
# fuel-bootstrap activate a778efad-88ca-41fe-b592-f02101c11d22
3. Reboot the affected node:
# fuel nodes
System response

+-------------------------------------------------------------------------------------|id | status
| name
| cluster | ip
| mac
| roles |
2016, Mirantis Inc.

Page 28

Fuel v8.0
Installation Guide

Build a bootstrap image with an additional package

|---|----------|------------------|---------|------------|-------------------|-------||1 | discover | Untitled (29:bb) | None

| 10.109.0.3 | 64:26:37:0b:29:bb |
|
+--------------------------------------------------------------------------------------

# ssh 10.109.0.3 reboot

Build a bootstrap image with an additional package

You can install any custom package from the default repository or the connected external repository through the
fuel-bootstrap builder script.
Example 1: Installation of the ``strace`` package from the default repository
1. Build the bootstrap:
$ fuel-bootstrap build --package 'strace' --label 'bootstrap_with_strace' \
--output-dir ~/example1/
System response:

...Building process...
Building initramfs
Building squashfs
...
Bootstrap image a778efad-88ca-41fe-b592-f02101c11d22 has been built: /root/example1/a77
2. After the build process is completed, you can import and activate the new bootstrap image:

$ fuel-bootstrap import ~/example1/a778efad-88ca-41fe-b592-f02101c11d22.tar.gz --activa

3. Verify that the bootsrtap image has been activated:
$ fuel-bootstrap list |grep active
System response:
| a778efad-88ca-41fe-b592-f02101c11d22 | bootstrap_with_strace

| active |

4. Reboot the discovered node:

$ ssh 10.109.0.3 reboot

2016, Mirantis Inc.

Page 29

Fuel v8.0
Installation Guide

Build a bootstrap image with an additional package

5. Verify that the new bootstrap image is loaded on the discovered node:
1. Verify that the runtime_uuid value of the activated bootstrap image has been updated in the
nailgun-agent configuration file:
# cat /etc/nailgun-agent/config.yaml
System response:
{runtime_uuid: a778efad-88ca-41fe-b592-f02101c11d22}
2. Verify that the new package has been installed:
# dpkg -l |grep strace
System response:
ii

strace

4.8-1ubuntu5

amd64 A system call tracer

Example 2: Installation of the ``nginx`` package using a custom repository

1. Add the nginx repository to the fuel_bootstrap_cli.yaml file:
1. Open the fuel_bootstrap_cli.yaml file for editing:
$ vim /etc/fuel-bootstrap-cli/fuel_bootstrap_cli.yaml
2. Add the following text:
...
repos:
- name: ubuntu-0
...
- name: ubuntu-1
...
- name: custom_user_repo
priority: 1001
section: "nginx"
suite: trusty
type: deb
uri: "http://nginx.org/packages/ubuntu"
...

2016, Mirantis Inc.

Page 30

Fuel v8.0
Installation Guide

Build a bootstrap image with an additional package

Warning
The first repository must point to the upstream mirror.

Warning
Use priorities higher than 1000 to force the installation of an old version of a package, when other
repositories have newer versions of the same package or a newer version of the package is already
installed on the system. You can use the force installation in case of a regression caused by the
newer version of a package. Find more information about apt-pinning in Debian Manuals.

2. Build the bootstrap image:

$ fuel-bootstrap --verbose --debug build --label 'with_nginx_repo_package' --package ng

System response:
...
Bootstrap image e295a410-2605-4ddf-a967-c3d638d901bc has been built:
...
Bootstrap image e295a410-2605-4ddf-a967-c3d638d901bc has been activated.
...
3. After the build process is completed, reboot the discovered node.
4. Verify that the new package has been installed:
# dpkg -l |grep nginx
System response:
ii

nginx

1.8.1-1~trusty

amd64

high performance web server

5. View the status of the packageL

# apt-cache show nginx
System response:
2016, Mirantis Inc.

Page 31

Fuel v8.0
Installation Guide

Install a custom kernel

Package: nginx
Status: install ok installed
...
6. Verify that the runtime_uuid value of the activated bootstrap image has been updated in the
nailgun-agent configuration file:
# cat /etc/nailgun-agent/config.yaml
System response:
{runtime_uuid: e295a410-2605-4ddf-a967-c3d638d901bc}

Install a custom kernel

You can install a custom kernel in a bootstrap image. For example, you can install the latest Ubuntu kernel or an
older version of the kernel intended to fix regressions.

Warning
Non-standard kernels, which were not verified with the Fuel packages, can brake your system.

Install the latest kernel

To install the latest lts-trusty kernel, you do not need to make any customization. Simply run the bootstrap
builder with the default parameters and the latest lts-trusty kernel available in the repositories will be
fetched.
To install the latest kernel:
1. Install the kernel different from lts-trusty
2. Open and edit configuration file adding the new repository:
$ vim /etc/fuel-bootstrap-cli/fuel_bootstrap_cli.yaml

...
- name: wily1
priority: 1001
section: "main restricted universe multiverse"
suite: wily
2016, Mirantis Inc.

Page 32

Fuel v8.0
Installation Guide

Install an old kernel

type: deb
uri: "http://cz.archive.ubuntu.com/ubuntu/"
- name: wily2
priority: 1001
section: "main restricted universe multiverse"
suite: wily-updates
type: deb
uri: "http://cz.archive.ubuntu.com/ubuntu/"
...
3. Build and activate a bootstrap image specifying a kernel flavor:

$ fuel-bootstrap --verbose --debug build --label 'with_wily_kernel' --activate --kernel

4. Reboot the discovered node:
$ ssh 10.109.0.3
5. Verify if the node applied the kernel succesfully:
1. View infomation about the installed kernel image:
# dpkg -l | grep wily
System response:
ii

linux-image-generic-lts-wily

4.2.0.27.21

amd64

Generic Linux kernel im

2. View infomation about the current kernel:

# uname

-a

System response:

Linux bootstrap 4.2.0-27-generic #32~14.04.1-Ubuntu SMP Fri Jan 22 15:32:26 UTC 201

Install an old kernel

For code stability, security, or other reasons, you may not want to install the latest kernel as described above.

2016, Mirantis Inc.

Page 33

Fuel v8.0
Installation Guide

Install an old kernel

Note
Due to a specific logic of apt-getupgrade\dist-upgrade system, an old kernel cannot be
installed as easily as the latest one.

To install an old version of kernel:

1. Verify the version of lts-vivid meta-package:
apt-cache show linux-image-generic-lts-vivid | grep -i Depends

Example of system response:

Depends: linux-image-3.19.0-47-generic, linux-image-extra-3.19.0-47-generic, linux-firm

2. Prepare a bash script with the kernel version you want to install. For example:
$ cat /root/user_script.sh
System response:
#!/bin/bash
echo "START user-script"
apt-get remove -y linux-image-generic-lts* linux-image-*
apt-get purge -y linux-image-generic-lts* linux-image-*
rm -f /boot/vmlinuz*
rm -f /boot/initrd*
apt-get install -y linux-image-3.19.0-25-generic linux-image-extra-3.19.0-25-generic
echo "END user-script"
This bash script installs the linux-image-3.19.0-25-generic kernel.
3. Build and activate a bootstrap image including the custom script you created before:

$ fuel-bootstrap build --verbose --debug --activate --label 'old_kernel' --script /root

System response:

2016, Mirantis Inc.

Page 34

Fuel v8.0
Installation Guide

Install an old kernel

...
Copy user-script /root/user_script.sh into chroot:/tmp/tmplGugKE.fuel-agent-image
Make user-script /tmp/tmplGugKE.fuel-agent-image/user_script.sh executable
Trying to execute command: chroot /tmp/tmplGugKE.fuel-agent-image /bin/bash -c /user_sc
...
Bootstrap image 244782c1-7343-43f7-9ee3-8989c252eb2e has been built
...
Bootstrap image 244782c1-7343-43f7-9ee3-8989c252eb2e has been activated.
4. Reboot the discovered node:
$ ssh 10.109.0.3
5. Verify if the node applied the kernel succesfully:
1. View infomation about the current kernel:
# uname

-a

System response:

Linux bootstrap 3.19.0-25-generic #26~14.04.1-Ubuntu SMP Fri Jul 24 21:16:20 UTC 20

2. View infomation about the installed kernel image:
# dpkg -l | grep image
System response:
ii
ii

linux-image-3.19.0-25-generic 3.19.0-25.26~14.04.1 amd64 Linux kernel image

linux-image-extra-3.19.0-25-generic 3.19.0-25.26~14.04.1
amd64 Linux kernel

3. Verify that the runtime_uuid value of the activated bootstrap image has been updated in the
nailgun-agent configuration file:
# cat /etc/nailgun-agent/config.yaml
System response:
{runtime_uuid: 244782c1-7343-43f7-9ee3-8989c252eb2e}

2016, Mirantis Inc.

Page 35

Fuel v8.0
Installation Guide

Inject custom SSL certificates

Inject custom SSL certificates

You can inject any customization scripts and files inside a bootstrap using fuel-bootstrap. For example, you
can add custom certificates to access an https repository.
** To inject certificate files:**
1. Add a certificate to the Fuel Master system to provide correct work of debootstrap run on the Fuel Master
node:
$ update-ca-trust force-enable
$ cp cert.crt /etc/pki/ca-trust/source/anchors/
$ update-ca-trust extract
2. Create a directory with the certificate to inject:
$ mkdir -p /root/bootstrap_root/usr/local/share/ca-certificates/
$ cp cert.crt /root/bootstrap_root/usr/local/share/ca-certificates/
3. Build the bootstrap:
$ fuel-bootstrap build --load-cert --extra-dir /root/bootstrap_root/

Inject a driver from .deb packages

When you need to install custom hardware drivers from the official repository, you can inject them into a
bootstrap.
To install a driver provided as a deb package:
Input:
.deb files provided by HW-support
Fetched from: http://bgate.mellanox.com/openstack/mellanox_fuel_plugin/8.0/repositories/ubuntu/
files to be injected to the bootstrap
Fetched from review.
The .deb files:
$ la -lah /root/mlnx_debs/
System response:
-rw-r--r--rw-r--r--rw-r--r--rw-r--r--rw-r--r--

1
1
1
1
1

root
root
root
root
root

2016, Mirantis Inc.

root
root
root
root
root

13M
13M
27K
27K
44K

Jan
Jan
Jan
Jan
Jan

21
21
21
21
31

08:55
08:55
08:55
08:55
16:08

cirros-testvm-mellanox-ib_0.3.2-7_amd64.deb
cirros-testvm-mellanox_0.3.2-ubuntu3_amd64.deb
eswitchd_0.13-1_amd64.deb
eswitchd_1.14-3_amd64.deb
libibverbs1_1.1.8mlnx1-OFED.3.1.1.0.0_amd64.deb

Page 36

Fuel v8.0
Installation Guide

-rw-r--r--rw-r--r--rw-r--r--rw-r--r--rw-r--r--rw-r--r--rw-r--r--rw-r--r--

1
1
1
1
1
1
1
1

Inject custom SSL certificates

root
root
root
root
root
root
root
root

root
root
root
root
root
root
root
root

49K
3.7K
100M
193M
1.9M
68K
14K
18K

Jan
Jan
Jan
Jan
Jan
Jan
Jan
Jan

31
21
21
21
31
31
31
21

16:08
08:55
08:55
08:55
16:08
16:08
16:08
08:55

libmlx4-1_1.0.6mlnx1-OFED.3.1.1.0.0_amd64.deb
mlnx-dnsmasq_2015.1.0-1_all.deb
mlnx-ofed-fuel_2.3-2.0.8_amd64.deb
mlnx-ofed-fuel_3.1-1.5.7_amd64.deb
mlnx-ofed-kernel-dkms_3.1-OFED.3.1.1.0.3.1.g903273
mlnx-ofed-kernel-utils_3.1-OFED.3.1.1.0.3.1.g90327
ofed-scripts_3.1-OFED.3.1.1.0.3_amd64.deb
python-networking-mlnx_2015.1.2-1_amd64.deb

The files to be injected to the bootstrap image:

$ tree /root/mlnx_files//
System response:
|-- mellanox_customize_init.sh
`-- mlnx_bootstrap_root
|-- etc
|
`-- modprobe.d
|
`-- ipoib.conf
`-- usr
`-- bin
`-- init_mlnx.sh

Warning
Injected files and folder should have execute permission

$ find /root/mlnx_files/ -type f -iname *.sh -print | xargs chmod 0755

$ find /root/mlnx_files/ -type d -print | xargs chmod 755
The custom script:
$ cat /root/mlnx/mellanox_customize_init.sh
System response:
#!/bin/bash

2016, Mirantis Inc.

Page 37

Fuel v8.0
Installation Guide

Inject custom SSL certificates

echo "MLNX add init_mlnx.sh into bootstrap /etc/rc.local"

sed -i 's/.*fix-configs.*/$(init_mlnx.sh > \/dev\/null 2>\&1) \& || true\n&/' /etc/rc.local
To push deb packages into the bootstrap, create a new repository on the Fuel Master node and pull the repository
to the builder following the steps below:
1. Prepare a custom repository under nailgun folder:
1. Create a fodler for the repository:
$ mkdir -p /var/www/nailgun/mlnx_repo/ubuntu
2. Copy all *.deb files to the folder:
$ cp /root/mlnx_debs/*.deb /var/www/nailgun/mlnx_repo/ubuntu
3. Run dpkg tool to create repo-metadata:
$ pushd /var/www/nailgun/mlnx_repo/ubuntu/
$ dpkg-scanpackages ./ /dev/null | gzip -9c > Packages.gz
$ popd
4. Create a simple Release stub file:
$ echo -e "Origin: user_custom\nLabel: custom\nSuite: user_custom\nCodename: \
user_custom\nArchitectures: amd64\nComponents: main\nDescription: custom" \
> /var/www/nailgun/mlnx_repo/ubuntu/Release
2. Include the repository to configure the bootstrap builder:
$ vim /etc/fuel-bootstrap-cli/fuel_bootstrap_cli.yaml
System response:
...
repos:
...
- name: custom_mlnx_repo
priority: 1001
section: ""
suite: ./
type: deb
uri: "http://<FUEL_MASTER_IP>:8080/mlnx_repo/ubuntu/"
where FUEL_MASTER_IP is an IP address of the Fuel Master node.

2016, Mirantis Inc.

Page 38

Fuel v8.0
Installation Guide

Inject custom SSL certificates

3. Run the bootstrap builder:

$ fuel-bootstrap --verbose --debug build --package mlnx-ofed-kernel-dkms \
--package mlnx-ofed-kernel-utils --extra-dir \
/root/mlnx/mlnx_bootstrap_root/ --label mlnx-ofed-kernel \
--activate --script /root/mlnx/mellanox_customize_init.sh
System response:

...
Trying to execute command: rsync -rlptDKv /root/mlnx/mlnx_bootstrap_root// /tmp/tmpsJA1
...
Trying to execute command: chroot /tmp/tmpsJA1Yp.fuel-agent-image /bin/bash -c /mellano
....
stdout:MLNX add init_mlnx.sh into bootstrap /etc/rc.local
...
Setting up mlnx-ofed-kernel-dkms (3.1-OFED.3.1.1.0.3.1.g9032737)
...
Loading new mlnx-ofed-kernel-3.1 DKMS files
...
Rsync files from /root/mlnx/mlnx_bootstrap_root/ to: /tmp/tmpIA5Ro8.fuel-agent-image
...
--- Building bootstrap image END (do_mkbootstrap) --...
Bootstrap image 37369fd8-34c0-444d-a4d1-2f266d586442 has been activated
4. Reboot the affected nodes:
$ ssh 10.109.0.3 reboot
5. Check that the driver has been installed succesfully:
1. View the information about the installed packages:
# dpkg -l |grep mlnx
System response:
ii
ii

mlnx-ofed-kernel-dkms 3.1-OFED.3.1.1.0.3.1.g9032737 all DKMS support for mlnxof

mlnx-ofed-kernel-utils 3.1-OFED.3.1.1.0.3.1.g9032737
amd64 Userspace tools t

2. View the information about the installed kernel module:

# modinfo mlx4_core

2016, Mirantis Inc.

Page 39

Fuel v8.0
Installation Guide

Enable advanced debugging

System response:
filename:
version:
license:
description:
author:
...

/lib/modules/3.13.0-76-generic/updates/dkms/mlx4_core.ko
3.1-1.0.3
Dual BSD/GPL
Mellanox ConnectX HCA low-level driver
Roland Dreier

3. View the running process:

# ps xauf |grep init_mlnx.sh
System response:
root

3113

0.0

0.0

9600

1492 pts/0

13:00

0:00 /bin/bash /usr/bin

Enable advanced debugging

If creating a new bootstrap image results in errors, you can analyze your system by enabling the chroot bootstrap
development environment.
This section provides an example of running bootstrap building in the chroot environment.
To enable advanced debugging:

Warning
Use for debug purpose only.

1. Prepare the sleep script:

$ cat /root/sleep.sh
#!/bin/bash
sleep 99h || true
2. Start the build process with the sleep.sh script:
$ fuel-bootstrap --verbose --debug build --extra-dir /root/mlnx/mlnx_bootstrap_root/ \
--label debug --activate --script /root/sleep.sh
System response:
2016, Mirantis Inc.

Page 40

Fuel v8.0
Installation Guide

Troubleshoot custom bootstrap building

...
Copy user-script /root/sleep.sh into chroot:/tmp/tmpdOS3ya.fuel-agent-image
Trying to execute command: chroot /tmp/tmpdOS3ya.fuel-agent-image /bin/bash -c /sleep.s
The process is sleeping and you can jump into chroot

The sleep.sh script delays the start of the building process. Therefore, you can enable the chroot
environment.
3. Enable the chroot environment:
$ chroot /tmp/tmpdOS3ya.fuel-agent-image /bin/bash
4. Fix PATH difference between CentOS and Ubuntu environmnets:
$ export PATH=$PATH:/sbin:/bin
5. You can now make any changes to the bootstrap-dev system.
6. After you apply the required changes, exit the chroot environment.
7. Terminate the sleep process:
$ [root@nailgun ~]# ps xauf |grep sleep
System response:
root
root

23642
23643

0.0
0.0

0.0
0.0

9524
4340

1128 pts/14
360 pts/14

S+
S+

17:54
17:54

0:00
0:00

|
|

\_ /bin/b
\_ sl

$ kill -s INT 23643

After that, the building process will continue as usual.

Troubleshoot custom bootstrap building

Automatic Fuel deployment has failed
Automatic bootstrap image building can fail with one of the following error messages:
"WARNING: Ubuntu bootstrap build has been skipped.
Please build and activate bootstrap manually with CLI command
`fuel-bootstrap build --activate`.

2016, Mirantis Inc.

Page 41

Fuel v8.0
Installation Guide

Troubleshoot custom bootstrap building

While you don't activate any bootstrap - new nodes cannot be discovered
and added to cluster.
For more information please visit
https://docs.mirantis.com/openstack/fuel/fuel-master/"

or
WARNING: Failed to build the bootstrap image, see
/var/log/fuel-bootstrap-image-build.log
for details. Perhaps your Internet connection is broken. Please fix the
problem and run `fuel-bootstrap build --activate`.
While you don't activate any bootstrap - new nodes cannot be discovered
and added to cluster.
For more information please visit
https://docs.mirantis.com/openstack/fuel/fuel-master/"

You typically receive such error messages when software repositories are unavailable.
To resolve the issue:
If the Fuel Master node has an Internet connection, verify network connectivity to the software repositories.
If you use a local repository mirror:
Follow
the
instructions
provided
https://github.com/openstack/fuel-mirror

in

the

fuel-mirror

utility

Additionally, analyze the following log files:

/var/log/fuel-bootstrap-image-build.log
/var/log/puppet/bootstrap_admin_node.log
A node has an old ``cmdline`` or a wrong bootstrap image
fuel-bootstrap has a limitation with UX issue. You can not change a bootstrap image on nodes already
added to an environment (serialized). This issue relates to the current architecture restriction.
The problem may occur under the following conditions:
You have a deprecated CentOS bootstrap image in the active state; or you power on nodes before the
Fuel Master node is completely deployed when ubuntu-bootstrap on the Fuel Master node has not
been activated yet.
You start a node and add it to an OpenStack environment, or you start or reset deployment on an
environment, or any other case that triggers Fuel to store a node and create a cobbler system.
cobbler system report --name default |grep -i Profile

System response:
2016, Mirantis Inc.

Page 42

Fuel v8.0
Installation Guide

Troubleshoot custom bootstrap building

Profile : bootstrap
Fuel (obbler) creates a system with the CentOS bootstrap image.
$ cobbler system report --name node-1
System response:
...
Profile : bootstrap (centos-bootstrap)
...
Then, you change the active bootstrap, which makes astute change the cobbler default profile to
ubuntu-bootstrap:
$ cobbler system report --name default |grep -i Profile
System response:
Profile : ubuntu_bootstrap

But the stored system still use the old bootstrap data.
To enable the new bootstarp image:
1. Remove the node from db, reboot, and re-discover it

Warning
All node data will be destroyed!

# fuel node --node-id 1 --delete-from-db

2. Manually update the cobbler profile:

2016, Mirantis Inc.

Page 43

Fuel v8.0
Installation Guide

Troubleshoot custom bootstrap building

Note
No data will be destroyed.

$ cobbler system edit --name node-1 --profile=ubuntu_bootstrap

$ cobbler system report --name node-1 |grep Profile
System response:
Profile : ubuntu_bootstrap
3. Reboot the node.

2016, Mirantis Inc.

Page 44

Fuel v8.0
Installation Guide

Fuel plugins overview

Fuel Plugins
You can extend Fuel functionality by installing the plugins that companies and individual contributors develop
for Fuel.
This section includes the following topics:
Fuel plugins overview
Prerequisites
Install a Fuel plugin
View Fuel plugins
Uninstall a plugin

Fuel plugins overview

Fuel provides plugins that you can use to extend the functionality of your OpenStack environment and enable
Fuel to work with various third-party components and technologies.
Most of the Fuel plugins are developed by OpenStack community members, as well as by companies who support
OpenStack. The Fuel plugins are distributed free of charge.
Fuel currently has the following plugins:
Networking plugins Fuel plugins such as Firewall-as-a-Service and VPN-as-a-Service, as well as plugins that
enable Fuel to work with enterprise-grade SDN and virtual networking.
Operations management plugins Enable Fuel to work with the third-party monitoring tools such as Zabbix
and Grafana.
Storage plugins Extend Fuel functionality by enabling OpenStack to use enterprise-class storage platforms
as a Cinder backend.
Compute plugins Extend the Fuel compute functionality. For example, the XenServer plugin enables you to
use the XenServer hypervisor as a compute provider.

Note
You must install all Fuel plugins that you plan to use in your OpenStack environment before you deploy
your environment. You will not be able to add plugins after deployment.

Fuel Plugins SDK enables you to develop virtually any plugin that you need to meet your environment
prerequisites.

Seealso
Fuel Plugins catalog
2016, Mirantis Inc.

Page 45

Fuel v8.0
Installation Guide

Prerequisites

Prerequisites
When planning to deploy an environment with Fuel plugins, mind the following recommendations:
No enviroment should be deployed before that point. If you already have the environment you want to
upgrade, read the Upgrade Fuel section first.
Use Fuel 6.1 or later for deployment.
Read additional requirements provided by the selected plugin.

Seealso
Fuel plugins catalog

Install a Fuel plugin

The installation procedure is common for all plugins. For more details about the plugin installation and its
requirements, see the corresponding plugin documentation.
To install a Fuel plugin:
1. Install the Fuel Master node as described in Install the Fuel Master node.
2. Boot the Fuel Master node as described in Log in to the Fuel Master node.
3. Download a plugin from Fuel Plugins atalog.
4. Read a Plugin Guide to learn about prerequisites and limitations.
5. Define variables with values suitable for your environment to be used during the plugin installation process
or replace them in your command line when appropriate.
export FUEL_PLUGIN_FILE=fuel-plugin.rpm
export FUEL_MASTER_NODE=10.20.0.2
6. Copy the plugin to the Fuel Master node.
scp ${FUEL_PLUGIN_FILE} root@:${FUEL_MASTER_NODE}:/tmp
7. Install the plugin by typing:
ssh root@:${FUEL_MASTER_NODE} "fuel plugins --install /tmp/${FUEL_PLUGIN_FILE}"

2016, Mirantis Inc.

Page 46

Fuel v8.0
Installation Guide

View Fuel plugins

8. Create an OpenStack environment as described in Create a new OpenStack environment in the Fuel User
Guide.
9. After completing the Create a new OpenStack environment wizard, click Settings in the Fuel web UI.
10. Enable plugin in the Fuel web UI as described in the plugin documentation.
11. Configure and deploy your environment as described in Configure a new environment in the Fuel User Guide.

Seealso
Fuel plugins CLI
Fuel plugins catalog

View Fuel plugins

You can view the list of installed plugins in the Fuel Web UI, as well as in the Fuel CLI.
To view the list of installed plugins using the Fuel Web UI, click the Plugins button. It is located at the top of the
screen at the Fuel level.
You can find the following information for every plugin:
version
description
homepage
authors
licenses
releases

Seealso
Fuel plugins CLI <fuel-plugins-cli>

Uninstall a plugin
Fuel does not support upgrades for plugins. The old plugin versions may not be compatible with the new version
of Fuel. Therefore, you must uninstall the Fuel plugins before upgrading Fuel.
To uninstall a plugin:
1. Log in to the Fuel Master node CLI.
2016, Mirantis Inc.

Page 47

Fuel v8.0
Installation Guide

View Fuel plugins

2. Create an uninstall.sh script with the following content:

#!/bin/bash
set -eux
echo uninstall > /tmp/myplugin_uninstall
where myplugin is the name of your plugin.
3. Put the uninstall.sh script in your plugin folder.
4. Type:
fuel plugins --remove myplugin

Seealso
Fuel Plugin Wiki

2016, Mirantis Inc.

Page 48

Fuel v8.0
Installation Guide

VMware vSphere prerequisites

Install Fuel on VMware vSphere

This section describes how to configure your VMware vSphere environment to install Fuel.

VMware vSphere prerequisites

Before you install Fuel and use your Mirantis OpenStack environment in intergration with vSphere, you must
configure all components of VMware vSphere.

Note
The vCenter Server supported versions are 5.1, 5.5, and 6.0.

Complete the following steps:

Install ESXi.
Install vCenter.
Configure vCenter.
Create Datacenter.
Create vCenter cluster.
Add ESXi hosts to clusters in vCenter.
For more information, see the VMware vSphere documentation.

Configure ESXi host networking

To integrate Mirantis OpenStack with VMware vCenter, you must configure the VMware ESXi host networking.
To configure ESXi host networking:
1. In VMware vSphere web-client open the ESXi host page.
2. Select Manage > Networking.
3. Click Add network. The Add networking wizard starts.
4. In the Add Networking wizard, select the Virtual Machine Port group.
5. Select the Virtual Machine Port Group option to ensure that the network is created in vSwitch0.

2016, Mirantis Inc.

Page 49

Fuel v8.0
Installation Guide

Upload the Fuel ISO to the VMware vSphere

datastore

6. Create a network called br100.

Note
You must name the network br100. Otherwise, Fuel will not be able to communicate with VMware
vSphere.

7. In the VLAN ID field, type a VLAN Tag.

8. Proceed to Upload the Fuel ISO to the VMware vSphere datastore.

Upload the Fuel ISO to the VMware vSphere datastore

You need to download the Fuel ISO and upload it do a vSphere datastore.
To upload the Fuel ISO to the VMware vSphere datastore:
1. Log into the vSphere web client.
2. Click vCenter.
3. Go to the Datastores and choose your datastore.
4. Go to the Actions menu and select Browse Files.
5. Click the Upload Files icon, browse your filesystem, and select your Mirantis ISO.
6. Proceed to Configure networks.

Configure networks
To enable inter-node communication, you must configure networks on VMware vCenter.

Configure a network for Fuel Admin (PXE) traffic

You must configure a network for the Fuel Admin (PXE) traffic and enable Promiscuous mode.
To configure a network for the Fuel Admin (PXE) traffic:
1. Go to the vCenter screen.
2. Choose Hosts.
3. Select the host on which you want to run the Fuel Master node.
4. Click the Networking button.
5. Click the Add Host Networking icon.

Create a vCenter Port Group network

You must create a Port Group with Promiscuous mode.

2016, Mirantis Inc.

Page 50

Fuel v8.0
Installation Guide

Create the Fuel Master node virtual machine

To create a vCenter Port Group network:

1. Choose a Port Group connection type.
2. Choose a switch.
3. Name your network and set the VLAN number. This is optional and depends on your underlying network
infrastructure.
4. After the network is created, select the network on the network map; then click the Edit Settings icon.
5. Click Security.
6. Verify that the Promiscuous mode is set to Accept.
7. Click "OK".
8. Proceed to Create the Fuel Master node virtual machine.

Create the Fuel Master node virtual machine

You need to create a new virtual machine with a guest operating system to run the Fuel Master node on it.
To create the Fuel Master node virtual machine:
1. On the vCenter screen choose Virtual Machines.
2. Click Create a Virtual Machine.
3. Click Create a new virtual machine.
Do not use templates.
4. Name your new VM and choose the datacenter where the Mirantis ISO is located.
5. Select a compute resource (ESXi host), storage, and compatibility for the VM.
6. Select a guest operating system.
7. Proceed to: Mount the Fuel ISO.

Mount the Fuel ISO

You must mount the Fuel ISO to install the Fuel Master node on the virtual machine.
To mount the Fuel ISO:
1. For the CD/DVD drive, choose Datastore ISO File from the dropdown menu on the right.
2. Navigate through the datastore and choose the ISO you uploaded earlier.
3. Enable the CD/DVD drive by clicking the Connect... checkbox opposite the drive.
4. Go to the VM Options tab and expand the Boot Options submenu.
5. Enable the "Force BIOS setup" item.
6. Click Next.
7. Verify the new Virtual Machine settings and proceed.
8. Proceed to Install the Fuel Master node on VMware vSphere.
2016, Mirantis Inc.

Page 51

Fuel v8.0
Installation Guide

Install the Fuel Master node on VMware vSphere

Install the Fuel Master node on VMware vSphere

You need to install the Fuel Master node on the created virtual machine.
To install the Fuel Master node on VMware vSphere:
1. At the Virtual Machines screen, select the Fuel VM and run it by clicking the Power on icon.
2. Click the Open a virtual machine console icon.
3. When the BIOS appears, use the arrow keys on your keyboard to navigate to the Boot tab. Then move the
highlighted selection to the CD-ROM drive.
4. Using the + button on the keyboard, move the CD-ROM Drive item to the top level.
5. Navigate to the Exit tab, choose Exit Saving Changes, and confirm your decision.
6. Proceed to Boot the Fuel Master node.

Boot the Fuel Master node

1. When the Mirantis ISO boot menu appears, press the Tab key on the keyboard and modify the last kernel
parameter showmenu to yes. Press Enter.
2. Wait for the Fuel Master node installation to complete.
To access the Fuel Web UI, your browser must have an access to the Fuel Master node through the IP gateway
that is connected to the Port Group network that you configured in Configure networks.
Proceed to Verify the Fuel Master node operation.

Verify the Fuel Master node operation

You need to verify that the Fuel Master node operates correctly.
To verify the Fuel Master node operation:
1. Create a new VM on the same ESXi host.
2. Boot the created VM via PXE.
If the boot is successful, the "Total nodes" at the top right of the Fuel Web UI will increase its value after two to
five minutes.
To verify that the Fuel bootstrap node runs on ESXi:
1. Open the node information window in the Fuel Web UI.
2. Verify that the Manufacturer field says VMWARE.

2016, Mirantis Inc.

Page 52

Fuel v8.0
Installation Guide

Install the Fuel Master node on VMware vSphere

Upgrade Fuel
You can upgrade the Fuel Master node to the latest Fuel version.
The following table describes available upgrades for the Fuel software:
Initial Fuel version

Fuel is upgraded to

Upgraded Fuel can manage

5.0

5.1, then to 5.1.1, then to 6.0

2014.1-5.0
2014.1.1-5.0.2
2014.1.1-5.1
2014.1.3-5.1.1
2014.2-6.0

5.0

5.0.1, then to 5.1,

then to 5.1.1
then to 6.0

2014.1-5.0
2014.1.1-5.0.1
2014.1.1-5.0.2
2014.1.1-5.1
2014.1.3-5.1.1
2014.2-6.0

5.0.1

5.1, then to 5.1.1

then to 6.0

2014.1.1-5.0.1
2014.1.1-5.0.2
2014.1.1-5.1
2014.1.3-5.1.1
2014.2-6.0

5.1

5.1.1, then to 6.0

2014.1.1-5.1
2014.1.3-5.1.1
2014.2-6.0

6.0

6.1, then apply all 6.1 updates,

then to 7.0

2014.2.6.0 2014.2.2-6.1 2015.x-7.0

6.1

Apply all 6.1 updates,

then to 7.0

2014.2-6.0
2014.2.2-6.1
2015.x-7.0

7.0

Apply all 7.0 updates,

then to 8.0

2014.2.2-6.1
2015.1.0-7.0
liberty-8.0

This section includes the following topics.

Upgrade the Fuel Master node
Set up a local repository.
Apply patches

2016, Mirantis Inc.

Page 53

Fuel v8.0
Installation Guide

Upgrade the Fuel Master node

Note
Fuel does not support upgrades for plugins. The old plugin versions may not be compatible with the new
version of Fuel. Therefore, you must uninstall the Fuel plugins before upgrading Fuel. See Uninstall a
plugin.

Upgrade the Fuel Master node

If you have a functional Fuel installation, you can upgrade the Fuel software to the latest version without
reinstalling your environments.

Note
Upgrades are not supported for Fuel 4.x or earlier. If you use Fuel 4.x or earlier, you must install new
instance of Fuel and deploy your environments from scratch.

After you upgrade Fuel, you can only deploy new environments of the corresponding Fuel version. Environments
deployed using older versions of Fuel will remain operational.
To upgrade the Fuel Master node:
1. Verify that no installations are in progress in any of your OpenStack environments.
2. Download and install the fuel-octane package using the yuminstall command:
$ yum install fuel-octane
3. Back up the configuration of the Fuel Master node to an archive:
octane fuel-backup --to <path-to-archive> --admin-password <admin-password>
Example:
$ octane fuel-backup --to /tmp/fuel-backup.7.0.tar.gz --admin-password admin
4. Back up package repositories and other binary artifacts from the Fuel Master node:
Example:
$ octane fuel-repo-backup --to /tmp/fuel-repo-backup.7.0.tar.gz

2016, Mirantis Inc.

Page 54

Fuel v8.0
Installation Guide

Upgrade the Fuel Master node

5. Copy the backup files to a secure external location, such as a removable USB drive or network server. If you
copy the files to a network server, use SSH.

Note
When you reinstall the Fuel Master node, all configuration files are deleted. Therefore, if you fail to
back up the Fuel Master node and repository configuration files, you will not be able to manage the
OpenStack environments created by the old version of Fuel.

6. Power off the Fuel Master node.

7. Install the latest version of the Fuel Master node as described in Install Fuel.

Note
The new Fuel Master node must have the same IP address as the original Fuel Master node.
Otherwise, you cannot restore the configuration from the backup.

8. Copy the backup files to the location on the new Fuel Master node.
For example, in the /tmp directory.
9. Log in to the new Fuel Master node.
10. Install the fuel-octane package:
$ yum install fuel-octane
11. Restore the configuration of the original Fuel Master node and the OpenStack environments:
$ octane fuel-restore --from /tmp/fuel-backup.7.0.tar.gz
12. Restore repositories and binary artifacts from the old version:
Example:
$ octane fuel-repo-restore --from /tmp/fuel-repo-backup.7.0.tar.gz

2016, Mirantis Inc.

Page 55

Fuel v8.0
Installation Guide

Set up a local repository

Warning
The Fuel Master node must have at least 2 GB of RAM to decompress the gzip upgrade archive.

When Fuel completes the upgrade, the New Release available message appears in the Releases tab.
13. If you want to use CentOS-based bootstrap, rebuild the bootstrap image:
$ octane update-bootstrap-centos
14. Reboot all nodes that are in the Discover status.

Seealso
Configure a bootstrap image.

Set up a local repository

Fuel downloads the OpenStack and operating system packages from the predefined repositories on the Fuel
Master node. If your Fuel Master node does not have an Internet connection, you must configure a local
repository mirror with the required packages and configure Fuel to use this repository.
You can set up a local repository in the Fuel web UI or through Fuel CLI using the fuel-createmirror script.
To set up a local repository in the Fuel web UI
1. In the Fuel web UI, navigate to the Settings tab and then scroll down to the Repositories section.
2. Change the path under URI.
To set up a local repository with the ``fuel-createmirror`` script
1. Log in to the Fuel Master node CLI.
2. Run the fuel-createmirror script:
If you use the default Fuel root password, type:
fuel-createmirror
If you change the default Fuel root password, type:
fuel-createmirror --password PASSWORD
3. Restart the the docker daemon

2016, Mirantis Inc.

Page 56

Fuel v8.0
Installation Guide

About the fuel-createmirror script

service docker restart

Alternatively (recommended), reboot the Fuel Master node.

About the fuel-createmirror script

The fuel-createmirror is a built-in Fuel script that enables you to modify the Fuel repository sources from
the CLI.
The script supports only RSYNC mirrors. See the the list of official upstream Ubuntu mirrors.
The script uses a Docker container with Ubuntu to support dependencies resolution.
To view help information, type fuel-createmirror-h.
The script supports running behind an HTTP proxy configured to Port 873 (rsync). The following
environment variables can be set either system-wide (via ~/.bashrc), or in the script configuration file:
http_proxy=http://username:password@host:port/
RSYNC_PROXY=username:password@host:port
You can also configure Docker to use the proxy to download the Ubuntu image needed to resolve the
packages dependencies. Add the environment variables to the /etc/sysconfig/docker file, and export them:
http_proxy=http://username:password@host:port/
RSYNC_PROXY=username:password@host:port
export http_proxy RYSNC_PROXY

Apply patches
You can apply only the patches you need one by one or you can apply all accumulated patches in one go.
The documentation for each patch is available in the corresponding release notes.

Note
Maintenance Updates are only available online. Currently there is no option to run these updates from a
local repository.

Check each patch item and proceed with the instructions.

To patch the Fuel Master node:
1. Log in to the Fuel Master node.
If you use a local repository, update it by typing:

2016, Mirantis Inc.

Page 57

Fuel v8.0
Installation Guide

Patch the Fuel Master node

fuel-createmirror -M
2. Run the command specified in the documentation to download and install the patch.
To patch a Fuel Slave node:
1. Run the command specified in the documentation to download and install the patch.
Apply all accumulated changes in one go:
Before starting the update, back up all sensitive data that can be changed during the the whole lifetime of your
environment and the Fuel Master node. We recommend to apply the updates to one node at a time, so that you
can interrupt the update procedure whenever an issue occurs.
If you have configured any custom repositories, Fuel will use fetch the upgrade packages from these repositories.

Note
This set of actions should be applied carefully and with consideration. It is strongly recommended that
you do this on your test staging environment before applying the updates to production.

Patch the Fuel Master node

1. Back up your data with dockerctl backup. This will save the data to /var/backup/fuel/.
2. Run yumupdate.
3. Run dockerctldestroyall.
4. Run dockerctlstartall.
5. Wait for the new containers deployment to finish.

Patch an Ubuntu slave node

1. Run apt-getupdate.
2. Run apt-getupgrade.
3. Apply all the additional configuration options as described in the supporting documentation.
4. Reboot the node.

Apply Puppet changes on a slave node

You may want to apply all changes on a slave node or run a single granular task so that Fuel Puppet changes
take effect.
To run a complete Puppet cycle on a Fuel Slave node:
1. Update fuel-libraryX.X on Fuel Master yumupdate
2016, Mirantis Inc.

Page 58

Fuel v8.0
Installation Guide

Verify a patch on the Fuel Master node

2. Run fuelnode--nodeNODE_ID--deploy
To update Puppet manifests and apply a single task:
1. Update fuel-libraryX.X on Fuel Master yumupdate
2. Run fuelnode--nodenode-XX--taskrsync_core_puppethieraglobalsTASK

Note
The tasks rsync_core_puppet, hiera, and globals are required for processing any Puppet changes.

Verify a patch:

Verify a patch on the Fuel Master node

To verify the packages on the Fuel Master node:
1. Log in to the Fuel Master node CLI.
2. Type:
yum clean expire-cache
yum -y update

Verify a patch on a Fuel slave node

To verify the packages are up-to-date on the Fuel Slave nodes:
1. Log in to the Fuel Master node CLI.
2. Update the list of available packages:
apt-get update
3. Update all packages:
apt-get dist-upgrade
4. Log in to the Fuel Master node GUI:
5. Click Support.
6. Generate and download a diagnostic snapshot by clicking Generate Diagnostic Snapshot.
The Fuel Master node generates ubuntu_installed_debs.txt.
7. Analyze ubuntu_installed_debs.txt to verify the versions of the packages.
Additionally, you can analyze the ubuntu_repo_list.txt file to verify the repositories.

2016, Mirantis Inc.

Page 59

Fuel v8.0
Installation Guide

Roll back the Fuel Master node

Roll back a patch:

Note
The rollback instructions listed here are for advanced administrators. If you are not sure how to plan and
execute the rollbacks, your best option is to contact Mirantis support.

Roll back the Fuel Master node

1. Roll back the packages on the Fuel Master node. Refer to this article as an example.
2. Roll back all the changes to the configuration you made when applying the patching instructions.
3. Run dockerctldestroyall.
4. Run dockerctlstartall.
5. Wait for bootstrap to complete.

Roll back an Ubuntu slave node

You must identify the packages to roll back and where to get their specific versions, install the packages and roll
back the changes to the configuration.
To roll back an Ubuntu slave node:
1. Evacuate all the running resources from the node.
2. Make sure no new workloads are scheduled to the node: Put nova services in maintenance, turn on
Pacemaker maintenance mode.
3. Look up the packages
/var/log/dpkg.log.

you

want

to

roll

back

in

/var/log/apt/history.log

and

4. Figure out where to get the old package version. Run apt-cachepolicy.
5. Figure out if the old package version is available locally.
6. If it is, install these versions using dpkg. Otherwise, check the snapshots of previous repositories on
http://mirror.fuel-infra.org/mos/snapshots and pick the repository that contains the packages you need.
7. Add this repository to the environment configuration.
8. On the Fuel Master node run:
fuel node --node-id <comma_separated_list_of_nodes_you_want_to_update_repo> \
--tasks upload_core_repos
This will propagate the new repos configuration.

2016, Mirantis Inc.

Page 60

Fuel v8.0
Installation Guide

Roll back the Fuel Master node

9. Install the packages with specific versions:

apt-get install <pkg1>=<ver1> <pkg2>=<ver2>
10. Roll back all the changes to the configuration you made when applying the patching instructions.
11. Reboot the node.

2016, Mirantis Inc.

Page 61

Fuel v8.0
Installation Guide

Hardware checklist

Pre-installation checklists
Before you install Fuel, verify that you configured your environment for the installation.
This section includes the following topics:
Hardware checklist

Hardware checklist
Before you install the Fuel Master node, verify that you have configured your hardware correctly. If you install
Fuel on virtual hardware for testing purposes, skip this section.
You must configure all items from the list below before you install Fuel.
Hardware checklist
Item to confirm

Status [tick if done]

The Fuel server has an IPMI or out-of-band management system that you can access.
The Fuel server hardware can boot the Fuel ISO from a DVD, USB flash drive, or IPMI
remote media.
Theserveron which you plan to install the Fuel Master node can access all nodes
through the L2 management network.
The Admin (PXE) network does not have a configured DHCP server. Fuel acts as a DHCP
server for Fuel Slave nodes configured to boot using PXE.
The Spanning Tree Protocol (STP) is disabled on switch ports connected to the node
servers ports or the switch ports are set to the edge/portfast mode. The edge/portfast
mode is the preferred configuration. It allows the ports to forward immediately when
they are linked up, but listens for network loops for 15 seconds.
The switch assigned for the Admin network does not have any tagged VLANs
configured.
The node servers are set to network boot using PXE.
The node servers have hardware virtualization enabled in BIOS.
You have a methodto reboot node servers(remotely or on-site).
The network equipment supports VLANs.
Your network switches support tagged ports. You need tagged ports in order to use the
nova-network VLAN Manager or Neutron with VLAN segmentation.
You have permit rules on TCP ports 22 and 8000 on the firewallfor the Fuel servers IP
address(to access the Fuel server from your PC).

2016, Mirantis Inc.

Page 62

Fuel v8.0
Installation Guide

Index

Index
C
confirm
H
Hardware configuration

2016, Mirantis Inc.

Page 63