volcengine

README

VolcEngine DNS for libdns

This package implements the libdns interfaces, allowing you to manage DNS records with the VolcEngine DNS API.

The official VolcEngine Go SDK is available here.

Authenticating

To authenticate you need to supply your AccessKeyID and AccessKeySecret to the Provider. You can obtain these credentials from the VolcEngine Console.

The credentials can be provided in two ways:

1. Environment variables: Set ACCESS_KEY_ID and ACCESS_KEY_SECRET environment variables
2. Direct configuration: Set AccessKeyID and AccessKeySecret in the Provider struct

Domain Identification

VolcEngine DNS API uses ZID (Zone ID) to identify domains. This provider supports three ways to specify a domain, with the following priority order:

1. ZID (highest priority): Set Provider.ZID directly with the domain ID (e.g., 304092)
2. Zone field: Set Provider.Zone with the domain name (e.g., example.com), and the provider will automatically look up the corresponding ZID using the ListZones API
3. zone parameter: Pass the domain name as the zone parameter in method calls (e.g., GetRecords(ctx, "example.com"))

Priority: Provider.ZID > Provider.Zone > zone parameter

Example

Here's a minimal example of how to get all your DNS records using this libdns provider:

package main

import (
	"context"
	"fmt"
	"github.com/libdns/volcengine"
)

func main() {
	provider := volcengine.Provider{
		CredentialInfo: volcengine.CredentialInfo{
			AccessKeyID:     "<AccessKeyID from your VolcEngine console>",
			AccessKeySecret: "<AccessKeySecret from your VolcEngine console>",
		},
		// Option 1: Set ZID directly if you know it (highest priority)
		// ZID: 304092,
		// Option 2: Set Zone domain name, will auto-lookup ZID via ListZones API
		// Zone: "example.com",
	}

	// GetRecords: if Provider.ZID or Provider.Zone is set, zone parameter can be empty
	// Otherwise, pass domain name as zone parameter
	records, err := provider.GetRecords(context.TODO(), "example.com")
	if err != nil {
		fmt.Println(err.Error())
		return
	}

	for _, record := range records {
		tmp := record.RR()
		fmt.Printf("%s %v %s %s\n", tmp.Name, tmp.TTL.Seconds(), tmp.Type, tmp.Data)
	}
}

For complete demo check _demo/demo.go

ACME DNS-01 Support

This provider fully supports ACME DNS-01 challenges for Let's Encrypt and other ACME certificate providers.

What is ACME DNS-01 Challenge?

ACME DNS-01 challenge is a method used by Let's Encrypt and other ACME providers to verify domain ownership before issuing SSL/TLS certificates. The process works as follows:

1. Challenge Request: When you request a certificate, the ACME server provides a challenge token
2. DNS Record Creation: Your ACME client (e.g., Caddy, cert-manager, Traefik) creates a TXT record:
   • Name: _acme-challenge.<your-domain>
   • Value: The challenge token provided by ACME server
3. Verification: The ACME server queries this TXT record to verify you control the domain
4. Cleanup: After verification, the challenge record is deleted

How libdns Enables ACME DNS-01 Support

The libdns library provides a standardized interface for DNS record management. ACME clients use libdns providers to:

• Add challenge TXT records (AppendRecords)
• Delete challenge TXT records (DeleteRecords)

Since this provider implements all required libdns interfaces, it automatically works with any ACME client that supports libdns.

Supported ACME Clients

This provider can be used with any ACME client that supports libdns, including:

• Caddy - Automatic HTTPS with DNS-01 challenge
• cert-manager - Kubernetes certificate management
• Traefik - Cloud-native reverse proxy
• acme.sh - Shell script for ACME
• lego - Let's Encrypt client and ACME library

Example: Using with Caddy

Configure Caddy to use this provider for DNS-01 challenges:

Option 1: Using ZID (recommended for better performance)

{
  "apps": {
    "tls": {
      "challenges": {
        "dns": {
          "provider": {
            "name": "volcengine",
            "access_key_id": "your_access_key_id",
            "access_key_secret": "your_access_key_secret",
            "zid": 304092
          }
        }
      }
    }
  }
}

Option 2: Using Zone (domain name)

{
  "apps": {
    "tls": {
      "challenges": {
        "dns": {
          "provider": {
            "name": "volcengine",
            "access_key_id": "your_access_key_id",
            "access_key_secret": "your_access_key_secret",
            "zone": "example.com"
          }
        }
      }
    }
  }
}

Note: You can use either zid or zone (not both). If both are provided, zid takes priority. The zone option will automatically look up the corresponding ZID using the ListZones API.

Implementation Details

This provider implements the following libdns interfaces required for ACME DNS-01 support:

• ✅ RecordGetter (GetRecords) - Query existing records
• ✅ RecordAppender (AppendRecords) - Create challenge TXT records
• ✅ RecordDeleter (DeleteRecords) - Remove challenge TXT records after verification
• ✅ RecordSetter (SetRecords) - Update records if needed

The provider automatically:

• Extracts the root domain from challenge record names (e.g., _acme-challenge.example.com → example.com)
• Handles both ZID and domain name identification
• Supports all DNS record types including TXT records required for ACME challenges

Documentation

Index

• func OpError(op string, err error) error
• func OpErrors(op string) *opErrors
• type CredentialInfo
• type DomainRecord
  • func (r DomainRecord) RR() libdns.RR
• type Provider
  • func (p *Provider) AppendRecords(ctx context.Context, zone string, recs []libdns.Record) ([]libdns.Record, error)
  • func (p *Provider) DeleteRecords(ctx context.Context, zone string, recs []libdns.Record) ([]libdns.Record, error)
  • func (p *Provider) GetRecords(ctx context.Context, zone string) ([]libdns.Record, error)
  • func (p *Provider) SetRecords(ctx context.Context, zone string, recs []libdns.Record) ([]libdns.Record, error)

Functions

func OpError

func OpError(op string, err error) error

func OpErrors

func OpErrors(op string) *opErrors

Types

type CredentialInfo

type CredentialInfo struct {
	// The API Key ID Required by VolcEngine for accessing the API
	AccessKeyID string `json:"access_key_id"`
	// The API Key Secret Required by VolcEngine for accessing the API
	AccessKeySecret string `json:"access_key_secret"`
	// Optional for identifying the region of the VolcEngine Service, default is cn-beijing
	RegionID string `json:"region_id,omitempty"`
}

CredentialInfo implements param of the credential

type DomainRecord

type DomainRecord struct {
	Type     string
	Name     string
	Value    string
	TTL      ttl_t
	Priority ttl_t
	ID       string
}

func (DomainRecord) RR

func (r DomainRecord) RR() libdns.RR

type Provider

type Provider struct {
	CredentialInfo
	// ZID is the domain ID used to directly query DNS records (highest priority)
	// VolcEngine API uses ZID instead of zone to identify domains
	ZID int64 `json:"zid,omitempty"`
	// Zone is the domain name. When ZID is not set, it will look up the corresponding ZID via ListZones API
	// Priority: ZID > Zone > zone parameter
	Zone string `json:"zone,omitempty"`
	// contains filtered or unexported fields
}

Provider implements the libdns interfaces for VolcEngine DNS.

func (*Provider) AppendRecords

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

AppendRecords adds records. It returns the records that were added. ZID resolution priority: Provider.ZID > Provider.Zone > zone parameter

func (*Provider) DeleteRecords

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

DeleteRecords deletes the records. If a record does not have an ID, it will be looked up. It returns the records that were deleted. ZID resolution priority: Provider.ZID > Provider.Zone > zone parameter

func (*Provider) GetRecords

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

GetRecords lists all the records. ZID resolution priority: Provider.ZID > Provider.Zone > zone parameter

func (*Provider) SetRecords

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

SetRecords sets the records, either by updating existing records or creating new ones. It returns the updated records. ZID resolution priority: Provider.ZID > Provider.Zone > zone parameter