Merge branch 'selhorn-kas-server-edit' into 'master'

Edited for style and naming

See merge request gitlab-org/gitlab!82446

doc/administration/clusters/kas.md

@@ -6,32 +6,31 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 
 # Install the GitLab agent server for Kubernetes (KAS) **(FREE SELF)**
 
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3834) in GitLab 13.10, the GitLab agent server (KAS) became available on GitLab.com under `wss://kas.gitlab.com`.
+> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3834) in GitLab 13.10, the GitLab agent server (KAS) became available on GitLab.com at `wss://kas.gitlab.com`.
 > - [Moved](https://gitlab.com/groups/gitlab-org/-/epics/6290) from GitLab Premium to GitLab Free in 14.5.
 
-The GitLab agent server for Kubernetes is a GitLab backend service dedicated to
-managing the [GitLab agent for Kubernetes](../../user/clusters/agent/index.md).
+The GitLab agent server for Kubernetes (KAS) is a service that
+manages the [GitLab agent for Kubernetes](../../user/clusters/agent/index.md).
 
-The KAS acronym refers to the former name, Kubernetes agent server.
+The KAS acronym refers to the former name, `Kubernetes agent server`.
 
-The KAS is already installed and available in GitLab.com under `wss://kas.gitlab.com`.
-This document describes how to install a KAS for GitLab self-managed instances.
+The agent server for Kubernetes is installed and available on GitLab.com at `wss://kas.gitlab.com`.
+If you use self-managed GitLab, you must install an agent server or specify an external installation.
 
 ## Installation options
 
-As a GitLab administrator of self-managed instances, you can install KAS according to your GitLab
-installation method:
+As a GitLab administrator, you can install the agent server:
 
-- For [Omnibus installations](#install-kas-with-omnibus).
-- For [GitLab Helm Chart installations](#install-kas-with-the-gitlab-helm-chart).
+- For [Omnibus installations](#for-omnibus).
+- For [GitLab Helm Chart installations](#for-gitlab-helm-chart).
 
-You can also opt to use an [external KAS](#use-an-external-kas-installation).
+Or, you can [use an external agent server](#use-an-external-installation).
 
-### Install KAS with Omnibus
+### For Omnibus
 
 For [Omnibus](https://docs.gitlab.com/omnibus/) package installations:
 
-1. Edit `/etc/gitlab/gitlab.rb` to enable the agent server:
+1. To enable the agent server, edit `/etc/gitlab/gitlab.rb`:
 
    ```ruby
    gitlab_kas['enable'] = true
@@ -39,49 +38,49 @@ For [Omnibus](https://docs.gitlab.com/omnibus/) package installations:
 
 1. [Reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure).
 
-To configure any additional options related to your KAS,
-refer to the **Enable GitLab KAS** section of the
+For additional configuration options, see 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 KAS with the GitLab Helm Chart
+### For GitLab Helm Chart
 
-For GitLab [Helm Chart](https://docs.gitlab.com/charts/)
-installations, you must set `global.kas.enabled` to `true`.
-For example, in a shell with `helm` and `kubectl`
-installed, run:
+For GitLab [Helm Chart](https://docs.gitlab.com/charts/) installations:
 
-```shell
-helm repo add gitlab https://charts.gitlab.io/
-helm repo update
-helm upgrade --install gitlab gitlab/gitlab \
-  --timeout 600s \
-  --set global.hosts.domain=<YOUR_DOMAIN> \
-  --set global.hosts.externalIP=<YOUR_IP> \
-  --set certmanager-issuer.email=<YOUR_EMAIL> \
-  --set global.kas.enabled=true # <-- without this, KAS will not be installed
-```
+1. Set `global.kas.enabled` to `true`. For example, in a shell with `helm` and `kubectl`
+   installed, run:
 
-To configure KAS, use a `gitlab.kas` sub-section in your `values.yaml` file:
+   ```shell
+   helm repo add gitlab https://charts.gitlab.io/
+   helm repo update
+   helm upgrade --install gitlab gitlab/gitlab \
+     --timeout 600s \
+     --set global.hosts.domain=<YOUR_DOMAIN> \
+     --set global.hosts.externalIP=<YOUR_IP> \
+     --set certmanager-issuer.email=<YOUR_EMAIL> \
+     --set global.kas.enabled=true # <-- without this setting, the agent server will not be installed
+   ```
 
-```yaml
-gitlab:
-  kas:
-    # put your KAS custom options here
-```
+1. To configure the agent server, use a `gitlab.kas` sub-section in your `values.yaml` file:
+
+   ```yaml
+   gitlab:
+     kas:
+       # put your custom options here
+   ```
 
 For details, see [how to use the GitLab-KAS chart](https://docs.gitlab.com/charts/charts/gitlab/kas/).
 
-### Use an external KAS installation
+### Use an external 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.
+Instead of installing the agent server, you can configure GitLab to use an external agent server.
 
-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).
+If you used the GitLab Helm Chart to install GitLab, see
+[how to configure your external agent server](https://docs.gitlab.com/charts/charts/globals.html#external-kas).
 
-For GitLab instances installed through Omnibus packages:
+If you used the Omnibus packages:
 
-1. Edit `/etc/gitlab/gitlab.rb` adding the paths to your external KAS:
+1. Edit `/etc/gitlab/gitlab.rb` and add the paths to your external agent server:
 
    ```ruby
    gitlab_kas['enable'] = false
@@ -96,7 +95,7 @@ For GitLab instances installed through Omnibus packages:
 
 ## Troubleshooting
 
-If you have issues while using the GitLab agent server for Kubernetes, view the
+If you have issues while using the agent server for Kubernetes, view the
 service logs by running the following command:
 
 ```shell
@@ -107,7 +106,7 @@ In Omnibus GitLab, find the logs in `/var/log/gitlab/gitlab-kas/`.
 
 You can also [troubleshoot issues with individual agents](../../user/clusters/agent/troubleshooting.md).
 
-### KAS logs - GitOps: failed to get project information
+### GitOps: failed to get project information
 
 If you get the following error message:
 
@@ -115,11 +114,11 @@ If you get the following error message:
 {"level":"warn","time":"2020-10-30T08:37:26.123Z","msg":"GitOps: failed to get project info","agent_id":4,"project_id":"root/kas-manifest001","error":"error kind: 0; status: 404"}
 ```
 
-It means that the specified manifest project `root/kas-manifest001`
-doesn't exist or the manifest project is private. To fix it, make sure the project path is correct
-and its visibility is [set to public](../../public_access/public_access.md).
+The project specified by the manifest (`root/kas-manifest001`)
+doesn't exist or the project where the manifest is kept is private. To fix this issue,
+ensure the project path is correct and that the project's visibility is [set to public](../../public_access/public_access.md).
 
-### KAS logs - Configuration file not found
+### Configuration file not found
 
 If you get the following error message:
 
@@ -127,29 +126,29 @@ If you get the following error message:
 time="2020-10-29T04:44:14Z" level=warning msg="Config: failed to fetch" agent_id=2 error="configuration file not found: \".gitlab/agents/test-agent/config.yaml\
 ```
 
-It means that the path to the configuration project is incorrect,
-or the path to `config.yaml` inside the project is not valid.
+The path is incorrect for either:
+
+- The repository where the agent was registered.
+- The agent configuration file.
 
-To fix this, ensure that the paths to the configuration repository and to the `config.yaml` file
-are correct.
+To fix this issue, ensure that the paths are correct.
 
-### KAS logs - `dial tcp <GITLAB_INTERNAL_IP>:443: connect: connection refused`
+### `dial tcp <GITLAB_INTERNAL_IP>:443: connect: connection refused`
 
-If you are running a self-managed GitLab instance and:
+If you are running self-managed GitLab and:
 
 - The instance isn't running behind an SSL-terminating proxy.
 - The instance doesn't have HTTPS configured on the GitLab instance itself.
 - The instance's hostname resolves locally to its internal IP address.
 
-You may see the following error when the KAS tries to connect to the GitLab API:
+When the agent server tries to connect to the GitLab API, the following error might occur:
 
 ```json
 {"level":"error","time":"2021-08-16T14:56:47.289Z","msg":"GetAgentInfo()","correlation_id":"01FD7QE35RXXXX8R47WZFBAXTN","grpc_service":"gitlab.agent.reverse_tunnel.rpc.ReverseTunnel","grpc_method":"Connect","error":"Get \"https://gitlab.example.com/api/v4/internal/kubernetes/agent_info\": dial tcp 172.17.0.4:443: connect: connection refused"}
 ```
 
-To fix this for [Omnibus](https://docs.gitlab.com/omnibus/) package installations,
-set the following parameter in `/etc/gitlab/gitlab.rb`
-(replacing `gitlab.example.com` with your GitLab instance's hostname):
+To fix this issue for [Omnibus](https://docs.gitlab.com/omnibus/) package installations,
+set the following parameter in `/etc/gitlab/gitlab.rb`. Replace `gitlab.example.com` with your GitLab instance's hostname:
 
 ```ruby
 gitlab_kas['gitlab_address'] = 'http://gitlab.example.com'

doc/user/clusters/agent/install/index.md

@@ -21,6 +21,7 @@ Before you can install the agent in your cluster, you need:
   - [Amazon Elastic Kubernetes Service (EKS)](https://docs.aws.amazon.com/eks/latest/userguide/getting-started.html)
   - [Digital Ocean](https://docs.digitalocean.com/products/kubernetes/quickstart/)
 - On self-managed GitLab instances, a GitLab administrator must set up the [agent server](../../../../administration/clusters/kas.md).
+  On GitLab.com, the agent server is available at `wss://kas.gitlab.com`.
 
 ## Installation steps
 
@@ -122,7 +123,7 @@ Flags:
       --agent-token string     Access token registered for agent
       --agent-version string   Version of the agentk image to use (default "v14.8.1")
   -h, --help                   help for generate
-      --kas-address string     GitLab Kubernetes Agent Server address
+      --kas-address string     GitLab agent server for Kubernetes address
       --name-prefix string     The prefix to use for names of Kubernetes objects
       --namespace string       Kubernetes namespace to create resources in (default "gitlab-agent")
       --no-rbac                Do not include corresponding Roles and RoleBindings for the agent service account