Add latest changes from gitlab-org/gitlab@master

2 files changed, 146 insertions, 28 deletions

diff --git a/doc/user/workspace/configuration.md b/doc/user/workspace/configuration.md
index 2bd47cf9aa5..a1308d04653 100644
--- a/doc/user/workspace/configuration.md
+++ b/doc/user/workspace/configuration.md
@@ -20,26 +20,22 @@ which you can customize to meet the specific needs of each project.
 
 ### Prerequisites
 
-- Set up a Kubernetes cluster that the GitLab agent for Kubernetes supports.
+- Set up a Kubernetes cluster that the GitLab agent supports.
   See the [supported Kubernetes versions](../clusters/agent/index.md#supported-kubernetes-versions-for-gitlab-features).
 - Ensure autoscaling for the Kubernetes cluster is enabled.
-- In the Kubernetes cluster, verify that a [default storage class](https://kubernetes.io/docs/concepts/storage/storage-classes/)
+- In the Kubernetes cluster:
+  - Verify that a [default storage class](https://kubernetes.io/docs/concepts/storage/storage-classes/)
   is defined so that volumes can be dynamically provisioned for each workspace.
-- In the Kubernetes cluster, install an Ingress controller of your choice (for example, `ingress-nginx`)
-  and make that controller accessible over a domain. For example, point `*.workspaces.example.dev` and
-  `workspaces.example.dev` to the load balancer exposed by the Ingress controller.
-- In the Kubernetes cluster, [install `gitlab-workspaces-proxy`](https://gitlab.com/gitlab-org/remote-development/gitlab-workspaces-proxy#installation-instructions).
-- In the Kubernetes cluster, [install the GitLab agent for Kubernetes](../clusters/agent/install/index.md).
-- Configure remote development settings for the GitLab agent with this snippet and update `dns_zone` as needed:
-
-  ```yaml
-  remote_development:
-    enabled: true
-    dns_zone: "workspaces.example.dev"
-  ```
+  - Install an Ingress controller of your choice (for example, `ingress-nginx`) and make
+  that controller accessible over a domain. For example, point `*.workspaces.example.dev`
+  and `workspaces.example.dev` to the load balancer exposed by the Ingress controller.
+  - [Install `gitlab-workspaces-proxy`](https://gitlab.com/gitlab-org/remote-development/gitlab-workspaces-proxy#installation-instructions).
+  - [Install the GitLab agent](../clusters/agent/install/index.md).
+- Configure [remote development settings for the GitLab agent](gitlab_agent_configuration.md).
 
   You can use any agent defined under the root group of your project,
   provided that remote development is properly configured for that agent.
+
 - You must have at least the Developer role in the root group.
 - In each project you want to use this feature for, create a [devfile](index.md#devfile):
   1. On the left sidebar, select **Search or go to** and find your project.
@@ -168,20 +164,6 @@ RUN chmod 775 /etc/shadow
 USER gitlab-workspaces
 ```
 
-## Disable remote development in the GitLab agent for Kubernetes
-
-You can stop the `remote_development` module of the GitLab agent for Kubernetes from communicating with GitLab.
-To disable remote development in the GitLab agent configuration, set this property:
-
-```yaml
-remote_development:
-  enabled: false
-```
-
-The `remote_development` module is no longer available when you [create a workspace](#set-up-a-workspace).
-
-If you already have running workspaces, an administrator must manually delete these workspaces in Kubernetes.
-
 ## Related topics
 
 - [Quickstart guide for GitLab remote development workspaces](https://go.gitlab.com/AVKFvy)
diff --git a/doc/user/workspace/gitlab_agent_configuration.md b/doc/user/workspace/gitlab_agent_configuration.md
new file mode 100644
index 00000000000..d74014e9f1f
--- /dev/null
+++ b/doc/user/workspace/gitlab_agent_configuration.md
@@ -0,0 +1,136 @@
+---
+stage: Create
+group: IDE
+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
+---
+
+# GitLab agent configuration
+
+When you [set up a workspace](configuration.md#set-up-a-workspace),
+you must configure remote development settings for the GitLab agent.
+These settings are available in the agent configuration file under `remote_development`.
+
+You can use any agent defined under the root group of your project,
+provided that remote development is properly configured for that agent.
+
+## Remote development settings
+
+| Setting                                               | Description                                                          |
+|-------------------------------------------------------|:---------------------------------------------------------------------|
+| [`enabled`](#enabled)                                 | Indicates whether remote development is enabled for the GitLab agent |
+| [`dns_zone`](#dns_zone)                               | DNS zone where workspaces are available                              |
+| [`gitlab_workspaces_proxy`](#gitlab_workspaces_proxy) | Namespace where [`gitlab-workspaces-proxy`](https://gitlab.com/gitlab-org/remote-development/gitlab-workspaces-proxy) is installed                   |
+| [`network_policy`](#network_policy)                   | Firewall rules for workspaces                                        |
+
+NOTE:
+If any setting has an invalid value, all settings cannot be updated until you fix that value.
+
+### `enabled`
+
+Use this setting to define whether:
+
+- The GitLab agent can communicate with the GitLab instance.
+- You can [create a workspace](configuration.md#set-up-a-workspace) with the GitLab agent.
+
+The default value is `false`.
+
+To enable remote development in the agent configuration, set `enabled` to `true`:
+
+```yaml
+remote_development:
+  enabled: true
+```
+
+If remote development is disabled, an administrator must manually delete any
+running workspaces to remove those workspaces from the Kubernetes cluster.
+
+### `dns_zone`
+
+Use this setting to define the DNS zone of the URL where workspaces are available.
+When you set `dns_zone`, you can no longer update the setting.
+
+**Example configuration:**
+
+```yaml
+remote_development:
+  dns_zone: "<workspaces.example.dev>"
+```
+
+### `gitlab_workspaces_proxy`
+
+Use this setting to define the namespace where
+[`gitlab-workspaces-proxy`](https://gitlab.com/gitlab-org/remote-development/gitlab-workspaces-proxy) is installed.
+The default value for `gitlab_workspaces_proxy.namespace` is `gitlab-workspaces`.
+
+**Example configuration:**
+
+```yaml
+remote_development:
+  gitlab_workspaces_proxy:
+    namespace: "<custom-gitlab-workspaces-proxy-namespace>"
+```
+
+### `network_policy`
+
+Use this setting to define the network policy for each workspace.
+This setting controls network traffic for workspaces.
+
+The default value is:
+
+```yaml
+remote_development:
+  network_policy:
+    egress:
+      - allow: "0.0.0.0/0"
+        except:
+          - "10.0.0.0/8"
+          - "172.16.0.0/12"
+          - "192.168.0.0/16"
+```
+
+In this configuration:
+
+- The network policy is generated for each workspace because `enabled` is `true`.
+- The egress rules allow all traffic to the internet (`0.0.0.0/0`) except to the IP CIDR ranges `10.0.0.0/8`, `172.16.0.0/12`, and `192.168.0.0/16`.
+
+The behavior of the network policy depends on the Kubernetes network plugin.
+For more information, see the [Kubernetes documentation](https://kubernetes.io/docs/concepts/services-networking/network-policies/).
+
+#### `network_policy.enabled`
+
+Use this setting to define whether the network policy is generated for each workspace.
+The default value for `network_policy.enabled` is `true`.
+
+#### `network_policy.egress`
+
+> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/11629) in GitLab 16.7.
+
+Use this setting to define a list of IP CIDR ranges to allow as egress destinations from a workspace.
+
+Define egress rules when:
+
+- The GitLab instance is available on a private IP.
+- Workspace users must access a cloud resource available on a private IP.
+
+Each element of the list defines an `allow` attribute with an optional `except` attribute.
+The `allow` attribute defines an IP CIDR range to allow traffic from.
+The `except` attribute lists IP CIDR ranges to exclude from the `allow` range.
+
+**Example configuration:**
+
+```yaml
+remote_development:
+  network_policy:
+    egress:
+      - allow: "0.0.0.0/0"
+        except:
+          - "10.0.0.0/8"
+          - "172.16.0.0/12"
+          - "192.168.0.0/16"
+      - allow: "172.16.123.1/32"
+```
+
+In this example, traffic from the workspace is allowed if:
+
+- The destination IP is any IP except `10.0.0.0/8`, `172.16.0.0/12`, or `192.168.0.0/16`.
+- The destination IP is `172.16.123.1/32`.