route53

README

Route53 for libdns

[!WARNING] Breaking changes in v1.6: Field names have changed. See BREAKING.md for migration guide.

This package implements the libdns interfaces for AWS Route53.

Example

package main

import (
	"context"
	"fmt"
	"time"

	"github.com/libdns/route53"
)

func main() {
	// greate a new Route53 provider instance
	provider := &route53.Provider{
		AccessKeyId:     "YOUR_ACCESS_KEY_ID",
		SecretAccessKey: "YOUR_SECRET_ACCESS_KEY",
		Region:          "us-east-1",
	}

	ctx := context.Background()
	zone := "example.com."

	// get all records for the zone
	records, err := provider.GetRecords(ctx, zone)
	if err != nil {
		panic(err)
	}

	for _, record := range records {
		fmt.Printf("%s %s %s %d\n", record.Name, record.Type, record.Value, record.TTL/time.Second)
	}
}

Authenticating

This package supports all the credential configuration methods described in the AWS Developer Guide, such as Environment Variables, Shared configuration files, the AWS Credentials file located in .aws/credentials, and Static Credentials. You may also pass in static credentials directly (or via caddy's configuration).

The following IAM policy is a minimal working example to give libdns permissions to manage DNS records:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "",
            "Effect": "Allow",
            "Action": [
                "route53:ListResourceRecordSets",
                "route53:GetChange",
                "route53:ChangeResourceRecordSets"
            ],
            "Resource": [
                "arn:aws:route53:::hostedzone/ZABCD1EFGHIL",
                "arn:aws:route53:::change/*"
            ]
        },
        {
            "Sid": "",
            "Effect": "Allow",
            "Action": [
                "route53:ListHostedZonesByName",
                "route53:ListHostedZones"
            ],
            "Resource": "*"
        }
    ]
}

Running in Docker on EC2 with Instance Roles

When running this provider in a Docker container on EC2 instances that use IAM instance roles, you need to ensure that the container can access the EC2 metadata service. By default, IMDSv2 (Instance Metadata Service Version 2) limits the hop count to 1, which prevents Docker containers from accessing the metadata service.

Instances created through the AWS Console typically have a hop limit of 2 by default and won't have this issue. This configuration is usually needed for instances created programmatically or with older configurations.

To enable Docker containers to use EC2 instance roles, configure the instance metadata options with an increased hop limit:

aws ec2 modify-instance-metadata-options \
    --instance-id <instance-id> \
    --http-put-response-hop-limit 2 \
    --http-endpoint enabled

Or when launching an instance:

aws ec2 run-instances \
    --metadata-options "HttpEndpoint=enabled,HttpPutResponseHopLimit=2" \
    # ... other parameters

For more information, see the AWS EC2 Instance Metadata Options documentation.

Note on propagation-related fields

When you update records in AWS Route53, changes first propagate internally across AWS's DNS servers before becoming visible to the public. This internal step usually finishes within seconds, but may take more in rare cases, and can be waited on when WaitForRoute53Sync is enabled. It is different from normal DNS propagation, which depends on TTL and external caching.

See Change Propagation to Route 53 DNS Servers.

Performance optimization for delete operations

By default, when WaitForRoute53Sync is enabled, the provider waits for synchronization on all operations, including deletes. For bulk delete operations where immediate consistency is not required, you can skip the wait on deletes by setting SkipRoute53SyncOnDelete to true:

provider := &route53.Provider{
    WaitForRoute53Sync:       true,  // Wait for sync on create/update
    SkipRoute53SyncOnDelete:  true,  // Skip wait on delete for better performance
}

This can significantly speed up bulk delete operations while still maintaining consistency guarantees for create and update operations.

Contributing

Contributions are welcome! Please ensure that:

1. All code passes golangci-lint checks. Run the following before committing:

   golangci-lint run ./...
   

2. All tests pass:

   go test ./...
   

3. For integration tests, set up the required environment variables:

   export AWS_ACCESS_KEY_ID="your-key"
   export AWS_SECRET_ACCESS_KEY="your-secret"
   export ROUTE53_TEST_ZONE="test.example.com."
   cd libdnstest && go test -v
   

Please fix any linter issues before submitting a pull request. The project maintains strict code quality standards to ensure maintainability.

Documentation

Index

• type Provider
  • func (p *Provider) AppendRecords(ctx context.Context, zone string, records []libdns.Record) ([]libdns.Record, error)
  • func (p *Provider) DeleteRecords(ctx context.Context, zone string, records []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, records []libdns.Record) ([]libdns.Record, error)

Types

type Provider

type Provider struct {

	// Region is the AWS Region to use. If not set, it will use AWS_REGION
	// environment variable.
	Region string `json:"region,omitempty"`

	// AWSProfile is the AWS Profile to use. If not set, it will use
	// AWS_PROFILE environment variable.
	Profile string `json:"profile,omitempty"`

	// AccessKeyId is the AWS Access Key ID to use. If not set, it will use
	// AWS_ACCESS_KEY_ID
	AccessKeyId string `json:"access_key_id,omitempty"` //nolint:revive,staticcheck // established public API, cannot change

	// SecretAccessKey is the AWS Secret Access Key to use. If not set, it will use
	// AWS_SECRET_ACCESS_KEY environment variable.
	SecretAccessKey string `json:"secret_access_key,omitempty"`

	// SessionToken is the AWS Session Token to use. If not set, it will use
	// AWS_SESSION_TOKEN environment variable.
	SessionToken string `json:"session_token,omitempty"`

	// MaxRetries is the maximum number of retries to make when a request
	// fails. If not set, it will use 5 retries.
	MaxRetries int `json:"max_retries,omitempty"`

	// Route53MaxWait is the maximum amount of time to wait for a record
	// to be propagated within AWS infrastructure. Default is 1 minute.
	Route53MaxWait time.Duration `json:"route53_max_wait,omitempty"`

	// WaitForRoute53Sync if set to true, it will wait for the record to be
	// propagated within AWS infrastructure before returning. This is not related
	// to DNS propagation, that could take much longer.
	WaitForRoute53Sync bool `json:"wait_for_route53_sync,omitempty"`

	// SkipRoute53SyncOnDelete if set to true, it will skip waiting for Route53
	// synchronization when deleting records, even if WaitForRoute53Sync is true.
	// This can speed up bulk delete operations where waiting is not necessary.
	SkipRoute53SyncOnDelete bool `json:"skip_route53_sync_on_delete,omitempty"`

	// HostedZoneID is the ID of the hosted zone to use. If not set, it will
	// be discovered from the zone name.
	//
	// This option should contain only the ID; the "/hostedzone/" prefix
	// will be added automatically.
	HostedZoneID string `json:"hosted_zone_id,omitempty"`

	// Logger receives structured log events emitted by the provider. If nil,
	// a discard handler is used. Wrappers (for example, the Caddy DNS module)
	// can adapt their own logger via slog.Handler — for zap, see
	// go.uber.org/zap/exp/zapslog.
	//
	// All events are emitted at Debug level except for ambiguous zone
	// resolution, which is Warn.
	Logger *slog.Logger `json:"-"`
	// contains filtered or unexported fields
}

Provider implements the libdns interfaces for Route53.

By default, the provider loads the AWS configuration from the environment. To override these values, set the fields in the Provider struct.

func (*Provider) AppendRecords

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

AppendRecords adds records to the zone. It returns the records that were added.

func (*Provider) DeleteRecords

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

DeleteRecords deletes the given records from the zone and returns the records that were actually deleted. Input records that do not exist in the zone are silently ignored.

As the libdns contract requires, an empty value or an empty type acts as a wildcard: an empty value matches every value in the targeted record set, and an empty type applies the deletion to every record type at that name. The zone's own SOA and NS record sets are never matched by an empty type, because Route53 does not allow deleting them.

TTL is not compared. Route53 keeps one TTL per record set rather than per value, so the TTL a caller holds for a record can legitimately differ from the stored one.

func (*Provider) GetRecords

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

GetRecords lists all the records in the zone.

func (*Provider) SetRecords

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

SetRecords sets the records in the zone. For each (name, type) tuple represented in the input, the corresponding ResourceRecordSet is replaced with exactly the values provided — other tuples in the zone are not touched. It returns the records that were set.

Multiple input records sharing the same (name, type) are combined into a single UPSERT carrying all their values, matching libdns semantics.