From 3dae436eba37100b45a89f4094de8b0b76382f40 Mon Sep 17 00:00:00 2001 From: Dorota Wojcik Date: Tue, 11 Feb 2025 11:42:20 +0100 Subject: [PATCH] feedback --- docs/platform/concepts/vpcs.md | 3 +- .../howto/_manage-org-vpc-peering-azure.md | 35 ++++++++++--------- docs/platform/howto/list-vpc-peering.md | 12 +++---- .../howto/manage-org-vpc-peering-aws.md | 5 +-- .../howto/manage-org-vpc-peering-google.md | 7 ++-- .../howto/manage-org-vpc-peering-upcloud.md | 5 +-- .../platform/howto/manage-organization-vpc.md | 8 ++--- docs/platform/howto/manage-project-vpc.md | 8 ++--- docs/platform/howto/vnet-peering-azure.md | 14 ++++---- docs/platform/howto/vpc-peering-aws.md | 5 +-- docs/platform/howto/vpc-peering-gcp.md | 5 +-- docs/platform/howto/vpc-peering-upcloud.md | 5 +-- static/includes/vpc/renew-lease-upcloud.md | 2 +- 13 files changed, 61 insertions(+), 53 deletions(-) diff --git a/docs/platform/concepts/vpcs.md b/docs/platform/concepts/vpcs.md index 6395e4c1c..03e6c7b60 100644 --- a/docs/platform/concepts/vpcs.md +++ b/docs/platform/concepts/vpcs.md @@ -4,6 +4,7 @@ sidebar_label: VPCs overview --- import LimitedBadge from "@site/src/components/non-swizzled/Badges/LimitedBadge"; +import RelatedPages from "@site/src/components/non-swizzled/RelatedPages"; Virtual private clouds (VPCs) supported on the Aiven Platform provide enhanced security, flexibility, and network control, allowing efficient traffic, resource, and access management. @@ -70,7 +71,7 @@ network infrastructure while maintaining isolation and control. Learn how to [create and manage organization VPCs in Aiven](/docs/platform/howto/manage-organization-vpc). -## Learn more + For information on VPCs supported by particular cloud providers, see the following: diff --git a/docs/platform/howto/_manage-org-vpc-peering-azure.md b/docs/platform/howto/_manage-org-vpc-peering-azure.md index 5e8e50a4b..c94821885 100644 --- a/docs/platform/howto/_manage-org-vpc-peering-azure.md +++ b/docs/platform/howto/_manage-org-vpc-peering-azure.md @@ -16,9 +16,9 @@ requires creating the peering both from the VPC in Aiven and from the VNet in Az To establish the peering from Aiven to Azure, the Aiven Platform's [Active Directory application object](https://learn.microsoft.com/en-us/azure/active-directory/develop/app-objects-and-service-principals) 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. +tenants (the Aiven AD tenant and your Azure AD tenant), your Azure AD tenant needs another +application object. Once granted permissions, this object allows peering +from Azure to Aiven. ## Prerequisites @@ -67,7 +67,7 @@ permissions to do so. --key-type Password ``` - This creates an entity to your AD that can be used to log into multiple + 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. @@ -76,14 +76,14 @@ permissions to do so. Save the `appId` field from the output. It will be referred to as `$user_app_id`. ::: -1. Create a service principal for your app object to the Azure subscription that the VNet +1. Create a service principal for your app object in the Azure subscription where the VNet to be peered is located in: ```bash az ad sp create --id $user_app_id ``` - This creates a service principal to your subscription that may be given + This creates a service principal in your subscription, which can be assigned permissions to peer your VNet. :::note @@ -131,11 +131,11 @@ permissions to do so. 1. 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. + The service principal needs to be assigned a role that includes the + `Microsoft.Network/virtualNetworks/virtualNetworkPeerings/write` permission at the + scope of your VNet. To limit the permissions granted to the application object and the + service principal, you can create a custom role with only this permission. The built-in + Network Contributor role also includes this permission. 1. Find the id of the role with the required permission: @@ -143,7 +143,7 @@ permissions to do so. az role definition list --name "Network Contributor" ``` - The `id` field from the output will be referred to as `$network_contributor_role_id`. + The `id` field in the output is referred to as `$network_contributor_role_id`. 1. Assign the service principal the network contributor role using `$network_contributor_role_id`: @@ -155,10 +155,11 @@ permissions to do so. --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. + This allows your application object to manage the network within the specified + `--scope`. Since you control the application object, you can also grant it + permissions at the scope of an entire resource group or the whole subscription. This + enables creating other peerings later without assigning the role to each VNet + separately. ### Aiven app object permissions @@ -365,7 +366,7 @@ from your Azure VNet to the Aiven organization VPC: --tenant $aiven_tenant_id ``` - At this point, your application object should have an opened session with your Azure AD + At this point, your application object should have an open session with your Azure AD tenant and the Aiven AD tenant. 1. Create a peering from your Azure VNet to the Aiven organization VPC: diff --git a/docs/platform/howto/list-vpc-peering.md b/docs/platform/howto/list-vpc-peering.md index cbe928f68..a91b7f948 100644 --- a/docs/platform/howto/list-vpc-peering.md +++ b/docs/platform/howto/list-vpc-peering.md @@ -13,11 +13,11 @@ the public internet. ### VPC peering characteristics -- Private communication: Private IP addresses used by VPCs to communicate -- High performance: Low latency thanks traffic remaining on the cloud provider's network -- Security: Reduced exposure to public networks without using internet gateways, VPNs, or +- Private communication: Uses private IP addresses for direct communication between VPCs +- High performance: Low latency thanks to traffic remaining on the cloud provider's network +- Security: Reduces exposure to public networks without using internet gateways, VPNs, or NAT -- Scalability: Connections supported across different accounts and regions, depending on a +- Scalability: Supports connections across different accounts and regions, depending on a cloud provider ### VPC peering use cases @@ -26,8 +26,8 @@ the public internet. layers, such as web or database - Resource sharing: Secure sharing between VPCs hosting different resources, for example, datasets or APIs -- Data isolation: Access control by using separate VPCs for different projects or teams in - an organization +- Data isolation: Enforce access control by using separate VPCs for different projects or + teams in an organization ## How it works diff --git a/docs/platform/howto/manage-org-vpc-peering-aws.md b/docs/platform/howto/manage-org-vpc-peering-aws.md index 89c95a962..359468ad4 100644 --- a/docs/platform/howto/manage-org-vpc-peering-aws.md +++ b/docs/platform/howto/manage-org-vpc-peering-aws.md @@ -31,8 +31,9 @@ Set up a peering connection between your Aiven organization VPC and an AWS VPC. ### Collect data from AWS -To [create a peering in Aiven](/docs/platform/howto/manage-org-vpc-peering-aws#create-a-peering-in-aiven), -first collect required data from AWS: +To +[create a peering connection in Aiven](/docs/platform/howto/manage-org-vpc-peering-aws#create-a-peering-in-aiven), +first collect the required data from AWS: diff --git a/docs/platform/howto/manage-org-vpc-peering-google.md b/docs/platform/howto/manage-org-vpc-peering-google.md index 2dd23ad59..191608f59 100644 --- a/docs/platform/howto/manage-org-vpc-peering-google.md +++ b/docs/platform/howto/manage-org-vpc-peering-google.md @@ -34,8 +34,9 @@ creating the peering both from the VPC in Aiven and from the VPC in Google Cloud ### Collect data from Google Cloud -To [create a peering in Aiven](/docs/platform/howto/manage-org-vpc-peering-google#create-the-peering-in-aiven), -first collect required data from Google Cloud: +To +[create a peering connection in Aiven](/docs/platform/howto/manage-org-vpc-peering-google#create-the-peering-in-aiven), +first collect the required data from Google Cloud: @@ -130,7 +131,7 @@ to create the VPC peering connection in Google Cloud: To peer multiple Google Cloud VPC networks to your Aiven-managed organization VPC, [add peering connections](/docs/platform/howto/manage-org-vpc-peering-google#create-a-peering-connection) -one by one in the [Aiven Console](https://console.aiven.io). +one at a time in the [Aiven Console](https://console.aiven.io). For the limit on the number of VPC peering connections allowed to a single VPC network, see the [Google Cloud documentation](https://cloud.google.com/vpc/docs/quota). diff --git a/docs/platform/howto/manage-org-vpc-peering-upcloud.md b/docs/platform/howto/manage-org-vpc-peering-upcloud.md index 606a3ccbb..9c049f7f8 100644 --- a/docs/platform/howto/manage-org-vpc-peering-upcloud.md +++ b/docs/platform/howto/manage-org-vpc-peering-upcloud.md @@ -58,8 +58,9 @@ type networks. ### Collect data from UpCloud -To [create a peering in Aiven](/docs/platform/howto/manage-org-vpc-peering-upcloud#create-the-peering-in-aiven), -first collect required data from UpCloud using either the +To +[create a peering connection in Aiven](/docs/platform/howto/manage-org-vpc-peering-upcloud#create-the-peering-in-aiven), +first collect the required data from UpCloud using either the [UpCloud Control Panel](https://hub.upcloud.com/) or the [UpCloud API](https://developers.upcloud.com/1.3/): diff --git a/docs/platform/howto/manage-organization-vpc.md b/docs/platform/howto/manage-organization-vpc.md index 9537bbac3..d0a365860 100644 --- a/docs/platform/howto/manage-organization-vpc.md +++ b/docs/platform/howto/manage-organization-vpc.md @@ -108,8 +108,8 @@ for details. Your organization VPC is available as a geolocation (cloud region) for the new service. :::note -You can only create a service in an organization VPC if the organization VPC is located in -the organization where to create the service. +You can create a service in an organization VPC only if the organization VPC is in the +same organization where you are creating the service. ::: Create a service in an organization VPC using a tool of your choice: @@ -193,8 +193,8 @@ Replace the following placeholders with meaningful data: Your organization VPC is available as a geolocation (cloud region) for your service. :::note -You can only migrate a service to an organization VPC if the organization VPC is located in -the organization where your service runs. +You can only migrate a service to an organization VPC if the organization VPC is in the +same organization where your service runs. ::: Migrate a service to an organization VPC using a tool of your choice: diff --git a/docs/platform/howto/manage-project-vpc.md b/docs/platform/howto/manage-project-vpc.md index 9ea79b16a..637adb9d2 100644 --- a/docs/platform/howto/manage-project-vpc.md +++ b/docs/platform/howto/manage-project-vpc.md @@ -108,8 +108,8 @@ resource. Your project VPC is available as a geolocation (cloud region) for the new service. :::note -You can only create a service in a project VPC if the project VPC is located in -the project where to create the service. +You can create a service in a project VPC only if it is in the same project +where you are creating the service. ::: Create a service in a project VPC using a tool of your choice: @@ -191,8 +191,8 @@ Replace the following placeholders with meaningful data: Your project VPC is available as a geolocation (cloud region) for your service. :::note -You can only migrate a service to a project VPC if the project VPC is located in -the project where your service runs. +You can migrate a service to a project VPC only if the project VPC is in the +same project running your service. ::: Migrate a service to a project VPC using a tool of your choice: diff --git a/docs/platform/howto/vnet-peering-azure.md b/docs/platform/howto/vnet-peering-azure.md index 38e8ca89c..3492dfafb 100644 --- a/docs/platform/howto/vnet-peering-azure.md +++ b/docs/platform/howto/vnet-peering-azure.md @@ -61,7 +61,7 @@ permissions to do so. --key-type Password ``` - This creates an entity to your AD that can be used to log into multiple + 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. @@ -77,8 +77,8 @@ permissions to do so. az ad sp create --id $user_app_id ``` - This creates a service principal to your subscription that may be given - permissions to peer your VNet. + 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`. @@ -237,8 +237,8 @@ permissions to do so. ## Create the peering in Aiven -By creating a peering from the Aiven project VPC to the VNet in your Azure subscription, -you also create a service principal for the application object +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. @@ -246,8 +246,8 @@ The Aiven application object authenticates with your Azure tenant to grant it ac [the service principal of the Aiven application object](/docs/platform/howto/vnet-peering-azure#aiven-app-object-permissions) (`--peer-azure-tenant-id $user_tenant_id`). -`$aiven_project_vpc_id` can be found in the [Aiven Console](https://console.aiven.io/) or -using the `avn vpc list` command. +Find `$aiven_project_vpc_id` in the [Aiven Console](https://console.aiven.io/) or by +running the `avn vpc list` command. 1. Run: diff --git a/docs/platform/howto/vpc-peering-aws.md b/docs/platform/howto/vpc-peering-aws.md index bb75465cf..d227035eb 100644 --- a/docs/platform/howto/vpc-peering-aws.md +++ b/docs/platform/howto/vpc-peering-aws.md @@ -29,8 +29,9 @@ Set up a peering connection between your Aiven project VPC and an AWS VPC. ### Collect data from AWS -To [create a peering in Aiven](/docs/platform/howto/vpc-peering-aws#create-a-peering-in-aiven), -first collect required data from AWS: +To +[create a peering connection in Aiven](/docs/platform/howto/vpc-peering-aws#create-a-peering-in-aiven), +first collect the required data from AWS: diff --git a/docs/platform/howto/vpc-peering-gcp.md b/docs/platform/howto/vpc-peering-gcp.md index 192417d3f..58e982ce7 100644 --- a/docs/platform/howto/vpc-peering-gcp.md +++ b/docs/platform/howto/vpc-peering-gcp.md @@ -33,8 +33,9 @@ creating the peering both from the VPC in Aiven and from the VPC in Google Cloud ### Collect data from Google Cloud -To [create a peering in Aiven](/docs/platform/howto/vpc-peering-gcp#create-the-peering-in-aiven), -first collect required data from Google Cloud: +To +[create a peering connection in Aiven](/docs/platform/howto/vpc-peering-gcp#create-the-peering-in-aiven), +first collect the required data from Google Cloud: diff --git a/docs/platform/howto/vpc-peering-upcloud.md b/docs/platform/howto/vpc-peering-upcloud.md index 3bf4c4d09..253622ec3 100644 --- a/docs/platform/howto/vpc-peering-upcloud.md +++ b/docs/platform/howto/vpc-peering-upcloud.md @@ -58,8 +58,9 @@ type networks. ### Collect data from UpCloud -To [create a peering in Aiven](/docs/platform/howto/vpc-peering-upcloud#create-the-peering-in-aiven), -first collect required data from UpCloud using either the +To +[create a peering connection in Aiven](/docs/platform/howto/vpc-peering-upcloud#create-the-peering-in-aiven), +first collect the required data from UpCloud using either the [UpCloud Control Panel](https://hub.upcloud.com/) or the [UpCloud API](https://developers.upcloud.com/1.3/): diff --git a/static/includes/vpc/renew-lease-upcloud.md b/static/includes/vpc/renew-lease-upcloud.md index 5f7c31926..b99feaf9b 100644 --- a/static/includes/vpc/renew-lease-upcloud.md +++ b/static/includes/vpc/renew-lease-upcloud.md @@ -1,4 +1,4 @@ -You only need to take this step if any of your VMs has been created +You only need to perform this step if any of your VMs have been created before setting up the network peering. In this case, refresh the Dynamic Host Configuration Protocol (DHCP) lease for a relevant network interface to get new routes.