diff options
author | GitLab Bot <gitlab-bot@gitlab.com> | 2023-12-04 12:13:06 +0300 |
---|---|---|
committer | GitLab Bot <gitlab-bot@gitlab.com> | 2023-12-04 12:13:06 +0300 |
commit | 6974ffffd292657d8257826b2e09a0a8fff6c6a8 (patch) | |
tree | c4cb8005ff9158a92cb8d87e2992603e7b8f8cd6 /doc/user | |
parent | 3f7324cf3aefa10a3b2126683e7d61e595bc210a (diff) |
Add latest changes from gitlab-org/gitlab@master
Diffstat (limited to 'doc/user')
-rw-r--r-- | doc/user/workspace/configuration.md | 38 | ||||
-rw-r--r-- | doc/user/workspace/gitlab_agent_configuration.md | 136 |
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`. |