Add latest changes from gitlab-org/gitlab@master

9 files changed, 336 insertions, 104 deletions

diff --git a/doc/ci/environments/configure_kubernetes_deployments.md b/doc/ci/environments/configure_kubernetes_deployments.md
new file mode 100644
index 00000000000..e618aae7cae
--- /dev/null
+++ b/doc/ci/environments/configure_kubernetes_deployments.md
@@ -0,0 +1,58 @@
+---
+stage: Deploy
+group: Environments
+info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments
+type: reference
+---
+
+# Configure Kubernetes deployments (deprecated)
+
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27630) in GitLab 12.6.
+> - [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5.
+
+WARNING:
+This feature was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5.
+
+If you are deploying to a [Kubernetes cluster](../../user/infrastructure/clusters/index.md)
+associated with your project, you can configure these deployments from your
+`.gitlab-ci.yml` file.
+
+NOTE:
+Kubernetes configuration isn't supported for Kubernetes clusters
+[managed by GitLab](../../user/project/clusters/gitlab_managed_clusters.md).
+
+The following configuration options are supported:
+
+- [`namespace`](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/)
+
+In the following example, the job deploys your application to the
+`production` Kubernetes namespace.
+
+```yaml
+deploy:
+  stage: deploy
+  script:
+    - echo "Deploy to production server"
+  environment:
+    name: production
+    url: https://example.com
+    kubernetes:
+      namespace: production
+  rules:
+    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
+```
+
+When you use the GitLab Kubernetes integration to deploy to a Kubernetes cluster,
+you can view cluster and namespace information. On the deployment
+job page, it's displayed above the job trace:
+
+![Deployment cluster information](../img/environments_deployment_cluster_v12_8.png)
+
+## Configure incremental rollouts
+
+Learn how to release production changes to only a portion of your Kubernetes pods with
+[incremental rollouts](../environments/incremental_rollouts.md).
+
+## Related topics
+
+- [Deploy boards (deprecated)](../../user/project/deploy_boards.md)
diff --git a/doc/ci/environments/index.md b/doc/ci/environments/index.md
index 137bc883072..d99c9aac34d 100644
--- a/doc/ci/environments/index.md
+++ b/doc/ci/environments/index.md
@@ -300,54 +300,6 @@ The `when: manual` action:
 
 You can find the play button in the pipelines, environments, deployments, and jobs views.
 
-## Configure Kubernetes deployments (deprecated)
-
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27630) in GitLab 12.6.
-> - [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5.
-
-WARNING:
-This feature was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5.
-
-If you are deploying to a [Kubernetes cluster](../../user/infrastructure/clusters/index.md)
-associated with your project, you can configure these deployments from your
-`.gitlab-ci.yml` file.
-
-NOTE:
-Kubernetes configuration isn't supported for Kubernetes clusters
-[managed by GitLab](../../user/project/clusters/gitlab_managed_clusters.md).
-
-The following configuration options are supported:
-
-- [`namespace`](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/)
-
-In the following example, the job deploys your application to the
-`production` Kubernetes namespace.
-
-```yaml
-deploy:
-  stage: deploy
-  script:
-    - echo "Deploy to production server"
-  environment:
-    name: production
-    url: https://example.com
-    kubernetes:
-      namespace: production
-  rules:
-    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
-```
-
-When you use the GitLab Kubernetes integration to deploy to a Kubernetes cluster,
-you can view cluster and namespace information. On the deployment
-job page, it's displayed above the job trace:
-
-![Deployment cluster information](../img/environments_deployment_cluster_v12_8.png)
-
-### Configure incremental rollouts
-
-Learn how to release production changes to only a portion of your Kubernetes pods with
-[incremental rollouts](../environments/incremental_rollouts.md).
-
 ## Track newly included merge requests per deployment
 
 GitLab can track newly included merge requests per deployment.
@@ -971,14 +923,14 @@ the `review/feature-1` spec takes precedence over `review/*` and `*` specs.
 
 ## Related topics
 
-- [Use GitLab CI to deploy to multiple environments (blog post)](https://about.gitlab.com/blog/2021/02/05/ci-deployment-and-environments/)
-- [Review Apps](../review_apps/index.md): Use dynamic environments to deploy your code for every branch.
-- [Deploy boards](../../user/project/deploy_boards.md): View the status of your applications running on Kubernetes.
-- [Protected environments](protected_environments.md): Determine who can deploy code to your environments.
-- [Environments Dashboard](../environments/environments_dashboard.md): View a summary of each
-  environment's operational health. **(PREMIUM)**
-- [Deployment safety](deployment_safety.md#restrict-write-access-to-a-critical-environment): Secure your deployments.
-- [Track deployments of an external deployment tool](external_deployment_tools.md): Use an external deployment tool instead of built-in deployment solution.
+- [Kubernetes dashboard](kubernetes_dashboard.md)
+- [Deploy to multiple environments with GitLab CI/CD (blog post)](https://about.gitlab.com/blog/2021/02/05/ci-deployment-and-environments/)
+- [Review Apps](../review_apps/index.md)
+- [Protected environments](protected_environments.md)
+- [Environments Dashboard](../environments/environments_dashboard.md)
+- [Deployment safety](deployment_safety.md#restrict-write-access-to-a-critical-environment)
+- [Track deployments of an external deployment tool](external_deployment_tools.md)
+- [Configure Kubernetes deployments (deprecated)](configure_kubernetes_deployments.md)
 
 ## Troubleshooting
 
diff --git a/doc/ci/environments/kubernetes_dashboard.md b/doc/ci/environments/kubernetes_dashboard.md
new file mode 100644
index 00000000000..c669898602f
--- /dev/null
+++ b/doc/ci/environments/kubernetes_dashboard.md
@@ -0,0 +1,69 @@
+---
+stage: Deploy
+group: Environments
+info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments
+type: reference
+---
+
+# Kubernetes Dashboard **(FREE)**
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/390769) in GitLab 16.1, with [flags](../../administration/feature_flags.md) named `environment_settings_to_graphql`, `kas_user_access`, `kas_user_access_project`, and `expose_authorized_cluster_agents`. Disabled by default.
+
+FLAG:
+On self-managed GitLab, by default this feature is not available. To make it available, ask an administrator to [enable the feature flags](../../administration/feature_flags.md) named `environment_settings_to_graphql`, `kas_user_access`, `kas_user_access_project`, and `expose_authorized_cluster_agents`.
+
+Use the Kubernetes Dashboard to understand the status of your clusters with an intuitive visual interface.
+The Kubernetes Dashboard works with every connected Kubernetes cluster, whether you deployed them
+with CI/CD or GitOps.
+
+For Flux users, the synchronization status of a given environment is not displayed in the dashboard.
+[Issue 391581](https://gitlab.com/gitlab-org/gitlab/-/issues/391581) proposes to add this functionality.
+
+## Configure the Kubernetes Dashboard
+
+Configure a Kubernetes Dashboard to use it for a given environment.
+You can configure dashboard for an environment that already exists, or
+add one when you create an environment.
+
+Prerequisite:
+
+- The agent for Kubernetes must be shared with the environment's project, or its parent group, using the [`user_access`](../../user/clusters/agent/user_access.md) keyword.
+
+### The environment already exists
+
+1. On the top bar, select **Main menu > Projects** and find your project.
+1. On the left sidebar, select **Deployments > Environments**.
+1. Select the environment to be associated with the Kubernetes.
+1. Select **Edit**.
+1. Select a GitLab agent for Kubernetes.
+1. Select **Save**.
+
+### The environment doesn't exist
+
+1. On the top bar, select **Main menu > Projects** and find your project.
+1. On the left sidebar, select **Deployments > Environments**.
+1. Select **New environment**.
+1. Complete the **Name** field.
+1. Select a GitLab agent for Kubernetes.
+1. Select **Save**.
+
+## View a dashboard
+
+To view a configured Kubernetes Dashboard:
+
+1. On the top bar, select **Main menu > Projects** and find your project.
+1. On the left sidebar, select **Deployments > Environments**.
+1. Expand the environment associated with GitLab agent for Kubernetes.
+1. Expand **Kubernetes overview**.
+
+## Troubleshooting
+
+When working with the Kubernetes Dashboard, you might encounter the following issues.
+
+### User cannot list resource in API group
+
+You might get an error that states `Error: services is forbidden: User "gitlab:user:<user-name>" cannot list resource "<resource-name>" in API group "" at the cluster scope`.
+
+This error happens when a user is not allowed to do the specified operation in the [Kubernetes RBAC](https://kubernetes.io/docs/reference/access-authn-authz/rbac/).
+
+To resolve, check your [RBAC configuration](../../user/clusters/agent/user_access.md#configure-kubernetes-access). If the RBAC is properly configured, contact your Kubernetes administrator.
diff --git a/doc/ci/yaml/index.md b/doc/ci/yaml/index.md
index c966676cbc9..ec7ab8e3a28 100644
--- a/doc/ci/yaml/index.md
+++ b/doc/ci/yaml/index.md
@@ -1850,7 +1850,7 @@ environment, using the `production`
 
 **Related topics**:
 
-- [Available settings for `kubernetes`](../environments/index.md#configure-kubernetes-deployments-deprecated).
+- [Available settings for `kubernetes`](../environments/configure_kubernetes_deployments.md).
 
 #### `environment:deployment_tier`
 
diff --git a/doc/development/testing_guide/flaky_tests.md b/doc/development/testing_guide/flaky_tests.md
index 40be7a7d094..9114ec3d179 100644
--- a/doc/development/testing_guide/flaky_tests.md
+++ b/doc/development/testing_guide/flaky_tests.md
@@ -13,62 +13,48 @@ eventually.
 
 ## What are the potential cause for a test to be flaky?
 
-### Unclean environment
+### State leak
 
-**Label:** `flaky-test::unclean environment`
+**Label:** `flaky-test::state leak`
 
-**Description:** The environment got dirtied by a previous test. The actual cause is probably not the flaky test here.
+**Description:** Data state has leaked from a previous test. The actual cause is probably not the flaky test here.
 
 **Difficulty to reproduce:** Moderate. Usually, running the same spec files until the one that's failing reproduces the problem.
 
-**Resolution:** Fix the previous tests and/or places where the environment is modified, so that
+**Resolution:** Fix the previous tests and/or places where the test data or environment is modified, so that
 it's reset to a pristine test after each test.
 
 **Examples:**
 
-- [Example 1](https://gitlab.com/gitlab-org/gitlab/-/issues/378414#note_1142026988): A migration
+- [Example 1](https://gitlab.com/gitlab-org/gitlab/-/issues/402915): State leakage can result from
+  data records created with `let_it_be` shared between test examples, while some test modifies the model
+  either deliberately or unwillingly causing out-of-sync data in test examples. This can result in `PG::QueryCanceled: ERROR` in the subsequent test examples or retries.
+  For more information about state leakages and resolution options, see [GitLab testing best practices](best_practices.md#lets-talk-about-let).
+- [Example 2](https://gitlab.com/gitlab-org/gitlab/-/issues/378414#note_1142026988): A migration
   test might roll-back the database, perform its testing, and then roll-up the database in an
   inconsistent state, so that following tests might not know about certain columns.
-- [Example 2](https://gitlab.com/gitlab-org/gitlab/-/issues/368500): A test modifies data that is
+- [Example 3](https://gitlab.com/gitlab-org/gitlab/-/issues/368500): A test modifies data that is
   used by a following test.
-- [Example 3](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/103434#note_1172316521): A test for a database query passes in a fresh database, but in a
+- [Example 4](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/103434#note_1172316521): A test for a database query passes in a fresh database, but in a
   CI/CD pipeline where the database is used to process previous test sequences, the test fails. This likely
-    means that the query itself needs to be updated to work in a non-clean database.
-
-### Ordering assertion
-
-**Label:** `flaky-test::ordering assertion`
-
-**Description:** The test is expecting a specific order in the data under test yet the data is in
-a non-deterministic order.
-
-**Difficulty to reproduce:** Easy. Usually, running the test locally several times would reproduce
-the problem.
-
-**Resolution:** Depending on the problem, you might want to:
-
-- loosen the assertion if the test shouldn't care about ordering but only on the elements
-- fix the test by specifying a deterministic ordering
-- fix the app code by specifying a deterministic ordering
-
-**Examples:**
-
-- [Example 1](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/10148/diffs): Without
-  specifying `ORDER BY`, database will not give deterministic ordering, or data race happening
-  in the tests.
-- [Example 2](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106936/diffs).
+  means that the query itself needs to be updated to work in a non-clean database.
 
 ### Dataset-specific
 
 **Label:** `flaky-test::dataset-specific`
 
-**Description:** The test assumes the dataset is in a particular (usually limited) state, which
+**Description:** The test assumes the dataset is in a particular (usually limited) state or order, which
 might not be true depending on when the test run during the test suite.
 
 **Difficulty to reproduce:** Moderate, as the amount of data needed to reproduce the issue might be
-difficult to achieve locally.
+difficult to achieve locally. Ordering issues are easier to reproduce by repeatedly running the tests several times.
 
-**Resolution:** Fix the test to not assume that the dataset is in a particular state, don't hardcode IDs.
+**Resolution:**
+
+- Fix the test to not assume that the dataset is in a particular state, don't hardcode IDs.
+- Loosen the assertion if the test shouldn't care about ordering but only on the elements.
+- Fix the test by specifying a deterministic ordering.
+- Fix the app code by specifying a deterministic ordering.
 
 **Examples:**
 
@@ -81,11 +67,10 @@ difficult to achieve locally.
   suite, it might pass as not enough records were created before it, but as soon as it would run
   later in the suite, there could be a record that actually has the ID `42`, hence the test would
   start to fail.
-- [Example 3](https://gitlab.com/gitlab-org/gitlab/-/issues/402915): State leakage can result from
-  data records created with `let_it_be` shared between test examples, while some test modifies the model
-  either deliberately or unwillingly causing out-of-sync data in test examples. This can result in `PG::QueryCanceled: ERROR` in the subsequent test examples or retries.
-  For more information about state leakages and resolution options,
-  see [GitLab testing best practices](best_practices.md#lets-talk-about-let).
+- [Example 3](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/10148/diffs): Without
+  specifying `ORDER BY`, database is not given deterministic ordering, or data race can happen
+  in the tests.
+- [Example 4](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106936/diffs).
 
 ### Random input
 
diff --git a/doc/user/clusters/agent/install/index.md b/doc/user/clusters/agent/install/index.md
index e91bcd6e330..12600747fad 100644
--- a/doc/user/clusters/agent/install/index.md
+++ b/doc/user/clusters/agent/install/index.md
@@ -29,7 +29,7 @@ Before you can install the agent in your cluster, you need:
 
 To install the agent in your cluster:
 
-1. Optional. [Create an agent configuration file](#create-an-agent-configuration-file).
+1. [Create an agent configuration file](#create-an-agent-configuration-file).
 1. [Register the agent with GitLab](#register-the-agent-with-gitlab).
 1. [Install the agent in your cluster](#install-the-agent-in-the-cluster).
 
@@ -44,8 +44,7 @@ For configuration settings, the agent uses a YAML file in the GitLab project. Yo
 
 - You use [a GitOps workflow](../gitops.md#gitops-workflow-steps).
 - You use [a GitLab CI/CD workflow](../ci_cd_workflow.md#gitlab-cicd-workflow-steps) and want to authorize a different project to use the agent.
-
-Otherwise it is optional.
+- You [allow specific project or group members to access Kubernetes](../user_access.md).
 
 To create an agent configuration file:
 
@@ -58,14 +57,12 @@ To create an agent configuration file:
    - Start with an alphanumeric character.
    - End with an alphanumeric character.
 
-1. In the repository, in the default branch, create this directory at the root:
+1. In the repository, in the default branch, create an agent configuration file at the root:
 
    ```plaintext
-   .gitlab/agents/<agent-name>
+   .gitlab/agents/<agent-name>/config.yaml
    ```
 
-1. In the directory, create a `config.yaml` file. Ensure the filename ends in `.yaml`, not `.yml`.
-
 You can leave the file blank for now, and [configure it](#configure-your-agent) later.
 
 ### Register the agent with GitLab
diff --git a/doc/user/clusters/agent/user_access.md b/doc/user/clusters/agent/user_access.md
new file mode 100644
index 00000000000..f4c7b1f658c
--- /dev/null
+++ b/doc/user/clusters/agent/user_access.md
@@ -0,0 +1,155 @@
+---
+stage: Deploy
+group: Environments
+info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments
+---
+
+# Grant users Kubernetes access **(FREE)**
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/390769) in GitLab 16.1, with [flags](../../../administration/feature_flags.md) named `environment_settings_to_graphql`, `kas_user_access`, `kas_user_access_project`, and `expose_authorized_cluster_agents`. Disabled by default.
+
+FLAG:
+On self-managed GitLab, by default this feature is not available. To make it available, ask an administrator to [enable the feature flags](../../../administration/feature_flags.md) named `environment_settings_to_graphql`, `kas_user_access`, `kas_user_access_project`, and `expose_authorized_cluster_agents`.
+
+As an administrator of Kubernetes clusters in an organization, you can grant Kubernetes access to members
+of a specific project or group.
+
+Granting access also activates the Kubernetes Dashboard for a project or group.
+
+## Configure Kubernetes access
+
+Configure access when you want to grant users access
+to a Kubernetes cluster.
+
+Prerequisites:
+
+- The agent for Kubernetes is installed in the Kubernetes cluster.
+- You must have the Developer role or higher.
+
+To configure access:
+
+- In the agent configuration file, define a `user_access` keyword with the following parameters:
+
+  - `projects`: A list of projects whose members should have access.
+  - `groups`: A list of groups whose members should have access.
+  - `access_as`: Required. For plain access, the value is `{ agent: {...} }`.
+
+After you configure access, requests are forwarded to the API server using
+the agent service account.
+For example:
+
+```yaml
+# .gitlab/agents/my-agent/config.yaml
+
+user_access:
+  access_as:
+    agent: {}
+  projects:
+    - id: group-1/project-1
+    - id: group-2/project-2
+  groups:
+    - id: group-2
+    - id: group-3/subgroup
+```
+
+## Configure access with user impersonation **(PREMIUM)**
+
+You can grant access to a Kubernetes cluster and transform
+requests into impersonation requests for authenticated users.
+
+Prerequisites:
+
+- The agent for Kubernetes is installed in the Kubernetes cluster.
+- You must have the Developer role or higher.
+
+To configure access with user impersonation:
+
+- In the agent configuration file, define a `user_access` keyword with the following parameters:
+
+  - `projects`: A list of projects whose members should have access.
+  - `groups`: A list of groups whose members should have access.
+  - `access_as`: Required. For user impersonation, the value is `{ user: {...} }`.
+
+After you configure access, requests are transformed into impersonation requests for
+authenticated users.
+
+### User impersonation workflow
+
+The installed `agentk` impersonates the given users as follows:
+
+- `UserName` is `gitlab:user:<username>`
+- `Groups` is:
+  - `gitlab:user`: Common to all requests coming from GitLab users.
+  - `gitlab:project_role:<project_id>:<role>` for each role in each authorized project.
+  - `gitlab:group_role:<group_id>:<role>` for each role in each authorized group.
+- `Extra` carries additional information about the request:
+  - `agent.gitlab.com/id`: The agent ID.
+  - `agent.gitlab.com/username`: The username of the GitLab user.
+  - `agent.gitlab.com/config_project_id`: The agent configuration project ID.
+  - `agent.gitlab.com/access_type`: One of `personal_access_token`,
+    `oidc_id_token`, or `session_cookie`.
+
+Only projects and groups directly listed in the under `user_access` in the configuration
+file are impersonated. For example:
+
+```yaml
+# .gitlab/agents/my-agent/config.yaml
+
+user_access:
+  access_as:
+    user: {}
+  projects:
+    - id: group-1/project-1 # group_id=1, project_id=1
+    - id: group-2/project-2 # group_id=2, project_id=2
+  groups:
+    - id: group-2 # group_id=2
+    - id: group-3/subgroup # group_id=3, group_id=4
+```
+
+In this configuration:
+
+- If a user is a member of only `group-1`, they receive
+  only the Kubernetes RBAC groups `gitlab:project_role:1:<role>`.
+- If a user is a member of `group-2`, they receive both Kubernetes RBAC groups:
+  - `gitlab:project_role:2:<role>`,
+  - `gitlab:group_role:2:<role>`.
+
+### RBAC authorization
+
+Impersonated requests require `ClusterRoleBinding` or `RoleBinding` to identify the resource permissions
+inside Kubernetes. See [RBAC authorization](https://kubernetes.io/docs/reference/access-authn-authz/rbac/)
+for the appropriate configuration.
+
+For example, if you allow maintainers in `awesome-org/deployment` project (ID: 123) to read the Kubernetes workloads,
+you must add a `ClusterRoleBinding` resource to your Kubernetes configuration:
+
+```yaml
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRoleBinding
+metadata:
+  name: my-cluster-role-binding
+roleRef:
+  name: view
+  kind: ClusterRole
+  apiGroup: rbac.authorization.k8s.io
+subjects:
+  - name: gitlab:project_role:123:maintainer
+    kind: Group
+```
+
+## Related topics
+
+- [Architectural blueprint](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/master/doc/kubernetes_user_access.md)
+- [Kubernetes Dashboard](https://gitlab.com/groups/gitlab-org/-/epics/2493)
+
+<!-- ## Troubleshooting
+
+Include any troubleshooting steps that you can foresee. If you know beforehand what issues
+one might have when setting this up, or when something is changed, or on upgrading, it's
+important to describe those, too. Think of things that may go wrong and include them here.
+This is important to minimize requests for support, and to avoid doc comments with
+questions that you know someone might ask.
+
+Each scenario can be a third-level heading, for example `### Getting error message X`.
+If you have none to add when creating a doc, leave this section in place
+but commented out to help encourage others to add to it in the future. -->
diff --git a/doc/user/clusters/agent/work_with_agent.md b/doc/user/clusters/agent/work_with_agent.md
index b2e8ac6ef16..2b69141d9c5 100644
--- a/doc/user/clusters/agent/work_with_agent.md
+++ b/doc/user/clusters/agent/work_with_agent.md
@@ -30,6 +30,22 @@ On this page, you can view:
 - The version of `agentk` installed on your cluster.
 - The path to each agent configuration file.
 
+## View shared agents
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/395498) in GitLab 16.1.
+
+In addition to the agents owned by your project, you can also view agents shared with the
+[`ci_access`](ci_cd_workflow.md) and [`user_access`](user_access.md) keywords. Once an agent
+is shared with a project, it automatically appears in the project agent tab.
+
+To view the list of shared agents:
+
+1. On the top bar, select **Main menu > Projects** and find the project.
+1. On the left sidebar, select **Infrastructure > Kubernetes clusters**.
+1. Select the **Agent** tab.
+
+The list of shared agents and their clusters are displayed.
+
 ## View an agent's activity information
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/277323) in GitLab 14.6.
diff --git a/doc/user/project/clusters/deploy_to_cluster.md b/doc/user/project/clusters/deploy_to_cluster.md
index 31d5a73757a..2ea7ac0f1fd 100644
--- a/doc/user/project/clusters/deploy_to_cluster.md
+++ b/doc/user/project/clusters/deploy_to_cluster.md
@@ -78,7 +78,7 @@ You can customize the deployment namespace in a few ways:
 - For **non-managed** clusters, the auto-generated namespace is set in the `KUBECONFIG`,
   but the user is responsible for ensuring its existence. You can fully customize
   this value using
-  [`environment:kubernetes:namespace`](../../../ci/environments/index.md#configure-kubernetes-deployments-deprecated)
+  [`environment:kubernetes:namespace`](../../../ci/environments/configure_kubernetes_deployments.md)
   in `.gitlab-ci.yml`.
 
 When you customize the namespace, existing environments remain linked to their current