GitLab agent configuration

Version history

When you set up a workspace, you must configure the GitLab agent for remote development. The remote development 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 the agent is properly configured for remote development.

Remote development settings

Setting Description
enabled Indicates whether remote development is enabled for the GitLab agent
dns_zone DNS zone where workspaces are available
gitlab_workspaces_proxy Namespace where gitlab-workspaces-proxy is installed
network_policy Firewall rules for workspaces
note
If a setting has an invalid value, it’s not possible to update any setting 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 with the GitLab agent.

The default value is false.

To enable remote development in the agent configuration, set enabled to true:

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:

remote_development:
  dns_zone: "<workspaces.example.dev>"

gitlab_workspaces_proxy

Use this setting to define the namespace where gitlab-workspaces-proxy is installed. The default value for gitlab_workspaces_proxy.namespace is gitlab-workspaces.

Example configuration:

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:

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.

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 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 on a private IP range.
  • The workspace must access a cloud resource on a private IP range.

Each element of the list defines an allow attribute with an optional except attribute. allow defines an IP range to allow traffic from. except lists IP ranges to exclude from the allow range.

Example configuration:

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 range 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.

Configuring user access with remote development

You can configure the user_access module to access the connected Kubernetes cluster with your GitLab credentials. This module is configured and runs independently of the remote_development module.

Be careful when configuring both user_access and remote_development in the same GitLab agent. The remote_development clusters manage user credentials (such as personal access tokens) as Kubernetes Secrets. Any misconfiguration in user_access might cause this private data to be accessible over the Kubernetes API.

For more information about configuring user_access, see Configure Kubernetes access.