Backport the doc directory from master to 0.9 (#1424)

* Backport doc changes from master to 0.9
* Add relnotes
* Remove extra spaces
* Replace master with 0.9

Author: alaudazzi

docs/accessing-services.asciidoc

@@ -1,5 +1,5 @@
 [id="{p}-accessing-elastic-services"]
-== How to access Elastic Stack services
+== Accessing Elastic Stack services
 
 To access the Elastic Stack services, you will need to retrieve:
 
@@ -21,7 +21,7 @@ All Elastic Stack resources deployed by the ECK Operator are secured by default.
 [id="{p}-authentication"]
 ==== Authentication
 
-To access Elasticsearch and Kibana, the operator manages a default user named `elastic` with the `superuser` role. Its password is stored in a `Secret` named `<name>-elastic-user`.
+To access Elasticsearch, Kibana or APM Server, the operator manages a default user named `elastic` with the `superuser` role. Its password is stored in a `Secret` named `<name>-elastic-user`.
 
 [source,sh]
 ----
@@ -33,13 +33,13 @@ To access Elasticsearch and Kibana, the operator manages a default user named `e
 [id="{p}-services"]
 === Services
 
-You can access Elasticsearch and Kibana by using native Kubernetes services that are not reachable from the public Internet by default.
+You can access Elasticsearch, Kibana or APM Server by using native Kubernetes services that are not reachable from the public Internet by default.
 
 [float]
 [id="{p}-kubernetes-service"]
 ==== Managing Kubernetes services
 
-For each resource, `Elasticsearch` or `Kibana`, the operator manages a Kubernetes service named `<name>-[es|kb]-http`, which is of type `ClusterIP` by default. `ClusterIP` exposes the service on a cluster-internal IP and makes the service only reachable from the cluster.
+For each resource, `Elasticsearch`, `Kibana` or `ApmServer`, the operator manages a Kubernetes service named `<name>-[es|kb|apm]-http`, which is of type `ClusterIP` by default. `ClusterIP` exposes the service on a cluster-internal IP and makes the service only reachable from the cluster.
 
 [source,sh]
 ----
@@ -56,7 +56,7 @@ hulk-kb-http        ClusterIP      10.19.247.151   <none>           5601:31380/T
 ==== Allowing public access
 
 You can expose services in link:https://kubernetes.io/docs/concepts/services-networking/service/#publishing-services-service-types[different ways] by specifying an `http.service.spec.type` in the `spec` of the resource manifest.
-On cloud providers which support external load balancers, you can set the `type` field to `LoadBalancer` to provision a load balancer for the `Service`, and populate the column `EXTERNAL-IP` after a short delay. Depending on the cloud provider, it may incur charges.
+On cloud providers which support external load balancers, you can set the `type` field to `LoadBalancer` to provision a load balancer for the `Service`, and populate the column `EXTERNAL-IP` after a short delay. Depending on the cloud provider, it may incur costs.
 
 [source,yaml]
 ----
@@ -87,14 +87,14 @@ hulk-kb-http        LoadBalancer   10.19.247.151   35.242.197.228   5601:31380/T
 [id="{p}-tls-certificates"]
 === TLS Certificates
 
-This section only covers TLS certificates for the HTTP layer. Those for the transport layer used for internal communication between nodes in a cluster are managed by ECK and are not configurable.
+This section only covers TLS certificates for the HTTP layer. Those for the transport layer used for Elasticsearch internal communication between nodes in a cluster are managed by ECK and are not configurable.
 
 [float]
 [id="{p}-default-self-signed-certificate"]
 ==== Default self-signed certificate
 
-By default, the operator manages a self-signed certificate with a custom CA for Elasticsearch and Kibana.
-The CA, the certificate and the private key are each stored in a `Secret`.
+By default, the operator manages a self-signed certificate with a custom CA for Elasticsearch, Kibana and APM Server.
+The CA, the certificate and the private key are each stored in a separate `Secret`.
 
 [source,sh]
 ----
@@ -144,8 +144,8 @@ You can bring your own certificate to configure TLS to ensure that communication
 
 Create a Kubernetes secret with:
 
-- tls.crt: the certificate (or a chain).
-- tls.key: the private key to the first certificate in the certificate chain.
+- `tls.crt`: the certificate (or a chain).
+- `tls.key`: the private key to the first certificate in the certificate chain.
 
 [source,sh]
 ----
@@ -167,7 +167,7 @@ spec:
 [id="{p}-disable-tls"]
 ==== Disable TLS
 
-You can explicitly disable TLS for Kibana or APM Server if you want to.
+You can explicitly disable TLS for Kibana or APM Server.
 
 [source,yaml]
 ----
@@ -225,7 +225,7 @@ Now you should get this message:
 curl: (51) SSL: no alternative certificate subject name matches target host name '35.198.131.115'
 ----
 
-Add the external IP of the service to the SANs of the certificate in the same Elasticsearch resource YAML manifest used for creating the cluster and apply it again using `kubectl`.
+Add the external IP of the service to the SANs of the certificate in the same Elasticsearch resource YAML manifest used to create the cluster and apply it again using `kubectl`.
 
 [source,yaml]
 ----

docs/advanced-node-scheduling.asciidoc

@@ -1,19 +1,19 @@
 [id="{p}-advanced-node-scheduling"]
 
-== Advanced Elasticsearch node scheduling
+=== Advanced Elasticsearch node scheduling
 
 Elastic Cloud on Kubernetes (ECK) offers full control over cluster nodes scheduling by combining Elasticsearch configuration with Kubernetes scheduling options:
 
-* <<{p}-define-elasticsearch-nodes-roles,define Elasticsearch nodes roles>>
-* <<{p}-affinity-options,pod affinity and anti-affinity>>
-* <<{p}-availability-zone-awareness,availability zone and rack awareness>>
-* <<{p}-hot-warm-topologies,hot-warm topologies>>
+* <<{p}-define-elasticsearch-nodes-roles,Define Elasticsearch nodes roles>>
+* <<{p}-affinity-options,Pod affinity and anti-affinity>>
+* <<{p}-availability-zone-awareness,Availability zone and rack awareness>>
+* <<{p}-hot-warm-topologies,Hot-warm topologies>>
 
 These features can be combined together, to deploy a production-grade Elasticsearch cluster.
 
 [float]
 [id="{p}-define-elasticsearch-nodes-roles"]
-=== Define Elasticsearch nodes roles
+==== Define Elasticsearch nodes roles
 
 You can configure Elasticsearch nodes with link:https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-node.html[one or multiple roles]. This allows you to describe an Elasticsearch cluster with 3 dedicated master nodes, for example:
 
@@ -43,12 +43,12 @@ spec:
 
 [float]
 [id="{p}-affinity-options"]
-=== Affinity options
+==== Affinity options
 
 You can setup various link:https://kubernetes.io/docs/concepts/configuration/assign-pod-node/#affinity-and-anti-affinity[affinity and anti-affinity options] through the `podTemplate` section of the Elasticsearch resource specification.
 
 [float]
-==== A single Elasticsearch node per Kubernetes host (default)
+===== A single Elasticsearch node per Kubernetes host (default)
 
 To avoid scheduling several Elasticsearch nodes from the same cluster on the same host, use a `podAntiAffinity` rule based on the hostname and the cluster name label:
 
@@ -120,7 +120,7 @@ spec:
 ----
 
 [float]
-==== Local Persistent Volume constraints
+===== Local Persistent Volume constraints
 
 By default, volumes can be bound to a pod before the pod gets scheduled to a particular node. This can be a problem if the PersistentVolume can only be accessed from a particular host or set of hosts. Local persistent volumes are a good example: they are accessible from a single host. If the pod gets scheduled to a different host based on any affinity or anti-affinity rule, the volume may not be available.
 
@@ -137,7 +137,7 @@ volumeBindingMode: WaitForFirstConsumer
 ----
 
 [float]
-==== Node affinity
+===== Node affinity
 
 To restrict the scheduling to a particular set of nodes based on labels, use a link:https://kubernetes.io/docs/concepts/configuration/assign-pod-node/#nodeselector[NodeSelector].
 The following example schedules Elasticsearch pods on Kubernetes nodes tagged with both labels `diskType: ssd` and `environment: production`.
@@ -197,7 +197,7 @@ This example restricts Elasticsearch nodes to be scheduled on Kubernetes hosts t
 
 [float]
 [id="{p}-availability-zone-awareness"]
-=== Availability zone awareness
+==== Availability zone awareness
 
 By combining link:https://www.elastic.co/guide/en/elasticsearch/reference/current/allocation-awareness.html#allocation-awareness[Elasticsearch shard allocation awareness] with link:https://kubernetes.io/docs/concepts/configuration/assign-pod-node/#node-affinity-beta-feature[Kubernetes node affinity], you can setup an availability zone-aware Elasticsearch cluster:
 
@@ -265,7 +265,7 @@ This example relies on:
 
 [float]
 [id="{p}-hot-warm-topologies"]
-=== Hot-warm topologies
+==== Hot-warm topologies
 
 By combining link:https://www.elastic.co/guide/en/elasticsearch/reference/current/allocation-awareness.html#allocation-awareness[Elasticsearch shard allocation awareness] with link:https://kubernetes.io/docs/concepts/configuration/assign-pod-node/#node-affinity-beta-feature[Kubernetes node affinity], you can setup an Elasticsearch cluster with hot-warm topology:
 

docs/apm.asciidoc

@@ -19,7 +19,7 @@ NOTE: The current Docker image of the APM Server must run as `root` or with the
 [id="{p}-apm-eck-managed-es"]
 === Use an Elasticsearch cluster managed by ECK
 
-When both the APM Server and Elasticsearch are managed by ECK it allows a smooth and secured integration between the two. The output configuration of the APM Server is setup automatically to establish a trust relationship with Elasticsearch.
+Managing both APM Server and Elasticsearch by ECK allows a smooth and secured integration between the two. The output configuration of the APM Server is setup automatically to establish a trust relationship with Elasticsearch.
 
 . To deploy an APM Server and connect it to the cluster `quickstart` created in the link:k8s-quickstart.html[quickstart], apply the following specification:
 +
@@ -40,28 +40,29 @@ EOF
 ----
 +
 NOTE: Deploying the APM Server and Elasticsearch in two different namespaces is currently not supported.
-+
-. Monitor APM Server deployment
+
+. Monitor APM Server deployment.
 +
 You can retrieve details about the APM Server instance:
-
++
 [source,sh]
 ----
 kubectl get apmservers
 ----
-
++
 [source,sh]
 ----
 NAME                     HEALTH    NODES    VERSION   AGE
 apm-server-quickstart    green     1         7.2.0     8m
 ----
++
 And you can list all the Pods belonging to a given deployment:
-
++
 [source,sh]
 ----
 kubectl get pods --selector='apm.k8s.elastic.co/name=apm-server-quickstart'
 ----
-
++
 [source,sh]
 ----
 NAME                                                READY   STATUS    RESTARTS   AGE
@@ -110,7 +111,7 @@ The APM Server keystore can be used to store sensitive settings in the APM Serve
 kubectl create secret generic apm-secret-settings --from-literal=ES_PASSWORD=asecretpassword
 ----
 
-. In the specification of the APM Server add a reference to the previously created secret within a `spec.secureSettings` section. Then reference the key in the APM Server configuration as it is described in the https://www.elastic.co/guide/en/apm/server/current/keystore.html[following documentation].
+. In the specification of the APM Server add a reference to the previously created secret within a `spec.secureSettings` section. Then reference the key in the APM Server configuration as it is described in the https://www.elastic.co/guide/en/apm/server/current/keystore.html[Secrets keystore for secure settings].
 +
 [source,yaml]
 ----
@@ -136,7 +137,7 @@ spec:
 
 Now that you know how to use the APM keystore and customize the server configuration, you can manually configure a secured connection to an existing Elasticsearch cluster.
 
-. Create a secret with the Elasticsearch CA
+. Create a secret with the Elasticsearch CA.
 +
 First, you need to store the certificate authority of the Elasticsearch cluster in a secret:
 +
@@ -145,7 +146,7 @@ First, you need to store the certificate authority of the Elasticsearch cluster
 kubectl create secret generic es-ca --from-file=tls.crt=elasticsearch-ca.crt
 ----
 +
-Note: the file `elasticsearch-ca.crt` must contain the CA certificate of the Elasticsearch cluster you want to use with the APM Server.
+NOTE: the file `elasticsearch-ca.crt` must contain the CA certificate of the Elasticsearch cluster you want to use with the APM Server.
 
 . You can then mount this secret using the Pod template, and reference the file in the `config` of the APM Server.
 +
@@ -231,4 +232,4 @@ This token is stored in a secret named `{APM-server-name}-apm-token` and can be
 kubectl get secret/apm-server-quickstart-apm-token -o go-template='{{index .data "secret-token" | base64decode}}'
 ----
 
-For more information about the APM Server, see https://www.elastic.co/guide/en/apm/server/current/index.html[APM Server Reference].
+For more information, see https://www.elastic.co/guide/en/apm/server/current/index.html[APM Server Reference].