Skip to content

Latest commit

 

History

History
332 lines (267 loc) · 16.4 KB

client.md

File metadata and controls

332 lines (267 loc) · 16.4 KB

certdx client

certdx_client is the standalone consumer. It connects to a certdx server, fetches the certificates you ask for, writes them to disk, and runs your reload command whenever a certificate changes.

A minimal example config is shipped as config/client_config.toml; the fully-annotated reference is config/client_config_full.toml.

Command line

certdx_client [flags]
Flag Default Description
-c, --conf (required) Path to the TOML config file.
-l, --log (stderr) Path to a log file.
-d, --debug false Enable debug logging.
-t, --test false Test mode: skip TLS verification on the HTTP server.
--quit false HTTP mode only. When every configured action is one-shot, fetch each certificate once, wait for all actions, then exit with status 0 on success or 1 on failure.
-h, --help Print help.
-v, --version Print build version.

Configuration file

Top-level sections:

  • [Common] — operating mode and retry/reconnect tuning.
  • [Http] / [Http.MainServer] / [Http.StandbyServer] — used when Common.mode = "http".
  • [GRPC.MainServer] / [GRPC.StandbyServer] — used when Common.mode = "grpc".
  • [[Profile.TencentCloud]] / [[Profile.AliESA]] / [[Profile.Kubernetes]] — named credentials for update actions.
  • [[Certificate]] — one entry per certificate to fetch, each with its update actions.

[Common]

Key Type Default Notes
retryCount int 5 Update actions: retries after a failed run, so an action runs at most retryCount + 1 times. Servers: failed requests (HTTP) or connections (gRPC) to one server before switching to the next.
mode string "http" http or grpc.
reconnectInterval duration string "10m" gRPC only. Reconnect to the server every interval if disconnected; also used to retry the main server while running on the standby.

[Http]

Key Type Default Notes
failoverOnDomainsNotAllowed bool false Immediately try the next server when a server returns Domains not allowed, without retrying the refusing server.

[Http.MainServer] / [Http.StandbyServer]

Key Type Default Notes
url string (required for main) Full URL including the server's apiPath.
authMethod string "token" token or mtls.
token string "" Shared bearer token; required with authMethod = "token".
pem path PEM bundle (client cert + key + CA cert). Required with authMethod = "mtls".

StandbyServer is optional; if url is set, it must also pass validation. The client switches to the standby after retryCount failed requests to the main server, and goes back to the main server after its next successful request; see Renewal cadence.

[GRPC.MainServer] / [GRPC.StandbyServer]

The gRPC endpoint always uses mTLS.

Key Type Notes
server string host:port of the certdx gRPC SDS endpoint.
pem path PEM bundle (client cert + key + CA cert).

StandbyServer is optional. The client switches to the standby after retryCount failed connections to the main server, and retries the main server every reconnectInterval while on the standby.

Generate the mTLS material with certdx_tools (make-ca, make-server, make-client); see tools.md.

[[Certificate]]

Each entry describes one certificate to fetch and one or more update actions describing where it should go.

Key Type Notes
name string Identifies the certificate in logs, and is the file base name used by the file action.
domains string list SANs to request. Wildcards (e.g. *.example.com) are supported when the server uses DNS-01.

At least one [[Certificate.UpdateAction]] is required. Each action table belongs to the [[Certificate]] above it, so keep a certificate's actions together and do not interleave two certificates.

[[Certificate.UpdateAction]]

Every action carries a type key selecting what to do with the renewed material. Actions for one certificate run concurrently, each on its own goroutine, retried up to Common.retryCount times; a failing action never stops the others or the daemon. An attempt that fails in under a second, or with a final verdict such as a failed reload command, is not retried.

With HTTP --quit, the client fetches each configured certificate once, waits for all its update actions, and exits. file, tencentCloud, aliESA, and kubernetes are all one-shot actions. Certificate fetches and actions must all succeed for exit status 0. Unlike the daemon, --quit does not compare the fetched certificate with the previous one: every run delivers to every action, so the file action rewrites its files and runs reloadCommand each time. Use a reload that is safe to repeat at the schedule's frequency.

Schedule --quit at least every ACME.renewTimeLeft of the server, ideally every quarter of it as the daemon does. Without a subscriber the server renews only when asked, so with a longer gap a certificate can expire between runs while every run still exits 0. An action that finds nothing to update, such as a kubernetes action with no matching secret, also counts as success.

type = "file"

Key Type Notes
savePath path Output directory. The certificate is written to <savePath>/<name>.pem and the private key to <savePath>/<name>.key.
reloadCommand string Command executed after a successful write, unless this write created the files. It is split on whitespace and run directly, not through a shell, so quotes, && and variables are not interpreted; put anything more complex in a script. A nonzero exit fails the action and is not retried; commands running longer than 5 minutes are killed. Typical values: systemctl reload nginx, bash /opt/acme/reload.sh.

type = "tencentCloud"

Re-points Tencent Cloud resources at the renewed certificate. On each update it looks up the uploaded certificates whose SANs equal this certificate's domains, picks the newest one that expires before the renewed certificate (by comparing CertEndTime with the renewed certificate's real expiry), and calls UpdateCertificateInstance on it. If the account holds no matching certificate, the action logs a warning and does nothing — it never uploads a certificate that is not already bound. Uploaded certificates that expire after the renewed one are never replaced. A certificate expiring at the same second as the renewed one is checked with DescribeCertificateDetail (grant ssl:DescribeCertificateDetail): if it holds the same certificate it is treated as already uploaded, otherwise (e.g. a same-domain reissue) it is replaced like any other.

The action then polls the deploy record (DescribeHostUpdateRecordDetail) until every resource has been re-bound, for up to five minutes, and reports failed resources as an error. Grant the profile's credentials ssl:DescribeHostUpdateRecordDetail so the update is confirmed; without it the action logs a warning and assumes the deploy succeeded. If Tencent Cloud already stores the renewed certificate (an earlier delivery uploaded it but did not finish), the resources are re-bound to the stored copy instead.

Throttling and other transient API errors are retried with backoff. A deploy that failed or could not be confirmed is reported once and not retried: replaying the upload cannot change the outcome.

Key Type Notes
profile string Name of a [[Profile.TencentCloud]] entry.
resourceTypes string list One or more of clb, cdn, waf, live, vod, ddos, tke, apigateway, tcb, teo.
resourceTypesRegions table list Optional per-resource-type region filter. Every resourceType used here must also appear in resourceTypes.

type = "aliESA"

Uploads a new certificate version at an Alibaba Cloud ESA site using ESA's SetCertificate API. The action matches certificates by the exact SAN set, reuses material already stored at the site, and refuses to upload an older certificate over a newer one. It names uploads certdx-<siteId>-<fingerprint prefix> and targets a soft cap of certdx uploads across that site at retainCount; when multiple SAN groups each need a protected latest upload, the site can remain above that target. If ESA rejects an upload because the plan's custom-certificate quota is full, it deletes one safe older certdx version and retries, repeating only as needed. Uploads with status Expired, ApplyFailed or Canceled are deleted first. It never deletes non-certdx uploads, the latest healthy certdx upload for a SAN set, or a newer upload of that set still being applied. Actions on the same site in one client run one at a time. After GetCertificate reports the new fingerprint with status OK or Expiring, it prunes excess older certdx uploads. This confirms ESA's certificate record, not which certificate every edge node currently serves; verify the live TLS endpoint separately when deploying to production.

Key Type Notes
profile string Name of a [[Profile.AliESA]] entry.
siteId integer ESA site ID returned by ListSites. Must be positive.
retainCount integer Target number of recent certdx uploads to retain across the site. Defaults to 3; 0 also selects the default, and positive values override it. The latest healthy upload for each SAN set remains protected. Each action applies its own value to the whole site, so the smallest value on a site takes effect.

ESA exposes the action in the cn-hangzhou and ap-southeast-1 regions; use one of those regionId values unless an explicit endpoint is configured. The custom-certificate quota depends on the ESA plan. The Free plan allows two custom certificates, so the default retainCount = 3 is above that quota.

Replacing a certificate needs a free slot, because the new version is uploaded before the old one is removed. If the quota is full and no older certdx version can be retired, the upload fails with an error and nothing changes, so keep one spare slot per SAN set. On the Free plan that means a single SAN set and no manual uploads. If cleanup after a confirmed upload cannot reach retainCount, the action only logs a warning.

Setting DEBUG=dara makes the Alibaba Cloud SDK print request headers to stdout, including x-acs-security-token and the signed Authorization header. Do not leave it on where those logs are kept.

type = "kubernetes"

Patches kubernetes.io/tls secrets in place. On each update it lists secrets across all namespaces, keeps the ones annotated with party.para.certdx/domains whose domains this certificate covers, and rewrites tls.crt / tls.key. It never creates secrets and never touches any other field. Secrets already holding the same material are skipped, so consuming pods are not restarted for nothing.

Key Type Notes
profile string Name of a [[Profile.Kubernetes]] entry.

Annotation domains are comma-separated, case-insensitive and de-duplicated. A secret is patched when every annotated domain is covered by one of the certificate's domains:

  • a plain entry covers itself and any subdomain, like the server's allowlist: example.com covers foo.example.com;
  • a wildcard entry covers itself and names exactly one label below it: *.example.com covers *.example.com and foo.example.com, but not foo.bar.example.com and not the apex example.com — list the apex explicitly if the secret needs it.

Only kubernetes.io/tls secrets are listed (a type=kubernetes.io/tls field selector), so other secrets never leave the apiserver.

The service account needs cluster-wide list, get and update on secrets:

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
    name: certdx-client
rules:
    - apiGroups: [""]
      resources: ["secrets"]
      verbs: ["list", "get", "update"]

[[Profile.TencentCloud]] / [[Profile.AliESA]] / [[Profile.Kubernetes]]

Named credentials referenced by update actions. Names are scoped per profile type, so a Tencent Cloud profile and a Kubernetes profile may share a name.

Section Key Notes
[[Profile.TencentCloud]] name Referenced by profile in a tencentCloud action.
secretID / secretKey Tencent Cloud API credentials. Both required.
endpoint Optional, defaults to ssl.tencentcloudapi.com.
[[Profile.AliESA]] name Referenced by profile in an aliESA action.
accessKeyId / accessKeySecret Alibaba Cloud credentials. Both required.
securityToken Optional temporary credential token; static tokens are suitable only for short-lived processes.
regionId ESA API region: cn-hangzhou or ap-southeast-1; defaults to cn-hangzhou.
endpoint ESA API host name, without a scheme or path. Defaults to esa.<regionId>.aliyuncs.com; set this explicitly for a VPC endpoint.
[[Profile.Kubernetes]] name Referenced by profile in a kubernetes action.
kubeConfig Path to a kubeconfig. Empty means in-cluster, then $KUBECONFIG, then ~/.kube/config.

Alibaba Cloud lists the available ESA public and VPC hosts in its service endpoint reference.

Example:

[[Profile.Kubernetes]]
name = "cluster-a"
kubeConfig = ""

[[Certificate]]
name = "wildcard-example"
domains = ["*.example.com", "example.com"]

[[Certificate.UpdateAction]]
type = "file"
savePath = "/etc/ssl/certdx"
reloadCommand = "systemctl reload nginx"

[[Certificate.UpdateAction]]
type = "kubernetes"
profile = "cluster-a"

Renewal cadence

The client polls the server on the same cadence as the server's renewal check (ACME.renewTimeLeft / 4). When the server returns a newer certificate, every update action configured for it runs.

In HTTP mode the client always starts with the main server. If a request fails (unreachable, or the server is still issuing), it retries the same server up to retryCount times, waiting 30 seconds and backing off to 90 seconds. Only then does it try the standby server the same way, so a main and a standby server issuing from different CAs don't alternate. If the standby fails too, the client waits an hour and starts over from the main server. After any successful request the next round starts with the main server.

With Http.failoverOnDomainsNotAllowed = true, a Domains not allowed response skips that server immediately. If all configured servers refuse or fail, the client waits an hour before starting over; --quit reports failure instead. The default is false: a refusal waits for the current polling interval without trying the standby. Other error strings keep this default behavior regardless of the setting.

The file action's writes are atomic via a temp-file-and-rename, so a downstream service reading the cert mid-update never observes a torn or partial file. Its reload command runs only when both <savePath>/<name>.pem and .key already existed — the very first install is treated as a bootstrap where the downstream service is not yet up.

Common validation errors

  • no certificate configured — add at least one [[Certificate]].
  • wrong certificate configuration for <name> — name and domains are both required.
  • certificate <name> has no update action configured — add at least one [[Certificate.UpdateAction]].
  • update action #<n>: no type set / unsupported type: <x> — every action needs a known type.
  • <action> update action: no such profile: <name> — the profile does not match any entry of the matching profile type.
  • unsupported profile type: <x> — only TencentCloud, AliESA, and Kubernetes exist under [Profile].
  • unsupported key in profile <type>: <key> — check the spelling of a field inside a known [[Profile.<type>]] table.
  • http main server url is empty — set Http.MainServer.url when in HTTP mode.
  • grpc main server url is empty — set GRPC.MainServer.server when in gRPC mode.
  • file not found: <path> — an mTLS path does not exist.
  • unsupported mode: <x> — Common.mode must be http or grpc.