Skip to main content
DNS resource record sets (RRsets) define individual DNS records such as A, AAAA, CNAME, MX, and TXT with TTL, geo-balancing, and failover settings.

​
Supported Record Types

  • A - IPv4 address records
  • AAAA - IPv6 address records
  • CNAME - Canonical name (alias) records
  • MX - Mail exchange records
  • TXT - Text records
  • SRV - Service locator records
  • NS - Name server records
  • SOA - Start of authority (managed automatically)

​
Create Record

Add a new DNS record to a zone. Records can be static or dynamic with advanced routing.

​
Simple A Record

ctx := context.Background()

record, err := client.DNS.Zones.Rrsets.New(ctx, "A", dns.ZoneRrsetNewParams{
    ZoneName: "example.com",
    RrsetName: "www",
    Ttl: gcore.F(int64(3600)),
    ResourceRecords: gcore.F([]dns.ZoneRrsetNewParamsResourceRecord{
        {
            Content: []any{"192.0.2.1"},
            Enabled: gcore.F(true),
        },
    }),
})
if err != nil {
    log.Fatal(err)
}

fmt.Printf("Record created: %s\n", record.Name)

​
Parameters

​
zoneName
string
required
Name of the DNS zone
​
rrsetName
string
required
Record name (use ”@” for zone apex)
​
rrsetType
string
required
Record type: A, AAAA, CNAME, MX, TXT, SRV, NS
​
ttl
integer
default:3600
Time to live in seconds
​
resource_records
array
required
Array of resource records

​
Record Type Examples

record, err := client.DNS.Zones.Rrsets.New(ctx, "AAAA", dns.ZoneRrsetNewParams{
    ZoneName: "example.com",
    RrsetName: "www",
    Ttl: gcore.F(int64(3600)),
    ResourceRecords: gcore.F([]dns.ZoneRrsetNewParamsResourceRecord{
        {
            Content: []any{"2001:db8::1"},
            Enabled: gcore.F(true),
        },
    }),
})

​
Dynamic Records with Geo-Routing

Dynamic RRsets enable advanced traffic routing based on user location, ASN, health checks, and weighted distribution.

​
Geo-Distance Routing

Route users to the nearest server based on geographic coordinates. 
ctx := context.Background()

record, err := client.DNS.Zones.Rrsets.New(ctx, "A", dns.ZoneRrsetNewParams{
    ZoneName: "example.com",
    RrsetName: "www",
    Ttl: gcore.F(int64(300)),
    ResourceRecords: gcore.F([]dns.ZoneRrsetNewParamsResourceRecord{
        {
            Content: []any{"192.0.2.1"},
            Enabled: gcore.F(true),
            Meta: map[string]any{
                "latlong": []float64{37.7749, -122.4194}, // San Francisco
                "notes": "US West Coast server",
            },
        },
        {
            Content: []any{"192.0.2.2"},
            Enabled: gcore.F(true),
            Meta: map[string]any{
                "latlong": []float64{40.7128, -74.0060}, // New York
                "notes": "US East Coast server",
            },
        },
        {
            Content: []any{"192.0.2.3"},
            Enabled: gcore.F(true),
            Meta: map[string]any{
                "latlong": []float64{51.5074, -0.1278}, // London
                "notes": "EU server",
            },
        },
    }),
    Pickers: gcore.F([]dns.ZoneRrsetNewParamsPicker{
        {
            Type: "geodistance",
        },
        {
            Type: "first_n",
            Limit: gcore.F(int64(1)),
        },
    }),
})

​
Country-Based Routing

Route traffic based on user’s country. 
record, err := client.DNS.Zones.Rrsets.New(ctx, "A", dns.ZoneRrsetNewParams{
    ZoneName: "example.com",
    RrsetName: "www",
    Ttl: gcore.F(int64(300)),
    ResourceRecords: gcore.F([]dns.ZoneRrsetNewParamsResourceRecord{
        {
            Content: []any{"192.0.2.1"},
            Meta: map[string]any{
                "countries": []string{"us", "ca", "mx"},
            },
        },
        {
            Content: []any{"192.0.2.2"},
            Meta: map[string]any{
                "countries": []string{"de", "fr", "gb"},
            },
        },
        {
            Content: []any{"192.0.2.3"},
            Meta: map[string]any{
                "default": true, // Fallback for other countries
            },
        },
    }),
    Pickers: gcore.F([]dns.ZoneRrsetNewParamsPicker{
        {
            Type: "geodns",
            Strict: gcore.F(false),
        },
    }),
})

​
Weighted Load Balancing

Distribute traffic based on weights. 
record, err := client.DNS.Zones.Rrsets.New(ctx, "A", dns.ZoneRrsetNewParams{
    ZoneName: "example.com",
    RrsetName: "www",
    Ttl: gcore.F(int64(300)),
    ResourceRecords: gcore.F([]dns.ZoneRrsetNewParamsResourceRecord{
        {
            Content: []any{"192.0.2.1"},
            Meta: map[string]any{
                "weight": 70, // 70% of traffic
            },
        },
        {
            Content: []any{"192.0.2.2"},
            Meta: map[string]any{
                "weight": 30, // 30% of traffic
            },
        },
    }),
    Pickers: gcore.F([]dns.ZoneRrsetNewParamsPicker{
        {
            Type: "weighted_shuffle",
        },
        {
            Type: "first_n",
            Limit: gcore.F(int64(2)),
        },
    }),
})

​
Picker Types

Pickers are applied in order to determine which records are returned.

​
Selectors

​
geodns
picker
Filter records by IP, ASN, region, country, or continent
  • strict: true - Return no answers if no match found
  • strict: false - Return all records if no match found
​
asn
picker
Select records matching requestor’s ASN
​
country
picker
Select records matching requestor’s country
​
continent
picker
Select records matching requestor’s continent
​
region
picker
Select records matching requestor’s region (e.g., “fr-nor” for France/Normandy)
​
ip
picker
Select records matching requestor’s IP subnet (max 100 subnets per record)
​
default
picker
Select records marked with "default": true in metadata

​
Mutators

​
geodistance
picker
Sort records by distance from requestor (requires latlong metadata)
​
weighted_shuffle
picker
Randomize records based on weight metadata (default weight: 50)

​
Filters

​
first_n
picker
Return only the first N records
  • limit: 1 - Return only first record
  • limit: 0 - Return all records (no limit)

​
Health Checks and Failover

Configure health checks to automatically failover to backup servers. 
record, err := client.DNS.Zones.Rrsets.New(ctx, "A", dns.ZoneRrsetNewParams{
    ZoneName: "example.com",
    RrsetName: "www",
    Ttl: gcore.F(int64(60)),
    ResourceRecords: gcore.F([]dns.ZoneRrsetNewParamsResourceRecord{
        {
            Content: []any{"192.0.2.1"},
            Enabled: gcore.F(true),
        },
        {
            Content: []any{"192.0.2.2"},
            Enabled: gcore.F(true),
            Meta: map[string]any{
                "backup": true,
            },
        },
    }),
    Meta: map[string]any{
        "failover": map[string]any{
            "protocol": "HTTP",
            "port": 443,
            "frequency": 30,
            "timeout": 5,
            "method": "GET",
            "url": "/health",
            "tls": true,
            "http_status_code": 200,
            "host": "www.example.com",
        },
    },
})

​
Failover Configuration

​
failover.protocol
string
required
Health check protocol: HTTP, TCP, UDP, ICMP
​
failover.port
integer
required
Port to check (1-65535)
​
failover.frequency
integer
required
Check frequency in seconds (10-3600)
​
failover.timeout
integer
required
Timeout in seconds (1-10)
​
failover.method
string
HTTP method (only for HTTP protocol)
​
failover.url
string
URL path to check (only for HTTP protocol)
​
failover.tls
boolean
Use HTTPS (only for HTTP protocol)
​
failover.host
string
Host header (only for HTTP protocol)
​
failover.http_status_code
integer
Expected HTTP status code (only for HTTP protocol)
​
failover.regexp
string
Regular expression to match in response (non-ICMP protocols)
​
failover.command
string
Bytes to send (only for TCP/UDP protocols)

​
List Records

Retrieve all records in a zone. 
ctx := context.Background()

response, err := client.DNS.Zones.Rrsets.List(ctx, "example.com", dns.ZoneRrsetListParams{
    Limit: gcore.F(int64(50)),
    Offset: gcore.F(int64(0)),
    OrderBy: gcore.F("name"),
    OrderDirection: gcore.F(dns.ZoneRrsetListParamsOrderDirectionAsc),
})
if err != nil {
    log.Fatal(err)
}

fmt.Printf("Total records: %d\n", response.TotalAmount)
for _, rrset := range response.Rrsets {
    fmt.Printf("%s %s %d\n", rrset.Name, rrset.Type, rrset.Ttl)
}

​
Get Record

Retrieve a specific DNS record. 
ctx := context.Background()

record, err := client.DNS.Zones.Rrsets.Get(ctx, "A", dns.ZoneRrsetGetParams{
    ZoneName: "example.com",
    RrsetName: "www",
})
if err != nil {
    log.Fatal(err)
}

fmt.Printf("%s %s TTL=%d\n", record.Name, record.Type, record.Ttl)
for _, rr := range record.ResourceRecords {
    fmt.Printf("  Content: %v\n", rr.Content)
}

​
Update Record

Update an existing DNS record. This replaces all resource records. 
ctx := context.Background()

record, err := client.DNS.Zones.Rrsets.Replace(ctx, "A", dns.ZoneRrsetReplaceParams{
    ZoneName: "example.com",
    RrsetName: "www",
    Ttl: gcore.F(int64(1800)),
    ResourceRecords: gcore.F([]dns.ZoneRrsetReplaceParamsResourceRecord{
        {
            Content: []any{"192.0.2.10"},
            Enabled: gcore.F(true),
        },
        {
            Content: []any{"192.0.2.11"},
            Enabled: gcore.F(true),
        },
    }),
})
if err != nil {
    log.Fatal(err)
}

​
Delete Record

Delete a DNS record from a zone. 
ctx := context.Background()

err := client.DNS.Zones.Rrsets.Delete(ctx, "A", dns.ZoneRrsetDeleteParams{
    ZoneName: "example.com",
    RrsetName: "www",
})
if err != nil {
    log.Fatal(err)
}

fmt.Println("Record deleted successfully")

​
Get Failover History

Retrieve the failover event log for a record with health checks. 
ctx := context.Background()

logs, err := client.DNS.Zones.Rrsets.GetFailoverLogs(ctx, "A", dns.ZoneRrsetGetFailoverLogsParams{
    ZoneName: "example.com",
    RrsetName: "www",
    Limit: gcore.F(int64(100)),
    Offset: gcore.F(int64(0)),
})
if err != nil {
    log.Fatal(err)
}

fmt.Printf("Total events: %d\n", logs.TotalAmount)
for _, event := range logs.Log {
    timestamp := time.Unix(event.Time, 0)
    fmt.Printf("%s: %s - %s\n", timestamp, event.Address, event.Action)
}

​
Record Metadata Fields

Use these metadata fields on individual resource records for advanced routing:
​
meta.asn
array
Array of autonomous system numbers (e.g., [1234, 5678])
​
meta.continents
array
Array of continent codes: af, an, eu, as, na, sa, oc
​
meta.countries
array
Array of ISO country codes (e.g., ["us", "ca", "mx"])
​
meta.regions
array
Array of region codes (e.g., ["de-bw", "de-by"])
​
meta.ip
array
Array of CIDR ranges (e.g., ["192.168.15.0/24", "2003:de:2016::/48"])
​
meta.latlong
array
Coordinates as [latitude, longitude] (e.g., [52.520008, 13.404954])
​
meta.weight
number
default:50
Weight for weighted_shuffle picker (0-100)
​
meta.default
boolean
Mark as default/fallback record
​
meta.backup
boolean
Mark as backup record for failover
​
meta.notes
string
Human-readable notes about the record

​
Complete Example

Complex geo-routed record with health checks and failover: 
ctx := context.Background()

record, err := client.DNS.Zones.Rrsets.New(ctx, "A", dns.ZoneRrsetNewParams{
    ZoneName: "example.com",
    RrsetName: "api",
    Ttl: gcore.F(int64(60)),
    ResourceRecords: gcore.F([]dns.ZoneRrsetNewParamsResourceRecord{
        {
            Content: []any{"192.0.2.1"},
            Enabled: gcore.F(true),
            Meta: map[string]any{
                "countries": []string{"us", "ca"},
                "latlong": []float64{37.7749, -122.4194},
                "weight": 70,
                "notes": "US West primary",
            },
        },
        {
            Content: []any{"192.0.2.2"},
            Enabled: gcore.F(true),
            Meta: map[string]any{
                "countries": []string{"us", "ca"},
                "latlong": []float64{37.7749, -122.4194},
                "weight": 30,
                "notes": "US West secondary",
            },
        },
        {
            Content: []any{"192.0.2.3"},
            Enabled: gcore.F(true),
            Meta: map[string]any{
                "countries": []string{"de", "fr", "gb"},
                "latlong": []float64{51.5074, -0.1278},
                "notes": "EU primary",
            },
        },
        {
            Content: []any{"192.0.2.4"},
            Enabled: gcore.F(true),
            Meta: map[string]any{
                "default": true,
                "backup": true,
                "notes": "Global fallback",
            },
        },
    }),
    Pickers: gcore.F([]dns.ZoneRrsetNewParamsPicker{
        {
            Type: "geodns",
            Strict: gcore.F(false),
        },
        {
            Type: "geodistance",
        },
        {
            Type: "weighted_shuffle",
        },
        {
            Type: "first_n",
            Limit: gcore.F(int64(2)),
        },
    }),
    Meta: map[string]any{
        "failover": map[string]any{
            "protocol": "HTTPS",
            "port": 443,
            "frequency": 30,
            "timeout": 5,
            "method": "GET",
            "url": "/health",
            "tls": true,
            "http_status_code": 200,
        },
    },
})
if err != nil {
    log.Fatal(err)
}

fmt.Printf("Created dynamic record: %s\n", record.Name)
This example:
  1. Filters by country (geodns)
  2. Sorts by distance to user (geodistance)
  3. Randomly distributes based on weights (weighted_shuffle)
  4. Returns 2 closest servers (first_n)
  5. Monitors health and automatically fails over unhealthy servers

Build docs developers (and LLMs) love

Get started for freeTalk to us