Create/delete record (POST v1.0/hostedzone/{zoneId}/rrset)

  • Creates and deletes records.
  • The types of records that can be registered are NS, A, AAAA, CNAME, MX, TXT, PTR, LBR (for latency-based routing), and SRV.
  • The SOA record settings cannot be changed.
  • Create/delete operations can be specified for multiple records in a single request. They are handled as a single transaction, so are not reflected in parts.
  • Because record creation/deletion is not reflected immediately, the response will return the update request information.

    The update will be complete when the update status changes from PENDING to INSYNC.

  • Up to 10,000 records can be registered for each zone.
  • If create or delete record APIs are executed concurrently in the same zone, a 500 Internal Error will occur, so retry the operation.

*The zone ID is the same value as the zone name.

Request Headers

x-fcx-region

The name of the region the floating IP is assigned to. Required when specifying PTR for record type.

jp-east-1, jp-west-1, jp-west-2.

x-fcx-region-token

The token of the project the floating IP is assigned to. The token of a project different to X-Auth-Token can be specified. Required when specifying PTR for record type. When PTR of the same project as X-Auth-Token is operated, the token specification is requiered.

Ex.) Register Floating IP of project B in the zone of project A in the PTR record. The following are specified for the request header.

- X-Auth-Token: <Token of the projectA>

- x-fcx-region-token: <Token of the projectB>

Request Parameter

n/a

Request Elements

ChangeResourceRecordSetsRequest

Request envelope.

Data type Cardinality Parent element Child element
- 1..1 None ChangeBatch

ChangeBatch

Envelope of record transaction.

Data type Cardinality Parent element Child element
- 1..1 ChangeResourceRecordSetsRequest Comment

Changes

Comment

Comment for the record transaction.

Data type Cardinality Parent element Child element
xsd:string 0..1 ChangeBatch None

Changes

Envelope of change content list.

Data type Cardinality Parent element Child element
- 1..1 ChangeBatch Change

Change

Envelope of change content.

Data type Cardinality Parent element Child element
- 1..n Changes Action

ResourceRecordSet

Action

Type of record operation. CREATE or DELETE.

Data type Cardinality Parent element Child element
xsd:string 1..1 Change None

ResourceRecordSet

Envelope of the record information.

Data type Cardinality Parent element Child element
- 1..1 Change Name

Type

Weight

XniftyDefaultHost

Failover

XniftyHealthCheckConfig

TTL

ResourceRecords

XniftyComment

Name

Record name.

Input limitation:

Halfwidth alphanumeric characters (a-z,0-9) , wild-cards (*) , at marks (@) and hyphens (-) are available.

Specify 1 or more and 63 or less character

Wildcards can be specified for A, AAAA, MX, and CNAME records, as long as

Weight and Failover are not specified.

The at mark (@) can be specified for A, AAAA, MX, and TXT records, as long as Failover is not specified.

Data type Cardinality Parent element Child element
xsd:string 1..1 ResourceRecordSet None

Type

Record type.

NS, A, AAAA, CNAME, MX, TXT, PTR, LBR, SRV.

Data type Cardinality Parent element Child element
xsd:string 1..1 ResourceRecordSet None

Weight

Weighting value. 0 to 100.

Data type Cardinality Parent element Child element
xsd:string 0..1 ResourceRecordSet None

XniftyDefaultHost

Default host information.

Data type Cardinality Parent element Child element
xsd:string 0..1 ResourceRecordSet None

Failover

Failover type. PRIMARY or SECONDARY.

Data type Cardinality Parent element Child element
xsd:string 0..1 ResourceRecordSet None

XniftyHealthCheckConfig

Envelope of health check information.

Data type Cardinality Parent element Child element
- 0..1 ResourceRecordSet IPAddress

Port

Protocol

ResourcePath

FullyQualifiedDomainName

IPAddress

Health check destination IP address.

Data type Cardinality Parent element Child element
xsd:string 1..1 XniftyHealthCheckConfig None

Port

Health check destination port.

Data type Cardinality Parent element Child element
xsd:string 1..1 XniftyHealthCheckConfig None

Protocol

Health check type. HTTP, HTTPS, TCP.

Data type Cardinality Parent element Child element
xsd:string 1..1 XniftyHealthCheckConfig None

ResourcePath

Health check destination path.

Data type Cardinality Parent element Child element
xsd:string 0..1 XniftyHealthCheckConfig None

FullyQualifiedDomainName

Health check destination domain name.

Data type Cardinality Parent element Child element
xsd:string 0..1 XniftyHealthCheckConfig None

TTL

TTL value. 60 to 86400 seconds. If omitted, the zone TTL will be used.

Unnecessary when the record type is LBR.

Data type Cardinality Parent element Child element
xsd:string 0..1 ResourceRecordSet None

ResourceRecords

Parent node of record response information

Data type Cardinality Parent element Child element
- 1..1 ResourceRecordSet ResourceRecord

ResourceRecord

Record response information.

Data type Cardinality Parent element Child element
- 1..n ResourceRecords Value

Value

Record response value. Multibyte domains can be set for CNAME, MX and NS records.

Data type Cardinality Parent element Child element
xsd:string 1..1 ResourceRecord None

XniftyComment

Comment. Specify up to 255 fullwidth characters.

Data type Cardinality Parent element Child element
xsd:string 0..1 ResourceRecordSet None

HTTP status

Status

The following error codes can be returned for the request.

One of the following values will be returned:
200:
Normal completion
400:
Invalid input parameter
404:
A zone with the specified ID does not exist
Data type Cardinality
Int 1..1

Response elements (normal completion)

ChangeResourceRecordSetsResponse

Envelope of the response.

Data type Cardinality Parent element Child element
- 1..1 None ChangeInfo

ChangeInfo

Envelope of the update request information.

Data type Cardinality Parent element Child element
- 1..1 ChangeResourceRecordSetsResponse Id

Status

SubmittedAt

Id

Update request ID.

The ID is used by the GetChange API to retrieve update request information.

Data type Cardinality Parent element Child element
xsd:string 1..1 ChangeInfo None

Status

Current status of an update request.

PENDING or INSYNC.

Data type Cardinality Parent element Child element
xsd:string 1..1 ChangeInfo None

SubmittedAt

Datetime when update request was issued. Format: YYYY-MM-DDThh:mm:ss.SSSZ

Data type Cardinality Parent element Child element
xsd:string 1..1 ChangeInfo None

Example of Request


POST /hostedzone/example.com/rrset HTTP/1.1
Date: Fri, 06 Jun 2014 11:00:37 GMT
Content-Length: . . .
Host: dns.gls.cloud.global.fujitsu.com
Accept: application/xml
X-Auth-Token: MIIFvgY. . .
<?xml version="1.0" encoding="UTF-8"?>
< ChangeResourceRecordSetsRequest xmlns="http://docs.cloudcommunity.global.fujitsu.com/dns/api/v1.0/">
  <ChangeBatch>
    <Changes>
      <Change>
        <Action>CREATE</Action>
        <ResourceRecordSet>
          <Name>server.example.com</Name>
          <Type>A</Type>
          <TTL>60</TTL>
          <ResourceRecords>
             <ResourceRecord>
               <Value>222.158.xxx.yyy</Value>
             </ResourceRecord>
          </ResourceRecords>
        </ResourceRecordSet>
      </Change>
    </Changes>
  </ChangeBatch>
</ChangeResourceRecordSetsRequest>    
     

Example of Response


HTTP/1.1 200 OK
Date: Fri, 06 Jun 2014 11:00:38 GMT
Content-Length: . . .
Content-Type: application/xml
x-fcx-request-id: d96bd874-9bf2-11e1-8ee7-c98a0037a2b6
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
< ChangeResourceRecordSetsResponse xmlns="http://docs.cloudcommunity.global.fujitsu.com/dns/api/v1.0/">
  <ChangeInfo>
    <Id>7a782d43939d7ff538ff1ee19dbdd5a0</Id>
    <Status>INSYNC</Status>
    <SubmittedAt>2014-06-06T11:00:38.178Z</SubmittedAt>
  </ChangeInfo>
</ChangeResourceRecordSetsResponse>   
     

Failover settings

  • Failover settings

    The failover settings are specified using Failover tags. They can only be specified for A and AAAA records.

    • PRIMARY: Only 1 record can be set.
    • SECONDARY: Multiple settings are possible.
  • Heath check

    Health checks are to be specified in the failover settings.

    Settings are to be specified by XniftyHealthCheckConfig tag.

    Health check rules

    • Individual health checks specified for each record are executed.
    • Health check is performed at 5-minute intervals.
    • During a health check, a check of whether packets can be sent to the target server via

      the Internet is performed.

    • When a failover occurs, a host switches over to the other host in the group that has the

      same Name tag and same Type tag.

    • Ensure that all the same record name is used for all records in the same group.
    • Set a global IP address as the target IP address.
    • Configure the network and OS (firewall service, security group rules, OS firewall, etc.)

      so that packets reach the target IP address.

    • When the FullyQualifiedDomainName tag is set, the value reaches the value of the Host header.
    • When ResourcePath tag is set, that value becomes a path to helth check. When this tag is not set, " /" becomes a path to helth check.
    • If multiple records are specified for [Secondary], priority is given to the record that was

      registered first.

    • The Health check is usually done only on the Primary.
    • Health checks are normally only performed for primary servers.

    • If an abnormality occurs in a health check for [Primary], health checks will be

      performed for both [Primary] and [Secondary].

    • The relationships of the server statuses of [Primary] and [Secondary] and the

      allocation destinations are as follows.

    • Please refer IaaS Features Handbook (Network - DNS service - Failover Function) for the relationships of the server statuses of [Primary] and [Secondary] and the allocation destinations.
    
    <XniftyHealthCheckConfig>
      <IPAddress>targetIpAddr</IPAddress>
      <Port>targetPortNum</Port>
      <Protocol>targetProtocol</Protocol>
      <ResourcePath>targetUrlPathSection</ResourcePath>
      <FullyQualifiedDomainName>httpHeaderHostInfo</FullyQualifiedDomainName>
    </XniftyHealthCheckConfig>         
           
    CAUTION:

    When using failover, it is recommended to set the record TTL to 60 seconds.
  • Example failover settings (ResourceRecordSet)
    
    <ResourceRecordSet>
     
     <Name>server.example.com</Name>
      <Type>A</Type>
      <Failover>PRIMARY</Failover>
      <XniftyHealthCheckConfig>
        <IPAddress>222.158.xxx.yyy</IPAddress>
        <Port>80</Port>
        <Protocol>HTTP</Protocol>
      </XniftyHealthCheckConfig>
      <ResourceRecords>
        <ResourceRecord>
          <Value>222.158.xxx.yyy</Value>
        </ResourceRecord>
      </ResourceRecords>
    </ResourceRecordSet>
    <ResourceRecordSet>
     
      <Name>server.example.com</Name>
      <Type>A</Type>
      <Failover>SECONDARY</Failover>
      <XniftyHealthCheckConfig>
        <IPAddress>222.158.xxx.zzz</IPAddress>
        <Port>80</Port>
        <Protocol>HTTP</Protocol>
      </XniftyHealthCheckConfig>
      <ResourceRecords>
        <ResourceRecord>
          <Value>222.158.xxx.zzz</Value>
        </ResourceRecord>
      </ResourceRecords>
    </ResourceRecordSet>           
             

LBR settings

  • Settings for latency-based routing (LBR)

    For the LBR settings, set the type to "LBR".

    Inside the Value tags, the area and host are delimited by a halfwidth space.

    
    <Value>area host<Value>           
             
    For area, specify the nearest area.
    10:
    Japan
    20:
    Asia
    30:
    North America
    For host, specify the value to be returned when there is access from the specified area. Registered A/AAAA records can be specified in the same zone.

    Use sub-domain notation instead of FQDN for the host.

    (in the LBR setting example below, www.example.com is specified as the default zone and registered in Japan, while www2.example.com is registered in Asia.)

    Inside the XniftyDefaultHost tags, specify the value to be returned when there is access from outside the specified area.

  • Example LBR settings (ResourceRecordSet)
    
    <Changes>
      <Change>
        <Action>CREATE</Action>
        <ResourceRecordSet>
          <Name>server.example.com</Name>
          <Type>LBR</Type>
          <XniftyDefaultHost>www</XniftyDefaultHost>
          <ResourceRecords>
            <ResourceRecord>
              <Value>10 www,20 www2</Value>
            </ResourceRecord>
          </ResourceRecords>
        </ResourceRecordSet>
      </Change>
    </Changes>           
             

Weighted round robin settings

  • Settings for a weighted round robin

    Specify the weighting value in the Weight tags. They can only be specified for A and AAAA records.

    The record hit rate varies according to the specified weighting value.

  • Notes
    • If there are no records with a weighting of 100 in the weighting setting value, the target record may not be returned when resolving the name.
    • When the weighting setting value is set to 0, the hit rate will be 0, so no value will be returned.
    • For normal record registration, when records of the same host/same record type are registered, they are handled as a weighting of 100.
  • Example weighted round robin settings (ResourceRecordSet)
    
    <ResourceRecordSet>
      <Name>server.example.com</Name>
      <Type>A</Type>
      <Weight>100</Weight>
      <TTL>60</TTL>
      <ResourceRecords>
        <ResourceRecord>
          <Value>222.158.xxx.yyy</Value>
        </ResourceRecord>
      </ResourceRecords>
    </ResourceRecordSet>
    <ResourceRecordSet>
      <Name>server.example.com</Name>
      <Type>A</Type>
      <Weight>100</Weight>
      <TTL>60</TTL>
      <ResourceRecords>
        <ResourceRecord>
          <Value>222.158.xxx.zzz</Value>
        </ResourceRecord>
      </ResourceRecords>
    </ResourceRecordSet>           
             

MX record settings

  • MX record settings

    Separate the priority from the host using a halfwidth space in the Value tag inside the ResourceRecord.

    
    <Value>priority host</Value>           
             
  • Example MX record settings
    Priority:
    10
    Host:
    mail.example.com
    
    <ResourceRecordSet>
      <Name>@</Name>
      <Type>MX</Type>
      <TTL>60</TTL>
      <ResourceRecords>
        <ResourceRecord>
          <Value>10 mail.example.com</Value>
        </ResourceRecord>
      </ResourceRecords>
    </ResourceRecordSet>           
             

PTR record settings

  • PTR record settings

    To set a PTR record, specify the IP address and the FQDN to be registered for Name and Value, respectively.

    It is necessary to register the A record for DNS lookup in advance.

    Register the A record for DNS lookup with the K5 DNS service.

  • The number of PTR record operations

    Only one PTR record can be operated each time the API is executed.

    When operations involving two or more records are attempted, 400 InvalidInput is returned. In this case, execute the API specifying fewer records.

  • Processing time

    Completion of API execution takes longer for PTR record operations than other record operations.

    CAUTION:

    Registration and deletion of PTR records take longer than operations of A records.
  • Concurrent execution

    When performing operations involving multiple PTR records, latter operations must wait until the preceding operations are completed.

    When the waiting time reaches a certain length of time, the latter PTR record operations may fail and a 503 Service Unavailable may occur.

    In this case, perform the operation again.

  • Concurrent execution with DeleteHostedZone

    Waiting time occurs for the latter operations to prevent operation of PTR records and zone deletion from being executed at the same time.

    When the waiting time reaches a certain length of time, the latter PTR record operations may fail and a 503 Service Unavailable may occur.

    In this case, perform the operation again.

  • Example of PTR record settings
    
      <Changes>
        <Change>
          <Action>CREATE</Action>
          <ResourceRecordSet>
            <Name>123.56.xxx.yyy</Name>
            <Type>PTR</Type>
            <ResourceRecords>
              <ResourceRecord>
                <Value>host.example.com</Value>
              </ResourceRecord>
            </ResourceRecords>
          </ResourceRecordSet>
        </Change>
      </Changes>
           

Confirmation after PTR record operations

  • After performing an operation involving a PTR record, perform reverse DNS lookup to confirm that the operation was reflected correctly.

    Confirm that the reverse DNS lookup operation was reflected correctly on the name server.

    Examples of the confirmation procedures are shown below.

    Perform one of the example procedures.

    • Example 1. Confirmation using the dig command (133.162.139.51 is a dummy value for the PTR record name)
      • Precondition: Perform this procedure in an environment where internet access is available using UDP port 53.
        
        dig -x 133.162.139.51 @ns0.dns.nifcloud.com                
                      
      • Points to be checked
        • For CREATE: Confirm that the DNS lookup record name is displayed in ANSWER SECTION
          
          ;; ANSWER SECTION:
          51.139.162.133.in-addr.arpa. 60 IN PTR <DNS lookup record name>
                           
        • For DELETE: Confirm that unlike for CREATE, the DNS lookup record name is not displayed in ANSWER SECTION
          
          ;; ANSWER SECTION:(not displayed)
          ;; AUTHORITY SECTION:
          139.162.133.in-addr.arpa. 3600 IN SOA ns0.dns.nifcloud.com. hostmaster.dns.nifcloud.com. 1538455002 10800 3600 604800 3600
                           
    • Example 2. Confirmation using the nslookup command (133.162.139.51 is a dummy value for the PTR record name)
      • Precondition: Perform this procedure in an environment where internet access is available using UDP port 53.
        
        nslookup -type=PTR 133.162.139.51 ns0.dns.nifcloud.com
                         
      • Points to be checked
        • For CREATE: Confirm that the DNS lookup record name is displayed as "name"
          
          51.139.162.133.in-addr.arpa     name = <DNS lookup record name>
                               
        • For DELETE: Confirm that the following message is displayed:
          
          ** server can't find 51.139.162.133.in-addr.arpa.: NXDOMAIN
                               
    • Example 3: Confirmation on the web site (133.162.139.51 is a dummy value for the PTR record name)
      • On https://www.cman.jp/network/support/nslookup.html, enter the following information for confirmation:
        • Specify the host name (FQDN): 133.162.139.51
        • Option (optional): PTR: IP address (reverse DNS lookup)
        • When specifying the DNS server (optional): ns0.dns.nifcloud.com
      • Points to be checked
        • When executing nslookup: Check the same points as for confirmation using the nslookup command
        • When executing dig: Check the same points as for confirmation using the dig command
CAUTION:

For details on global IP addresses for which reverse DNS lookup is possible, refer "Appendix A.22 How to Use Reverse DNS Lookup" of IaaS Features Handbook.

SRV record settings

  • SRV record settings

    In the record name (the value of the Name tag), specify the service name and the protocol name (Example: _ftp._tcp) in the format "_<service name>._<protocol name>"

    In the value (the value of the Value tag), specify the priority, weighting, port number, and target, in this order, separated by single-byte blank spaces.

    
    <Value>Priority Weighting PortNumber Target</Value>
             
  • Example of SRV record settings
    Priority:
    1
    Weighting:
    2
    Port number:
    21
    Target:
    ftp-server-01.example.com
    
    <ResourceRecordSet>
      <Name>_ftp._tcp</Name>
      <Type>SRV</Type>
      <TTL>3600</TTL>
      <ResourceRecords>
        <ResourceRecord>
          <Value>1 2 21 ftp-server-01.example.com</Value>
        </ResourceRecord>
      </ResourceRecords>
    </ResourceRecordSet>
             
  • The zone ID specified in the URL when issuing an API request is registered in the domain name of the SRV record (Example: example.com).
  • Notes
    • Specify the target value using the format "<record name of A record existing in same zone>.<domain name>".

      Example where the record name of the A record is "ftp-server-01" and the domain name is "example.com"

      "ftp-server-01.example.com".

  • Domain name of the SRV record
    • Zone ID specified at the execution of API request is registered to the domain name of SRV recored. (Example: example.com)
  • Notes
    • Specify the target value using the format "<record name of A record existing in same zone>.<domain name>".

      For example, where the record name of the A record is "ftp-server-01" and the domain name is "example.com",

      Please specify "ftp-server-01.example.com".

    • The target value can be specified in multibyte domains.
    • The weighting in SRV records is not handled as a weighted round robin function.
  • Supplement
    • Refer to RFC-2782 for the specifications of SRV records.