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 - Euphrates
  10 release - after it was deployed. For details on how to deploy check the
  11 installation instructions in the :ref:`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     | Deploy Type       | Description                                             |
  27 |                  |                   |                                                         |
  28 +==================+===================+=========================================================+
  29 | **PXE/ADMIN**    | baremetal only    | Used for booting the nodes via PXE                      |
  30 +------------------+-------------------+---------------------------------------------------------+
  31 | **MCPCONTROL**   | baremetal &       | Used to provision the infrastructure VMs (Salt & MaaS). |
  32 |                  | virtual           | On virtual deploys, it is used for Admin too (on target |
  33 |                  |                   | VMs) leaving the PXE/Admin bridge unused                |
  34 +------------------+-------------------+---------------------------------------------------------+
  35 | **Mgmt**         | baremetal &       | Used for internal communication between                 |
  36 |                  | virtual           | OpenStack components                                    |
  37 +------------------+-------------------+---------------------------------------------------------+
  38 | **Internal**     | baremetal &       | Used for VM data communication within the               |
  39 |                  | virtual           | cloud deployment                                        |
  40 +------------------+-------------------+---------------------------------------------------------+
  41 | **Public**       | baremetal &       | Used to provide Virtual IPs for public endpoints        |
  42 |                  | virtual           | that are used to connect to OpenStack services APIs.    |
  43 |                  |                   | Used by Virtual machines to access the Internet         |
  44 +------------------+-------------------+---------------------------------------------------------+
  45
  46
  47 These networks - except mcpcontrol - can be linux bridges configured before the deploy on the
  48 Jumpserver. If they don't exists at deploy time, they will be created by the scripts as virsh
  49 networks.
  50
  51 Mcpcontrol exists only on the Jumpserver and needs to be virtual because a DHCP server runs
  52 on this network and associates static host entry IPs for Salt and Maas VMs.
  53
  54
  55
  56 ===================
  57 Accessing the Cloud
  58 ===================
  59
  60 Access to any component of the deployed cloud is done from Jumpserver to user *ubuntu* with
  61 ssh key */var/lib/opnfv/mcp.rsa*. The example below is a connection to Salt master.
  62
  63    .. code-block:: bash
  64
  65        $ ssh -o StrictHostKeyChecking=no -i  /var/lib/opnfv/mcp.rsa  -l ubuntu 10.20.0.2
  66
  67 **Note**: The Salt master IP is not hard set, it is configurable via INSTALLER_IP during deployment
  68
  69
  70 The Fuel baremetal deploy has a Virtualized Control Plane (VCP) which means that the controller
  71 services are installed in VMs on the baremetal targets (kvm servers). These VMs can also be
  72 accessed with virsh console: user *opnfv*, password *opnfv_secret*. This method does not apply
  73 to infrastructure VMs (Salt master and MaaS).
  74
  75 The example below is a connection to a controller VM. The connection is made from the baremetal
  76 server kvm01.
  77
  78    .. code-block:: bash
  79
  80        $ ssh -o StrictHostKeyChecking=no -i  /var/lib/opnfv/mcp.rsa  -l ubuntu x.y.z.141
  81        ubuntu@kvm01:~$ virsh console ctl01
  82
  83 User *ubuntu* has sudo rights. User *opnfv* has sudo rights only on aarch64 deploys.
  84
  85
  86 =============================
  87 Exploring the Cloud with Salt
  88 =============================
  89
  90 To gather information about the cloud, the salt commands can be used. It is based
  91 around a master-minion idea where the salt-master pushes config to the minions to
  92 execute actions.
  93
  94 For example tell salt to execute a ping to 8.8.8.8 on all the nodes.
  95
  96 .. figure:: img/saltstack.png
  97
  98 Complex filters can be done to the target like compound queries or node roles.
  99 For more information about Salt see the :ref:`references` section.
 100
 101 Some examples are listed below. Note that these commands are issued from Salt master
 102 with *root* user.
 103
 104
 105 #. View the IPs of all the components
 106
 107    .. code-block:: bash
 108
 109        root@cfg01:~$ salt "*" network.ip_addrs
 110        cfg01.baremetal-mcp-ocata-odl-ha.local:
 111            - 10.20.0.2
 112            - 172.16.10.100
 113        mas01.baremetal-mcp-ocata-odl-ha.local:
 114            - 10.20.0.3
 115            - 172.16.10.3
 116            - 192.168.11.3
 117        .........................
 118
 119
 120 #. View the interfaces of all the components and put the output in a file with yaml format
 121
 122    .. code-block:: bash
 123
 124        root@cfg01:~$ salt "*" network.interfaces --out yaml --output-file interfaces.yaml
 125        root@cfg01:~# cat interfaces.yaml
 126        cfg01.baremetal-mcp-ocata-odl-ha.local:
 127          enp1s0:
 128            hwaddr: 52:54:00:72:77:12
 129            inet:
 130            - address: 10.20.0.2
 131              broadcast: 10.20.0.255
 132              label: enp1s0
 133              netmask: 255.255.255.0
 134            inet6:
 135            - address: fe80::5054:ff:fe72:7712
 136              prefixlen: '64'
 137              scope: link
 138            up: true
 139        .........................
 140
 141
 142 #. View installed packages in MaaS node
 143
 144    .. code-block:: bash
 145
 146       root@cfg01:~# salt "mas*" pkg.list_pkgs
 147       mas01.baremetal-mcp-ocata-odl-ha.local:
 148           ----------
 149           accountsservice:
 150               0.6.40-2ubuntu11.3
 151           acl:
 152               2.2.52-3
 153           acpid:
 154               1:2.0.26-1ubuntu2
 155           adduser:
 156               3.113+nmu3ubuntu4
 157           anerd:
 158               1
 159       .........................
 160
 161
 162 #. Execute any linux command on all nodes (list the content of */var/log* in this example)
 163
 164    .. code-block:: bash
 165
 166       root@cfg01:~# salt "*" cmd.run 'ls /var/log'
 167       cfg01.baremetal-mcp-ocata-odl-ha.local:
 168          alternatives.log
 169          apt
 170          auth.log
 171          boot.log
 172          btmp
 173          cloud-init-output.log
 174          cloud-init.log
 175       .........................
 176
 177
 178 #. Execute any linux command on nodes using compound queries filter
 179
 180    .. code-block:: bash
 181
 182       root@cfg01:~# salt -C '* and cfg01*' cmd.run 'ls /var/log'
 183       cfg01.baremetal-mcp-ocata-odl-ha.local:
 184          alternatives.log
 185          apt
 186          auth.log
 187          boot.log
 188          btmp
 189          cloud-init-output.log
 190          cloud-init.log
 191       .........................
 192
 193
 194 #. Execute any linux command on nodes using role filter
 195
 196    .. code-block:: bash
 197
 198       root@cfg01:~# salt -I 'nova:compute' cmd.run 'ls /var/log'
 199       cmp001.baremetal-mcp-ocata-odl-ha.local:
 200          alternatives.log
 201          apache2
 202          apt
 203          auth.log
 204          btmp
 205          ceilometer
 206          cinder
 207          cloud-init-output.log
 208          cloud-init.log
 209       .........................
 210
 211
 212
 213 ===================
 214 Accessing Openstack
 215 ===================
 216
 217 Once the deployment is complete, Openstack CLI is accessible from controller VMs (ctl01..03).
 218 Openstack credentials are at */root/keystonercv3*.
 219
 220  .. code-block:: bash
 221
 222     root@ctl01:~# source keystonercv3
 223     root@ctl01:~# openstack image list
 224     +--------------------------------------+-----------------------------------------------+--------+
 225     | ID                                   | Name                                          | Status |
 226     +======================================+===============================================+========+
 227     | 152930bf-5fd5-49c2-b3a1-cae14973f35f | CirrosImage                                   | active |
 228     | 7b99a779-78e4-45f3-9905-64ae453e3dcb | Ubuntu16.04                                   | active |
 229     +--------------------------------------+-----------------------------------------------+--------+
 230
 231
 232 The OpenStack Dashboard, Horizon is available at http://<controller VIP>:8078, e.g. http://10.16.0.101:8078.
 233 The administrator credentials are *admin*/*opnfv_secret*.
 234
 235 .. figure:: img/horizon_login.png
 236
 237
 238 A full list of IPs/services is available at <proxy public VIP>:8090 for baremetal deploys.
 239
 240 .. figure:: img/salt_services_ip.png
 241
 242 For Virtual deploys, the most commonly used IPs are in the table below.
 243
 244 +-----------+--------------+---------------+
 245 | Component | IP           | Default value |
 246 +===========+==============+===============+
 247 | gtw01     | x.y.z.110    | 172.16.10.110 |
 248 +-----------+--------------+---------------+
 249 | ctl01     | x.y.z.100    | 172.16.10.100 |
 250 +-----------+--------------+---------------+
 251 | cmp001    | x.y.z.105    | 172.16.10.105 |
 252 +-----------+--------------+---------------+
 253 | cmp002    | x.y.z.106    | 172.16.10.106 |
 254 +-----------+--------------+---------------+
 255
 256
 257 =============================
 258 Reclass model viewer tutorial
 259 =============================
 260
 261
 262 In order to get a better understanding on the reclass model Fuel uses, the `reclass-doc
 263 <https://github.com/jirihybek/reclass-doc>`_ can be used to visualise the reclass model.
 264 A simplified installation can be done with the use of a docker ubuntu container. This
 265 approach will avoid installing packages on the host, which might collide with other packages.
 266 After the installation is done, a webbrowser on the host can be used to view the results.
 267
 268 **NOTE**: The host can be any device with Docker package already installed.
 269           The user which runs the docker needs to have root priviledges.
 270
 271
 272 **Instructions**
 273
 274
 275 #. Create a new directory at any location
 276
 277    .. code-block:: bash
 278
 279       $ mkdir -p modeler
 280
 281
 282 #. Place fuel repo in the above directory
 283
 284    .. code-block:: bash
 285
 286       $ cd modeler
 287       $ git clone https://gerrit.opnfv.org/gerrit/fuel && cd fuel
 288
 289
 290 #. Create a container and mount the above host directory
 291
 292    .. code-block:: bash
 293
 294       $ docker run --privileged -it -v <absolute_path>/modeler:/host ubuntu bash
 295
 296
 297 #. Install all the required packages inside the container.
 298
 299    .. code-block:: bash
 300
 301       $ apt-get update
 302       $ apt-get install -y npm nodejs
 303       $ npm install -g reclass-doc
 304       $ cd /host/fuel/mcp/reclass
 305       $ ln -s /usr/bin/nodejs /usr/bin/node
 306       $ reclass-doc --output /host /host/fuel/mcp/reclass
 307
 308
 309 #. View the results from the host by using a browser. The file to open should be now at modeler/index.html
 310
 311    .. figure:: img/reclass_doc.png
 312
 313
 314 .. _references:
 315
 316 ==========
 317 References
 318 ==========
 319
 320 1) `Installation instructions <http://docs.opnfv.org/en/stable-euphrates/submodules/fuel/docs/release/installation/installation.instruction.html>`_
 321 2) `Saltstack Documentation <https://docs.saltstack.com/en/latest/topics>`_
 322 3) `Saltstack Formulas <http://salt-formulas.readthedocs.io/en/latest/develop/overview-reclass.html>`_
 323
 324