Merge branch 'bl-combine-setup-workspaces-tutorials' into 'master'

Consolidate Workspace setup tutorials

See merge request https://gitlab.com/gitlab-org/gitlab/-/merge_requests/179217



Merged-by: Chad Woolley <cwoolley@gitlab.com>
Approved-by: Chad Woolley <cwoolley@gitlab.com>
Reviewed-by: Chad Woolley <cwoolley@gitlab.com>
Co-authored-by: Brendan <blynch@gitlab.com>

doc/user/workspace/configuration.md

@@ -35,7 +35,7 @@ To set up infrastructure for workspaces:
    1. Point [`dns_zone`](gitlab_agent_configuration.md#dns_zone) and `*.<dns_zone>`
       to the load balancer exposed by the Ingress controller.
       This load balancer must support WebSockets.
-   1. [Set up the GitLab workspaces proxy](set_up_workspaces_proxy.md).
+   1. [Set up the GitLab workspaces proxy](set_up_gitlab_agent_and_proxies.md).
 1. Optional. [Configure sudo access for a workspace](#configure-sudo-access-for-a-workspace).
 1. Optional. [Configure support for private container registries](#configure-support-for-private-container-registries).
 
@@ -149,7 +149,7 @@ Prerequisites:
 - You must enable SSH access for the images specified in your [devfile](index.md#devfile).
   For more information, see [update your workspace container image](#update-your-workspace-container-image).
 - You must configure a TCP load balancer that points to the GitLab workspaces proxy.
-  For more information, see [update your DNS records](set_up_workspaces_proxy.md#update-your-dns-records).
+  For more information, see [update your DNS records](set_up_gitlab_agent_and_proxies.md#update-your-dns-records).
 
 To connect to a workspace with an SSH client:
 

doc/user/workspace/gitlab_agent_configuration.md

@@ -19,6 +19,7 @@ When you [set up workspace infrastructure](configuration.md#set-up-workspace-inf
 
 Prerequisites:
 
+- You must complete the setup steps in [Tutorial: Set up GitLab agent and proxies](set_up_gitlab_agent_and_proxies.md).
 - The agent configuration must have the `remote_development` module enabled, and the required fields of this module must be correctly set. For more information, see [workspace settings](#workspace-settings).
 - The agent must be **allowed** in a group for the purpose of creating workspaces. During workspace creation, users can select allowed agents that are associated with any parent group of the workspace project.
 - The workspace creator must have the Developer role to the project of the agent.
@@ -111,7 +112,7 @@ you can use any configured agent in `top-level-group` and in any of its subgroup
 |-------------------------------------------------------------------------------------------|----------|-----------------------------------------|-------------|
 | [`enabled`](#enabled)                                                                     | Yes      | `false`                                 | Indicates whether remote development is enabled for the GitLab agent. |
 | [`dns_zone`](#dns_zone)                                                                   | Yes      | None                                    | DNS zone where workspaces are available. |
-| [`gitlab_workspaces_proxy`](#gitlab_workspaces_proxy)                                     | No       | `gitlab-workspaces`                     | Namespace where [`gitlab-workspaces-proxy`](set_up_workspaces_proxy.md) is installed. |
+| [`gitlab_workspaces_proxy`](#gitlab_workspaces_proxy)                                     | No       | `gitlab-workspaces`                     | Namespace where [`gitlab-workspaces-proxy`](set_up_gitlab_agent_and_proxies.md) is installed. |
 | [`network_policy`](#network_policy)                                                       | No       | See [`network_policy`](#network_policy) | Firewall rules for workspaces. |
 | [`default_resources_per_workspace_container`](#default_resources_per_workspace_container) | No       | `{}`                                    | Default requests and limits for CPU and memory per workspace container. |
 | [`max_resources_per_workspace`](#max_resources_per_workspace)                             | No       | `{}`                                    | Maximum requests and limits for CPU and memory per workspace. |
@@ -163,7 +164,7 @@ remote_development:
 ### `gitlab_workspaces_proxy`
 
 Use this setting to define the namespace where
-[`gitlab-workspaces-proxy`](set_up_workspaces_proxy.md) is installed.
+[`gitlab-workspaces-proxy`](set_up_gitlab_agent_and_proxies.md) is installed.
 The default value for `gitlab_workspaces_proxy.namespace` is `gitlab-workspaces`.
 
 **Example configuration:**

doc/user/workspace/set_up_gitlab_agent.md

 ---
-stage: Create
-group: Remote Development
-info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments
-description: "Set up the GitLab agent to create and manage workspaces in a project."
+redirect_to: 'set_up_gitlab_agent_and_proxies.md'
+remove_date: '2025-04-20'
 ---
 
-# Tutorial: Set up the GitLab agent for workspaces
+<!-- markdownlint-disable -->
 
-This tutorial shows you how to set up the GitLab agent
-so users can create and manage workspaces in a project.
-For this tutorial, the following hierarchy is used:
+This document was moved to [another location](set_up_gitlab_agent_and_proxies.md).
 
-```mermaid
-%%{init: {'theme':'neutral'}}%%
-graph TD;
-    classDef active fill:lightgreen, stroke:#green, color:green, stroke-width:1px;
-
-    topGroup[Top-level group]
-    subGroup[Subgroup]
-    workspaceProject[Workspace project]
-    agentProject[Agent project]
-    workspaceAgent[Workspace agent]
-
-    topGroup --> subGroup
-
-    subGroup --> workspaceProject
-    subGroup --> agentProject
-    agentProject -.- workspaceAgent
-
-    class workspaceProject active;
-```
-
-To set up the GitLab agent for workspaces, you will:
-
-1. [Configure the `remote_development` module in the agent project](#configure-the-remote_development-module-in-the-agent-project).
-1. [Allow the GitLab agent in a group](#allow-the-gitlab-agent-in-a-group).
-1. [Grant workspace users the necessary permissions](#grant-workspace-users-the-necessary-permissions).
-
-## Prerequisites
-
-- You must install the GitLab agent.
-  For more information, see [set up workspace infrastructure](configuration.md#set-up-workspace-infrastructure).
-- You must have administrator access to the instance or the Owner role for the group.
-
-## Configure the `remote_development` module in the agent project
-
-To configure the `remote_development` module in the agent project:
-
-1. On the left sidebar, select **Search or go to** and find your project.
-1. In your project, create a `.gitlab/agents/<agentName>/config.yaml` file.
-   `agentName` is the name of the agent you configured when you set up workspace infrastructure.
-1. In `config.yaml`, use the following configuration for [workspace settings](gitlab_agent_configuration.md#workspace-settings):
-
-   ```yaml
-   remote_development:
-     enabled: true
-     dns_zone: "<workspaces.example.dev>" # DNS zone of the URL where workspaces are available
-   ```
-
-Next, you'll allow the GitLab agent in a group.
-
-## Allow the GitLab agent in a group
-
-When you allow an agent in a group, the group and its subgroups can use that agent.
-Carefully consider the group where you allow the GitLab agent.
-
-To allow the GitLab agent in a group:
-
-1. On the left sidebar, select **Search or go to** and find your group.
-1. On the left sidebar, select **Settings > Workspaces**.
-1. In the **Group agents** section, select the **All agents** tab.
-1. For the GitLab agent, select **Allow**.
-1. On the confirmation dialog, select **Allow agent**.
-
-Now it's time to grant workspace users the necessary permissions to create and manage workspaces.
-
-## Grant workspace users the necessary permissions
-
-You can grant users with at least the Developer role for the workspace and agent projects
-the necessary permissions to create and manage workspaces.
-
-To grant workspace users the necessary permissions, see:
-
-- [Add users to a project](../project/members/index.md#add-users-to-a-project).
-- [Add users to a group](../group/index.md#add-users-to-a-group).
-
-You've done it! Users can now create and manage workspaces in a project.
+<!-- This redirect file can be deleted after <2025-04-20>. -->
+<!-- Redirects that point to other docs in the same project expire in three months. -->
+<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. -->
+<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html -->

doc/user/workspace/set_up_gitlab_agent_and_proxies.md

+---
+stage: Create
+group: Remote Development
+info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments
+description: "Create a GitLab workspaces proxy to authenticate and authorize workspaces in your cluster."
+---
+
+# Tutorial: Set up GitLab agent and proxies
+
+This tutorial shows you how to:
+
+- Set up the GitLab agent so users can create and manage workspaces in a project.
+- Set up the GitLab workspaces proxy to authenticate and authorize [workspaces](index.md)
+  in your cluster.
+
+NOTE:
+You must complete the setup steps in this tutorial before you can configure a GitLab agent to support workspaces.
+After completing the tutorial, use [GitLab agent configuration](gitlab_agent_configuration.md) to configure
+your GitLab agent.
+
+## Before you begin
+
+Before starting this tutorial, you must have:
+
+- Administrator access to your GitLab instance or the Owner role for your group.
+- An installed Ingress controller.
+- A running Kubernetes cluster.
+- `helm` 3.11.0 or later and `kubectl` on your local machine.
+- The GitLab agent installed in your cluster.
+  For installation instructions, see [set up workspace infrastructure](configuration.md#set-up-workspace-infrastructure).
+- Access to configure a wildcard domain in your DNS provider.
+  For example, `*.workspaces.example.dev` is required for workspace access.
+
+For this tutorial, the following hierarchy is used:
+
+```mermaid
+%%{init: {'theme':'neutral'}}%%
+graph TD;
+    classDef active fill:lightgreen, stroke:#green, color:green, stroke-width:1px;
+
+    topGroup[Top-level group]
+    subGroup[Subgroup]
+    workspaceProject[Workspace project]
+    agentProject[Agent project]
+    workspaceAgent[Workspace agent]
+
+    topGroup --> subGroup
+
+    subGroup --> workspaceProject
+    subGroup --> agentProject
+    agentProject -.- workspaceAgent
+
+    class workspaceProject active;
+```
+
+## Configure the GitLab agent for workspaces
+
+To configure the `remote_development` module in the agent project:
+
+1. On the left sidebar, select **Search or go to** and find your project.
+1. In your project, create a `.gitlab/agents/<agentName>/config.yaml` file.
+   `agentName` is the name of the agent you configured when you set up workspace infrastructure.
+1. In `config.yaml`, use the following configuration for workspace settings:
+
+   ```yaml
+   remote_development:
+     enabled: true
+     dns_zone: "<workspaces.example.dev>" # DNS zone of the URL where workspaces are available
+   ```
+
+## Allow the GitLab agent in your group
+
+When you allow an agent in a group, the group and its subgroups can use that agent.
+Carefully consider the group where you allow the GitLab agent.
+
+To allow your GitLab agent in a group and its subgroups:
+
+1. On the left sidebar, select **Search or go to** and find your group.
+1. Select **Settings > Workspaces**.
+1. In the **Group agents** section, select the **All agents** tab.
+1. For the GitLab agent, select **Allow**.
+1. On the confirmation dialog, select **Allow agent**.
+
+## Grant workspace permissions
+
+Grant users with at least the Developer role for the workspace and agent projects
+the necessary permissions to create and manage workspaces. You can:
+
+- [Add users to a project](../project/members/index.md#add-users-to-a-project)
+- [Add users to a group](../group/index.md#add-users-to-a-group)
+
+## Generate TLS certificates
+
+A wildcard domain is required for workspace access because each workspace gets its own subdomain.
+You must generate TLS certificates for:
+
+- The domain `gitlab-workspaces-proxy` listens on (`GITLAB_WORKSPACES_PROXY_DOMAIN`).
+- The wildcard domain where workspaces are available (`GITLAB_WORKSPACES_WILDCARD_DOMAIN`).
+
+For example, if your base domain is `workspaces.example.dev`:
+
+- The `GITLAB_WORKSPACES_PROXY_DOMAIN` is `workspaces.example.dev`.
+- The `GITLAB_WORKSPACES_WILDCARD_DOMAIN` is `*.workspaces.example.dev`.
+- Individual workspaces are available at URLs like `workspace-1.workspaces.example.dev`.
+
+You can generate certificates from any certificate authority.
+If [`cert-manager`](https://cert-manager.io/docs/) is configured for your Kubernetes cluster,
+you can use it to create and renew TLS certificates automatically.
+
+To generate certificates manually:
+
+1. Install [Certbot](https://certbot.eff.org/) to enable HTTPS:
+
+   ```shell
+   brew install certbot
+   ```
+
+1. Generate Let's Encrypt certificates with ACME DNS and create `TXT` records in your DNS provider:
+
+   ```shell
+   export EMAIL="YOUR_EMAIL@example.dev"
+   export GITLAB_WORKSPACES_PROXY_DOMAIN="workspaces.example.dev"
+   export GITLAB_WORKSPACES_WILDCARD_DOMAIN="*.workspaces.example.dev"
+
+   certbot -d "${GITLAB_WORKSPACES_PROXY_DOMAIN}" \
+     -m "${EMAIL}" \
+     --config-dir ~/.certbot/config \
+     --logs-dir ~/.certbot/logs \
+     --work-dir ~/.certbot/work \
+     --manual \
+     --preferred-challenges dns certonly
+
+   certbot -d "${GITLAB_WORKSPACES_WILDCARD_DOMAIN}" \
+     -m "${EMAIL}" \
+     --config-dir ~/.certbot/config \
+     --logs-dir ~/.certbot/logs \
+     --work-dir ~/.certbot/work \
+     --manual \
+     --preferred-challenges dns certonly
+   ```
+
+1. Set the following environment variables with the certificate directories from the output:
+
+   ```shell
+   export WORKSPACES_DOMAIN_CERT="${HOME}/.certbot/config/live/${GITLAB_WORKSPACES_PROXY_DOMAIN}/fullchain.pem"
+   export WORKSPACES_DOMAIN_KEY="${HOME}/.certbot/config/live/${GITLAB_WORKSPACES_PROXY_DOMAIN}/privkey.pem"
+   export WILDCARD_DOMAIN_CERT="${HOME}/.certbot/config/live/${GITLAB_WORKSPACES_PROXY_DOMAIN}-0001/fullchain.pem"
+   export WILDCARD_DOMAIN_KEY="${HOME}/.certbot/config/live/${GITLAB_WORKSPACES_PROXY_DOMAIN}-0001/privkey.pem"
+   ```
+
+   Depending on your environment, the `certbot` command might save the certificate and key on a different path.
+   To get the exact path, run:
+
+   ```shell
+   certbot certificates \
+     --config-dir ~/.certbot/config \
+     --logs-dir ~/.certbot/logs \
+     --work-dir ~/.certbot/work
+   ```
+
+NOTE:
+You must renew your certificates when they expire.
+For example, Let's Encrypt certificates expire after three months.
+To automatically renew certificates, see [`cert-manager`](https://cert-manager.io/docs/).
+
+## Register a GitLab OAuth application
+
+To register an application on your GitLab instance:
+
+1. [Configure GitLab as an OAuth 2.0 identity provider](../../integration/oauth_provider.md).
+1. Set the redirect URI to `https://${GITLAB_WORKSPACES_PROXY_DOMAIN}/auth/callback`.
+1. Select the **Trusted** checkbox.
+1. Set the scopes to `api`, `read_user`, `openid`, and `profile`.
+1. Export your configuration values:
+
+   ```shell
+   export GITLAB_URL="https://gitlab.com"
+   export CLIENT_ID="your_application_id"
+   export CLIENT_SECRET="your_application_secret"
+   export REDIRECT_URI="https://${GITLAB_WORKSPACES_PROXY_DOMAIN}/auth/callback"
+   export SIGNING_KEY="make_up_a_random_key_consisting_of_letters_numbers_and_special_chars"
+   ```
+
+1. Store the client ID and generated secret securely. For examples, in 1Password.
+
+## Generate an SSH host key
+
+To generate an RSA key:
+
+```shell
+ssh-keygen -f ssh-host-key -N '' -t rsa
+export SSH_HOST_KEY=$(pwd)/ssh-host-key
+```
+
+As an alternative, you can also generate an ECDSA key.
+
+## Create Kubernetes secrets
+
+To create Kubernetes secrets:
+
+```shell
+kubectl create namespace gitlab-workspaces
+
+kubectl create secret generic gitlab-workspaces-proxy-config \
+  --namespace="gitlab-workspaces" \
+  --from-literal="auth.client_id=${CLIENT_ID}" \
+  --from-literal="auth.client_secret=${CLIENT_SECRET}" \
+  --from-literal="auth.host=${GITLAB_URL}" \
+  --from-literal="auth.redirect_uri=${REDIRECT_URI}" \
+  --from-literal="auth.signing_key=${SIGNING_KEY}" \
+  --from-literal="ssh.host_key=$(cat ${SSH_HOST_KEY})"
+
+kubectl create secret tls gitlab-workspace-proxy-tls \
+  --namespace="gitlab-workspaces" \
+  --cert="${WORKSPACES_DOMAIN_CERT}" \
+  --key="${WORKSPACES_DOMAIN_KEY}"
+
+kubectl create secret tls gitlab-workspace-proxy-wildcard-tls \
+  --namespace="gitlab-workspaces" \
+  --cert="${WILDCARD_DOMAIN_CERT}" \
+  --key="${WILDCARD_DOMAIN_KEY}"
+```
+
+## Install the proxy Helm chart
+
+To install the Helm chart for the proxy:
+
+1. Add the `helm` repository:
+
+   ```shell
+   helm repo add gitlab-workspaces-proxy \
+     https://gitlab.com/api/v4/projects/gitlab-org%2fworkspaces%2fgitlab-workspaces-proxy/packages/helm/devel
+   ```
+
+   For Helm chart 0.1.13 and earlier, use the following command:
+
+   ```shell
+   helm repo add gitlab-workspaces-proxy \
+     https://gitlab.com/api/v4/projects/gitlab-org%2fremote-development%2fgitlab-workspaces-proxy/packages/helm/devel
+   ```
+
+1. Install the chart:
+
+   ```shell
+   helm repo update
+
+   helm upgrade --install gitlab-workspaces-proxy \
+     gitlab-workspaces-proxy/gitlab-workspaces-proxy \
+     --version=0.1.16 \
+     --namespace="gitlab-workspaces" \
+     --set="ingress.enabled=true" \
+     --set="ingress.hosts[0].host=${GITLAB_WORKSPACES_PROXY_DOMAIN}" \
+     --set="ingress.hosts[0].paths[0].path=/" \
+     --set="ingress.hosts[0].paths[0].pathType=ImplementationSpecific" \
+     --set="ingress.hosts[1].host=${GITLAB_WORKSPACES_WILDCARD_DOMAIN}" \
+     --set="ingress.hosts[1].paths[0].path=/" \
+     --set="ingress.hosts[1].paths[0].pathType=ImplementationSpecific" \
+     --set="ingress.tls[0].hosts[0]=${GITLAB_WORKSPACES_PROXY_DOMAIN}" \
+     --set="ingress.tls[0].secretName=gitlab-workspace-proxy-tls" \
+     --set="ingress.tls[1].hosts[0]=${GITLAB_WORKSPACES_WILDCARD_DOMAIN}" \
+     --set="ingress.tls[1].secretName=gitlab-workspace-proxy-wildcard-tls" \
+     --set="ingress.className=nginx"
+   ```
+
+   If you're using a different Ingress class, modify the `ingress.className` parameter.
+
+## Verify your setup
+
+1. Verify the Ingress configuration for the `gitlab-workspaces` namespace:
+
+   ```shell
+   kubectl -n gitlab-workspaces get ingress
+   ```
+
+1. Verify the pods are running:
+
+   ```shell
+   kubectl -n gitlab-workspaces get pods
+   ```
+
+## Update your DNS records
+
+To update your DNS records:
+
+1. Point `${GITLAB_WORKSPACES_PROXY_DOMAIN}` and `${GITLAB_WORKSPACES_WILDCARD_DOMAIN}`
+   to the load balancer exposed by the Ingress controller.
+1. Check if `gitlab-workspaces-proxy` is accessible:
+
+   ```shell
+   curl --verbose --location ${GITLAB_WORKSPACES_PROXY_DOMAIN}
+   ```
+
+   This command returns a `400 Bad Request` error until you create a workspace.
+
+1. From another terminal, check the proxy logs::
+
+   ```shell
+   kubectl -n gitlab-workspaces logs -f -l app.kubernetes.io/name=gitlab-workspaces-proxy
+   ```
+
+   This command returns a `could not find upstream workspace upstream not found` error until you create a workspace.
+
+## Update the GitLab agent configuration
+
+If you deploy the Helm chart for the proxy to a namespace other than `gitlab-workspaces`,
+update your [GitLab agent configuration](gitlab_agent_configuration.md):
+
+```yaml
+remote_development:
+  gitlab_workspaces_proxy:
+    namespace: "<custom-gitlab-workspaces-proxy-namespace>"
+```
+
+## Related topics
+
+- [Configure workspaces](configuration.md)
+- [GitLab agent configuration](gitlab_agent_configuration.md)

doc/user/workspace/set_up_workspaces_proxy.md

 ---
-stage: Create
-group: Remote Development
-info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments
-description: "Create a GitLab workspaces proxy to authenticate and authorize workspaces in your cluster."
+redirect_to: 'set_up_gitlab_agent_and_proxies.md'
+remove_date: '2025-04-20'
 ---
 
-# Tutorial: Set up the GitLab workspaces proxy
+<!-- markdownlint-disable -->
 
-In this tutorial, you'll learn how to set up the GitLab workspaces proxy
-to authenticate and authorize [workspaces](index.md) in your cluster.
+This document was moved to [another location](set_up_gitlab_agent_and_proxies.md).
 
-To set up `gitlab-workspaces-proxy`, you're going to:
-
-1. [Generate TLS certificates](#generate-tls-certificates).
-1. [Register an app on your GitLab instance](#register-an-app-on-your-gitlab-instance).
-1. [Generate an SSH host key](#generate-an-ssh-host-key).
-1. [Create Kubernetes secrets](#create-kubernetes-secrets).
-1. [Install the Helm chart for the proxy](#install-the-helm-chart-for-the-proxy).
-1. [Verify Kubernetes resources](#verify-kubernetes-resources).
-1. [Update your DNS records](#update-your-dns-records).
-1. [Update the GitLab agent configuration](#update-the-gitlab-agent-configuration).
-
-## Prerequisites
-
-- An installed Ingress controller
-- A running Kubernetes cluster
-- `helm` 3.11.0 and later and `kubectl` on your local machine
-
-## Generate TLS certificates
-
-You must generate TLS certificates for:
-
-- The domain `gitlab-workspaces-proxy` listens on (`GITLAB_WORKSPACES_PROXY_DOMAIN`).
-- The domain workspaces are available on (`GITLAB_WORKSPACES_WILDCARD_DOMAIN`).
-
-You can generate certificates from any certificate authority.
-If [`cert-manager`](https://cert-manager.io/docs/) is configured for your Kubernetes cluster,
-you can use it to create and renew TLS certificates automatically.
-Alternatively, to generate TLS certificates manually:
-
-1. Install [Certbot](https://certbot.eff.org/) to enable HTTPS:
-
-   ```shell
-   brew install certbot
-   ```
-
-1. Generate Let's Encrypt certificates with ACME DNS and create `TXT` records in your DNS provider:
-
-   ```shell
-   export EMAIL="YOUR_EMAIL@example.dev"
-   export GITLAB_WORKSPACES_PROXY_DOMAIN="workspaces.example.dev"
-   export GITLAB_WORKSPACES_WILDCARD_DOMAIN="*.workspaces.example.dev"
-
-   certbot -d "${GITLAB_WORKSPACES_PROXY_DOMAIN}" \
-     -m "${EMAIL}" \
-     --config-dir ~/.certbot/config \
-     --logs-dir ~/.certbot/logs \
-     --work-dir ~/.certbot/work \
-     --manual \
-     --preferred-challenges dns certonly
-
-   certbot -d "${GITLAB_WORKSPACES_WILDCARD_DOMAIN}" \
-     -m "${EMAIL}" \
-     --config-dir ~/.certbot/config \
-     --logs-dir ~/.certbot/logs \
-     --work-dir ~/.certbot/work \
-     --manual \
-     --preferred-challenges dns certonly
-   ```
-
-1. Update the following environment variables with the certificate directories from the output:
-
-   ```shell
-   export WORKSPACES_DOMAIN_CERT="${HOME}/.certbot/config/live/${GITLAB_WORKSPACES_PROXY_DOMAIN}/fullchain.pem"
-   export WORKSPACES_DOMAIN_KEY="${HOME}/.certbot/config/live/${GITLAB_WORKSPACES_PROXY_DOMAIN}/privkey.pem"
-   export WILDCARD_DOMAIN_CERT="${HOME}/.certbot/config/live/${GITLAB_WORKSPACES_PROXY_DOMAIN}-0001/fullchain.pem"
-   export WILDCARD_DOMAIN_KEY="${HOME}/.certbot/config/live/${GITLAB_WORKSPACES_PROXY_DOMAIN}-0001/privkey.pem"
-   ```
-
-   Depending on your environment, the `certbot` command might save the certificate and key on a different path.
-   To get the exact path, check the output of the following command:
-
-   ```shell
-   certbot certificates \
-     --config-dir ~/.certbot/config \
-     --logs-dir ~/.certbot/logs \
-     --work-dir ~/.certbot/work
-   ```
-
-NOTE:
-You must renew your certificates when they expire.
-For example, Let's Encrypt certificates are valid for three months by default.
-To renew certificates automatically, see [`cert-manager`](https://cert-manager.io/docs/).
-
-Now that you've generated the certificates, it's time to register an app on your GitLab instance.
-
-## Register an app on your GitLab instance
-
-To register an app on your GitLab instance:
-
-1. [Configure GitLab as an OAuth 2.0 identity provider](../../integration/oauth_provider.md).
-1. Set the redirect URI to `https://${GITLAB_WORKSPACES_PROXY_DOMAIN}/auth/callback`.
-1. Select the **Trusted** checkbox.
-1. Set the scopes to `api`, `read_user`, `openid`, and `profile`.
-1. Export your `GITLAB_URL`, `CLIENT_ID`, `CLIENT_SECRET`, `REDIRECT_URI`, and `SIGNING_KEY`:
-
-   ```shell
-   export GITLAB_URL="https://gitlab.com"
-   export CLIENT_ID="your_application_id"
-   export CLIENT_SECRET="your_application_secret"
-   export REDIRECT_URI="https://${GITLAB_WORKSPACES_PROXY_DOMAIN}/auth/callback"
-   export SIGNING_KEY="make_up_a_random_key_consisting_of_letters_numbers_and_special_chars"
-   ```
-
-1. Store the client ID and generated secret in a safe place (for example, 1Password).
-
-Next, you'll generate an SSH host key.
-
-## Generate an SSH host key
-
-To generate an RSA key, run this command:
-
-```shell
-ssh-keygen -f ssh-host-key -N '' -t rsa
-export SSH_HOST_KEY=$(pwd)/ssh-host-key
-```
-
-You can also generate an ECDSA key instead.
-
-Next, you'll create Kubernetes secrets for the proxy.
-
-## Create Kubernetes secrets
-
-To create Kubernetes secrets:
-
-```shell
-kubectl create namespace gitlab-workspaces
-
-kubectl create secret generic gitlab-workspaces-proxy-config \
-  --namespace="gitlab-workspaces" \
-  --from-literal="auth.client_id=${CLIENT_ID}" \
-  --from-literal="auth.client_secret=${CLIENT_SECRET}" \
-  --from-literal="auth.host=${GITLAB_URL}" \
-  --from-literal="auth.redirect_uri=${REDIRECT_URI}" \
-  --from-literal="auth.signing_key=${SIGNING_KEY}" \
-  --from-literal="ssh.host_key=$(cat ${SSH_HOST_KEY})"
-
-kubectl create secret tls gitlab-workspace-proxy-tls \
-  --namespace="gitlab-workspaces" \
-  --cert="${WORKSPACES_DOMAIN_CERT}" \
-  --key="${WORKSPACES_DOMAIN_KEY}"
-
-kubectl create secret tls gitlab-workspace-proxy-wildcard-tls \
-  --namespace="gitlab-workspaces" \
-  --cert="${WILDCARD_DOMAIN_CERT}" \
-  --key="${WILDCARD_DOMAIN_KEY}"
-```
-
-Now it's time to install the Helm chart for the proxy.
-
-## Install the Helm chart for the proxy
-
-To install the Helm chart for the proxy:
-
-1. Add the `helm` repository:
-
-   ```shell
-   helm repo add gitlab-workspaces-proxy \
-     https://gitlab.com/api/v4/projects/gitlab-org%2fworkspaces%2fgitlab-workspaces-proxy/packages/helm/devel
-   ```
-
-   For Helm chart 0.1.13 and earlier, use the following command:
-
-   ```shell
-   helm repo add gitlab-workspaces-proxy \
-     https://gitlab.com/api/v4/projects/gitlab-org%2fremote-development%2fgitlab-workspaces-proxy/packages/helm/devel
-   ```
-
-1. Modify the `ingress.className` parameter if you're using a different Ingress class:
-
-   ```shell
-   helm repo update
-
-   helm upgrade --install gitlab-workspaces-proxy \
-     gitlab-workspaces-proxy/gitlab-workspaces-proxy \
-     --version=0.1.16 \
-     --namespace="gitlab-workspaces" \
-     --set="ingress.enabled=true" \
-     --set="ingress.hosts[0].host=${GITLAB_WORKSPACES_PROXY_DOMAIN}" \
-     --set="ingress.hosts[0].paths[0].path=/" \
-     --set="ingress.hosts[0].paths[0].pathType=ImplementationSpecific" \
-     --set="ingress.hosts[1].host=${GITLAB_WORKSPACES_WILDCARD_DOMAIN}" \
-     --set="ingress.hosts[1].paths[0].path=/" \
-     --set="ingress.hosts[1].paths[0].pathType=ImplementationSpecific" \
-     --set="ingress.tls[0].hosts[0]=${GITLAB_WORKSPACES_PROXY_DOMAIN}" \
-     --set="ingress.tls[0].secretName=gitlab-workspace-proxy-tls" \
-     --set="ingress.tls[1].hosts[0]=${GITLAB_WORKSPACES_WILDCARD_DOMAIN}" \
-     --set="ingress.tls[1].secretName=gitlab-workspace-proxy-wildcard-tls" \
-     --set="ingress.className=nginx"
-   ```
-
-Let's now verify Kubernetes resources.
-
-## Verify Kubernetes resources
-
-1. Verify the Ingress class, hosts, address, and port for the `gitlab-workspaces` namespace:
-
-   ```shell
-   kubectl -n gitlab-workspaces get ingress
-   ```
-
-1. Verify the pods are running:
-
-   ```shell
-   kubectl -n gitlab-workspaces get pods
-   ```
-
-You can now start updating your DNS records.
-
-## Update your DNS records
-
-To update your DNS records:
-
-1. Point `${GITLAB_WORKSPACES_PROXY_DOMAIN}` and `${GITLAB_WORKSPACES_WILDCARD_DOMAIN}`
-   to the load balancer exposed by the Ingress controller.
-1. From a terminal, run this command to check if `gitlab-workspaces-proxy` is accessible:
-
-   ```shell
-   curl --verbose --location ${GITLAB_WORKSPACES_PROXY_DOMAIN}
-   ```
-
-   This command returns a `400 Bad Request` error until you create a workspace in GitLab.
-
-1. From another terminal, run this command:
-
-   ```shell
-   kubectl -n gitlab-workspaces logs -f -l app.kubernetes.io/name=gitlab-workspaces-proxy
-   ```
-
-   The logs show a `could not find upstream workspace upstream not found` error.
-
-## Update the GitLab agent configuration
-
-If you deploy the Helm chart for the proxy to any namespace other than `gitlab-workspaces`,
-update the namespace in the [GitLab agent configuration](gitlab_agent_configuration.md):
-
-```yaml
-remote_development:
-  gitlab_workspaces_proxy:
-    namespace: "<custom-gitlab-workspaces-proxy-namespace>"
-```
-
-You're all set! You can now use the GitLab workspaces proxy to
-authenticate and authorize [workspaces](index.md) in your cluster.
+<!-- This redirect file can be deleted after <2025-04-20>. -->
+<!-- Redirects that point to other docs in the same project expire in three months. -->
+<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. -->
+<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html -->