mirror of
https://github.com/shankar0123/certctl.git
synced 2026-06-07 12:21:31 +00:00
shankar0123
ecb8896b1c
Phase 4 structural (commit 633e440) moved 6 connector files into the
new docs/reference/connectors/ subdirectory but didn't update all
inter-doc references for the new path layout. Phase 11 caught the
high-traffic ones; this sweep gets the rest, found by the Phase 4
follow-on verification pass.
Mappings applied (relative to docs/reference/connectors/):
deployment-atomicity.md → ../deployment-model.md
deployment-vendor-matrix.md → ../vendor-matrix.md
architecture.md → ../architecture.md
est.md → ../protocols/est.md
scep-intune.md → ../protocols/scep-intune.md
async-polling.md → ../protocols/async-ca-polling.md
quickstart.md → ../../getting-started/quickstart.md
demo-advanced.md → ../../getting-started/advanced-demo.md
legacy-est-scep.md → ../protocols/scep-server.md
connectors.md → index.md
Plus prose backtick references (`docs/architecture.md` etc.) updated
to the new subdirectory paths.
Files touched: apache, f5, iis, k8s, nginx, index. 33 line changes.
Full link-check across docs/reference/connectors/*.md is now clean
(0 broken inter-doc references).
172 lines
5.5 KiB
Markdown
172 lines
5.5 KiB
Markdown
# F5 BIG-IP Connector — Operator Deep-Dive
|
|
|
|
> Last reviewed: 2026-05-05
|
|
>
|
|
> Per Phase 14 of the deploy-hardening II master bundle. For the
|
|
> connector-development context (interface contract, registry, atomic
|
|
> deploy primitive shared across all targets), see the
|
|
> [connector index](index.md).
|
|
|
|
## 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/reference/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
|
|
|
|
```bash
|
|
# 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](../deployment-model.md)
|
|
- [Vendor compatibility matrix](../vendor-matrix.md)
|
|
- F5 official iControl REST docs: <https://clouddocs.f5.com/api/icontrol-rest/>
|