updating documentation

Author: kumarvna

README.md

@@ -2,30 +2,42 @@
 
 Azure Key Vault is a tool for securely storing and accessing secrets. A secret is anything that you want to tightly control access to, such as API keys, passwords, or certificates. A vault is a logical group of secrets.
 
-This Terraform Module creates a Key Vault also adds required access policies for AD users and groups. This also sends all logs to log analytic workspace and storage.
+This Terraform Module creates a Key Vault also adds required access policies for azure AD users, groups and azure AD service principals. This also enables private endpoint and sends all logs to log analytic workspace or storage.
+
+## Resources Supported
+
+* [Acess Polices for AD users, groups and SPN](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/resources/key_vault_access_policy)
+* [Secrets](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/resources/key_vault_secret)
+* [Certifiate Contacts](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/resources/key_vault#contact)
+* [Private Endpoints](https://www.terraform.io/docs/providers/azurerm/r/private_endpoint.html)
+* [Private DNS zone for `privatelink` A records](https://www.terraform.io/docs/providers/azurerm/r/private_dns_zone.html)
+* [Azure Log Dignostics](https://www.terraform.io/docs/providers/azurerm/r/network_security_group.html)
 
 ## Module Usage
 
-```hcl
+```terraform
+# Azurerm Provider configuration
+provider "azurerm" {
+  features {}
+}
+
 module "key-vault" {
   source  = "kumarvna/key-vault/azurerm"
-  version = "2.1.0"
+  version = "2.2.0"
 
-  # Resource Group and Key Vault pricing tier details
+  # By default, this module will not create a resource group and expect to provide 
+  # a existing RG name to use an existing resource group. Location will be same as existing RG. 
+  # set the argument to `create_resource_group = true` to create new resrouce.
   resource_group_name        = "rg-shared-westeurope-01"
   key_vault_name             = "demo-project-shard"
   key_vault_sku_pricing_tier = "premium"
 
   # Once `Purge Protection` has been Enabled it's not possible to Disable it
-  # Deleting the Key Vault with `Purge Protection` enabled will schedule the Key Vault to be deleted 
+  # Deleting the Key Vault with `Purge Protection` enabled will schedule the Key Vault to be deleted
   # The default retention period is 90 days, possible values are from 7 to 90 days
   # use `soft_delete_retention_days` to set the retention period
   enable_purge_protection = false
-
-  # Adding Key vault logs to Azure monitoring and Log Analytics space
-  # to enable key-vault logs, either one of log_analytics_workspace_id or storage_account_id required  
-  log_analytics_workspace_id = var.log_analytics_workspace_id
-  storage_account_id         = var.storage_account_id
+  # soft_delete_retention_days = 90
 
   # Access policies for users, you can provide list of Azure AD users and set permissions.
   # Make sure to use list of user principal names of Azure AD users.
@@ -38,24 +50,41 @@ module "key-vault" {
       storage_permissions           = ["backup", "get", "list", "recover"]
     },
 
-  # Access policies for AD Groups, enable this feature to provide list of Azure AD groups and set permissions.
+    # Access policies for AD Groups
+    # enable this feature to provide list of Azure AD groups and set permissions.
     {
-      azure_ad_group_names = ["ADGroupName1", "ADGroupName2"]
-      secret_permissions   = ["get", "list", "set"]
+      azure_ad_group_names    = ["ADGroupName1", "ADGroupName2"]
+      key_permissions         = ["get", "list"]
+      secret_permissions      = ["get", "list"]
+      certificate_permissions = ["get", "import", "list"]
+      storage_permissions     = ["backup", "get", "list", "recover"]
     },
 
+    # Access policies for Azure AD Service Principlas
+    # enable this feature to provide list of Azure AD SPN and set permissions.
+    {
+      azure_ad_service_principal_names = ["azure-ad-dev-sp1", "azure-ad-dev-sp2"]
+      key_permissions                  = ["get", "list"]
+      secret_permissions               = ["get", "list"]
+      certificate_permissions          = ["get", "import", "list"]
+      storage_permissions              = ["backup", "get", "list", "recover"]
+    }
   ]
 
   # Create a required Secrets as per your need.
-  # When you Add `usernames` with empty password this module creates a strong random password 
-  # use .tfvars file to manage the secrets as variables to avoid security issues. 
+  # When you Add `usernames` with empty password this module creates a strong random password
+  # use .tfvars file to manage the secrets as variables to avoid security issues.
   secrets = {
     "message" = "Hello, world!"
     "vmpass"  = ""
   }
 
-  # Adding TAG's to your Azure resources (Required)
-  # ProjectName and Env are already declared above, to use them here or create a varible. 
+  # (Optional) To enable Azure Monitoring for Azure Application Gateway 
+  # (Optional) Specify `storage_account_id` to save monitoring logs to storage. 
+  log_analytics_workspace_id = var.log_analytics_workspace_id
+  #storage_account_id         = var.storage_account_id
+
+  # Adding additional TAG's to your Azure resources
   tags = {
     ProjectName  = "demo-project"
     Env          = "dev"
@@ -75,7 +104,7 @@ Default action is set to `Allow` when no network rules matched. A `virtual_netwo
 ```hcl
 module "key-vault" {
   source  = "kumarvna/key-vault/azurerm"
-  version = "2.1.0"
+  version = "2.2.0"
 
   # .... omitted
 
@@ -123,54 +152,100 @@ When purge protection is on, a vault or an object in the deleted state cannot be
 
 > The default retention period is 90 days for the soft-delete and the purge protection retention policy uses the same interval. Once set, the retention policy interval cannot be changed.
 
-## Recommended naming and tagging conventions
+## Certificate contacts
 
-Well-defined naming and metadata tagging conventions help to quickly locate and manage resources. These conventions also help associate cloud usage costs with business teams via chargeback and show back accounting mechanisms.
+Certificate contacts contain contact information to send notifications triggered by certificate lifetime events. The contacts information is shared by all the certificates in the key vault. A notification is sent to all the specified contacts for an event for any certificate in the key vault.
 
-> ### Resource naming
+```terraform
+module "key-vault" {
+  source  = "kumarvna/key-vault/azurerm"
+  version = "2.2.0"
 
-An effective naming convention assembles resource names by using important resource information as parts of a resource's name. For example, using these [recommended naming conventions](https://docs.microsoft.com/en-us/azure/cloud-adoption-framework/ready/azure-best-practices/naming-and-tagging#example-names), a public IP resource for a production SharePoint workload is named like this: `pip-sharepoint-prod-westus-001`.
+  # .... omitted
 
-> ### Metadata tags
+  # The contacts information is shared by all the certificates in the key vault. 
+  # A notification is sent to all the specified contacts for an event for any certificate in the key vault. 
+  # This field can only be set once user has `managecontacts` certificate permission.
+  certificate_contacts = [
+    {
+      email = "[email protected]"
+      name  = "User1"
+      phone = "1010101010"
+    },
+    {
+      email = "[email protected]"
+      name  = "User2"
+      phone = "2020202020"
+    },
+  ]
 
-When applying metadata tags to the cloud resources, you can include information about those assets that couldn't be included in the resource name. You can use that information to perform more sophisticated filtering and reporting on resources. This information can be used by IT or business teams to find resources or generate reports about resource usage and billing.
+  # ....omitted
 
-The following list provides the recommended common tags that capture important context and information about resources. Use this list as a starting point to establish your tagging conventions.
+}
+```
 
-Tag Name|Description|Key|Example Value|Required?
---------|-----------|---|-------------|---------|
-Project Name|Name of the Project for the infra is created. This is mandatory to create a resource names.|ProjectName|{Project name}|Yes
-Application Name|Name of the application, service, or workload the resource is associated with.|ApplicationName|{app name}|Yes
-Approver|Name Person responsible for approving costs related to this resource.|Approver|{email}|Yes
-Business Unit|Top-level division of your company that owns the subscription or workload the resource belongs to. In smaller organizations, this may represent a single corporate or shared top-level organizational element.|BusinessUnit|FINANCE, MARKETING,{Product Name},CORP,SHARED|Yes
-Cost Center|Accounting cost center associated with this resource.|CostCenter|{number}|Yes
-Disaster Recovery|Business criticality of this application, workload, or service.|DR|Mission Critical, Critical, Essential|Yes
-Environment|Deployment environment of this application, workload, or service.|Env|Prod, Dev, QA, Stage, Test|Yes
-Owner Name|Owner of the application, workload, or service.|Owner|{email}|Yes
-Requester Name|User that requested the creation of this application.|Requestor| {email}|Yes
-Service Class|Service Level Agreement level of this application, workload, or service.|ServiceClass|Dev, Bronze, Silver, Gold|Yes
-Start Date of the project|Date when this application, workload, or service was first deployed.|StartDate|{date}|No
-End Date of the Project|Date when this application, workload, or service is planned to be retired.|EndDate|{date}|No
+## Private Endpoint - Integrate Key Vault with Azure Private Link
 
-> This module allows you to manage the above metadata tags directly or as a variable using `variables.tf`. All Azure resources which support tagging can be tagged by specifying key-values in argument `tags`. Tag `ResourceName` is added automatically to all resources.
+Azure Private Endpoint is a network interface that connects you privately and securely to a service powered by Azure Private Link. Private Endpoint uses a private IP address from your VNet, effectively bringing the service into your VNet.
 
-```hcl
+With Private Link, Microsoft offering the ability to associate a logical server to a specific private IP address (also known as private endpoint) within the VNet. Clients can connect to the Private endpoint from the same VNet, peered VNet in same region, or via VNet-to-VNet connection across regions. Additionally, clients can connect from on-premises using ExpressRoute, private peering, or VPN tunneling.
+
+By default, this feature not enabled on this module. To create private link with private endpoints set the variable `enable_private_endpoint` to `true` and provide `virtual_network_name`, `private_subnet_address_prefix` with a valid values. You can also use the existing private DNS zone to create DNS records. To use this feature, set the `existing_private_dns_zone` with a valid existing private DNS zone name.
+
+```terraform
 module "key-vault" {
   source  = "kumarvna/key-vault/azurerm"
-  version = "2.1.0"
+  version = "2.2.0"
 
-  # ... omitted
+  # .... omitted
 
-  tags = {
-    ProjectName  = "demo-project"
-    Env          = "dev"
-    Owner        = "[email protected]"
-    BusinessUnit = "CORP"
-    ServiceClass = "Gold"
-  }
-}  
+  # Creating Private Endpoint requires, VNet name and address prefix to create a subnet
+  # By default this will create a `privatelink.vaultcore.azure.net` DNS zone. 
+  # To use existing private DNS zone specify `existing_private_dns_zone` with valid zone name
+  enable_private_endpoint       = true
+  virtual_network_name          = "vnet-shared-hub-westeurope-001"
+  private_subnet_address_prefix = ["10.1.5.0/27"]
+  # existing_private_dns_zone     = "demo.example.com"
+
+  # ....omitted
+
+}
 ```
 
+If you want to use eixsting VNet and Subnet to create a private endpoints, set a variable `enable_private_endpoint` to `true` and provide `existing_vnet_id`, `existing_subnet_id` with a valid resource ids. You can also use the existing private DNS zone to create DNS records. To use this feature, set the `existing_private_dns_zone` with a valid existing private DNS zone name.
+
+```terraform
+module "key-vault" {
+  source  = "kumarvna/key-vault/azurerm"
+  version = "2.2.0"
+
+  # .... omitted
+
+  # Creating Private Endpoint requires, VNet name and address prefix to create a subnet
+  # By default this will create a `privatelink.vaultcore.azure.net` DNS zone. 
+  # To use existing private DNS zone specify `existing_private_dns_zone` with valid zone name
+  enable_private_endpoint = true
+  existing_vnet_id        = data.azurerm_virtual_network.example.id
+  existing_subnet_id      = data.azurerm_subnet.example.id
+  # existing_private_dns_zone     = "demo.example.com"
+
+  # ....omitted
+
+}
+```
+
+For more details: [Integrate Key Vault with Azure Private Link](https://docs.microsoft.com/en-us/azure/key-vault/general/private-link-service?tabs=portal)
+
+## 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.
+For recommendations on how to implement a tagging strategy, see Resource naming and tagging decision guide.
+
+>**Important** :
+Tag names are case-insensitive for operations. A tag with a tag name, regardless of the casing, is updated or retrieved. However, the resource provider might keep the casing you provide for the tag name. You'll see that casing in cost reports. **Tag values are case-sensitive.**
+
+An effective naming convention assembles resource names by using important resource information as parts of a resource's name. For example, using these [recommended naming conventions](https://docs.microsoft.com/en-us/azure/cloud-adoption-framework/ready/azure-best-practices/naming-and-tagging#example-names), a public IP resource for a production SharePoint workload is named like this: `pip-sharepoint-prod-westus-001`.
+
 ## Requirements
 
 Name | Version
@@ -184,7 +259,7 @@ azurerm | >= 2.59.0
 |------|---------|
 azurerm | >= 2.59.0
 random | >= 3.1.0
-azuread | >= 1.4.0
+azuread | >= 2.7.0
 
 ## Inputs
 

examples/keyvault_private_end_point_with_existing_VNet_Subnet/README.md

@@ -2,7 +2,7 @@
 
 Terraform Module to create a Key Vault also adds required access policies for azure AD users, groups and azure AD service principals. This module also creates private endpoint and sends all logs to log analytic workspace or storage.
 
-## Module Usage to enable privaite endpoint
+## Module Usage to enable privaite endpoint using existing VNet and Subnet
 
 ```hcl
 # Azurerm Provider configuration