F5 BIG-IP module

Uploads cert + key + chain to F5 BIG-IP LTM via iControl REST, creates or updates the named SSL profile, and attaches it to virtual servers. Supports TMOS 13.0+, partition scope, and intermediate-chain handling with fingerprint-based naming to avoid duplicate objects.

01Overview

• Transport: iControl REST (HTTPS).
• Auth: username + password, or username + client TLS certificate.
• Artifacts: three separate objects per certificate — /sys/file/ssl-cert, /sys/file/ssl-key, and (if the chain has intermediates) /sys/file/ssl-cert entries for chain members.
• Profile: /ltm/profile/client-ssl or /ltm/profile/server-ssl is created/updated to reference the new trio.
• Rollback: not supported. Old cert/key/chain objects remain. See below.
• Minimum version: TMOS 13.0.

02Prerequisites

• Management IP (or hostname) reachable from the backend on port 443.
• An admin user with Resource Administrator role on the target partition (or Administrator on Common).
• If you deploy to a non-Common partition, the user needs access to that partition explicitly.

03Create the module credential

1. Settings → Distribution → Credentials → New → F5 BIG-IP.
2. Username + password. Paste only once; stored encrypted.
3. Save.

04Create an F5 target

1. Settings → Distribution → Targets → New. Module: F5 BIG-IP.
2. Fields:
   • Host — management IP or DNS name.
   • Port — default 443.
   • Partition — default Common. F5's admin partition.
   • Credential.
   • Profile name — the name we will use for the Client SSL profile (e.g. ClientSSL_{{ .cn }}).
   • Profile type — client-ssl or server-ssl.
   • Virtual servers — optional list of VS names to attach the profile to after update.
   • TLS skip verify — for self-signed management certs during bring-up only.
   • Intermediate chain handling — strict (reject if chain is incomplete) or soft (warn-and-continue). Default: strict.
3. Save → health check queries /mgmt/tm/sys/version to confirm iControl + TMOS version.

05Object naming

Uploaded objects use fingerprint-based names to avoid collisions when multiple certs have the same CN:

• Cert: <cn-or-prefix>_<sha256-8-chars>.crt
• Key: <cn-or-prefix>_<sha256-8-chars>.key
• Chain members: each gets its own _<sha256-8-chars>.crt entry so identical intermediates across different certs deduplicate naturally.

The Client SSL profile name is what you set in the target config — it stays stable across renewals so virtual servers keep their reference.

06Rollback — not supported

After a successful distribution, the old cert/key/chain objects remain in /sys/file. The profile's trio references the new ones. Rolling back means updating the profile to point at the old trio — we don't do that automatically because it disrupts running traffic unpredictably. Operate via F5's own change-management tooling (iApp or Ansible playbook) if you need reversible changes.

07Stale object cleanup

Old cert/key/chain objects remain by design — deleting them on the next deploy would break any profile still referencing them. Clean up out-of-band on a monthly cadence by listing /sys/file/ssl-cert and removing objects not referenced by any profile.

08Troubleshooting

"TMOS version < 13.0 not supported"

Upgrade the BIG-IP. iControl REST before 13.0 has different endpoints that we don't target.

"Chain verification failed"

The cert's intermediate chain doesn't verify against a trusted root on the BIG-IP, or the issuer's intermediate is missing from the deployment. Options: (a) add the missing intermediate to the chain; (b) set Intermediate chain handling to soft if your deployment tolerates it.

"Forbidden — role lacks permission"

Admin user isn't Resource Administrator on the partition, or the partition doesn't exist. Create it or grant access.