Add latest changes from gitlab-org/gitlab@14-1-stable-eev14.1.0-rc42

1 files changed, 39 insertions, 3 deletions

diff --git a/doc/user/infrastructure/index.md b/doc/user/infrastructure/index.md
index 05ffab93f85..bdaae4b8225 100644
--- a/doc/user/infrastructure/index.md
+++ b/doc/user/infrastructure/index.md
@@ -16,7 +16,7 @@ GitLab, and support Terraform best practices.
 ## Quick Start
 
 Use the following `.gitlab-ci.yml` to set up a basic Terraform project integration
-for GitLab versions 13.5 and later:
+for GitLab versions 14.0 and later:
 
 ```yaml
 include:
@@ -38,7 +38,7 @@ This template includes some opinionated decisions, which you can override:
 - Creating [four pipeline stages](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Terraform.gitlab-ci.yml):
   `init`, `validate`, `build`, and `deploy`. These stages
   [run the Terraform commands](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Terraform/Base.gitlab-ci.yml)
-  `init`, `validate`, `plan`, `plan-json`, and `apply`. The `apply` command only runs on `master`.
+  `init`, `validate`, `plan`, `plan-json`, and `apply`. The `apply` command only runs on the default branch.
 
 This video from January 2021 walks you through all the GitLab Terraform integration features:
 
@@ -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.
@@ -101,3 +101,39 @@ owned by GitLab, where everyone can contribute.
 
 The [documentation of the provider](https://registry.terraform.io/providers/gitlabhq/gitlab/latest/docs)
 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.