docs/usecases/vpp_testbench/index.rst

   1 VPP Container Test Bench
   2 ========================
   3
   4 This project spins up a pair of Docker containers, both of which are running
   5 Ubuntu 20.04 "Focal Fossa" (x86_64) along with VPP. At run-time, the containers
   6 will attempt to create various links between each other, using both the Linux
   7 networking stack as well as VPP, and will then send some simple traffic
   8 back-and-forth (i.e. ICMP echo/ping requests and HTTP GET requests).
   9
  10 The intent of this example is to provide a relatively simple example of
  11 connecting containers via VPP and allowing others to use it as a springboard of
  12 sorts for their own projects and examples. Besides Docker and a handful of
  13 common Linux command-line utlities, not much else is required to build this
  14 example (due to most of the dependencies being lumped inside the containers
  15 themselves).
  16
  17 Instructions - Short Version
  18 ----------------------------
  19
  20 The use of an Ubuntu 20.04 LTS Linux distro, running on x86_64 hardware, is
  21 required for these labs. If your current workstation/PC/laptop/etc. is
  22 unable to run such a setup natively, the reader is now tasked with figuring out
  23 how to get such a setup in order. This can be accomplished, for example,
  24 through the use of virtual machines  via tools like VirtualBox, or ``vagrant``.
  25 As this can be a time consuming task for readers new to virtual machines, we
  26 leave it as an exercise for the reader, as it is impractical to provide support
  27 for such a task in this narrow/focused set of labs and tutorials.
  28
  29 This being said, it's quite probable that one could use these labs on different
  30 flavors/distros of Linux, since the bulk of the work involved takes place
  31 inside containers which are always set to use an Ubuntu 20.04 baseline.
  32 However, for the sake of these labs, any other such setup is not supported.
  33
  34 - Replicate the file listings at the end of this document
  35   (:ref:`sec_file_listings_vpp_testbench`).  You can also directly acquire a
  36   copy of these files by cloning the VPP repo, and navigating to the
  37   ``docs/usecases/vpp_testbench/src`` path to save yourself the hassle of
  38   copy-pasting and naming the files. Once that's done, open a shell, and
  39   navigate to the location housing the project files.
  40 - To build the project, simply run: ``make``
  41 - To start up the containers and have all the initialization logic take place,
  42   run: ``make start``
  43 - To trigger some basic traffic tests, run: ``make poll``
  44 - To terminate the containers and clean-up associated resources, run ``make stop``
  45 - To launch an interactive shell for the "client" container, run ``make
  46   shell_client``
  47 - To launch an interactive shell for the "server" container, run ``make
  48   shell_server``
  49
  50 Instructions - Long Version
  51 ---------------------------
  52
  53 Directory Structure and File Purposes
  54 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  55
  56 First, let's quickly review the purpose of the various files used in this
  57 project.
  58
  59 * ``vpp_testbench_helpers.sh``: shell variables and helper functions re-used in
  60   other scripts in this project. Intended to be sourced (i.e. not intended to
  61   be run directly). Some of the helper functions are used at run-time within
  62   the containers, while others are intended to be run in the default namespace
  63   on the host operating system to help with run-time configuration/bringup of
  64   the testbench.
  65 * ``Dockerfile.vpp_testbench``: used to build the various Docker images used in
  66   this project (i.e. so VPP, our test tools, etc.; are all encapsulated within
  67   containers rather than being deployed to the host OS).
  68 * ``Dockerfile.vpp_testbench.dockerignore``: a "permit-list" to restrict what
  69   files we permit to be included in our Docker images (helps keep image size
  70   down and provides some minor security benefits at build time, at least in
  71   general).
  72 * ``entrypoint_client.sh``: entrypoint script used by the "client" Docker
  73   container when it is launched.
  74 * ``entrypoint_server.sh``: entrypoint script used by the "server" Docker
  75   container when it is launched.
  76 * ``Makefile``: top-level script; used to trigger the artifacts and Docker
  77   image builds, provides rules for starting/testing/stopping the containers,
  78   etc.
  79
  80 Getting Started
  81 ^^^^^^^^^^^^^^^
  82
  83 First, we'll assume you are running on a Ubuntu 20.04 x86_64 setup (either on a
  84 bare metal host or in a virtual machine), and have acquirec a copy of the
  85 project files (either by cloning the VPP git repository, or duplicating them
  86 from :ref:`sec_file_listings_vpp_testbench`). Now, just run ``make``. The
  87 process should take a few minutes as it pulls the baseline Ubuntu Docker image,
  88 applies system/package updates/upgrades via ``apt``, and installs VPP.
  89
  90 Next, one can start up the containers used by the project via ``make start``.
  91 From this point forward, most testing, experiments, etc.; will likely involve
  92 modifying/extending the ``poll_containers`` definition inside ``Makefile``
  93 (probably easiest to just have it invoke a shell script that you write for your
  94 own testing). Once you've completed various test runs, the entire deployment
  95 can be cleaned-up via ``make stop``, and the whole process of starting,
  96 testing, stopping, etc.; can be repeated as needed.
  97
  98 In addition to starting up the containers, ``make start`` will establish
  99 variaous types of links/connections between the two containers, making use of
 100 both the Linux network stack, as well as VPP, to handle the "plumbing"
 101 involved. This is to allow various types of connections between the two
 102 containers, and to allow the reader to experiment with them (i.e. using
 103 ``vppctl`` to congfigure or trace packets going over VPP-managed links, use
 104 traditional Linux command line utilities like ``tcpdump``, ``iproute2``,
 105 ``ping``, etc.; to accomplish similar tasks over links managed purely by the
 106 Linux network stack, etc.). Later labs will also encourage readers to compare
 107 the two types of links (perhaps some performance metrics/profiling, or similar
 108 tasks). This testbench project is effectively intended as a baseline workspace
 109 upon which one may design and run the labs (or your own projects and examples,
 110 whichever works for you).
 111
 112 Labs
 113 ----
 114
 115 .. toctree::
 116    labs/intro_to_vpp/index
 117
 118 Future Labs
 119 -----------
 120
 121 .. note::
 122
 123    Coming soon.
 124
 125 - Lab: Writing your First CLI Application (Querying Statistics)
 126 - Lab: MACSWAP Plugin Revisited
 127
 128 .. _sec_file_listings_vpp_testbench:
 129
 130 File Listings
 131 -------------
 132
 133 Makefile
 134 ^^^^^^^^
 135
 136 .. literalinclude:: src/Makefile
 137    :caption: Makefile
 138    :language: Makefile
 139    :linenos:
 140
 141 Dockerfile.vpp_testbench
 142 ^^^^^^^^^^^^^^^^^^^^^^^^
 143
 144 .. literalinclude:: src/Dockerfile.vpp_testbench
 145    :caption: Dockerfile.vpp_testbench
 146    :language: Dockerfile
 147    :linenos:
 148
 149 Dockerfile.vpp_testbench.dockerignore
 150 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 151
 152 .. literalinclude:: src/Dockerfile.vpp_testbench.dockerignore
 153    :caption: Dockerfile.vpp_testbench.dockerignore
 154    :language: Dockerfile
 155    :linenos:
 156
 157 vpp_testbench_helpers.sh
 158 ^^^^^^^^^^^^^^^^^^^^^^^^
 159
 160 .. literalinclude:: src/vpp_testbench_helpers.sh
 161    :caption: vpp_testbench_helpers.sh
 162    :language: shell
 163    :linenos:
 164
 165 entrypoint_client.sh
 166 ^^^^^^^^^^^^^^^^^^^^
 167
 168 .. literalinclude:: src/entrypoint_client.sh
 169    :caption: entrypoint_client.sh
 170    :language: shell
 171    :linenos:
 172
 173 entrypoint_server.sh
 174 ^^^^^^^^^^^^^^^^^^^^
 175
 176 .. literalinclude:: src/entrypoint_server.sh
 177    :caption: entrypoint_server.sh
 178    :language: shell
 179    :linenos:
 180