From 507f0030851498bac112c2e777cf070aa5d5e376 Mon Sep 17 00:00:00 2001
From: Mark Beierl <mark.beierl@canonical.com>
Date: Wed, 24 Apr 2024 10:47:42 -0400
Subject: [PATCH] feat: Add gNB Integrator howto

---
 docs/.wordlist.txt                            |  2 +
 docs/how-to/index.md                          |  1 +
 .../integrate_sdcore_with_external_gnb.md     | 60 +++++++++++++++++++
 3 files changed, 63 insertions(+)
 create mode 100644 docs/how-to/integrate_sdcore_with_external_gnb.md

diff --git a/docs/.wordlist.txt b/docs/.wordlist.txt
index aea41aa..3265eee 100644
--- a/docs/.wordlist.txt
+++ b/docs/.wordlist.txt
@@ -52,6 +52,7 @@ icmp
 ICMP
 IMSI
 integrations
+integrator
 IOV
 juju
 Juju
@@ -112,6 +113,7 @@ sub-module
 subnet
 subnets
 systemd
+TAC
 TCP
 Terraform
 Terraform's
diff --git a/docs/how-to/index.md b/docs/how-to/index.md
index f054661..4508978 100644
--- a/docs/how-to/index.md
+++ b/docs/how-to/index.md
@@ -11,6 +11,7 @@ deploy_sdcore_standalone
 deploy_sdcore_cups
 deploy_sdcore_gnbsim
 integrate_sdcore_with_observability
+integrate_sdcore_with_external_gnb
 ```
 
 ## Day 2 operations
diff --git a/docs/how-to/integrate_sdcore_with_external_gnb.md b/docs/how-to/integrate_sdcore_with_external_gnb.md
new file mode 100644
index 0000000..339dd79
--- /dev/null
+++ b/docs/how-to/integrate_sdcore_with_external_gnb.md
@@ -0,0 +1,60 @@
+# Integrate SD-Core with an Externally Managed Radio
+
+For simplicity in managing deployments, the gNB Name and TAC can be supplied via a charm integration. This is the purpose of the sdcore-gnb-integrator charm.
+
+## Pre-requisites
+
+- A Kubernetes cluster capable of handling the load from both SD-Core and one additional container per represented gNB
+- [Charmed 5G Terraform modules][Charmed 5G Terraform modules] Git repository cloned onto the Juju host machine
+- Charmed 5g already deployed using Terraform
+
+You need to have the following information ready:
+
+- A name for the gNB
+- The name of the juju model for the gNB integrator
+- The TAC (represented in hex) that the gNB is serving
+- The name of the control plane model
+
+## Deploying gNB Integrator
+
+Given the following:
+
+- Model name: `gnb-integration`
+- GNB Name: `gnb01`
+- TAC: `B01F`
+- Control Plane Model: `control-plane`
+
+Either create a new `.tf` file, or add the following content to you existing `main.tf`.
+
+```console
+module "gnb01" {
+  app_name   = "gnb01"
+  source     = "git::https://github.com/canonical/sdcore-gnb-integrator//terraform"
+  model_name = "gnb-integration"
+  channel    = "1.4/edge"
+  config     = {
+    tac: B01F
+  }
+}
+
+resource "juju_offer" "gnb01-fiveg-gnb-identity" {
+  model            = "gnb-integration"
+  application_name = module.gnb01.app_name
+  endpoint         = module.gnb01.fiveg_gnb_identity_endpoint
+}
+
+resource "juju_integration" "nms-gnb01" {
+  model = "control-plane"
+
+  application {
+    name     = module.sdcore-control-plane.nms_app_name
+    endpoint = module.sdcore-control-plane.fiveg_gnb_identity_endpoint
+  }
+
+  application {
+    offer_url = juju_offer.gnb01-fiveg-gnb-identity.url
+  }
+}
+```
+
+[Charmed 5G Terraform modules]: https://github.com/canonical/terraform-juju-sdcore-k8s