feedback

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
+<RelatedPages/>
 
 For information on VPCs supported by particular cloud providers, see the following:
 

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,19 +131,19 @@ 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:
 
       ```bash
       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:

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
 

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:
 
 <CollectDataAws/>
 

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:
 
 <CollectDataGoogle/>
 
@@ -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).

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/):
 

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:

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:

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,17 +237,17 @@ 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.
 
 The Aiven application object authenticates with your Azure tenant to grant it access to
 [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:
 

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:
 
 <CollectDataAws/>
 

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:
 
 <CollectDataGoogle/>
 

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/):
 

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.