Skip to content
local-cert
Browse the documentation

Google Cloud provider

local-cert manages Cloud DNS as a service account, using its JSON key. One provider corresponds to one Google Cloud project.

Before you start

  • The Cloud DNS API is enabled on the project (APIs & Services → Library → Cloud DNS API).
  • The zone is public. A private zone is invisible to Let's Encrypt.

1. Create the service account

  1. Google Cloud console, the project that holds your zones → IAM & Admin → Service Accounts → Create service account.
  2. Name: local-cert-dns. Create and continue.
  3. Role: DNS Administrator (roles/dns.admin). Continue, then Done.

Or from the command line:

gcloud
PROJECT=my-project
gcloud iam service-accounts create local-cert-dns --project "$PROJECT"
gcloud projects add-iam-policy-binding "$PROJECT" \
  --member "serviceAccount:local-cert-dns@$PROJECT.iam.gserviceaccount.com" \
  --role roles/dns.admin

2. Create the JSON key

  1. Open the service account → Keys tab → Add key → Create new key → JSON.
  2. A .json file is downloaded: it is the only copy.
gcloud
gcloud iam service-accounts keys create local-cert-dns.json \
  --iam-account "local-cert-dns@$PROJECT.iam.gserviceaccount.com"

3. Create the provider

  1. Providers → + New provider → Google Cloud.
  2. Give it a name and paste the entire content of the JSON file. The project ID is read from the key; only fill it in if the zones are in a different project.
  3. Test connection, then Save. Then delete the downloaded file.

4. Add a domain

Domains → + Add a domain → this provider → the zone. The test creates and then deletes a temporary TXT record.

Good to know

  • The roles/dns.admin role applies to every zone in the project. To isolate a zone, put it in a dedicated project, or grant the role at the zone level rather than the project level (the managed zone's IAM) while keeping roles/dns.reader for the account on the project, for listing.
  • The domain must be delegated to the name servers Cloud DNS gives for the zone (ns-cloud-*.googledomains.com).
  • Several projects: one provider per project, each with its own service account — or a single service account that each project grants the role to, declared as many providers with different project IDs.

Troubleshooting

MessageCause
invalid_grantKey deleted or service account disabled; server clock out of sync.
403 … Cloud DNS API has not been usedThe Cloud DNS API isn't enabled on the project.
403 ForbiddenThe service account doesn't have the DNS role on this project.
The service account key is not valid JSONThe file was only partially pasted.