feat: add the fiveg_core_gnb interface (#194)

* feat: add the fiveg_core_gnb interface Signed-off-by: Dario Faccin <[email protected]> * fix: use correct names for provider and requirer app data classes Signed-off-by: Dario Faccin <[email protected]> * chore: update relation according to new spec Signed-off-by: Dario Faccin <[email protected]> * fix: use List from typing to avoid TypeError Signed-off-by: Dario Faccin <[email protected]> * chore: address review comments Signed-off-by: Dario Faccin <[email protected]> * chore: improve schema Signed-off-by: Dario Faccin <[email protected]> * fix: make Slice Differentiator optional Signed-off-by: Dario Faccin <[email protected]> --------- Signed-off-by: Dario Faccin <[email protected]>
canonical · Nov 26, 2024 · 85ecb9f · 85ecb9f
1 parent 733001b
commit 85ecb9f
Show file tree

Hide file tree

Showing 5 changed files with 338 additions and 0 deletions.
diff --git a/docs/json_schemas/fiveg_core_gnb/v0/provider.json b/docs/json_schemas/fiveg_core_gnb/v0/provider.json
@@ -0,0 +1,122 @@
+{
+  "$defs": {
+    "BaseModel": {
+      "properties": {},
+      "title": "BaseModel",
+      "type": "object"
+    },
+    "FivegCoreGnbProviderAppData": {
+      "properties": {
+        "tac": {
+          "description": "Tracking Area Code",
+          "examples": [
+            1
+          ],
+          "maximum": 16777215,
+          "minimum": 1,
+          "title": "Tac",
+          "type": "integer"
+        },
+        "plmns": {
+          "items": {
+            "$ref": "#/$defs/PLMNConfig"
+          },
+          "title": "Plmns",
+          "type": "array"
+        }
+      },
+      "required": [
+        "tac",
+        "plmns"
+      ],
+      "title": "FivegCoreGnbProviderAppData",
+      "type": "object"
+    },
+    "PLMNConfig": {
+      "properties": {
+        "mcc": {
+          "description": "Mobile Country Code",
+          "examples": [
+            "001",
+            "208",
+            "302"
+          ],
+          "pattern": "[0-9][0-9][0-9]",
+          "title": "Mcc",
+          "type": "string"
+        },
+        "mnc": {
+          "description": "Mobile Network Code",
+          "examples": [
+            "01",
+            "001",
+            "999"
+          ],
+          "pattern": "[0-9][0-9][0-9]?",
+          "title": "Mnc",
+          "type": "string"
+        },
+        "sst": {
+          "description": "Slice/Service Type",
+          "examples": [
+            1,
+            2,
+            3,
+            4
+          ],
+          "maximum": 255,
+          "minimum": 0,
+          "title": "Sst",
+          "type": "integer"
+        },
+        "sd": {
+          "anyOf": [
+            {
+              "maximum": 16777215,
+              "minimum": 0,
+              "type": "integer"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Slice Differentiator",
+          "examples": [
+            1
+          ],
+          "title": "Sd"
+        }
+      },
+      "required": [
+        "mcc",
+        "mnc",
+        "sst"
+      ],
+      "title": "PLMNConfig",
+      "type": "object"
+    }
+  },
+  "description": "The schema for the provider side of the fiveg_core_gnb interface.",
+  "properties": {
+    "unit": {
+      "anyOf": [
+        {
+          "$ref": "#/$defs/BaseModel"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "default": null
+    },
+    "app": {
+      "$ref": "#/$defs/FivegCoreGnbProviderAppData"
+    }
+  },
+  "required": [
+    "app"
+  ],
+  "title": "ProviderSchema",
+  "type": "object"
+}
diff --git a/docs/json_schemas/fiveg_core_gnb/v0/requirer.json b/docs/json_schemas/fiveg_core_gnb/v0/requirer.json
@@ -0,0 +1,48 @@
+{
+  "$defs": {
+    "BaseModel": {
+      "properties": {},
+      "title": "BaseModel",
+      "type": "object"
+    },
+    "FivegCoreGnbRequirerAppData": {
+      "properties": {
+        "cu_name": {
+          "description": "Unique identifier of the CU/gnB.",
+          "examples": [
+            "gnb001"
+          ],
+          "title": "Cu Name",
+          "type": "string"
+        }
+      },
+      "required": [
+        "cu_name"
+      ],
+      "title": "FivegCoreGnbRequirerAppData",
+      "type": "object"
+    }
+  },
+  "description": "The schema for the requirer side of the fiveg_core_gnb interface.",
+  "properties": {
+    "unit": {
+      "anyOf": [
+        {
+          "$ref": "#/$defs/BaseModel"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "default": null
+    },
+    "app": {
+      "$ref": "#/$defs/FivegCoreGnbRequirerAppData"
+    }
+  },
+  "required": [
+    "app"
+  ],
+  "title": "RequirerSchema",
+  "type": "object"
+}
diff --git a/interfaces/fiveg_core_gnb/v0/README.md b/interfaces/fiveg_core_gnb/v0/README.md
@@ -0,0 +1,67 @@
+# `fiveg_core_gnb`
+
+## Usage
+
+Within 5G, the CU is the Central Unit of a RAN (Radio Access Network) and needs to be configured according to the 5G network parameters.
+
+The `fiveg_core_gnb` relation interface describes the expected behavior of any charm claiming to be able to provide or consume the CU (or gNodeB) configuration information.
+
+In a typical 5G network, the provider of this interface would be a CU or a gNodeB. The requirer of this interface would be the NMS (Network Management System).
+
+## Direction
+
+```mermaid
+flowchart TD
+    Provider -- MCC, MNC, TAC, SST, SD --> Requirer
+    Requirer -- CU/gNodeB Identifier --> Provider
+```
+
+As with all Juju relations, the `fiveg_core_gnb` interface consists of two parties: a Provider and a Requirer.
+
+## Behavior
+
+Both the Requirer and the Provider need to adhere to criteria to be considered compatible with the interface.
+
+### Provider
+
+- Is expected to provide the following data:
+  - TAC (Tracking Area Code)
+  - List of PLMNs
+
+The list of PLMNs should include the following data:
+  - MCC (Mobile Country Code)
+  - MNC (Mobile Network Code)
+  - SST (Slice Service Type)
+  - SD (Slice Differentiator)
+
+
+### Requirer
+
+- Is expected to provide a unique identifier of the CU (or gNodeB).
+
+## Relation Data
+
+[\[Pydantic Schema\]](./schema.py)
+
+#### Example
+
+```yaml
+provider:
+  app: {
+    "tac": 1,
+    "plmns": [
+      {
+        "mcc": "001",
+        "mnc": "01",
+        "sst": 1,
+        "sd": 1,
+      }
+    ],
+  }
+  unit: {}
+requirer:
+  app: {
+    "cu_name": "gnb001"
+  }
+  unit: {}
+```
diff --git a/interfaces/fiveg_core_gnb/v0/interface.yaml b/interfaces/fiveg_core_gnb/v0/interface.yaml
@@ -0,0 +1,14 @@
+name: fiveg_core_gnb
+internal: true
+
+version: 0
+status: draft
+
+providers:
+  - name: sdcore-nms-k8s-operator
+    url: https://github.com/canonical/sdcore-nms-k8s-operator
+requirers:
+  - name: sdcore-gnbsim-k8s-operator
+    url: https://github.com/canonical/sdcore-gnbsim-k8s-operator
+
+maintainer: telco
diff --git a/interfaces/fiveg_core_gnb/v0/schema.py b/interfaces/fiveg_core_gnb/v0/schema.py
@@ -0,0 +1,87 @@
+"""This file defines the schemas for the provider and requirer sides of the `fiveg_core_gnb` relation interface.
+
+It must expose two interfaces.schema_base.DataBagSchema subclasses called:
+- ProviderSchema
+- RequirerSchema
+
+Examples:
+    ProviderSchema:
+        unit: <empty>
+        app: {
+            "tac": 1,
+            "plmns": [
+                {
+                    "mcc": "001",
+                    "mnc": "01",
+                    "sst": 1,
+                    "sd": 1,
+                }
+            ],
+        }
+    RequirerSchema:
+        unit: <empty>
+        app: {
+            "cu_name": "gnb001",
+        }
+"""
+
+from dataclasses import dataclass
+from interface_tester.schema_base import DataBagSchema
+from pydantic import BaseModel, Field
+from typing import List, Optional
+
+
+@dataclass
+class PLMNConfig:
+    """Dataclass representing the configuration for a PLMN."""
+
+    mcc: str = Field(
+        description="Mobile Country Code",
+        examples=["001", "208", "302"],
+        pattern=r"[0-9][0-9][0-9]",
+    )
+    mnc: str = Field(
+        description="Mobile Network Code",
+        examples=["01", "001", "999"],
+        pattern=r"[0-9][0-9][0-9]?",
+    )
+    sst: int = Field(
+        description="Slice/Service Type",
+        examples=[1, 2, 3, 4],
+        ge=0,
+        le=255,
+    )
+    sd: Optional[int] = Field(
+        description="Slice Differentiator",
+        default=None,
+        examples=[1],
+        ge=0,
+        le=16777215,
+    )
+
+
+class FivegCoreGnbProviderAppData(BaseModel):
+    tac: int = Field(
+        description="Tracking Area Code",
+        examples=[1],
+        ge=1,
+        le=16777215,
+    )
+    plmns: List[PLMNConfig]
+
+
+class FivegCoreGnbRequirerAppData(BaseModel):
+    cu_name: str = Field(
+        description="Unique identifier of the CU/gnB.",
+        examples=["gnb001"]
+    )
+
+
+class ProviderSchema(DataBagSchema):
+    """The schema for the provider side of the fiveg_core_gnb interface."""
+    app: FivegCoreGnbProviderAppData
+
+
+class RequirerSchema(DataBagSchema):
+    """The schema for the requirer side of the fiveg_core_gnb interface."""
+    app: FivegCoreGnbRequirerAppData