# Proposers - Lluis Gifre (CTTC) # Description Add optional controller-authoritative optical spectrum reservations to TeraFlowSDN. The feature enables an external system to ask TFS to hold a candidate flex-grid spectrum block before the optical service is created. The reservation is stored and checked by TFS, not by the external system, so concurrent interactions cannot reserve overlapping slots on the same optical resources. The feature must remain backward compatible: if a service is created or updated without a reservation reference, the current optical service and optical controller logic continues to select spectrum as it does today. If a reservation is specified, the Service component consumes it and the Optical component validates that the reservation matches the required spectrum computed from the connection/service specifications. # Demo or definition of done The feature is complete when TFS can: - compute required spectrum width/slots in the Optical component from optical connection specifications, such as bitrate, modulation, and optical service constraints; - create a tentative reservation over a path/link set and reject conflicting overlapping reservations; - expose reservation state through TFS APIs for operational evidence; - allow Service `UpdateService` to optionally reference a reservation; - use existing behavior when no reservation is referenced; - consume the reservation during optical service provisioning and verify that the resulting optical band/lightpath uses the reserved spectrum; - release or expire unused reservations and release consumed reservations when the service is deleted; - pass unit and integration tests covering non-conflicting, conflicting, expired, committed, released, and no-reservation service paths. ## Acknowledgements This work is funded by the European Commission through the HORIZON-JU-SNS-2023 PROTEUS-6G project with Grant Agreement number 101139134. # References 1. ETSI TeraFlowSDN Context model: `proto/context.proto`. 2. TeraFlowSDN Optical Controller RSA logic: `src/opticalcontroller/RSA.py` and `src/opticalcontroller/tools.py`. 3. TeraFlowSDN Optical Controller northbound routes: `src/opticalcontroller/OpticalController.py`. 4. TeraFlowSDN Service two-step lifecycle: `CreateService` followed by `UpdateService`. # Feature Design (for New-Features) ## Clarifications to Expected Behavior Changes The current optical workflow lets the Optical component select spectrum when the Service component triggers optical provisioning. That behavior must remain the default. The new behavior adds an optional reservation step before service provisioning. The reservation step is intended for distributed or concurrent reservations where one system must temporarily block a candidate spectrum range before optical controller actually consumes the range. The reservation is not a service and does not provision devices. It is a controller-owned hold over optical resources with a bounded lifetime. Expected behavior changes: - TFS becomes the authoritative source of truth for tentative spectrum reservations. - External systems may request reservations, query them, release them, and reference them during service update. - External systems must not calculate the required slot count as the source of truth. The Optical component derives required spectrum from optical connection specifications and validates any requested/reserved range. - The Service component optionally accepts a reservation reference in the service constraints/config rules. If absent, the existing service path is unchanged. - If a reservation reference is present, Service passes it to the Optical component during provisioning. Optical validates it, consumes it, and returns allocation evidence. - A reservation must be rejected if it overlaps with an active service allocation or another non-expired reservation on any shared optical resource. - A reservation must be released on failed service provisioning, explicit release, expiration, or service deletion when applicable. The feature should avoid making any external system responsible for spectrum correctness. Upper-layer systems can request candidate/hold operations, but the controller validates resource availability, required width, contiguity, continuity, and final allocation. ## References - `context.proto`: existing `OpticalLinkDetails.c_slots`, `l_slots`, and `s_slots` maps expose the slot state per optical link. - `opticalcontroller.tools.map_rate_to_slot()`: existing optical logic maps bitrate to required slots and optical parameters. - `opticalcontroller.tools.slot_selection()`: existing optical logic selects C/L/S slot blocks. - `OpticalController.AddFlexLightpath`: existing optical controller endpoint accepts bitrate, preference, directionality, band, and optical-band index. - Service unit tests in `src/service/tests/test_unitary.py` document the two-step `CreateService` then `UpdateService` lifecycle. ## Assumptions - Optical services continue to use the two-step lifecycle: - `CreateService` reserves only service UUID/name/type. - `UpdateService` adds endpoints, constraints, and config rules, then triggers path computation/provisioning. - Existing optical service creation without a reservation must remain backward compatible. - The Optical component has enough information to derive required spectrum from the service/connection request. If not, the request must be rejected with a clear validation error before mutating state. - Slot indexes are controller-local flex-grid indexes over `c_slots`, `l_slots`, and `s_slots` maps. - A reservation is scoped to one TFS context/topology/domain and one optical resource set. - The first implementation may use path/link IDs selected by the controller. A future extension can support explicit candidate paths if needed. - Reservation expiry is required to avoid stale holds when reservation is not used or external system disappears. - `tfs-ctrl` implementation changes must be reviewed and manually committed by the project owner. ## Impacted Components - Context - NBI/TFS-API - Service - Optical Controller - PathComp - Tests/CI ## Context Impact Context should persist controller-owned spectrum reservations and expose them to other TFS components. Recommended new data model: ```text OpticalSpectrumReservationId - context_id - reservation_uuid OpticalSpectrumReservation - reservation_id - topology_id - owner_id - correlation_id - service_id optional - connection_id optional - src_endpoint_id optional - dst_endpoint_id optional - optical_link_ids repeated - band: c_slots | l_slots | s_slots - n_start - n_end - required_slots - bitrate_gbps optional - modulation_format optional - status: RESERVED | CONSUMED | RELEASED | EXPIRED - expires_at_epoch_ms - created_at_epoch_ms - updated_at_epoch_ms - allocation_evidence optional ``` Context API additions should support: - set/create reservation; - get reservation; - list reservations by context/topology/status; - update reservation status atomically; - delete/release reservation. Conflict checks should consider only active states: ```text candidate.status in RESERVED existing.status in RESERVED or CONSUMED same context/topology same band shared optical_link_id slot ranges overlap existing reservation not expired ``` Slot overlap is: ```text candidate.n_start <= existing.n_end and existing.n_start <= candidate.n_end ``` Context should provide transactional or compare-and-set semantics so two concurrent reservation requests cannot both succeed for overlapping resources. ## NBI/TFS-API Impact NBI should expose reservation operations for external orchestrators. Recommended REST API: ```text POST /tfs-api/context/{context_uuid}/optical-spectrum-reservations GET /tfs-api/context/{context_uuid}/optical-spectrum-reservations GET /tfs-api/context/{context_uuid}/optical-spectrum-reservations/{reservation_uuid} POST /tfs-api/context/{context_uuid}/optical-spectrum-reservations/{reservation_uuid}/release POST /tfs-api/context/{context_uuid}/optical-spectrum-reservations/{reservation_uuid}/renew ``` Recommended request for creation: ```json { "topology_uuid": "admin", "src_endpoint_id": "...", "dst_endpoint_id": "...", "service_constraints": [], "connection_specs": { "bitrate_gbps": 100, "modulation_format": "DP-QPSK" }, "preferred_band": "c_slots", "preferred_n_start": 0, "preferred_n_end": 15, "owner_id": "owner-id", "correlation_id": "correl-1234", "ttl_seconds": 120 } ``` The preferred range is optional. If it is specified, Optical validates that it is feasible for the computed required width. If it is not specified, Optical can return the selected available range using its existing slot-selection policy. Recommended response: ```json { "reservation_uuid": "...", "status": "RESERVED", "band": "c_slots", "n_start": 0, "n_end": 15, "required_slots": 16, "optical_link_ids": ["..."], "expires_at_epoch_ms": 1234567890 } ``` NBI should also include reservation status and allocation evidence in `GetService` or related service details when a reservation is consumed by a service. ## Service Impact Service should remain backward compatible. Existing behavior: - no reservation reference in service constraints/config rules; - Service invokes current path computation and optical provisioning logic; - Optical selects spectrum according to current RSA/slot-selection behavior. New optional behavior: - `UpdateService` may include a reservation reference, for example as a typed constraint or custom constraint: ```text constraint_type = "optical-spectrum-reservation" constraint_value = "<reservation_uuid>" ``` - Service validates that the reservation exists, is not expired, is in `RESERVED` state, belongs to the same context/topology, and matches the service endpoints or expected path scope. - Service passes the reservation reference to the Optical component when requesting optical provisioning. - Service must not mark the service as `ACTIVE` unless Optical confirms the reservation was consumed and the effective allocation matches the reservation. - If provisioning fails after reservation consumption starts, Service must trigger rollback/release. - On service deletion, Service should release the consumed reservation/allocation or instruct Optical to release the corresponding optical band/lightpath. The Service component should not compute required slots. It can validate the presence and format of high-level service constraints, but the Optical component owns optical feasibility and required-spectrum calculation. ## Optical Controller Impact Optical is the authoritative component for optical-spectrum feasibility. Required Optical responsibilities: - derive required slots from connection/service specifications, such as bitrate and modulation; - map bitrate/modulation to slot requirements using or extending existing logic such as `map_rate_to_slot()`; - evaluate candidate slots over the optical path using current optical link slot maps; - enforce continuity and contiguity across all selected optical links; - validate an optional preferred band/range; - validate a reservation before consuming it; - consume a reservation by applying the selected slots during lightpath/band creation; - return allocation evidence including band, slot range, optical links, optical band ID, flow ID, and related service/connection IDs; - release allocation state on service deletion or failed provisioning. Recommended internal Optical APIs: ```text ComputeRequiredSpectrum(connection_specs) -> required_slots, band_constraints ComputeSpectrumCandidates(src, dst, connection_specs, optional_path, optional_preference) ReserveSpectrum(candidate, owner_id, correlation_id, ttl) ConsumeSpectrumReservation(reservation_id, service_id, connection_id) ReleaseSpectrumReservation(reservation_id, reason) VerifySpectrumAllocation(service_id or connection_id, reservation_id) ``` Implementation can initially wrap current RSA functions: - use existing bitrate-to-slot logic; - use existing path and slot-selection logic; - add reservation conflict filtering before returning candidates or creating holds; - add reservation consumption checks before calling the final lightpath/band mutation. If a service references a reservation whose slot range is too small for the computed connection specifications, Optical must reject it. If a reservation references available slots but a later service request has different bitrate/modulation/endpoints, Optical must reject it. ## PathComp Impact PathComp remains responsible for path computation where applicable. The spectrum-reservation workflow needs either: - a path from PathComp before reservation, so Optical can reserve along a concrete optical path; or - an Optical-controlled RSA path computation that returns both path and spectrum candidate. For the first implementation, prefer the second option for optical services if that is the current behavior: Optical computes optical path and spectrum together. If Service/PathComp already computes a path for optical service, the reservation request should include or reference that path. PathComp does not need to store reservations. It may need to expose enough path information for Optical/Context to bind reservations to optical link IDs. ## Backward Compatibility Backward compatibility is mandatory. No-reservation service update: ```text CreateService -> UpdateService without reservation -> existing Service/Optical logic ``` Reservation-aware service update: ```text CreateService -> CreateSpectrumReservation -> UpdateService with reservation -> Service validates -> Optical consumes -> ACTIVE ``` Existing systems and tests should continue to pass without adding reservation fields. ## Error Handling Recommended error classes: - `RESERVATION_NOT_FOUND` - `RESERVATION_EXPIRED` - `RESERVATION_CONFLICT` - `RESERVATION_ENDPOINT_MISMATCH` - `RESERVATION_PATH_MISMATCH` - `RESERVATION_WIDTH_MISMATCH` - `RESERVATION_ALREADY_CONSUMED` - `RESERVATION_RELEASED` - `OPTICAL_SPECTRUM_UNAVAILABLE` - `OPTICAL_SPECS_INSUFFICIENT` Errors should be visible through NBI and Service logs. They should be deterministic enough for external systems to decide whether to retry, reserve a different spectrum block, or abort. ## Testing Unit tests: - Context reservation create/get/list/release/expire. - Conflict detection for overlapping slots on shared optical links. - No conflict for same slots on disjoint optical links. - No conflict for non-overlapping slots on shared optical links. - Expired reservations ignored by conflict checks. - Service update without reservation uses existing behavior. - Service update with missing/expired/released reservation fails before provisioning. - Optical rejects reservation whose requested slot width is smaller than required spectrum. - Optical rejects reservation whose endpoints/path differ from service request. - Optical consumes reservation and returns allocation evidence. - Service deletion releases consumed reservation/allocation. Integration tests: - Single-domain optical service without reservation reaches `ACTIVE`. - Single-domain optical service with reservation reaches `ACTIVE` and reservation becomes `CONSUMED`. - Two concurrent overlapping reservation requests: one succeeds, one fails. - Cross-domain scenario: Domain A and Domain B each reserve compatible spectrum, then service creation consumes both reservations. - Failure rollback: peer reservation succeeds, local reservation or service fails, both reservations are released. - Expiration: reservation is not consumed within TTL and later service update fails with `RESERVATION_EXPIRED`. - Evidence: `GetService`, reservation list, and optical link details show requested, reserved, consumed, and released state. Manual validation: - Capture unencrypted NBI/TFS-API traffic showing reservation create, service update with reservation, optical allocation evidence, and release/delete. - Verify optical links reflect the effective consumed slot range after service reaches `ACTIVE`. - Verify no external state persistence is required to prove spectrum ownership.