Manage a custom IP address prefix
A custom IP address prefix is a contiguous range of IP addresses owned by an external customer and provisioned into a subscription. The customer owns the range and permits Microsoft to advertise the range. For more information, see Custom IP address prefix overview.
This article explains how to:
Use the regional commissioning feature to safely migrate an active prefix to Azure
Create public IP prefixes from provisioned custom IP prefixes
Migrate active IP prefixes from outside Microsoft
View information about a custom IP prefix
Decommission a custom IP prefix
Deprovision/delete a custom IP prefix
For information on provisioning an IP address, see Create a custom IP address prefix - Azure portal, Create a custom IP address prefix - Azure PowerShell, or Create a custom IP address prefix - Azure CLI.
Create a public IP prefix from a custom IP prefix
When a unified (or regional) model custom IP prefix is in Provisioned, Commissioning, or Commissioned state, a linked public IP prefix can be created. Either as a subset of the custom IP prefix range or the entire range.
Use the following CLI and PowerShell commands to create public IP prefixes with the --custom-ip-prefix-name (CLI) and -CustomIpPrefix (PowerShell) parameters that point to an existing custom IP prefix.
| Tool | Command |
|---|---|
| CLI | az network custom-ip prefix update |
| PowerShell | New-AzPublicIpPrefix |
Note
A public IP prefix can be derived from a custom IP prefix in another subscription with the appropriate permissions using Azure PowerShell or Azure portal.
The example derivation of a public IP prefix from a custom IP prefix using PowerShell is shown as follows:
Set-AzContext -Subscription xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
$customprefix = Get-AzCustomIpPrefix -Name myBYOIPPrefix -ResourceGroupName myResourceGroup
Set-AzContext -Subscription yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy
New-AzPublicIpPrefix -Name myPublicIpPrefix -ResourceGroupName myResourceGroup2 -Location eastus -PrefixLength 30 -CustomIpPrefix $customprefix
Once created, the IPs in the child public IP prefix can be associated with resources like any other standard SKU static public IPs. To learn more about using IPs from a public IP prefix, including selection of a specific IP from the range, see Create a static public IP address from a prefix.
Migration of active prefixes from outside Microsoft
If another network advertises the provisioned range to the Internet, you should plan the migration to Azure to prevent unplanned downtime. Use a maintenance window to make the transition, no matter which method you choose.
Method 1: Create public IP prefixes and public IP addresses from the prefixes when the custom IP prefix is in a "Provisioned" state.
- The public IPs can be associated to networking resources but aren't advertised and aren't reachable. When the command to update the custom IP prefix to the Commissioned state is executed, the IPs advertise from Microsoft's network. Any advertisement of this same range from a location other than Microsoft could potentially create BGP routing instability or traffic loss. For example, a customer on-premises building. The advertisement should be disabled once the Azure infrastructure has been verified as operational.
Method 2: Create public IP prefixes and public IP addresses from the prefixes using Microsoft ranges. Deploy an infrastructure in your subscription and verify it's operational.
Create a second set of mirrored public IP prefixes and public IP addresses from the prefixes when the custom IP prefix is in a Provisioned state. Add the provisioned IPs to the existing infrastructure. For example, add another network interface to a virtual machine or another frontend for a load balancer. Perform a change to the desired IPs before issuing the command to move the custom IP prefix to the Commissioned state.
Alternatively, the ranges can be commissioned first and then changed. This process doesn't work for all resource types with public IPs. In those cases, a new resource with the provisioned public IP must be created.
Use the regional commissioning feature for unified model custom IP prefixes
When a unified model custom IP prefix transitions to a fully 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. If the range is currently being advertised to the Internet from a location other than Microsoft at the same time, there's the potential for BGP routing instability or traffic loss. In order to ease the transition for a range that is currently "live" outside of Azure, you can utilize a regional commissioning feature, which places an onboarded range into a CommissionedNoInternetAdvertise state where it's only advertised from within a single Azure region. This state allows for testing of all the attached infrastructure from within this region before advertising this range to the Internet, and fits well with Method 1 in the previous section.
Use the following steps in the Azure portal to put a custom IP prefix into this state:
In the search box at the top of the Azure portal, enter Custom IP and select Custom IP Prefixes.
In Custom IP Prefixes, verify your custom IP prefix is listed in a Provisioned state. Refresh the status if needed until state is correct.
Select your custom IP prefix from the list of resources.
In Overview for your custom IP prefix, select the Commission dropdown menu, and choose <Resource_Region> only.
The operation is asynchronous. You can check the status by reviewing the Commissioned state field for the custom IP prefix. Initially, the status will show the prefix as Commissioning, followed in the future by Commissioned. The advertisement rollout isn't binary and the range is partially advertised while still in the Commissioning status.
Use the following example PowerShell to put a custom IP prefix range into this state.
Update-AzCustomIpPrefix
(other arguments)
-Commission
-NoInternetAdvertise
View a custom IP prefix
To view a custom IP prefix, the following commands can be used in Azure CLI and Azure PowerShell. All public IP prefixes created under the custom IP prefix are displayed.
Commands
| Tool | Command |
|---|---|
| CLI | az network custom-ip prefix list to list custom IP prefixes az network custom-ip prefix show to show settings and any derived public IP prefixes |
| PowerShell | Get-AzCustomIpPrefix to retrieve a custom IP prefix object and view its settings and any derived public IP prefixes |
Decommission a custom IP prefix
A custom IP prefix must be decommissioned to turn off advertisements.
Note
All public IP prefixes created from an provisioned custom IP prefix must be deleted before a custom IP prefix can be decommissioned. If this could potentially cause an issue as part of a migration, see the following section on regional commissioning.
The estimated time to fully complete the decommissioning process is 3-4 hours.
The following commands can be used in Azure CLI and Azure PowerShell to begin the process to stop advertising the range from Azure. The operation is asynchronous, use view commands to retrieve the status. The CommissionedState field initially shows the prefix as Decommissioning, followed by Provisioned as it transitions to the earlier state. Advertisement removal is a gradual process, and the range is partially advertised while still in Decommissioning.
Commands
| Tool | Command |
|---|---|
| Azure portal | Use the Decommission option in the Overview section of a Custom IP Prefix |
| CLI | az network custom-ip prefix update with --state flag set to decommission |
| PowerShell | Update-AzCustomIpPrefix with the flag to -Decommission |
Alternatively, a custom IP prefix can be decommissioned via the Azure portal using the Decommission button in the Overview section of the custom IP prefix.
Use the regional commissioning feature to assist decommission
A unified (or regional) model custom IP prefix must be clear of public IP prefixes before it can be put into Decommissioning state. To ease a migration, you can reverse the regional commissioning feature. You can change a globally commissioned range back to a regionally commissioned status. This change allows you to ensure the range is no longer advertised beyond the scope of a single region before removing any public IP addresses from their respective resources.
The command is similar as the one from earlier on this page:
Update-AzCustomIpPrefix
(other arguments)
-Decommission
-NoInternetAdvertise
The operation is asynchronous. You can check the status by reviewing the Commissioned state field for the custom IP prefix. Initially, the status will show the prefix as InternetDecommissioningInProgress, followed in the future by CommissionedNoInternetAdvertise. The advertisement to the Internet isn't binary and the range is partially advertised while still in the InternetDecommissioningInProgress status.
Deprovision/Delete a custom IP prefix
To fully remove a custom IP prefix, it must be deprovisioned and then deleted.
Important
It is strongly reccomended to decommission the range prior to modifying/deleting the Route Origin Authorization (ROA) you created with your Routing Internet Registry. Failure to do this will mean Microsoft will still be advertising your range when not authrorized to do so. Please see the creation documentation for more information about ROAs.
Note
If there is a requirement to migrate an provisioned range from one region to the other, the original custom IP prefix must be fully removed from the first region before a new custom IP prefix with the same address range can be created in another region.
The estimated time to complete the deprovisioning process is anywhere from 30 to 60 minutes.
The following commands can be used in Azure CLI and Azure PowerShell to deprovision and remove the range from Microsoft. The deprovisioning operation is asynchronous. You can use the view commands to retrieve the status. The CommissionedState field initially shows the prefix as Deprovisioning, followed by Deprovisioned as it transitions to the earlier state. When the range is in the Deprovisioned state, it can be deleted by using the commands to remove.
Commands
| Tool | Command |
|---|---|
| Azure portal | Use the Deprovision option in the Overview section of a Custom IP Prefix |
| CLI | az network custom-ip prefix update with the --state flag set to deprovision az network custom-ip prefix delete to remove |
| PowerShell | Update-AzCustomIpPrefixwith the flag to -Deprovision Remove-AzCustomIpPrefix to remove |
Alternatively, a custom IP prefix can be decommissioned via the Azure portal using the Deprovision button in the Overview section of the custom IP prefix, and then deleted using the Delete button in the same section.
Permissions
For permissions to manage public IP address prefixes, your account must be assigned to the network contributor role or to a custom role.
| Action | Name |
|---|---|
| Microsoft.Network/customIPPrefixes/read | Read a custom IP address prefix |
| Microsoft.Network/customIPPrefixes/write | Create or update a custom IP address prefix |
| Microsoft.Network/customIPPrefixes/delete | Delete a custom IP address prefix |
| Microsoft.Network/customIPPrefixes/join/action | Create a public IP prefix from a custom IP address prefix |
Troubleshooting and FAQs
This section provides answers for common questions about custom IP prefix resources and the provisioning and removal processes.
A "ValidationFailed" error is returned after a new custom IP prefix creation
A quick failure of provisioning is likely due to a prefix validation error. A prefix validation error indicates we're unable to verify your ownership of the range. A validation error can also indicate that we can't verify Microsoft permission to advertise the range, and or the association of the range with the given subscription. To view the specific error, review the FailedReason field in the custom IP prefix resource (in the JSON view in the portal) and review the Status messages section in the following section.
After updating a custom IP prefix to advertise, it transitions to a "CommissioningFailed" status
If a custom IP prefix is unable to be fully advertised, it moves to a CommissioningFailed status. To view the specific error, review the FailedReason field in the custom IP prefix resource (in the JSON view in the portal) and review the Status messages section as follows, which helps determine at what point the commission process failed.
I’m unable to decommission a custom IP prefix
Before decommissioning a custom IP prefix, ensure it has no public IP prefixes or public IP addresses.
I’m unable to delete a custom IP prefix
To delete a custom IP prefix, it must be in either Deprovisioned or in a ValidationFailed state. If your range is in ProvisionFailed state, it must be Deprovisioned before it can be deleted. If the range is "stuck" in the Provisioning or Deprovisioning state for an extended period of time, contact Microsoft support.
How can I migrate a range from one region to another
To migrate a custom IP prefix, it must first be deprovisioned from one region. A new custom IP prefix with the same CIDR can then be created in another region.
Are there any special considerations when using IPv6
Yes - there are multiple differences for provisioning and commissioning when using BYOIPv6. For more information, see Create a custom IPv6 address prefix - PowerShell.
Status messages
When you onboard or remove a custom IP prefix from Azure, the system updates the FailedReason attribute of the resource. If the Azure portal is used, the message is shown as a top-level banner. The following tables list the status messages when onboarding or removing a custom IP prefix.
Note
If the FailedReason is OperationNotFailed, the custom IP prefix is in a stable state (e.g. Provisioned, Commissioned) with no apparent issues.
Validation failures
| Failure message | Explanation |
|---|---|
| CustomerSignatureNotVerified | The signed message can't be verified against the authentication message using the Whois/RDAP record for the prefix. |
| NotAuthorizedToAdvertiseThisPrefix or ASN8075NotAllowedToAdvertise |
ASN8075 isn't authorized to advertise this prefix. Make sure your route origin authorization (ROA) is submitted correctly. |
| PrefixRegisteredInAfricaAndSouthAmericaNotAllowedInOtherRegion | IP prefix is registered with AFRINIC or LACNIC. These prefixes can't be used outside Africa/South America. |
| NotFindRoutingRegistryToGetCertificate | Can't find the public key for the IP prefix using the registration data access protocol (RDAP) of the regional internet registry (RIR). |
| CIDRInAuthorizationMessageNotMatchCustomerIP | The CIDR in the authorization message doesn't match the submitted IP address. |
| ExpiryDateFormatInvalidOrNotInThefuture | The expiration date provided in the authorization message is in the wrong format or expired. Expected format is yyyymmdd. |
| AuthMessageFormatInvalid | Authorization message format isn't valid. Expected format is xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx1.2.3.0/24yyyymmdd. |
| CannotParseValidCertificateFromRIRPage | Can't parse the public key for the IP prefix using the registration data access protocol (RDAP) of the regional internet registry (RIR). |
| ROANotFound | Unable to find route origin authorization (ROA) for validation. |
| CertFromRIRPageExpired | The public key provided by the registration data access protocol (RDAP) of the regional internet registry (RIR) is expired. |
| InvalidPrefixLengthInROA | The prefix length provided doesn't match the prefix in the route origin authorization (ROA). |
| RIRNotSupport | Only prefixes registered at ARIN, RIPE, APNIC, AFRINIC, and LACNIC are supported. |
| InvalidCIDRFormat | The CIDR format isn't valid. Expected format is 10.10.10.0/16. |
| InvalidCIDRFormatInAuthorizationMessage | The format of the CIDR in the authorization message isn't valid. Expected format is xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx1.2.3.0/24yyyymmdd. |
| OperationFailedPleaseRetryLaterOrContactSupport | Unknown error. Contact support. |
Note
Not all the messages shown during the commissioning or decommissioning process indicate failure--some simply provide more granular status.
Commission status
| Status message | Explanation |
|---|---|
| RegionalCommissioningInProgress | The range is being commissioned to advertise regionally within Azure. |
| CommissionedNoInternetAdvertise | The range is now advertising regionally within Azure. |
| InternetCommissioningInProgress | The range is now advertising regionally within Azure and is being commissioned to advertise to the internet. |
Decommission status
| Status message | Explanation |
|---|---|
| InternetDecommissioningInProgress | The range is currently being decommissioned. The range is no longer advertised to the internet. |
| RegionalDecommissioningInProgress | The range is no longer advertised to the internet and is currently being decommissioned. The range is no longer advertised regionally within Azure. |
Commission failures
| Failure message | Explanation |
|---|---|
| CommissionFailedRangeNotAdvertised | The range was unable to be advertised regionally within Azure or to the internet. |
| CommissionFailedRangeRegionallyAdvertised | The range was unable to be advertised to the internet but is being advertised within Azure. |
| CommissionFailedRangeInternetAdvertised | The range was unable to be advertised optimally but is being advertised to the internet and within Azure. |
Decommission failures
| Failure message | Explanation |
|---|---|
| DecommissionFailedRangeInternetAdvertised | The range was unable to be decommissioned and is still advertised to the internet and within Azure. |
| DecommissionFailedRangeRegionallyAdvertised | The range was unable to be decommissioned and is still advertised within Azure but is no longer advertised to the internet. |
Next steps
To learn about scenarios and benefits of using a custom IP prefix, see Custom IP address prefix (BYOIP).
To create a custom IP address prefix using the Azure portal, see Create custom IP address prefix using the Azure portal.
To create a custom IP address prefix using PowerShell, see Create a custom IP address prefix using Azure PowerShell.