Merge branch 'jfarmiloe-tf-troubleshoot' into 'master'

Add troubleshooting section for missing group_share resources

See merge request gitlab-org/gitlab!64968

doc/user/infrastructure/index.md

@@ -89,7 +89,7 @@ tools or rely on 3rd party solutions to streamline their IaC workflows.
 
 Read more on setting up and [using the merge request integrations](mr_integration.md).
 
-## The GitLab terraform provider
+## The GitLab Terraform provider
 
 WARNING:
 The GitLab Terraform provider is released separately from GitLab.
@@ -105,3 +105,35 @@ is available as part of the official Terraform provider documentations.
 ## Create a new cluster through IaC
 
 Learn how to [create a new cluster on Google Kubernetes Engine (GKE)](clusters/connect/new_gke_cluster.md).
+
+## Troubleshooting
+
+### `gitlab_group_share_group` resources not detected when subgroup state is refreshed
+
+The GitLab Terraform provider can fail to detect existing `gitlab_group_share_group` resources
+due to the issue ["User with permissions cannot retrieve `share_with_groups` from the API"](https://gitlab.com/gitlab-org/gitlab/-/issues/328428).
+This results in an error when running `terraform apply` because Terraform attempts to recreate an
+existing resource. 
+
+For example, consider the following group/subgroup configuration:
+
+```plaintext
+parent-group
+├── subgroup-A
+└── subgroup-B
+```
+
+Where:
+
+- User `user-1` creates `parent-group`, `subgroup-A`, and `subgroup-B`.
+- `subgroup-A` is shared with `subgroup-B`.
+- User `terraform-user` is member of `parent-group` with inherited `owner` access to both subgroups.
+
+When the Terraform state is refreshed, the API query `GET /groups/:subgroup-A_id` issued by the provider does not return the
+details of `subgroup-B` in the `shared_with_groups` array. This leads to the error.
+
+To workaround this issue, make sure to apply one of the following conditions:
+
+1. The `terraform-user` creates all subgroup resources.
+1. Grant Maintainer or Owner role to the `terraform-user` user on `subgroup-B`.
+1. The `terraform-user` inherited access to `subgroup-B` and `subgroup-B` contains at least one project.