Improve TF doc (#64)

README.md

@@ -6,10 +6,15 @@
 [![Build Status](https://dev.azure.com/geekzter/Pipeline%20Playground/_apis/build/status%2Fcreate-service-connection?branchName=main&label=terraform-ci)](https://dev.azure.com/geekzter/Pipeline%20Playground/_build/latest?definitionId=5&branchName=main)
 [![Build Status](https://dev.azure.com/geekzter/Pipeline%20Playground/_apis/build/status%2Fterraform-azure-environment-variables?branchName=main&label=create-oidc-token-ci)](https://dev.azure.com/geekzter/Pipeline%20Playground/_build/latest?definitionId=11&branchName=main)
 
+## Terraform-managed Azure Service Connection
+
+Manage Azure Service Connections with [Terraform](terraform/azure-devops/create-service-connection/README.md) to create Managed Identity, Federated Identity Credential, Entra ID group membership, implement secret rotation, assign co-owners and ITSM metadata.
+
+## Scripts
 
 This repo contains a few [PowerShell](https://github.com/PowerShell/PowerShell) scripts that use the [Azure CLI](https://github.com/Azure/azure-cli) to create or find Entra ID objects:
 
-## Entra ID
+### Entra ID
 
 - Find Service Principal or Managed Identity with [find_workload_identity.ps1](scripts/find_workload_identity.ps1), using any of these as argument:
   - Application/Client id
@@ -24,16 +29,15 @@ This repo contains a few [PowerShell](https://github.com/PowerShell/PowerShell)
 - Purge deleted directory objects (e.g. applications): [purge_deleted_objects.ps1](scripts/purge_deleted_objects.ps1)
 - Add IT Service Management data (reference, co-owner) to applications: [add_app_itsm_information.ps1](scripts/add_app_itsm_information.ps1)
 
-## Azure DevOps
+### Azure DevOps
 
-- Manage Azure Service Connection with [Terraform](terraform/azure-devops/create-service-connection/README.md) to create Managed Identity, Federated Identity Credential, secret rotation and ITSM metadata
 - Configure Terraform [azuread](https://registry.terraform.io/providers/hashicorp/azuread/latest/docs#authenticating-to-azure-active-directory)/[azurerm](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs#authenticating-to-azure) provider `ARM_*` environment variables to use the [AzureCLI](https://learn.microsoft.com/azure/devops/pipelines/tasks/reference/azure-cli-v2?view=azure-pipelines) task [Service Connection](https://learn.microsoft.com/azure/devops/pipelines/library/connect-to-azure?view=azure-devops):  
   [set_terraform_azurerm_vars.ps1](scripts/azure-devops/set_terraform_azurerm_vars.ps1)
 - Create Managed Identity for Service Connection with Workload identity federation: [create_azurerm_msi_oidc_service_connection.ps1](scripts/azure-devops/create_azurerm_msi_oidc_service_connection.ps1)
 - List identities for Azure DevOps Service Connections in Entra ID pertaining to Azure DevOps organization and (optionally) project: [list_service_connection_identities.ps1](scripts/azure-devops/list_service_connection_identities.ps1)
 - List Azure DevOps Service Connections in an Azure DevOps organization and project: [list_service_connections.ps1](scripts/azure-devops/list_service_connections.ps1)
 - 'Pretty-name' Entra ID applications created for Service Connections, so the Service Connection name is included in the application display name: [rename_service_connection_applications.ps1](scripts/azure-devops/rename_service_connection_applications.ps1)
 
-## GitHub
+### GitHub
 
 - Create Service Principal for GitHub Actions with Workload identity federation: [create_sp_for_github_actions.ps1](scripts/github/github-actions.md)   

terraform/azure-devops/create-service-connection/README.md

@@ -3,6 +3,8 @@
 
 [![Build Status](https://dev.azure.com/geekzter/Pipeline%20Playground/_apis/build/status%2Fcreate-service-connection?branchName=main&label=terraform-ci)](https://dev.azure.com/geekzter/Pipeline%20Playground/_build/latest?definitionId=5&branchName=main)
 
+![](visuals/diagram.png)
+
 Azure DevOps uses service connections to connect to services that are targets for cloud infrastructure provisioning and application deployment. The most commonly used service connection is the [Azure Resource Manager service connection](https://learn.microsoft.com/azure/devops/pipelines/library/connect-to-azure?view=azure-devops). This creates an object in Azure DevOps, an identity in Entra ID and a role assignment in Azure.
 
 Many Enterprise customers have requirements around the management of Entra [workload identities](https://learn.microsoft.com/entra/workload-id/workload-identities-overview) (applications, service principals, managed identities) as well as the permissions they are assigned to.
@@ -70,7 +72,6 @@ Pre-requisites:
 This creates a Managed Identity with Federated Identity Credential and custom Azure RBAC (role-based access control) role assignments:
 
 ```hcl
-azdo_creates_identity          = false
 azdo_organization_url          = "https://dev.azure.com/my-organization"
 azdo_project_name              = "my-project"
 azure_role_assignments         = [
@@ -102,7 +103,6 @@ Pre-requisites:
 This creates a Managed Identity with Federated Identity Credential and custom Azure RBAC (role-based access control) role assignments:
 
 ```hcl
-azdo_creates_identity          = false
 azdo_organization_url          = "https://dev.azure.com/my-organization"
 azdo_project_name              = "my-project"
 azure_role_assignments         = [] # No direct assignments
@@ -115,14 +115,13 @@ managed_identity_resource_group_id = "/subscriptions/11111111-1111-1111-1111-111
 Pre-requisites:
 
 - A resource group to hold the Managed Identity has been pre-created
-- The user is an owner of the security enabled Entra ID group to add the Managed Identity to
+- The user is an owner of the Entra ID security group to add the Managed Identity to
 
 #### App registration with FIC and ITSM metadata
 
 This creates an Entra ID app registration with IT service reference and notes fields populated as well as specifying co-owners:
 
 ```hcl
-azdo_creates_identity          = false
 azdo_organization_url          = "https://dev.azure.com/my-organization"
 azdo_project_name              = "my-project"
 create_federation              = true
@@ -145,7 +144,6 @@ Pre-requisites:
 This creates an Entra ID app registration with secret that expires after 1 hour:
 
 ```hcl
-azdo_creates_identity          = false
 azdo_organization_url          = "https://dev.azure.com/my-organization"
 azdo_project_name              = "my-project"
 azure_role_assignments         = [

terraform/azure-devops/create-service-connection/doc-gen/header.md

@@ -2,6 +2,8 @@
 
 [![Build Status](https://dev.azure.com/geekzter/Pipeline%20Playground/_apis/build/status%2Fcreate-service-connection?branchName=main&label=terraform-ci)](https://dev.azure.com/geekzter/Pipeline%20Playground/_build/latest?definitionId=5&branchName=main)
 
+![](visuals/diagram.png)
+
 Azure DevOps uses service connections to connect to services that are targets for cloud infrastructure provisioning and application deployment. The most commonly used service connection is the [Azure Resource Manager service connection](https://learn.microsoft.com/azure/devops/pipelines/library/connect-to-azure?view=azure-devops). This creates an object in Azure DevOps, an identity in Entra ID and a role assignment in Azure.
 
 Many Enterprise customers have requirements around the management of Entra [workload identities](https://learn.microsoft.com/entra/workload-id/workload-identities-overview) (applications, service principals, managed identities) as well as the permissions they are assigned to.
@@ -69,7 +71,6 @@ Pre-requisites:
 This creates a Managed Identity with Federated Identity Credential and custom Azure RBAC (role-based access control) role assignments:
 
 ```hcl
-azdo_creates_identity          = false
 azdo_organization_url          = "https://dev.azure.com/my-organization"
 azdo_project_name              = "my-project"
 azure_role_assignments         = [
@@ -101,7 +102,6 @@ Pre-requisites:
 This creates a Managed Identity with Federated Identity Credential and custom Azure RBAC (role-based access control) role assignments:
 
 ```hcl
-azdo_creates_identity          = false
 azdo_organization_url          = "https://dev.azure.com/my-organization"
 azdo_project_name              = "my-project"
 azure_role_assignments         = [] # No direct assignments
@@ -114,14 +114,13 @@ managed_identity_resource_group_id = "/subscriptions/11111111-1111-1111-1111-111
 Pre-requisites:
 
 - A resource group to hold the Managed Identity has been pre-created
-- The user is an owner of the security enabled Entra ID group to add the Managed Identity to
+- The user is an owner of the Entra ID security group to add the Managed Identity to
 
 #### App registration with FIC and ITSM metadata
 
 This creates an Entra ID app registration with IT service reference and notes fields populated as well as specifying co-owners:
 
 ```hcl
-azdo_creates_identity          = false
 azdo_organization_url          = "https://dev.azure.com/my-organization"
 azdo_project_name              = "my-project"
 create_federation              = true
@@ -144,7 +143,6 @@ Pre-requisites:
 This creates an Entra ID app registration with secret that expires after 1 hour:
 
 ```hcl
-azdo_creates_identity          = false
 azdo_organization_url          = "https://dev.azure.com/my-organization"
 azdo_project_name              = "my-project"
 azure_role_assignments         = [