updating the documentation #3

Author: kumarvna

README.md

@@ -4,13 +4,11 @@ Azure virtual machine scale sets let you create and manage a group of identical,
 
 This module deploys Windows or Linux virtual machine scale sets with Public / Private Load Balancer support and many other features.
 
-> **[NOTE]**
-> **This module now supports the meta arguments including `providers`, `depends_on`, `count`, and `for_each`.**
-
 ## Resources Supported
 
 * [Linux Virtual Machine Scale Set](https://www.terraform.io/docs/providers/azurerm/r/linux_virtual_machine_scale_set.html)
 * [Windows Virtual Machine Scale Set](https://www.terraform.io/docs/providers/azurerm/r/windows_virtual_machine_scale_set.html)
+* [Automatic OS image upgrade](https://docs.microsoft.com/en-us/azure/virtual-machine-scale-sets/virtual-machine-scale-sets-automatic-upgrade)
 * [Public Azure Load Balancer](https://www.terraform.io/docs/providers/azurerm/r/lb.html)
 * [Private Azure Load Balancer](https://www.terraform.io/docs/providers/azurerm/r/lb.html)
 * [Inbound NAT Rule](https://www.terraform.io/docs/providers/azurerm/r/lb_nat_pool.html)
@@ -20,42 +18,47 @@ This module deploys Windows or Linux virtual machine scale sets with Public / Pr
 
 ## Module Usage
 
-```hcl
+```terraform
 # Azurerm provider configuration
 provider "azurerm" {
   features {}
 }
 
+data "azurerm_log_analytics_workspace" "example" {
+  name                = "loganalytics-we-sharedtest2"
+  resource_group_name = "rg-shared-westeurope-01"
+}
+
 module "vmscaleset" {
   source  = "kumarvna/vm-scale-sets/azurerm"
-  version = "2.2.0"
+  version = "2.3.0"
 
   # Resource Group and location, VNet and Subnet detials (Required)
   resource_group_name  = "rg-shared-westeurope-01"
   virtual_network_name = "vnet-shared-hub-westeurope-001"
   subnet_name          = "snet-management"
   vmscaleset_name      = "testvmss"
 
-  # (Optional) To enable Azure Monitoring and install log analytics agents
-  # (Optional) Specify `storage_account_name` to save monitoring logs to storage. 
-  log_analytics_workspace_name = var.log_analytics_workspace_name
-
-  # Deploy log analytics agents to virtual machine. Log analytics workspace name required.
-  # Defaults to `false` 
-  deploy_log_analytics_agent = false
-
   # This module support multiple Pre-Defined Linux and Windows Distributions.
-  # These distributions support the Automatic OS image upgrades in virtual machine scale sets
-  # Linux images: ubuntu1804, ubuntu1604, centos75, coreos
-  # Windows Images: windows2012r2dc, windows2016dc, windows2019dc, windows2016dccore
-  # Specify the RSA key for production workloads and set generate_admin_ssh_key argument to false
-  # When you use Autoscaling feature, instances_count will become default and minimum instance count. 
+  # Check the README.md file for more pre-defined images for Ubuntu, Centos, RedHat.
+  # Please make sure to use gen2 images supported VM sizes if you use gen2 distributions
+  # Specify `disable_password_authentication = false` to create random admin password
+  # Specify a valid password with `admin_password` argument to use your own password 
+  # To generate SSH key pair, specify `generate_admin_ssh_key = true`
+  # To use existing key pair, specify `admin_ssh_key_data` to a valid SSH public key path.  
   os_flavor               = "linux"
   linux_distribution_name = "ubuntu1804"
-  generate_admin_ssh_key  = false
-  admin_ssh_key_data      = "~/.ssh/id_rsa.pub"
+  virtual_machine_size    = "Standard_A2_v2"
+  admin_username          = "azureadmin"
+  generate_admin_ssh_key  = true
   instances_count         = 2
 
+  # Proxymity placement group, Automatic Instance repair and adding Public IP to VM's are optional.
+  # remove these argument from module if you dont want to use it.  
+  enable_proximity_placement_group    = true
+  assign_public_ip_to_each_vm_in_vmss = true
+  enable_automatic_instance_repair    = true
+
   # Public and private load balancer support for VM scale sets
   # Specify health probe port to allow LB to detect the backend endpoint status
   # Standard Load Balancer helps load-balance TCP and UDP flows on all ports simultaneously
@@ -75,10 +78,14 @@ module "vmscaleset" {
   scale_out_cpu_percentage_threshold = 80
   scale_in_cpu_percentage_threshold  = 20
 
+  # Boot diagnostics to troubleshoot virtual machines, by default uses managed 
+  # To use custom storage account, specify `storage_account_name` with a valid name
+  # Passing a `null` value will utilize a Managed Storage Account to store Boot Diagnostics
+  enable_boot_diagnostics = true
+
   # Network Seurity group port allow definitions for each Virtual Machine
   # NSG association to be added automatically for all network interfaces.
-  # SSH port 22 and 3389 is exposed to the Internet recommended for only testing. 
-  # For production environments, we recommend using a VPN or private connection
+  # Remove this NSG rules block, if `existing_network_security_group_id` is specified
   nsg_inbound_rules = [
     {
       name                   = "http"
@@ -93,10 +100,19 @@ module "vmscaleset" {
     },
   ]
 
-  # Adding TAG's to your Azure resources (Required)
-  # ProjectName and Env are already declared above, to use them here, create a varible. 
+  # (Optional) To enable Azure Monitoring and install log analytics agents
+  # (Optional) Specify `storage_account_name` to save monitoring logs to storage.   
+  log_analytics_workspace_id = data.azurerm_log_analytics_workspace.example.id
+
+  # Deploy log analytics agents to virtual machine. 
+  # Log analytics workspace customer id and primary shared key required.
+  deploy_log_analytics_agent                 = true
+  log_analytics_customer_id                  = data.azurerm_log_analytics_workspace.example.workspace_id
+  log_analytics_workspace_primary_shared_key = data.azurerm_log_analytics_workspace.example.primary_shared_key
+
+  # Adding additional TAG's to your Azure resources
   tags = {
-    ProjectName  = "demo-internal"
+    ProjectName  = "demo-project"
     Env          = "dev"
     Owner        = "[email protected]"
     BusinessUnit = "CORP"
@@ -131,14 +147,15 @@ If the pre-defined Windows or Linux variants are not sufficient then, you can sp
 ```hcl
 module "vmscaleset" {
   source  = "kumarvna/vm-scale-sets/azurerm"
-  version = "2.2.0"
+  version = "2.3.0"
 
   # .... omitted
 
   os_flavor               = "linux"
   linux_distribution_name = "ubuntu1804"
-  generate_admin_ssh_key  = false
-  admin_ssh_key_data      = "~/.ssh/id_rsa.pub"
+  virtual_machine_size    = "Standard_A2_v2"
+  admin_username          = "azureadmin"
+  generate_admin_ssh_key  = true
   instances_count         = 2
 
   custom_image = {
@@ -149,6 +166,8 @@ module "vmscaleset" {
     }
 
   # .... omitted
+
+}
 ```
 
 ## Custom DNS servers
@@ -233,6 +252,68 @@ When an instance goes through a state change operation because of a PUT, PATCH o
 
 The automatic instance repair feature can be enabled while creating a new scale set by setting up the argument `enable_automatic_instance_repair = true` and the grace period can be managed using the argument `grace_period = "PT30M"`. Default grace period is 30 minutes.
 
+### `enable_proximity_placement_group` -  Achieving the lowest possible latency
+
+Placing VMs in a single region reduces the physical distance between the instances. Placing them within a single availability zone will also bring them physically closer together. However, as the Azure footprint grows, a single availability zone may span multiple physical data centers, which may result in a network latency impacting your application.
+
+To get VMs as close as possible, achieving the lowest possible latency, you should deploy them within a proximity placement group.
+
+A proximity placement group is a logical grouping used to make sure that Azure compute resources are physically located close to each other. Proximity placement groups are useful for workloads where low latency is a requirement.
+
+By default, this not enabled and set to disable. To enable the Proximity placement group with this module, set the argument `enable_proximity_placement_group = true`.
+
+### `Identity` - Configure managed identities for Azure resources on a VM Scale Sets
+
+Managed identities for Azure resources provides Azure services with an automatically managed identity in Azure Active Directory. You can use this identity to authenticate to any service that supports Azure AD authentication, without having credentials in your code.
+
+There are two types of managed identities:
+
+* **System-assigned**: When enabled a system-assigned managed identity an identity is created in Azure AD that is tied to the lifecycle of that service instance. when the resource is deleted, Azure automatically deletes the identity. By design, only that Azure resource can use this identity to request tokens from Azure AD.
+* **User-assigned**: A managed identity as a standalone Azure resource. For User-assigned managed identities, the identity is managed separately from the resources that use it.
+
+Regardless of the type of identity chosen a managed identity is a service principal of a special type that may only be used with Azure resources. When the managed identity is deleted, the corresponding service principal is automatically removed.
+
+```terraform
+resource "azurerm_user_assigned_identity" "example" {
+  for_each            = toset(["user-identity1", "user-identity2"])
+  resource_group_name = "rg-shared-westeurope-01"
+  location            = "westeurope"
+  name                = each.key
+}
+
+module "vmscaleset" {
+  source  = "kumarvna/vm-scale-sets/azurerm"
+  version = "2.3.0"
+
+  # .... omitted for bravity
+  
+  os_flavor               = "linux"
+  linux_distribution_name = "ubuntu1804"
+  virtual_machine_size    = "Standard_A2_v2"
+  admin_username          = "azureadmin"
+  generate_admin_ssh_key  = true
+  instances_count         = 2
+
+  # Configure managed identities for Azure resources on a VM
+  # Possible types are `SystemAssigned`, `UserAssigned` and `SystemAssigned, UserAssigned`.
+  managed_identity_type = "UserAssigned"
+  managed_identity_ids  = [for k in azurerm_user_assigned_identity.example : k.id]
+
+# .... omitted for bravity
+
+}
+```
+
+### `enable_boot_diagnostics` - boot diagnostics to troubleshoot virtual machines
+
+Boot diagnostics is a debugging feature for Azure virtual machines (VM) that allows the diagnosis of VM boot failures. Boot diagnostics enables a user to observe the state of their VM as it is booting up by collecting serial log information and screenshots. This module enabled this feature by setting up `enable_boot_diagnostics = true`. Azure Storage Account to be used to store Boot Diagnostics, including Console Output and Screenshots from the Hypervisor. This module supports the existing storage account using the `storage_account_name` argument with a valid name. If we are not passing any storage account, it will utilize a Managed Storage Account to store Boot Diagnostics.
+
+### `winrm_protocol` - Enable WinRM wiht HTTPS
+
+Window remote management - in short, `WinRM` is a built-in windows protocol/Service which uses soap[simple object access protocol] to connect from another source system. Using WinRM, we can connect the remote system and execute any command there as its native user.
+
+WinRM comes pre-installed with all new window OS. We need to enable WinRM service and configure the ports for outside traffic. This module configure `winRM` by setting up `winrm_protocol = "Https"` and `key_vault_certificate_secret_url` value to the Secret URL of a Key Vault Certificate.
+
 ## Network Security Groups
 
 By default, the network security groups connected to Network Interface and allow necessary traffic and block everything else (deny-all rule). Use `nsg_inbound_rules` in this Terraform module to create a Network Security Group (NSG) for network interface and allow it to add additional rules for inbound flows.
@@ -244,14 +325,15 @@ In the Source and Destination columns, `VirtualNetwork`, `AzureLoadBalancer`, an
 ```hcl
 module "vmscaleset" {
   source  = "kumarvna/vm-scale-sets/azurerm"
-  version = "2.2.0"
+  version = "2.3.0"
 
-  # .... omitted
+  # .... omitted for bravity
   
   os_flavor               = "linux"
   linux_distribution_name = "ubuntu1804"
-  generate_admin_ssh_key  = false
-  admin_ssh_key_data      = "~/.ssh/id_rsa.pub"
+  virtual_machine_size    = "Standard_A2_v2"
+  admin_username          = "azureadmin"
+  generate_admin_ssh_key  = true
   instances_count         = 2
 
   nsg_inbound_rules = [
@@ -270,6 +352,39 @@ module "vmscaleset" {
 }
 ```
 
+## Using exisging Network Security Groups
+
+Enterprise environments may need a requirement to use pre-existing NSG groups to maintain capabilities. This module supports existing network security groups usage. To use this feature, set the argument `existing_network_security_group_id` with a valid NSG resource id and remove all NSG inbound rules blocks from the module.
+
+```terraform
+data "azurerm_network_security_group" "example" {
+  name                = "nsg_mgnt_subnet_in"
+  resource_group_name = "vnet-shared-hub-westeurope-001"
+}
+
+module "vmscaleset" {
+  source  = "kumarvna/vm-scale-sets/azurerm"
+  version = "2.3.0"
+
+  # .... omitted for bravity
+  
+  os_flavor               = "linux"
+  linux_distribution_name = "ubuntu1804"
+  virtual_machine_size    = "Standard_A2_v2"
+  admin_username          = "azureadmin"
+  generate_admin_ssh_key  = true
+  instances_count         = 2
+
+  # Network Seurity group port allow definitions for each Virtual Machine
+  # NSG association to be added automatically for all network interfaces.
+  # Remove this NSG rules block, if `existing_network_security_group_id` is specified
+  existing_network_security_group_id = data.azurerm_network_security_group.example.id
+
+  # .... omitted for bravity
+
+}
+```
+
 ## Recommended naming and tagging conventions
 
 Applying tags to your Azure resources, resource groups, and subscriptions to logically organize them into a taxonomy. Each tag consists of a name and a value pair. For example, you can apply the name `Environment` and the value `Production` to all the resources in production.
@@ -291,9 +406,9 @@ azurerm | >= 2.59.0
 
 | Name | Version |
 |------|---------|
-azurerm |>= 2.59.0
-random | n/a
-tls | n/a
+| azurerm | >= 2.59.0 |
+| random | >= 3.1.0 |
+| tls | >= 3.1.0 |
 
 ## Inputs