certctl/docs/connector-f5.md

F5 BIG-IP Connector — Operator Deep-Dive

Per Phase 14 of the deploy-hardening II master bundle.

Overview

The F5 connector (internal/connector/target/f5/) deploys TLS certs to F5 BIG-IP load balancers via the iControl REST API. F5's transactional API gives certctl atomic-update semantics for free at the API level — the Bundle I rollback wire layers on-failure cleanup of orphaned crypto objects.

Vendor versions tested

• F5 v15.1 LTS
• F5 v17.0 LTS
• F5 v17.5

Two-tier validation strategy (frozen decision 0.3)

1. CI tier: f5-mock-icontrol sidecar — in-tree Go server at deploy/test/f5-mock-icontrol/ implementing the iControl REST surface this bundle exercises (auth, file upload, transactions, SSL profile CRUD). All TestVendorEdge_F5_*_E2E tests run against this in CI.
2. Customer-grade tier: operator-supplied real F5 vagrant box. Documented setup recipe below. Manual smoke required for "verified" status in docs/deployment-vendor-matrix.md.

The mock implements a SUBSET of iControl REST. A real F5 may diverge on quirks the mock doesn't model. Customer-grade validation against the vagrant box is the validation tier above the mock.

Setting up the operator-supplied real F5

# F5 Networks publishes BIG-IP VE (Virtual Edition) on:
#   https://downloads.f5.com → BIG-IP VE → 17.5.0 → Vagrant
# Download the .box file (requires F5 account; free tier ok).
vagrant box add f5/big-ip-17.5.0 ~/Downloads/BIGIP-17.5.0.0.0.box
vagrant init f5/big-ip-17.5.0
vagrant up

# Then point certctl at vagrant's mapped management interface:
#   https://localhost:8443 with admin/<vagrant-default-password>
# Per-target Config:
#   Host: "localhost"
#   Port: 8443
#   Username: "admin"
#   Password: "<from vagrant>"

Run the F5 vendor-edge tests against the real F5 by setting:

F5_REAL_HOST=localhost:8443 \
F5_REAL_USER=admin \
F5_REAL_PASS=<vagrant-pass> \
INTEGRATION=1 go test -tags integration \
  -run 'TestVendorEdge_F5' ./deploy/test/...

(Test bodies opt into the real-F5 path when these env vars are set; otherwise default to the mock sidecar.)

Per-quirk operator guidance

SSL profile reference counting

TestVendorEdge_F5_SSLProfileReferenceCounting_TransactionWithNVS_AtomicCommit_E2E

When a transaction binds the new SSL profile to N virtual servers, F5 commits all N atomically. Failure aborts all N.

Client SSL vs server SSL profile

TestVendorEdge_F5_ClientSSLProfileVsServerSSLProfile_DeployUpdatesCorrect_E2E

F5 has separate client-ssl profiles (terminating TLS from clients) and server-ssl profiles (originating TLS to backends). Connector targets the operator-named profile only.

Partition handling

TestVendorEdge_F5_PartitionCommonVsCustom_DeployRespectsPartition_E2E

F5 partitions namespace objects (Common, custom-tenant). Connector respects the operator-supplied Partition.

v15 vs v17 API stability

TestVendorEdge_F5_F5v15_vs_v17_TransactionAPIShapeStable_E2E

mgmt/tm/transaction API shape stable across v15.1 LTS and v17.x. No per-version branch needed.

Large cert chain (>4 links)

TestVendorEdge_F5_LargeCertChainHandling_E2E

v15.x had a known issue with cert chains >4 links (silent truncation of the deep links). v17.x lifted this limit.

Operator action: if on v15.x, keep chains ≤4 links OR upgrade to v17.x. Documented loud in this doc.

Auth token expiry

TestVendorEdge_F5_AuthTokenExpiryRefresh_E2E

F5 auth tokens expire (default 1200s). Connector re-authenticates on 401 transparently.

Transaction timeout cleanup

TestVendorEdge_F5_TransactionTimeoutCleanup_E2E

Open transactions timeout after 120s. Bundle I rollback wire catches orphaned crypto objects (uploaded files not committed via transaction).

Same-VS update

TestVendorEdge_F5_VirtualServerBindingOnSameVS_E2E

Re-binding an SSL profile on the same Virtual Server is atomic at the F5 API level. No listener disruption.

SSL options preservation

TestVendorEdge_F5_SSLOptionsPreservedAcrossRotation_E2E

Operator-supplied cipher-list, no-tls-v1, secure-renegotiate options on the SSL profile preserved across cert rotation.

iControl REST rate limit

TestVendorEdge_F5_iControlRESTRateLimit_E2E

F5 iControl REST defaults to 100 req/s. Connector backs off on 429 with exponential retry.

Troubleshooting matrix

Symptom	Test name	Operator action
Cert deploys but only 4 chain links served	LargeCertChainHandling_E2E	upgrade to v17.x or shorten chain
Frequent 401 retries	AuthTokenExpiryRefresh_E2E	benign; tune token lifetime if needed
Orphaned /Common/cert-<timestamp> objects	TransactionTimeoutCleanup_E2E	run cleanup script; check for hung deploys
Wrong partition deployed to	PartitionCommonVsCustom_E2E	verify Partition in connector config
Cipher list reset post-rotate	SSLOptionsPreservedAcrossRotation_E2E	bug — file an issue

V3-Pro deferrals

• F5 GTM (DNS-load-balancer cert deploys).
• F5 NGINX Plus cert deploy via the F5 API (when F5 ships the unified API).
• AS3 declarative deploy (operator-friendly JSON declaration vs the imperative iControl REST flow).

Related docs

• Atomic deploy + post-verify + rollback
• Vendor compatibility matrix
• F5 official iControl REST docs: https://clouddocs.f5.com/api/icontrol-rest/