Managing DNS zones

Manage DNS zones by using the UI, CLI, or API.

You must have an IBM Cloud® DNS Services instance before managing DNS zones. Refer to Create a DNS Services instance for more information.

A zone can have an arbitrary number of levels, but not fewer than two. For example, ibm.austin.texas.example.com is a valid zone name, but com is not.

You can have multiple zones where one is a suffix to another. For example, sub.domain.example.com and domain.example.com can co-exist.

You can also define subdomains within an added zone. For example, the following are all valid names within the zone domain.example.com.

subdomain.domain.example.com
hostname.domain.example.com
hostname.subdomain.domain.example.com

The name host.sub.domain.example.com might be host.sub within the zone domain.example.com. It might also be host.sub.domain within the zone example.com. Both can exist at the same time, and are separate.

Known limitations

The DNS resolver always looks for a record from the longest matching zone, even though the record might not exist in the longest matching zone but does exist in another non-longest matching zone.

Let's say we have two zones, domain.example.com and example.com.

Records for example.com

 {
      myhost.domain.example.com A 1.1.1.1
      me.domain.example.com A 8.8.8.8
  }

Records for domain.example.com

  {
      myhost.domain.example.com A 2.2.2.2
  }

If a user queries for myhost.domain.example.com, the expected result (which is 2.2.2.2) should come from domain.example.com, because domain.example.com is the longest match with the user query.

If they queried for me.domain.example.com instead, the resolver searches only the longest matching zone. Because me.domain.example.com does not exist in domain.example.com, the result is an NXDOMAIN.

Creating a DNS zone in the UI

From the Resource page, select the desired DNS Services instance.
Click the Create Zone button on the DNS Zones page.
In the panel that appears, enter your zone name in the Name field. Optionally, enter Label and Description fields. See [Restricted DNS zone names(#restricted-dns-zone-names) for information about what names are not permitted.
Click Create Zone.

If the zone creation is successful, you are directed to the Zone Details page.

Newly added zones have a pending state until you add permitted networks to the zone. The zone becomes active after permitted networks are added.

If the zone creation is unsuccessful, an error notification appears with information about what caused the error.

Restricted DNS zone names

Subdomains to any of the restricted 2-level zones are not permitted. For example, my.host.ibm.com is a subdomain to ibm.com. Therefore, my.host.ibm.com is also a restricted zone.

The following DNS zone names are not permitted.

ibm.com
softlayer.com
bluemix.net
softlayer.local
mybluemix.net
networklayer.com
ibmcloud.com
pdnsibm.net
appdomain.cloud
compass.cobaltiron.com

Edit a DNS zone in the UI

From the DNS Zones page, select your zone. Label and Description options appear.
Click the edit icon for Label, then enter the label and click Save.
Click the edit icon for Description, then enter the description and click Save.

Delete a DNS zone in the UI

From the DNS Zones page, click the delete icon from the row for the zone you wish to delete. A confirmation dialog appears.
Click Delete button.

Manage DNS zones from the CLI

Follow these instructions to install DNS Services CLI plugin.

First use ibmcloud dns instances command to list the DNS Services instances and then use the ibmcloud dns instance-target command to set the target operating DNS Services instance.

$ ibmcloud dns instances
Retrieving service instances for service 'dns-svcs' ...
OK

Name                 ID                                     Location   State    Service Name
DNS Services-km      ffffffff-b042-41fd-885e-000000000000   global     active   dns-svcs

$ ibmcloud dns instance-target "DNS Services-km"

Create a DNS zone from the CLI

Use the ibmcloud dns zone-create command followed by the zone name to create a zone.

$ ibmcloud dns zone-create example.com
Creating zone 'example.com' for service instance 'DNS Services-km' ...
OK

ID            example.com:f7f40364-a5e6-48f7-9fc9-387434c579ae
Name          example.com
Description
Label
State         PENDING_NETWORK_ADD
Created On    2020-04-10 07:21:51.774444868 +0000 UTC
Modified On   2020-04-10 07:21:51.774444868 +0000 UTC

For future reference, the "ID" in output is used as variable DNS_ZONE_ID. Run this command to store it in variable DNS_ZONE_ID:

DNS_ZONE_ID="example.com:f7f40364-a5e6-48f7-9fc9-387434c579ae"

Get a DNS zone from the CLI

Use the ibmcloud dns zone command followed by the zone ID to get details of an existing zone.

$ ibmcloud dns zone $DNS_ZONE_ID
Getting zone 'example.com:f7f40364-a5e6-48f7-9fc9-387434c579ae' for service instance 'DNS Services-km' ...
OK

ID            example.com:f7f40364-a5e6-48f7-9fc9-387434c579ae
Name          example.com
Description
Label
State         PENDING_NETWORK_ADD
Created On    2020-04-10 07:21:51.774444868 +0000 UTC
Modified On   2020-04-10 07:21:51.774444868 +0000 UTC

Update a DNS zone from the CLI

Use the ibmcloud dns zone-update command followed by the zone ID to update a zone. Specify -d, --description to update the description and/or -l, --label to update the label of a zone.

$ ibmcloud dns zone-update $DNS_ZONE_ID -d "example zone" -l "us-south"
Updating zone 'example.com:f7f40364-a5e6-48f7-9fc9-387434c579ae' for service instance 'DNS Services-km' ...
OK

ID            example.com:f7f40364-a5e6-48f7-9fc9-387434c579ae
Name          example.com
Description   example zone
Label         us-south
State         PENDING_NETWORK_ADD
Created On    2020-04-10 07:21:51.774444868 +0000 UTC
Modified On   2020-04-10 07:38:36.712131819 +0000 UTC

List DNS zones from the CLI

Use the ibmcloud dns zones command to list all zones.

$ ibmcloud dns zones
Listing zones for service instance 'DNS Services-km' ...
OK

ID                                                      Name               Status
example.com:f7f40364-a5e6-48f7-9fc9-387434c579ae        example.com        PENDING_NETWORK_ADD

Delete a DNS zone from the CLI

Use the ibmcloud dns zone-delete followed by the zone ID to delete a zone.

ibmcloud dns zone-delete  $DNS_ZONE_ID

Manage DNS zones with the API

First store the API endpoint in a variable so you can use it in API requests without having to type the full URL. For example, to store the production endpoint in a variable, run this command:

DNSSVCS_ENDPOINT=https://api.dns-svcs.cloud.ibm.com

To verify that this variable was saved, run echo $DNSSVCS_ENDPOINT and make sure the response is not empty.

Authentication

The Authorization header is required for each API call. This header is the bearer token for the user, which can be retrieved from IAM (for example, using the ibmcloud iam oauth-tokens command).

You must obtain an IAM token and export it into the $TOKEN for DNS Services.

Create a DNS zone with the API

Create a new zone by using the following curl command:

Request

curl -X POST \
  $DNSSVCS_ENDPOINT/v1/instances/$INSTANCE_ID/dnszones \
  -H "Authorization: $TOKEN" \
  -d '{
  "name": "example.com",
  "description": "Example zone"
}'

Response

{
    "success": true,
    "result": {
        "id": "ed10e4b2-8a64-4afa-a4e2-9e60a766d079",
        "created_on": "2019-07-24 12:30:58.357201205 +0000 UTC",
        "modified_on": "2019-07-24 12:30:58.357201205 +0000 UTC",
        "instance_id": "1a34bda8-9c94-4232-bea7-7df163b21d23",
        "name": "example.com",
        "description": "Example zone",
        "state": "PENDING_NETWORK_ADD",
        "tag": "example.com:ed10e4b2-8a64-4afa-a4e2-9e60a766d079"
    },
    "errors": [],
    "messages": []
}

For future reference, the "id" in response is used as DNSZONE_ID.

Get a DNS zone with the API

Use the following command to get an existing zone.

Request

curl -X GET \
  $DNSSVCS_ENDPOINT/v1/instances/$INSTANCE_ID/dnszones/$DNSZONE_ID \
  -H "Authorization: $TOKEN"

Response

{
    "success": true,
    "result": {
        "id": "example.com:ed10e4b2-8a64-4afa-a4e2-9e60a766d079",
        "created_on": "2019-07-24 12:30:58.357201205 +0000 UTC",
        "modified_on": "2019-07-24 12:30:58.357201205 +0000 UTC",
        "instance_id": "1a34bda8-9c94-4232-bea7-7df163b21d23",
        "name": "example.com",
        "description": "Example zone",
        "state": "PENDING_NETWORK_ADD"
    },
    "errors": [],
    "messages": []
}

Updating a DNS zone with the API

Use the following command to update an existing zone. You can update the description and label fields. All other fields are read-only.

Request

curl -X PATCH \
  $DNSSVCS_ENDPOINT/v1/instances/$INSTANCE_ID/dnszones/$DNSZONE_ID \
  -H 'Content-Type: application/json' \
  -H "Authorization: $TOKEN" \
  -d '{
    "description": "The DNS zone is used for VPCs in us-east region",
    "label": "us-east"
}'

Response

{
  "created_on": "2019-01-01T05:20:00.12345Z",
  "description": "The DNS zone is used for VPCs in us-east region",
  "id": "example.com:2d0f862b-67cc-41f3-b6a2-59860d0aa90e",
  "instance_id": "1407a753-a93f-4bb0-9784-bcfc269ee1b3",
  "label": "us-east",
  "modified_on": "2019-01-01T05:20:00.12345Z",
  "name": "example.com",
  "state": "PENDING_NETWORK_ADD"
}

List DNS zones with the API

List one or more zones in your domain by using the following curl command:

Request

curl -X GET \
  $DNSSVCS_ENDPOINT/v1/instances/$INSTANCE_ID/dnszones \
  -H "Authorization: $TOKEN"

Response

{
    "success": true,
    "result": [
        {
            "id": "example.com:ed10e4b2-8a64-4afa-a4e2-9e60a766d079",
            "created_on": "2019-07-24 12:30:58.357201205 +0000 UTC",
            "modified_on": "2019-07-24 12:30:58.357201205 +0000 UTC",
            "instance_id": "1a34bda8-9c94-4232-bea7-7df163b21d23",
            "name": "example.com",
            "description": "Example zone",
            "state": "PENDING_NETWORK_ADD"
        }
    ],
    "errors": [],
    "messages": []
}

Delete a DNS zone with the API

Request

curl -X DELETE \
  $DNSSVCS_ENDPOINT/v1/instances/$INSTANCE_ID/dnszones/$DNSZONE_ID \
  -H "Authorization: $TOKEN"

Response

HTTP/2 204 No Content