Larry Peterson | 9249775 | 2023-08-16 14:17:24 -0700 | [diff] [blame] | 1 | .. Repositories |
| 2 | .. --------------- |
llp | b353464 | 2023-08-02 09:23:52 -0700 | [diff] [blame] | 3 | |
Larry Peterson | 9249775 | 2023-08-16 14:17:24 -0700 | [diff] [blame] | 4 | Aether is a complex system, assembled from multiple components |
| 5 | spanning several Git repositories. These include repos for different |
| 6 | subsystems (e.g., AMP, SD-Core, SD-RAN), but also for different stages |
Larry Peterson | 5d6b3b3 | 2023-09-05 15:11:55 -0700 | [diff] [blame^] | 7 | of the development pipeline (e.g., source code, deployment artifacts, |
| 8 | configuration specs). This rest of this section identifies all the |
| 9 | Aether-related repositories, with the OnRamp repos listed at the end |
| 10 | serving as the starting point for anyone that wants to come |
| 11 | up-to-speed on the rest of the system. |
| 12 | |
| 13 | .. admonition:: Troubleshooting Hint |
| 14 | |
| 15 | This guide includes *Troubleshooting Hints* like this one. Our first |
| 16 | hint is to recommend that the guide be followed sequentially. This |
| 17 | is because each section establishes a milestone that may prove |
| 18 | useful when you find yourself trying to troubleshoot a problem in a |
| 19 | later section. For example, isolating a problem with a physical gNB |
| 20 | is easier if you know that connectivity to the AMF and UPF works |
| 21 | correctly, which the *Emulated RAN* section helps to establish. |
| 22 | |
| 23 | Our second hint is to join the ``#aether-onramp`` channel of the |
| 24 | `ONF Workspace <https://onf-community.slack.com/>`__ on Slack, where |
| 25 | questions about using OnRamp to bring up Aether are asked and |
| 26 | answered. The ``Troubleshooting`` bookmark for that channel includes |
| 27 | summaries of known issues. |
llp | b353464 | 2023-08-02 09:23:52 -0700 | [diff] [blame] | 28 | |
| 29 | Source Repos |
| 30 | ~~~~~~~~~~~~~~~~ |
| 31 | |
| 32 | Source code for Aether and all of its subsystems can be found in |
| 33 | the following repositories: |
| 34 | |
| 35 | * Gerrit repository for the CORD Project |
| 36 | (https://gerrit.opencord.org): Microservices for AMP, plus source |
| 37 | for the jobs that implement the CI/CD pipeline. |
| 38 | |
| 39 | * GitHub repository for the OMEC Project |
| 40 | (https://github.com/omec-project): Microservices for SD-Core, plus |
| 41 | the emulator (gNBsim) that subjects SD-Core to RAN workloads. |
| 42 | |
| 43 | * GitHub repository for the ONOS Project |
| 44 | (https://github.com/onosproject): Microservices for SD-Fabric and |
| 45 | SD-RAN, plus the YANG models used to generate the Aether API. |
| 46 | |
| 47 | * GitHub repository for the Stratum Project |
| 48 | (https://github.com/stratum): On-switch components of SD-Fabric. |
| 49 | |
| 50 | For Gerrit, you can either browse Gerrit (select the `master` branch) |
| 51 | or clone the corresponding *<repo-name>* by typing: |
| 52 | |
| 53 | .. code-block:: |
| 54 | |
| 55 | $ git clone ssh://gerrit.opencord.org:29418/<repo-name> |
| 56 | |
| 57 | If port 29418 is blocked by your network administrator, you can try cloning |
| 58 | using https instead of ssh: |
| 59 | |
| 60 | .. code-block:: |
| 61 | |
| 62 | $ git clone https://gerrit.opencord.org/<repo-name> |
| 63 | |
| 64 | Anyone wanting to participate in Aether's ongoing development will |
| 65 | want to learn how to contribute new features to these source repos. |
| 66 | |
| 67 | Artifact Repos |
| 68 | ~~~~~~~~~~~~~~~~ |
| 69 | |
| 70 | Aether includes a *Continuous Integration (CI)* pipeline that builds |
| 71 | deployment artifacts (e.g., Helm Charts, Docker Images) from the |
| 72 | source code. These artifacts are stored in the following repositories: |
| 73 | |
| 74 | Helm Charts |
| 75 | |
| 76 | | https://charts.aetherproject.org |
| 77 | | https://charts.onosproject.org |
| 78 | | https://charts.opencord.org |
| 79 | | https://charts.atomix.io |
| 80 | | https://sdrancharts.onosproject.org |
| 81 | | https://charts.rancher.io/ |
| 82 | |
| 83 | Docker Images |
| 84 | |
| 85 | | https://registry.aetherproject.org |
| 86 | |
| 87 | Note that as of version 1.20.8, Kubernetes uses the `Containerd |
| 88 | <https://containerd.io/>`__ runtime system instead of Docker. This is |
| 89 | transparent to anyone using Aether, which manages containers |
| 90 | indirectly through Kubernetes (e.g., using ``kubectl``), but does |
| 91 | impact anyone that directly depends on the Docker toolchain. Also note |
| 92 | that while Aether documentation often refers its use of "Docker |
| 93 | containers," it is now more accurate to say that Aether uses |
| 94 | `OCI-Compliant containers <https://opencontainers.org/>`__. |
| 95 | |
| 96 | The Aether CI pipeline keeps the above artifact repos in sync with the |
| 97 | source repos listed above. Among those source repos are the source |
| 98 | files for all the Helm Charts: |
| 99 | |
| 100 | | ROC: https://gerrit.opencord.org/plugins/gitiles/roc-helm-charts |
| 101 | | SD-RAN: https://github.com/onosproject/sdran-helm-charts |
| 102 | | SD-Core: https://gerrit.opencord.org/plugins/gitiles/sdcore-helm-charts |
| 103 | | SD-Fabric (Servers): https://github.com/onosproject/onos-helm-charts |
| 104 | | SD-Fabric (Switches): https://github.com/stratum/stratum-helm-charts |
| 105 | |
| 106 | The QA tests run against code checked into these source repos can be |
| 107 | found here: |
| 108 | |
| 109 | | https://gerrit.opencord.org/plugins/gitiles/aether-system-tests |
| 110 | |
| 111 | For more information about Aether's CI pipeline, including its QA and |
| 112 | version control strategy, we recommend the Lifecycle Management |
| 113 | chapter of our companion Edge Cloud Operations book. |
| 114 | |
| 115 | .. _reading_cicd: |
| 116 | .. admonition:: Further Reading |
| 117 | |
| 118 | L. Peterson, A. Bavier, S. Baker, Z. Williams, and B. Davie. `Edge |
| 119 | Cloud Operations: A Systems Approach |
| 120 | <https://ops.systemsapproach.org/lifecycle.html>`__. June 2022. |
| 121 | |
| 122 | OnRamp Repos |
| 123 | ~~~~~~~~~~~~~~~~~~~ |
| 124 | |
Larry Peterson | def1b67 | 2023-08-07 14:06:24 -0700 | [diff] [blame] | 125 | The process to deploy the artifacts listed above, sometimes |
llp | b353464 | 2023-08-02 09:23:52 -0700 | [diff] [blame] | 126 | referred to as GitOps, manages the *Continuous Deployment (CD)* half |
| 127 | of the CI/CD pipeline. OnRamp's approach to GitOps uses a different |
| 128 | mechanism than the one the ONF ops team originally used to manage its |
| 129 | multi-site deployment of Aether. The latter approach has a large |
Larry Peterson | def1b67 | 2023-08-07 14:06:24 -0700 | [diff] [blame] | 130 | startup cost, which has proven difficult to replicate. (It also locks |
| 131 | you into deployment toolchain that may or may not be appropriate for |
| 132 | your situation.) |
llp | b353464 | 2023-08-02 09:23:52 -0700 | [diff] [blame] | 133 | |
| 134 | In its place, OnRamp adopts minimal Ansible tooling. This makes it |
| 135 | easier to take ownership of the configuration parameters that define |
| 136 | your specific deployment scenario. The rest of this guide walks you |
| 137 | through a step-by-step process of deploying and operating Aether on |
| 138 | your own hardware. For now, we simply point you at the collection of |
| 139 | OnRamp repos: |
| 140 | |
| 141 | | Deploy Aether: https://github.com/opennetworkinglab/aether-onramp |
| 142 | | Deploy 5G Core: https://github.com/opennetworkinglab/aether-5gc |
| 143 | | Deploy 4G Core: https://github.com/opennetworkinglab/aether-4gc |
| 144 | | Deploy Management Plane: https://github.com/opennetworkinglab/aether-amp |
| 145 | | Deploy 5G RAN Simulator: https://github.com/opennetworkinglab/aether-gnbsim |
| 146 | | Deploy Kubernetes: https://github.com/opennetworkinglab/aether-k8s |
| 147 | |
| 148 | It is the first repo that defines a way to integrate all of the Aether |
| 149 | artifacts into an operational system. That repo, in turn, includes the |
| 150 | other repos as submodules. Note that each of the submodules is |
| 151 | self-contained if you are interested in deploying just that subsystem, |
| 152 | but this guide approaches the deployment challenge from an |
| 153 | integrated/end-to-end perspective. |
| 154 | |
| 155 | Because OnRamp uses Ansible as its primary deployment tool, a general |
| 156 | understanding of Ansible is helpful (see the suggested reference). |
| 157 | However, this guide walks you, step-by-step, through the process of |
| 158 | deploying and operating Aether, so previous experience with Ansible is |
| 159 | not a requirement. Note that Ansible has evolved to be both a |
| 160 | "Community Toolset" anyone can use to manage a software deployment, |
| 161 | and an "Automation Platform" offered as a service by RedHat. OnRamp |
| 162 | uses the toolset, but not the platform/service. |
| 163 | |
| 164 | .. _reading_ansible: |
| 165 | .. admonition:: Further Reading |
| 166 | |
| 167 | `Overview: How Ansible Works <https://www.ansible.com/overview/how-ansible-works>`__. |
| 168 | |