Deploying Certificates

Issuing a certificate is only half the job. The other half is getting the leaf, its chain, and the private key onto every device that terminates TLS for that name — and rebinding the SSL profile if you're rotating to a new object. Versus treats deployment as a distinct, auditable stage of certificate lifecycle: a managed certificate that has been issued is pushed to its deployment targets through a vendor-aware dispatcher, recorded per target, and verified over the wire.

This page covers what happens when a certificate is deployed, the two deployment modes, how targets are discovered, and how the built-in deploy workflow ties it together. For issuance (CSR generation, ACME DNS-01, the Versus CA) see Certificates.

---

What "deploy" means

A deploy takes an issued ManagedCertificate and, for each target, writes the certificate material onto the device and makes the SSL profile serve it. Everything flows through one dispatcher, deploy_client.push(), which routes to a per-vendor deployer based on the device's vendor:

push(device, profile_name, cert_pem, chain_pem, key_pem,
     deployment_mode='overwrite', new_cert_name='', cert_object_name='')
  → { "success": bool, "message": str, "cert_object_name": str }

• cert_pem / chain_pem — the leaf and the intermediate chain, stored separately on the certificate record and recombined per vendor (F5 wants a bundled leaf+chain; NetScaler wants them split).
• key_pem — the private key. Only certificates issued with a Versus-generated key (key_source = versus) can be deployed this way; the key is held encrypted at rest in Versus. Certificates whose key was generated on the device never leave the box and take a different install path.
• cert_object_name — the exact cert object on the device to overwrite, resolved by the discovery step from the profile's current binding.

The dispatcher catches per-device failures and returns a structured result rather than raising, so one unreachable device doesn't abort a multi-target deploy.

---

Two deployment modes

Every deploy runs in one of two modes, carried on the certificate as deployment_mode and overridable per run:

In overwrite mode the deployer writes to the resolved bound object and touches nothing else. In rename_update mode it uploads the new object, then rebinds the profile (or virtual server, or vserver) to point at it — so the switchover is a single binding change you can back out by rebinding to the previous object.

---

Per-vendor behavior

Deployment is vendor-specific under the hood but presents the same two-mode contract everywhere. The dispatcher supports on-prem ADCs and cloud WAF/CDN edges alike:

For the F5 BIG-IP path, the deployer routes through the collector plane automatically when the target is a site-bound, private-LAN device — the same outbound-only tunnel used for every other F5 operation — and falls back to a direct REST call otherwise. The tunnel is always closed after the push. See F5 BIG-IP Integration for how those devices are enrolled.

Cloud edges are treated as ordinary devices in inventory, so a renewal reaches an Azure Front Door secret or a Cloudflare zone certificate exactly the way it reaches an F5 virtual server. See Cloud WAF & CDN.

---

Finding the targets

You can name deployment targets explicitly, or let Versus find them.

A deployment target is a small record:

{
  "device_id": 42,
  "profile_name": "/Common/app-clientssl",
  "cert_object_name": "app_example_com",
  "new_cert_name": ""
}

• Explicit targets — if the certificate already carries deployment_targets, they're used as-is and auto-discovery is skipped.
• Auto-discovery — the cert.discover_targets step matches the managed certificate's CN and SANs against every discovered device certificate in inventory, then finds the SSL profiles bound to those certs. It resolves each profile's currently bound cert object into cert_object_name, so an overwrite lands on exactly the object already in service. Discovery covers F5 today, and you can restrict it to client, server, or both profile sides.

Auto-discovery means "renew the cert for app.example.com" fans out to every F5 profile actually serving that name, without you maintaining a device list by hand.

---

The deploy step

cert.deploy_to_adcs is the worker. For each target it:

1. Loads the device (with its credential) and logs the target and mode.
2. Calls deploy_client.push() with the certificate's stored leaf, chain, and private key.
3. Records the result in a CertificateDeployment row — one per (certificate, device, profile_name) — capturing the actual object written (the resolved bound object, or the year-suffixed name on a rename), the status, who deployed it, and the workflow run.

A per-run deployment_mode_override takes precedence over the certificate's stored mode, so an operator can force a rename_update for one rotation from the Deploy button without changing the record. The step needs both an issued certificate (pem_certificate) and a private key on the record; if either is missing it fails fast. When every target succeeds, the certificate advances to deployed.

Each deployment is tracked durably:

---

Verifying the result

After a deploy, cert.verify_tls opens a TLS connection to each deployed target on port 443 and confirms the endpoint presents a certificate, stamping last_verified on success. It's a liveness check that the rebind took effect end-to-end — a failed verification is surfaced as a warning on the run without rolling anything back, so you can investigate a target that didn't come up cleanly.

---

The built-in deploy workflow

Versus ships a built-in Deploy Managed Certificate workflow (cert-deploy) that wires these steps together:

Deploy Certificate (trigger)
  → Discover cert-using devices
  → Approval required?  ──yes──►  Await Deploy Approval
                        └──no───┐         │
                                ▼         ▼
                        Deploy to ADCs
                        → Verify TLS
                        → Done

Because the workflow is marked production, the Versus Desk change gate and back-out light up automatically: if the workflow is configured under a change window, triggering it opens a Change ticket and the deploy runs only once that change is approved and scheduled. The approval branch also pauses the run in-flight so a reviewer can inspect the discovered targets and the deployment mode before anything is pushed.

You run it from the certificate's Deploy action in the UI, or over the API like any other workflow.

Deploying over the API

Trigger the deploy workflow by name and pass the certificate id in context:

POST /api/workflow-trigger/
Authorization: Bearer …
Content-Type: application/json

{
  "workflow": "Deploy Managed Certificate",
  "run_name": "Renew app.example.com",
  "context": {
    "cert_id": 128,
    "deployment_mode_override": "rename_update"
  }
}

201 Created
{ "run_id": 91, "status": "pending", "status_url": "/api/workflow-status/91/" }

Poll GET /api/workflow-status/91/ for the per-step, per-device breakdown, and clear the approval gate with resume_approval if the workflow is gated. The full request/response contract — authentication, staged execution with stop_after_section, approvals, retries, and back-out — is in Running Workflows via the API.

---

How it fits the platform

Deployment reuses the platform's existing planes rather than introducing its own: device credentials come from the Versus Vault, private keys are held encrypted on the certificate record, private-LAN devices are reached over the outbound-only collector plane, and the whole operation runs as a durable, auditable workflow with change-gating and back-out. Every push leaves a CertificateDeployment record, so at any moment you can answer "which devices serve this certificate, and when were they last verified?" — the same question that drives renewal.

Because renewals carry the certificate's deployment_mode and deployment_targets forward, a renewal re-runs the identical deploy against the identical targets — the operator effort is front-loaded into the first deploy, and every rotation after that is hands-off.

---

Related

• Certificates — issuance, the Versus CA, ACME, and the certificate record deployed here.
• F5 BIG-IP Integration — enrolling the ADCs that receive certificates.
• Cloud WAF & CDN — deploying to cloud edges (F5 XC, Cloudflare, Akamai, Azure Front Door, and more).
• Running Workflows via the API — trigger and supervise the deploy workflow from your own tooling.
• Secret Vault — where the device credentials used to push certificates are stored.
• Collector Security — the outbound-only path to private-LAN devices.