docs(orc8r): Adds docs for Charmed Magma 1.8 (magma#15186)

* docs(orc8r): Adds docs for Charmed Magma 1.8 Signed-off-by: Bartlomiej Gmerek <[email protected]> * docs(orc8r): Fixes styling issues Signed-off-by: Bartlomiej Gmerek <[email protected]> * docs(orc8r): Fixes styling issues Signed-off-by: Bartlomiej Gmerek <[email protected]> * docs(orc8r): Fixes styling issues Signed-off-by: Bartlomiej Gmerek <[email protected]> * docs(orc8r): Addressing PR comments Signed-off-by: Bartlomiej Gmerek <[email protected]> * Updating links to the official Charmed Magma docs Signed-off-by: Bartlomiej Gmerek <[email protected]> * Minor updates in the tutorial Signed-off-by: Bartlomiej Gmerek <[email protected]> * Minor updates in the tutorial Signed-off-by: Bartlomiej Gmerek <[email protected]> --------- Signed-off-by: Bartlomiej Gmerek <[email protected]>
Mirantis · Jul 30, 2024 · 4c7edd1 · 4c7edd1
1 parent 3595d44
commit 4c7edd1
Show file tree

Hide file tree

Showing 25 changed files with 1,854 additions and 14 deletions.
diff --git a/docs/docusaurus/i18n/en.json b/docs/docusaurus/i18n/en.json
@@ -174,6 +174,9 @@
       "lte/debug_user_control_plane": {
         "title": "User Control Plane trace CLI"
       },
+      "lte/deploy_agw_using_juju": {
+        "title": "Deploy AGW using Juju"
+      },
       "lte/deploy_config_agw": {
         "title": "Configure AGW"
       },
@@ -517,6 +520,30 @@
       "resources/ref_useful_links": {
         "title": "Useful Links"
       },
+      "tutorials/00_overview": {
+        "title": "Overview"
+      },
+      "tutorials/01_getting_started": {
+        "title": "1. Getting Started"
+      },
+      "tutorials/02_deploying_magma_orchestrator": {
+        "title": "2. Deploying Magma Orchestrator"
+      },
+      "tutorials/03_deploying_magma_agw": {
+        "title": "3. Deploying Magma Access Gateway"
+      },
+      "tutorials/04_integrating_agw_with_orc8r": {
+        "title": "4. Integrating Magma Access Gateway with Magma Orchestrator"
+      },
+      "tutorials/05_deploying_the_radio_simulator": {
+        "title": "5. Deploying the radio simulator"
+      },
+      "tutorials/06_simulating_user_traffic": {
+        "title": "6. Simulating user traffic"
+      },
+      "tutorials/06_destroying_the_env": {
+        "title": "7. Destroying the environment"
+      },
       "version-1.0.0/basics/version-1.0.0-introduction": {
         "title": "Introduction"
       },
@@ -2003,6 +2030,9 @@
       "version-1.8.0/lte/version-1.8.0-build_install_magma_pkg_in_agw": {
         "title": "Build and install a magma package in AGW"
       },
+      "version-1.8.0/lte/version-1.8.0-deploy_agw_using_juju": {
+        "title": "Deploy AGW using Juju"
+      },
       "version-1.8.0/lte/version-1.8.0-deploy_install_docker": {
         "title": "Install Docker AGW"
       },
@@ -2074,6 +2104,30 @@
       },
       "version-1.8.0/proposals/version-1.8.0-p014_proposal_process": {
         "title": "Magma Proposals"
+      },
+      "version-1.8.0/tutorials/version-1.8.0-00_overview": {
+        "title": "Overview"
+      },
+      "version-1.8.0/tutorials/version-1.8.0-01_getting_started": {
+        "title": "1. Getting Started"
+      },
+      "version-1.8.0/tutorials/version-1.8.0-02_deploying_magma_orchestrator": {
+        "title": "2. Deploying Magma Orchestrator"
+      },
+      "version-1.8.0/tutorials/version-1.8.0-03_deploying_magma_agw": {
+        "title": "3. Deploying Magma Access Gateway"
+      },
+      "version-1.8.0/tutorials/version-1.8.0-04_integrating_agw_with_orc8r": {
+        "title": "4. Integrating Magma Access Gateway with Magma Orchestrator"
+      },
+      "version-1.8.0/tutorials/version-1.8.0-05_deploying_the_radio_simulator": {
+        "title": "5. Deploying the radio simulator"
+      },
+      "version-1.8.0/tutorials/version-1.8.0-06_simulating_user_traffic": {
+        "title": "6. Simulating user traffic"
+      },
+      "version-1.8.0/tutorials/version-1.8.0-06_destroying_the_env": {
+        "title": "7. Destroying the environment"
       }
     },
     "links": {
@@ -2086,6 +2140,7 @@
     },
     "categories": {
       "Getting Started": "Getting Started",
+      "Tutorials": "Tutorials",
       "Usage": "Usage",
       "Architecture": "Architecture",
       "Deploy": "Deploy",

diff --git a/docs/docusaurus/sidebars.json b/docs/docusaurus/sidebars.json
@@ -6,6 +6,22 @@
       "basics/quick_start_guide",
       "bazel/agw_with_bazel"
     ],
+    "Tutorials": [
+      {
+        "type": "subcategory",
+        "label": "Operate your own private mobile network with Charmed Magma",
+        "ids": [
+          "tutorials/00_overview",
+          "tutorials/01_getting_started",
+          "tutorials/02_deploying_magma_orchestrator",
+          "tutorials/03_deploying_magma_agw",
+          "tutorials/04_integrating_agw_with_orc8r",
+          "tutorials/05_deploying_the_radio_simulator",
+          "tutorials/06_simulating_user_traffic",
+          "tutorials/06_destroying_the_env"
+        ]
+      }
+    ],
     "Usage": [
       {
         "type": "subcategory",
@@ -98,6 +114,7 @@
           "lte/deploy_config_agw",
           "lte/deploy_config_enodebd",
           "lte/deploy_config_apn",
+          "lte/deploy_agw_using_juju",
           "lte/build_install_magma_pkg_in_agw"
         ]
       },

diff --git a/docs/docusaurus/versioned_docs/version-1.6.X/orc8r/deploy_using_juju.md b/docs/docusaurus/versioned_docs/version-1.6.X/orc8r/deploy_using_juju.md
@@ -10,7 +10,7 @@ original_id: deploy_using_juju
 This how-to guide can be used to deploy Magma's Orchestrator on any cloud environment. It contains
 steps to set up a Kubernetes cluster, bootstrap a Juju controller, deploy charmed operators for
 Magma Orchestrator and configure DNS A records. For more information on Charmed Magma, please visit
-the project's [homepage](https://canonical.github.io/charmed-magma/1.6/).
+the project's [homepage](https://canonical-charmed-magma.readthedocs-hosted.com/en/1.6/).
 
 ## Pre-requisites
 

diff --git a/docs/docusaurus/versioned_docs/version-1.7.0/orc8r/deploy_using_juju.md b/docs/docusaurus/versioned_docs/version-1.7.0/orc8r/deploy_using_juju.md
@@ -7,11 +7,11 @@ original_id: deploy_using_juju
 
 # Deploy Orchestrator using Juju
 
-[Charmed Magma](https://canonical.github.io/charmed-magma/) doesn't
+[Charmed Magma](https://canonical-charmed-magma.readthedocs-hosted.com/en/latest/) doesn't
 support release 1.7.
 
-To use officially released Charmed Magma 1.6, please refer to the
-[official Charmed Magma 1.6 docs](https://canonical.github.io/charmed-magma/1.6/).
+To use officially released Charmed Magma 1.8, please refer to the
+[official Charmed Magma 1.8 docs](https://canonical-charmed-magma.readthedocs-hosted.com/en/1.8/).
 
 To try out the latest version of Charmed Magma please follow instructions
-from the [official docs](https://canonical.github.io/charmed-magma/main/).
+from the [official docs](https://canonical-charmed-magma.readthedocs-hosted.com/en/latest/).
diff --git a/docs/docusaurus/versioned_docs/version-1.8.0/lte/deploy_agw_using_juju.md b/docs/docusaurus/versioned_docs/version-1.8.0/lte/deploy_agw_using_juju.md
@@ -0,0 +1,77 @@
+---
+id: version-1.8.0-deploy_agw_using_juju
+title: Deploy AGW using Juju
+hide_title: true
+original_id: deploy_agw_using_juju
+---
+
+# Deploy Charmed Magma Access Gateway
+
+## Requirements
+
+### Management machine
+
+- Ubuntu machine with internet access
+
+### Access Gateway machine
+
+The Access Gateway must be installed on a machine with the following specifications:
+
+- **Operating System**: Ubuntu 20.04 LTS with Linux Kernel 5.4
+- **Processor**: x86-64 dual-core processor (around 2GHz clock speed or faster)
+- **Memory**: 4GB RAM
+- **Storage**: 32GB or greater SSD
+- **Networking**: At least two ethernet interfaces using two different subnets (**SGi** for internet connectivity and **S1** for enodeB connectivity)
+
+!!! danger
+
+    Installing this charm will affect the target computer's networking configuration. Make sure it is installed on designated hardware (personal computers are strongly discouraged).
+
+!!! info
+
+    Some clouds like AWS use newer kernel versions by default. If you want to downgrade your kernel, please refer to the following [guide](https://discourse.ubuntu.com/t/how-to-downgrade-the-kernel-on-ubuntu-20-04-to-the-5-4-lts-version/26459).
+
+## Set up your management environment
+
+- Install [Juju 2.9](https://juju.is/docs/olm/installing-juju) on your management machine
+- Create and bootstrap a [manual cloud](https://juju.is/docs/olm/manual-setup)
+- [Add the Ubuntu machine](https://juju.is/docs/olm/manual-setup#heading--add-machines-to-a-manual-cloud) to your manual cloud
+
+## Install Magma Access Gateway
+
+=== "Option 1: DHCP network configuration"
+
+    Deploy Magma Access Gateway:
+    ``` bash
+    juju deploy magma-access-gateway-operator --config sgi=enp0s1 --config s1=enp0s2 --channel=1.8/stable --to <AGW machine ID>
+    ```
+
+    !!! info
+        The interface names will need to be adjusted based on your specific machine.
+
+=== "Option 2: Static network configuration"
+
+    Create a file called `agw_config.yaml` that contains the following content:
+
+    ``` yaml
+    ---
+    magma-access-gateway-operator:
+      sgi: enp0s1
+      sgi-ipv4-address: 192.168.0.2/24
+      sgi-ipv4-gateway: 192.168.0.1
+      sgi-ipv6-address: fd7d:3797:378b:a502::2/64
+      sgi-ipv6-gateway: fd7d:3797:378b:a502::1
+      s1: enp0s2
+      s1-ipv4-address: 192.168.1.2/24
+      s1-ipv6-address: fd7d:3797:378b:a503::2/64
+      dns: '["8.8.8.8", "208.67.222.222"]'
+    ```
+
+    !!! info
+        The interface names and IP addresses will need to be adjusted based on your specific machine.
+
+    Deploy Magma Access Gateway:
+
+    ```bash
+    juju deploy magma-access-gateway-operator --config agw_config.yaml --channel=1.8/stable --to <AGW machine ID>
+    ```
diff --git a/docs/docusaurus/versioned_docs/version-1.8.0/orc8r/deploy_using_juju.md b/docs/docusaurus/versioned_docs/version-1.8.0/orc8r/deploy_using_juju.md
@@ -7,11 +7,104 @@ original_id: deploy_using_juju
 
 # Deploy Orchestrator using Juju
 
-[Charmed Magma](https://canonical.github.io/charmed-magma/) doesn't support
-release 1.8 yet.
+This how-to guide can be used to deploy Magma's Orchestrator on any cloud environment. It contains
+steps to set up a Kubernetes cluster, bootstrap a Juju controller, deploy charmed operators for
+Magma Orchestrator and configure DNS A records. For more information on Charmed Magma, please visit
+the project's [homepage](https://canonical-charmed-magma.readthedocs-hosted.com/en/1.8/).
 
-To use officially released Charmed Magma 1.6, please refer to the
-[official Charmed Magma 1.6 docs](https://canonical.github.io/charmed-magma/1.6/).
+## Pre-requisites
 
-To try out the latest version of Charmed Magma please follow instructions
-from the [official docs](https://canonical.github.io/charmed-magma/main/).
+- A machine with internet access
+- A public domain
+
+## Set up your management environment
+
+From your machine, install the following tools:
+
+- [Juju 2.9](https://juju.is/docs/olm/installing-juju)
+- [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl-linux/)
+
+## Create a Kubernetes cluster and bootstrap a Juju controller
+
+Select a Kubernetes environment and follow the guide to create the cluster and bootstrap
+a Juju controller on it.
+
+1. [MicroK8s](https://juju.is/docs/olm/microk8s)
+2. [Google Cloud (GKE)](https://juju.is/docs/olm/google-kubernetes-engine-(gke))
+3. [Amazon Web Services (EKS)](https://juju.is/docs/olm/amazon-elastic-kubernetes-service-(amazon-eks)#heading--install-the-juju-client)
+4. [Microsoft Azure (AKS)](<https://juju.is/docs/olm/azure-kubernetes-service-(azure-aks)>)
+
+## Deploy charmed Magma Orchestrator
+
+From your machine, create an `overlay.yaml` file that contains the following content:
+
+```yaml
+applications:
+  fluentd:
+    options:
+      domain: <your domain name>
+      elasticsearch-url: <your elasticsearch https url>
+  orc8r-certifier:
+    options:
+      domain: <your domain name>
+  orc8r-eventd:
+    options:
+      elasticsearch-url: <your elasticsearch http url>
+  orc8r-nginx:
+    options:
+      domain: <your domain name>
+  tls-certificates-operator:
+    options:
+      generate-self-signed-certificates: true
+      ca-common-name: rootca.<your domain name>
+```
+
+> **Warning**: This configuration is unsecure because it uses self-signed certificates.
+
+Deploy Orchestrator:
+
+```bash
+juju deploy magma-orc8r --overlay overlay.yaml --channel=1.8/stable
+```
+
+The deployment is completed when all services are in the `Active-Idle` state.
+
+## Import the admin operator HTTPS certificate
+
+Retrieve the PFX package and password that contains the certificates to authenticate against Magma Orchestrator:
+
+```bash
+juju scp --container="magma-orc8r-certifier" orc8r-certifier/0:/var/opt/magma/certs/admin_operator.pfx admin_operator.pfx
+juju run-action orc8r-certifier/leader get-pfx-package-password --wait
+```
+
+> The pfx package was copied to your current working directory and can now be loaded in your browser.
+
+## Setup DNS
+
+Retrieve the services that need to be exposed:
+
+```bash
+juju run-action orc8r-orchestrator/leader get-load-balancer-services --wait
+```
+
+In your domain registrar, create A records for the following Kubernetes services:
+
+| Address                                | Hostname                                |
+|----------------------------------------|-----------------------------------------|
+| `<orc8r-bootstrap-nginx External IP>`  | `bootstrapper-controller.<your domain>` |
+| `<orc8r-nginx-proxy External IP>`      | `api.<your domain>`                     |
+| `<orc8r-clientcert-nginx External IP>` | `controller.<your domain>`              |
+| `<nginx-proxy External IP>`            | `*.nms.<your domain>`                   |
+| `<fluentd External IP>`                | `fluentd.<your domain>`                 |
+
+## Verify the deployment
+
+Get the host organization's username and password:
+
+```bash
+juju run-action nms-magmalte/leader get-host-admin-credentials --wait
+```
+
+Confirm successful deployment by visiting `https://host.nms.<your domain>` and logging in
+with the `admin-username` and `admin-password` outputted here.
diff --git a/...ed_docs/version-1.8.0/tutorials/00_private_mobile_network_with_charmed_magma.md b/...ed_docs/version-1.8.0/tutorials/00_private_mobile_network_with_charmed_magma.md
@@ -0,0 +1,35 @@
+---
+id: version-1.8.0-00_overview
+title: Overview
+hide_title: true
+original_id: 00_overview
+---
+
+# Operate your own private mobile network with Charmed Magma
+
+In this tutorial, we will use Juju to deploy and run Magma's 4G core network on AWS.
+We will also deploy a radio and cellphone simulator from the [srsRAN](https://www.srslte.com/)
+project to simulate usage of this network. You will need:
+
+- An AWS account[^1]
+- A public domain
+- A computer[^2] with the following software installed:
+    - [juju 2.9](https://juju.is/docs/olm/install-juju)
+    - [kubectl](https://kubernetes.io/docs/tasks/tools/)
+    - [aws cli](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)
+    - [eksctl](https://docs.aws.amazon.com/eks/latest/userguide/eksctl.html)
+
+## Table of contents
+
+1. [Getting Started](01_getting_started.md)
+2. [Deploying Magma Orchestrator](02_deploying_magma_orchestrator.md)
+3. [Deploying Magma Access Gateway](03_deploying_magma_access_gateway.md)
+4. [Integrating Magma Access Gateway with Magma Orchestrator](04_integrating_magma_access_gateway_with_magma_orchestrator.md)
+5. [Deploying the radio simulator](05_deploying_the_radio_simulator.md)
+6. [Simulating user traffic](06_simulating_user_traffic.md)
+7. [Destroying the environment](07_destroying_the_environment.md)
+
+[^1]: This tutorial uses AWS as the cloud provider. You can use any cloud provider
+that Juju supports. See [Juju Clouds](https://juju.is/docs/olm/juju-supported-clouds)
+for more information.
+[^2]: All the commands were tested from a Ubuntu 22.04 LTS machine.