docs/release/userguide/userguide.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. http://creativecommons.org/licenses/by/4.0
   3 .. (c) Open Platform for NFV Project, Inc. and its contributors
   4
   5 ========
   6 Abstract
   7 ========
   8
   9 This document contains details about how to use OPNFV Fuel - Fraser
  10 release - after it was deployed. For details on how to deploy check the
  11 installation instructions in the :ref:`fuel_userguide_references` section.
  12
  13 This is an unified documentation for both x86_64 and aarch64
  14 architectures. All information is common for both architectures
  15 except when explicitly stated.
  16
  17
  18
  19 ================
  20 Network Overview
  21 ================
  22
  23 Fuel uses several networks to deploy and administer the cloud:
  24
  25 +------------------+---------------------------------------------------------+
  26 | Network name     | Description                                             |
  27 |                  |                                                         |
  28 +==================+=========================================================+
  29 | **PXE/ADMIN**    | Used for booting the nodes via PXE and/or Salt          |
  30 |                  | control network                                         |
  31 +------------------+---------------------------------------------------------+
  32 | **MCPCONTROL**   | Used to provision the infrastructure VMs (Salt & MaaS)  |
  33 +------------------+---------------------------------------------------------+
  34 | **Mgmt**         | Used for internal communication between                 |
  35 |                  | OpenStack components                                    |
  36 +------------------+---------------------------------------------------------+
  37 | **Internal**     | Used for VM data communication within the               |
  38 |                  | cloud deployment                                        |
  39 +------------------+---------------------------------------------------------+
  40 | **Public**       | Used to provide Virtual IPs for public endpoints        |
  41 |                  | that are used to connect to OpenStack services APIs.    |
  42 |                  | Used by Virtual machines to access the Internet         |
  43 +------------------+---------------------------------------------------------+
  44
  45
  46 These networks - except mcpcontrol - can be linux bridges configured before the deploy on the
  47 Jumpserver. If they don't exists at deploy time, they will be created by the scripts as virsh
  48 networks.
  49
  50 Mcpcontrol exists only on the Jumpserver and needs to be virtual because a DHCP server runs
  51 on this network and associates static host entry IPs for Salt and Maas VMs.
  52
  53
  54
  55 ===================
  56 Accessing the Cloud
  57 ===================
  58
  59 Access to any component of the deployed cloud is done from Jumpserver to user *ubuntu* with
  60 ssh key */var/lib/opnfv/mcp.rsa*. The example below is a connection to Salt master.
  61
  62     .. code-block:: bash
  63
  64         $ ssh -o StrictHostKeyChecking=no -i  /var/lib/opnfv/mcp.rsa  -l ubuntu 10.20.0.2
  65
  66 **Note**: The Salt master IP is not hard set, it is configurable via INSTALLER_IP during deployment
  67
  68 Logging in to cluster nodes is possible from the Jumpserver and from Salt master. On the Salt master
  69 cluster hostnames can be used instead of IP addresses:
  70
  71     .. code-block:: bash
  72
  73         $ sudo -i
  74         $ ssh -i mcp.rsa ubuntu@ctl01
  75
  76 User *ubuntu* has sudo rights.
  77
  78
  79 =============================
  80 Exploring the Cloud with Salt
  81 =============================
  82
  83 To gather information about the cloud, the salt commands can be used. It is based
  84 around a master-minion idea where the salt-master pushes config to the minions to
  85 execute actions.
  86
  87 For example tell salt to execute a ping to 8.8.8.8 on all the nodes.
  88
  89 .. figure:: img/saltstack.png
  90
  91 Complex filters can be done to the target like compound queries or node roles.
  92 For more information about Salt see the :ref:`fuel_userguide_references` section.
  93
  94 Some examples are listed below. Note that these commands are issued from Salt master
  95 as *root* user.
  96
  97
  98 #. View the IPs of all the components
  99
 100     .. code-block:: bash
 101
 102         root@cfg01:~$ salt "*" network.ip_addrs
 103         cfg01.mcp-pike-odl-ha.local:
 104            - 10.20.0.2
 105            - 172.16.10.100
 106         mas01.mcp-pike-odl-ha.local:
 107            - 10.20.0.3
 108            - 172.16.10.3
 109            - 192.168.11.3
 110         .........................
 111
 112
 113 #. View the interfaces of all the components and put the output in a file with yaml format
 114
 115     .. code-block:: bash
 116
 117         root@cfg01:~$ salt "*" network.interfaces --out yaml --output-file interfaces.yaml
 118         root@cfg01:~# cat interfaces.yaml
 119         cfg01.mcp-pike-odl-ha.local:
 120          enp1s0:
 121            hwaddr: 52:54:00:72:77:12
 122            inet:
 123            - address: 10.20.0.2
 124              broadcast: 10.20.0.255
 125              label: enp1s0
 126              netmask: 255.255.255.0
 127            inet6:
 128            - address: fe80::5054:ff:fe72:7712
 129              prefixlen: '64'
 130              scope: link
 131            up: true
 132         .........................
 133
 134
 135 #. View installed packages in MaaS node
 136
 137     .. code-block:: bash
 138
 139         root@cfg01:~# salt "mas*" pkg.list_pkgs
 140         mas01.mcp-pike-odl-ha.local:
 141             ----------
 142             accountsservice:
 143                 0.6.40-2ubuntu11.3
 144             acl:
 145                 2.2.52-3
 146             acpid:
 147                 1:2.0.26-1ubuntu2
 148             adduser:
 149                 3.113+nmu3ubuntu4
 150             anerd:
 151                 1
 152         .........................
 153
 154
 155 #. Execute any linux command on all nodes (list the content of */var/log* in this example)
 156
 157     .. code-block:: bash
 158
 159         root@cfg01:~# salt "*" cmd.run 'ls /var/log'
 160         cfg01.mcp-pike-odl-ha.local:
 161            alternatives.log
 162            apt
 163            auth.log
 164            boot.log
 165            btmp
 166            cloud-init-output.log
 167            cloud-init.log
 168         .........................
 169
 170
 171 #. Execute any linux command on nodes using compound queries filter
 172
 173     .. code-block:: bash
 174
 175         root@cfg01:~# salt -C '* and cfg01*' cmd.run 'ls /var/log'
 176         cfg01.mcp-pike-odl-ha.local:
 177            alternatives.log
 178            apt
 179            auth.log
 180            boot.log
 181            btmp
 182            cloud-init-output.log
 183            cloud-init.log
 184         .........................
 185
 186
 187 #. Execute any linux command on nodes using role filter
 188
 189     .. code-block:: bash
 190
 191         root@cfg01:~# salt -I 'nova:compute' cmd.run 'ls /var/log'
 192         cmp001.mcp-pike-odl-ha.local:
 193            alternatives.log
 194            apache2
 195            apt
 196            auth.log
 197            btmp
 198            ceilometer
 199            cinder
 200            cloud-init-output.log
 201            cloud-init.log
 202         .........................
 203
 204
 205
 206 ===================
 207 Accessing Openstack
 208 ===================
 209
 210 Once the deployment is complete, Openstack CLI is accessible from controller VMs (ctl01..03).
 211 Openstack credentials are at */root/keystonercv3*.
 212
 213     .. code-block:: bash
 214
 215         root@ctl01:~# source keystonercv3
 216         root@ctl01:~# openstack image list
 217         +--------------------------------------+-----------------------------------------------+--------+
 218         | ID                                   | Name                                          | Status |
 219         +======================================+===============================================+========+
 220         | 152930bf-5fd5-49c2-b3a1-cae14973f35f | CirrosImage                                   | active |
 221         | 7b99a779-78e4-45f3-9905-64ae453e3dcb | Ubuntu16.04                                   | active |
 222         +--------------------------------------+-----------------------------------------------+--------+
 223
 224
 225 The OpenStack Dashboard, Horizon, is available at http://<proxy public VIP>
 226 The administrator credentials are *admin*/*opnfv_secret*.
 227
 228 .. figure:: img/horizon_login.png
 229
 230
 231 A full list of IPs/services is available at <proxy public VIP>:8090 for baremetal deploys.
 232
 233 .. figure:: img/salt_services_ip.png
 234
 235 ==============================
 236 Guest Operating System Support
 237 ==============================
 238
 239 There are a number of possibilities regarding the guest operating systems which can be spawned
 240 on the nodes. The current system spawns virtual machines for VCP VMs on the KVM nodes  and VMs
 241 requested by users in OpenStack compute nodes. Currently the system supports the following
 242 UEFI-images for the guests:
 243
 244 +------------------+-------------------+------------------+
 245 | OS name          | x86_64 status     | aarch64 status   |
 246 +==================+===================+==================+
 247 | Ubuntu 17.10     | untested          | Full support     |
 248 +------------------+-------------------+------------------+
 249 | Ubuntu 16.04     | Full support      | Full support     |
 250 +------------------+-------------------+------------------+
 251 | Ubuntu 14.04     | untested          | Full support     |
 252 +------------------+-------------------+------------------+
 253 | Fedora atomic 27 | untested          | Not supported    |
 254 +------------------+-------------------+------------------+
 255 | Fedora cloud 27  | untested          | Not supported    |
 256 +------------------+-------------------+------------------+
 257 | Debian           | untested          | Full support     |
 258 +------------------+-------------------+------------------+
 259 | Centos 7         | untested          | Not supported    |
 260 +------------------+-------------------+------------------+
 261 | Cirros 0.3.5     | Full support      | Full support     |
 262 +------------------+-------------------+------------------+
 263 | Cirros 0.4.0     | Full support      | Full support     |
 264 +------------------+-------------------+------------------+
 265
 266
 267 The above table covers only UEFI image and implies OVMF/AAVMF firmware on the host. An x86 deployment
 268 also supports non-UEFI images, however that choice is up to the underlying hardware and the administrator
 269 to make.
 270
 271 The images for the above operating systems can be found in their respective websites.
 272
 273 ===================
 274 Openstack Endpoints
 275 ===================
 276
 277 For each Openstack service three endpoints are created: admin, internal and public.
 278
 279     .. code-block:: bash
 280
 281         ubuntu@ctl01:~$ openstack endpoint list --service keystone
 282         +----------------------------------+-----------+--------------+--------------+---------+-----------+------------------------------+
 283         | ID                               | Region    | Service Name | Service Type | Enabled | Interface | URL                          |
 284         +----------------------------------+-----------+--------------+--------------+---------+-----------+------------------------------+
 285         | 008fec57922b4e9e8bf02c770039ae77 | RegionOne | keystone     | identity     | True    | internal  | http://172.16.10.26:5000/v3  |
 286         | 1a1f3c3340484bda9ef7e193f50599e6 | RegionOne | keystone     | identity     | True    | admin     | http://172.16.10.26:35357/v3 |
 287         | b0a47d42d0b6491b995d7e6230395de8 | RegionOne | keystone     | identity     | True    | public    | https://10.0.15.2:5000/v3    |
 288         +----------------------------------+-----------+--------------+--------------+---------+-----------+------------------------------+
 289
 290 MCP sets up all Openstack services to talk to each other over unencrypted
 291 connections on the internal management network. All admin/internal endpoints use
 292 plain http, while the public endpoints are https connections terminated via nginx
 293 at the VCP proxy VMs.
 294
 295 To access the public endpoints an SSL certificate has to be provided. For
 296 convenience, the installation script will copy the required certificate into
 297 to the cfg01 node at /etc/ssl/certs/os_cacert.
 298
 299 Copy the certificate from the cfg01 node to the client that will access the https
 300 endpoints and place it under /etc/ssl/certs. The SSL connection will be established
 301 automatically after.
 302
 303     .. code-block:: bash
 304
 305         $ ssh -o StrictHostKeyChecking=no -i  /var/lib/opnfv/mcp.rsa  -l ubuntu 10.20.0.2 \
 306         "cat /etc/ssl/certs/os_cacert" | sudo tee /etc/ssl/certs/os_cacert
 307
 308
 309 =============================
 310 Reclass model viewer tutorial
 311 =============================
 312
 313
 314 In order to get a better understanding on the reclass model Fuel uses, the `reclass-doc
 315 <https://github.com/jirihybek/reclass-doc>`_ can be used to visualise the reclass model.
 316 A simplified installation can be done with the use of a docker ubuntu container. This
 317 approach will avoid installing packages on the host, which might collide with other packages.
 318 After the installation is done, a webbrowser on the host can be used to view the results.
 319
 320 **NOTE**: The host can be any device with Docker package already installed.
 321           The user which runs the docker needs to have root priviledges.
 322
 323
 324 **Instructions**
 325
 326
 327 #. Create a new directory at any location
 328
 329     .. code-block:: bash
 330
 331         $ mkdir -p modeler
 332
 333
 334 #. Place fuel repo in the above directory
 335
 336     .. code-block:: bash
 337
 338         $ cd modeler
 339         $ git clone https://gerrit.opnfv.org/gerrit/fuel && cd fuel
 340
 341
 342 #. Create a container and mount the above host directory
 343
 344     .. code-block:: bash
 345
 346         $ docker run --privileged -it -v <absolute_path>/modeler:/host ubuntu bash
 347
 348
 349 #. Install all the required packages inside the container.
 350
 351     .. code-block:: bash
 352
 353         $ apt-get update
 354         $ apt-get install -y npm nodejs
 355         $ npm install -g reclass-doc
 356         $ cd /host/fuel/mcp/reclass
 357         $ ln -s /usr/bin/nodejs /usr/bin/node
 358         $ reclass-doc --output /host /host/fuel/mcp/reclass
 359
 360
 361 #. View the results from the host by using a browser. The file to open should be now at modeler/index.html
 362
 363    .. figure:: img/reclass_doc.png
 364
 365
 366 .. _fuel_userguide_references:
 367
 368 ==========
 369 References
 370 ==========
 371
 372 1) :ref:`fuel-release-installation-label`
 373 2) `Saltstack Documentation <https://docs.saltstack.com/en/latest/topics>`_
 374 3) `Saltstack Formulas <http://salt-formulas.readthedocs.io/en/latest/>`_