Merge branch 'docs-aqualls-fix-vale-issues' into 'master'

Tidy tone and style on Kubernetes integrations

See merge request gitlab-org/gitlab!42912

doc/development/kubernetes.md

@@ -15,14 +15,14 @@ This document provides various guidelines when developing for GitLab's
 
 Some Kubernetes operations, such as creating restricted project
 namespaces are performed on the GitLab Rails application. These
-operations are performed using a [client library](#client-library).
-These operations will carry an element of risk as the operations will be
-run as the same user running the GitLab Rails application, see the
-[security](#security) section below.
+operations are performed using a [client library](#client-library),
+and carry an element of risk. The operations are
+run as the same user running the GitLab Rails application. For more information,
+read the [security](#security) section below.
 
 Some Kubernetes operations, such as installing cluster applications are
 performed on one-off pods on the Kubernetes cluster itself. These
-installation pods are currently named `install-<application_name>` and
+installation pods are named `install-<application_name>` and
 are created within the `gitlab-managed-apps` namespace.
 
 In terms of code organization, we generally add objects that represent
@@ -33,33 +33,32 @@ Kubernetes resources in
 
 We use the [`kubeclient`](https://rubygems.org/gems/kubeclient) gem to
 perform Kubernetes API calls. As the `kubeclient` gem does not support
-different API Groups (e.g. `apis/rbac.authorization.k8s.io`) from a
+different API Groups (such as `apis/rbac.authorization.k8s.io`) from a
 single client, we have created a wrapper class,
 [`Gitlab::Kubernetes::KubeClient`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/kubernetes/kube_client.rb)
-that will enable you to achieve this.
+that enable you to achieve this.
 
-Selected Kubernetes API groups are currently supported. Do add support
+Selected Kubernetes API groups are supported. Do add support
 for new API groups or methods to
 [`Gitlab::Kubernetes::KubeClient`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/kubernetes/kube_client.rb)
 if you need to use them. New API groups or API group versions can be
-added to `SUPPORTED_API_GROUPS` - internally, this will create an
+added to `SUPPORTED_API_GROUPS` - internally, this creates an
 internal client for that group. New methods can be added as a delegation
 to the relevant internal client.
 
 ### Performance considerations
 
-All calls to the Kubernetes API must be in a background process. Do not
-perform Kubernetes API calls within a web request as this will block
-Unicorn and can easily lead to a Denial Of Service (DoS) attack in GitLab as
+All calls to the Kubernetes API must be in a background process. Don't
+perform Kubernetes API calls within a web request. This blocks
+Unicorn, and can lead to a denial-of-service (DoS) attack in GitLab as
 the Kubernetes cluster response times are outside of our control.
 
 The easiest way to ensure your calls happen a background process is to
 delegate any such work to happen in a [Sidekiq worker](sidekiq_style_guide.md).
 
-There are instances where you would like to make calls to Kubernetes and
-return the response and as such a background worker does not seem to be
-a good fit. For such cases you should make use of [reactive
-caching](https://gitlab.com/gitlab-org/gitlab/blob/master/app/models/concerns/reactive_caching.rb).
+You may want to make calls to Kubernetes and return the response, but a background
+worker isn't a good fit. Consider using
+[reactive caching](https://gitlab.com/gitlab-org/gitlab/blob/master/app/models/concerns/reactive_caching.rb).
 For example:
 
 ```ruby
@@ -76,7 +75,7 @@ For example:
 
 ### Testing
 
-We have some Webmock stubs in
+We have some WebMock stubs in
 [`KubernetesHelpers`](https://gitlab.com/gitlab-org/gitlab/blob/master/spec/support/helpers/kubernetes_helpers.rb)
 which can help with mocking out calls to Kubernetes API in your tests.
 
@@ -86,8 +85,8 @@ This section outlines the process for allowing a GitLab instance to create EKS c
 
 The following prerequisites are required:
 
-A `Customer` AWS account. This is the account in which the
-EKS cluster will be created. The following resources must be present:
+A `Customer` AWS account. The EKS cluster is created in this account. The following
+resources must be present:
 
 - A provisioning role that has permissions to create the cluster
   and associated resources. It must list the `GitLab` AWS account
@@ -114,7 +113,7 @@ The process for creating a cluster is as follows:
    which takes somewhere between 10 and 15 minutes in most cases.
 1. When the stack is ready, GitLab stores the cluster details and generates
    another set of temporary credentials, this time to allow connecting to
-   the cluster via Kubeclient. These credentials are valid for one minute.
+   the cluster via `kubeclient`. These credentials are valid for one minute.
 1. GitLab configures the worker nodes so that they are able to authenticate
    to the cluster, and creates a service account for itself for future operations.
 1. Credentials that are no longer required are removed. This deletes the following
@@ -126,7 +125,7 @@ The process for creating a cluster is as follows:
 
 ## Security
 
-### SSRF
+### Server Side Request Forgery (SSRF) attacks
 
 As URLs for Kubernetes clusters are user controlled it is easily
 susceptible to Server Side Request Forgery (SSRF) attacks. You should
@@ -153,11 +152,11 @@ Mitigation strategies include:
      app.make_errored!("Kubernetes error: #{e.error_code}")
    ```
 
-## Debugging
+## Debugging Kubernetes integrations
 
 Logs related to the Kubernetes integration can be found in
 [`kubernetes.log`](../administration/logs.md#kuberneteslog). On a local
-GDK install, this will be present in `log/kubernetes.log`.
+GDK install, these logs are present in `log/kubernetes.log`.
 
 Some services such as
 [`Clusters::Applications::InstallService`](https://gitlab.com/gitlab-org/gitlab/blob/master/app/services/clusters/applications/install_service.rb#L18)
@@ -176,7 +175,9 @@ kubectl logs <pod_name> --follow -n gitlab-managed-apps
 
 ## GitLab Managed Apps
 
-GitLab provides [GitLab Managed Apps](../user/clusters/applications.md), a one-click install for various applications which can be added directly to your configured cluster.
+GitLab provides [GitLab Managed Apps](../user/clusters/applications.md), a one-click
+install for various applications which can be added directly to your configured cluster.
 
 **<i class="fa fa-youtube-play youtube" aria-hidden="true"></i>
-For an overview of how to add a new GitLab-managed app, see [How to add GitLab-managed-apps to Kubernetes integration](https://youtu.be/mKm-jkranEk).**
+For an overview of how to add a new GitLab-managed app, see
+[How to add GitLab-managed-apps to Kubernetes integration](https://youtu.be/mKm-jkranEk).**