Create a custom IPv4 address prefix using Azure PowerShell

A custom IPv4 address prefix enables you to bring your own IPv4 ranges to Microsoft and associate it to your Azure subscription. The range would continue to be owned by you, though Microsoft would be permitted to advertise it to the Internet. A custom IP address prefix functions as a regional resource that represents a contiguous block of customer owned IP addresses.

The steps in this article detail the process to:

  • Prepare a range to provision

  • Provision the range for IP allocation

  • Enable the range to be advertised by Microsoft

Prerequisites

  • An Azure account with an active subscription. Create an account for free.
  • Azure PowerShell installed locally or Azure Cloud Shell.
  • Sign in to Azure PowerShell and ensure you've selected the subscription with which you want to use this feature. For more information, see Sign in with Azure PowerShell.
  • Ensure your Az.Network module is 5.1.1 or later. To verify the installed module, use the command Get-InstalledModule -Name "Az.Network". If the module requires an update, use the command Update-Module -Name "Az.Network" if necessary.
  • A customer owned IPv4 range to provision in Azure.
    • A sample customer range (1.2.3.0/24) is used for this example. This range won't be validated by Azure. Replace the example range with yours.

If you choose to install and use PowerShell locally, this article requires the Azure PowerShell module version 5.4.1 or later. Run Get-Module -ListAvailable Az to find the installed version. If you need to upgrade, see Install Azure PowerShell module. If you're running PowerShell locally, you also need to run Connect-AzAccount to create a connection with Azure.

Note

For problems encountered during the provisioning process, please see Troubleshooting for custom IP prefix.

Pre-provisioning steps

To utilize the Azure BYOIP feature, you must perform the following steps prior to the provisioning of your IPv4 address range.

Requirements and prefix readiness

  • The address range must be owned by you and registered under your name with the American Registry for Internet Numbers (ARIN), the Réseaux IP Européens Network Coordination Centre (RIPE NCC), or the Asia Pacific Network Information Centre Regional Internet Registries (APNIC). If the range is registered under the Latin America and Caribbean Network Information Centre (LACNIC) or the African Network Information Centre (AFRINIC), contact the Microsoft Azure BYOIP team.

  • The address range must be no smaller than a /24 so it will be accepted by Internet Service Providers.

  • A Route Origin Authorization (ROA) document that authorizes Microsoft to advertise the address range must be filled out by the customer on the appropriate Routing Internet Registry (RIR) website or via their API. The RIR will require the ROA to be digitally signed with the Resource Public Key Infrastructure (RPKI) of your RIR.

    For this ROA:

    • The Origin AS must be listed as 8075 for the Public Cloud. (If the range will be onboarded to the US Gov Cloud, the Origin AS must be listed as 8070.)

    • The validity end date (expiration date) needs to account for the time you intend to have the prefix advertised by Microsoft. Some RIRs don't present validity end date as an option and or choose the date for you.

    • The prefix length should exactly match the prefixes that can be advertised by Microsoft. For example, if you plan to bring 1.2.3.0/24 and 2.3.4.0/23 to Microsoft, they should both be named.

    • After the ROA is complete and submitted, allow at least 24 hours for it to become available to Microsoft, where it will be verified to determine its authenticity and correctness as part of the provisioning process.

Note

It is also recommended to create a ROA for any existing ASN that is advertising the range to avoid any issues during migration.

Certificate readiness

To authorize Microsoft to associate a prefix with a customer subscription, a public certificate must be compared against a signed message.

The following steps show the steps required to prepare sample customer range (1.2.3.0/24) for provisioning to the Public cloud.

Note

Execute the following commands in PowerShell with OpenSSL installed.

  1. A self-signed X509 certificate must be created to add to the Whois/RDAP record for the prefix. For information about RDAP, see the ARIN, RIPE, and APNIC sites.

    An example utilizing the OpenSSL toolkit is shown below. The following commands generate an RSA key pair and create an X509 certificate using the key pair that expires in six months:

    ./openssl genrsa -out byoipprivate.key 2048
    Set-Content -Path byoippublickey.cer (./openssl req -new -x509 -key byoipprivate.key -days 180) -NoNewline
    
  2. After the certificate is created, update the public comments section of the Whois/RDAP record for the prefix. To display for copying, including the BEGIN/END header/footer with dashes, use the command cat byoippublickey.cer You should be able to perform this procedure via your Routing Internet Registry.

    Instructions for each registry are below:

    • ARIN - edit the "Comments" of the prefix record.

    • RIPE - edit the "Remarks" of the inetnum record.

    • APNIC - edit the “Remarks” of the inetnum record using MyAPNIC.

    • For ranges from either LACNIC or AFRINIC registries, create a support ticket with Microsoft.

    After the public comments are filled out, the Whois/RDAP record should look like the example below. Ensure there aren't spaces or carriage returns. Include all dashes:

    Screenshot of example certificate comment

  3. To create the message that will be passed to Microsoft, create a string that contains relevant information about your prefix and subscription. Sign this message with the key pair generated in the steps above. Use the format shown below, substituting your subscription ID, prefix to be provisioned, and expiration date matching the Validity Date on the ROA. Ensure the format is in that order.

    Use the following command to create a signed message that will be passed to Microsoft for verification.

    Note

    If the Validity End date was not included in the original ROA, pick a date that corresponds to the time you intend to have the prefix advertised by Azure.

    $byoipauth="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx|1.2.3.0/24|yyyymmdd"
    Set-Content -Path byoipauth.txt -Value $byoipauth -NoNewline
    ./openssl dgst -sha256 -sign byoipprivate.key -keyform PEM -out byoipauthsigned.txt byoipauth.txt
    $byoipauthsigned=(./openssl enc -base64 -in byoipauthsigned.txt) -join ''
    
  4. To view the contents of the signed message, enter the variable created from the signed message created previously and select Enter at the PowerShell prompt:

    $byoipauthsigned
    dIlwFQmbo9ar2GaiWRlSEtDSZoH00I9BAPb2ZzdAV2A/XwzrUdz/85rNkXybXw457//gHNNB977CQvqtFxqqtDaiZd9bngZKYfjd203pLYRZ4GFJnQFsMPFSeePa8jIFwGJk6JV4reFqq0bglJ3955dVz0v09aDVqjj5UJx2l3gmyJEeU7PXv4wF2Fnk64T13NESMeQk0V+IaEOt1zXgA+0dTdTLr+ab56pR0RZIvDD+UKJ7rVE7nMlergLQdpCx1FoCTm/quY3aiSxndEw7aQDW15+rSpy+yxV1iCFIrUa/4WHQqP4LtNs3FATvLKbT4dBcBLpDhiMR+j9MgiJymA==
    

Provisioning steps

The following steps display the procedure for provisioning a sample customer range (1.2.3.0/24) to the US West 2 region.

Note

Clean up or delete steps aren't shown on this page given the nature of the resource. For information on removing a provisioned custom IP prefix, see Manage custom IP prefix.

Create a resource group and specify the prefix and authorization messages

Create a resource group in the desired location for provisioning the BYOIP range.

$rg =@{
   Name = 'myResourceGroup'
   Location = 'WestUS2'
}
New-AzResourceGroup @rg

Provision a custom IP address prefix

The following command creates a custom IP prefix in the specified region and resource group. Specify the exact prefix in CIDR notation as a string to ensure there's no syntax error. For the -AuthorizationMessage parameter, substitute your subscription ID, prefix to be provisioned, and expiration date matching the Validity Date on the ROA. Ensure the format is in that order. Use the variable $byoipauthsigned for the -SignedMessage parameter created in the certificate readiness section.

$prefix =@{
   Name = 'myCustomIPPrefix'
   ResourceGroupName = 'myResourceGroup'
   Location = 'WestUS2'
   CIDR = '1.2.3.0/24'
   AuthorizationMessage = 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx|1.2.3.0/24|yyyymmdd'
   SignedMessage = $byoipauthsigned
}
$myCustomIpPrefix = New-AzCustomIPPrefix @prefix -Zone 1,2,3

The range will be pushed to the Azure IP Deployment Pipeline. The deployment process is asynchronous. To determine the status, execute the following command:

Get-AzCustomIpPrefix -ResourceId $myCustomIpPrefix.Id

Sample output is shown below, with some fields removed for clarity:

Name              : myCustomIpPrefix
ResourceGroupName : myResourceGroup
Location          : westus2
Id                : /subscriptions/xxxx/resourceGroups/myResourceGroup/providers/Microsoft.Network/customIPPrefixes/MyCustomIPPrefix
Cidr              : 1.2.3.0/24
Zones             : {1, 2, 3}
CommissionedState : Provisioning

The CommissionedState field should show the range as Provisioning initially, followed in the future by Provisioned.

Note

The estimated time to complete the provisioning process is 30 minutes.

Important

After the custom IP prefix is in a Provisioned state, a child public IP prefix can be created. These public IP prefixes and any public IP addresses can be attached to networking resources. For example, virtual machine network interfaces or load balancer front ends. The IPs won't be advertised and therefore won't be reachable. For more information on a migration of an active prefix, see Manage a custom IP prefix.

Commission the custom IP address prefix

When the custom IP prefix is in the Provisioned state, the following command updates the prefix to begin the process of advertising the range from Azure.

Update-AzCustomIpPrefix -ResourceId $myCustomIPPrefix.Id -Commission

As before, the operation is asynchronous. Use Get-AzCustomIpPrefix to retrieve the status. The CommissionedState field will initially show the prefix as Commissioning, followed in the future by Commissioned. The advertisement rollout isn't binary and the range will be partially advertised while still in Commissioning.

Note

The estimated time to fully complete the commissioning process is 3-4 hours.

Important

As the custom IP prefix transitions to a Commissioned state, the range is being advertised with Microsoft from the local Azure region and globally to the Internet by Microsoft's wide area network under Autonomous System Number (ASN) 8075. Advertising this same range to the Internet from a location other than Microsoft at the same time could potentially create BGP routing instability or traffic loss. For example, a customer on-premises building. Plan any migration of an active range during a maintenance period to avoid impact. Additionally, you could take advantage of the regional commissioning feature to put a custom IP prefix into a state where it is only advertised within the Azure region it is deployed in-- see Manage a custom IP address prefix (BYOIP) for more information.

Next steps