Merge branch 'ash2k/improve-agent-gitops-page' into 'master'

Update the main Agent page

See merge request gitlab-org/gitlab!52441

doc/user/clusters/agent/index.md

@@ -37,7 +37,7 @@ sequenceDiagram
   participant D as Developer
   participant A as Application code repository
   participant M as Manifest repository
-  participant K as Kubernetes agent
+  participant K as Kubernetes Agent
   participant C as Agent configuration repository
   K->C: Grab the configuration
   D->>+A: Pushing code changes
@@ -50,11 +50,10 @@ sequenceDiagram
 
 There are several components that work in concert for the Agent to accomplish GitOps deployments:
 
-- A properly-configured Kubernetes cluster.
+- A properly-configured Kubernetes cluster where the Agent is running.
 - 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.
+  Agent which repositories to synchronize with the cluster.
+- A manifest repository that contains manifest files. Any changes to manifest files are applied to the cluster.
 
 These repositories might be the same GitLab project or separate projects.
 
@@ -75,7 +74,7 @@ The setup process involves a few steps to enable GitOps deployments:
 1. [Create an Agent record in GitLab](#create-an-agent-record-in-gitlab).
 1. [Generate and copy a Secret token used to connect to the Agent](#create-the-kubernetes-secret).
 1. [Install the Agent into the cluster](#install-the-agent-into-the-cluster).
-1. [Create a `manifest.yaml`](#create-a-manifestyaml).
+1. [Create manifest files](#create-manifest-files).
 
 ### Upgrades and version compatibility
 
@@ -389,11 +388,10 @@ subjects:
   namespace: gitlab-agent
 ```
 
-### Create a `manifest.yaml`
+### Create manifest files
 
 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
+the Agent should synchronize. Agent monitors each of those projects for changes to the manifest files it contains. You can auto-generate manifest files with a
 templating engine or other means.
 
 The agent is authorized to download manifests for the configuration
@@ -401,13 +399,13 @@ project, and public projects. Support for other private projects is
 planned in the issue [Agent authorization for private manifest
 projects](https://gitlab.com/gitlab-org/gitlab/-/issues/220912).
 
-Each time you commit and push a change to this file, the Agent logs the change:
+Each time you push a change to a monitored manifest repository, the Agent logs the change:
 
 ```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 `manifest.yaml` file
+#### Example manifest file
 
 This file creates an NGINX deployment.
 
@@ -549,9 +547,9 @@ specified the `kas-address` correctly.
 {"level":"info","time":"2020-10-30T08:56:54.329Z","msg":"Synced","project_id":"root/kas-manifest001","resource_key":"apps/Deployment/kas-test001/nginx-deployment","sync_result":"error validating data: [ValidationError(Deployment.metadata): unknown field \"replicas\" in io.k8s.apimachinery.pkg.apis.meta.v1.ObjectMeta, ValidationError(Deployment.metadata): unknown field \"selector\" in io.k8s.apimachinery.pkg.apis.meta.v1.ObjectMeta, ValidationError(Deployment.metadata): unknown field \"template\" in io.k8s.apimachinery.pkg.apis.meta.v1.ObjectMeta]"}
 ```
 
-This error is shown if your `manifest.yaml` file is malformed, and Kubernetes can't
-create specified objects. Make sure that your `manifest.yaml` file is valid. You
-may try using it to create objects in Kubernetes directly for more troubleshooting.
+This error is shown if a manifest file is malformed, and Kubernetes can't
+create specified objects. Make sure that your manifest files are valid. You
+may try using them to create objects in Kubernetes directly for more troubleshooting.
 
 ### Agent logs - Error while dialing failed to WebSocket dial: failed to send handshake request