Setting up your DNS Services instance

Creating a DNS Services instance in the UI

1. Open the IBM Cloud Catalog page.

2. Select the Networking category.

3. Click the DNS Services tile.

4. Choose a plan.

5. Enter Service name and click Create.

   You are redirected to the DNS Services instance page showing DNS Zones information.

You can also navigate directly to the DNS Services instance creation by going to the DNS Services catalog entry.

Creating a DNS zone in the UI

1. Navigate to the Resource page and select your DNS Services instance.
2. On the DNS Zones page, click Create zone.
3. In the Create Zone panel, enter your zone name. Optionally, enter a label and description.
4. Click Create zone in the panel. If the zone is created successfully, you are redirected to the Zone Details page.

Creating an "A" resource record in the UI

1. Navigate to the Resource page and select your DNS Services instance. Then select your zone.
2. On the DNS Details page, click the DNS Records tab.
3. Click Select record action, and select Add record from the list menu.
4. In the Add Record panel, select the type of DNS record that you want to add from the Type menu. In this case, select the type A.
5. Enter the required data for the type of DNS record you selected. In this case, for type A, enter Name and IPv4 Address.
6. Click Add record in the panel.

Creating a permitted network in the UI

1. Navigate to the Resource page and select your DNS Services instance. Then select your zone.

2. Click the Permitted Networks tab.

3. Click Add network.

4. In the Add Network panel, select the region of your VPC from the Network Region menu.

5. Select the VPC from the Network menu that appears.

6. Click Add network.

   This request adds the VPC network to your zone, thereby giving the network access to the zone.

Creating a DNS Services instance with the API

See the create a new resource instance documentation for the Resource Controller API. Note that the resource_group and resource_plan_id must be set. Each account can have multiple resource groups, and each resource group has a unique ID.

Set the variables as follows to create an instance of the standard plan:

"resource_plan_id": "2c8fa097-d7c2-4df2-b53e-2efb7874cdf7",

See the Resource Controller API reference documentation for more information on using the API.

Command lines for instances are using resource controller API, not DNS APIs. These commands are equivalent to commands ibmcloud resource service-instance, which provide convenience for DNS users to manage DNS Services instances.

Creating a DNS zone with the API

You must create a VPC so that you can link your DNS zone to the VPC.

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 endpoint in a variable, run this command:

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

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

After you gather details about your instance, run the following curl command to create a DNS zone:

curl -X POST \
  $DNSSVCS_ENDPOINT/v1/instances/$INSTANCE_ID/dnszones \
  -H "Authorization: $TOKEN" \
  -d '{
        "name": "example.com",
        "description": "The DNS zone is used for VPCs in the us-east region",
        "label": "us-east"
  }'

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

Creating a permitted network with the API

DNS Services allows name resolution only from a VPC that was added to the DNS zone.

When a DNS zone gets created, its Status is PENDING_NETWORK_ADD. To move the zone to ACTIVE state, add an entry for your VPC to the zone's permitted network.

By adding your VPC to your zone's permitted network, compute instances on your VPC can access these resource records.

curl -X POST \
  $DNSSVCS_ENDPOINT/v1/instances/$INSTANCE_ID/dnszones/$DNSZONE_ID/acls \
  -H "Authorization: $TOKEN" \
  -d '{
        "type": "vpc",
        "acl_data": {
            "vpc_crn": "crn:v1:staging:public:is:us-east:a/40705ee14536813e2385f26c20be24a5::vpc:ed5e3cdd-8a4f-45ce-bae4-2774cb028caf"
        }
  }'

{
  "id": "fecd0173-3919-456b-b202-3029dfa1b0f7",
  "created_on": "2019-01-01T05:20:00.12345Z",
  "modified_on": "2019-01-01T05:20:00.12345Z",
  "acl_data": {
    "vpc_crn": "crn:v1:staging:public:is:us-east:a/40705ee14536813e2385f26c20be24a5::vpc:ed5e3cdd-8a4f-45ce-bae4-2774cb028caf"
  },
  "type": "vpc"
}

Creating an "A" resource record with the API

An A Record (Address Record) is a DNS resource record that associates a domain or subdomain to an IPv4 address.

curl -X POST \
  $DNSSVCS_ENDPOINT/v1/instances/$INSTANCE_ID/dnszones/$DNSZONE_ID/resource_records \
  -H "Authorization: $TOKEN" \
  -d '{
        "name":"www.example.com",
        "type":"A",
        "rdata": {
            "ip":"1.2.6.7"
        },
        "ttl":300
  }'

{
   "created_on":"2019-09-13 19:56:42.484382585 +0000 UTC",
   "modified_on":"2019-09-13 19:56:42.484382585 +0000 UTC",
   "rtype":"A",
   "ttl":300,
   "name":"www.example.com.testZone.com",
   "id":"A:786c07c7-173e-473b-aa09-c186601a5709",
   "rdata":{
      "ip":"1.2.6.7"
   }
}