docs/release/installation/upstream.rst

   1 Deploying Directly from Upstream - (Beta)
   2 =========================================
   3
   4 In addition to deploying with OPNFV tested artifacts included in the
   5 opnfv-apex-undercloud and opnfv-apex RPMs, it is now possible to deploy
   6 directly from upstream artifacts.  Essentially this deployment pulls the latest
   7 RDO overcloud and undercloud artifacts at deploy time.  This option is useful
   8 for being able to deploy newer versions of OpenStack that are not included
   9 with this release, and offers some significant advantages for some users.
  10 Please note this feature is currently in beta for the Fraser release and will
  11 be fully supported in the next OPNFV release.
  12
  13 Upstream Deployment Key Features
  14 --------------------------------
  15
  16 In addition to being able to install newer versions of OpenStack, the upstream
  17 deployment option allows the use of a newer version of TripleO, which provides
  18 overcloud container support.  Therefore when deploying from upstream with an
  19 OpenStack version newer than Pike, every OpenStack service (also OpenDaylight)
  20 will be running as a docker container.  Furthermore, deploying upstream gives
  21 the user the flexibility of including any upstream OpenStack patches he/she
  22 may need by simply adding them into the deploy settings file.  The patches will
  23 be applied live during deployment.
  24
  25 Installation Guide - Upstream Deployment
  26 ========================================
  27
  28 This section goes step-by-step on how to correctly install and provision the
  29 OPNFV target system using a direct upstream deployment.
  30
  31 Special Requirements for Upstream Deployments
  32 ---------------------------------------------
  33
  34 With upstream deployments it is required to have internet access.  In addition,
  35 the upstream artifacts will be cached under the root partition of the jump
  36 host.  It is required to at least have 10GB free space in the root partition
  37 in order to download and prepare the cached artifacts.
  38
  39 Scenarios and Deploy Settings for Upstream Deployments
  40 ------------------------------------------------------
  41
  42 Some deploy settings files are already provided which have been tested by the
  43 Apex team.  These include (under /etc/opnfv-apex/):
  44
  45     - os-nosdn-queens_upstream-noha.yaml
  46     - os-nosdn-master_upstream-noha.yaml
  47     - os-odl-queens_upstream-noha.yaml
  48     - os-odl-master_upstream-noha.yaml
  49
  50 Each of these scenarios has been tested by Apex over the Fraser release, but
  51 none are guaranteed to work as upstream is a moving target and this feature is
  52 relatively new.  Still it is the goal of the Apex team to provide support
  53 and move to an upstream based deployments in the future, so please file a bug
  54 when encountering any issues.
  55
  56 Including Upstream Patches with Deployment
  57 ------------------------------------------------------
  58
  59 With upstream deployments it is possible to include any pending patch in
  60 OpenStack gerrit with the deployment.  These patches are applicable to either
  61 the undercloud or the overcloud.  This feature is useful in the case where
  62 a developer or user desires to pull in an unmerged patch for testing with a
  63 deployment.  In order to use this feature, include the following in the deploy
  64 settings file, under "global_params" section:
  65
  66 .. code-block:: yaml
  67
  68      patches:
  69        undercloud:
  70          - change-id: <gerrit change id>
  71            project: openstack/<project name>
  72            branch:  <branch where commit is proposed>
  73        overcloud:
  74          - change-id: <gerrit change id>
  75            project: openstack/<project name>
  76            branch:  <branch where commit is proposed>
  77
  78 You may include as many patches as needed.  If the patch is already merged or
  79 abandoned, then it will not be included in the deployment.
  80
  81 Running ``opnfv-deploy``
  82 ------------------------
  83
  84 Deploying is similar to the typical method used for baremetal and virtual
  85 deployments with the addition of a few new arguments to the ``opnfv-deploy``
  86 command.  In order to use an upstream deployment, please use the ``--upstream``
  87 argument.  Also, the artifacts for each upstream deployment are only
  88 downloaded when a newer version is detected upstream.  In order to explicitly
  89 disable downloading new artifacts from upstream if previous artifacts are
  90 already cached, please use the ``--no-fetch`` argument.
  91
  92 Interacting with Containerized Overcloud
  93 ----------------------------------------
  94
  95 Upstream deployments will use a containerized overcloud.  These containers are
  96 Docker images built by the Kolla project.  The Containers themselves are run
  97 and controlled through Docker as root user.  In order to access logs for each
  98 service, examine the '/var/log/containers' directory or use the `docker logs
  99 <container name>`.  To see a list of services running on the node, use the
 100 ``docker ps`` command.  Each container uses host networking, which means that
 101 the networking of the overcloud node will act the same exact way as a
 102 traditional deployment.  In order to attach to a container, use this command:
 103 ``docker exec -it <container name/id> bin/bash``.  This will login to the
 104 container with a bash shell.  Note the containers do not use systemd, unlike
 105 the traditional deployment model and are instead started as the first process
 106 in the container.  To restart a service, use the ``docker restart <container>``
 107 command.