Merge branch 'docs-describe-external-kas' into 'master'

Document configuring external KAS with GitLab

See merge request gitlab-org/gitlab!56972

doc/user/clusters/agent/index.md

@@ -7,7 +7,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 # GitLab Kubernetes Agent **(PREMIUM SELF)**
 
 > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/223061) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.4.
-> - It's disabled on GitLab.com. Rolling this feature out to GitLab.com is [planned](https://gitlab.com/groups/gitlab-org/-/epics/3834).
+> - [In GitLab 13.10](https://gitlab.com/gitlab-org/gitlab/-/issues/300960), KAS became available on GitLab.com under `wss://kas.gitlab.com` through an Early Adopter Program.
 
 WARNING:
 This feature might not be available to you. Check the **version history** note above for details.
@@ -85,7 +85,7 @@ component, `agentk`.
 
 Upgrade your agent installations together with GitLab upgrades. To decide which version of `agentk`to install follow:
 
-1. Open the [GITLAB_KAS_VERSION](https://gitlab.com/gitlab-org/gitlab/-/blob/master/GITLAB_KAS_VERSION) file from the GitLab Repository, which contains the latest `agentk` version associated with the `master` branch.
+1. Open the [`GITLAB_KAS_VERSION`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/GITLAB_KAS_VERSION) file from the GitLab Repository, which contains the latest `agentk` version associated with the `master` branch.
 1. Change the `master` branch and select the Git tag associated with your version. For instance, you could change it to GitLab [v13.5.3-ee release](https://gitlab.com/gitlab-org/gitlab/-/blob/v13.5.3-ee/GITLAB_KAS_VERSION)
 
 The available `agentk` and `kas` versions can be found in
@@ -96,20 +96,21 @@ The available `agentk` and `kas` versions can be found in
 [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3834) in GitLab 13.10,
 the GitLab Kubernetes Agent Server (KAS) is available on GitLab.com under `wss://kas.gitlab.com`.
 If you are a GitLab.com user, skip this step and directly
-[set up the configuration repository](#define-a-configuration-repository) 
+[set up the configuration repository](#define-a-configuration-repository)
 for your agent.
 
-The GitLab Kubernetes Agent Server (KAS) can be deployed using [Omnibus
-GitLab](https://docs.gitlab.com/omnibus/) or the [GitLab
-chart](https://gitlab.com/gitlab-org/charts/gitlab). If you don't already have
+The GitLab Kubernetes Agent Server (KAS) can be installed through Omnibus GitLab or
+through the GitLab Helm Chart. If you don't already have
 GitLab installed, please refer to our [installation
 documentation](https://docs.gitlab.com/ee/install/README.html).
+You can install the KAS within GitLab as explained below according to your GitLab installation method.
+You can also opt to use an [external KAS](#use-an-external-kas-installation).
 
-#### Install with Omnibus
+#### Install KAS with Omnibus
 
-When using the [Omnibus GitLab](https://docs.gitlab.com/omnibus/) package:
+For [Omnibus](https://docs.gitlab.com/omnibus/) package installations:
 
-1. Edit `/etc/gitlab/gitlab.rb`:
+1. Edit `/etc/gitlab/gitlab.rb` to enable the Kubernetes Agent Server:
 
    ```plaintext
    gitlab_kas['enable'] = true
@@ -121,9 +122,9 @@ To configure any additional options related to GitLab Kubernetes Agent Server,
 refer to the **Enable GitLab KAS** section of the
 [`gitlab.rb.template`](https://gitlab.com/gitlab-org/omnibus-gitlab/-/blob/master/files/gitlab-config-template/gitlab.rb.template).
 
-#### Install with the Helm chart
+#### Install KAS with GitLab Helm Chart
 
-When installing or upgrading the GitLab Helm chart, consider the following Helm v3 example.
+For GitLab [Helm Chart](https://gitlab.com/gitlab-org/charts/gitlab) installations, consider the following Helm v3 example.
 If you're using Helm v2, you must modify this example. See our [notes regarding deploy with Helm](https://docs.gitlab.com/charts/installation/deployment.html#deploy-using-helm).
 
 You must set `global.kas.enabled=true` for the KAS to be properly installed and configured:
@@ -150,6 +151,29 @@ gitlab:
 
 For details, read [Using the GitLab-KAS chart](https://docs.gitlab.com/charts/charts/gitlab/kas/).
 
+#### Use an external KAS installation
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/299850) in GitLab 13.10.
+
+Besides installing KAS with GitLab, you can opt to configure GitLab to use an external KAS.
+
+For GitLab instances installed through the GitLab Helm Chart, see [how to configure your external KAS](https://docs.gitlab.com/charts/charts/globals.html#external-kas).
+
+For GitLab instances installed through Omnibus packages:
+
+1. Edit `/etc/gitlab/gitlab.rb` adding the paths to your external KAS:
+
+   ```ruby
+   gitlab_kas['enable'] = false
+   gitlab_kas['api_secret_key'] = 'Your shared secret between GitLab and KAS'
+
+   gitlab_rails['gitlab_kas_enabled'] = true
+   gitlab_rails['gitlab_kas_external_url'] = 'wss://kas.gitlab.example.com' # User-facing URL for the in-cluster agentk
+   gitlab_rails['gitlab_kas_internal_url'] = 'grpc://kas.internal.gitlab.example.com' # Internal URL for the GitLab backend
+   ```
+
+1. [Reconfigure GitLab](../../../administration/restart_gitlab.md#omnibus-gitlab-reconfigure).
+
 ### Define a configuration repository
 
 Next, you need a GitLab repository to contain your Agent configuration. The minimal