Google Cloud Dynamic DNS Client

Note: This is an actively maintained fork of luontola/gcp-dynamic-dns with updated dependencies and modernized GCP SDK.

Automatically sync your public IP address to Google Cloud DNS records. Perfect for home servers, self-hosted services, and dynamic IP environments.

Features

• Multiple IP Detection Methods
  • External web service (default)
  • Local network interface
  • Router via UPnP
• Flexible Authentication
  • Environment variable (JSON string)
  • Mounted credentials file
• Lightweight
  • Minimal Docker image (~10MB)
  • Single static binary
• Multi-Architecture
  • linux/amd64
  • linux/arm64

Table of Contents

• Quick Start
• Installation
  • Docker Compose
  • UnRaid
• Configuration
  • Authentication
  • Environment Variables
• GCP Setup
• Development
• Contributing
• License

Quick Start

docker run -d \
  --name gcp-dynamic-dns \
  --network host \
  --restart always \
  -e DNS_NAMES="example.com." \
  -e GOOGLE_PROJECT="your-project-id" \
  -e GOOGLE_CREDENTIALS_JSON='{"type":"service_account",...}' \
  b1tsized/gcp-dynamic-dns sync

Installation

Docker Compose

services:
  dyndns:
    image: b1tsized/gcp-dynamic-dns
    container_name: gcp-dynamic-dns
    command: sync
    network_mode: host
    restart: always
    environment:
      DNS_NAMES: example.com. www.example.com.
      GOOGLE_PROJECT: your-project-123456
      # Option 1: Credentials as JSON string (recommended)
      GOOGLE_CREDENTIALS_JSON: '{"type":"service_account","project_id":"..."}'
      # Option 2: Credentials as file
      # GOOGLE_APPLICATION_CREDENTIALS: /gcp-keys.json
    # volumes:
    #   - ./gcp-keys.json:/gcp-keys.json:ro

UnRaid

Using credentials from GOOGLE_CREDENTIALS_JSON environment variable
Current IP: 203.0.113.42
Updated DNS: example.com. A -> 203.0.113.42

Configuration

Authentication

Two methods are supported for GCP credentials:

Option 1: Environment Variable (Recommended)

Pass the entire service account JSON as an environment variable:

environment:
  GOOGLE_CREDENTIALS_JSON: '{"type":"service_account","project_id":"...","private_key":"..."}'

Pros: No file mounts, works great with container orchestrators

Option 2: File Mount

Mount the JSON key file into the container:

environment:
  GOOGLE_APPLICATION_CREDENTIALS: /gcp-keys.json
volumes:
  - /path/to/credentials.json:/gcp-keys.json:ro

Environment Variables

* One of GOOGLE_CREDENTIALS_JSON or GOOGLE_APPLICATION_CREDENTIALS is required

IP Detection Modes

Note: Modes interface and upnp require network_mode: host

Default Service URLs

https://ipv4.icanhazip.com/
https://checkip.amazonaws.com/
https://ifconfig.me/ip
https://ipinfo.io/ip

Services are queried in round-robin fashion every 5 minutes.

GCP Setup

1. Go to GCP Console → IAM & Admin → Service Accounts

2. Create a service account

   • Name: dns-updater
   • Role: DNS Administrator (roles/dns.admin)

3. Create a JSON key

   • Click on the service account
   • Keys → Add Key → Create new key → JSON
   • Download and save securely

4. Ensure DNS records exist

   • Records must already exist in Cloud DNS
   • Must be type A records
   • Names must end with . (e.g., example.com.)

Development

Prerequisites

• Go 1.25+
• Docker

Local Development

# Run tests
cd src/app
go test -v ./...

# Build binary
go build -o ../../app

# Run locally
DNS_NAMES="example.com." GOOGLE_PROJECT="test" ./app list-ip

Docker Build

# Build image
docker build -t b1tsized/gcp-dynamic-dns .

# Test container
docker run --rm b1tsized/gcp-dynamic-dns help

CI/CD

Creating a Release

1. Go to Releases → Create a new release
2. Create tag: v2.0.0 (semantic versioning)
3. Click Publish release

The workflow automatically builds multi-arch images and pushes:

• b1tsized/gcp-dynamic-dns:latest
• b1tsized/gcp-dynamic-dns:2.0.0
• b1tsized/gcp-dynamic-dns:2.0
• b1tsized/gcp-dynamic-dns:2

Repository Secrets

Required for releases:

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Changes from Upstream

This fork includes:

• Updated to Go 1.25
• Updated all dependencies to latest versions
• Modernized GCP SDK (dns.NewService() instead of deprecated dns.New())
• Narrower OAuth scope (NdevClouddnsReadwriteScope)
• New: GOOGLE_CREDENTIALS_JSON environment variable support
• New: Multi-architecture Docker images (amd64/arm64)
• New: GitHub Actions CI/CD
• Code quality improvements

License

Apache License 2.0

Original work Copyright © 2023 Esko Luontola

Report Bug · Request Feature