Commit c74bab66 authored by Dimitrios Gogos's avatar Dimitrios Gogos
Browse files

docs: enhance descriptions in app deployment and registration flow documents for clarity

parent dfc2fe5f

oeg/app-deployment-flow.md

+108 −13
Changes for oeg/app-deployment-flow.md: 108 added lines, 13 removed lines.
Original line number Diff line number Diff line 
---

type: Topic Reference

title: "OEG Internal Model — Multi-Zone App Deployment Flow"

description: "Topic links into the OEG Release 2.0 specification."

title: "OEG — Multi-Zone App Deployment Flow"

description: "How OEG deploys one app to several zones as a single deployment, tracks each instance, handles partial failure, and where the full detail lives."

tags: [oeg, flow, deployment]

timestamp: 2026-10-22T00:00:00Z

component: Open Exposure Gateway (OEG)
@@ -9,34 +9,129 @@ version: "2.0" 
status: "OOP Release 2.0 — topic reference"

---



# OEG Internal Model — Multi-Zone App Deployment Flow

# OEG — Multi-Zone App Deployment Flow



Read the [four-part specification](index.md) in order. The links below lead to the authoritative requirements, payloads and operational guidance for this topic.

**Companion documents:**

[oeg/requirements-and-design.md](/oeg/requirements-and-design.md),

[oeg/interface-contract.md](/oeg/interface-contract.md)



**Closest neighbours:**

[oeg/app-instance-flow.md](/oeg/app-instance-flow.md),

[ADR-0005](/decisions/0005-appinstance-identity-and-multiplicity.md),

[ADR-0012](/decisions/0012-multi-target-runtime-schema.md)



This page explains the flow in plain terms. The four-part [OEG specification](/oeg/index.md)

is authoritative; the last section points to the parts that own each detail.



---



<a id="overview"></a>

<a id="inbound-path--request-multi-zone-deployment"></a>

<a id="3-request-flow"></a>



[J.3 Multi-Zone Deployment](requirements-and-design.md#j3-multi-zone-deployment).

## Mental Model



**A deployment is one app in many zones.** It groups 1–100 instances under one

`appDeploymentId`. It works like the [single-zone flow](/oeg/app-instance-flow.md), except that

one command carries N targets.



**Grouped, not atomic.** Some zones can succeed while others fail. OEG reports that honestly;

it does not roll the others back.



**Only OEG knows the grouping.** SRM never sees `appDeploymentId`. It fulfils each target under

one shared operation.



```text

 App provider          OEG                           DataBus / SRM

      | POST /deployments  |                               |

      | (zones A, B, C)    |                               |

      |------------------->| mint deployment, operation    |

      |                    | and 3 instance ids; commit    |

      |                    | command.srm.service.deploy    |

      |                    | (3 targets)                   |

      |                    |------------------------------>| SRM deploys each target

      |<-------------------| 202 {appDeploymentId}         |

      |                    |                               |

      |                    | event.srm.operation.completed |

      |                    |<------------------------------| one outcome per instance

      |                    | update instances and rollup   |

      |<-------------------| callback: one event per instance

```



---



## Steps



1. The client posts `/deployments` with the app and its zones. Cluster pins and a callback are

   optional.

2. OEG mints one deployment id, one operation id and one instance id per zone. It commits them,

   the `instantiating` rows and the command together.

3. OEG publishes one deploy command with N targets.

4. After the broker acknowledges it, OEG answers 202 with **only** `appDeploymentId`.

5. The client finds the instance ids with `GET /deployments?appDeploymentId=...` or from the

   callbacks.



The same commit-and-publish gap as the single-zone flow applies

([design §M.2](/oeg/requirements-and-design.md#m2-commit-and-publish-boundary)).



---



<a id="1-nbi-northbound-interface-endpoint"></a>

<a id="2-camara-request-payload"></a>

<a id="4-databus-message--commandenvelopev1--srmservicedeployv1"></a>

<a id="5-202-response--post-deployments"></a>

<a id="completion-path"></a>

<a id="1-trigger"></a>

<a id="2-eventsrmoperationcompleted-multi-instance"></a>

<a id="3-oeg_db-updates"></a>



## Completion



SRM reports every target in one completion event. OEG updates each instance it created at

request time, then the deployment.



| Outcome | Operation status | Deployment state |

|---|---|---|

| Every zone succeeds | `COMPLETED` | `ready` |

| Some zones fail | `PARTIALLY_COMPLETED` | `partial` |

| The whole operation fails | `FAILED` | `failed`, with every instance failed |



Instances that succeeded stay in place after a partial failure. Whether they should be rolled

back is open (OQ-D3).



---



<a id="read--lifecycle"></a>

<a id="get-deployments-optionally-appid--appdeploymentid--appdeploymentinfo"></a>

<a id="patch-deploymentsappdeploymentid-json-merge-patch"></a>

<a id="delete-deploymentsappdeploymentid"></a>



[8. Multi-Zone Deployment](interface-contract.md#8-multi-zone-deployment).

## Read, change and delete



<a id="delete-deploymentsappdeploymentid"></a>

| Call | Does |

|---|---|

| `GET /deployments` | Lists deployments with their zones and instance ids; filter by `appId` or `appDeploymentId` |

| `PATCH /deployments/{appDeploymentId}` | Meant to replace the zone list. Answers 501 until OQ-D2 decides how changes map to operations |

| `DELETE /deployments/{appDeploymentId}` | Marks the deployment and its instances `terminating` and sends one terminate command per instance. Rows stay, as `terminated`. If nothing is left to tear down, OEG can settle it at once |



Selected code matches cluster pins to zones by position. The matching rule is still open

(OQ-D1).



---



## Where the details live



| Topic | Section |

|---|---|

| Acceptance steps and partial failure | [Design §J.3](/oeg/requirements-and-design.md#j3-multi-zone-deployment) |

| Deployment termination | [Design §J.4](/oeg/requirements-and-design.md#j4-termination) |



<a id="1-nbi-northbound-interface-endpoint"></a>

<a id="2-camara-request-payload"></a>

<a id="4-databus-message--commandenvelopev1--srmservicedeployv1"></a>

<a id="5-202-response--post-deployments"></a>



[J.4 Termination](requirements-and-design.md#j4-termination).

| Topic | Section |

|---|---|

| Request payload, N-target command, 202 response, completion event, stored updates, read, delete and patch examples | [Contract §8](/oeg/interface-contract.md#8-multi-zone-deployment) |



<a id="open-questions"></a>



[F. Open Questions](overview-and-architecture.md#f-open-questions).
 
Pin matching (OQ-D1), patch operations (OQ-D2) and rollback after partial success (OQ-D3) are

open; see [overview §F](/oeg/overview-and-architecture.md#f-open-questions).

oeg/app-instance-flow.md

+118 −19
Changes for oeg/app-instance-flow.md: 118 added lines, 19 removed lines.
Original line number Diff line number Diff line 
---

type: Topic Reference

title: "OEG Internal Model — App Instance Deployment Flow"

description: "Topic links into the OEG Release 2.0 specification."

title: "OEG — App Instance Deployment Flow"

description: "How OEG accepts a deployment to one zone, hands it to SRM over the DataBus, reports the outcome and tears the instance down, and where the full detail lives."

tags: [oeg, flow, deployment]

timestamp: 2026-10-22T00:00:00Z

component: Open Exposure Gateway (OEG)
@@ -9,15 +9,122 @@ version: "2.0" 
status: "OOP Release 2.0 — topic reference"

---



# OEG Internal Model — App Instance Deployment Flow

# OEG — App Instance Deployment Flow



Read the [four-part specification](index.md) in order. The links below lead to the authoritative requirements, payloads and operational guidance for this topic.

**Companion documents:**

[oeg/requirements-and-design.md](/oeg/requirements-and-design.md),

[oeg/interface-contract.md](/oeg/interface-contract.md)



**Closest neighbours:**

[oeg/app-registration-flow.md](/oeg/app-registration-flow.md),

[oeg/app-deployment-flow.md](/oeg/app-deployment-flow.md),

[ADR-0005](/decisions/0005-appinstance-identity-and-multiplicity.md)



This page explains the flow in plain terms. The four-part [OEG specification](/oeg/index.md)

is authoritative; the last section points to the parts that own each detail.



---



<a id="overview"></a>

<a id="uc6--request-application-deployment-inbound-path"></a>

<a id="3-request-flow"></a>



[J.2 Single-Zone Deployment](requirements-and-design.md#j2-single-zone-deployment).

## Mental Model



**Accepted is not running.** OEG records the request, sends a command to SRM over the DataBus

and answers 202. The app is not deployed yet.



**OEG picks the instance id.** OEG mints the `appInstanceId` before sending the command, and

SRM adopts it. The client has the id straight away and never needs to ask SRM for it.



**SRM reports back with an event.** OEG updates its records from that event and, if the client

asked, calls the client back. The client can always poll instead.



```text

 App provider          OEG                         DataBus / SRM

      | POST /appinstances |                              |

      |------------------->| validate, mint ids,          |

      |                    | commit rows and command      |

      |                    | command.srm.service.deploy   |

      |                    |----------------------------->| SRM deploys through TF-SDK

      |<-------------------| 202 {appInstanceId,          |

      |                    |      status instantiating}   |

      |                    |                              |

      |                    | event.srm.operation.completed|

      |                    |<-----------------------------|

      |                    | update operation, instance   |

      |<-------------------| callback, if registered      |

```



---



## Request path



1. The client calls `POST /appinstances` with a registered `appId` and exactly one

   `edgeCloudZoneId`. A cluster pin and a callback sink are optional.

2. An unknown app is 400. An app already active in that zone is 409. Failed or terminated

   instances do not block a new one.

3. OEG mints an operation id and the `appInstanceId`.

4. In one transaction, OEG commits the `PENDING` operation, the `instantiating` instance, any

   callback row and the command to send.

5. OEG publishes `command.srm.service.deploy` with one target. Only after the broker

   acknowledges it does OEG answer 202.



Steps 4 and 5 are required behaviour, not current behaviour. Selected code publishes before it

commits and uses core NATS, which gives no acknowledgment

([design §M.2](/oeg/requirements-and-design.md#m2-commit-and-publish-boundary)).



---



<a id="uc7--successful-application-deployment-completion-path"></a>

<a id="2-completion-flow"></a>



## Completion path



1. SRM publishes `event.srm.operation.completed` with the operation id, outcome and instances.

2. OEG updates the operation and moves the instance to `ready` or `failed`. If the whole

   operation failed and the event lists no instances, OEG fails the rows it created at request

   time.

3. If a callback was registered, OEG sends a CloudEvent to the sink. Selected code tries once,

   without retry.



`GET /appinstances?appInstanceId=...` combines OEG's own row with live SRM data such as

endpoints.



---



## Instance states



| Internal state | Client sees | Reached when |

|---|---|---|

| `instantiating` | `instantiating` | The request is accepted |

| `ready` | `ready` | SRM reports success |

| `failed` | `failed` | SRM reports failure, or OEG's timeout sweep gives up |

| `terminating` | `terminating` | A delete is accepted |

| `terminated` | `unknown` | SRM confirms teardown; the row is kept |



CAMARA has no `terminated` value, so the client sees `unknown`. The internal `operationId`

never appears in responses or callbacks.



---



<a id="terminate--delete-appinstancesappinstanceid"></a>



## Termination



`DELETE /appinstances/{appInstanceId}` creates a separate terminate operation, marks the

instance `terminating` and publishes `command.srm.service.terminate`. Completion moves it to

`terminated`. An instance that failed before starting can be settled at once, without SRM.



---



## Where the details live



| Topic | Section |

|---|---|

| Acceptance steps and failure handling | [Design §J.2](/oeg/requirements-and-design.md#j2-single-zone-deployment) |

| Event handling, status and timeouts | [Design §M.1](/oeg/requirements-and-design.md#m1-completion-and-status) |

| Termination | [Design §J.4](/oeg/requirements-and-design.md#j4-termination) |



<a id="1-nbi-endpoint"></a>

<a id="2-camara-request-payload"></a>
@@ -44,22 +151,14 @@ Read the [four-part specification](index.md) in order. The links below lead to t 
<a id="field-origins--get-list-response"></a>

<a id="response-3--get-appinstancesappinstanceid-200--single-instance-read"></a>

<a id="appinstancestatus-mapping"></a>



[7. Instance Payloads and Mappings](interface-contract.md#7-instance-payloads-and-mappings).



<a id="uc7--successful-application-deployment-completion-path"></a>

<a id="2-completion-flow"></a>



[M.1 Completion and Status](requirements-and-design.md#m1-completion-and-status).



<a id="response-4--webhook-callback-uc7--push"></a>



[4. Callback Contract](interface-contract.md#4-callback-contract).



<a id="terminate--delete-appinstancesappinstanceid"></a>



[J.4 Termination](requirements-and-design.md#j4-termination).

| Topic | Section |

|---|---|

| Request payload, field mapping, stored rows, DataBus messages, responses, status mapping | [Contract §7](/oeg/interface-contract.md#7-instance-payloads-and-mappings) |

| Callback payload and credentials | [Contract §4](/oeg/interface-contract.md#4-callback-contract) |



<a id="open-questions"></a>



[F. Open Questions](overview-and-architecture.md#f-open-questions).
 
Callback retry (OQ-03), endpoint enrichment (OQ-04) and region filtering (OQ-05) are open; see

[overview §F](/oeg/overview-and-architecture.md#f-open-questions).

oeg/app-registration-flow.md

+98 −10
Changes for oeg/app-registration-flow.md: 98 added lines, 10 removed lines.
Original line number Diff line number Diff line 
---

type: Topic Reference

title: "OEG Internal Model — App Registration Flow"

description: "Topic links into the OEG Release 2.0 specification."

title: "OEG — App Registration Flow"

description: "How OEG turns a CAMARA app manifest into an SRM catalog entry in one synchronous call, the two ids it keeps, how registration fails, and where the full detail lives."

tags: [oeg, flow, registration]

timestamp: 2026-10-22T00:00:00Z

component: Open Exposure Gateway (OEG)
@@ -9,14 +9,103 @@ version: "2.0" 
status: "OOP Release 2.0 — topic reference"

---



# OEG Internal Model — App Registration Flow

# OEG — App Registration Flow



Read the [four-part specification](index.md) in order. The links below lead to the authoritative requirements, payloads and operational guidance for this topic.

**Companion documents:**

[oeg/requirements-and-design.md](/oeg/requirements-and-design.md),

[oeg/interface-contract.md](/oeg/interface-contract.md),

[oeg/translation-example-uc1.md](/oeg/translation-example-uc1.md)



**Closest neighbours:**

[oeg/app-instance-flow.md](/oeg/app-instance-flow.md),

[srm/interface-contract.md](/srm/interface-contract.md),

[ADR-0011](/decisions/0011-catalog-id-adoption.md)



This page explains the flow in plain terms. The four-part [OEG specification](/oeg/index.md)

is authoritative; the last section points to the parts that own each detail.



---



<a id="1-overview"></a>

<a id="4-request-flow"></a>



[J.1 Registration](requirements-and-design.md#j1-registration).

## Mental Model



**Registration says what the app is; it runs nothing.** An app provider registers an app

before deploying it. The manifest names the image or chart, the resources it needs and the

network interfaces it opens.



**One synchronous call, no DataBus.** OEG maps the CAMARA `AppManifest` into SRM's catalog

vocabulary and calls SRM once. The caller gets a final answer in the HTTP response.



**SRM keeps the manifest.** OEG keeps only a summary row saying who registered what.

`GET /apps` reads the manifest back from SRM.



```text

 App provider            OEG                                SRM

      | POST /apps         |                                  |

      |------------------->| validate manifest, map fields    |

      |                    | POST /internal/catalog/          |

      |                    |      service-specifications      |

      |                    |--------------------------------->| create specification,

      |                    |<---------------------------------| units and capability (atomic)

      |                    | write app_registrations          |

      |                    | (status REGISTERED)              |

      |<-------------------| 201 SubmittedApp {appId}         |

```



---



## Steps



1. The client calls `POST /apps`. OEG checks the token and validates the manifest.

2. OEG keeps the supplied `appId`, or generates one, and mints a fresh internal

   `app_registration_id`.

3. OEG translates the manifest into one service specification, its deployment units and a

   compute capability requirement.

4. OEG calls SRM once. SRM creates everything atomically and adopts `app_registration_id` as

   the specification's primary key.

5. OEG stores a summary row with status `REGISTERED` and returns 201 with the `appId`.



---



<a id="3-appid-resolution"></a>



## Two ids



| Id | Meaning |

|---|---|

| `appId` | The CAMARA id the caller uses. Unique among active registrations |

| `app_registration_id` | Internal, new on every registration. SRM uses it as the specification id; deployments refer to it |



Registration status is only `REGISTERED` → `DELETED`. Deploying the app never changes it.

`DELETE /apps/{appId}` removes the SRM specification and marks the row `DELETED`. It answers

409 while instances are still running.



---



## When it fails



| Situation | Result |

|---|---|

| Invalid manifest | 400 |

| Valid but unsupported variant | 501 `NOT_IMPLEMENTED` |

| `appId` already registered | 409 `ALREADY_EXISTS` |

| SRM call fails | Nothing is created in SRM; nothing to clean up |

| OEG write fails after SRM succeeded | An orphan specification can remain; recovery is Unspecified |



Only Kubernetes `CONTAINER` and `HELM` packages are fulfilled. Registry credentials are not yet

stored as secrets, so private repositories are blocked (C09). CPU and GPU totals do not yet

follow the intended mapping (C28).



---



## Where the details live



| Topic | Section |

|---|---|

| Steps, failures and limits | [Design §J.1](/oeg/requirements-and-design.md#j1-registration) |

| Id and state rules | [Design §L](/oeg/requirements-and-design.md#l-data-state-and-invariants) |



<a id="2-nbi-endpoint"></a>

<a id="5-camara-input-fields"></a>
@@ -31,8 +120,7 @@ Read the [four-part specification](index.md) in order. The links below lead to t 
<a id="9a-read--delete-coverage-note"></a>

<a id="10-full-translation-summary-table"></a>



[6. Application Registration](interface-contract.md#6-application-registration).



<a id="3-appid-resolution"></a>



[L. Data, State and Invariants](requirements-and-design.md#l-data-state-and-invariants).
 
| Topic | Section |

|---|---|

| Input fields, internal model, SRM payload, stored row, response, reads and deletes, UC1–UC3 examples | [Contract §6](/oeg/interface-contract.md#6-application-registration) |

| One registration followed step by step | [Translation example UC1](/oeg/translation-example-uc1.md) |

oeg/architecture.md

+113 −37

File changed.

Preview size limit exceeded, changes collapsed.

oeg/persistence-model.md

+136 −25

File changed.

Preview size limit exceeded, changes collapsed.