F5 Instance Record to Settings Mapping

Overview

The F5SettingsMapper is an internal utility component that centralizes the logic for translating a stored F5InstanceRecord into the specific settings objects required by discovery and reconciliation services.

This component solves the problem of configuration drift by providing a single, canonical source of truth for interpreting an F5 instance's stored configuration. Previously, this logic was duplicated between the operator-facing F5Controller and the background F5ManagedRuleReconciler. By delegating this mapping to F5SettingsMapper, the platform ensures that both manual operations and automated background tasks connect to F5 BIG-IP appliances using identical settings derived from the same logic.

Its primary function is to take an F5InstanceRecord as input and produce two distinct outputs:

• An F5DiscoveryService.F5Settings object for general connection and discovery.
• An F5DiscoveryService.F5LogForwardingSettings object for configuring log forwarding.

How It Works

The mapper exposes static methods that perform direct translation from the fields of an F5InstanceRecord to the constructor arguments of the target settings objects.

Mapping to Connection Settings

The toSettings method creates an F5DiscoveryService.F5Settings object. This mapping is a direct pass-through of values from the F5InstanceRecord to the settings object.

The following F5InstanceRecord properties are mapped directly:

• managementUrl()
• managementUrls()
• partitionName()
• selectedPartitionNames()
• primaryPolicyName()
• selectedPolicyNames()
• effectiveUsername()
• effectivePassword()
• frontendVsFilter()
• backendVsFilter()
• selectedFrontVirtualServers()
• selectedBackendVirtualServers()

Additionally, a hardcoded boolean value of true is passed to the F5Settings constructor. The source does not specify the purpose of this parameter.

Mapping to Log Forwarding Settings

The toLogSettings method creates an F5DiscoveryService.F5LogForwardingSettings object, applying defaults for several fields if they are not specified in the F5InstanceRecord.

The mapping logic is as follows:

• Log Profile Name: If record.logProfileName() is null or blank, the value defaults to "S2R_AUTO_SOAP_LOGS". Otherwise, the value from the record is used.
• Log Receiver Target: The target address is determined by the effectiveReceiverAddress logic. If the resulting address is not blank, it is provided as a single-element list. If it is blank, an empty list is provided.
• Protocol: The protocol is always hardcoded to "tcp".
• Response Logging: If record.responseLogging() is null or blank, the value defaults to "all". Otherwise, the value from the record is used.

Log Receiver Address Resolution

The target address for log forwarding is determined using a specific fallback chain to provide both instance-level and global configuration. The effectiveReceiverAddress method implements this logic.

The address is selected based on the first available value in the following order of precedence:

1. Instance-Specific Address: The logReceiverAddress value from the F5InstanceRecord.
2. Primary Environment Variable: The value of the S2R_DISCOVERY_INGEST_LOG_RELAY_TARGET environment variable.
3. Legacy Environment Variable: The value of the S2R_F5_LOG_RELAY_TARGET environment variable.

If none of these sources provide a non-blank value, an empty string is returned, effectively disabling log forwarding to a configured target.

The following diagram illustrates this decision flow:

flowchart TD
    subgraph Log Receiver Address Resolution
        A[Start] --> B{Instance-level `logReceiverAddress` configured?};
        B -- Yes --> C[Use instance-level address];
        B -- No --> D{`S2R_DISCOVERY_INGEST_LOG_RELAY_TARGET` env var set?};
        D -- Yes --> E[Use `S2R_DISCOVERY_INGEST_LOG_RELAY_TARGET` value];
        D -- No --> F{`S2R_F5_LOG_RELAY_TARGET` env var set?};
        F -- Yes --> G[Use `S2R_F5_LOG_RELAY_TARGET` value];
        F -- No --> H[Use empty string];
    end
    subgraph Result
        C --> Z[Return address];
        E --> Z;
        G --> Z;
        H --> Z;
    end

API Reference

The F5SettingsMapper provides the following public static methods.

toSettings

Maps an F5InstanceRecord to connection and discovery settings.

public static F5DiscoveryService.F5Settings toSettings(F5InstanceRecord record)

• Parameters:
  • record: The F5InstanceRecord containing the stored configuration for the F5 BIG-IP instance.
• Returns: An F5DiscoveryService.F5Settings object populated with values from the record.

toLogSettings

Maps an F5InstanceRecord to log forwarding settings, applying system defaults where needed.

public static F5DiscoveryService.F5LogForwardingSettings toLogSettings(F5InstanceRecord record)

• Parameters:
  • record: The F5InstanceRecord containing the stored configuration.
• Returns: An F5DiscoveryService.F5LogForwardingSettings object populated with values from the record and applicable defaults.

effectiveReceiverAddress

Resolves the definitive log receiver address using a fallback chain of instance configuration and environment variables.

public static String effectiveReceiverAddress(String configuredReceiverAddress)

• Parameters:
  • configuredReceiverAddress: The address configured on the specific instance record, which may be null or empty.
• Returns: A String containing the resolved log receiver address, or an empty string if no address is configured at any level.

Configuration Reference

The behavior of the F5SettingsMapper is driven by the properties of the F5InstanceRecord and two platform-level environment variables.

F5InstanceRecord Properties

The following properties from an F5InstanceRecord object are used as inputs for the mapping process. The source does not specify the data types for these properties.

Environment Variables

These environment variables provide a global default for the log forwarding target if an instance-specific address is not set.

Troubleshooting

Default and Fallback Behavior

The mapper is designed to be resilient by providing default values. Misconfiguration is unlikely to cause a hard failure but may result in unintended behavior.

• Missing Log Profile Name: If an F5InstanceRecord has a blank logProfileName, the system will automatically use the name S2R_AUTO_SOAP_LOGS.
• Missing Response Logging Mode: If an F5InstanceRecord has a blank responseLogging value, the system will default to logging all responses.
• No Log Receiver Address: If logReceiverAddress is not set on the instance and neither of the fallback environment variables (S2R_DISCOVERY_INGEST_LOG_RELAY_TARGET or S2R_F5_LOG_RELAY_TARGET) are set, the resulting F5LogForwardingSettings will contain an empty list of targets. This will prevent the configuration of a log forwarding destination on the F5 appliance.

See Also

• F5DiscoveryService: The service that consumes the settings objects produced by this mapper to interact with F5 BIG-IP appliances.
• F5ManagedRuleReconciler: A background reconciliation process that uses this mapper to ensure its connection settings are consistent with other parts of the system.
• System Design Principles: The creation of this centralized mapper aligns with the design principle of avoiding duplicate definitions of component configuration to prevent logic drift.

All SOAP-to-REST docs