Availability Group Listeners - Create Or Update

Service:

SQL VM

API Version:

2023-10-01

Creates or updates an availability group listener.

PUT https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.SqlVirtualMachine/sqlVirtualMachineGroups/{sqlVirtualMachineGroupName}/availabilityGroupListeners/{availabilityGroupListenerName}?api-version=2023-10-01

URI Parameters

Name	In	Required	Type	Description
availabilityGroupListenerName	path	True	string	Name of the availability group listener.
resourceGroupName	path	True	string	Name of the resource group that contains the resource. You can obtain this value from the Azure Resource Manager API or the portal.
sqlVirtualMachineGroupName	path	True	string	Name of the SQL virtual machine group.
subscriptionId	path	True	string	Subscription ID that identifies an Azure subscription.
api-version	query	True	string	API version to use for the request.

Request Body

Name	Type	Description
properties.availabilityGroupConfiguration	AgConfiguration	Availability Group configuration.
properties.availabilityGroupName	string	Name of the availability group.
properties.createDefaultAvailabilityGroupIfNotExist	boolean	Create a default availability group if it does not exist.
properties.loadBalancerConfigurations	LoadBalancerConfiguration[]	List of load balancer configurations for an availability group listener.
properties.multiSubnetIpConfigurations	MultiSubnetIpConfiguration[]	List of multi subnet IP configurations for an AG listener.
properties.port	integer	Listener port.

Responses

Name	Type	Description
200 OK	AvailabilityGroupListener	Successfully updated the availability group listener.
201 Created	AvailabilityGroupListener	Successfully created the availability group listener.
Other Status Codes	ErrorResponse	*** Error Responses: *** 400 InvalidParameterValue - An invalid value was given to parameter. 400 RPGenericUser - User Failure when calling other Resource Provider. 400 RPResponseMissingAsyncOperationHeader - Response is missing Async operation header information 400 InvalidArgument - Invalid argument '{0}'. 400 ArgumentNotInRange - Argument '{0}' not in range. 400 ResourceNotProvisioned - As the resource: {0} is not in a provisioned state, the request cannot be proceeded forward 400 CRPNotAllowedOperation - Operation cannot be completed due to the following error: {0} 400 AadAppDisabled - Microsoft AAD app SQLVMResourceProviderAuth ({0}) is disabled in your tenant. 400 InternalAPIAccessDenied - Internal API Access denied. App Id {0} is not valid to use this API. 400 InvalidSQLAuthPasswordLength - SQL auth password should not be greater than 128 characters 400 InvalidRgResourceId - Invalid Resourcegroup resource id specified. 400 AgDoesNotExist - Availability group does not exist. 400 AgListDoesNotMatch - SQL Availability group list does not match the list of virtual machines in SQL Virtual machine group. 400 NoIpProvided - At least one IP needs to be provided. 400 MoreIpProvided - Only one IP needs to be provided. 400 SqlVmGroupDoesNotHaveAGListener - SQL virtual machine group does not have the AG listener. 400 AgListenerUpdateNotAllowed - Only handful properties of availability group listener can be updated. 400 SqlVmNotInGroup - SQL virtual machine is not part of the group. 400 SqlVmListCannotBeEmpty - SQL virtual machines list cannot be empty. 400 PublicIpNotIPv4 - Public IP must be IPv4 address. 400 PublicIPDynamicAllocation - Public IP allocation mode must be static 400 PublicLBInvalid - Load balancer specified is not public. 400 SubnetMissingFromPrivateIP - Subnet must be provided with private IP. 400 IPNotInSubnet - IP not part of subnet. 400 NoActivePrimaryInAG - None of the nodes in AvailabilityGroup are Primary 400 MultipleListenerSameAG - Multiple availability group listeners for same availability group are not allowed. 400 AgListenerNotEmpty - Availability group listener not empty. 400 AgListenerVnetMismatch - Provided VNet for Availability group listener does not match Vnet of internal load balancer. 400 InternalLBInvalid - Load balancer specified is not internal. 400 InvalidSqlVmResourceIdParameterValue - SQL virtual machine resource id provided is invalid. 400 DifferentSubSqlVmList - All SQL virtual machines should be under same subscription. 400 OnlyStandardPublicIp - Every virtual machine should have standard public IP. 400 ListenerNameTooLong - Listener name should not exceed 15 characters. 400 InvalidListenerName - Invalid listener name. 400 InvalidLBResourceIdParameterValue - Load balancer resource id is invalid. 400 InvalidPublicIpResourceIdParameterValue - Public IP resource id is invalid. 400 InvalidSubnetIdParameterValue - Invalid resource id provided for subnet parameter. 400 InvalidPrivateIpParameterValue - Invalid address given for private IP address. 400 ExtVersionNotSupported - The virtual machine: {0} is running older version of SqlIaasExtension which is not supported by this operation. Please update the extension and retry the operation. 400 InvalidReplicaRole - Invalid replica role: {0} specified for SQL VM: {1}. 400 InvalidReplicaFailover - Invalid replica Failover: {0} for SQL VM: {1}. 400 InvalidReplicaReadableSecondary - Invalid replica readable secondary: {0} for SQL VM: {1}. 400 InvalidReplicaCommit - Invalid replica commit mode: {0} for SQL VM: {1}. 400 ExpectedSynchronousCommitForAutomaticFailover - Invalid replica commit mode: {0} for SQL VM: {1}. {2} is expected for failover mode: {3}. 400 NoPrimaryInAg - There are no replicas with primary role. There should be exactly one replica with role as primary. 400 MoreThanOnePrimaryInAg - There are more than one replica with primary role. There should be exactly one replica with role as primary. 400 MoreThanThreeSynchronousCommitInAg - There are more than three replica with commit mode as: {0}. There should be at most three replica with commit mode as: {0} 400 MoreThanEightSecondariesInAg - There are more than eight secondary replica with secondary role. There should be at most eight replica with role as secondary. 400 AlwaysOnNotEnabled - Always on feature is not enabled on Virtual machine: {0}. 400 ExpectedReplicaNotPrimary - The VM: {0} does not host the primary replica. 400 ListenerSqlvmsMismatchWithReplicaSqlvms - List of SQL VMs specified in Availability group does not match list of SQL VMs in listener config. 400 ReplicaSqlvmHasDuplicateEntries - Replica configuration should be unique for each SQL virtual machine. We have found one or more configuration for the same SQL virtual machine resource. 400 ReplicaDeleteNotAllowed - Replica deletion through SQL VM RP is not supported yet. 400 OnlyBasicPublicIP - All VM specified should contain only Basic Public IP, when providing Loadbalancer Basic Sku. 400 NICCannotUseMultipleLBsOfSameType - NIC: {0} cannot reference more than one load balancer of INTERNAL or PUBLIC type 400 AGReplicaSQLStartupAccount - NT service account cannot be used as SQL startup account for AG setup. You should use a domain account. 400 AgListenerMultiSubnetUpdateNotAllowed - Update of multi subnet AG listener is not allowed. 400 ListenerIpSubnetVmSubnetMismatch - Listener static ip address subnet and VM subnet should be same 400 IpAddressEmpty - Cannot get the subnet mask when IP address is null or empty. 400 InvalidIpAddress - Invalid address given for IP address. 400 VmNicVnetMismatch - Virtual machine NIC VNet mismatch. 400 NoAvailabilitySet - Vm is not associated with any availability set. 400 AvailabilitySetMismatch - Availability set of virtual machines does not match. 400 MismatchVmGroupSubscription - Subscription id for SQL virtual machine and SQL virtual machine group are different. 400 VmNotRunning - The VM is not in running state. 400 VmAgentNotRunning - The VM agent is not installed or in running state. 400 NoIpAvailable - No available IP. 403 AccessDenied - Access denied. 404 ResourceNotFound - The requested resource was not found. 404 SubscriptionDoesNotExist - Subscription id does not exist. 404 ResourceDoesNotExist - Resource does not exist. 404 RPOperationNotFound - Operation not found 404 OperationIdNotFound - Operation id could not be found. 404 OperationTypeNotFound - Operation Type not found. 404 SubscriptionDoesNotHaveSqlVMGroupInResourceGroup - Subscription does not have SQL virtual machine group in resource group. 409 OperationInProgress - Operation in progress on resource already. 409 OperationCanceled - Operation Cancelled. 409 ResourceAlreadyExists - Resource already exists. 409 LBGenericErrors - LB operation failed 409 NICGenericError - NIC operation failed 409 SqlExtensionNotInstalled - SQL extension not installed. 409 RPPluginSubstatusMissing - RP plugin substatus missing 409 MissingMoveResources - Cannot move resources(s) because some resources are missing in the request. 409 ResourceExists - There was an internal error in cleaning up of resources. 409 SubscriptionOperationInProgress - An operation on subscription is already in progress 409 ReplicasWithDifferentSqlStartupAccounts - Please make sure all your SQL server startup accounts in the specified replicas are the same. This is one of our prerequisites for setting up availability groups. 409 ReplicasJoinedToMoreThanOneCluster - AG replicas are joined to more than one failover cluster. Please make sure all your replicas are joined to same failover cluster. 409 IPNotAvailable - IP {0} is not available{1}. Consider using one from ({2}) 409 IpAddressAlreadyReserved - IP address reserved for this listener already exists. Please use the IP address 429 SqlVmGroupGmsaNotAllowed - GMSA account is not supported yet. 429 SqlVmGroupGmsaInfoInvalid - GMSA info such as SqlServiceAccount is not valid. 429 TooManyRequestsReceived - Request throttled due to too many requests. 429 ArgumentMissingForSetup - Argument is missing for setup. Please provide a value for the argument. 429 MultisubnetOperationNotAllowed - Multi subnet HA setup operation is not allowed. 500 UnExpectedErrorOccurred - Unexpected error occurred. 500 OperationTimeout - Operation timed out. 500 RPGenericSystem - System Failure when calling other Resource Provider. 500 StorageAccountUnexpectedError - Unexpected error for storage account. 500 SqlVmEntityNotFound - SQL VM entity not found. 500 RestoreJobEntityNotFound - Restore job entity not found. 500 RpPluginSubstatusHAStatusMissing - Resource provider plugin substatus is missing HA status. 500 SqlVmGroupIsBusy - SQL virtual machine group is busy.

Examples

Creates or updates an availability group listener using load balancer. This is used for VMs present in single subnet.

Creates or updates an availability group listener. This is used for VMs present in multi subnet

Creates or updates an availability group listener using load balancer. This is used for VMs present in single subnet.

Sample Request

HTTP

PUT https://management.azure.com/subscriptions/00000000-1111-2222-3333-444444444444/resourceGroups/testrg/providers/Microsoft.SqlVirtualMachine/sqlVirtualMachineGroups/testvmgroup/availabilityGroupListeners/agl-test?api-version=2023-10-01

{
  "properties": {
    "availabilityGroupName": "ag-test",
    "loadBalancerConfigurations": [
      {
        "privateIpAddress": {
          "ipAddress": "10.1.0.112",
          "subnetResourceId": "/subscriptions/00000000-1111-2222-3333-444444444444/resourceGroups/testrg/providers/Microsoft.Network/virtualNetworks/test-vnet/subnets/default"
        },
        "loadBalancerResourceId": "/subscriptions/00000000-1111-2222-3333-444444444444/resourceGroups/testrg/providers/Microsoft.Network/loadBalancers/lb-test",
        "probePort": 59983,
        "sqlVirtualMachineInstances": [
          "/subscriptions/00000000-1111-2222-3333-444444444444/resourceGroups/testrg/providers/Microsoft.SqlVirtualMachine/sqlVirtualMachines/testvm2",
          "/subscriptions/00000000-1111-2222-3333-444444444444/resourceGroups/testrg/providers/Microsoft.SqlVirtualMachine/sqlVirtualMachines/testvm3"
        ]
      }
    ],
    "port": 1433
  }
}

Sample Response

Status code:

200

{
  "properties": {
    "provisioningState": "Updating",
    "loadBalancerConfigurations": [
      {
        "privateIpAddress": {
          "ipAddress": "10.1.0.113",
          "subnetResourceId": "/subscriptions/00000000-1111-2222-3333-444444444444/resourceGroups/testrg/providers/Microsoft.Network/virtualNetworks/test-vnet/subnets/default"
        },
        "sqlVirtualMachineInstances": [
          "/subscriptions/00000000-1111-2222-3333-444444444444/resourceGroups/testrg/providers/Microsoft.SqlVirtualMachine/sqlVirtualMachines/testvm2",
          "/subscriptions/00000000-1111-2222-3333-444444444444/resourceGroups/testrg/providers/Microsoft.SqlVirtualMachine/sqlVirtualMachines/testvm3"
        ]
      }
    ],
    "port": 1433
  },
  "id": "/subscriptions/00000000-1111-2222-3333-444444444444/resourceGroups/testrg/providers/Microsoft.SqlVirtualMachine/sqlVirtualMachineGroups/testvmgroup/availabilityGroupListeners/agl-test",
  "name": "agl-test",
  "type": "Microsoft.SqlVirtualMachine/sqlVirtualMachineGroups/availabilityGroupListeners"
}

Status code:

201

{
  "properties": {
    "provisioningState": "Provisioning",
    "loadBalancerConfigurations": [
      {
        "privateIpAddress": {
          "ipAddress": "10.1.0.112",
          "subnetResourceId": "/subscriptions/00000000-1111-2222-3333-444444444444/resourceGroups/testrg/providers/Microsoft.Network/virtualNetworks/test-vnet/subnets/default"
        },
        "sqlVirtualMachineInstances": [
          "/subscriptions/00000000-1111-2222-3333-444444444444/resourceGroups/testrg/providers/Microsoft.SqlVirtualMachine/sqlVirtualMachines/testvm2",
          "/subscriptions/00000000-1111-2222-3333-444444444444/resourceGroups/testrg/providers/Microsoft.SqlVirtualMachine/sqlVirtualMachines/testvm3"
        ]
      }
    ],
    "port": 1433
  },
  "id": "/subscriptions/00000000-1111-2222-3333-444444444444/resourceGroups/testrg/providers/Microsoft.SqlVirtualMachine/sqlVirtualMachineGroups/testvmgroup/availabilityGroupListeners/agl-test",
  "name": "agl-test",
  "type": "Microsoft.SqlVirtualMachine/sqlVirtualMachineGroups/availabilityGroupListeners"
}

Creates or updates an availability group listener. This is used for VMs present in multi subnet

Sample Request

HTTP

PUT https://management.azure.com/subscriptions/00000000-1111-2222-3333-444444444444/resourceGroups/testrg/providers/Microsoft.SqlVirtualMachine/sqlVirtualMachineGroups/testvmgroup/availabilityGroupListeners/agl-test?api-version=2023-10-01

{
  "properties": {
    "availabilityGroupName": "ag-test",
    "multiSubnetIpConfigurations": [
      {
        "privateIpAddress": {
          "ipAddress": "10.0.0.112",
          "subnetResourceId": "/subscriptions/00000000-1111-2222-3333-444444444444/resourceGroups/testrg/providers/Microsoft.Network/virtualNetworks/test-vnet/subnets/default"
        },
        "sqlVirtualMachineInstance": "/subscriptions/00000000-1111-2222-3333-444444444444/resourceGroups/testrg/providers/Microsoft.SqlVirtualMachine/sqlVirtualMachines/testvm2"
      },
      {
        "privateIpAddress": {
          "ipAddress": "10.0.1.112",
          "subnetResourceId": "/subscriptions/00000000-1111-2222-3333-444444444444/resourceGroups/testrg/providers/Microsoft.Network/virtualNetworks/test-vnet/subnets/alternate"
        },
        "sqlVirtualMachineInstance": "/subscriptions/00000000-1111-2222-3333-444444444444/resourceGroups/testrg/providers/Microsoft.SqlVirtualMachine/sqlVirtualMachines/testvm1"
      }
    ],
    "port": 1433
  }
}

Sample Response

Status code:

200

{
  "properties": {
    "provisioningState": "Updating",
    "multiSubnetIpConfigurations": [
      {
        "privateIpAddress": {
          "ipAddress": "10.0.0.112",
          "subnetResourceId": "/subscriptions/00000000-1111-2222-3333-444444444444/resourceGroups/testrg/providers/Microsoft.Network/virtualNetworks/test-vnet/subnets/default"
        },
        "sqlVirtualMachineInstance": "/subscriptions/00000000-1111-2222-3333-444444444444/resourceGroups/testrg/providers/Microsoft.SqlVirtualMachine/sqlVirtualMachines/testvm2"
      },
      {
        "privateIpAddress": {
          "ipAddress": "10.0.1.112",
          "subnetResourceId": "/subscriptions/00000000-1111-2222-3333-444444444444/resourceGroups/testrg/providers/Microsoft.Network/virtualNetworks/test-vnet/subnets/alternate"
        },
        "sqlVirtualMachineInstance": "/subscriptions/00000000-1111-2222-3333-444444444444/resourceGroups/testrg/providers/Microsoft.SqlVirtualMachine/sqlVirtualMachines/testvm1"
      }
    ],
    "port": 1433
  },
  "id": "/subscriptions/00000000-1111-2222-3333-444444444444/resourceGroups/testrg/providers/Microsoft.SqlVirtualMachine/sqlVirtualMachineGroups/testvmgroup/availabilityGroupListeners/agl-test",
  "name": "agl-test",
  "type": "Microsoft.SqlVirtualMachine/sqlVirtualMachineGroups/availabilityGroupListeners"
}

Status code:

201

{
  "properties": {
    "provisioningState": "Provisioning",
    "multiSubnetIpConfigurations": [
      {
        "privateIpAddress": {
          "ipAddress": "10.0.0.112",
          "subnetResourceId": "/subscriptions/00000000-1111-2222-3333-444444444444/resourceGroups/testrg/providers/Microsoft.Network/virtualNetworks/test-vnet/subnets/default"
        },
        "sqlVirtualMachineInstance": "/subscriptions/00000000-1111-2222-3333-444444444444/resourceGroups/testrg/providers/Microsoft.SqlVirtualMachine/sqlVirtualMachines/testvm2"
      },
      {
        "privateIpAddress": {
          "ipAddress": "10.0.1.112",
          "subnetResourceId": "/subscriptions/00000000-1111-2222-3333-444444444444/resourceGroups/testrg/providers/Microsoft.Network/virtualNetworks/test-vnet/subnets/alternate"
        },
        "sqlVirtualMachineInstance": "/subscriptions/00000000-1111-2222-3333-444444444444/resourceGroups/testrg/providers/Microsoft.SqlVirtualMachine/sqlVirtualMachines/testvm1"
      }
    ],
    "port": 1433
  },
  "id": "/subscriptions/00000000-1111-2222-3333-444444444444/resourceGroups/testrg/providers/Microsoft.SqlVirtualMachine/sqlVirtualMachineGroups/testvmgroup/availabilityGroupListeners/agl-test",
  "name": "agl-test",
  "type": "Microsoft.SqlVirtualMachine/sqlVirtualMachineGroups/availabilityGroupListeners"
}

Definitions

Name	Description
AgConfiguration	Availability group configuration.
AgReplica	Availability group replica configuration.
AvailabilityGroupListener	A SQL Server availability group listener.
Commit	Replica commit mode in availability group.
createdByType	The type of identity that created the resource.
ErrorAdditionalInfo	The resource management error additional info.
ErrorDetail	The error detail.
ErrorResponse	Error response
Failover	Replica failover mode in availability group.
LoadBalancerConfiguration	A load balancer configuration for an availability group listener.
MultiSubnetIpConfiguration	Multi subnet ip configuration for an availability group listener.
PrivateIPAddress	A private IP address bound to the availability group listener.
ReadableSecondary	Replica readable secondary mode in availability group.
Role	Replica Role in availability group.
systemData	Metadata pertaining to creation and last modification of the resource.

AgConfiguration

Availability group configuration.

Name	Type	Description
replicas	AgReplica[]	Replica configurations.

AgReplica

Availability group replica configuration.

Name	Type	Description
commit	Commit	Replica commit mode in availability group.
failover	Failover	Replica failover mode in availability group.
readableSecondary	ReadableSecondary	Replica readable secondary mode in availability group.
role	Role	Replica Role in availability group.
sqlVirtualMachineInstanceId	string	Sql VirtualMachine Instance Id.

AvailabilityGroupListener

A SQL Server availability group listener.

Name	Type	Description
id	string	Resource ID.
name	string	Resource name.
properties.availabilityGroupConfiguration	AgConfiguration	Availability Group configuration.
properties.availabilityGroupName	string	Name of the availability group.
properties.createDefaultAvailabilityGroupIfNotExist	boolean	Create a default availability group if it does not exist.
properties.loadBalancerConfigurations	LoadBalancerConfiguration[]	List of load balancer configurations for an availability group listener.
properties.multiSubnetIpConfigurations	MultiSubnetIpConfiguration[]	List of multi subnet IP configurations for an AG listener.
properties.port	integer	Listener port.
properties.provisioningState	string	Provisioning state to track the async operation status.
systemData	systemData	Metadata pertaining to creation and last modification of the resource.
type	string	Resource type.

Commit

Replica commit mode in availability group.

Name	Type	Description
Asynchronous_Commit	string
Synchronous_Commit	string

createdByType

The type of identity that created the resource.

Name	Type	Description
Application	string
Key	string
ManagedIdentity	string
User	string

ErrorAdditionalInfo

The resource management error additional info.

Name	Type	Description
info	object	The additional info.
type	string	The additional info type.

ErrorDetail

The error detail.

Name	Type	Description
additionalInfo	ErrorAdditionalInfo[]	The error additional info.
code	string	The error code.
details	ErrorDetail[]	The error details.
message	string	The error message.
target	string	The error target.

ErrorResponse

Error response

Name	Type	Description
error	ErrorDetail	The error object.

Failover

Replica failover mode in availability group.

Name	Type	Description
Automatic	string
Manual	string

LoadBalancerConfiguration

A load balancer configuration for an availability group listener.

Name	Type	Description
loadBalancerResourceId	string	Resource id of the load balancer.
privateIpAddress	PrivateIPAddress	Private IP address.
probePort	integer	Probe port.
publicIpAddressResourceId	string	Resource id of the public IP.
sqlVirtualMachineInstances	string[]	List of the SQL virtual machine instance resource id's that are enrolled into the availability group listener.

MultiSubnetIpConfiguration

Multi subnet ip configuration for an availability group listener.

Name	Type	Description
privateIpAddress	PrivateIPAddress	Private IP address.
sqlVirtualMachineInstance	string	SQL virtual machine instance resource id that are enrolled into the availability group listener.

PrivateIPAddress

A private IP address bound to the availability group listener.

Name	Type	Description
ipAddress	string	Private IP address bound to the availability group listener.
subnetResourceId	string	Subnet used to include private IP.

ReadableSecondary

Replica readable secondary mode in availability group.

Name	Type	Description
All	string
No	string
Read_Only	string

Role

Replica Role in availability group.

Name	Type	Description
Primary	string
Secondary	string

systemData

Metadata pertaining to creation and last modification of the resource.

Name	Type	Description
createdAt	string	The timestamp of resource creation (UTC).
createdBy	string	The identity that created the resource.
createdByType	createdByType	The type of identity that created the resource.
lastModifiedAt	string	The timestamp of resource last modification (UTC)
lastModifiedBy	string	The identity that last modified the resource.
lastModifiedByType	createdByType	The type of identity that last modified the resource.