Manage a project VPC peering with Microsoft Azure

Set up a peering connection between your Aiven project VPC and a Microsoft Azure virtual network.

Establishing a peering connection between an Aiven project VPC and an Azure VNet requires creating the peering both from the VPC in Aiven and from the VNet in Azure.

To establish the peering from Aiven to Azure, the Aiven Platform's Active Directory application object needs permissions in your Azure subscription. Because the peering is between different AD tenants (the Aiven AD tenant and your Azure AD tenant), another application object is needed for your Azure AD tenant to create the peering from Azure to Aiven once granted permissions to do so.

Prerequisites

Manage project networking permissions in Aiven
Azure account with at least the application administrator role
Azure CLI and, optionally, the Microsoft Azure portal
Aiven CLI installed

Set up permissions in Azure

Azure app object permissions

Log in with an Azure admin account using the Azure CLI:
```
az account clear
az login
```
This should open a window in your browser prompting to choose an Azure account to log in with.
tip
If you manage multiple Azure subscriptions, also configure the Azure CLI to default to the correct subscription for the subsequent commands. This is not needed if there's only one subscription:
az account set --subscription SUBSCRIPTION_NAME_OR_ID
Create an application object in your AD tenant using the Azure CLI:
```
az ad app create                         \
  --display-name "NAME_OF_YOUR_CHOICE"   \
  --sign-in-audience AzureADMultipleOrgs \
  --key-type Password
```
This creates an application object in Azure AD that can be used to log into multiple AD tenants ( --sign-in-audience AzureADMultipleOrgs ), but only the home tenant (the tenant the app was created in) has the credentials to authenticate the app.

note
Save the appId field from the output. It will be referred to as $user_app_id.
Create a service principal for your app object to the Azure subscription that the VNet to be peered is located in:
```
az ad sp create --id $user_app_id
```
This creates a service principal in your subscription, which can be assigned permissions to peer your VNet.

note
Save the id field from the JSON output. It will be referred to as $user_sp_id.
Set a password for your app object:
```
az ad app credential reset --id $user_app_id
```
note
Save the password field from the output. It will be referred to as $user_app_secret.
Find properties of your virtual network:
- Resource ID
  - In the Azure portal: Virtual networks > name of your network > JSON View > id
  - Using the Azure CLI:
    az network vnet list
  tip
  The id field should have format /subscriptions/$user_subscription_id/ resourceGroups/$user_resource_group/providers/Microsoft.Network/virtualNetworks/$user_vnet_name. It will be referred to as $user_vnet_id.
- Azure Subscription ID (the VNet page in the Azure portal > Essentials > Subscription ID) or the part after /subscriptions/ in the resource ID. It will be referred to as $user_subscription_id.
- Resource group name (the VNet page in the Azure portal > Essentials > Resource group) or the resourceGroup field in the output. This will be referred to as $user_resource_group.
- VNet name (title of the VNet page), or the name field from the output. It will be referred to as $user_vnet_name.
note
Save all the properties for later.
Grant your service principal permissions to peer.

The service principal needs to be assigned a role that has the permission for the Microsoft.Network/virtualNetworks/virtualNetworkPeerings/write action on the scope of your VNet. To limit the amount of permissions the application object and the service principal have, you can create a custom role with just that permission. The built-in network contributor role includes that permission.
1. Find the id of the role with the required permission:
```
az role definition list --name "Network Contributor"
```
  The id field from the output will be referred to as $network_contributor_role_id.
2. Assign the service principal the network contributor role using $network_contributor_role_id:
```
az role assignment create             \
  --role $network_contributor_role_id \
  --assignee-object-id $user_sp_id    \
  --scope $user_vnet_id
```
  This allows your application object to manage the network in the --scope. Since you control the application object, it may also be given permission for the scope of an entire resource group or the whole subscription to allow creating other peerings later without assigning the role for each VNet separately.

Aiven app object permissions

Create a service principal for the Aiven application object.

The Aiven AD tenant contains an application object that the Aiven Platform uses to create a peering from the Aiven project VPC to the Azure VNet. For this, the Aiven application object needs a service principal in your Azure subscription. To create it, run:
```
az ad sp create --id 55f300d4-fc50-4c5e-9222-e90a6e2187fb
```
The argument to --id field is a fixed value that represents the ID of the Aiven application object.

note
Save the id field from the JSON output. It will be referred to as $aiven_sp_id.
important
The command might fail for the following reasons:
- When using this permission, the backing application of the service principal being created must in the local tenant, which means your account doesn't have the required permissions. See Prerequisites.
- The service principal cannot be created, updated, or restored because the service principal name 55f300d4-fc50-4c5e-9222-e90a6e2187fb is already in use, in which case run az ad sp show --id 55f300d4-fc50-4c5e-9222-e90a6e2187fb and find id in the output.
Create a custom role for the Aiven application object.

The Aiven application has a service principal that can be granted permissions. To restrict the service principal's permissions to peering, create a custom role with the peering action only allowed:
```
az role definition create --role-definition '
  {
    "Name": "NAME_OF_YOUR_CHOICE",
    "Description": "Allows creating a peering to vnets in scope (but not from)",
    "Actions": ["Microsoft.Network/virtualNetworks/peer/action"],
    "AssignableScopes": ["/subscriptions/'$user_subscription_id'"]
  }'
```
AssignableScopes includes your Azure subscription ID to restrict scopes that a role assignment can use.

note
Save the id field from the output. It will be referred to as $aiven_role_id.
Assign the custom role to the Aiven service principal.

To give the Aiven application object's service principal permissions to peer with your VNet, assign the created role to the Aiven service principal with the scope of your VNet:
```
az role assignment create           \
  --role $aiven_role_id             \
  --assignee-object-id $aiven_sp_id \
  --scope $user_vnet_id
```
Find your AD tenant ID:
- In the Azure portal: Settings > Directories + subscriptions > Directories > Directory ID
- Using the Azure CLI:
```
az account list
```
note
Save the tenantId field from the output. It will be referred to as $user_tenant_id.

Create the peering in Aiven

By creating a peering connection from the Aiven project VPC to the VNet in your Azure subscription, you also create a service principal for the application object (--peer-azure-app-id $user_app_id) and grant it the permission to peer with the Aiven project VPC.

The Aiven application object authenticates with your Azure tenant to grant it access to the service principal of the Aiven application object (--peer-azure-tenant-id $user_tenant_id).

Find $aiven_project_vpc_id in the Aiven Console or by running the avn vpc list command.

Run:

avn vpc peering-connection create            \
  --project-vpc-id $aiven_project_vpc_id     \
  --peer-cloud-account $user_subscription_id \
  --peer-resource-group $user_resource_group \
  --peer-vpc $user_vnet_name                 \
  --peer-azure-app-id $user_app_id           \
  --peer-azure-tenant-id $user_tenant_id

note

Use lower case for arguments starting with $user_.

Run the following command until the state changes from APPROVED to PENDING_PEER:
```
avn vpc peering-connection get -v            \
  --project-vpc-id $aiven_project_vpc_id     \
  --peer-cloud-account $user_subscription_id \
  --peer-resource-group $user_resource_group \
  --peer-vpc $user_vnet_name
```
tip
If the state is INVALID_SPECIFICATION or REJECTED_BY_PEER, check if the Azure VNet exists and if the Aiven application object has the permission to be peered with. Revise your configuration and recreate the peering connection.

Establishing the connection from Aiven to Azure can take a while. When completed, the state changes to PENDING_PEER and the output shows details for establishing the peering from your Azure VNet to the Aiven project VPC.
note
Save the following from the output:
- to-tenant-id: It will be referred to as $aiven_tenant_id.
- to-network-id: It will be referred to as $aiven_vnet_id.

Create the peering in Azure

Establish the peering connection from your Azure VNet to the Aiven project VPC:

Log out the Azure user you logged in with:
```
az account clear
```

az login              \
  --service-principal \
  -u $user_app_id     \
  -p $user_app_secret \
  --tenant $user_tenant_id

Log in the Azure application object to the Aiven AD tenant:
```
az login              \
  --service-principal \
  -u $user_app_id     \
  -p $user_app_secret \
  --tenant $aiven_tenant_id
```
At this point, your application object should have an opened session with your Azure AD tenant and the Aiven AD tenant.
Create a peering from your Azure VNet to the Aiven project VPC:
```
az network vnet peering create          \
  --name PEERING_NAME_OF_YOUR_CHOICE    \
  --remote-vnet $aiven_vnet_id          \
  --vnet-name $user_vnet_name           \
  --resource-group $user_resource_group \
  --subscription $user_subscription_id  \
  --allow-vnet-access
```
If the peering state in the output is connected, the peering is created.
tip
The command might fail with the following error:
The client 'RANDOM_UUID' with object id 'RANDOM_UUID' does not have authorization to perform action 'Microsoft.Network/virtualNetworks/virtualNetworkPeerings/write' over scope '$user_vnet_id'. If access was recently granted, refresh your credentials.
for two reasons related to the role assignment:
- Role assignment hasn't taken effect yet, in which case try logging in again and recreating the peering.
- Role assignment is incorrect, in which case try recreating the role assignment.
Wait until the Aiven peering connection is active. The Aiven Platform polls peering connections in state PENDING_PEER regularly to see if the peer (your Azure VNet) has created a peering connection to the Aiven project VPC. Once this is detected, the state changes from PENDING_PEER to ACTIVE, at which point Aiven services in the project VPC can be reached through the peering.

Check if the status of the peering connection is ACTIVE:

avn vpc peering-connection get -v            \
  --project-vpc-id $aiven_project_vpc_id     \
  --peer-cloud-account $user_subscription_id \
  --peer-resource-group $user_resource_group \
  --peer-vpc $user_vnet_name

Delete the peering

important

Once you delete your VPC peering on the Aiven Platform, the cloud-provider side of the peering connection becomes inactive or deleted, and the traffic between the disconnected VPCs is terminated.

Delete a project VPC peering using a tool of your choice:

Aiven Console
Aiven CLI
Aiven API
Aiven Provider for Terraform

Log in to the Aiven Console, and go to your project page.
Click VPCs in the sidebar.
On the Virtual private clouds page, select a project VPC.
On the VPC details page, go to the VPC peering connections section, find the peering to be deleted, and click Actions > Delete.
In the Confirmation window, click Delete VPC peering.

Run the avn vpc peering-connection delete command:

avn vpc peering-connection delete         \
  --project-vpc-id PROJECT_VPC_ID         \
  --peer-cloud-account PEER_CLOUD_ACCOUNT \
  --peer-vpc PEER_VPC_ID

Replace the following with meaningful values:

PROJECT_VPC_ID, for example 12345678-1a2b-3c4d-5f6g-1a2b3c4d5e6f
PEER_CLOUD_ACCOUNT, for example 012345678901
PEER_VPC_ID, for example vpc-abcdef01234567890

Make an API call to the VpcPeeringConnectionDelete endpoint:

curl --request DELETE \
  --url https://api.aiven.io/v1/project/PROJECT_ID/vpcs/PROJECT_VPC_ID \
  --header 'Authorization: Bearer BEARER_TOKEN' \

curl --request DELETE \
  --url https://api.aiven.io/v1/project/PROJECT_ID/vpcs/PROJECT_VPC_ID/peering-connections/peer-accounts/PEER_CLOUD_ACCOUNT/peer-vpcs/PEER_VPC \
  --header 'Authorization: Bearer BEARER_TOKEN'

Replace the following placeholders with meaningful data:

PROJECT_ID: Aiven project name
PROJECT_VPC_ID: Aiven project VPC ID
PEER_CLOUD_ACCOUNT: your cloud provider account ID or name
PEER_VPC: your cloud provider VPC ID or name
BEARER_TOKEN

To delete your Aiven project VPC peering connection resource, run terraform destroy. See the Aiven Provider for Terraform documentation for details.

Prerequisites​

Set up permissions in Azure​

Azure app object permissions​

Aiven app object permissions​

Create the peering in Aiven​

Create the peering in Azure​

Delete the peering​