onramp/directory.rst

.. Repositories
.. ---------------

Aether is a complex system, assembled from multiple components
spanning several Git repositories. These include repos for different
subsystems (e.g., AMP, SD-Core, SD-RAN), but also for different stages
of the development pipeline (e.g., source code, deployment artifacts,
configuration specs).  This rest of this section identifies all the
Aether-related repositories, with the OnRamp repos listed at the end
serving as the starting point for anyone who wants to come
up to speed on the rest of the system.

.. admonition:: Troubleshooting Hint

  This guide includes *Troubleshooting Hints* like this one. Our first
  hint is to recommend that the guide be followed sequentially. This
  is because each section establishes a milestone that may prove
  useful when you find yourself trying to troubleshoot a problem in a
  later section. For example, isolating a problem with a physical gNB
  is easier if you know that connectivity to the AMF and UPF works
  correctly, which the *Emulated RAN* section helps to establish.

  Our second hint is to join the ``#aether-onramp`` channel of the
  `ONF Workspace <https://onf-community.slack.com/>`__ on Slack, where
  questions about using OnRamp to bring up Aether are asked and
  answered. The ``Troubleshooting`` bookmark for that channel includes
  summaries of known issues.

Source Repos
~~~~~~~~~~~~~~~~

Source code for Aether and all of its subsystems can be found in
the following repositories:

* Gerrit repository for the CORD Project
  (https://gerrit.opencord.org): Microservices for AMP, plus source
  for the jobs that implement the CI/CD pipeline.

* GitHub repository for the OMEC Project
  (https://github.com/omec-project): Microservices for SD-Core, plus
  the emulator (gNBsim) that subjects SD-Core to RAN workloads.

* GitHub repository for the ONOS Project
  (https://github.com/onosproject): Microservices for SD-Fabric and
  SD-RAN, plus the YANG models used to generate the Aether API.

* GitHub repository for the Stratum Project
  (https://github.com/stratum): On-switch components of SD-Fabric.

For Gerrit, you can either browse Gerrit (select the `master` branch)
or clone the corresponding *<repo-name>* by typing:

.. code-block::

  $ git clone ssh://gerrit.opencord.org:29418/<repo-name>

If port 29418 is blocked by your network administrator, you can try cloning
using https instead of ssh:

.. code-block::

  $ git clone https://gerrit.opencord.org/<repo-name>

Anyone wanting to participate in Aether's ongoing development will
want to learn how to contribute new features to these source repos.

Artifact Repos
~~~~~~~~~~~~~~~~

Aether includes a *Continuous Integration (CI)* pipeline that builds
deployment artifacts (e.g., Helm Charts, Docker Images) from the
source code. These artifacts are stored in the following repositories:

Helm Charts

 | https://charts.aetherproject.org
 | https://charts.onosproject.org
 | https://charts.opencord.org
 | https://charts.atomix.io
 | https://sdrancharts.onosproject.org
 | https://charts.rancher.io/

Docker Images

 | https://registry.aetherproject.org

Note that as of version 1.20.8, Kubernetes uses the `Containerd
<https://containerd.io/>`__ runtime system instead of Docker. This is
transparent to anyone using Aether, which manages containers
indirectly through Kubernetes (e.g., using ``kubectl``), but does
impact anyone who directly depends on the Docker toolchain. Also note
that while Aether documentation often refers its use of "Docker
containers," it is now more accurate to say that Aether uses
`OCI-Compliant containers <https://opencontainers.org/>`__.

The Aether CI pipeline keeps the above artifact repos in sync with the
source repos listed above. Among those source repos are the source
files for all the Helm Charts:

 | ROC: https://gerrit.opencord.org/plugins/gitiles/roc-helm-charts
 | SD-RAN: https://github.com/onosproject/sdran-helm-charts
 | SD-Core: https://gerrit.opencord.org/plugins/gitiles/sdcore-helm-charts
 | SD-Fabric (Servers): https://github.com/onosproject/onos-helm-charts
 | SD-Fabric (Switches): https://github.com/stratum/stratum-helm-charts

The QA tests run against code checked into these source repos can be
found here:

 | https://gerrit.opencord.org/plugins/gitiles/aether-system-tests

The specification for the CI pipeline, which invokes these QA tests,
gates merge requests, and publishes artifacts, can be found here:

 | https://gerrit.opencord.org/plugins/gitiles/aether-ci-management

For more information about Aether's CI pipeline, including its QA and
version control strategy, we recommend the Lifecycle Management
chapter of our companion Edge Cloud Operations book.

.. _reading_cicd:
.. admonition:: Further Reading

    L. Peterson, A. Bavier, S. Baker, Z. Williams, and B. Davie. `Edge
    Cloud Operations: A Systems Approach
    <https://ops.systemsapproach.org/lifecycle.html>`__. June 2022.

OnRamp Repos
~~~~~~~~~~~~~~~~~~~

The process to deploy the artifacts listed above, sometimes
referred to as GitOps, manages the *Continuous Deployment (CD)* half
of the CI/CD pipeline. OnRamp's approach to GitOps uses a different
mechanism than the one the ONF ops team originally used to manage its
multi-site deployment of Aether.  The latter approach has a large
startup cost, which has proven difficult to replicate. (It also locks
you into deployment toolchain that may or may not be appropriate for
your situation.)

In its place, OnRamp adopts minimal Ansible tooling. This makes it
easier to take ownership of the configuration parameters that define
your specific deployment scenario.  The rest of this guide walks you
through a step-by-step process of deploying and operating Aether on
your own hardware.  For now, we simply point you at the collection of
OnRamp repos:

 | Deploy Aether: https://github.com/opennetworkinglab/aether-onramp
 | Deploy 5G Core: https://github.com/opennetworkinglab/aether-5gc
 | Deploy 4G Core: https://github.com/opennetworkinglab/aether-4gc
 | Deploy Management Plane: https://github.com/opennetworkinglab/aether-amp
 | Deploy 5G RAN Simulator: https://github.com/opennetworkinglab/aether-gnbsim
 | Deploy Kubernetes: https://github.com/opennetworkinglab/aether-k8s

It is the first repo that defines a way to integrate all of the Aether
artifacts into an operational system. That repo, in turn, includes the
other repos as submodules. Note that each of the submodules is
self-contained if you are interested in deploying just that subsystem,
but this guide approaches the deployment challenge from an
integrated, end-to-end perspective.

Because OnRamp uses Ansible as its primary deployment tool, a general
understanding of Ansible is helpful (see the suggested reference).
However, this guide walks you, step-by-step, through the process of
deploying and operating Aether, so previous experience with Ansible is
not a requirement. Note that Ansible has evolved to be both a
"Community Toolset" anyone can use to manage a software deployment,
and an "Automation Platform" offered as a service by RedHat. OnRamp
uses the toolset, but not the platform/service.

.. _reading_ansible:
.. admonition:: Further Reading

   `Overview: How Ansible Works <https://www.ansible.com/overview/how-ansible-works>`__.