Skip to main content

MerlinCDN module

Uploads a certificate to MerlinCDN and binds it to a CDN distribution's canonical-name (CNAME). MerlinCDN certificates are immutable, so every renewal uploads a fresh certificate and re-binds.

Overview​

  • Transport: MerlinCDN REST API (https://api.merlincdn.com by default; overridable per target).
  • Auth: a personal access token (Bearer) plus a merlin-organization-id and merlin-workspace-id header.
  • Certificates are immutable: there is no update-in-place. Each deployment uploads a new certificate (a new numeric id) and re-points a CNAME at it.
  • Rollback: conditional — available only when delete_old_cert is off (the previous certificate still exists).

Prerequisites​

  • A MerlinCDN CDN distribution and a canonical-name (CNAME) under it, or a domain the module can create the CNAME for.
  • A personal access token with certificate + canonical-name permissions, plus your organization and workspace ids.

Create the module credential​

Settings → Distribution → Credentials → Add Credential → type MerlinCDN Token. Provide:

  • Personal Access Token — the Bearer token.
  • Organization ID — sent as merlin-organization-id.
  • Workspace ID — sent as merlin-workspace-id.

Stored as an envelope-encrypted JSON blob:

{
    "personal_access_token": "<merlin PAT>",
    "organization_id": "<merlin-organization-id>",
    "workspace_id": "<merlin-workspace-id>"
}

Create a MerlinCDN target​

Settings → Distribution → Targets → Add Target → type MerlinCDN:

  • Distribution ID (required) — the CDN distribution the CNAME lives under.
  • API Host (optional) — defaults to https://api.merlincdn.com.
  • Canonical Name ID (optional) — the specific CNAME to re-point (takes priority).
  • Domain (optional) — used to match or create the CNAME when Canonical Name ID is empty.
  • Delete old certificate (default on) — remove the previous certificate after the re-bind.

Execution flow​

  1. Authenticate with the token + organization/workspace headers.
  2. Upload the certificate (POST /v1/cdn/certificates, multipart cert_file + key_file) → a new certificate id. If the upload fails nothing is bound.
  3. Resolve the CNAME: explicit canonical_name_id → previous run → match/create by domain.
  4. Bind: PATCH /v1/cdn/distributions/:id/canonical-names/:cnameId with the new certificate_id. If the bind fails, the just-uploaded certificate is deleted (orphan cleanup).
  5. If delete_old_cert is on, best-effort delete the previous certificate.

Rollback​

Rollback re-binds the CNAME to the previous certificate stored in the target's remote state.

  • delete_old_cert = false → the previous certificate is kept → rollback is available.
  • delete_old_cert = true (default) → the previous certificate is deleted after the re-bind → rollback is unavailable. Disable delete_old_cert if you need one-click rollback.

Because execute uploads before it binds, an upload failure never changes the live CDN state.

Troubleshooting​

  • MERLINCDN_AUTH — the token, organization id, or workspace id was rejected.
  • MERLINCDN_NOT_FOUND — the distribution or canonical-name id does not exist.
  • MERLINCDN_UPLOAD / MERLINCDN_BIND — the certificate upload or the CNAME re-bind failed.
  • MERLINCDN_QUOTA / MERLINCDN_CONNECT — rate limited or a connection failure (both retried).

See also​