sakuracloud

package module
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Mar 28, 2026 License: MIT Imports: 16 Imported by: 0

README

caddy-sakuracloud

A Caddy DNS module for Sakura Cloud DNS, implementing the libdns interfaces. This enables Caddy to solve ACME DNS-01 challenges via the Sakura Cloud DNS API, which is required for wildcard TLS certificates.

During certificate issuance and renewal, Caddy creates and removes _acme-challenge TXT records automatically via this module.

Requirements

Build

xcaddy build --with github.com/kamakiri-labs/caddy-sakuracloud

Configuration

Caddyfile
*.example.com {
    tls {
        dns sakuracloud {
            api_token {env.SAKURACLOUD_ACCESS_TOKEN}
            api_secret {env.SAKURACLOUD_ACCESS_TOKEN_SECRET}
        }
    }
    # ...
}
JSON
{
    "module": "sakuracloud",
    "api_token": "{env.SAKURACLOUD_ACCESS_TOKEN}",
    "api_secret": "{env.SAKURACLOUD_ACCESS_TOKEN_SECRET}"
}
Environment variables

If api_token or api_secret are not set in the Caddyfile or JSON config, the module falls back to these environment variables. Explicit Caddyfile/JSON values always take precedence.

Variable Description
SAKURACLOUD_ACCESS_TOKEN Sakura Cloud API token
SAKURACLOUD_ACCESS_TOKEN_SECRET Sakura Cloud API secret

These are the same environment variables used by the official sacloud tools.

Supported record types

A, AAAA, ALIAS, CAA, CNAME, HTTPS, MX, NS (read-only), PTR, SVCB, SRV, TXT

NS records are returned by GetRecords but are protected from removal by SetRecords and DeleteRecords to prevent accidental zone breakage.

Known limitations

  • Single writer per zone recommended. The module uses optimistic concurrency control (SettingsHash) and per-zone mutexes to handle conflicts, but running multiple Caddy instances managing the same zone is not recommended without external coordination.
  • Credential rotation requires process restart. API credentials are captured on first use and cannot be changed without restarting Caddy.
  • Zone metadata is cached for the lifetime of the process. If a DNS zone is deleted and recreated externally with the same name, Caddy must be restarted to pick up the new zone ID.
  • SDK rate limit. The Sakura Cloud SDK defaults to 5 requests/second.
  • Startup API call. On startup or reload, a lightweight API call validates credentials. Failures are logged as warnings and do not block startup, but startup latency is coupled to API response time.

Troubleshooting

Credentials not working: Verify your API credentials with curl:

curl -s -u "$SAKURACLOUD_ACCESS_TOKEN:$SAKURACLOUD_ACCESS_TOKEN_SECRET" \
  https://secure.sakura.ad.jp/cloud/zone/is1a/api/cloud/1.1/commonserviceitem

A successful response returns a JSON object with your DNS zones.

Zone not found: Ensure the domain is registered as a DNS zone in your Sakura Cloud account and that the API credentials have access to it.

Update conflict (HTTP 409): This occurs when multiple writers modify the same zone concurrently. The module retries conflicts automatically (up to 3 times with jitter), but persistent conflicts indicate multiple Caddy instances competing for the same zone. Other API errors (auth failures, invalid records, etc.) are not retried and are reported immediately.

Acknowledgements

Design informed by studying these open source projects:

Development assisted by Claude Code and Codex.

License

MIT

Documentation

Index

Constants

This section is empty.

Variables

View Source
var (
	// ErrZoneNotFound is returned when the requested DNS zone does not exist
	// in the Sakura Cloud account.
	ErrZoneNotFound = errors.New("sakuracloud: zone not found")

	// ErrRetriesExhausted is returned when a mutation fails after all retry
	// attempts due to update conflicts.
	ErrRetriesExhausted = errors.New("sakuracloud: update retries exhausted")

	// ErrEmptySettingsHash is returned when the API returns an empty SettingsHash,
	// which would silently skip the optimistic concurrency check.
	ErrEmptySettingsHash = errors.New("sakuracloud: empty SettingsHash")
)

Functions

This section is empty.

Types

type Provider

type Provider struct {
	// API credentials — set via Caddyfile, JSON config, or environment variables.
	APIToken  string `json:"api_token,omitempty"`
	APISecret string `json:"api_secret,omitempty"`
	// contains filtered or unexported fields
}

Provider implements the libdns interfaces for Sakura Cloud DNS.

func (*Provider) AppendRecords

func (p *Provider) AppendRecords(ctx context.Context, zone string, recs []libdns.Record) ([]libdns.Record, error)

AppendRecords adds records to the zone, skipping duplicates (matched on Name+Type+RData).

func (*Provider) CaddyModule

func (*Provider) CaddyModule() caddy.ModuleInfo

func (*Provider) DeleteRecords

func (p *Provider) DeleteRecords(ctx context.Context, zone string, recs []libdns.Record) ([]libdns.Record, error)

DeleteRecords removes records from the zone. Records are matched on Name, and optionally on Type, TTL, and Data (empty values act as wildcards per libdns spec). Only records that actually existed are returned.

func (*Provider) GetRecords

func (p *Provider) GetRecords(ctx context.Context, zone string) ([]libdns.Record, error)

GetRecords returns all DNS records in the zone.

func (*Provider) Provision

func (p *Provider) Provision(ctx caddy.Context) error

func (*Provider) SetRecords

func (p *Provider) SetRecords(ctx context.Context, zone string, recs []libdns.Record) ([]libdns.Record, error)

SetRecords creates or updates records in the zone. For any (name, type) pair in the input, all existing records with that pair are replaced by the input records.

func (*Provider) UnmarshalCaddyfile

func (p *Provider) UnmarshalCaddyfile(d *caddyfile.Dispenser) error

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL