Merge pull request #65 from canonical/dev-doc-consolidation

Consolidates documentation under the bundle's readme / charmhub page.
canonical · Jul 12, 2022 · a3278ee · a3278ee
2 parents 6d45245 + 6965327
commit a3278ee
Show file tree

Hide file tree

Showing 8 changed files with 61 additions and 404 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -5,14 +5,8 @@
 The charms and bundles in this repository are specifically developed for the 
 [magma](https://www.magmacore.org/) usecase.
 
-## Roadmap
-
-1. Charm Magma Orchestrator (microk8s)
-2. Charm Magma Access Gateway with MAAS (Bare metal)
-3. Charm Magma Federation Gateway (microk8s)
-4. Validate public cloud deployments (AWS, GCP and Azure)
-
 ## Code contributions
+
 If you want to propose a new feature, a bug fix or a documentation improvement:
 - Create a new branch from main.
 - Commit and push your changes to this branch.
@@ -24,6 +18,7 @@ Note that each component has its own `CONTRIBURING.md` file that will detail how
 deploy and publish this specific component. Please refer to that file.
 
 ## Continuous Integration
+
 On each code push and pull request made in Github, a series of validations are triggered through 
 Github actions:
 - Linting validation

diff --git a/LICENSE b/LICENSE
@@ -187,7 +187,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright [yyyy] [name of copyright owner]
+   Copyright 2022 Canonical Ltd.
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

diff --git a/README.md b/README.md
@@ -1,26 +1,15 @@
-<h1> Charmed Magma </h1>
-
-<h1>
-    <a href="https://www.magmacore.org/"><img src="https://raw.githubusercontent.com/magma/magma/master/docs/docusaurus/static/img/magma-logo-purple.svg" alt="Magma" width="550"></a>
-</h1>
+# Charmed Magma 
 
+<a href="https://www.magmacore.org/"><img src="https://raw.githubusercontent.com/magma/magma/master/docs/docusaurus/static/img/magma-logo-purple.svg" alt="Magma" width="550"></a>
 
 Magma is an open-source software platform that gives network operators a mobile core network 
-solution. Magma has three major components:
-1. Access Gateway
-2. Orchestrator
-3. Federation Gateway
+solution. For more information about Magma, visit the [official website](https://docs.magmacore.org).
 
-This project contains a set of Juju charms with the purpose of driving the lifecycle 
-management, configuration, integration and daily actions for Magma.
+Charmed Magma is the easiest way to deploy, configure, manage, integrate and drive daily actions for Magma.
+It consists of a set of Juju charms and bundles built using the [Charmed Operator Framework](https://juju.is/docs/sdk).
 
-### Useful links
+> Charmed-Magma is in Beta and is not yet production ready or feature complete.
 
-- [Magma documentation](https://docs.magmacore.org/docs/basics/introduction)
-- [Orchestrator documentation](https://docs.magmacore.org/docs/orc8r/architecture_overview)
-- [Charmed operator framework](https://juju.is/docs/sdk)
+## Usage
 
-## Deployment
-To deploy a specific component, please follow the directives located in the component's directory 
-README.md file. For example, to deploy Orchestrator, go to the `orchestrator-bundle` directory and
-read the `Installation guide` section.
+- [Deploy Charmed Magma Orchestrator using Juju](https://charmhub.io/magma-orc8r)
diff --git a/orchestrator-bundle/CONTRIBUTING.md b/orchestrator-bundle/CONTRIBUTING.md
@@ -75,49 +75,3 @@ Or you can also run the `deploy.sh` bash script (which does the exact same Juju
 ```bash
 ./deploy.sh
 ```
-
-## Publish
-
-### Specific Charm
-
-First `cd` into the charm directory. 
-
-- If the charm is new and not already registered, register it:
-```bash
-charmcraft register magma-orc8r-<charm-name>
-```
-
-- Upload the charm charmhub:
-```bash
-charmcraft upload magma-orc8r-<charm-name>_ubuntu-20.04-amd64.charm
-```
-
-- Upload the OCI image to charmhub:
-```bash
-charmcraft upload-resource magma-orc8r-<charm-name> magma-orc8r-<charm-name>-image --image=<oci-image>
-```
-
-- Release the charm:
-```bash
-charmcraft release magma-orc8r-<charm-name> --revision=1 --channel=edge --resource=magma-orc8r-<charm-name>-image:1
-```
-
-### Bundle
-To publish the bundle, `cd` to the `orc8r-bundle` directory.
-
-- Pack the bundle:
-```bash
-charmcraft pack
-```
-
-- Upload the bundle to charmhub:
-
-```bash
-charmcraft upload magma-orc8r.zip
-```
-
-- Release the bundle to charmhub:
-
-```bash
-charmcraft release magma-orc8r --revision=<revision number> --channel=edge
-```
diff --git a/orchestrator-bundle/documentation/how-to-guides/deploy_using_juju.md b/orchestrator-bundle/documentation/how-to-guides/deploy_using_juju.md
diff --git a/orchestrator-bundle/documentation/how-to-guides/integrate_with_elasticsearch.md b/orchestrator-bundle/documentation/how-to-guides/integrate_with_elasticsearch.md
diff --git a/orchestrator-bundle/orc8r-bundle/README.md b/orchestrator-bundle/orc8r-bundle/README.md
@@ -1,8 +1,6 @@
 # magma-orc8r
 
-## Overview
-
-Orchestrator is a Magma service that provides a simple and consistent way to
+Orchestrator is a Magma component that provides a simple and consistent way to
 configure and monitor the wireless network securely. The metrics acquired through the platform
 allows you to see the analytics and traffic flows of the wireless users through the Magma web UI.
 
@@ -11,11 +9,38 @@ and it has been tested with all major public cloud platforms.
 
 For more information about Magma, see the official documentation [here](https://magmacore.org/).
 
-## Usage
+## How-to: Deploy Charmed Magma Orchestrator 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://github.com/canonical/charmed-magma).
+
+### Pre-requisites
+
+- Ubuntu 20.04 machine with internet access
+- A public domain
+
+### 1. Set up your management environment
+
+From a Ubuntu 20.04 machine, install the following tools:
 
-### Deploy the bundle
+- [Juju](https://juju.is/docs/olm/installing-juju)
+- [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl-linux/)
 
-Create an `overlay.yaml` file that contains the following:
+### 2. 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)
+3. [Google Cloud (GKE)](https://juju.is/docs/olm/google-kubernetes-engine-(gke))
+4. [Amazon Web Services (EKS)](https://juju.is/docs/olm/amazon-elastic-kubernetes-service-(amazon-eks)#heading--install-the-juju-client)
+5. [Microsoft Azure (AKS)](<https://juju.is/docs/olm/azure-kubernetes-service-(azure-aks)>)
+
+### 3. Deploy charmed Magma Orchestrator
+
+From your Ubuntu machine, create an `overlay.yaml` file that contains the following content:
 
 ```yaml
 applications:
@@ -26,43 +51,37 @@ applications:
 
 Replace `<your domain name>` with your domain name.
 
-Deploy orchestrator:
+Deploy Orchestrator:
 
 ```bash
 juju deploy magma-orc8r --overlay overlay.yaml --trust --channel=edge
 ```
 
 The deployment is completed when all services are in the `Active-Idle` state.
 
-
-### Import the admin operator HTTPS certificate
+### 4. Import the admin operator HTTPS certificate
 
 Retrieve the self-signed certificate:
 
 ```bash
 juju scp --container="magma-orc8r-certifier" orc8r-certifier/0:/var/opt/magma/certs/..data/admin_operator.pfx admin_operator.pfx
 ```
 
-> The default password to open the admin_operator.pfx file is `password123`. To choose a different 
+> The default password to open the admin_operator.pfx file is `password123`. To choose a different
 > password, re-deploy orc8r-certifier with the `passphrase` juju config.
 
-### Create the orchestrator admin user
+### 5. Create the Orchestrator admin user
 
 Create the user:
 
 ```bash
 juju run-action orc8r-orchestrator/0 create-orchestrator-admin-user
 ```
 
-### Setup DNS
+### 6. Setup DNS
 
-Retrieve the services that need to be exposed:
-
-```bash
-kubectl get services -n <your model> | grep LoadBalancer
-```
-
-Note the addresses associated to the following services:
+Use `kubectl` or your cloud's CLI to retrieve the public addresses associated to the following Kubernetes
+LoadBalancer services:
 
 - `nginx-proxy`
 - `orc8r-bootstrap-nginx`
@@ -78,8 +97,7 @@ Create these A records in your managed domain:
 | `controller.<your domain>`              | `<orc8r-clientcert-nginx External IP>` |
 | `*.nms.<your domain>`                   | `<nginx-proxy External IP>`            |
 
-
-## Verify the deployment
+### 7. Verify the deployment
 
 Get the master organization's username and password:
 
@@ -89,3 +107,14 @@ juju run-action nms-magmalte/0 get-master-admin-credentials --wait
 
 Confirm successful deployment by visiting `https://master.nms.<your domain>` and logging in
 with the `admin-username` and `admin-password` outputted here.
+
+## How-to: Integrate Magma Orchestrator with elasticsearch
+
+From the same environment where orchestrator was deployed, run:
+```bash
+juju config orc8r-eventd elasticsearch-url=<elasticsearch url>:<elasticsearch port>
+juju config orc8r-orchestrator elasticsearch-url=<elasticsearch url>:<elasticsearch port>
+```
+
+Where `<elasticsearch url>` and `<elasticsearch port>` are your elasticsearch instance's url and port.
+This address must be accessible from the environment where orchestrator is installed.