Merge branch 'bl-workspaces-troubleshooting-page' into 'master'

Workspaces troubleshooting page

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



Merged-by: Jon Glassman <jglassman@gitlab.com>
Approved-by: Amy Qualls <aqualls@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

@@ -230,38 +230,9 @@ USER gitlab-workspaces
 
 ## Related topics
 
+- [Tutorial: Set up GitLab agent and proxies](set_up_gitlab_agent_and_proxies.md)
+- [Workspace settings](settings.md)
+- [Workspace configuration](configuration.md)
+- [Troubleshooting Workspaces](workspaces_troubleshooting.md)
 - [Quickstart guide for GitLab remote development workspaces](https://go.gitlab.com/AVKFvy)
 - [Set up your infrastructure for on-demand, cloud-based development environments in GitLab](https://go.gitlab.com/dp75xo)
-
-## Troubleshooting
-
-When working with workspaces, you might encounter the following issues.
-
-### Error: `Failed to renew lease`
-
-Creating a workspace can fail due to a known issue in the GitLab agent for Kubernetes.
-The following error message might appear in the agent's log:
-
-```plaintext
-{"level":"info","time":"2023-01-01T00:00:00.000Z","msg":"failed to renew lease gitlab-agent-remote-dev-dev/agent-123XX-lock: timed out waiting for the condition\n","agent_id":XXXX}
-```
-
-This issue occurs when an agent instance cannot renew its leadership lease, which results
-in the shutdown of leader-only modules including the `remote_development` module.
-To resolve this issue, restart the agent instance.
-
-### Error: `No agents available to create workspaces`
-
-When you create a workspace in a project, you might get the following error:
-
-```plaintext
-No agents available to create workspaces. Please consult Workspaces documentation for troubleshooting.
-```
-
-To resolve this issue:
-
-- If you do not have at least the Developer role for the workspace and agent projects, contact your administrator.
-- If the ancestor groups of the project do not have an allowed agent,
-  [allow an agent](gitlab_agent_configuration.md#allow-a-cluster-agent-for-workspaces-in-a-group) for any of these groups.
-- If the `remote_development` module is disabled for the GitLab agent,
-  set [`enabled`](settings.md#enabled) to `true`.

doc/user/workspace/create_image.md

@@ -109,3 +109,7 @@ components:
 ```
 
 You're all set! You can now use this custom image with any [workspace](index.md) you create in GitLab.
+
+## Related topics
+
+- [Troubleshooting Workspaces](workspaces_troubleshooting.md)

doc/user/workspace/gitlab_agent_configuration.md

@@ -73,7 +73,7 @@ To allow a cluster agent for workspaces in a group:
 
 GitLab updates the status of the selected agent to **Allowed**, and displays the agent in the **Allowed agents** tab.
 
-## Remove an allowed cluster agent for workspaces within a group
+## Remove an allowed cluster agent for workspaces in a group
 
 Prerequisites:
 
@@ -123,3 +123,4 @@ For more information about configuring `user_access`, see
 - [Tutorial: Set up GitLab agent and proxies](set_up_gitlab_agent_and_proxies.md)
 - [Workspace settings](settings.md)
 - [Workspace configuration](configuration.md)
+- [Troubleshooting Workspaces](workspaces_troubleshooting.md)

doc/user/workspace/index.md

@@ -271,3 +271,7 @@ see [Create a custom workspace image that supports arbitrary user IDs](../worksp
 
 For more information, see the
 [OpenShift documentation](https://docs.openshift.com/container-platform/4.12/openshift_images/create-images.html#use-uid_create-images).
+
+## Related topics
+
+- [Troubleshooting Workspaces](workspaces_troubleshooting.md)

doc/user/workspace/workspaces_troubleshooting.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."
+---
+
+# Troubleshooting workspaces
+
+When working with GitLab workspaces, you might encounter the following issues.
+
+## Error: `Failed to renew lease`
+
+When creating a workspace, you might encounter the following error message in the agent's log:
+
+```plaintext
+{"level":"info","time":"2023-01-01T00:00:00.000Z","msg":"failed to renew lease gitlab-agent-remote-dev-dev/agent-123XX-lock: timed out waiting for the condition\n","agent_id":XXXX}
+```
+
+The error is because of a known issue in the GitLab agent for Kubernetes.
+This error occurs when an agent instance cannot renew its leadership lease, causing leader-only modules like `remote_development` to shut down.
+
+To resolve this issue:
+
+1. Restart the agent instance.
+1. If the issue persists, check your Kubernetes cluster's health and connectivity.
+
+## Error: `No agents available to create workspaces`
+
+When you create a workspace in a project, you might get the following error:
+
+```plaintext
+No agents available to create workspaces. Please consult Workspaces documentation for troubleshooting.
+```
+
+To resolve this issue:
+
+1. Check agent configuration:
+
+   - Verify the `remote_development` module is enabled in your agent configuration:
+
+     ```yaml
+     remote_development:
+       enabled: true
+     ```
+
+     - If the `remote_development` module is disabled for the GitLab agent,
+     set [`enabled`](settings.md#enabled) to `true`.
+
+1. Check permissions:
+
+   - Ensure you have at least the Developer role for both the workspace project and agent project.
+     - If you do not have at least the Developer role for the workspace and agent projects, contact your administrator.
+   - Verify the agent is allowed in an ancestor group of your workspace project.
+     - If the ancestor groups of the project do not have an allowed agent,
+    [allow an agent](gitlab_agent_configuration.md#allow-a-cluster-agent-for-workspaces-in-a-group)
+    for any of these groups.
+
+1. Check agent logs:
+
+   ```shell
+   kubectl logs -f -l app=gitlab-agent -n gitlab-workspaces
+   ```
+
+<!--- Other suggested topics:
+
+## DNS configuration
+
+## Workspace stops unexpectedly
+
+## Workspace creation fails due to quotas
+
+## Network connectivity
+
+## SSH connection failures
+
+### Network policy restrictions
+
+-->

ee/app/assets/javascripts/workspaces/dropdown_group/components/workspaces_dropdown_group.vue

@@ -34,9 +34,9 @@ export const i18n = {
 };
 
 const workspacesHelpPath = helpPagePath('user/workspace/index.md');
-const workspacesTroubleshootingDocsPath = helpPagePath('user/workspace/configuration.html', {
-  anchor: 'troubleshooting',
-});
+const workspacesTroubleshootingDocsPath = helpPagePath(
+  'user/workspace/workspaces_troubleshooting.html',
+);
 
 export default {
   components: {

ee/app/assets/javascripts/workspaces/user/pages/create.vue

@@ -78,9 +78,9 @@ export const i18n = {
 };
 
 export const devfileHelpPath = helpPagePath('user/workspace/index.md#devfile');
-export const workspacesTroubleshootingDocsPath = helpPagePath('user/workspace/configuration.html', {
-  anchor: 'troubleshooting',
-});
+export const workspacesTroubleshootingDocsPath = helpPagePath(
+  'user/workspace/workspaces_troubleshooting.html',
+);
 
 export default {
   components: {

ee/spec/frontend/workspaces/user/pages/create_spec.js

@@ -243,7 +243,7 @@ describe('workspaces/user/pages/create.vue', () => {
 
     it('shows a link to the troubleshooting page', () => {
       expect(wrapper.findByTestId('workspaces-troubleshooting-doc-link').attributes('href')).toBe(
-        '/help/user/workspace/configuration.html#troubleshooting',
+        '/help/user/workspace/workspaces_troubleshooting.html',
       );
     });
   });

ee/spec/frontend/workspaces/workspaces_dropdown_group/components/workspaces_dropdown_group_spec.js

@@ -274,7 +274,7 @@ describe('workspaces/dropdown_group/components/workspaces_dropdown_group.vue', (
 
     it('shows a link to the troubleshooting page', () => {
       expect(wrapper.findByTestId('workspaces-troubleshooting-doc-link').attributes('href')).toBe(
-        '/help/user/workspace/configuration.html#troubleshooting',
+        '/help/user/workspace/workspaces_troubleshooting.html',
       );
     });
   });