F5 Instance Synchronization State

Overview

The F5 Sync State Repository is a data access component responsible for persisting and retrieving the operational state of F5 BIG-IP instances managed by the platform. It tracks the status and outcomes of various asynchronous tasks performed against each F5 instance, such as configuration scans, catalog discovery, and traffic relay management.

This component solves the problem of maintaining a durable, centralized record of an F5 instance's lifecycle and health. It acts as the source of truth for:

• Connectivity status and the last-used management endpoint.
• The timing, status, and summary of "light" and "full" configuration scans.
• The complete F5 configuration catalog, stored as a JSON snapshot.
• The status of WSDL probes against virtual servers.
• The provisioning and health state of associated traffic relay virtual machines.
• The status of log forwarding configuration updates.

It is an internal component of the Admin API, called by services that execute these operations. The data it manages is exposed through the API to provide visibility into the synchronization status of F5 instances.

How it Works

The repository manages state in a single database table, s2r_f5_sync_state, where each row corresponds to a single F5 instance, identified by f5_instance_id. All write operations use an INSERT ... ON CONFLICT (upsert) pattern to create a record if one doesn't exist or update the existing one for a given F5 instance.

Tenancy and Data Isolation

A critical aspect of this repository is its handling of multi-tenancy. The s2r_f5_sync_state table does not have a tenant_id column. Instead, data access is strictly controlled by joining against the s2r_f5_instance table, which is tenant-scoped.

All read operations, such as findByInstanceId and findByInstanceIds, include a SQL predicate (BOUND_TENANT_INSTANCE_SQL) that filters results to only include F5 instances owned by the API consumer's tenant. A request to read the state for an F5 instance owned by another tenant will return no data, which is indistinguishable from an instance that has no sync state recorded.

Catalog Snapshot and Materialization

When the F5 configuration catalog is loaded, the markCatalogLoaded method performs two key actions:

1. It persists the complete configuration as a JSONB snapshot in the last_catalog_snapshot column of the s2r_f5_sync_state table. This snapshot is the authoritative source of the catalog at that point in time.
2. It then calls the F5VirtualServerCatalogRepository to populate a separate, materialized table of virtual servers from the snapshot. This materialized data is optimized for fast lookups during traffic processing.

This process is designed for resilience. If the second step (materialization) fails, a warning is logged, but the primary operation of saving the snapshot succeeds. The materialized catalog can be rebuilt from the authoritative snapshot on a subsequent scan.

sequenceDiagram
    participant Caller as "Service Logic"
    participant F5SyncStateRepo as "F5SyncStateRepository"
    participant DB as "Database (s2r_f5_sync_state)"
    participant VSCatalogRepo as "F5VirtualServerCatalogRepository"

    Caller->>F5SyncStateRepo: markCatalogLoaded(instanceId, snapshot, ...)
    F5SyncStateRepo->>DB: UPSERT state with JSON snapshot
    DB-->>F5SyncStateRepo: Acknowledge write
    F5SyncStateRepo->>VSCatalogRepo: syncFromSnapshot(instanceId, snapshot)
    Note right of VSCatalogRepo: Populates materialized VS table for fast lookups
    VSCatalogRepo-->>F5SyncStateRepo: Return success/failure
    alt on failure
        F5SyncStateRepo->>F5SyncStateRepo: log.warn("...sync failed...")
    end
    F5SyncStateRepo-->>Caller: Return

Scan Types

The repository distinguishes between two types of scans:

• Light Scan: A minimal scan, with its state stored in last_light_scan_* fields.
• Full Scan: A comprehensive scan, with its state stored in last_full_scan_* fields.

The markManualScan method accepts a fullScan boolean parameter to determine which set of fields to update.

API Reference

The repository exposes a Java API for reading and writing F5 instance state.

findByInstanceId(UUID instanceId)

Retrieves the complete sync state for a single F5 instance.

• Parameters:
  • instanceId (UUID): The unique identifier of the F5 instance.
• Returns: An F5SyncStateRecord object if a record exists and is owned by the calling tenant. Returns null if no record is found or if the instance belongs to another tenant.

findByInstanceIds(List<UUID> instanceIds)

Retrieves the sync state for a list of F5 instances.

• Parameters:
  • instanceIds (List<UUID>): A list of F5 instance identifiers.
• Returns: A Map<UUID, F5SyncStateRecord> where keys are the instance IDs. The map only contains entries for instances that were found and are owned by the calling tenant.

markConnectionOk(...)

Updates the state to indicate a successful connection to the F5 instance.

• Parameters:
  • instanceId (UUID): The instance identifier.
  • connectedAt (OffsetDateTime): The timestamp of the successful connection.
  • activeManagementUrl (String): The management URL that was used for the connection.

markCatalogLoaded(...)

Updates the state after a configuration catalog load attempt. If the status is ok, this also updates last_connection_ok_at.

• Parameters:
  • instanceId (UUID): The instance identifier.
  • loadedAt (OffsetDateTime): The timestamp when the load completed.
  • status (String): The outcome of the operation (e.g., "ok").
  • message (String): A descriptive message about the outcome.
  • snapshot (Map<String, Object>): The complete configuration catalog, which will be serialized to JSON.
  • activeManagementUrl (String): The management URL that was used.

markWsdlProbe(...)

Updates the state after a WSDL probe operation.

• Parameters:
  • instanceId (UUID): The instance identifier.
  • checkedAt (OffsetDateTime): The timestamp when the probe completed.
  • status (String): The outcome of the operation.
  • message (String): A descriptive message about the outcome.
  • summary (Map<String, Object>): A summary of the probe results, which will be serialized to JSON.

markManualScan(...)

Updates the state after a light or full configuration scan. If the status is ok, this also updates last_connection_ok_at.

• Parameters:
  • instanceId (UUID): The instance identifier.
  • fullScan (boolean): true to update full scan fields, false to update light scan fields.
  • startedAt (OffsetDateTime): The timestamp when the scan started.
  • completedAt (OffsetDateTime): The timestamp when the scan completed.
  • status (String): The outcome of the scan.
  • message (String): A descriptive message about the outcome.
  • summary (Map<String, Object>): A summary of the scan results, which will be serialized to JSON.
  • activeManagementUrl (String): The management URL that was used.

markRelayProvisioned(...)

Updates the state for a newly provisioned traffic relay VM. Sets relay_enabled to true.

• Parameters:
  • instanceId (UUID): The instance identifier.
  • relayMode (String): The mode of the relay.
  • vmInstanceName (String): The name of the relay VM instance.
  • addressName (String): The name of the relay's network address resource.
  • ipAddress (String): The IP address of the relay VM.
  • target (String): The target the relay forwards traffic to.
  • status (String): The provisioning status.
  • message (String): A descriptive message.
  • provisionedAt (OffsetDateTime): Timestamp of provisioning completion.
  • healthCheckedAt (OffsetDateTime): Timestamp of the last health check.
  • healthOkAt (OffsetDateTime): Timestamp of the last successful health check.

markRelayHealth(...)

Updates the health status of an existing traffic relay VM.

• Parameters:
  • instanceId (UUID): The instance identifier.
  • status (String): The health status.
  • message (String): A descriptive message.
  • checkedAt (OffsetDateTime): Timestamp of when the health check was performed.
  • okAt (OffsetDateTime): Timestamp of the last successful health check. If null, the existing value is preserved.

markRelayDeleted(...)

Updates the state for a deleted traffic relay VM. Sets relay_enabled to false and nullifies most other relay-related fields.

• Parameters:
  • instanceId (UUID): The instance identifier.
  • status (String): The deletion status.
  • message (String): A descriptive message.
  • deletedAt (OffsetDateTime): Timestamp of deletion completion.

markLogForwardingApply(...)

Updates the state after an attempt to apply log forwarding configuration.

• Parameters:
  • instanceId (UUID): The instance identifier.
  • appliedAt (OffsetDateTime): Timestamp of the operation's completion.
  • status (String): The outcome of the operation.
  • message (String): A descriptive message.

Data Record Schema

The following table describes the fields of an F5SyncStateRecord, which correspond to the columns in the s2r_f5_sync_state database table.

Troubleshooting

Missing Sync State

If a call to findByInstanceId returns null or findByInstanceIds returns a map missing an expected ID, it can mean one of two things:

1. No synchronization operations have ever been recorded for that F5 instance.
2. The F5 instance is owned by a different tenant than the one making the API request.

Due to the tenancy model, these two scenarios are indistinguishable from the repository's perspective.

Stale Virtual Server Catalog

The markCatalogLoaded method updates the authoritative JSON snapshot and the materialized virtual server catalog in two separate steps. If the second step fails, a warning is logged: F5 virtual-server catalog sync failed for {instanceId}. This indicates that while the new catalog snapshot was saved correctly, the materialized tables used for fast lookups may be out of date. The system will attempt to rebuild the materialized catalog on the next successful scan.

Empty JSON Fields

The repository's JSON processing logic is designed to be fault-tolerant. If it encounters an error while serializing a summary map to a JSON string, it will persist an empty JSON object ({}). Similarly, if it fails to parse a JSON string from the database, it will return an empty map. This prevents crashes due to data corruption but may result in the loss of summary or snapshot information for a given operation.

See Also

• F5 Virtual Server Catalog: This repository populates a materialized view of F5 Virtual Servers, which is managed by the F5VirtualServerCatalogRepository. This catalog is used by other parts of the system for efficient lookups.

All SOAP-to-REST docs