F5 Instance Data Management

Manages the lifecycle and configuration of F5 BIG-IP instance records, including tenancy, credential encryption, and data validation for the API platform.

Overview

The F5 Instance Repository is a data access component responsible for the persistent storage and management of F5 BIG-IP instance configurations. It provides a centralized, secure mechanism for creating, reading, updating, and deleting records that define how the platform connects to and interacts with an F5 instance.

This component serves as the persistence layer for the Admin API, handling all database operations related to F5 instances. Its primary functions are to:

Enforce strict data isolation between tenants.
Securely store and handle credentials.
Validate and normalize configuration payloads.
Provide reliable CRUD (Create, Read, Update, Delete) operations for F5 instance records.

Every operation is scoped to the authenticated API consumer's tenant, ensuring that one tenant cannot access or even detect the existence of another tenant's F5 configurations.

How it Works

The repository manages records in the s2r_f5_instance database table. Its design incorporates key principles of security and data integrity, including multi-tenancy, credential encryption, and careful handling of configuration updates.

Multi-Tenancy Enforcement

Data access is strictly segregated by tenant. Every database query executed by this repository includes a TENANT_SCOPE clause that filters records by the current request's tenant ID.

This has two main consequences:

API consumers can only operate on F5 instances that belong to their tenant.
An attempt to access an instance by its id will fail with a "not found" error if the instance belongs to a different tenant, preventing information leakage about the existence of other tenants' resources.

In multi-tenant deployments, if a request is processed without a resolved tenant context, the database operation will fail with an S2R-TENANCY-UNBOUND error to prevent accidental access to default-tenant credentials.

flowchart TD
    subgraph "API Platform"
        A[API Consumer Request] -- "Carries Tenant Context" --> B{Admin API Service}
        B --> C[F5 Instance Repository]
        subgraph "Database"
            D[s2r_f5_instance table]
        end
        C -- "SQL with Tenant Scope Filter" --> D
    end

Credential Encryption and Security

The repository ensures that all sensitive credentials for an F5 instance are encrypted at rest. The following fields are always stored as encrypted envelopes using the platform's CredentialsCipher service:

password
managed_password
relay_service_account_json

When an F5InstanceRecord is read from the database, these values are decrypted in memory for use by internal services, but they are never exposed in plaintext via administrative GET requests.

WARNING

Credential Re-submission on Target Change To prevent a stored credential from being inadvertently sent to a new or different F5 appliance, the system requires the password to be re-submitted in an update payload if the managementUrl, haManagementUrls, or username fields are changed. If the target is modified without providing a new password, the update will be rejected. The same logic applies to the managedPassword, which is cleared if the target host changes.

The system also includes a startup migration task, encryptLegacyPlaintextSecrets, which idempotently finds and encrypts any secrets that were stored in plaintext by older versions of the platform.

API Operations

The repository exposes methods for managing F5InstanceRecord entities. These are internal service methods called by the Admin API in response to API consumer requests.

Method	Description
`create(payload, actor)`	Creates a new F5 instance record. Generates a unique `id` and `ingestToken`. Encrypts secrets and persists the normalized payload.
`update(id, payload, actor)`	Updates an existing F5 instance record identified by `id`. Applies normalization and credential security rules.
`findAll()`	Returns a list of all `F5InstanceRecord` objects owned by the caller's tenant, sorted by `enabled` status and name.
`findRequired(id)`	Retrieves a single `F5InstanceRecord` by its `id`. Throws an `IllegalArgumentException` if the record is not found or does not belong to the caller's tenant.
`delete(id)`	Deletes an F5 instance record by its `id`, respecting tenant boundaries.
`setEnabled(id, enabled, actor)`	Sets the `enabled` status for a specific F5 instance.
`updateManagedCredential(...)`	Updates the `managed_username` and `managed_password` for an instance. Also sets `managed_credential_requested` to `true`.
`updateDiscoveredManagementTopology(...)`	Updates the `management_url` and `ha_management_urls` based on runtime discovery.
`updateLogReceiverAddress(...)`	Updates the `log_receiver_address` for a specific instance.
`encryptLegacyPlaintextSecrets()`	An internal maintenance operation to encrypt any plaintext secrets found in the database. Returns the count of re-encrypted values.

Configuration Fields

When creating or updating an F5 instance, a payload object is provided. The repository normalizes this payload, applying defaults and validation rules. The following table details all configurable fields.

Field	Type	Default (on create)	Required	Description
`instanceName`	String	—	Yes	A unique, human-readable name for the F5 instance.
`enabled`	Boolean	`true`	No	If `true`, the instance is active and will be used for scanning and other operations.
`managementUrl`	String (URL)	—	Yes	The primary management endpoint URL for the F5 BIG-IP device.
`haManagementUrls`	Array of Strings	`[]` (empty list)	No	A list of secondary management URLs for F5 devices in a high-availability (HA) pair.
`username`	String	—	Yes	The username for authenticating with the F5 management API.
`password`	String (Secret)	—	Yes	The password for the `username`. This value is write-only and must be re-submitted if the `managementUrl` or `username` changes.
`tlsInsecure`	Boolean	`true`	No	This field is internally set to `true`. The source does not provide a way to change this value.
`bootstrapMode`	String	`personal_admin_once`	No	Defines the bootstrap strategy for the instance. The source does not specify other possible values.
`managedCredentialRequested`	Boolean	`false`	No	A flag indicating if managed credentials have been requested for this instance.
`managedUsername`	String	`null`	No	The username for a managed credential. This value is cleared if the `managementUrl` is changed on an update.
`managedPassword`	String (Secret)	`null`	No	The password for a managed credential. This value is cleared if the `managementUrl` is changed on an update.
`partitionName`	String	`null`	No	The primary F5 partition name. If `partitionNames` is set, this field will be updated to the first element of that list.
`partitionNames`	Array of Strings	`[]` (empty list)	No	A list of F5 partition names to manage. If this is empty but `partitionName` is provided, this list will be populated with `partitionName`.
`wafPolicyName`	String	`null`	No	The primary WAF policy name. If `wafPolicyNames` is set, this field will be updated to the first element of that list.
`wafPolicyNames`	Array of Strings	`[]` (empty list)	No	A list of WAF policy names to manage. If this is empty but `wafPolicyName` is provided, this list will be populated with `wafPolicyName`.
`relayProjectId`	String	`null`	No	The project ID for a relay service.
`relayServiceAccountJson`	String (Secret)	`null`	No	A service account JSON key for a relay service. This value is encrypted at rest. It can be cleared by sending `clearRelayServiceAccountJson: true`.
`clearRelayServiceAccountJson`	Boolean	`false`	No	A write-only flag. If `true`, the stored `relayServiceAccountJson` will be cleared.

| | logProfileName | String | S2R_AUTO_SOAP_LOGS | No | The name of the log profile to be created or used on the F5 instance.

Tagsreference

All SOAP-to-REST docs

Loading…