Add latest changes from gitlab-org/gitlab@master

7 files changed, 230 insertions, 221 deletions

diff --git a/doc/administration/clusters/kas.md b/doc/administration/clusters/kas.md
index ba0d7280b74..192b636e246 100644
--- a/doc/administration/clusters/kas.md
+++ b/doc/administration/clusters/kas.md
@@ -4,13 +4,15 @@ group: Configure
 info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
 ---
 
-# Install the GitLab Agent Server (KAS) **(FREE SELF)**
+# Install the GitLab Agent Server for Kubernetes (KAS) **(FREE SELF)**
 
 > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3834) in GitLab 13.10, the GitLab Agent Server (KAS) became available on GitLab.com under `wss://kas.gitlab.com`.
-> [Moved](https://gitlab.com/groups/gitlab-org/-/epics/6290) from GitLab Premium to GitLab Free in 14.5.
+> - [Moved](https://gitlab.com/groups/gitlab-org/-/epics/6290) from GitLab Premium to GitLab Free in 14.5.
 
-The GitLab Agent Server (KAS) is a GitLab backend service dedicated to
-managing the [GitLab Agent](../../user/clusters/agent/index.md).
+The GitLab Agent Server for Kubernetes is a GitLab backend service dedicated to
+managing the [GitLab Agent for Kubernetes](../../user/clusters/agent/index.md).
+
+The KAS acronym refers to the former name, Kubernetes Agent Server.
 
 The KAS is already installed and available in GitLab.com under `wss://kas.gitlab.com`.
 This document describes how to install a KAS for GitLab self-managed instances.
@@ -94,8 +96,8 @@ For GitLab instances installed through Omnibus packages:
 
 ## Troubleshooting
 
-If you face any issues with KAS, you can read the service logs
-with the following command:
+If you have issues while using the GitLab Agent Server for Kubernetes, view the
+service logs by running the following command:
 
 ```shell
 kubectl logs -f -l=app=kas -n <YOUR-GITLAB-NAMESPACE>
@@ -103,8 +105,7 @@ kubectl logs -f -l=app=kas -n <YOUR-GITLAB-NAMESPACE>
 
 In Omnibus GitLab, find the logs in `/var/log/gitlab/gitlab-kas/`.
 
-See also the [user documentation](../../user/clusters/agent/index.md#troubleshooting)
-for troubleshooting problems with individual agents.
+You can also [troubleshoot issues with individual Agents](../../user/clusters/agent/troubleshooting.md).
 
 ### KAS logs - GitOps: failed to get project information
 
diff --git a/doc/administration/monitoring/prometheus/gitlab_metrics.md b/doc/administration/monitoring/prometheus/gitlab_metrics.md
index ced0ff310d0..d94c3cdefbf 100644
--- a/doc/administration/monitoring/prometheus/gitlab_metrics.md
+++ b/doc/administration/monitoring/prometheus/gitlab_metrics.md
@@ -48,6 +48,7 @@ The following metrics are available:
 | `gitlab_database_transaction_seconds`                            | Histogram   | 12.1    | Time spent in database transactions, in seconds                                                                       |                                                           |
 | `gitlab_method_call_duration_seconds`                            | Histogram   | 10.2    | Method calls real duration                                                                                            | `controller`, `action`, `module`, `method`                |
 | `gitlab_page_out_of_bounds`                                      | Counter     | 12.8    | Counter for the PageLimiter pagination limit being hit                                                                | `controller`, `action`, `bot`                             |
+| `gitlab_rails_boot_time_seconds`                                 | Gauge       | 14.8    | Time elapsed for Rails primary process to finish startup                                               |                                                           |
 | `gitlab_rails_queue_duration_seconds`                            | Histogram   | 9.4     | Measures latency between GitLab Workhorse forwarding a request to Rails                                               |                                                           |
 | `gitlab_sql_duration_seconds`                                    | Histogram   | 10.2    | SQL execution time, excluding `SCHEMA` operations and `BEGIN` / `COMMIT`                                              |                                                           |
 | `gitlab_sql_<role>_duration_seconds`                             | Histogram   | 13.10   | SQL execution time, excluding `SCHEMA` operations and `BEGIN` / `COMMIT`, grouped by database roles (primary/replica) |                                                           |
diff --git a/doc/user/clusters/agent/index.md b/doc/user/clusters/agent/index.md
index f85ca5aac8d..eeeb7168267 100644
--- a/doc/user/clusters/agent/index.md
+++ b/doc/user/clusters/agent/index.md
@@ -205,191 +205,6 @@ For self-managed GitLab instances, go to `https://gitlab.example.com/-/graphql-e
 
 Find out how to [migrate to the GitLab Agent for Kubernetes](../../infrastructure/clusters/migrate_to_gitlab_agent.md) from the certificate-based integration depending on the features you use.
 
-## Troubleshooting
+## Related topics
 
-If you face any issues while using the Agent, read the
-service logs with the following command:
-
-```shell
-kubectl logs -f -l=app=gitlab-kubernetes-agent -n gitlab-kubernetes-agent
-```
-
-GitLab administrators can additionally view the [GitLab Agent Server logs](../../../administration/clusters/kas.md#troubleshooting).
-
-### Agent logs
-
-#### Transport: Error while dialing failed to WebSocket dial
-
-```json
-{
-  "level": "warn",
-  "time": "2020-11-04T10:14:39.368Z",
-  "msg": "GetConfiguration failed",
-  "error": "rpc error: code = Unavailable desc = connection error: desc = \"transport: Error while dialing failed to WebSocket dial: failed to send handshake request: Get \\\"https://gitlab-kas:443/-/kubernetes-agent\\\": dial tcp: lookup gitlab-kas on 10.60.0.10:53: no such host\""
-}
-```
-
-This error is shown if there are some connectivity issues between the address
-specified as `kas-address`, and your Agent pod. To fix it, make sure that you
-specified the `kas-address` correctly.
-
-```json
-{
-  "level": "error",
-  "time": "2021-06-25T21:15:45.335Z",
-  "msg": "Reverse tunnel",
-  "mod_name": "reverse_tunnel",
-  "error": "Connect(): rpc error: code = Unavailable desc = connection error: desc= \"transport: Error while dialing failed to WebSocket dial: expected handshake response status code 101 but got 301\""
-}
-```
-
-This error occurs if the `kas-address` doesn't include a trailing slash. To fix it, make sure that the
-`wss` or `ws` URL ends with a trailing slash, such as `wss://GitLab.host.tld:443/-/kubernetes-agent/`
-or `ws://GitLab.host.tld:80/-/kubernetes-agent/`.
-
-#### ValidationError(Deployment.metadata)
-
-```json
-{
-  "level": "info",
-  "time": "2020-10-30T08:56:54.329Z",
-  "msg": "Synced",
-  "project_id": "root/kas-manifest001",
-  "resource_key": "apps/Deployment/kas-test001/nginx-deployment",
-  "sync_result": "error validating data: [ValidationError(Deployment.metadata): unknown field \"replicas\" in io.k8s.apimachinery.pkg.apis.meta.v1.ObjectMeta, ValidationError(Deployment.metadata): unknown field \"selector\" in io.k8s.apimachinery.pkg.apis.meta.v1.ObjectMeta, ValidationError(Deployment.metadata): unknown field \"template\" in io.k8s.apimachinery.pkg.apis.meta.v1.ObjectMeta]"
-}
-```
-
-This error is shown if a manifest file is malformed, and Kubernetes can't
-create specified objects. Make sure that your manifest files are valid. You
-may try using them to create objects in Kubernetes directly for more troubleshooting.
-
-#### Error while dialing failed to WebSocket dial: failed to send handshake request
-
-```json
-{
-  "level": "warn",
-  "time": "2020-10-30T09:50:51.173Z",
-  "msg": "GetConfiguration failed",
-  "error": "rpc error: code = Unavailable desc = connection error: desc = \"transport: Error while dialing failed to WebSocket dial: failed to send handshake request: Get \\\"https://GitLabhost.tld:443/-/kubernetes-agent\\\": net/http: HTTP/1.x transport connection broken: malformed HTTP response \\\"\\\\x00\\\\x00\\\\x06\\\\x04\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x05\\\\x00\\\\x00@\\\\x00\\\"\""
-}
-```
-
-This error is shown if you configured `wss` as `kas-address` on the agent side,
-but KAS on the server side is not available via `wss`. To fix it, make sure the
-same schemes are configured on both sides.
-
-It's not possible to set the `grpc` scheme due to the issue
-[It is not possible to configure KAS to work with `grpc` without directly editing GitLab KAS deployment](https://gitlab.com/gitlab-org/gitlab/-/issues/276888). To use `grpc` while the
-issue is in progress, directly edit the deployment with the
-`kubectl edit deployment gitlab-kas` command, and change `--listen-websocket=true` to `--listen-websocket=false`. After running that command, you should be able to use
-`grpc://gitlab-kas.<YOUR-NAMESPACE>:8150`.
-
-#### Decompressor is not installed for grpc-encoding
-
-```json
-{
-  "level": "warn",
-  "time": "2020-11-05T05:25:46.916Z",
-  "msg": "GetConfiguration.Recv failed",
-  "error": "rpc error: code = Unimplemented desc = grpc: Decompressor is not installed for grpc-encoding \"gzip\""
-}
-```
-
-This error is shown if the version of the agent is newer that the version of KAS.
-To fix it, make sure that both `agentk` and KAS use the same versions.
-
-#### Certificate signed by unknown authority
-
-```json
-{
-  "level": "error",
-  "time": "2021-02-25T07:22:37.158Z",
-  "msg": "Reverse tunnel",
-  "mod_name": "reverse_tunnel",
-  "error": "Connect(): rpc error: code = Unavailable desc = connection error: desc = \"transport: Error while dialing failed to WebSocket dial: failed to send handshake request: Get \\\"https://GitLabhost.tld:443/-/kubernetes-agent/\\\": x509: certificate signed by unknown authority\""
-}
-```
-
-This error is shown if your GitLab instance is using a certificate signed by an internal CA that
-is unknown to the agent. One approach to fixing it is to present the CA certificate file to the agent
-via a Kubernetes `configmap` and mount the file in the agent `/etc/ssl/certs` directory from where it
-will be picked up automatically.
-
-For example, if your internal CA certificate is `myCA.pem`:
-
-```plaintext
-kubectl -n gitlab-kubernetes-agent create configmap ca-pemstore --from-file=myCA.pem
-```
-
-Then in `resources.yml`:
-
-```yaml
-    spec:
-      serviceAccountName: gitlab-kubernetes-agent
-      containers:
-      - name: agent
-        image: "registry.gitlab.com/gitlab-org/cluster-integration/gitlab-agent/agentk:<version>"
-        args:
-        - --token-file=/config/token
-        - --kas-address
-        - wss://kas.host.tld:443 # replace this line with the line below if using Omnibus GitLab or GitLab.com.
-        # - wss://gitlab.host.tld:443/-/kubernetes-agent/
-        # - wss://kas.gitlab.com # for GitLab.com users, use this KAS.
-        # - grpc://host.docker.internal:8150 # use this attribute when connecting from Docker.
-        volumeMounts:
-        - name: token-volume
-          mountPath: /config
-        - name: ca-pemstore-volume
-          mountPath: /etc/ssl/certs/myCA.pem
-          subPath: myCA.pem
-      volumes:
-      - name: token-volume
-        secret:
-          secretName: gitlab-kubernetes-agent-token
-      - name: ca-pemstore-volume
-        configMap:
-          name: ca-pemstore
-          items:
-          - key: myCA.pem
-            path: myCA.pem
-```
-
-Alternatively, you can mount the certificate file at a different location and include it using the
-`--ca-cert-file` agent parameter:
-
-```yaml
-      containers:
-      - name: agent
-        image: "registry.gitlab.com/gitlab-org/cluster-integration/gitlab-agent/agentk:<version>"
-        args:
-        - --ca-cert-file=/tmp/myCA.pem
-        - --token-file=/config/token
-        - --kas-address
-        - wss://kas.host.tld:443 # replace this line with the line below if using Omnibus GitLab or GitLab.com.
-        # - wss://gitlab.host.tld:443/-/kubernetes-agent/
-        # - wss://kas.gitlab.com # for GitLab.com users, use this KAS.
-        # - grpc://host.docker.internal:8150 # use this attribute when connecting from Docker.
-        volumeMounts:
-        - name: token-volume
-          mountPath: /config
-        - name: ca-pemstore-volume
-          mountPath: /tmp/myCA.pem
-          subPath: myCA.pem
-```
-
-#### Project not found
-
-```json
-{
-  "level ":"error ",
-  "time ":"2022-01-05T15:18:11.331Z",
-  "msg ":"GetObjectsToSynchronize.Recv failed ",
-  "mod_name ":"gitops ",
-  "error ":"rpc error: code = NotFound desc = project not found ",
-}
-```
-
-This error is shown if the manifest project is not public. To fix it,
-[make sure your manifest project is public](repository.md#synchronize-manifest-projects) or your manifest files
-are stored in the Agent's configuration repository.
+- [Troubleshooting](troubleshooting.md)
diff --git a/doc/user/clusters/agent/troubleshooting.md b/doc/user/clusters/agent/troubleshooting.md
new file mode 100644
index 00000000000..d5777267582
--- /dev/null
+++ b/doc/user/clusters/agent/troubleshooting.md
@@ -0,0 +1,193 @@
+---
+stage: Configure
+group: Configure
+info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
+---
+
+# Troubleshooting the GitLab Agent for Kubernetes
+
+When you are using the GitLab Agent for Kubernetes, you might experience issues you need to troubleshoot.
+
+You can start by viewing the service logs:
+
+```shell
+kubectl logs -f -l=app=gitlab-kubernetes-agent -n gitlab-kubernetes-agent
+```
+
+If you are a GitLab administrator, you can also view the [GitLab Agent Server logs](../../../administration/clusters/kas.md#troubleshooting).
+
+## Transport: Error while dialing failed to WebSocket dial
+
+```json
+{
+  "level": "warn",
+  "time": "2020-11-04T10:14:39.368Z",
+  "msg": "GetConfiguration failed",
+  "error": "rpc error: code = Unavailable desc = connection error: desc = \"transport: Error while dialing failed to WebSocket dial: failed to send handshake request: Get \\\"https://gitlab-kas:443/-/kubernetes-agent\\\": dial tcp: lookup gitlab-kas on 10.60.0.10:53: no such host\""
+}
+```
+
+This error is shown if there are some connectivity issues between the address
+specified as `kas-address`, and your Agent pod. To fix it, make sure that you
+specified the `kas-address` correctly.
+
+```json
+{
+  "level": "error",
+  "time": "2021-06-25T21:15:45.335Z",
+  "msg": "Reverse tunnel",
+  "mod_name": "reverse_tunnel",
+  "error": "Connect(): rpc error: code = Unavailable desc = connection error: desc= \"transport: Error while dialing failed to WebSocket dial: expected handshake response status code 101 but got 301\""
+}
+```
+
+This error occurs if the `kas-address` doesn't include a trailing slash. To fix it, make sure that the
+`wss` or `ws` URL ends with a trailing slash, such as `wss://GitLab.host.tld:443/-/kubernetes-agent/`
+or `ws://GitLab.host.tld:80/-/kubernetes-agent/`.
+
+## ValidationError(Deployment.metadata)
+
+```json
+{
+  "level": "info",
+  "time": "2020-10-30T08:56:54.329Z",
+  "msg": "Synced",
+  "project_id": "root/kas-manifest001",
+  "resource_key": "apps/Deployment/kas-test001/nginx-deployment",
+  "sync_result": "error validating data: [ValidationError(Deployment.metadata): unknown field \"replicas\" in io.k8s.apimachinery.pkg.apis.meta.v1.ObjectMeta, ValidationError(Deployment.metadata): unknown field \"selector\" in io.k8s.apimachinery.pkg.apis.meta.v1.ObjectMeta, ValidationError(Deployment.metadata): unknown field \"template\" in io.k8s.apimachinery.pkg.apis.meta.v1.ObjectMeta]"
+}
+```
+
+This error is shown if a manifest file is malformed, and Kubernetes can't
+create specified objects. Make sure that your manifest files are valid. You
+may try using them to create objects in Kubernetes directly for more troubleshooting.
+
+## Error while dialing failed to WebSocket dial: failed to send handshake request
+
+```json
+{
+  "level": "warn",
+  "time": "2020-10-30T09:50:51.173Z",
+  "msg": "GetConfiguration failed",
+  "error": "rpc error: code = Unavailable desc = connection error: desc = \"transport: Error while dialing failed to WebSocket dial: failed to send handshake request: Get \\\"https://GitLabhost.tld:443/-/kubernetes-agent\\\": net/http: HTTP/1.x transport connection broken: malformed HTTP response \\\"\\\\x00\\\\x00\\\\x06\\\\x04\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x05\\\\x00\\\\x00@\\\\x00\\\"\""
+}
+```
+
+This error is shown if you configured `wss` as `kas-address` on the agent side,
+but KAS on the server side is not available via `wss`. To fix it, make sure the
+same schemes are configured on both sides.
+
+It's not possible to set the `grpc` scheme due to the issue
+[It is not possible to configure KAS to work with `grpc` without directly editing GitLab KAS deployment](https://gitlab.com/gitlab-org/gitlab/-/issues/276888). To use `grpc` while the
+issue is in progress, directly edit the deployment with the
+`kubectl edit deployment gitlab-kas` command, and change `--listen-websocket=true` to `--listen-websocket=false`. After running that command, you should be able to use
+`grpc://gitlab-kas.<YOUR-NAMESPACE>:8150`.
+
+## Decompressor is not installed for grpc-encoding
+
+```json
+{
+  "level": "warn",
+  "time": "2020-11-05T05:25:46.916Z",
+  "msg": "GetConfiguration.Recv failed",
+  "error": "rpc error: code = Unimplemented desc = grpc: Decompressor is not installed for grpc-encoding \"gzip\""
+}
+```
+
+This error is shown if the version of the agent is newer that the version of KAS.
+To fix it, make sure that both `agentk` and KAS use the same versions.
+
+## Certificate signed by unknown authority
+
+```json
+{
+  "level": "error",
+  "time": "2021-02-25T07:22:37.158Z",
+  "msg": "Reverse tunnel",
+  "mod_name": "reverse_tunnel",
+  "error": "Connect(): rpc error: code = Unavailable desc = connection error: desc = \"transport: Error while dialing failed to WebSocket dial: failed to send handshake request: Get \\\"https://GitLabhost.tld:443/-/kubernetes-agent/\\\": x509: certificate signed by unknown authority\""
+}
+```
+
+This error is shown if your GitLab instance is using a certificate signed by an internal CA that
+is unknown to the agent. One approach to fixing it is to present the CA certificate file to the agent
+via a Kubernetes `configmap` and mount the file in the agent `/etc/ssl/certs` directory from where it
+will be picked up automatically.
+
+For example, if your internal CA certificate is `myCA.pem`:
+
+```plaintext
+kubectl -n gitlab-kubernetes-agent create configmap ca-pemstore --from-file=myCA.pem
+```
+
+Then in `resources.yml`:
+
+```yaml
+    spec:
+      serviceAccountName: gitlab-kubernetes-agent
+      containers:
+      - name: agent
+        image: "registry.gitlab.com/gitlab-org/cluster-integration/gitlab-agent/agentk:<version>"
+        args:
+        - --token-file=/config/token
+        - --kas-address
+        - wss://kas.host.tld:443 # replace this line with the line below if using Omnibus GitLab or GitLab.com.
+        # - wss://gitlab.host.tld:443/-/kubernetes-agent/
+        # - wss://kas.gitlab.com # for GitLab.com users, use this KAS.
+        # - grpc://host.docker.internal:8150 # use this attribute when connecting from Docker.
+        volumeMounts:
+        - name: token-volume
+          mountPath: /config
+        - name: ca-pemstore-volume
+          mountPath: /etc/ssl/certs/myCA.pem
+          subPath: myCA.pem
+      volumes:
+      - name: token-volume
+        secret:
+          secretName: gitlab-kubernetes-agent-token
+      - name: ca-pemstore-volume
+        configMap:
+          name: ca-pemstore
+          items:
+          - key: myCA.pem
+            path: myCA.pem
+```
+
+Alternatively, you can mount the certificate file at a different location and include it using the
+`--ca-cert-file` agent parameter:
+
+```yaml
+      containers:
+      - name: agent
+        image: "registry.gitlab.com/gitlab-org/cluster-integration/gitlab-agent/agentk:<version>"
+        args:
+        - --ca-cert-file=/tmp/myCA.pem
+        - --token-file=/config/token
+        - --kas-address
+        - wss://kas.host.tld:443 # replace this line with the line below if using Omnibus GitLab or GitLab.com.
+        # - wss://gitlab.host.tld:443/-/kubernetes-agent/
+        # - wss://kas.gitlab.com # for GitLab.com users, use this KAS.
+        # - grpc://host.docker.internal:8150 # use this attribute when connecting from Docker.
+        volumeMounts:
+        - name: token-volume
+          mountPath: /config
+        - name: ca-pemstore-volume
+          mountPath: /tmp/myCA.pem
+          subPath: myCA.pem
+```
+
+## Project not found
+
+```json
+{
+  "level ":"error ",
+  "time ":"2022-01-05T15:18:11.331Z",
+  "msg ":"GetObjectsToSynchronize.Recv failed ",
+  "mod_name ":"gitops ",
+  "error ":"rpc error: code = NotFound desc = project not found ",
+}
+```
+
+This error is shown if the manifest project is not public. To fix it,
+[make sure your manifest project is public](repository.md#synchronize-manifest-projects) or your manifest files
+are stored in the Agent's configuration repository.
diff --git a/doc/user/infrastructure/iac/index.md b/doc/user/infrastructure/iac/index.md
index 21769bdd14c..cb6ec8bc438 100644
--- a/doc/user/infrastructure/iac/index.md
+++ b/doc/user/infrastructure/iac/index.md
@@ -6,36 +6,33 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 
 # Infrastructure as Code with Terraform and GitLab **(FREE)**
 
-## Motivation
+With Terraform in GitLab, you can use GitLab authentication and authorization with
+your GitOps and Infrastructure-as-Code (IaC) workflows.
+Use these features if you want to collaborate on Terraform code within GitLab or would like to use GitLab as a Terraform state storage that incorporates best practices out of the box.
 
-The Terraform integration features in GitLab enable your GitOps / Infrastructure-as-Code (IaC)
-workflows to tie into GitLab authentication and authorization. These features focus on
-lowering the barrier to entry for teams to adopt Terraform, collaborate effectively in
-GitLab, and support Terraform best practices.
-
-## Quick Start
+## Integrate your project with Terraform
 
 > SAST test was [introduced](https://gitlab.com/groups/gitlab-org/-/epics/6655) in GitLab 14.6.
 
-Use the following `.gitlab-ci.yml` to set up a basic Terraform project integration
-for GitLab versions 14.0 and later:
+In GitLab 14.0 and later, to integrate your project with Terraform, add the following
+to your `.gitlab-ci.yml` file:
 
 ```yaml
 include:
   - template: Terraform.latest.gitlab-ci.yml
 
 variables:
-  # If not using GitLab's HTTP backend, remove this line and specify TF_HTTP_* variables
+  # If you do not use the GitLab HTTP backend, remove this line and specify TF_HTTP_* variables
   TF_STATE_NAME: default
   TF_CACHE_KEY: default
   # If your terraform files are in a subdirectory, set TF_ROOT accordingly
   # TF_ROOT: terraform/production
 ```
 
-This template includes the following parameters that you can override:
+The `Terraform.latest.gitlab-ci.yml` template:
 
 - Uses the latest [GitLab Terraform image](https://gitlab.com/gitlab-org/terraform-images).
-- Uses the [GitLab-managed Terraform State](#gitlab-managed-terraform-state) as
+- Uses the [GitLab-managed Terraform state](#gitlab-managed-terraform-state) as
   the Terraform state storage backend.
 - Creates [four pipeline stages](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Terraform.latest.gitlab-ci.yml):
   `test`, `validate`, `build`, and `deploy`. These stages
@@ -44,10 +41,12 @@ This template includes the following parameters that you can override:
 - Runs the [Terraform SAST scanner](../../application_security/iac_scanning/index.md#configure-iac-scanning-manually),
   that you can disable by creating a `SAST_DISABLED` environment variable and setting it to `1`.
 
-The latest template described above might contain breaking changes between major GitLab releases. For users requiring more stable setups, we
-recommend using the stable templates:
+You can override the values in the default template by updating your `.gitlab-ci.yml` file.
+
+The latest template might contain breaking changes between major GitLab releases.
+For a more stable template, we recommend:
 
-- [A ready to use version](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Terraform.gitlab-ci.yml)
+- [A ready-to-use version](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Terraform.gitlab-ci.yml)
 - [A base template for customized setups](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Terraform/Base.gitlab-ci.yml)
 
 This video from January 2021 walks you through all the GitLab Terraform integration features:
@@ -59,7 +58,7 @@ This video from January 2021 walks you through all the GitLab Terraform integrat
   <iframe src="https://www.youtube.com/embed/iGXjUrkkzDI" frameborder="0" allowfullscreen="true"> </iframe>
 </figure>
 
-## GitLab Managed Terraform state
+## GitLab-managed Terraform state
 
 [Terraform remote backends](https://www.terraform.io/docs/language/settings/backends/index.html)
 enable you to store the state file in a remote, shared store. GitLab uses the
@@ -67,7 +66,7 @@ enable you to store the state file in a remote, shared store. GitLab uses the
 to securely store the state files in local storage (the default) or
 [the remote store of your choice](../../../administration/terraform_state.md).
 
-The GitLab managed Terraform state backend can store your Terraform state easily and
+The GitLab-managed Terraform state backend can store your Terraform state easily and
 securely. It spares you from setting up additional remote resources like
 Amazon S3 or Google Cloud Storage. Its features include:
 
@@ -75,7 +74,7 @@ Amazon S3 or Google Cloud Storage. Its features include:
 - Locking and unlocking state.
 - Remote Terraform plan and apply execution.
 
-Read more on setting up and [using GitLab Managed Terraform states](terraform_state.md).
+Read more about setting up and [using GitLab-managed Terraform states](terraform_state.md).
 
 ## Terraform module registry
 
@@ -104,7 +103,7 @@ to manage various aspects of GitLab using Terraform. The provider is an open sou
 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.
+is available as part of the official Terraform provider documentation.
 
 ## Create a new cluster through IaC (DEPRECATED)
 
diff --git a/doc/user/infrastructure/iac/mr_integration.md b/doc/user/infrastructure/iac/mr_integration.md
index 95ca478a383..8c135f18bc1 100644
--- a/doc/user/infrastructure/iac/mr_integration.md
+++ b/doc/user/infrastructure/iac/mr_integration.md
@@ -23,7 +23,7 @@ recommend encrypting plan output or modifying the project visibility settings.
 
 ## Configure Terraform report artifacts
 
-GitLab ships with a [pre-built CI template](index.md#quick-start) that uses GitLab Managed Terraform state and integrates Terraform changes into merge requests. We recommend customizing the pre-built image and relying on the `gitlab-terraform` helper provided within for a quick setup.
+GitLab ships with a [pre-built CI template](index.md#integrate-your-project-with-terraform) that uses GitLab Managed Terraform state and integrates Terraform changes into merge requests. We recommend customizing the pre-built image and relying on the `gitlab-terraform` helper provided within for a quick setup.
 
 To manually configure a GitLab Terraform Report artifact:
 
diff --git a/doc/user/infrastructure/iac/terraform_state.md b/doc/user/infrastructure/iac/terraform_state.md
index 0c5c09e8ace..fb60024e0ba 100644
--- a/doc/user/infrastructure/iac/terraform_state.md
+++ b/doc/user/infrastructure/iac/terraform_state.md
@@ -4,7 +4,7 @@ group: Configure
 info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
 ---
 
-# GitLab managed Terraform State **(FREE)**
+# GitLab-managed Terraform state **(FREE)**
 
 > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2673) in GitLab 13.0.
 
@@ -19,7 +19,7 @@ Using local storage (the default) on clustered deployments of GitLab will result
 a split state across nodes, making subsequent executions of Terraform inconsistent.
 You are highly advised to use a remote storage resource in that case.
 
-The GitLab managed Terraform state backend can store your Terraform state easily and
+The GitLab-managed Terraform state backend can store your Terraform state easily and
 securely, and spares you from setting up additional remote resources like
 Amazon S3 or Google Cloud Storage. Its features include:
 
@@ -216,7 +216,7 @@ recommends encrypting plan output or modifying the project visibility settings.
 
 See [this reference project](https://gitlab.com/gitlab-org/configure/examples/gitlab-terraform-aws) using GitLab and Terraform to deploy a basic AWS EC2 in a custom VPC.
 
-## Using a GitLab managed Terraform state backend as a remote data source
+## Using a GitLab-managed Terraform state backend as a remote data source
 
 You can use a GitLab-managed Terraform state as a
 [Terraform data source](https://www.terraform.io/docs/language/state/remote-state-data.html).
@@ -260,13 +260,13 @@ using `data.terraform_remote_state.example.outputs.<OUTPUT-NAME>`.
 You need at least the Developer role in the target project
 to read the Terraform state.
 
-## Migrating to GitLab Managed Terraform state
+## Migrating to GitLab-managed Terraform state
 
 Terraform supports copying the state when the backend is changed or
 reconfigured. This can be useful if you need to migrate from another backend to
-GitLab managed Terraform state. Using a local terminal is recommended to run the commands needed for migrating to GitLab Managed Terraform state.
+GitLab-managed Terraform state. Using a local terminal is recommended to run the commands needed for migrating to GitLab-managed Terraform state.
 
-The following example demonstrates how to change the state name, the same workflow is needed to migrate to GitLab Managed Terraform state from a different state storage backend.
+The following example demonstrates how to change the state name, the same workflow is needed to migrate to GitLab-managed Terraform state from a different state storage backend.
 
 ### Setting up the initial backend