Merge branch 'docs-aqualls-clean-agent-page' into 'master'

Tidy Kubernetes agent page for tone and style

See merge request gitlab-org/gitlab!43063

doc/user/clusters/agent/index.md

@@ -8,14 +8,17 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/223061) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.4.
 
-The [GitLab Kubernetes Agent](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent) is an active in-cluster component for solving GitLab and Kubernetes integration tasks in a secure and cloud native way.
+The [GitLab Kubernetes Agent](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent)
+is an active in-cluster component for solving GitLab and Kubernetes integration
+tasks in a secure and cloud-native way. It enables:
 
-Features:
+- Integrating GitLab with a Kubernetes cluster behind a firewall or NAT
+  (network address translation).
+- Pull-based GitOps deployments by leveraging the
+  [GitOps Engine](https://github.com/argoproj/gitops-engine).
+- Real-time access to API endpoints within a cluster.
 
-1. Makes it possible to integrate GitLab with a Kubernetes cluster behind a firewall or NAT
-1. Enables pull-based GitOps deployments by leveraging the [GitOps Engine](https://github.com/argoproj/gitops-engine)
-1. Allows for real-time access to API endpoints within a cluster.
-1. Many more features are planned. Please [review our roadmap](https://gitlab.com/groups/gitlab-org/-/epics/3329).
+Many more features are planned. Please [review our roadmap](https://gitlab.com/groups/gitlab-org/-/epics/3329).
 
 ## Architecture
 
@@ -37,34 +40,42 @@ sequenceDiagram
   end
 ```
 
-Please refer to our [full architecture documentation in the Agent project](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/master/doc/architecture.md#high-level-architecture).
+Please refer to our [full architecture documentation](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/master/doc/architecture.md#high-level-architecture)
+in the Agent project.
 
-## Getting started with GitOps using the GitLab Agent and the GitLab Cloud Native Helm chart
+## Get started with GitOps and the GitLab Agent
 
 There are several components that work in concert for the Agent to accomplish GitOps deployments:
 
-1. A Kubernetes cluster that is properly configured
-1. A configuration repository that contains a `config.yaml` file. This `config.yaml` tells the Agent which repositories to synchronize with.
-1. A manifest repository that contains a `manifest.yaml`. This `manifest.yaml` (which can be autogenerated) is tracked by the Agent and any changes to the file are automatically applied to the cluster.
+- A properly-configured Kubernetes cluster.
+- A configuration repository that contains a `config.yaml` file, which tells the
+  Agent which repositories to synchronize with.
+- A manifest repository that contains a `manifest.yaml`, which is tracked by the
+  Agent and can be auto-generated. Any changes to `manifest.yaml` are applied to the cluster.
 
-The setup process involves a few steps that, once completed, will enable GitOps deployments to work
+The setup process involves a few steps to enable GitOps deployments:
 
-1. Installing the Agent server via GitLab Helm chart
-1. Defining a configuration directory
-1. Creating an Agent record in GitLab
-1. Generating and copying a Secret token used to connect to the Agent
-1. Installing the Agent into the cluster
-1. Creating a `manifest.yaml`
+1. Installing the Agent server via GitLab Helm chart.
+1. Defining a configuration directory.
+1. Creating an Agent record in GitLab.
+1. Generating and copying a Secret token used to connect to the Agent.
+1. Installing the Agent into the cluster.
+1. Creating a `manifest.yaml`.
 
-### Installing the Agent server via Helm
+### Install the Agent server
 
-Currently the GitLab Kubernetes Agent can only be deployed via our [Helm chart](https://gitlab.com/gitlab-org/charts/gitlab).
+The GitLab Kubernetes Agent can only be deployed through our
+[Helm chart](https://gitlab.com/gitlab-org/charts/gitlab). If you don't already
+have GitLab installed via Helm, please refer to our
+[installation documentation](https://docs.gitlab.com/charts/installation/).
 
-NOTE: We are working quickly to [include the Agent in Official Linux Package](https://gitlab.com/gitlab-org/gitlab/-/issues/223060).
+NOTE: **Note:**
+GitLab plans to [include the Agent](https://gitlab.com/gitlab-org/gitlab/-/issues/223060)
+in the official Linux Package.
 
-If you don't already have GitLab installed via Helm please refer to our [installation documentation](https://docs.gitlab.com/charts/installation/)
-
-When installing/upgrading the GitLab Helm chart please consider the following Helm 2 example (if using Helm 3 please modify):
+When installing or upgrading the GitLab Helm chart, consider the following Helm 2 example.
+(If you're using Helm 3, you must modify this example.) You must set `global.kas.enabled=true`
+for the Agent to be properly installed and configured:
 
 ```shell
 helm upgrade --force --install gitlab . \
@@ -76,15 +87,14 @@ helm upgrade --force --install gitlab . \
   --set global.kas.enabled=true
 ```
 
-`global.kas.enabled=true` must be set in order for the Agent to be properly installed and configured.
-
-### Defining a configuration repository
+### Define a configuration repository
 
-Next you will need a GitLab repository that will contain your Agent configuration.
+Next, you need a GitLab repository to contain your Agent configuration. The minimal
+repository layout looks like this:
 
-The minimal repository layout looks like this:
-
-`.gitlab/agents/<agent-name>/config.yaml`
+```plaintext
+.gitlab/agents/<agent-name>/config.yaml
+```
 
 The `config.yaml` file contents should look like this:
 
@@ -94,31 +104,24 @@ gitops:
   - id: "path-to/your-awesome-project"
 ```
 
-### Creating an Agent record in GitLab
-
-Next you will need to create an GitLab Rails Agent record so that your GitLab project so that the Agent itself can associate with a GitLab project. This process will also yield a Secret that you will use to configure the Agent in subsequent steps.
+### Create an Agent record in GitLab
 
-There are two ways to accomplish this:
+Next, create an GitLab Rails Agent record so the Agent can associate itself with
+a GitLab project. Creating this record also creates a Secret needed to configure
+the Agent in subsequent steps. You can create an Agent record either:
 
-1. Via the Rails console
-1. Via GraphQL
+- Through the Rails console, by running `rails c`:
 
-To do this you could either run `rails c` or via GraphQL. From `rails c`:
-
-```ruby
+  ```ruby
   project = ::Project.find_by_full_path("path-to/your-awesome-project")
   agent = ::Clusters::Agent.create(name: "<agent-name>", project: project)
   token = ::Clusters::AgentToken.create(agent: agent)
   token.token # this will print out the token you need to use on the next step
-```
+  ```
 
-or using GraphQL:
+- Through GraphQL: **(PREMIUM ONLY)**
 
-with this approach, you'll need a premium license to use this feature.
-
-If you are new to using the GitLab GraphQL API please refer to the [Getting started with the GraphQL API page](../../../api/graphql/getting_started.md) or check out the [GraphQL Explorer](https://gitlab.com/-/graphql-explorer).
-
-```json
+  ```json
     mutation createAgent {
       createClusterAgent(input: { projectPath: "path-to/your-awesome-project", name: "<agent-name>" }) {
         clusterAgent {
@@ -139,37 +142,66 @@ If you are new to using the GitLab GraphQL API please refer to the [Getting star
         errors
       }
     }
-```
+  ```
 
-Note that GraphQL will only show you the token once, after you've created it.
+  NOTE: **Note:**
+  GraphQL only displays the token once, after creating it.
 
-### Creating the Kubernetes secret
+  If you are new to using the GitLab GraphQL API, refer to the
+  [Getting started with the GraphQL API page](../../../api/graphql/getting_started.md),
+  or the [GraphQL Explorer](https://gitlab.com/-/graphql-explorer).
 
-Once the token has been generated it needs to be applied to the Kubernetes cluster.
+### Create the Kubernetes secret
 
-If you didn't previously define or create a namespace you need to do that first:
+After generating the token, you must apply it to the Kubernetes cluster.
 
-```shell
-kubectl create namespace <YOUR-DESIRED-NAMESPACE>
-```
+1. If you haven't previous defined or created a namespace, run the following command:
+
+   ```shell
+   kubectl create namespace <YOUR-DESIRED-NAMESPACE>
+   ```
+
+1. Run the following command to create your Secret:
 
-Run the following command to create your Secret:
+   ```shell
+   kubectl create secret generic -n <YOUR-DESIRED-NAMESPACE> gitlab-agent-token --from-literal=token='YOUR_AGENT_TOKEN'
+   ```
+
+### Install the Agent into the cluster
+
+Next, install the in-cluster component of the Agent. This example file contains the
+Kubernetes resources required for the Agent to be installed. You can modify this
+example [`resources.yml` file](#example-resourcesyml-file) in the following ways:
+
+- You can replace `gitlab-agent` with your desired namespace.
+- For the `kas-address` (Kubernetes Agent Server), you can replace
+  `grpc://host.docker.internal:5005` with the address of the `kas` agent initialized
+  in your Helm install.
+- If you defined your own secret name, replace `gitlab-agent-token` with your secret name.
+
+To apply this file, run the following command:
 
 ```shell
-kubectl create secret generic -n <YOUR-DESIRED-NAMESPACE> gitlab-agent-token --from-literal=token='YOUR_AGENT_TOKEN'
+kubectl apply -n gitlab-agent -f ./resources.yml
 ```
 
-### Installing the Agent into the cluster
-
-Next you are now ready to install the in-cluster component of the Agent. The below is an example YAML file of the Kubernetes resources required for the Agent to be installed.
+To review your configuration, run the following command:
 
-Let's highlight a few of the details in the example below:
+```shell
+$ kubectl get pods --all-namespaces
 
-1. You can replace `gitlab-agent` with <YOUR-DESIRED-NAMESPACE>
-1. For the `kas-address` (Kubernetes Agent Server), you can replace `grpc://host.docker.internal:5005` with the address of the kas agent that was initialized via your Helm install.
-1. If you defined your own secret name, then replace `gitlab-agent-token` with your secret name.
+NAMESPACE     NAME                               READY   STATUS    RESTARTS   AGE
+gitlab-agent  gitlab-agent-77689f7dcb-5skqk      1/1     Running   0          51s
+kube-system   coredns-f9fd979d6-n6wcw            1/1     Running   0          14m
+kube-system   etcd-minikube                      1/1     Running   0          14m
+kube-system   kube-apiserver-minikube            1/1     Running   0          14m
+kube-system   kube-controller-manager-minikube   1/1     Running   0          14m
+kube-system   kube-proxy-j6zdh                   1/1     Running   0          14m
+kube-system   kube-scheduler-minikube            1/1     Running   0          14m
+kube-system   storage-provisioner                1/1     Running   0          14m
+```
 
-`./resources.yml`
+#### Example `resources.yml` file
 
 ```yaml
 apiVersion: v1
@@ -266,31 +298,24 @@ subjects:
 - name: gitlab-agent
   kind: ServiceAccount
   namespace: gitlab-agent
-
 ```
 
-```shell
-kubectl apply -n gitlab-agent -f ./resources.yml
-```
+### Create a `manifest.yaml`
+
+In a previous step, you configured a `config.yaml` to point to the GitLab projects
+the Agent should synchronize. In each of those projects, you must create a `manifest.yaml`
+file for the Agent to monitor. You can auto-generate this `manifest.yaml` with a
+templating engine or other means.
+
+Each time you commit and push a change to this file, the Agent logs the change:
 
 ```plaintext
-$ kubectl get pods --all-namespaces
-NAMESPACE     NAME                               READY   STATUS    RESTARTS   AGE
-gitlab-agent  gitlab-agent-77689f7dcb-5skqk      1/1     Running   0          51s
-kube-system   coredns-f9fd979d6-n6wcw            1/1     Running   0          14m
-kube-system   etcd-minikube                      1/1     Running   0          14m
-kube-system   kube-apiserver-minikube            1/1     Running   0          14m
-kube-system   kube-controller-manager-minikube   1/1     Running   0          14m
-kube-system   kube-proxy-j6zdh                   1/1     Running   0          14m
-kube-system   kube-scheduler-minikube            1/1     Running   0          14m
-kube-system   storage-provisioner                1/1     Running   0          14m
+2020-09-15_14:09:04.87946 gitlab-k8s-agent      : time="2020-09-15T10:09:04-04:00" level=info msg="Config: new commit" agent_id=1 commit_id=e6a3651f1faa2e928fe6120e254c122451be4eea
 ```
 
-### Creating a `manifest.yaml`
-
-In the above step, you configured a `config.yaml` to point to which GitLab projects the Agent should synchronize. Within each one of those projects, you need to create a `manifest.yaml` file which the Agent will monitor. This `manifest.yaml` can be autogenerated by a templating engine or other means.
+#### Example `manifest.yaml` file
 
-Example `manifest.yaml`:
+This file creates a simple NGINX deployment.
 
 ```yaml
 apiVersion: apps/v1
@@ -314,14 +339,9 @@ spec:
         - containerPort: 80
 ```
 
-The above file creates a simple NGINX deployment.
-
-Each time you commit and push a change to the `manifest.yaml` the Agent will observe the change. Example log:
-
-```plaintext
-2020-09-15_14:09:04.87946 gitlab-k8s-agent      : time="2020-09-15T10:09:04-04:00" level=info msg="Config: new commit" agent_id=1 commit_id=e6a3651f1faa2e928fe6120e254c122451be4eea
-```
-
 ## Example projects
 
-Basic GitOps example deploying NGINX: [Configuration repository](https://gitlab.com/gitlab-org/configure/examples/kubernetes-agent), [Manifest repository](https://gitlab.com/gitlab-org/configure/examples/gitops-project)
+This basic GitOps example deploys NGINX:
+
+- [Configuration repository](https://gitlab.com/gitlab-org/configure/examples/kubernetes-agent)
+- [Manifest repository](https://gitlab.com/gitlab-org/configure/examples/gitops-project)