Proposed rewrite to "Creating Microsoft Azure Virtual Machines for NGINX Open Source and F5 NGINX Plus" #608
+49
−41
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Co-authored-by: Alan Dooley <github@adubhlaoi.ch>
Co-authored-by: Alan Dooley <github@adubhlaoi.ch>
Co-authored-by: Alan Dooley <github@adubhlaoi.ch>
Co-authored-by: Alan Dooley <github@adubhlaoi.ch>
Co-authored-by: Alan Dooley <github@adubhlaoi.ch>
Co-authored-by: Alan Dooley <github@adubhlaoi.ch>
Co-authored-by: Alan Dooley <github@adubhlaoi.ch>
Co-authored-by: Alan Dooley <github@adubhlaoi.ch>
Co-authored-by: Alan Dooley <github@adubhlaoi.ch>
Co-authored-by: Alan Dooley <github@adubhlaoi.ch>
Co-authored-by: Alan Dooley <github@adubhlaoi.ch>
Co-authored-by: Alan Dooley <github@adubhlaoi.ch>
Co-authored-by: Alan Dooley <github@adubhlaoi.ch>
Hi @ADubhlaoich 👋 Thank you for your thoughtful suggestions! I’ve committed all the changes and will closely review the rest of the file to catch any similar issues. Really appreciate your patience as I get up to speed (Whew!). Your feedback has been incredibly helpful. Please let me know if you spot anything else. Thank you so much once again. :) |
JTorreG
reviewed
Jul 7, 2025
|
|
||
| 2. Click the Virtual machines icon. Or click the stacked lines icon (☰) in the top-left corner and select Virtual machines from the menu. |
There was a problem hiding this comment.
Suggested change
| 2. Click the Virtual machines icon. Or click the stacked lines icon (☰) in the top-left corner and select Virtual machines from the menu. | |
| 2. Select the Virtual machines icon. Or select the stacked lines icon (☰) in the top-left corner and select Virtual machines from the menu. |
JTorreG
reviewed
Jul 7, 2025
| <img src="/nginx/images/azure-portal.png" alt="screenshot of top navigation bar at Microsoft Azure portal" width="1024" height="226" class="aligncenter size-full image-64310" style="border:2px solid #666666; padding:2px; margin:2px;" /> | ||
|
|
||
| 3. On the **Virtual machines** page that opens, click **<span style="color:#4d9bdc;">+</span> Add** in the upper left corner. | ||
| 3. On the Virtual machines page that opens, click **+ Add** in the upper left corner. |
There was a problem hiding this comment.
Suggested change
| 3. On the Virtual machines page that opens, click **+ Add** in the upper left corner. | |
| 3. On the Virtual machines page that opens, select **+ Add** in the upper left corner. |
JTorreG
reviewed
Jul 7, 2025
| When this guide was first published, the hourly cost for the six VMs was only $0.008. And this costlier than VMs with basic IP addresses. For current pricing, see the [Microsoft documentation](https://azure.microsoft.com/en-us/pricing/details/ip-addresses/). | ||
| Depending on your work load, you might need up to 6 VMs. Follow these steps: | ||
| - Open the **Networking** tab on the **Create a virtual machine** window. | ||
| - Click _Create new_ below the **Public IP** field. |
There was a problem hiding this comment.
Suggested change
| - Click _Create new_ below the **Public IP** field. | |
| - Select _Create new_ below the **Public IP** field. |
JTorreG
reviewed
Jul 7, 2025
|
|
||
| <a href="/nginx/images/azure-create-vm-networking.png"><img src="/nginx/images/azure-create-vm-networking.png" alt="screenshot of 'Networking' tab on Azure 'Create a virtual machine' page" width="1024" height="718" class="aligncenter size-full wp-image-64994" style="border:2px solid #666666; padding:2px; margin:2px;" /></a> | ||
| When this guide was first published, the hourly cost for the six VMs was only $0.008. And this costlier than VMs with basic IP addresses. For current pricing, see the [Microsoft documentation](https://azure.microsoft.com/en-us/pricing/details/ip-addresses/). | ||
| Depending on your work load, you might need up to 6 VMs. Follow these steps: |
There was a problem hiding this comment.
Suggested change
| Depending on your work load, you might need up to 6 VMs. Follow these steps: | |
| Depending on your workload, you might need up to 6 VMs. Follow these steps: |
JTorreG
reviewed
Jul 7, 2025
| - Click _Create new_ below the **Public IP** field. | ||
| - In the **Create public IP address column** that opens, click the **Standard Radio button** under **SKU**. | ||
| - In the **Name** field, accept the default created by Azure, ngx-plus-1-ip. | ||
| - Click the _Ok_ button. |
There was a problem hiding this comment.
Suggested change
| - Click the _Ok_ button. | |
| - Select _Ok_. |
When referring to a button by the label it is showing on screen there is no need to add "button" after. "Select Apply, Select Cancel, etc"
JTorreG
reviewed
Jul 7, 2025
|
|
||
| <a href="/nginx/images/azure-create-vm-networking.png"><img src="/nginx/images/azure-create-vm-networking.png" alt="screenshot of 'Networking' tab on Azure 'Create a virtual machine' page" width="1024" height="718" class="aligncenter size-full wp-image-64994" style="border:2px solid #666666; padding:2px; margin:2px;" /></a> | ||
| When this guide was first published, the hourly cost for the six VMs was only $0.008. And this costlier than VMs with basic IP addresses. For current pricing, see the [Microsoft documentation](https://azure.microsoft.com/en-us/pricing/details/ip-addresses/). |
There was a problem hiding this comment.
The first sentence does not make sense and needs to be rewritten.
JTorreG
reviewed
Jul 7, 2025
|
|
||
| If all of your settings are valid, a summary of them appears under the **Validation passed** banner, as in the following screenshot. | ||
| After you've completed your changes, click the _Review + create_ button at the bottom of the **Create a virtual machine** page. |
There was a problem hiding this comment.
Suggested change
| After you've completed your changes, click the _Review + create_ button at the bottom of the **Create a virtual machine** page. | |
| After you've completed your changes, select _Review + create_ at the bottom of the **Create a virtual machine** page. |
JTorreG
reviewed
Jul 7, 2025
|
|
||
| To change any settings, open the appropriate tab. If the settings are correct, click the <span style="background-color:#137ad1; color:white;"> Create </span> button. | ||
| You’ll find a summary of your setting under the **Validation passed** banner. Ensure they’re suitable. Then, click on <span style="background-color:#137ad1; color:white;"> Create </span> |
There was a problem hiding this comment.
Suggested change
| You’ll find a summary of your setting under the **Validation passed** banner. Ensure they’re suitable. Then, click on <span style="background-color:#137ad1; color:white;"> Create </span> | |
| You’ll find a summary of your setting under the **Validation passed** banner. Ensure they’re suitable. Then, select Create. |
While the original doc is using a span here, we are moving away from using raw HTML, so this is a good chance to correct that.
JTorreG
reviewed
Jul 7, 2025
|
|
||
| If you chose in [Step 4](#create-vm_Basics) to generate a new key pair, a {{<nb>}}**Generate new key pair**{{</nb>}} window pops up. Click the <span style="background-color:#137ad1; color:white; white-space: nowrap;"> Download key and create private resource </span> button. | ||
| If you generated a new key pair in [Step 4](#create-vm_Basics), a _Generate new key pair_ window pops up. Click on the _Download key and create private resource_ button. |
There was a problem hiding this comment.
Suggested change
| If you generated a new key pair in [Step 4](#create-vm_Basics), a _Generate new key pair_ window pops up. Click on the _Download key and create private resource_ button. | |
| If you generated a new key pair in [Step 4](#create-vm_Basics), a _Generate new key pair_ window pops up. Select _Download key and create private resource_. |
JTorreG
reviewed
Jul 7, 2025
|
|
||
| <a href="/nginx/images/azure-create-vm-validation-passed.png"><img src="/nginx/images/azure-create-vm-validation-passed.png" alt="screenshot of validation message on Azure 'Create a virtual machine' page" width="1024" height="954" class="aligncenter size-full image-64993" style="border:2px solid #666666; padding:2px; margin:2px;" /></a> | ||
|
|
||
| It takes a few minutes for a VM to deploy. When it's ready, a summary of associated resources appears, as in the following screenshot. | ||
| VM deployment only takes a few minutes. After that, you’ll get a summary of your resources. Just like in the following screenshot. |
There was a problem hiding this comment.
Suggested change
| VM deployment only takes a few minutes. After that, you’ll get a summary of your resources. Just like in the following screenshot. | |
| The VM deployment takes a few minutes. After that, you’ll get a summary of your resources. See an example in the following screenshot. |
Avoid "just", "only" and similar expressions
JTorreG
reviewed
Jul 7, 2025
| @@ -218,7 +226,7 @@ To streamline the process of installing NGINX Open Source on multiple VMs, you c | |||
|
|
|||
| ### Creating a VM from the Image | |||
|
|
|||
| It takes a few moments for the image to be created. When it's ready, you can create VMs from it with NGINX Open Source already installed. | |||
| An Azure image takes only a few moments to deploy. When it’s ready, you can create VMs from it with NGINX Open Source already installed. | |||
There was a problem hiding this comment.
Suggested change
| An Azure image takes only a few moments to deploy. When it’s ready, you can create VMs from it with NGINX Open Source already installed. | |
| An Azure image takes a few moments to deploy. When it’s ready, you can create VMs from it with NGINX Open Source already installed. |
See my previous comment
JTorreG
reviewed
Jul 7, 2025
| @@ -228,7 +236,7 @@ It takes a few moments for the image to be created. When it's ready, you can cre | |||
|
|
|||
| <a href="/nginx/images/azure-create-image-create-vm.png"><img src="/nginx/images/azure-create-image-create-vm.png" alt="screenshot of details page for Azure 'ngx-plus-1-image' image" width="1024" height="426" class="aligncenter size-full wp-image-64986" style="border:2px solid #666666; padding:2px; margin:2px;" /></a> | |||
|
|
|||
| The **Create a virtual machine** page that opens is the same as in Step 4 of Creating a Microsoft Azure Virtual Machine, except that some fields have hardcoded values derived from the image and the **Image** field has the name of the image instead of an operating system. Return to that [step](#create-vm_Basics) to complete the VM creation. | |||
| The **Create a VM** page looks like Step 4 in Creating a Microsoft Azure Virtual Machine, but some fields are pre-filled from your image. The **Image** field now shows the image name instead of an OS. Go back to that [step](#create-vm_Basics) to finish creating your VM. | |||
There was a problem hiding this comment.
Suggested change
| The **Create a VM** page looks like Step 4 in Creating a Microsoft Azure Virtual Machine, but some fields are pre-filled from your image. The **Image** field now shows the image name instead of an OS. Go back to that [step](#create-vm_Basics) to finish creating your VM. | |
| The **Create a VM** page is similar to the Step 4 in Creating a Microsoft Azure Virtual Machine, but some fields are pre-filled from your image. The **Image** field now shows the image name instead of an OS. Go back to that [step](#create-vm_Basics) to finish creating your VM. |
y82
reviewed
Jul 7, 2025
| @@ -71,32 +73,38 @@ In addition, to install NGINX software by following the linked instructions, you | |||
| <a href="/nginx/images/azure-create-vm-basics.png"><img src="/nginx/images/azure-create-vm-basics.png" alt="screenshot of 'Basics' tab on Azure 'Create a virtual machine' page" width="1024" height="1168" class="aligncenter size-full wp-image-64995" style="border:2px solid #666666; padding:2px; margin:2px;" /></a> | |||
|
|
|||
| <span id="create-vm_Networking"></span> | |||
| 5. If you are creating VMs to use in [Active-Active HA for NGINX Plus on Microsoft Azure Using the Azure Standard Load Balancer]({{< ref "high-availability-standard-load-balancer.md" >}}), the two NGINX Plus VMs in that deployment must have public IP addresses with SKU type **Standard** instead of the default **Basic**. | |||
| 5. For [Active-Active HA for NGINX Plus on Microsoft Azure Using the Azure Standard Load Balancer]({{< ref "high-availability-standard-load-balancer.md" >}}): | |||
There was a problem hiding this comment.
The original text of step 5 is still more understandable for me (although I understand it's not perfect) so I'd rather use the original version, thanks
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
NOTE: this is a rewrite only. No technical changes.
The original documentation was slightly difficult to read and follow. It had complex sentences and paragraphs that scored 14 on the Hemmingway app. Some constructs were conflicting or confusing, which took longer to understand.
I improved the document’s readability and clarity, making it accessible to a wider, non-expert audience. Here’s how:
Testing: I used the Hemmingway app to confirm readability and studied the terms individually to ensure they were all updated.
README.mdandCHANGELOG.mdFootnotes
Potentially sensitive changes include anything involving code, personally identify information (PII), live URLs or significant amounts of new or revised documentation. Please refer to our style guide for guidance about placeholder content. ↩