Skip to content
local-cert
Browse the documentation

DNS providers

A provider is an account at the host of your DNS zones, with the credentials that let local-cert write there. This is how the proof Let's Encrypt asks for gets published: a TXT record set for the duration of the validation.

Supported hosts

HostServiceCredentialsMinimum TTLGuide
AWSRoute53IAM key, role recommended30 sopen
OVHcloudOVHcloud DNS zonesAPI region, Application key, Application secret, Consumer key60 sopen
GandiLiveDNSPersonal Access Token300 sopen
GoDaddyGoDaddy DNSAPI key, API secret600 sopen
Google CloudCloud DNSService account key (JSON)1 sopen

The principle, whichever host you use

  1. At the host, you create credentials limited to DNS — never those of your main account.
  2. Providers → + New provider: you pick the host, paste the credentials, test, save.
  3. Domains → + Add a domain: local-cert lists the account's zones, you pick one, and it tests its permissions.

Several providers on the same host is the normal case: one per account, or one per permission scope. Secrets are encrypted in the database (AES-256-GCM with MASTER_KEY) and are never displayed again or returned by the API.

What differs from one host to another

AWS Route53The others
Permissionsper zone: an IAM policy to extend with every domain addedcarried by the credentials: nothing to change when you add a domain
Permission testno write at all in the zonea temporary TXT record (_localcert-preflight-…) is created and then deleted
Writesatomic, tracked until propagationrecord by record

Marking what local-cert creates

Every record published at your request comes with a TXT _local-cert.<name>: this is what lets you tell, in the zone, what comes from local-cert from what was already there. Setting TAG_RECORDS=0 turns it off.

Declaring a provider with environment variables

When credentials must come from the deployment rather than the database, a provider can be declared with variables. This is optional, and the block is repeated with a different label for each account.

.env
# PROVIDER_<HOST>_<LABEL>_NAME declares the provider; the rest are its credentials
PROVIDER_AWS_DEFAULT_NAME="Default AWS"
PROVIDER_AWS_DEFAULT_ACCESS_KEY_ID=AKIA…
PROVIDER_AWS_DEFAULT_SECRET_ACCESS_KEY=…
PROVIDER_AWS_DEFAULT_ROLE_ARN=arn:aws:iam::123456789012:role/local-cert-dns

PROVIDER_OVH_PERSO_NAME="ovh-perso"
PROVIDER_OVH_PERSO_ENDPOINT=ovh-eu
PROVIDER_OVH_PERSO_APPLICATION_KEY=…
PROVIDER_OVH_PERSO_APPLICATION_SECRET=…
PROVIDER_OVH_PERSO_CONSUMER_KEY=…

PROVIDER_GANDI_MAIN_NAME="gandi"
PROVIDER_GANDI_MAIN_TOKEN=…

PROVIDER_GODADDY_MAIN_NAME="godaddy"
PROVIDER_GODADDY_MAIN_API_KEY=…
PROVIDER_GODADDY_MAIN_API_SECRET=…

PROVIDER_GCP_MAIN_NAME="gcp"
PROVIDER_GCP_MAIN_SERVICE_ACCOUNT_JSON=<the key's JSON, or its base64 encoding>
PROVIDER_GCP_MAIN_PROJECT_ID=my-project   # optional
  • The label (DEFAULT, PERSO, MAIN…) is free: uppercase letters, digits and underscores.
  • These providers appear in the console with an environment tag. They can be tested, but not edited or removed: that is done in the variables, followed by a restart. Their secrets are never written to the database.
  • An incomplete declaration is ignored, with a message at startup naming the missing variable.