SakuraCloud External-DNS Webhook Provider

July 25, 2025 · View on GitHub

ExternalDNS is a Kubernetes plugin for automating DNS record management for Kubernetes resources. By default, Kubernetes only handles internal cluster DNS. ExternalDNS delegates DNS record synchronization to external providers (e.g., SakuraCloud, AWS Route 53, etc.).

This project implements a Webhook Provider for SakuraCloud, allowing ExternalDNS to manage SakuraCloud DNS zones via standard webhook calls. It fully adheres to the official ExternalDNS Webhook Provider specification, enabling seamless integration into any existing ExternalDNS deployment. For more details, see the official documentation: kubernetes-sigs/external-dns.

Important

If an upgrade path between versions is listed here, please make sure to follow those paths without skipping a version! Otherwise, inconsistencies or errors may occur.

Warning

Please familiarize yourself with the limitations before using this provider!

Features

Leverages sacloud/iaas-api-go and sacloud/iaas-service-go SDKs
Full Webhook Provider compliance with ExternalDNS specs
Support for ALIAS records, TXT registry, and custom endpoint adjustment
Minimal, container-friendly deployment (Helm Chart support coming)
Comprehensive unit tests and CI/CD workflows

Supported Platforms

Architectures: amd64, arm64
Kubernetes >=1.20
ExternalDNS versions up to v0.18.0

Requirements

SakuraCloud API Token & Secret
Existing DNS Zone in SakuraCloud

Note

For more information, please refer to the link below.

Usage

0. Download Releases

Download pre-built binaries or Docker images from Releases.

1. Configuration Options

Flag	Env Var	Description	Required	Default
`--sakura-api-token`	`SAKURA_API_TOKEN`	SakuraCloud API Token	Yes
`--sakura-api-secret`	`SAKURA_API_SECRET`	SakuraCloud API Secret	Yes
`--zone-name`	`ZONE_NAME`	SakuraCloud DNS zone (e.g. `example.com`)	Yes
`--provider-ip`	`PROVIDER_IP`	Webhook listen address	No	`0.0.0.0`
`--provider-port`	`PROVIDER_PORT`	Webhook listen port	No	`8080`
`--registry-txt`		Enable TXT registry mode	No	`false`
`--txt-owner-id`		TXT registry owner ID	No	`default`
`--config`	`CONFIG_FILE_PATH`	Path to configuration file (YAML format)	No

2. Deployment

2-1. Quick Deploy Script

Executes:

Delete existing test resources
Deploy Webhook Provider
Deploy ExternalDNS Controller
Deploy sample app and Ingress rules

Usage:

Update the parameters at the top of example/reset-and-deploy.sh, including the SakuraCloud API Token, Secret, and DNS Zone name. Then update the sample app’s target accordingly.

You can edit the environment variable assignments directly in the script header.
Ensure your Kubernetes cluster is properly configured and accessible.

From the project root directory, run:

bash example/reset-and-deploy.sh

The script will sequentially tear down and re-deploy all resources, printing detailed logs for each step.
Upon completion, verify the deployed resources, for example:

kubectl get pod -n <namespace>
kubectl get ingress -n <namespace>

Note

The script defaults to the default namespace; adjust as needed for your environment.

Warning

This script is intended for testing and development purposes only. Do not use it in production environments.

2-2. Helm Chart (coming soon)

Architecture Flow

sequenceDiagram
  participant C as External-DNS Controller
  participant W as Webhook Provider
  participant S as SakuraCloud DNS SDK

  C->>W: GET /records
  W-->>C: 200 OK + []

  C->>W: POST /adjustendpoints
  W-->>C: 200 OK + []

  C->>W: POST /records (create)
  W->>S: CreateRecord/Alias/TXT + Delete
  S-->>W: success
  W-->>C: 204 No Content

  Note over C,W: Subsequent sync cycles...

Advanced ALIAS Support

sequenceDiagram
  participant C as Controller
  participant W as WebhookProvider
  participant S as SakuraCloudAPI

  C->>W: GET /records
  W->>S: ListRecords()
  S-->>W: DNS records list
  W-->>C: Endpoint list

  C->>W: POST /adjustendpoints []
  W-->>C: []

  C->>W: POST /records (create alias)
  W->>S: ApplyChanges(ALIAS + TXT)
  S-->>W: success
  W-->>C: 204 No Content

  C->>W: POST /adjustendpoints []
  W-->>C: []

  C->>W: POST /records (delete alias)
  W->>S: ApplyChanges(delete ALIAS + TXT)
  S-->>W: success
  W-->>C: 204 No Content

Limitations

Only supports A, CNAME, & TXT record types
Currently SakuraCloud does not support AAAA or MX via this webhook
SakuraCloud DNS API only supports a single target (RData) per DNS record. Multiple targets (e.g. multiple A or TXT values for the same name) are not supported; each must be a separate record.