Architecture

content/en/docs/architecture.md

@@ -0,0 +1,51 @@
+---
+title: "Nephio Architecture"
+type: docs
+weight: 5
+description: Reference for the Nephio Architecture
+---
+
+Some experiments on working with [C4 model](https://c4model.com/) to document Nephio.
+
+## Prerequisites
+1. [Graphviz](https://graphviz.org/download/) is required to render some of the diagrams in this document.
+
+## System Context View
+
+
+![System Context](/images/architecture/level1-nephio-system.png)
+
+The system context view gives a high level perspective of the Nephio software system and the external entities that it interacts with. There are no deployment considerations in this view - the main purpose of the picture is to depict what is the responsibility and scope of Nephio, and the key interfaces and capabilities it exposes to deliver on that responsibility.
+
+## System Landscape View
+
+![System Landscape](/images/architecture/level2-nephio-container.png)
+
+Nephio is an amalgamation of software systems, so a system landscape provides a high-level view of how those software systems interoperate.
+
+## Component Views
+
+### Nephio Core
+
+![Nephio Core Component View](/images/architecture/level3-nephio-core-component.png)
+
+Nephio core is a collection of operators and functions that perform the fundamental aspects of Nephio use cases, independent of the specifics of vendor implementations. 
+
+The controllers for OAI and Free5GC are represented here. Although they are vendor extensions to Nephio, they are for now part of the Nephio system.
+
+
+### Porch
+
+![Nephio Porch Component View](/images/architecture/nephio-porch-component-view.png)
+
+### ConfigSync
+
+TBD - is this a component of Nephio or a dependency?
+
+## Deployment View
+
+TBD
+
+## Representative Use Cases
+
+TBD - use cases between the major components

diagrams/src/level1-nephio-system.puml

@@ -0,0 +1,36 @@
+@startuml nephio-system
+!include  https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Context.puml
+
+' External actors
+
+Boundary(persons, "Personas"){
+    Person(desginer, "Designer", "Creates the Network Function packages")
+    Person(networkEng, "Network Engineer", "Implements and instantiates the Network Function")
+}
+Boundary(service_orchestrators, "Service Orchestration") {
+    System_Ext(core_service_orchestrator, "Core Service Orchestrator", "Core Domain service orchestrator" )
+    System_Ext(oran_service_orchestrator, "O-RAN Service Orchestrator (SMO)", "RAN domain service orchestrator")
+}
+System_Ext(cicd_system, "GitOps, CI/CD", "Verifies workloads and packages before onboarding to Nephio, or using Nephio as part of their operations")
+
+' Core Nephio function
+System(nephio, "Nephio", "Kubernetes-based cloud native automation system, supporting deployment and management of multi-vendor cloud infrastructure and network functions across large scale edge deployments")
+
+' Southbound dependencies
+System_Ext(supported_nfs, "Supported network functions", "Network functions supported by Nephio (currently free5gc and OAI, with other vendors implementing support independently)")
+Boundary(infrastructure, "Infrastructure") {
+    System_Ext(clouds, "Cloud Providers", "Providers of Kubernetes clusters, such as GCP / Openshift and local kind clusters")
+    System_Ext(network_fabric, "Network Fabric", "Data Center network fabric elements, such as Nokia SR Linux")
+}
+
+' Actor - nephio relationships
+Rel_D(persons, nephio, "Create Network Topology, K8s Cluster and Network Function Intent")
+Rel_D(service_orchestrators, nephio, "Generate Network Topology, K8s Cluster and Network Function Intent")
+Rel_R(cicd_system, nephio, "Reconcile, Integrate or Deploy external artifacts")
+
+' Nephio - managed entity relationships
+Rel_D(nephio, infrastructure, "Manage Network Topology and K8s Cluster Lifecycle (e.g. O2-IMS)")
+Rel_D(nephio, supported_nfs, "Manage Network Functions Lifecycle")
+Rel_D(supported_nfs, clouds, "Execute on cloud infrastructure")
+
+@enduml

diagrams/src/level2-nephio-container.puml

@@ -0,0 +1,62 @@
+@startuml nephio-container
+!include  https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml
+
+' External actors
+Person(admin, "Administrator", "Administrator of networks, cloud infrastructure or both")
+Boundary(service_orchestrators, "Service Orchestration") {
+    System_Ext(core_service_orchestrator, "Core Service Orchestrator", "Core Domain service orchestrator")
+    System_Ext(oran_service_orchestrator, "O-RAN Service Orchestrator (SMO)", "RAN domain service orchestrator")
+}
+Lay_R(admin, service_orchestrators)
+System_Ext(cicd_system, "GitOps, CI/CD", "Verifies workloads and packages before onboarding to Nephio, or using Nephio as part of their operations")
+
+System_Boundary(nephio, "Nephio") {
+    Container(web_ui, "Web UI", "Backstage-based web application providing Nephio Packages management via web browser")
+    Container(porch, "Porch", "kpt as a Service", "Package Orchestration Server is a K8s extension apiserver which manages the lifecycle of KRM configuration packages")
+    Container(nephio_core, "Nephio Core", "K8s Operators", "Responsible for handling different aspects of workload and cluster specialisation and actuation")
+    Container(K8s_api, "Kubernetes API Server", "K8s Control Plane", "A component of the Kubernetes control plane that exposes the Kubernetes API. The API server is the front end for the Kubernetes control plane")
+    Container_Ext(configsync, "Reconciliation Engine", "GitOps Engine", "GitOps service which lets administrators deploy configurations from a source of truth, with the flexibility to support one or many clusters in a hybrid or multi-cloud environment")
+    ContainerDb_Ext(gitrepomgr, "Git Repository Manager", "git", "System for hosting git repositories and supporting remote branch management and merging")
+    Container(network_function_controllers, "Network Function Controllers", "K8s Operators", "Manage the lifecycle of Network Functions; Nephio currently supports OAI Core and RAN, and Free5GC")
+}
+
+' Southbound dependencies
+System_Ext(supported_nfs, "Supported Network Functions", "Network functions supported by Nephio (currently free5gc and OAI, with other vendors implementing support independently)")
+Boundary(infrastructure, "Infrastructure") {
+    System_Ext(clouds, "Cloud Providers", "Providers of Kubernetes clusters, such as GCP / Openshift and local kind clusters")
+    System_Ext(network_fabric, "Network Fabric", "Data Center network fabric elements, such as Nokia SR Linux")
+}
+
+' Actor - nephio relationships
+Rel_D(admin, K8s_api, "Create Network Topology, K8s Cluster and Network Function Intent")
+Rel_D(admin, web_ui, "Manage Lifecycle of Nephio Blueprints and Packages")
+Rel_D(service_orchestrators, K8s_api, "Generate Network Topology, K8s Cluster and Network Function Intent")
+Rel_L(cicd_system, K8s_api, "Reconcile, Integrate or Deploy external artifacts")
+Lay_L(K8s_api, cicd_system)
+
+Rel_D(web_ui, K8s_api, "Use the K8s API to read/write Porch resources")
+
+' Porch relations
+BiRel_L(porch, K8s_api, "Manage PackagesVariants / PackageRevisions API")
+Rel_D(porch, gitrepomgr, "Lifecycle KRM packages")
+
+' ConfigSync relations
+Rel_L(configsync, gitrepomgr, "Reconcile K8s resources")
+Rel_U(configsync, K8s_api, "Apply K8s resources")
+
+' Nephio core relations
+BiRel_U(nephio_core, K8s_api, "Consume and Create K8s resources")
+BiRel_U(network_function_controllers, K8s_api, "Consume and Create K8s resources")
+Lay_L(network_function_controllers, configsync)
+Lay_L(nephio_core, network_function_controllers)
+
+
+' Nephio - managed entity relationships
+Rel_D(nephio_core, infrastructure, "Manage Network Topology and K8s Cluster Lifecycle (e.g. O2-IMS)")
+Rel_D(network_function_controllers, supported_nfs, "Manage Network Functions Lifecycle")
+
+
+' Workload relations
+Rel_D(supported_nfs, clouds, "Execute on cloud infrastructure")
+
+@enduml

diagrams/src/level3-nephio-core-component.puml

@@ -0,0 +1,74 @@
+@startuml nephio-core-component
+!include  https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Component.puml
+
+System_Boundary(nephio, "Nephio") {
+    ' Container(web_ui, "Web UI", "Backstage-based web application providing Nephio Packages management via web browser")
+    ' Container(porch, "Porch", "kpt as a Service", "Package Orchestration Server is a K8s extension apiserver which manages the lifecycle of KRM configuration packages")
+    Container(K8s_api, "Kubernetes API Server", "K8s Control Plane", "A component of the Kubernetes control plane that exposes the Kubernetes API. The API server is the front end for the Kubernetes control plane")
+    ' Container(configsync, "ConfigSync", "GitOps Engine", "GitOps service which lets administrators deploy configurations from a source of truth, with the flexibility to support one or many clusters in a hybrid or multi-cloud environment")
+    Container(gitrepomgr, "Git Repository Manager", "git", "System for hosting git repositories and supporting remote branch management and merging")
+    Container(network_function_controllers, "Network Function Controllers", "K8s Operators", "Manage the lifecycle of Network Functions; Nephio currently supports OAI Core and RAN, and Free5GC")
+
+    Container_Boundary(nephio_core, "Nephio Core") {
+
+        ContainerDb(inventory, "Inventory", "datastore", "inventory Network Configuration or Token")
+
+        Container_Boundary(nephio_core_api, "Nephio Core APIs") {
+            Component(workload_crd, "Workload", "CRD", "Defines NFConfigs, NFDeployments, and AMF UPF and SMF Network Functions")
+            ' Component(requirements_crd, "Requirements", "CRD", "Defines Capacities, DataNetworks, and Interfaces")
+            Component(infrastructure_crd, "Infrastructure", "CRD", "Defines Workload Cluster, Tokens, Repositories, Networks, and NetworkConfigs")
+            Component(inventory_crd, "Inventory", "CRD", "Defines Endpoints, Links, Nodes, and Targets")
+            Component(resources_crd, "Resources", "CRD", "Defines IPClaim, IPPrefix, NetworkInstances, VlanClaims, VlanIndices, and Vlans")
+            Component(config_crd, "Config", "CRD", "Defines Networks configuration")
+            ' Component(topology_crd, "Topology", "CRD", "Defines RawTopologies configuration")
+            ' Component(ref_crd, "Reference", "CRD", "Defines Config reference")
+        }
+
+        Container_Boundary(nephio_core_controllers, "Nephio Core Controllers") {
+            Component(cluster_controller, "K8S Cluster ", "K8s reconcilier", "Controller responsible for reconciling cluster definitions with running clusters")
+            Component(network_controller, "Network", "K8s reconcilier", "Controller responsible for reconciling Network attachment definitions")
+            Component(resource_backend, "Resource Backend", "K8s reconcilier")
+            Component(token, "Token", "K8s reconcilier", "Controller for handling security tokens")
+            Component(bootstrap_package, "Bootstrap Package", "K8s reconcilier", "Controller for bootstrapping onboarded packages")
+            Component(repository, "Repository", "K8s reconcilier", "Controller for reconciling repository definitions")
+        }
+    }
+}
+
+' Southbound dependencies
+System_Ext(supported_nfs, "Supported Network Functions", "Network functions supported by Nephio (currently free5gc and OAI, with other vendors implementing support independently)")
+Boundary(infrastructure, "Infrastructure") {
+    System_Ext(clouds, "Cloud Providers", "Providers of Kubernetes clusters, such as GCP / Openshift and local kind clusters")
+    System_Ext(network_fabric, "Network Fabric", "Data Center network fabric elements, such as Nokia SR Linux")
+}
+
+Lay_D(inventory, infrastructure)
+
+
+Rel_D(K8s_api, nephio_core_api, "Allow users to manage Custom Resource instances for the exposed Custom Resource Definitions")
+
+Rel_D(infrastructure_crd, cluster_controller, "Manage K8s Clusters")
+Rel_D(infrastructure_crd, token, "Manage Tokens")
+Rel_D(infrastructure_crd, repository, "Manage Repositories")
+Rel_D(infrastructure_crd, network_controller, "Manage Network Configurations")
+
+Rel_U(network_controller, config_crd, "Generate Network Function configuration")
+BiRel_D(resources_crd, resource_backend, "Manage resources assignement")
+BiRel_D(workload_crd, network_function_controllers, "Manage Network Function lifecycle")
+BiRel_D(workload_crd, network_controller, "Manage Network Function configuration")
+
+Rel_R(repository, gitrepomgr, "Manage Git repositories programatically")
+
+Rel_U(resource_backend, inventory_crd, "Generate inventory resources")
+Rel_D(resource_backend, inventory, "Create and manage IP and VLAN index, claim and assignement")
+Rel_D(token, inventory, "Create and manage Token used to authenticate against systems")
+Rel_D(network_controller, inventory, "Create and manage Network configuration")
+
+Rel_D(network_function_controllers, supported_nfs, "Manage Network Functions Lifecycle")
+
+Rel_D(supported_nfs, clouds, "Execute on cloud infrastructure")
+Rel_D(bootstrap_package, clouds, "Deploy initial kpt packages upon K8s Cluster creation")
+Rel_D(cluster_controller, clouds, "Create and Manage K8s Clusters")
+Rel_D(network_controller, network_fabric, "Provision the Network Fabric using OpenConfig")
+
+@enduml

diagrams/src/level3-nephio-porch-component.puml

@@ -0,0 +1,35 @@
+@startuml
+!include  https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Component.puml
+!include  https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Component.puml
+
+Person_Ext(admin, "Network administrator", "Administrator of networks, cloud infrastructure or both")
+System_Ext(ext_auto, "External Automation Systems", "Software systems responsible for automatically provisioning and managing networks, cloud infrastructure, or both")
+
+System_Boundary(nephio, "Nephio") {
+    System_Boundary(porch, "Porch") {
+        Component(packagevariant_controller, "PackageVariant Controller", "controller", "Controller responsible for reconciling package variants with what is in git")
+        Component(packagevariantset_controller, "PackageVariantSet Controller", "controller", "Controller responsible for reconciling package variants with what is in git")
+    }
+
+    System_Boundary(k8s_api, "Kubernetes API Server") {
+        Component(packagevariant_crds, "PackageVariant CRD", "Custom Resource Definition", "Custom resource representing package variants managed by Porch")
+        Component(packagevariantset_crds, "PackageVariantSet CRD", "Custom Resource Definition", "Custom resource representing package variant sets managed by Porch")
+    }
+        ContainerDb_Ext(gitrepo, "Git Repository Manager", "git", "System for hosting git repositories and supporting remote branch management and merging")
+}
+
+' Relationships with external users
+Rel_D(admin, packagevariant_crds, "Manage package variants")
+Rel_D(admin, packagevariantset_crds, "Manage package variant sets")
+Rel_D(ext_auto, packagevariant_crds, "Manage package variants")
+Rel_D(ext_auto, packagevariantset_crds, "Manage package variant sets")
+
+' Relationships between operators and CRDs
+Rel_U(packagevariant_controller, packagevariant_crds, "Reconcile PackageVariants")
+Rel_U(packagevariantset_controller, packagevariantset_crds, "Reconcile PackageVariantSets")
+
+' Porch relationships
+Rel_U(packagevariant_controller, gitrepo, "Reconcile Package Variants")
+Rel_U(packagevariantset_controller, gitrepo, "Reconcile Package Variant Sets")
+
+@enduml