docs/release/installation/troubleshooting.rst

   1 Developer Guide and Troubleshooting
   2 ===================================
   3
   4 This section aims to explain in more detail the steps that Apex follows
   5 to make a deployment. It also tries to explain possible issues you might find
   6 in the process of building or deploying an environment.
   7
   8 After installing the Apex RPMs in the jumphost, some files will be located
   9 around the system.
  10
  11 1.  /etc/opnfv-apex: this directory contains a bunch of scenarios to be
  12     deployed with different characteristics such HA (High Availability), SDN
  13     controller integration (OpenDaylight/ONOS), BGPVPN, FDIO, etc. Having a
  14     look at any of these files will give you an idea of how to make a
  15     customized scenario setting up different flags.
  16
  17 2.  /usr/bin/: it contains the binaries for the commands opnfv-deploy,
  18     opnfv-clean and opnfv-util.
  19
  20 3.  /var/opt/opnfv/: it contains several files and directories.
  21
  22    3.1.   images/: this folder contains the images that will be deployed
  23    according to the chosen scenario.
  24
  25    3.2.   lib/: bunch of scripts that will be executed in the different phases
  26    of deployment.
  27
  28
  29 Utilization of Images
  30 ---------------------
  31
  32 As mentioned earlier in this guide, the Undercloud VM will be in charge of
  33 deploying OPNFV (Overcloud VMs). Since the Undercloud is an all-in-one
  34 OpenStack deployment, it will use Glance to manage the images that will be
  35 deployed as the Overcloud.
  36
  37 So whatever customization that is done to the images located in the jumpserver
  38 (/var/opt/opnfv/images) will be uploaded to the undercloud and consequently, to
  39 the overcloud.
  40
  41 Make sure, the customization is performed on the right image. For example, if I
  42 virt-customize the following image overcloud-full-opendaylight.qcow2, but then
  43 I deploy OPNFV with the following command:
  44
  45         ``sudo opnfv-deploy -n network_settings.yaml -d
  46         /etc/opnfv-apex/os-onos-nofeature-ha.yaml``
  47
  48 It will not have any effect over the deployment, since the customized image is
  49 the opendaylight one, and the scenario indicates that the image to be deployed
  50 is the overcloud-full-onos.qcow2.
  51
  52
  53 Post-deployment Configuration
  54 -----------------------------
  55
  56 Post-deployment scripts will perform some configuration tasks such ssh-key
  57 injection, network configuration, NATing, OpenVswitch creation. It will take
  58 care of some OpenStack tasks such creation of endpoints, external networks,
  59 users, projects, etc.
  60
  61 If any of these steps fail, the execution will be interrupted. In some cases,
  62 the interruption occurs at very early stages, so a new deployment must be
  63 executed. However, some other cases it could be worth it to try to debug it.
  64
  65         1.  There is not external connectivity from the overcloud nodes:
  66
  67                 Post-deployment scripts will configure the routing, nameservers
  68                 and a bunch of other things between the overcloud and the
  69                 undercloud. If local connectivity, like pinging between the
  70                 different nodes, is working fine, script must have failed when
  71                 configuring the NAT via iptables. The main rules to enable
  72                 external connectivity would look like these:
  73
  74                 ``iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE``
  75                 ``iptables -t nat -A POSTROUTING -s ${external_cidr} -o eth0 -j
  76                 MASQUERADE``
  77                 ``iptables -A FORWARD -i eth2 -j ACCEPT``
  78                 ``iptables -A FORWARD -s ${external_cidr} -m state --state
  79                 ESTABLISHED,RELATED -j ACCEPT``
  80                 ``service iptables save``
  81
  82                 These rules must be executed as root (or sudo) in the
  83                 undercloud machine.
  84
  85 OpenDaylight Integration
  86 ------------------------
  87
  88 When a user deploys any of the following scenarios:
  89
  90         - os-odl-bgpvpn-ha.yaml
  91         - os-odl_l2-fdio-ha.yaml
  92         - os-odl_l2-fdio-noha.yaml
  93         - os-odl_l2-nofeature-ha.yaml
  94         - os-odl_l2-sfc-noha.yaml
  95         - os-odl_l3-nofeature-ha.yaml
  96
  97 OpenDaylight (ODL) SDN controller will be deployed too and completely
  98 integrated with OpenStack. ODL is running as a systemd service, so you can
  99 manage it as a regular service:
 100
 101         ``systemctl start/restart/stop opendaylight.service``
 102
 103 This command must be executed as root in the controller node of the overcloud,
 104 where OpenDaylight is running. ODL files are located in /opt/opendaylight. ODL
 105 uses karaf as a Java container management system that allows the users to
 106 install new features, check logs and configure a lot of things. In order to
 107 connect to Karaf's console, use the following command:
 108
 109         ``opnfv-util opendaylight``
 110
 111 This command is very easy to use, but in case it is not connecting to Karaf,
 112 this is the command that is executing underneath:
 113
 114         ``ssh -p 8101 -o UserKnownHostsFile=/dev/null -o
 115         StrictHostKeyChecking=no karaf@localhost``
 116
 117 Of course, localhost when the command is executed in the overcloud controller,
 118 but you use its public IP to connect from elsewhere.
 119
 120 Debugging Failures
 121 ------------------
 122
 123 This section will try to gather different type of failures, the root cause and
 124 some possible solutions or workarounds to get the process continued.
 125
 126 1.  I can see in the output log a post-deployment error messages:
 127
 128         Heat resources will apply puppet manifests during this phase. If one of
 129         these processes fail, you could try to see the error and after that,
 130         re-run puppet to apply that manifest. Log into the controller (see
 131         verification section for that) and check as root /var/log/messages.
 132         Search for the error you have encountered and see if you can fix it. In
 133         order to re-run the puppet manifest, search for "puppet apply" in that
 134         same log. You will have to run the last "puppet apply" before the
 135         error. And It should look like this:
 136
 137                 ``FACTER_heat_outputs_path="/var/run/heat-config/heat-config-puppet/5b4c7a01-0d63-4a71-81e9-d5ee6f0a1f2f"  FACTER_fqdn="overcloud-controller-0.localdomain.com" \
 138                 FACTER_deploy_config_name="ControllerOvercloudServicesDeployment_Step4"  puppet apply --detailed-exitcodes -l syslog -l console \
 139                 /var/lib/heat-config/heat-config-puppet/5b4c7a01-0d63-4a71-81e9-d5ee6f0a1f2f.pp``
 140
 141         As a comment, Heat will trigger the puppet run via os-apply-config and
 142         it will pass a different value for step each time. There is a total of
 143         five steps. Some of these steps will not be executed depending on the
 144         type of scenario that is being deployed.