Add latest changes from gitlab-org/gitlab@master

8 files changed, 150 insertions, 195 deletions

diff --git a/doc/administration/geo/replication/version_specific_updates.md b/doc/administration/geo/replication/version_specific_updates.md
index 41e9dbe677c..b7095426ad7 100644
--- a/doc/administration/geo/replication/version_specific_updates.md
+++ b/doc/administration/geo/replication/version_specific_updates.md
@@ -11,10 +11,6 @@ Check this document if it includes instructions for the version you are updating
 These steps go together with the [general steps](updating_the_geo_nodes.md#general-update-steps)
 for updating Geo nodes.
 
-## Updating to GitLab 13.8
-
-We've detected an issue with the `FetchRemove` call that is used by Geo secondaries. This causes performance issues as we execute reference transaction hooks for each updated reference. Please hold off upgrading until this is in [the 13.8.1 patch release.](https://gitlab.com/gitlab-org/gitaly/-/merge_requests/3002). More details are available [in this issue](https://gitlab.com/gitlab-org/git/-/issues/79).
-
 ## Updating to GitLab 13.7
 
 We've detected an issue with the `FetchRemove` call that is used by Geo secondaries. This causes performance issues as we execute reference transaction hooks for each updated reference. Please hold off upgrading until this is in [the 13.7.5 patch release.](https://gitlab.com/gitlab-org/gitaly/-/merge_requests/3002). More details are available [in this issue](https://gitlab.com/gitlab-org/git/-/issues/79).
diff --git a/doc/administration/reference_architectures/1k_users.md b/doc/administration/reference_architectures/1k_users.md
index 161964353f5..c1344274c9a 100644
--- a/doc/administration/reference_architectures/1k_users.md
+++ b/doc/administration/reference_architectures/1k_users.md
@@ -45,7 +45,7 @@ To install GitLab for this default reference architecture, use the standard
 
 You can also optionally configure GitLab to use an [external PostgreSQL service](../postgresql/external.md)
 or an [external object storage service](../object_storage.md) for added
-performance and reliability at a reduced complexity cost.
+performance and reliability at an increased complexity cost.
 
 ## Configure Advanced Search **(STARTER ONLY)**
 
diff --git a/doc/development/agent/routing.md b/doc/development/agent/routing.md
index 43cc78ccdfb..4b02b65f484 100644
--- a/doc/development/agent/routing.md
+++ b/doc/development/agent/routing.md
@@ -134,90 +134,97 @@ of the `kas` receiving the request from the _external_ endpoint to retry and re-
 requests. This method ensures a single central component for each request can determine
 how a request is routed, rather than distributing the decision across several `kas` instances.
 
-### API definitions
+### Reverse gRPC tunnel
+
+This section explains how the `agentk` -> `kas` reverse gRPC tunnel is implemented.
+
+<i class="fa fa-youtube-play youtube" aria-hidden="true"></i>
+For a video overview of how some of the blocks map to code, see
+[GitLab Kubernetes Agent reverse gRPC tunnel architecture and code overview
+](https://www.youtube.com/watch?v=9pnQF76hyZc).
+
+#### High level schema
+
+In this example, `Server side of module A` exposes its API to get the `Pod` list
+on the `Public API gRPC server`. When it receives a request, it must determine
+the agent ID from it, then call the proxying code which forwards the request to
+a suitable `agentk` that can handle it.
+
+The `Agent side of module A` exposes the same API on the `Internal gRPC server`.
+When it receives the request, it needs to handle it (such as retrieving and returning
+the `Pod` list).
+
+This schema describes how reverse tunneling is handled fully transparently
+for modules, so you can add new features:
+
+```mermaid
+graph TB
+    subgraph kas
+        server-internal-grpc-server[Internal gRPC server]
+        server-api-grpc-server[Public API gRPC server]
+        server-module-a[Server side of module A]
+        server-module-b[Server side of module B]
+    end
+    subgraph agentk
+        agent-internal-grpc-server[Internal gRPC server]
+        agent-module-a[Agent side of module A]
+        agent-module-b[Agent side of module B]
+    end
+
+    agent-internal-grpc-server -- request --> agent-module-a
+    agent-internal-grpc-server -- request --> agent-module-b
+
+    server-module-a-. expose API on .-> server-internal-grpc-server
+    server-module-b-. expose API on .-> server-api-grpc-server
+
+    server-internal-grpc-server -- proxy request --> agent-internal-grpc-server
+    server-api-grpc-server -- proxy request --> agent-internal-grpc-server
+```
+
+#### Implementation schema
+
+`HandleTunnelConnection()` is called with the server-side interface of the reverse
+tunnel. It registers the connection and blocks, waiting for a request to proxy
+through the connection.
+
+`HandleIncomingConnection()` is called with the server-side interface of the incoming
+connection. It registers the connection and blocks, waiting for a matching tunnel
+to proxy the connection through.
+
+After it has two connections that match, `Connection registry` starts bi-directional
+data streaming:
 
-```proto
-syntax = "proto3";
-
-import "google/protobuf/timestamp.proto";
-
-message KasAddress {
-    string ip = 1;
-    uint32 port = 2;
-}
-
-message ConnectedAgentInfo {
-    // Agent id.
-    int64 id = 1;
-    // Identifies a particular agentk->kas connection. Randomly generated when agent connects.
-    int64 connection_id = 2;
-    string version = 3;
-    string commit = 4;
-    // Pod namespace.
-    string pod_namespace = 5;
-    // Pod name.
-    string pod_name = 6;
-    // When the connection was established.
-    google.protobuf.Timestamp connected_at = 7;
-    KasAddress kas_address = 8;
-    // What else do we need?
-}
-
-message KasInstanceInfo {
-    string version = 1;
-    string commit = 2;
-    KasAddress address = 3;
-    // What else do we need?
-}
-
-message ConnectedAgentsForProjectRequest {
-    int64 project_id = 1;
-}
-
-message ConnectedAgentsForProjectResponse {
-    // There may 0 or more agents with the same id, depending on the number of running Pods.
-    repeated ConnectedAgentInfo agents = 1;
-}
-
-message ConnectedAgentsByIdRequest {
-    int64 agent_id = 1;
-}
-
-message ConnectedAgentsByIdResponse {
-    repeated ConnectedAgentInfo agents = 1;
-}
-
-// API for use by GitLab.
-service KasApi {
-    // Connected agents for a particular configuration project.
-    rpc ConnectedAgentsForProject (ConnectedAgentsForProjectRequest) returns (ConnectedAgentsForProjectResponse) {
-    }
-    // Connected agents for a particular agent id.
-    rpc ConnectedAgentsById (ConnectedAgentsByIdRequest) returns (ConnectedAgentsByIdResponse) {
-    }
-    // Depends on the need, but here is the call from the example above.
-    rpc GetPods (GetPodsRequest) returns (GetPodsResponse) {
-    }
-}
-
-message Pod {
-    string namespace = 1;
-    string name = 2;
-}
-
-message GetPodsRequest {
-    int64 agent_id = 1;
-    int64 connection_id = 2;
-}
-
-message GetPodsResponse {
-    repeated Pod pods = 1;
-}
-
-// Internal API for use by kas for kas -> kas calls.
-service KasInternal {
-    // Depends on the need, but here is the call from the example above.
-    rpc GetPods (GetPodsRequest) returns (GetPodsResponse) {
-    }
-}
+```mermaid
+graph TB
+    subgraph kas
+        server-tunnel-module[Server tunnel module]
+        connection-registry[Connection registry]
+        server-internal-grpc-server[Internal gRPC server]
+        server-api-grpc-server[Public API gRPC server]
+        server-module-a[Server side of module A]
+        server-module-b[Server side of module B]
+    end
+    subgraph agentk
+        agent-internal-grpc-server[Internal gRPC server]
+        agent-tunnel-module[Agent tunnel module]
+        agent-module-a[Agent side of module A]
+        agent-module-b[Agent side of module B]
+    end
+
+    server-tunnel-module -- "HandleTunnelConnection()" --> connection-registry
+    server-internal-grpc-server -- "HandleIncomingConnection()" --> connection-registry
+    server-api-grpc-server -- "HandleIncomingConnection()" --> connection-registry
+    server-module-a-. expose API on .-> server-internal-grpc-server
+    server-module-b-. expose API on .-> server-api-grpc-server
+
+    agent-tunnel-module -- "establish tunnel, receive request" --> server-tunnel-module
+    agent-tunnel-module -- make request --> agent-internal-grpc-server
+    agent-internal-grpc-server -- request --> agent-module-a
+    agent-internal-grpc-server -- request --> agent-module-b
 ```
+
+### API definitions
+
+- [`agent_tracker/agent_tracker.proto`](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/master/internal/module/agent_tracker/agent_tracker.proto)
+- [`agent_tracker/rpc/rpc.proto`](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/master/internal/module/agent_tracker/rpc/rpc.proto)
+- [`reverse_tunnel/rpc/rpc.proto`](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/master/internal/module/reverse_tunnel/rpc/rpc.proto)
diff --git a/doc/development/import_project.md b/doc/development/import_project.md
index dfe6153ad45..a4917cc0c3d 100644
--- a/doc/development/import_project.md
+++ b/doc/development/import_project.md
@@ -170,7 +170,7 @@ The last option is to import a project using a Rails console:
 
    Gitlab::ImportExport::RepoRestorer.new(path_to_bundle: repo_path,
                                           shared: shared,
-                                          project: project).restore
+                                          importable: project).restore
    ```
 
    We are storing all import failures in the `import_failures` data table.
diff --git a/doc/gitlab-basics/create-issue.md b/doc/gitlab-basics/create-issue.md
index 39e47690264..ab0cec6e058 100644
--- a/doc/gitlab-basics/create-issue.md
+++ b/doc/gitlab-basics/create-issue.md
@@ -1,8 +1,8 @@
 ---
-redirect_to: '../user/project/issues/index.md#viewing-and-managing-issues'
+redirect_to: '../user/project/issues/index.md#view-and-manage-issues'
 ---
 
-This document was moved to [another location](../user/project/issues/index.md#viewing-and-managing-issues).
+This document was moved to [another location](../user/project/issues/index.md#view-and-manage-issues).
 
 <!-- This redirect file can be deleted after February 1, 2021. -->
 <!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->
diff --git a/doc/user/index.md b/doc/user/index.md
index 3b2acfab34c..598c47963b5 100644
--- a/doc/user/index.md
+++ b/doc/user/index.md
@@ -43,7 +43,7 @@ GitLab is a Git-based platform that integrates a great number of essential tools
 - Hosting code in repositories with version control.
 - Tracking proposals for new implementations, bug reports, and feedback with a
   fully featured [Issue Tracker](project/issues/index.md#issues-list).
-- Organizing and prioritizing with [Issue Boards](project/issues/index.md#issue-boards).
+- Organizing and prioritizing with [Issue Boards](project/issue_board.md).
 - Reviewing code in [Merge Requests](project/merge_requests/index.md) with live-preview changes per
   branch with [Review Apps](../ci/review_apps/index.md).
 - Building, testing, and deploying with built-in [Continuous Integration](../ci/README.md).
diff --git a/doc/user/project/issues/index.md b/doc/user/project/issues/index.md
index d07905c0ead..16ef4a05cc2 100644
--- a/doc/user/project/issues/index.md
+++ b/doc/user/project/issues/index.md
@@ -6,33 +6,27 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 
 # Issues **(CORE)**
 
-Issues are the fundamental medium for collaborating on ideas and planning work in GitLab.
+Issues are the fundamental mechanism in GitLab to collaborate on ideas, solve
+problems, and plan work.
 
-## Overview
+Using issues, you can share and discuss proposals (both before and during their
+implementation) between you and your team, and outside collaborators.
 
-The GitLab issue tracker is an advanced tool for collaboratively developing ideas, solving problems,
-and planning work.
+You can use issues for many purposes, customized to your needs and workflow.
+Common use cases include:
 
-Issues can allow sharing and discussion of proposals before, and during,
-their implementation between:
+- Discussing the implementation of a new idea.
+- Tracking tasks and work status.
+- Accepting feature proposals, questions, support requests, or bug reports.
+- Elaborating on new code implementations.
 
-- You and your team.
-- Outside collaborators.
+For more information about using issues, see the
+[Always start a discussion with an issue](https://about.gitlab.com/blog/2016/03/03/start-with-an-issue/)
+GitLab blog post.
 
-They can also be used for a variety of other purposes, customized to your
-needs and workflow.
-
-Issues are always associated with a specific project. If you have multiple projects in a group,
-you can view all of the issues collectively at the group level.
-
-**Common use cases include:**
-
-- Discussing the implementation of a new idea
-- Tracking tasks and work status
-- Accepting feature proposals, questions, support requests, or bug reports
-- Elaborating on new code implementations
-
-See also [Always start a discussion with an issue](https://about.gitlab.com/blog/2016/03/03/start-with-an-issue/).
+Issues are always associated with a specific project. If you have multiple
+projects in a group, you can view all of the issues collectively at the group
+level.
 
 <i class="fa fa-youtube-play youtube" aria-hidden="true"></i>
 To learn how our Strategic Marketing department uses GitLab issues with [labels](../labels.md) and
@@ -41,63 +35,30 @@ To learn how our Strategic Marketing department uses GitLab issues with [labels]
 
 ## Parts of an issue
 
-Issues contain a variety of content and metadata, enabling a large range of flexibility
-in how they are used. Each issue can contain the following attributes, though not all items
-must be set.
-
-<table class="borderless-table fixed-table">
-<tr>
-    <td>
-        <ul>
-            <li>Content</li>
-            <ul>
-                <li>Title</li>
-                <li>Description and tasks</li>
-                <li>Comments and other activity</li>
-            </ul>
-            <li>People</li>
-            <ul>
-                <li>Author</li>
-                <li>Assignee(s)</li>
-            </ul>
-            <li>State</li>
-            <ul>
-                <li>State (open or closed)</li>
-                <li>Health status (on track, needs attention, or at risk)</li>
-                <li>Confidentiality</li>
-                <li>Tasks (completed vs. outstanding)</li>
-            </ul>
-        </ul>
-    </td>
-    <td>
-        <ul>
-            <li>Planning and tracking</li>
-            <ul>
-                <li>Milestone</li>
-                <li>Due date</li>
-                <li>Weight</li>
-                <li>Time tracking</li>
-                <li>Labels</li>
-                <li>Votes</li>
-                <li>Reaction emoji</li>
-                <li>Linked issues</li>
-                <li>Assigned epic</li>
-                <li>Unique issue number and URL</li>
-            </ul>
-       </ul>
-    </td>
-</tr>
-</table>
-
-## Viewing and managing issues
-
-While you can view and manage details of an issue on the [issue page](#issue-page),
-you can also work with multiple issues at a time using:
-
-- [Issues List](#issues-list).
-- [Issue Boards](#issue-boards).
-- Issue references.
-- [Epics](#epics) **(PREMIUM)**.
+Issues have a flexible content and metadata structure. Here are some of the
+elements you can provide in an issue:
+
+- Title
+- Description and tasks
+- Comments and other activity
+- Author
+- Assignees
+- State (open or closed)
+- Health status (on track, needs attention, or at risk)
+- Confidentiality
+- Tasks (completed vs. outstanding)
+- Milestone
+- Due date
+- Weight
+- Time tracking
+- Labels
+- Votes
+- Reaction emoji
+- Linked issues
+- Assigned epic
+- Unique issue number and URL
+
+## View and manage issues
 
 Key actions for issues include:
 
@@ -105,7 +66,17 @@ Key actions for issues include:
 - [Moving issues](managing_issues.md#moving-issues)
 - [Closing issues](managing_issues.md#closing-issues)
 - [Deleting issues](managing_issues.md#deleting-issues)
-- [Promoting issues](managing_issues.md#promote-an-issue-to-an-epic) **(PREMIUM)**
+- [Promoting issues](managing_issues.md#promote-an-issue-to-an-epic)
+
+Although you can view and manage details of an issue on the [issue page](#issue-page),
+you can also work with several issues at a time by using these features:
+
+- [Issues List](#issues-list): View a list of issues in a project or group.
+- [Issue Boards](../issue_board.md): Organize issues with a project management
+  workflow for a feature or product release.
+- Issue references
+- [Epics](../../group/epics/index.md): Manage your portfolio of projects by
+  tracking groups of issues with a shared theme.
 
 ### Issue page
 
@@ -125,7 +96,7 @@ To enable it, you need to enable [ActionCable in-app mode](https://docs.gitlab.c
 
 ![Project Issues List view](img/project_issues_list_view.png)
 
-On the Issues List, you can:
+In the Issues List, you can:
 
 - View all issues in a project when opening the Issues List from a project context.
 - View all issues in a groups's projects when opening the Issues List from a group context.
@@ -154,31 +125,12 @@ This feature might not be available to you. Check the **version history** note a
 In a group, the sidebar displays the total count of open issues and this value is cached if higher
 than 1000. The cached value is rounded to thousands (or millions) and updated every 24 hours.
 
-### Issue boards
-
-![Issue board](img/issue_board.png)
-
-[Issue boards](../issue_board.md) are Kanban boards with columns that display issues based on their
-labels or their assignees**(PREMIUM)**. They offer the flexibility to manage issues using
-highly customizable workflows.
-
-You can reorder issues in the column. If you drag an issue card to another column, its
-associated label or assignee is changed to match that of the new column. The entire
-board can also be filtered to only include issues from a certain milestone or an overarching
-label.
-
 ### Design Management
 
 With [Design Management](design_management.md), you can upload design
 assets to issues and view them all together for sharing and
 collaboration with your team.
 
-### Epics **(PREMIUM)**
-
-[Epics](../../group/epics/index.md) let you manage your portfolio of projects more
-efficiently and with less effort. Epics track groups of issues that share a theme, across
-projects and milestones.
-
 ### Related issues
 
 You can mark two issues as related, so that when viewing one, the other is always
diff --git a/doc/user/project/issues/issue_data_and_actions.md b/doc/user/project/issues/issue_data_and_actions.md
index 0bded97f189..5218bb57bca 100644
--- a/doc/user/project/issues/issue_data_and_actions.md
+++ b/doc/user/project/issues/issue_data_and_actions.md
@@ -129,7 +129,7 @@ element. Due dates can be changed as many times as needed.
 ### Labels
 
 Categorize issues by giving them [labels](../labels.md). They help to organize workflows,
-and they enable you to work with the [GitLab Issue Board](index.md#issue-boards).
+and they enable you to work with the [GitLab Issue Board](../issue_board.md).
 
 Group Labels, which allow you to use the same labels for all projects in the same
 group, can also be given to issues. They work exactly the same, but are immediately