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.
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. |
Top-level sections:
[Common]— operating mode and retry/reconnect tuning.[Http]/[Http.MainServer]/[Http.StandbyServer]— used whenCommon.mode = "http".[GRPC.MainServer]/[GRPC.StandbyServer]— used whenCommon.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.
| 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. |
| Key | Type | Default | Notes |
|---|---|---|---|
failoverOnDomainsNotAllowed |
bool | false |
Immediately try the next server when a server returns Domains not allowed, without retrying the refusing server. |
| 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.
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.
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.
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.
| 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. |
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. |
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.
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.comcoversfoo.example.com; - a wildcard entry covers itself and names exactly one label below it:
*.example.comcovers*.example.comandfoo.example.com, but notfoo.bar.example.comand not the apexexample.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"]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"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.
no certificate configured— add at least one[[Certificate]].wrong certificate configuration for <name>—nameanddomainsare 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 knowntype.<action> update action: no such profile: <name>— theprofiledoes not match any entry of the matching profile type.unsupported profile type: <x>— onlyTencentCloud,AliESA, andKubernetesexist 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— setHttp.MainServer.urlwhen in HTTP mode.grpc main server url is empty— setGRPC.MainServer.serverwhen in gRPC mode.file not found: <path>— an mTLS path does not exist.unsupported mode: <x>—Common.modemust behttporgrpc.