mirror of
https://github.com/shankar0123/certctl.git
synced 2026-06-07 15:41:41 +00:00
shankar0123
633e440787
Per Phase 1 audit at cowork/docs-overhaul-phase-1-audit-2026-05-04/.
Phase 4 in the audit recommended a full split of connectors.md (2055
lines) into an index + 27 per-connector pages (12 issuer + 15 target).
This commit lands the structural half of that work; full per-target
page extraction is deferred to follow-up commits.
Renames (all blame-preserving):
docs/connectors.md → docs/reference/connectors/index.md
docs/connector-apache.md → docs/reference/connectors/apache.md
docs/connector-f5.md → docs/reference/connectors/f5.md
docs/connector-iis.md → docs/reference/connectors/iis.md
docs/connector-k8s.md → docs/reference/connectors/k8s.md
docs/connector-nginx.md → docs/reference/connectors/nginx.md
Edits:
- docs/reference/connectors/index.md gets a top-of-doc note
explaining the per-connector deep-dive sibling pattern + a forward
list of the 5 per-target pages.
- The 5 per-connector deep-dive pages each get a `Last reviewed:
2026-05-05` header + a back-link to the index.
Deferred to future commits (Phase 4b/c follow-on):
- Extracting the 12 issuer sections from index.md into per-issuer
pages at reference/connectors/{acme,awsacmpca,digicert,ejbca,
entrust,globalsign,googlecas,local,openssl,sectigo,stepca,vault}.md
- Extracting the 10 remaining target sections from index.md into
per-target pages at reference/connectors/{caddy,traefik,envoy,
haproxy,postfix-dovecot,ssh,javakeystore,wincertstore,awsacm,
azurekv}.md
The pragmatic split makes this Phase 4 work incrementally landable —
each per-connector extraction is a small follow-up commit that doesn't
change the docs/ tree shape further. Cross-references from README.md
and other docs to docs/connectors.md still need fixing in Phase 11.
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/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
|
|
|
|
```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-atomicity.md)
|
|
- [Vendor compatibility matrix](deployment-vendor-matrix.md)
|
|
- F5 official iControl REST docs: <https://clouddocs.f5.com/api/icontrol-rest/>
|