Skip to content

Commit 246ad2d

Browse files
JoseMCondeJoseMConde
authored
Merge pull request #395 from ALIIQBAL786/ALIIQBAL786-EdgeCloud-Intents-doc
Add EdgeCloud Intents and API Mapping document
2 parents 1d03f10 + 19a32ba commit 246ad2d

2 files changed

Lines changed: 185 additions & 1 deletion

File tree

documentation/SupportingDocuments/API_Documentation/User Stories/Edge.Cloud.Lifecycle.Management.User.Story.md renamed to documentation/API_documentation/User Stories/Edge.Application.Management.User.Story.md

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11

2-
Edge Cloud Lifecycle Management User Story
2+
Edge Application Management User Story
33
_This document is based on the [CAMARA Commonalities template for User Stories](https://github.com/camaraproject/Commonalities/blob/main/documentation/Userstory-template.md)_
44
_Roles are referenced from the ITU-T Cloud Refence Architecture._
55

@@ -80,3 +80,4 @@ sequenceDiagram
8080

8181

8282

83+

‎documentation/SupportingDocuments/EdgeCloud-Intents-and-API-Mapping-Harmonisation.md‎

Lines changed: 183 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,183 @@
1+
# Edge Cloud Intents and API Mapping – Harmonisation Document
2+
3+
_This document is based on the [CAMARA Commonalities template for User Stories](https://github.com/camaraproject/Commonalities/blob/main/documentation/Userstory-template.md) and references ITU-T Cloud Reference Architecture roles._
4+
5+
---
6+
7+
## 1. Summary
8+
9+
This document provides a harmonised view of **EdgeCloud Intents** and their corresponding **CAMARA APIs**, consolidating the functional flow across discovery, deployment, runtime, and termination stages of the **Edge Cloud lifecycle**.
10+
11+
The purpose is to bridge earlier MEC & Deployment API proposals with the current **CAMARA Edge Cloud family of APIs**, ensuring a unified lifecycle from **Zone discovery** to **Application endpoint registration and discovery**.
12+
13+
---
14+
15+
## 2. Objectives
16+
17+
- To define the **intents** supporting the lifecycle of Edge-hosted applications.
18+
- To map these intents to existing and emerging **CAMARA APIs**.
19+
- To support interoperability between **Operator Platforms** and **Application Providers**.
20+
- To prepare the foundation for future harmonisation across **Edge, Application Management, and Network APIs** (e.g., Traffic Influence).
21+
22+
---
23+
24+
## 3. Roles, Actors, and Scope
25+
26+
| Actor | Role | Scope |
27+
|-------|------|-------|
28+
| Application Provider (AP) | API Consumer | API requester, deploys applications and manages instances. |
29+
| Operator Platform (OP) | Edge Cloud Provider | API publisher, orchestrates resources and exposes APIs. |
30+
| Edge Infrastructure Provider (EIP) | Edge Cloud Provider | Hosts and manages the physical/virtual infrastructure. |
31+
| End User (UE) | Service Consumer | Interacts with applications hosted at the edge. |
32+
33+
> Note: Edge Cloud Provider may be the Operator or a Hyperscaler.
34+
35+
---
36+
37+
## 4. EdgeCloud Lifecycle Intents Overview
38+
39+
| **Intent ID** | **Intent Name** | **Purpose / Description** | **Mapped CAMARA API / Status** |
40+
|---------------|----------------|----------------------------|--------------------------------|
41+
| **Intent 1** | Discover EdgeCloud Zones | Discover the closest Edge Cloud Zone to a user device based purely on network topology (shortest network path). | `Simple Edge Discovery API` |
42+
| **Intent 2** | List Available Regions / Capabilities | Discover the best Edge Cloud Zone for an application, considering compute, storage, and network performance requirements beyond distance. | Planned extension of Optimal Edge Discovery |
43+
| **Intent 3** | Retrieve Zone Information | Obtain metadata, KPIs, and current resource availability of a specific Edge Cloud Zone. | `Simple Edge Discovery API` |
44+
| **Intent 4** | Filter / Select Preferred Zones | Apply filters (latency, region) for optimal zone selection. | Planned enhancement within Optimal Edge Discovery |
45+
| **Intent 5** | Register / Onboard Application | Upload manifests, metadata, and container images. | `Edge Cloud Lifecycle Management API` |
46+
| **Intent 6** | Validate Application Metadata | Validate manifests and dependencies before deployment. | Partially covered by Lifecycle Management |
47+
| **Intent 7** | Instantiate Application | Deploy application instances in selected Edge Zones. | `Edge Cloud Lifecycle Management API` |
48+
| **Intent 8** | Scale Application Instance | Adjust resources dynamically (horizontal/vertical). | Future – EdgeCloud Scaling API (proposed) |
49+
| **Intent 9** | Register Application Endpoints | Register deployed app endpoints (URLs, ports, zones). | `Application Endpoint Registration API` |
50+
| **Intent 10** | Update Endpoint Metadata | Modify endpoint details (status, performance). | Within `Application Endpoint Registration API` |
51+
| **Intent 11** | Discover Optimal Application Endpoints | Find best endpoint for a device based on latency or policy. | `Application Endpoint Discovery API` |
52+
| **Intent 12** | Client-Side Endpoint Selection | Allow clients to select among multiple available endpoints. | Optional behaviour of Endpoint Discovery |
53+
| **Intent 13** | Influence Network Traffic | Apply routing rules for premium users or optimisation. | `Traffic Influence API` |
54+
| **Intent 14** | Configure Network Policies | Manage slicing/routing preferences for traffic flows. | Evolution of Traffic Influence |
55+
| **Intent 15** | Monitor Application Performance | Retrieve runtime telemetry: latency, usage, etc. | SessionInsights API |
56+
| **Intent 16** | Retrieve Edge Metrics / Zone Health | Query Edge Zone health and operational metrics. | Under discussion – EdgeCloud Monitoring API |
57+
| **Intent 17** | Automate Policy or Scaling Actions | Enable closed-loop orchestration and scaling triggers. | Future – Edge Orchestration Intent API |
58+
| **Intent 18** | Terminate Application | Decommission instances and release resources. | `Edge Cloud Lifecycle Management API` |
59+
| **Intent 19** | Deregister Application Endpoints | Remove obsolete endpoints from registry. | `Application Endpoint Registration API` |
60+
| **Intent 20** | Audit and Logging | Track API operations, logs, and service usage. | Commonalities Cross-API Logging proposal |
61+
| **Intent 21** | Federated Edge Discovery | Discover edge zones from partner operators/hyperscalers. | Proposed – Edge Federation Discovery API |
62+
| **Intent 22** | Cross-Operator Application Placement | Deploy app instances across federated networks. | Future CAMARA/GSMA initiative |
63+
| **Intent 23** | Consent and Policy Management | Manage end-user consent during discovery/exposure. | Privacy & Consent WG |
64+
| **Intent 24** | Service Quality Enforcement | Apply QoS constraints dynamically per application. | Future – Edge QoS Policy API |
65+
| **Intent 25** | Edge Resource Reservation / Pre-Booking | Reserve compute/storage/network capacity pre-deployment. | Proposed – Edge Reservation API |
66+
67+
---
68+
69+
70+
## 5. Harmonised EdgeCloud Lifecycle Flow
71+
72+
```mermaid
73+
flowchart LR
74+
A[Intent 1: Discover Edge Zones] --> B[Intent 3: Retrieve Zone Info]
75+
B --> C[Intent 5: Register Application]
76+
C --> D[Intent 7: Instantiate Application]
77+
D --> E[Intent 9: Register Application Endpoints]
78+
E --> F[Intent 11: Discover Optimal Endpoints]
79+
F --> G[Intent 13: Apply Traffic Influence - optional]
80+
G --> H[Intent 18: Terminate Application]
81+
```
82+
```mermaid
83+
sequenceDiagram
84+
participant AP as Application Provider
85+
participant OP as Operator Platform
86+
participant EIP as Edge Infrastructure Provider
87+
participant UE as User Equipment
88+
participant AF as Application Function
89+
90+
Note over AP,OP: Phase 1 - Discovery
91+
AP->>OP: POST /discover-optimal-edge-zones
92+
OP-->>AP: EdgeCloudZone list ordered by proximity
93+
94+
Note over AP,OP: Phase 2 - Provisioning & Deployment
95+
AP->>OP: POST /applications (Onboard Application)
96+
OP-->>AP: Returns appId
97+
AP->>OP: POST /applications/{appId}/instances
98+
OP->>EIP: Instantiate app in target Edge Zone
99+
EIP-->>OP: Instance ready
100+
OP-->>AP: appInstanceId + status "RUNNING"
101+
102+
Note over AP,OP: Phase 3 - Endpoint Management
103+
AP->>OP: POST /register (Application Endpoint)
104+
OP-->>AP: endpointId confirmation
105+
106+
Note over UE,OP: Phase 4 - Runtime & Discovery
107+
UE->>OP: POST /retrieve-optimal-app-endpoints {appId, device}
108+
OP-->>UE: Returns optimal endpoint (EdgeCloudZoneId, endpointURL)
109+
110+
Note over AF,OP: Phase 5 - Network Optimisation
111+
AF->>OP: POST /traffic-influence (toward EAS)
112+
OP-->>AF: Returns routing configuration ID
113+
UE->>EIP: Connect to optimal EAS endpoint
114+
```
115+
# CAMARA EdgeCloud Harmonisation Analysis
116+
117+
## 7. Harmonisation Analysis
118+
119+
### 7.1 API Relationship Summary
120+
121+
- **Simple Edge Discovery**: Provides baseline nearest-zone discovery using network proximity.
122+
- **Optimal Edge Discovery**: Extends discovery with richer metadata (zone characteristics, latency, region).
123+
- **Edge Application Management**: Enables deployment and lifecycle control of applications in these zones.
124+
- **Application Endpoint Registration**: Establishes registry of deployed endpoints.
125+
- **Application Endpoint Discovery**: Allows clients or servers to dynamically retrieve optimal endpoints.
126+
- **Traffic Influence**: Complements discovery and lifecycle by providing routing enforcement at the network level.
127+
128+
### 7.2 Common Design Principles
129+
130+
- **Entity Alignment**: Shared objects (e.g., `edgeCloudZoneId`, `appId`, `endpointId`) across all APIs.
131+
- **Security Consistency**: All APIs assume OAuth2-based access with clear roles.
132+
- **Consent Integration**: Optional per API (explicit in Discovery and Endpoint APIs).
133+
- **Operator Neutrality**: APIs work across multiple operators via federated exposure models.
134+
135+
**Conclusion**: CAMARA EdgeCloud APIs collectively address all intents from earlier MEC proposals, forming a continuous lifecycle from discovery → provisioning → runtime → termination.
136+
137+
## 8. Harmonised Data Model Overview
138+
139+
| Entity | Description | Referenced In |
140+
|--------|-------------|---------------|
141+
| `edgeCloudZoneId` | Identifier of Edge Cloud Zone | Discovery, Lifecycle, Endpoint APIs |
142+
| `appId` | Unique application identifier | Lifecycle, Endpoint Discovery |
143+
| `appInstanceId` | Deployed instance ID | Lifecycle API |
144+
| `endpointId` | Registered endpoint for a deployed instance | Endpoint Registration & Discovery |
145+
| `deviceId` | Device identifier or token | Discovery and Endpoint Discovery APIs |
146+
| `trafficInfluenceId` | Identifier for a network routing session | Traffic Influence API |
147+
148+
## 9. Inter-API Dependencies
149+
150+
| API | Depends On | Dependency Description |
151+
|-----|------------|------------------------|
152+
| Simple Edge Discovery | None | Can be used standalone for planning |
153+
| Optimal Edge Discovery | None | Can be used standalone for planning |
154+
| Edge Application Management | Optimal Edge Discovery | Uses discovered zones for deployment decisions |
155+
| Application Endpoint Registration | Edge Cloud Lifecycle Management | Registers endpoints of instantiated applications |
156+
| Application Endpoint Discovery | Endpoint Registration | Discovers registered endpoints |
157+
| Traffic Influence | Endpoint Discovery | Optimises routing to discovered endpoints |
158+
159+
**Harmonised APIs together enable a complete closed loop**:
160+
Discovery → Deployment → Registration → Discovery (endpoint) → Influence → Termination.
161+
162+
## 10. Open Harmonisation Topics
163+
164+
| Area | Description | Next Step |
165+
|------|-------------|-----------|
166+
| Unified Discovery Schema | Align Simple and Optimal Edge Discovery response objects | Define a shared `EdgeCloudZoneInfo` schema |
167+
| Cross-API Security Scopes | Establish unified OAuth2 roles and scopes | Coordinate with Commonalities WG |
168+
| Consent Management | Define consistent consent-handling process across Discovery and Endpoint APIs | Align with Privacy & Consent WG |
169+
| Federated Operations | Support discovery and lifecycle across multi-operator environments | Introduce Edge Federation API concept |
170+
| Traffic Policy Automation | Enable dynamic network steering based on real-time metrics | Collaborate with Network API group |
171+
172+
## 11. References
173+
174+
- **CAMARA – Simple Edge Discovery API**: [User Story](https://github.com/camaraproject/SimpleEdgeDiscovery/blob/main/documentation/API_documentation/SimpleEdgeDiscovery_User_Story.md)
175+
- **CAMARA – Optimal Edge Discovery API**: [User Story](https://github.com/camaraproject/OptimalEdgeDiscovery/blob/main/documentation/API_documentation/optimal-edge-discovery-User-Story.md)
176+
- **CAMARA – Edge Application Management**: [User Story](https://github.com/camaraproject/EdgeCloud/blob/main/documentation/SupportingDocuments/API_Documentation/User%20Stories/Edge.Cloud.Lifecycle.Management.User.Story.md)
177+
- **CAMARA – Application Endpoint Registration API**: [User Story](https://github.com/camaraproject/ApplicationEndpointRegistration/blob/main/documentation/API_documentation/application-endpoint-registration-User-Story.md)
178+
- **CAMARA – Application Endpoint Discovery API**: [User Story](https://github.com/camaraproject/ApplicationEndpointDiscovery/blob/main/documentation/SupportingDocuments/API_Documentation/User%20Stories/Application%20Endpoint%20Discovery%20User%20Story.md)
179+
- **CAMARA – Traffic Influence API**: [User Story](https://github.com/camaraproject/TrafficInfluence/blob/main/documentation/API_documentation/traffic-influence-user-story-use-case-1.md)
180+
- **GSMA – Open Gateway & CAMARA Harmonisation Framework**: [Reference](https://www.hcltech.com/sites/default/files/documents/resources/whitepaper/files/2024/09/16/gsma-open-gateway.pdf?utm_source=chatgpt.com)
181+
182+
183+

0 commit comments

Comments
 (0)