FAQ and examples improvements (#598) (#600)

FAQ and examples improvements (#598)

- Add missing section in contributing guide
- Add note about ECK
- Add more FAQ topics
- Document all examples
- NIT: fixes typos...

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

@@ -16,12 +16,12 @@ added below.
 
 | Chart                                      | Docker documentation                                                            |
 |--------------------------------------------|---------------------------------------------------------------------------------|
-| [APM-Server](./apm-server/README.md)       | https://www.elastic.co/guide/en/apm/server/current/running-on-docker.html       |
-| [Elasticsearch](./elasticsearch/README.md) | https://www.elastic.co/guide/en/elasticsearch/reference/current/docker.html     |
-| [Filebeat](./filebeat/README.md)           | https://www.elastic.co/guide/en/beats/filebeat/current/running-on-docker.html   |
-| [Kibana](./kibana/README.md)               | https://www.elastic.co/guide/en/kibana/current/docker.html                      |
-| [Logstash](./logstash/README.md)           | https://www.elastic.co/guide/en/logstash/current/docker.html                    |
-| [Metricbeat](./metricbeat/README.md)       | https://www.elastic.co/guide/en/beats/metricbeat/current/running-on-docker.html |
+| [APM-Server](./apm-server/README.md)       | https://www.elastic.co/guide/en/apm/server/7.7/running-on-docker.html       |
+| [Elasticsearch](./elasticsearch/README.md) | https://www.elastic.co/guide/en/elasticsearch/reference/7.7/docker.html     |
+| [Filebeat](./filebeat/README.md)           | https://www.elastic.co/guide/en/beats/filebeat/7.7/running-on-docker.html   |
+| [Kibana](./kibana/README.md)               | https://www.elastic.co/guide/en/kibana/7.7/docker.html                      |
+| [Logstash](./logstash/README.md)           | https://www.elastic.co/guide/en/logstash/7.7/docker.html                    |
+| [Metricbeat](./metricbeat/README.md)       | https://www.elastic.co/guide/en/beats/metricbeat/7.7/running-on-docker.html |
 
 ## Kubernetes Versions
 
@@ -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+7.7/
+[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/7.7/helpers/helm-tester/Dockerfile
 [helpers/matrix.yml]: https://github.com/elastic/helm-charts/blob/7.7/helpers/matrix.yml
+[operator pattern]: https://kubernetes.io/docs/concepts/extend-kubernetes/operator/

apm-server/README.md

@@ -10,8 +10,9 @@
 - [Upgrading](#upgrading)
 - [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 -->
@@ -75,6 +76,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
 
@@ -115,28 +119,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
@@ -150,15 +149,20 @@ about our development and testing process.
 [CONTRIBUTING.md]: https://github.com/elastic/helm-charts/blob/master/CONTRIBUTING.md
 [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 docker image]: https://www.elastic.co/guide/en/apm/server/7.7/running-on-docker.html
+[apm server oss docker image]: https://www.docker.elastic.co/#apm-server-7-7-0-oss
 [default elasticsearch helm chart]: https://github.com/elastic/helm-charts/tree/7.7/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/7.7/apm-server/examples
+[examples/oss]: https://github.com/elastic/helm-charts/tree/7.7/apm-server/examples/oss
+[examples/security]: https://github.com/elastic/helm-charts/tree/7.7/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/default/README.md

@@ -0,0 +1,27 @@
+# Default
+
+This example deploy APM Server 7.7.0-SNAPSHOT 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/7.7/elasticsearch/examples/default/
+[goss integration tests]: https://github.com/elastic/helm-charts/tree/7.7/apm-server/examples/default/test/goss.yaml
+[default values]: https://github.com/elastic/helm-charts/tree/7.7/apm-server/values.yaml

apm-server/examples/oss/README.md

@@ -0,0 +1,27 @@
+# OSS
+
+This example deploy APM Server 7.7.0-SNAPSHOT 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/7.7/elasticsearch/examples/oss/
+[goss integration tests]: https://github.com/elastic/helm-charts/tree/7.7/apm-server/examples/oss/test/goss.yaml

apm-server/examples/security/README.md

@@ -0,0 +1,28 @@
+# Security
+
+This example deploy APM Server 7.7.0-SNAPSHOT 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/7.7/elasticsearch/examples/security/
+[goss integration tests]: https://github.com/elastic/helm-charts/tree/7.7/apm-server/examples/security/test/goss.yaml
+[values]: https://github.com/elastic/helm-charts/tree/7.7/apm-server/examples/security/values.yaml