Skip to content

Latest commit

 

History

History
395 lines (254 loc) · 20.3 KB

dns-operations-recordsets.md

File metadata and controls

395 lines (254 loc) · 20.3 KB
title description services documentationcenter author manager ms.assetid ms.service ms.devlang ms.topic ms.tgt_pltfrm ms.custom ms.workload ms.date ms.author
Manage DNS records in Azure DNS using Azure PowerShell | Microsoft Docs
Managing DNS record sets and records on Azure DNS when hosting your domain on Azure DNS. All PowerShell commands for operations on record sets and records.
dns
na
vhorne
timlt
7136a373-0682-471c-9c28-9e00d2add9c2
dns
na
article
na
H1Hack27Feb2017
infrastructure-services
12/21/2016
victorh

Manage DNS records and recordsets in Azure DNS using Azure PowerShell

[!div class="op_single_selector"]

This article shows you how to manage DNS records for your DNS zone by using Azure PowerShell. DNS records can also be managed by using the cross-platform Azure CLI or the Azure portal.

The examples in this article assume you have already installed Azure PowerShell, signed in, and created a DNS zone.

Introduction

Before creating DNS records in Azure DNS, you first need to understand how Azure DNS organizes DNS records into DNS record sets.

[!INCLUDE dns-about-records-include]

For more information about DNS records in Azure DNS, see DNS zones and records.

Create a new DNS record

If your new record has the same name and type as an existing record, you need to add it to the existing record set. If your new record has a different name and type to all existing records, you need to create a new record set.

Create 'A' records in a new record set

You create record sets by using the New-AzureRmDnsRecordSet cmdlet. When creating a record set, you need to specify the record set name, the zone, the time to live (TTL), the record type, and the records to be created.

The parameters for adding records to a record set vary depending on the type of the record set. For example, when using a record set of type 'A', you need to specify the IP address using the parameter -IPv4Address. Other parameters are used for other record types. See Additional record type examples for details.

The following example creates a record set with the relative name 'www' in the DNS Zone 'contoso.com'. The fully-qualified name of the record set is 'www.contoso.com'. The record type is 'A', and the TTL is 3600 seconds. The record set contains a single record, with IP address '1.2.3.4'.

New-AzureRmDnsRecordSet -Name "www" -RecordType A -ZoneName "contoso.com" -ResourceGroupName "MyResourceGroup" -Ttl 3600 -DnsRecords (New-AzureRmDnsRecordConfig -IPv4Address "1.2.3.4")

To create a record set at the 'apex' of a zone (in this case, 'contoso.com'), use the record set name '@' (excluding quotation marks):

New-AzureRmDnsRecordSet -Name "@" -RecordType A -ZoneName "contoso.com" -ResourceGroupName "MyResourceGroup" -Ttl 3600 -DnsRecords (New-AzureRmDnsRecordConfig -IPv4Address "1.2.3.4")

If you need to create a record set containing more than one record, first create a local array and add the records, then pass the array to New-AzureRmDnsRecordSet as follows:

$aRecords = @()
$aRecords += New-AzureRmDnsRecordConfig -IPv4Address "1.2.3.4"
$aRecords += New-AzureRmDnsRecordConfig -IPv4Address "2.3.4.5"
New-AzureRmDnsRecordSet -Name www –ZoneName "contoso.com" -ResourceGroupName MyResourceGroup -Ttl 3600 -RecordType A -DnsRecords $aRecords

Record set metadata can be used to associate application-specific data with each record set, as key-value pairs. The following example shows how to create a record set with two metadata entries, 'dept=finance' and 'environment=production'.

New-AzureRmDnsRecordSet -Name "www" -RecordType A -ZoneName "contoso.com" -ResourceGroupName "MyResourceGroup" -Ttl 3600 -DnsRecords (New-AzureRmDnsRecordConfig -IPv4Address "1.2.3.4") -Metadata @{ dept="finance"; environment="production" }

Azure DNS also supports 'empty' record sets, which can act as a placeholder to reserve a DNS name before creating DNS records. Empty record sets are visible in the Azure DNS control plane, but do appear on the Azure DNS name servers. The following example creates an empty record set:

New-AzureRmDnsRecordSet -Name "www" -RecordType A -ZoneName "contoso.com" -ResourceGroupName "MyResourceGroup" -Ttl 3600 -DnsRecords @()

Create records of other types

Having seen in detail how to create 'A' records, the following examples show how to create records of other record types supported by Azure DNS.

In each case, we show how to create a record set containing a single record. The earlier examples for 'A' records can be adapted to create record sets of other types containing multiple records, with metadata, or to create empty record sets.

We do not give an example to create an SOA record set, since SOAs are created and deleted with each DNS zone and cannot be created or deleted separately. However, the SOA can be modified, as shown in a later example.

Create an AAAA record set with a single record

New-AzureRmDnsRecordSet -Name "test-aaaa" -RecordType AAAA -ZoneName "contoso.com" -ResourceGroupName "MyResourceGroup" -Ttl 3600 -DnsRecords (New-AzureRmDnsRecordConfig -Ipv6Address "2607:f8b0:4009:1803::1005")

Create a CAA record set with a single record

New-AzureRmDnsRecordSet -Name "test-caa" -RecordType CAA -ZoneName "contoso.com" -ResourceGroupName "MyResourceGroup" -Ttl 3600 -DnsRecords (New-AzureRmDnsRecordConfig -Caaflags 0 -CaaTag "issue" -CaaValue "ca1.contoso.com")

Create a CNAME record set with a single record

Note

The DNS standards do not permit CNAME records at the apex of a zone (-Name '@'), nor do they permit record sets containing more than one record.

For more information, see CNAME records.

New-AzureRmDnsRecordSet -Name "test-cname" -RecordType CNAME -ZoneName "contoso.com" -ResourceGroupName "MyResourceGroup" -Ttl 3600 -DnsRecords (New-AzureRmDnsRecordConfig -Cname "www.contoso.com")

Create an MX record set with a single record

In this example, we use the record set name '@' to create an MX record at the zone apex (in this case, 'contoso.com').

New-AzureRmDnsRecordSet -Name "@" -RecordType MX -ZoneName "contoso.com" -ResourceGroupName "MyResourceGroup" -Ttl 3600 -DnsRecords (New-AzureRmDnsRecordConfig -Exchange "mail.contoso.com" -Preference 5)

Create an NS record set with a single record

New-AzureRmDnsRecordSet -Name "test-ns" -RecordType NS -ZoneName "contoso.com" -ResourceGroupName "MyResourceGroup" -Ttl 3600 -DnsRecords (New-AzureRmDnsRecordConfig -Nsdname "ns1.contoso.com")

Create a PTR record set with a single record

In this case, 'my-arpa-zone.com' represents the ARPA reverse lookup zone representing your IP range. Each PTR record set in this zone corresponds to an IP address within this IP range. The record name '10' is the last octet of the IP address within this IP range represented by this record.

New-AzureRmDnsRecordSet -Name 10 -RecordType PTR -ZoneName "my-arpa-zone.com" -ResourceGroupName "MyResourceGroup" -Ttl 3600 -DnsRecords (New-AzureRmDnsRecordConfig -Ptrdname "myservice.contoso.com")

Create an SRV record set with a single record

When creating an SRV record set, specify the _service and _protocol in the record set name. There is no need to include '@' in the record set name when creating an SRV record set at the zone apex.

New-AzureRmDnsRecordSet -Name "_sip._tls" -RecordType SRV -ZoneName "contoso.com" -ResourceGroupName "MyResourceGroup" -Ttl 3600 -DnsRecords (New-AzureRmDnsRecordConfig -Priority 0 -Weight 5 -Port 8080 -Target "sip.contoso.com")

Create a TXT record set with a single record

The following example shows how to create a TXT record. For more information about the maximum string length supported in TXT records, see TXT records.

New-AzureRmDnsRecordSet -Name "test-txt" -RecordType TXT -ZoneName "contoso.com" -ResourceGroupName "MyResourceGroup" -Ttl 3600 -DnsRecords (New-AzureRmDnsRecordConfig -Value "This is a TXT record")

Get a record set

To retrieve an existing record set, use Get-AzureRmDnsRecordSet. This cmdlet returns a local object that represents the record set in Azure DNS.

As with New-AzureRmDnsRecordSet, the record set name given must be a relative name, meaning it must exclude the zone name. You also need to specify the record type, and the zone containing the record set.

The following example shows how to retrieve a record set. In this example, the zone is specified using the -ZoneName and -ResourceGroupName parameters.

$rs = Get-AzureRmDnsRecordSet -Name "www" -RecordType A -ZoneName "contoso.com" -ResourceGroupName "MyResourceGroup"

Alternatively, you can also specify the zone using a zone object, passed using the -Zone parameter.

$zone = Get-AzureRmDnsZone -Name "contoso.com" -ResourceGroupName "MyResourceGroup"
$rs = Get-AzureRmDnsRecordSet -Name "www" -RecordType A -Zone $zone

List record sets

You can also use Get-AzureRmDnsZone to list record sets in a zone, by omitting the -Name and/or -RecordType parameters.

The following example returns all record sets in the zone:

$recordsets = Get-AzureRmDnsRecordSet -ZoneName "contoso.com" -ResourceGroupName "MyResourceGroup"

The following example shows how all record sets of a given type can be retrieved by specifying the record type while omitting the record set name:

$recordsets = Get-AzureRmDnsRecordSet -RecordType A -ZoneName "contoso.com" -ResourceGroupName "MyResourceGroup"

To retrieve all record sets with a given name, across record types, you need to retrieve all record sets and then filter the results:

$recordsets = Get-AzureRmDnsRecordSet -ZoneName "contoso.com" -ResourceGroupName "MyResourceGroup" | where {$_.Name.Equals("www")}

In all the above examples, the zone can be specified either by using the -ZoneName and -ResourceGroupNameparameters (as shown), or by specifying a zone object:

$zone = Get-AzureRmDnsZone -Name "contoso.com" -ResourceGroupName "MyResourceGroup"
$recordsets = Get-AzureRmDnsRecordSet -Zone $zone

Add a record to an existing record set

To add a record to an existing record set, follow the following three steps:

  1. Get the existing record set

    $rs = Get-AzureRmDnsRecordSet -Name www –ZoneName "contoso.com" -ResourceGroupName "MyResourceGroup" -RecordType A

  2. Add the new record to the local record set. This is an off-line operation.

    Add-AzureRmDnsRecordConfig -RecordSet $rs -Ipv4Address "5.6.7.8"

  3. Commit the change back to the Azure DNS service.

    Set-AzureRmDnsRecordSet -RecordSet $rs

Using Set-AzureRmDnsRecordSet replaces the existing record set in Azure DNS (and all records it contains) with the record set specified. Etag checks are used to ensure concurrent changes are not overwritten. You can use the optional -Overwrite switch to suppress these checks.

This sequence of operations can also be piped, meaning you pass the record set object by using the pipe rather than passing it as a parameter:

Get-AzureRmDnsRecordSet -Name "www" –ZoneName "contoso.com" -ResourceGroupName "MyResourceGroup" -RecordType A | Add-AzureRmDnsRecordConfig -Ipv4Address "5.6.7.8" | Set-AzureRmDnsRecordSet

The examples above show how to add an 'A' record to an existing record set of type 'A'. A similar sequence of operations is used to add records to record sets of other types, substituting the -Ipv4Address parameter of Add-AzureRmDnsRecordConfig with other parameters specific to each record type. The parameters for each record type are the same as for the New-AzureRmDnsRecordConfig cmdlet, as shown in Additional record type examples above.

Record sets of type 'CNAME' or 'SOA' cannot contain more than one record. This constraint arises from the DNS standards. It is not a limitation of Azure DNS.

Remove a record from an existing record set

The process to remove a record from a record set is similar to the process to add a record to an existing record set:

  1. Get the existing record set

    $rs = Get-AzureRmDnsRecordSet -Name www –ZoneName "contoso.com" -ResourceGroupName "MyResourceGroup" -RecordType A

  2. Remove the record from the local record set object. This is an off-line operation. The record that's being removed must be an exact match with an existing record across all parameters.

    Remove-AzureRmDnsRecordConfig -RecordSet $rs -Ipv4Address "5.6.7.8"

  3. Commit the change back to the Azure DNS service. Use the optional -Overwrite switch to suppress Etag checks for concurrent changes.

    Set-AzureRmDnsRecordSet -RecordSet $Rs

Using the above sequence to remove the last record from a record set does not delete the record set, rather it leaves an empty record set. To remove a record set entirely, see Delete a record set.

Similarly to adding records to a record set, the sequence of operations to remove a record set can also be piped:

Get-AzureRmDnsRecordSet -Name www –ZoneName "contoso.com" -ResourceGroupName "MyResourceGroup" -RecordType A | Remove-AzureRmDnsRecordConfig -Ipv4Address "5.6.7.8" | Set-AzureRmDnsRecordSet

Different record types are supported by passing the appropriate type-specific parameters to Remove-AzureRmDnsRecordSet. The parameters for each record type are the same as for the New-AzureRmDnsRecordConfig cmdlet, as shown in Additional record type examples above.

Modify an existing record set

The steps for modifying an existing record set are similar to the steps you take when adding or removing records from a record set:

  1. Retrieve the existing record set by using Get-AzureRmDnsRecordSet.
  2. Modify the local record set object by:
    • Adding or removing records
    • Changing the parameters of existing records
    • Changing the record set metadata and time to live (TTL)
  3. Commit your changes by using the Set-AzureRmDnsRecordSet cmdlet. This replaces the existing record set in Azure DNS with the record set specified.

When using Set-AzureRmDnsRecordSet, Etag checks are used to ensure concurrent changes are not overwritten. You can use the optional -Overwrite switch to suppress these checks.

To update a record in an existing record set

In this example, we change the IP address of an existing 'A' record:

$rs = Get-AzureRmDnsRecordSet -name "www" -RecordType A -ZoneName "contoso.com" -ResourceGroupName "MyResourceGroup"
$rs.Records[0].Ipv4Address = "9.8.7.6"
Set-AzureRmDnsRecordSet -RecordSet $rs

To modify an SOA record

You cannot add or remove records from the automatically created SOA record set at the zone apex (-Name "@", including quote marks). However, you can modify any of the parameters within the SOA record (except "Host") and the record set TTL.

The following example shows how to change the Email property of the SOA record:

$rs = Get-AzureRmDnsRecordSet -Name "@" -RecordType SOA -ZoneName "contoso.com" -ResourceGroupName "MyResourceGroup"
$rs.Records[0].Email = "admin.contoso.com"
Set-AzureRmDnsRecordSet -RecordSet $rs

To modify NS records at the zone apex

The NS record set at the zone apex is automatically created with each DNS zone. It contains the names of the Azure DNS name servers assigned to the zone.

You can add additional name servers to this NS record set, to support co-hosting domains with more than one DNS provider. You can also modify the TTL and metadata for this record set. However, you cannot remove or modify the pre-populated Azure DNS name servers.

Note that this applies only to the NS record set at the zone apex. Other NS record sets in your zone (as used to delegate child zones) can be modified without constraint.

The following example shows how to add an additional name server to the NS record set at the zone apex:

$rs = Get-AzureRmDnsRecordSet -Name "@" -RecordType NS -ZoneName "contoso.com" -ResourceGroupName "MyResourceGroup"
Add-AzureRmDnsRecordConfig -RecordSet $rs -Nsdname ns1.myotherdnsprovider.com
Set-AzureRmDnsRecordSet -RecordSet $rs

To modify record set metadata

Record set metadata can be used to associate application-specific data with each record set, as key-value pairs.

The following example shows how to modify the metadata of an existing record set:

# Get the record set
$rs = Get-AzureRmDnsRecordSet -Name www -RecordType A -ZoneName "contoso.com" -ResourceGroupName "MyResourceGroup"

# Add 'dept=finance' name-value pair
$rs.Metadata.Add('dept', 'finance') 

# Remove metadata item named 'environment'
$rs.Metadata.Remove('environment')  

# Commit changes
Set-AzureRmDnsRecordSet -RecordSet $rs

Delete a record set

Record sets can be deleted by using the Remove-AzureRmDnsRecordSet cmdlet. Deleting a record set also deletes all records within the record set.

Note

You cannot delete the SOA and NS record sets at the zone apex (-Name '@'). Azure DNS created these automatically when the zone was created, and deletes them automatically when the zone is deleted.

The following example shows how to delete a record set. In this example, the record set name, record set type, zone name, and resource group are each specified explicitly.

Remove-AzureRmDnsRecordSet -Name "www" -RecordType A -ZoneName "contoso.com" -ResourceGroupName "MyResourceGroup"

Alternatively, the record set can be specified by name and type, and the zone specified using an object:

$zone = Get-AzureRmDnsZone -Name "contoso.com" -ResourceGroupName "MyResourceGroup"
Remove-AzureRmDnsRecordSet -Name "www" -RecordType A -Zone $zone

As a third option, the record set itself can be specified using a record set object:

$rs = Get-AzureRmDnsRecordSet -Name www -RecordType A -ZoneName "contoso.com" -ResourceGroupName "MyResourceGroup"
Remove-AzureRmDnsRecordSet -RecordSet $rs

When you specify the record set to be deleted by using a record set object, Etag checks are used to ensure concurrent changes are not deleted. You can use the optional -Overwrite switch to suppress these checks.

The record set object can also be piped instead of being passed as a parameter:

Get-AzureRmDnsRecordSet -Name www -RecordType A -ZoneName "contoso.com" -ResourceGroupName "MyResourceGroup" | Remove-AzureRmDnsRecordSet

Confirmation prompts

The New-AzureRmDnsRecordSet, Set-AzureRmDnsRecordSet, and Remove-AzureRmDnsRecordSet cmdlets all support confirmation prompts.

Each cmdlet prompts for confirmation if the $ConfirmPreference PowerShell preference variable has a value of Medium or lower. Since the default value for $ConfirmPreference is High, these prompts are not given when using the default PowerShell settings.

You can override the current $ConfirmPreference setting using the -Confirm parameter. If you specify -Confirm or -Confirm:$True , the cmdlet prompts you for confirmation before it runs. If you specify -Confirm:$False , the cmdlet does not prompt you for confirmation.

For more information about -Confirm and $ConfirmPreference, see About Preference Variables.

Next steps

Learn more about zones and records in Azure DNS.
Learn how to protect your zones and records when using Azure DNS.
Review the Azure DNS PowerShell reference documentation.