FAQ and examples improvements

CONTRIBUTING.md

@@ -12,6 +12,7 @@
   - [Commits and Merging](#commits-and-merging)
     - [Rebasing and fixing merge conflicts](#rebasing-and-fixing-merge-conflicts)
   - [What Goes Into a Pull Request](#what-goes-into-a-pull-request)
+- [Submitting a Pull Request](#submitting-a-pull-request)
 - [Releases](#releases)
 - [Testing](#testing)
   - [Templating tests](#templating-tests)
@@ -169,6 +170,21 @@ appropriate.
 * See [Submitting a Pull Request](#submitting-a-pull-request) for more info.
 
 
+## Submitting a Pull Request
+
+Push your local changes to your forked copy of the repository and submit a Pull
+Request. In the Pull Request, describe what your changes do and mention the
+number of the issue where discussion has taken place, e.g., “Closes #123″.
+
+Always submit your pull against `master` unless the bug is only present in an
+older version. If the bug affects both master and another branch say so in your
+pull.
+
+Then sit back and wait. There will probably be discussion about the Pull Request
+and, if any changes are needed, we'll work with you to get your Pull Request
+merged into Kibana.
+
+
 ## Releases
 
 Just like with the rest of the stack, all versions in this helm chart repo are

README.md

@@ -35,7 +35,17 @@ While we are checking backward compatibility, the charts are only tested with
 Helm version mentioned in [helm-tester Dockerfile][] (currently 2.16.6).
 Note that we don't support [Helm 3][] version.
 
+## ECK
+
+In addition of these Helm charts, Elastic also provides
+[Elastic Cloud on Kubernetes][] which is based on [Operator pattern][] and is
+Elastic recommended way to deploy Elasticsearch, Kibana and APM Server on
+Kubernetes.
+
+
 [currently tested]: https://devops-ci.elastic.co/job/elastic+helm-charts+master/
+[elastic cloud on kubernetes]: https://github.com/elastic/cloud-on-k8s
 [helm 3]: https://v3.helm.sh
 [helm-tester Dockerfile]: https://github.com/elastic/helm-charts/blob/master/helpers/helm-tester/Dockerfile
 [helpers/matrix.yml]: https://github.com/elastic/helm-charts/blob/master/helpers/matrix.yml
+[operator pattern]: https://kubernetes.io/docs/concepts/extend-kubernetes/operator/

apm-server/README.md

@@ -11,8 +11,9 @@
 - [Compatibility](#compatibility)
 - [Usage notes](#usage-notes)
 - [Configuration](#configuration)
-- [Examples](#examples)
-  - [Default](#default)
+- [FAQ](#faq)
+  - [How to use APM Server with Elasticsearch with security (authentication and TLS) enabled?](#how-to-use-apm-server-with-elasticsearch-with-security-authentication-and-tls-enabled)
+  - [How to install OSS version of APM Server?](#how-to-install-oss-version-of-apm-server)
 - [Contributing](#contributing)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
@@ -87,6 +88,9 @@ can easily be overridden in the config value `apmConfig.apm-server.yml`.
 * Automated testing of this chart is currently only run against GKE (Google
 Kubernetes Engine).
 
+* This repo includes a number of [examples][] configurations which can be used
+as a reference. They are also used in the automated testing of this chart.
+
 
 ## Configuration
 
@@ -127,28 +131,23 @@ Kubernetes Engine).
 | `updateStrategy`         | Allows you to change the default [updateStrategy][] for the deployment                                                                                     | see [values.yaml][]                |
 
 
-## Examples
-
-In [examples][] you will find some example configurations. These examples are
-used for the automated testing of this Helm chart.
+## FAQ
 
-### Default
+### How to use APM Server with Elasticsearch with security (authentication and TLS) enabled?
 
-* Deploy the [default Elasticsearch Helm chart][].
+This Helm chart can use existing [Kubernetes secrets][] to setup
+credentials or certificates for examples. These secrets should be created
+outside of this chart and accessed using [environment variables][] and volumes.
 
-* Deploy APM Server with the default values:
+An example can be found in [examples/security][].
 
-  ```
-  cd examples/default
-  make
-  ```
+### How to install OSS version of APM Server?
 
-* You can now setup a port forward for Elasticsearch to observe APM indices:
+Deploying OSS version of Elasticsearch can be done by setting `image` value to
+[APM Server OSS Docker image][]
 
-  ```
-  kubectl port-forward svc/elasticsearch-master 9200
-  curl localhost:9200/_cat/indices
-  ```
+An example of APM Server deployment using OSS version can be found in
+[examples/oss][].
 
 
 ## Contributing
@@ -163,14 +162,19 @@ about our development and testing process.
 [affinity]: https://kubernetes.io/docs/concepts/configuration/assign-pod-node/#affinity-and-anti-affinity
 [annotations]: https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/
 [apm server docker image]: https://www.elastic.co/guide/en/apm/server/current/running-on-docker.html
+[apm server oss docker image]: https://www.docker.elastic.co/#apm-server-7-6-2-oss
 [default elasticsearch helm chart]: https://github.com/elastic/helm-charts/tree/master/elasticsearch/README.md#default
 [environment variables]: https://kubernetes.io/docs/tasks/inject-data-application/define-environment-variable-container/#using-environment-variables-inside-of-your-config
+[environment from variables]: https://kubernetes.io/docs/tasks/configure-pod-container/configure-pod-configmap/#configure-all-key-value-pairs-in-a-configmap-as-container-environment-variables
 [examples]: https://github.com/elastic/helm-charts/tree/master/apm-server/examples
+[examples/oss]: https://github.com/elastic/helm-charts/tree/master/apm-server/examples/oss
+[examples/security]: https://github.com/elastic/helm-charts/tree/master/apm-server/examples/security
 [helm]: https://helm.sh
 [horizontal pod autoscaler]: https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale/
 [imagePullPolicy]: https://kubernetes.io/docs/concepts/containers/images/#updating-images
 [imagePullSecrets]: https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/#create-a-pod-that-uses-your-secret
 [ingress]: https://kubernetes.io/docs/concepts/services-networking/ingress/
+[kubernetes secrets]: https://kubernetes.io/docs/concepts/configuration/secret/
 [labels]: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/
 [lifecycle hooks]: https://kubernetes.io/docs/concepts/containers/container-lifecycle-hooks/
 [nodeSelector]: https://kubernetes.io/docs/concepts/configuration/assign-pod-node/#nodeselector

apm-server/examples/6.x/README.md

@@ -0,0 +1,26 @@
+# 6.x
+
+This example deploy APM Server 6.8.8.
+
+
+## Usage
+
+* Deploy [Elasticsearch Helm chart][].
+
+* Deploy APM Server chart with the default values: `make install`
+
+* You can now setup a port forward to query APM indices:
+
+  ```
+  kubectl port-forward svc/six-master 9200
+  curl localhost:9200/_cat/indices
+  ```
+
+
+## Testing
+
+You can also run [goss integration tests][] using `make test`
+
+
+[elasticsearch helm chart]: https://github.com/elastic/helm-charts/tree/master/elasticsearch/examples/6.x/
+[goss integration tests]: https://github.com/elastic/helm-charts/tree/master/apm-server/examples/6.x/test/goss.yaml

apm-server/examples/default/README.md

@@ -0,0 +1,27 @@
+# Default
+
+This example deploy APM Server 7.6.2 using [default values][].
+
+
+## Usage
+
+* Deploy [Elasticsearch Helm chart][].
+
+* Deploy APM Server chart with the default values: `make install`
+
+* You can now setup a port forward to query APM indices:
+
+  ```
+  kubectl port-forward svc/elasticsearch-master 9200
+  curl localhost:9200/_cat/indices
+  ```
+
+
+## Testing
+
+You can also run [goss integration tests][] using `make test`
+
+
+[elasticsearch helm chart]: https://github.com/elastic/helm-charts/tree/master/elasticsearch/examples/default/
+[goss integration tests]: https://github.com/elastic/helm-charts/tree/master/apm-server/examples/default/test/goss.yaml
+[default values]: https://github.com/elastic/helm-charts/tree/master/apm-server/values.yaml

apm-server/examples/oss/README.md

@@ -0,0 +1,27 @@
+# OSS
+
+This example deploy APM Server 7.6.2 using [APM Server OSS][] version.
+
+
+## Usage
+
+* Deploy [Elasticsearch Helm chart][].
+
+* Deploy APM Server chart with the default values: `make install`
+
+* You can now setup a port forward to query APM indices:
+
+  ```
+  kubectl port-forward svc/oss-master 9200
+  curl localhost:9200/_cat/indices
+  ```
+
+
+## Testing
+
+You can also run [goss integration tests][] using `make test`
+
+
+[apm server oss]: https://www.elastic.co/downloads/apm-oss
+[elasticsearch helm chart]: https://github.com/elastic/helm-charts/tree/master/elasticsearch/examples/oss/
+[goss integration tests]: https://github.com/elastic/helm-charts/tree/master/apm-server/examples/oss/test/goss.yaml

apm-server/examples/security/README.md

@@ -0,0 +1,28 @@
+# Security
+
+This example deploy APM Server 7.6.2 using authentication and TLS to connect to
+Elasticsearch (see [values][]).
+
+
+## Usage
+
+* Deploy [Elasticsearch Helm chart][].
+
+* Deploy APM Server chart with security: `make install`
+
+* You can now setup a port forward to query APM indices:
+
+  ```
+  kubectl port-forward svc/security-master 9200
+  curl -u elastic:changeme https://localhost:9200/_cat/indices
+  ```
+
+
+## Testing
+
+You can also run [goss integration tests][] using `make test`
+
+
+[elasticsearch helm chart]: https://github.com/elastic/helm-charts/tree/master/elasticsearch/examples/security/
+[goss integration tests]: https://github.com/elastic/helm-charts/tree/master/apm-server/examples/security/test/goss.yaml
+[values]: https://github.com/elastic/helm-charts/tree/master/apm-server/examples/security/values.yaml