fix: bug fixes and documentation addition for service_map variable (#288)

Author: dishankkalra23

README.md

@@ -14,6 +14,8 @@ Update status and "latest release" badges:
 
 This module generates authorization policies and context-based restriction (CBR) rules to enable access and restrictions between a source service and a target service.
 
+For important details on upgrading from v1 to v2, please refer to the [migration notes](./docs/migration_notes.md). This explains necessary steps for handling `service_map` variable format changes and state migration to avoid unintended policy destruction during your upgrade process.
+
 <!-- Below content is automatically populated via pre-commit hook -->
 <!-- BEGIN OVERVIEW HOOK -->
 ## Overview
@@ -111,7 +113,7 @@ You need the following permissions to run this module.
 | <a name="input_cbr_target_service_details"></a> [cbr\_target\_service\_details](#input\_cbr\_target\_service\_details) | Details of the target service for which the rule has to be created. | <pre>list(object({<br/>    target_service_name = string<br/>    target_rg           = optional(string)<br/>    enforcement_mode    = string<br/>    tags                = optional(list(string))<br/>  }))</pre> | `[]` | no |
 | <a name="input_enable_cbr"></a> [enable\_cbr](#input\_enable\_cbr) | Set to true to enable creation of Context Based restrictions (CBR) for services defined in var.cbr\_target\_service\_details. When true, var.zone\_vpc\_crn\_list and var.zone\_service\_ref\_list must be provided to create and attach the required CBR zones. When false, no CBR zones or rules are created. | `bool` | `true` | no |
 | <a name="input_prefix"></a> [prefix](#input\_prefix) | Prefix for new CBR zones and rules. | `string` | `null` | no |
-| <a name="input_service_map"></a> [service\_map](#input\_service\_map) | Map of unique service pairs and their authorization config. | <pre>map(object({<br/>    source_service_name         = string<br/>    target_service_name         = string<br/>    roles                       = list(string)<br/>    description                 = optional(string, null)<br/>    source_service_account_id   = optional(string, null)<br/>    source_resource_instance_id = optional(string, null)<br/>    target_resource_instance_id = optional(string, null)<br/>    source_resource_group_id    = optional(string, null)<br/>    target_resource_group_id    = optional(string, null)<br/>  }))</pre> | `{}` | no |
+| <a name="input_service_map"></a> [service\_map](#input\_service\_map) | Map of unique service pairs and their authorization config. [Learn more](https://github.com/terraform-ibm-modules/terraform-ibm-s2s-auth/tree/main/solutions/fully-configurable/DA-complex-input-variables.md#service-map) | <pre>map(object({<br/>    source_service_name         = string<br/>    target_service_name         = string<br/>    roles                       = list(string)<br/>    description                 = optional(string, null)<br/>    source_service_account_id   = optional(string, null)<br/>    source_resource_instance_id = optional(string, null)<br/>    target_resource_instance_id = optional(string, null)<br/>    source_resource_group_id    = optional(string, null)<br/>    target_resource_group_id    = optional(string, null)<br/>  }))</pre> | `{}` | no |
 | <a name="input_zone_service_ref_list"></a> [zone\_service\_ref\_list](#input\_zone\_service\_ref\_list) | Service reference for the zone creation. | <pre>map(object({<br/>    service_ref_location = optional(list(string), [])<br/>  }))</pre> | `{}` | no |
 | <a name="input_zone_vpc_crn_list"></a> [zone\_vpc\_crn\_list](#input\_zone\_vpc\_crn\_list) | CRN of the VPC for the zones. | `list(string)` | `[]` | no |
 

ibm_catalog.json

@@ -51,6 +51,7 @@
             },
             {
               "key": "service_map",
+              "required": true,
               "custom_config": {
                 "type": "code_editor"
               }

solutions/fully-configurable/solutions/fully-configurable/DA-complex-input-variables.md

@@ -0,0 +1,78 @@
+# Configuring complex inputs for Service to Service Authoirsation in IBM Cloud projects
+
+The `service_map` input variable use complex object type. You need to specify this input variable when you configure deployable architecture.
+
+* [Service Map](#service-map) (`service_map`)
+
+## Service Map <a name="service-map"></a>
+
+The `service_map` input variable allows you to define service to service authorisation policy between services in same or different account.
+
+- Variable name: `service_map`
+- Type: A map of objects, where the key is a unique attribute to describe the authorisation policy
+- Default value: An empty map (`{}`)
+
+### Options for service_map
+- `source_service_name` (required): The name of the service requesting the access (or needing the access)
+
+- `target_service_name` (required): The name of the service that the source service wants to access or communicate with.
+
+- `roles` (required): A list of roles or permissions granted from the source service to the target service. These roles define the scope and level of access allowed.
+
+- `description` (optional): A description providing additional context or the purpose of the authorization policy
+
+- `source_service_account_id` (optional): The cloud account ID where the source service resides. This is important when the source and target services belong to different accounts.
+
+- `source_resource_instance_id` (optional): The unique identifier(GUID) for a specific resource instance of the source service. This is mutually exclusive with `source_resource_group_id` and identifies the granular resource for access control.
+
+- `target_resource_instance_id` (optional): The unique identifier(GUID) for the target service. This gives fine-grained control over the target resource. It is mutually exclusive with `target_resource_group_id`.
+
+- `source_resource_group_id` (optional): The resource group ID containing the source service instances. This is an alternative to `source_resource_instance_id` to specify a group-level scope. Cannot be used at the same time as `source_resource_instance_id`.
+
+- `target_resource_group_id` (optional): The resource group ID for the target service. Allows specifying a group-level target rather than an individual resource instance. Mutually exclusive with `target_resource_instance_id`.
+
+### Points to note
+
+- You must provide either `source_resource_instance_id` or `source_resource_group_id` but not both.
+- Similarly, only one of `target_resource_instance_id` or `target_resource_group_id` should be provided to avoid conflicts in target scope definition.
+
+### Example Service Map Configuration
+
+#### Cross Account s2s Authorisation Policy
+
+```hcl
+service_map = {
+  "cross-account-policy" = {
+    source_service_name         = "toolchain"
+    target_service_name         = "secrets-manager"
+    roles                       = ["Viewer"]
+    description                 = "Toolchain in account A can view to secrets manager in account B."
+    source_service_account_id   = "acct-id-123456"
+    source_resource_instance_id = "be19xxxxxxxx3ea90c7d"
+    target_resource_instance_id = "abcd12xxxxxxxxe21fgh"
+    source_resource_group_id    = null
+    target_resource_group_id    = null
+  }
+}
+```
+
+#### Single Resource Instance to whole Resource Group
+
+Authorize one resource instance to access all resources of service "secrets-manager" within a target resource group
+
+```hcl
+service_map = {
+  "instance-to-group-policy" = {
+    source_service_name         = "toolchain"
+    target_service_name         = "secrets-manager"
+    roles                       = ["Viewer"]
+    description                 = "Toolchain instance needs read access to all storage resources in dev group."
+    source_resource_instance_id = "be19xxxxxxxx3ea90c7d"
+    target_resource_instance_id = null
+    source_resource_group_id    = null
+    target_resource_group_id    = "example-resource-group"
+  }
+}
+```
+
+For more information, refer to the [IBM Cloud Service to Service Authorisation documentation](https://cloud.ibm.com/docs/account?topic=account-serviceauth&interface=ui) and the [IBM Cloud Terraform Provider documentation for Authorisation Policy](https://registry.terraform.io/providers/IBM-Cloud/ibm/latest/docs/resources/iam_authorization_policy).

variables.tf

@@ -9,7 +9,7 @@ variable "prefix" {
 }
 
 variable "service_map" {
-  description = "Map of unique service pairs and their authorization config."
+  description = "Map of unique service pairs and their authorization config. [Learn more](https://github.com/terraform-ibm-modules/terraform-ibm-s2s-auth/tree/main/solutions/fully-configurable/DA-complex-input-variables.md#service-map)"
   type = map(object({
     source_service_name         = string
     target_service_name         = string