Create backlinks and forward links in GCP dynamic adapters (#2807)

# Add Bidirectional Hierarchical Linking for GCP Resources

## Overview

This PR implements comprehensive support for bidirectional linking
between hierarchical GCP resources (parent-child relationships). It
enables automatic discovery of relationships in both directions:
- **Backlinks:** Child resources can link to their parent (e.g.,
Database → Instance)
- **Forward links:** Parent resources can discover all their children
(e.g., Instance → All Databases)

## Key Changes

### 1. Framework Enhancement

**File:** `sources/gcp/shared/linker.go`

Added `IsParentToChild` flag support to enable parent-to-child forward
linking:
- Detects the `IsParentToChild` flag on blast propagation impacts
- Automatically removes the last unique attribute key (child identifier)
when creating forward links
- Changes query method from GET to SEARCH to discover all child
resources
- Fixes variable shadowing for regional/zonal scope handling

**Example:** A Spanner Instance can now link to all its databases using
SEARCH with just the instance name, without needing to know specific
database names.

### 2. Backlinks Implemented (Child → Parent via GET)

Uses the `name` field to extract parent identifiers from hierarchical
resource names:

- **BigTableAdminCluster** → BigTableAdminInstance
- **ContainerNodePool** → ContainerCluster
- **SpannerBackup** → SpannerInstance
- **SpannerDatabase** → SpannerInstance _(initial implementation)_

**How it works:** The framework extracts the parent identifier from the
child's name (e.g., `projects/p/instances/i/databases/d` → extracts `i`)
and creates a GET query to the parent resource.

### 3. Forward Links Implemented (Parent → Child via SEARCH)

Uses the `IsParentToChild: true` flag to create SEARCH queries that
discover all children:

- **BigTableAdminInstance** → BigTableAdminCluster
- **ArtifactRegistryRepository** → ArtifactRegistryDockerImage
- **ContainerCluster** → ContainerNodePool
- **RunService** → RunRevision
- **SpannerInstance** → SpannerDatabase
- **SQLAdminInstance** → SQLAdminBackupRun

**How it works:** The framework uses the parent's name to create a
SEARCH query that returns all child resources belonging to that parent.

### 4. Documentation

**File:**
`sources/gcp/dynamic/adapters/.cursor/rules/dynamic-adapter-creation.mdc`

Added comprehensive documentation (143 lines) covering:

#### Backlink Pattern
- Concept explanation and use cases
- Complete code example using Spanner Database → Instance
- Step-by-step framework behavior breakdown
- Test patterns for verification
- Guidelines on when to use this pattern

#### Forward Link Pattern
- Concept explanation and use cases
- Complete code example using Spanner Instance → Databases
- Framework behavior with `IsParentToChild` flag
- Critical requirements (child must support SEARCH)
- Test patterns for verification
- Comparison table: Backlink vs Forward Link

### 5. Tests Updated

- `big-table-admin-cluster_test.go`: Added backlink test case
- `spanner-instance_test.go`: Added forward link test case

## Validation

✅ All tests passing: `go test -race ./sources/gcp/... -v -timeout 5m`
✅ Linting clean: `golangci-lint run ./sources/gcp/... --timeout 5m`

## Impact

This PR enables complete bidirectional relationship discovery for
hierarchical GCP resources, improving:
- **Dependency tracking:** Understanding which children depend on a
parent
- **Impact analysis:** Discovering all resources affected by parent
changes
- **Infrastructure visualization:** Building complete resource graphs
with parent-child relationships

---

Would you like me to make any adjustments to this PR description?

---------

Co-authored-by: carabasdaniel <[email protected]>
GitOrigin-RevId: c8d839894d83a800f8c5d9f75019e59847bdc920

Author: 2 people

sources/gcp/dynamic/adapter_test.go

@@ -842,6 +842,17 @@ func TestAdapter(t *testing.T) {
 							Out: false,
 						},
 					},
+					{
+						// name field creates a backlink to the Spanner instance
+						ExpectedType:   gcpshared.SpannerInstance.String(),
+						ExpectedMethod: sdp.QueryMethod_GET,
+						ExpectedQuery:  instanceName,
+						ExpectedScope:  projectID,
+						ExpectedBlastPropagation: &sdp.BlastPropagation{
+							In:  true,
+							Out: false,
+						},
+					},
 				}
 
 				shared.RunStaticTests(t, adapter, sdpItem, queryTests)

sources/gcp/dynamic/adapters/.cursor/rules/dynamic-adapter-creation.mdc

@@ -179,6 +179,151 @@ blastPropagation: map[string]*gcpshared.Impact{
 - **If no adapter exists**: Create the SDP item type definition in `sources/gcp/shared/item-types.go` and `models.go` as if the adapter exists, then link to it
 - **Follow naming**: `gcp-<api>-<resource>` for new adapter types
 
+#### Creating Backlinks from Child to Parent Resources
+
+When a resource name contains hierarchical information (e.g., a database name includes its parent instance), you can create a backlink using the `name` field. The framework will automatically extract the parent resource identifier and create the appropriate linked item query.
+
+**Use Case**: Child resources that reference their parent in their name structure.
+
+**Example: Spanner Database to Instance Backlink**
+
+A Spanner database name has the format: `projects/{project}/instances/{instance}/databases/{database}`
+
+To create a backlink from the database to its parent instance:
+
+```go
+// In sources/gcp/shared/blast-propagations.go
+SpannerDatabase: {
+    // ... other blast propagations ...
+
+    // This is a backlink to instance.
+    // Framework will extract the instance name and create the linked item query with GET
+    "name": {
+        Description:      "If the Spanner Instance is deleted or updated: The Database may become invalid or inaccessible. If the Database is updated: The instance remains unaffected.",
+        ToSDPItemType:    SpannerInstance,
+        BlastPropagation: impactInOnly,
+    },
+}
+```
+
+**How It Works:**
+1. The framework reads the `name` field value (e.g., `projects/my-project/instances/test-instance/databases/my-db`)
+2. It extracts the parent instance identifier (`test-instance`)
+3. It creates a GET query for the parent SpannerInstance
+4. The linked item query will have:
+   - Type: `gcp-spanner-instance`
+   - Method: GET
+   - Query: `test-instance` (extracted from database name)
+   - Scope: Same project as the database
+
+**Testing the Backlink:**
+
+When adding backlink blast propagations, verify they work correctly in tests:
+
+```go
+// In adapter_test.go
+{
+    // name field creates a backlink to the Spanner instance
+    ExpectedType:   gcpshared.SpannerInstance.String(),
+    ExpectedMethod: sdp.QueryMethod_GET,
+    ExpectedQuery:  instanceName,
+    ExpectedScope:  projectID,
+    ExpectedBlastPropagation: &sdp.BlastPropagation{
+        In:  true,
+        Out: false,
+    },
+}
+```
+
+**When to Use This Pattern:**
+- Child resources with hierarchical naming (database → instance, subnet → network)
+- Parent resource is part of the child's name/path
+- Relationship is one-way (child depends on parent, but parent doesn't depend on specific child)
+- Use `impactInOnly` blast propagation (parent changes affect child, but not vice versa)
+
+#### Creating Forward Links from Parent to Child Resources
+
+When a parent resource needs to link to all its child resources, you can use the `IsParentToChild` flag to create a forward link using SEARCH. This is the inverse pattern of the backlink described above.
+
+**Use Case**: Parent resources that need to discover and link to all their child resources (e.g., instance → all databases).
+
+**Example: Spanner Instance to Databases Forward Link**
+
+A Spanner instance needs to link to all databases that belong to it. Since the instance doesn't have the database names, we use SEARCH to find all databases for that instance.
+
+To create a forward link from the instance to its databases:
+
+```go
+// In the adapter file (e.g., spanner-instance.go)
+var spannerInstanceAdapter = registerableAdapter{
+    // ... other fields ...
+
+    blastPropagation: map[string]*gcpshared.Impact{
+        // This a link from parent to child via SEARCH
+        // We need to make sure that the linked item supports `SEARCH` method for the `instance` name.
+        "name": {
+            ToSDPItemType: gcpshared.SpannerDatabase,
+            Description:   "If the Spanner Instance is deleted or updated: All associated databases may become invalid or inaccessible. If a database is updated: The instance remains unaffected.",
+            BlastPropagation: &sdp.BlastPropagation{
+                In: false,
+                Out: true,
+            },
+            IsParentToChild: true,
+        },
+    },
+}
+```
+
+**How It Works:**
+1. The framework detects `IsParentToChild: true` on the blast propagation
+2. It modifies the unique attribute keys by removing the last element (the child identifier)
+   - For databases: `["instances", "databases"]` becomes `["instances"]`
+3. It extracts only the parent identifier from the resource name (e.g., `test-instance`)
+4. It creates a SEARCH query (not GET) to find all child resources
+5. The linked item query will have:
+   - Type: `gcp-spanner-database`
+   - Method: SEARCH
+   - Query: `test-instance` (the instance name)
+   - Scope: Same project as the instance
+
+**Testing the Forward Link:**
+
+When adding parent-to-child blast propagations, verify they work correctly in tests:
+
+```go
+// In adapter_test.go (e.g., spanner-instance_test.go)
+{
+    ExpectedType:   gcpshared.SpannerDatabase.String(),
+    ExpectedMethod: sdp.QueryMethod_SEARCH,
+    ExpectedQuery:  instanceName,
+    ExpectedScope:  projectID,
+    ExpectedBlastPropagation: &sdp.BlastPropagation{
+        In: false,
+        Out: true,
+    },
+}
+```
+
+**Critical Requirements:**
+- **Child adapter must support SEARCH**: The child resource type must implement the SEARCH method
+- **Query parameter must match**: The child's SEARCH method must accept the parent identifier as a search parameter
+- **Set `IsParentToChild: true`**: This flag triggers the special SEARCH behavior
+
+**When to Use This Pattern:**
+- Parent resources that need to discover all their children (instance → databases, network → subnets)
+- The parent's name/identifier is sufficient to search for children
+- The child adapter supports SEARCH method
+
+**Comparison: Backlink vs Forward Link**
+
+| Aspect | Backlink (Child → Parent) | Forward Link (Parent → Child) |
+|--------|---------------------------|------------------------------|
+| Direction | Child points to parent | Parent discovers children |
+| Method | GET | SEARCH |
+| Flag | No special flag | `IsParentToChild: true` |
+| Use Case | Database → Instance | Instance → All Databases |
+| Query | Single parent identifier | Parent identifier searches all children |
+
 ### 6. Special Considerations
 
 #### NameSelector

sources/gcp/dynamic/adapters/artifact-registry-repository.go

@@ -23,6 +23,17 @@ var artifactRegistryRepositoryAdapter = registerableAdapter{ //nolint:unused
 	},
 	blastPropagation: map[string]*gcpshared.Impact{
 		"kmsKeyName": gcpshared.CryptoKeyImpactInOnly,
+		// Forward link from parent to child via SEARCH
+		// Link to all docker images in this repository
+		"name": {
+			ToSDPItemType: gcpshared.ArtifactRegistryDockerImage,
+			Description:   "If the Artifact Registry Repository is deleted or updated: All associated Docker Images may become invalid or inaccessible. If a Docker Image is updated: The repository remains unaffected.",
+			BlastPropagation: &sdp.BlastPropagation{
+			    In: false,
+				Out: true,
+			},
+			IsParentToChild: true,
+		},
 	},
 	terraformMapping: gcpshared.TerraformMapping{
 		Reference:   "https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/artifact_registry_repository#attributes-reference",

sources/gcp/dynamic/adapters/big-table-admin-cluster.go

@@ -24,6 +24,18 @@ var bigTableAdminClusterAdapter = registerableAdapter{ //nolint:unused
 	blastPropagation: map[string]*gcpshared.Impact{
 		// Customer-managed encryption key protecting data in this cluster.
 		"encryptionConfig.kmsKeyName": gcpshared.CryptoKeyImpactInOnly,
+		// This is a backlink to instance.
+		// Framework will extract the instance name and create the linked item query with GET
+		// NOTE: We prioritize the backlink over a forward link to BigTableAdminBackup
+		// because the backlink is more critical for understanding the cluster's dependencies.
+		"name": {
+			ToSDPItemType: gcpshared.BigTableAdminInstance,
+			Description:   "If the BigTableAdmin Instance is deleted or updated: The Cluster may become invalid or inaccessible. If the Cluster is updated: The instance remains unaffected.",
+			BlastPropagation: &sdp.BlastPropagation{
+				In:  true,
+				Out: false,
+			},
+		},
 	},
 	// No Terraform mapping
 }.Register()

sources/gcp/dynamic/adapters/big-table-admin-cluster_test.go

@@ -176,6 +176,17 @@ func TestBigTableAdminCluster(t *testing.T) {
 						Out: false,
 					},
 				},
+				{
+					// name field creates a backlink to the BigTable instance
+					ExpectedType:   gcpshared.BigTableAdminInstance.String(),
+					ExpectedMethod: sdp.QueryMethod_GET,
+					ExpectedQuery:  instanceName,
+					ExpectedScope:  projectID,
+					ExpectedBlastPropagation: &sdp.BlastPropagation{
+						In:  true,
+						Out: false,
+					},
+				},
 			}
 
 			shared.RunStaticTests(t, adapter, sdpItem, queryTests)

sources/gcp/dynamic/adapters/big-table-admin-instance.go

@@ -21,8 +21,19 @@ var bigTableAdminInstanceAdapter = registerableAdapter{ //nolint:unused
 		// TODO: https://linear.app/overmind/issue/ENG-631/investigate-how-we-can-add-health-status-for-supporting-items
 		// state: https://cloud.google.com/bigtable/docs/reference/admin/rest/v2/projects.instances#State
 	},
-	// The Bigtable Instance does not contain any fields that would cause blast propagation.
-	blastPropagation: map[string]*gcpshared.Impact{},
+	blastPropagation: map[string]*gcpshared.Impact{
+		// Forward link from parent to child via SEARCH
+		// Link to all clusters in this instance (most fundamental infrastructure component)
+		"name": {
+			ToSDPItemType: gcpshared.BigTableAdminCluster,
+			Description:   "If the BigTableAdmin Instance is deleted or updated: All associated Clusters may become invalid or inaccessible. If a Cluster is updated: The instance remains unaffected.",
+			BlastPropagation: &sdp.BlastPropagation{
+			    In: false,
+				Out: true,
+			},
+			IsParentToChild: true,
+		},
+	},
 	terraformMapping: gcpshared.TerraformMapping{
 		Reference: "https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/bigtable_instance",
 		Mappings: []*sdp.TerraformMapping{

sources/gcp/dynamic/adapters/container-cluster.go

@@ -51,6 +51,17 @@ var _ = registerableAdapter{
 		"userManagedKeysConfig.serviceAccountVerificationKeys": gcpshared.CryptoKeyVersionImpactInOnly,
 		"userManagedKeysConfig.controlPlaneDiskEncryptionKey":  gcpshared.CryptoKeyImpactInOnly,
 		"userManagedKeysConfig.gkeopsEtcdBackupEncryptionKey":  gcpshared.CryptoKeyImpactInOnly,
+		// Forward link from parent to child via SEARCH
+		// Link to all node pools in this cluster
+		"name": {
+			ToSDPItemType:    gcpshared.ContainerNodePool,
+			Description:      "If the Container Cluster is deleted or updated: All associated Node Pools may become invalid or inaccessible. If a Node Pool is updated: The cluster remains unaffected.",
+			BlastPropagation: &sdp.BlastPropagation{
+			  In: false,
+			  Out: true,
+			 },
+			IsParentToChild:  true,
+		},
 	},
 	terraformMapping: gcpshared.TerraformMapping{
 		Reference:   "https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/container_cluster",

sources/gcp/dynamic/adapters/container-node-pool.go

@@ -36,6 +36,13 @@ var containerNodePoolAdapter = registerableAdapter{ //nolint:unused
 		// https://cloud.google.com/kubernetes-engine/docs/reference/rest/v1/projects.locations.clusters.nodePools#NodePool.Status
 	},
 	blastPropagation: map[string]*gcpshared.Impact{
+		// This is a backlink to cluster.
+		// Framework will extract the cluster name and create the linked item query with GET
+		"name": {
+			ToSDPItemType:    gcpshared.ContainerCluster,
+			Description:      "If the Container Cluster is deleted or updated: The Node Pool may become invalid or inaccessible. If the Node Pool is updated: The cluster remains unaffected.",
+			BlastPropagation: gcpshared.ImpactInOnly,
+		},
 		"config.bootDiskKmsKey": gcpshared.CryptoKeyImpactInOnly,
 		"config.serviceAccount": gcpshared.IAMServiceAccountImpactInOnly,
 		"config.nodeGroup": {

sources/gcp/dynamic/adapters/run-service.go

@@ -87,6 +87,17 @@ var _ = registerableAdapter{
 			Description:      "If the Cloud Run Service is deleted or updated: Traffic allocation to revisions will be lost. If revisions are updated: The service traffic configuration may need updates.",
 			BlastPropagation: &sdp.BlastPropagation{Out: true},
 		},
+		// Forward link from parent to child via SEARCH
+		// Link to all revisions in this service
+		"name": {
+			ToSDPItemType:    gcpshared.RunRevision,
+			Description:      "If the Cloud Run Service is deleted or updated: All associated Revisions may become invalid or inaccessible. If a Revision is updated: The service remains unaffected.",
+			BlastPropagation: &sdp.BlastPropagation{
+			  In:false,
+			  Out: true,
+			},
+			IsParentToChild:  true,
+		},
 	},
 	terraformMapping: gcpshared.TerraformMapping{
 		Reference:   "https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/cloud_run_v2_service",

sources/gcp/dynamic/adapters/spanner-instance.go

@@ -31,6 +31,17 @@ var spannerInstanceAdapter = registerableAdapter{ //nolint:unused
 				Out: false,
 			},
 		},
+		// This is a link from parent to child via SEARCH
+		// We need to make sure that the linked item supports `SEARCH` method for the `instance` name.
+		"name": {
+			ToSDPItemType: gcpshared.SpannerDatabase,
+			Description:   "If the Spanner Instance is deleted or updated: All associated databases may become invalid or inaccessible. If a database is updated: The instance remains unaffected.",
+			BlastPropagation: &sdp.BlastPropagation{
+			    In: false,
+				Out: true,
+			},
+			IsParentToChild: true,
+		},
 	},
 	terraformMapping: gcpshared.TerraformMapping{
 		Reference: "https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/spanner_instance",