From 2f36dad47472e00deb9e82f58b669d73d9b93d84 Mon Sep 17 00:00:00 2001 From: Julien Mailleret Date: Wed, 22 Apr 2020 23:03:31 +0200 Subject: [PATCH] [meta] centralize development and testing doc in CONTRIBUTING.md --- CONTRIBUTING.md | 118 +++++++++++++++++++++++++++++++++++++--- apm-server/README.md | 40 ++------------ elasticsearch/README.md | 40 ++------------ filebeat/README.md | 40 ++------------ kibana/README.md | 26 ++------- logstash/README.md | 40 ++------------ metricbeat/README.md | 40 ++------------ 7 files changed, 133 insertions(+), 211 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8dd908c8f..5bc54a2aa 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,21 +1,121 @@ # Contributing to the Elastic helm charts +## Requirements for submiting a pull request + +Before submitting a pull request make sure you validated the following +requirements: + +* CLA should be signed (see [CLA section][] for more details). + +* Charts version shouldn't be bumped (see [Releases section][] for more +details). + +* Charts `README.md` should be updated if required (especially updating default +values if they have been changed). + +* Templating tests should be added/updated (see [Templating tests section][] for +more details). + +* Integration tests should be added/updated (see [Integration tests section][] +for more details). + ## CLA (Contributor License Agreement) -If you haven't already you will need to sign the [CLA](https://www.elastic.co/contributor-agreement) before your pull request can be reviewed and merged. +If you haven't already you will need to sign the [CLA][] before your pull +request can be reviewed and merged. + +## Branches workflow + +Pull request are merged on `master` branch, then they should be backported to +version branches (example `7.7` branch). + +>TODO: add more details about version branching. + +# Releases + +Just like with the rest of the stack, all versions in this helm chart repo are +bumped and released at the same time. There is no need to bump the version in +your pull request. + +Charts are released from version branchs (example `7.7` branch). + +[Elastic Helm repository][] is updated only during releases. + +>TODO: add more details about releases (see also [release.md][]). -## Version bumps +## Testing -Just like with the rest of the stack, all versions in this helm chart repo are bumped and released at the same time. There is no need to bump the version in your pull request. +### Templating tests -## Testing and documentation +Templating tests which can be found in `${CHART}/tests/*.py` +([Example][templating test example]). -When making any changes be sure to also update the following: +These charts use [pytest][] to test the templating logic. The dependencies for +testing can be installed from the [requirements.txt][] in the parent directory: -* Charts README.md -* The templating tests which can be found in `${CHART}/tests/*.py`. [Example](/elasticsearch/tests/elasticsearch_test.py) -* The integration tests which can be found in `${CHART}/examples/*/test/goss.yaml`. [Example](/elasticsearch/examples/default/test/goss.yaml) +``` +pip install -r ./requirements.txt +``` + +Tests can then be run from each chart directory using `make pytest` + +You can also use `make template` (equivalent to `helm template` ) to look at the +YAML being generated: + +It is possible to run all of the tests and linting inside of a Docker container +using `make test` + +Note that templating tests are formated using [Black][], you should run +`make lint-python` (equivalent to `black --diff --check .` ) to validate them or +`black .` to apply formatting before submitting a pull request which will modify +them. + +### Integration tests + +Integration tests which can be found in `${CHART}/examples/*/test/goss.yaml` +([Example][integration test example]). + +Integration tests are run using [goss][] which is a [Serverspec][] like tool +written in golang. See [integration test example][] for an example of what the +tests look like. + +The different integration tests are present in each chart's `examples` +directory. + +Each charts contains an `examples/default` integration test which validate the +chart deployment with default values. + +`examples` directory contains also integration tests for other use cases (for +example: using `oss` Docker images, using `6.x` version or using `security` ). + +Every directory which contains some `test` subdirectory is an integration test +(`examples` directory contains also some configuration examples for some +specific scenarios without tests like configuration for specific k8s providers). + +To run the goss tests against the default example: + +``` +cd examples/default +make goss +``` ## Adding new features -If you aren't 100% sure that this is a feature that makes sense for everyone. Please open an issue first to discuss with the maintainers before investing a lot of time into it. +If you aren't 100% sure that this is a feature that makes sense for everyone. +Please open an issue first to discuss with the maintainers before investing a +lot of time into it. + +[black]: https://black.readthedocs.io/en/stable/ +[cla]: https://www.elastic.co/contributor-agreement +[cla section]: #cla-contributor-license-agreement +[elastic helm repository]: https://helm.elastic.co +[goss]: https://github.com/aelsabbahy/goss/blob/master/docs/manual.md +[integration test example]: https://github.com/elastic/helm-charts/blob/master/elasticsearch/examples/default/test/goss.yaml +[integration tests section]: #integration-tests +[pytest]: https://docs.pytest.org/en/latest/ +[serverspec]: https://serverspec.org +[templating test example]: https://github.com/elastic/helm-charts/blob/master/elasticsearch/tests/elasticsearch_test.py +[templating tests section]: #templating-tests +[release.md]: https://github.com/elastic/helm-charts/blob/master/helpers/release.md +[releases section]: #releases +[requirements.txt]: https://github.com/elastic/helm-charts/blob/master/requirements.txt \ No newline at end of file diff --git a/apm-server/README.md b/apm-server/README.md index 7bebb0f2f..1f222b26f 100644 --- a/apm-server/README.md +++ b/apm-server/README.md @@ -130,48 +130,18 @@ used for the automated testing of this Helm chart. curl localhost:9200/_cat/indices ``` -## Testing +## Contributing -This chart uses [pytest][] to test the templating logic. The dependencies for -testing can be installed from the [requirements.txt][] in the parent directory: - -``` -pip install -r ../requirements.txt -make pytest -``` - -You can also use `helm template` to look at the YAML being generated: - -``` -make template -``` - -It is possible to run all of the tests and linting inside of a Docker container: - -``` -make test -``` - -## Integration Testing - -Integration tests are run using [goss][] which is a serverspec like tool written -in golang. See [goss.yaml][] for an example of what the tests look like. - -To run the goss tests against the default example: - -``` -cd examples/default -make goss -``` +Please check [CONTRIBUTING.md][] before any contribution or for any questions +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 +[contributing.md]: https://github.com/elastic/helm-charts/blob/master/CONTRIBUTING.md [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 [examples]: https://github.com/elastic/helm-charts/tree/master/apm-server/examples -[goss]: https://github.com/aelsabbahy/goss/blob/master/docs/manual.md -[goss.yaml]: https://github.com/elastic/helm-charts/tree/master/apm-server/examples/default/test/goss.yaml [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 @@ -183,8 +153,6 @@ make goss [podSecurityContext]: https://kubernetes.io/docs/tasks/configure-pod-container/security-context/ [priorityClass]: https://kubernetes.io/docs/concepts/configuration/pod-priority-preemption/#priorityclass [probe]: https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-probes/ -[pytest]: https://docs.pytest.org/en/latest/ -[requirements.txt]: https://github.com/elastic/helm-charts/tree/master/requirements.txt [resources]: https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/ [service]: https://kubernetes.io/docs/concepts/services-networking/service/ [serviceAccount]: https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/ diff --git a/elasticsearch/README.md b/elasticsearch/README.md index edd858fdd..cb23e515f 100644 --- a/elasticsearch/README.md +++ b/elasticsearch/README.md @@ -421,39 +421,10 @@ For an example of deploying both a group master nodes and data nodes using multiple releases of this chart, see the accompanying values files in `examples/multi`. -## Testing +## Contributing -This chart uses [pytest][] to test the templating logic. The dependencies for -testing can be installed from the [requirements.txt][] in the parent directory: - -``` -pip install -r ../requirements.txt -make pytest -``` - -You can also use `helm template` to look at the YAML being generated: - -``` -make template -``` - -It is possible to run all of the tests and linting inside of a Docker container: - -``` -make test -``` - -## Integration Testing - -Integration tests are run using [goss][] which is a serverspec like tool written -in golang. See [goss.yaml][] for an example of what the tests look like. - -To run the goss tests against the default example: - -``` -cd examples/default -make goss -``` +Please check [CONTRIBUTING.md][] before any contribution or for any questions +about our development and testing process. [#63]: https://github.com/elastic/helm-charts/issues/63 [#458]: https://github.com/elastic/helm-charts/pull/458 @@ -461,6 +432,7 @@ make goss [alternate scheduler]: https://kubernetes.io/docs/tasks/administer-cluster/configure-multiple-schedulers/#specify-schedulers-for-pods [annotations]: https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/ [anti-affinity]: https://kubernetes.io/docs/concepts/configuration/assign-pod-node/#affinity-and-anti-affinity +[contributing.md]: https://github.com/elastic/helm-charts/blob/master/CONTRIBUTING.md [cluster.name]: https://www.elastic.co/guide/en/elasticsearch/reference/current/cluster.name.html [clustering and node discovery]: https://github.com/elastic/helm-charts/tree/master/elasticsearch/README.md#clustering-and-node-discovery [config example]: https://github.com/elastic/helm-charts/tree/master/elasticsearch/examples/config/values.yaml @@ -473,8 +445,6 @@ make goss [elasticsearch docker image]: https://www.elastic.co/guide/en/elasticsearch/reference/current/docker.html [environment variables]: https://kubernetes.io/docs/tasks/inject-data-application/define-environment-variable-container/#using-environment-variables-inside-of-your-config [examples]: https://github.com/elastic/helm-charts/tree/master/elasticsearch/examples/ -[goss]: https://github.com/aelsabbahy/goss/blob/master/docs/manual.md -[goss.yaml]: https://github.com/elastic/helm-charts/tree/master/elasticsearch/examples/default/test/goss.yaml [helm]: https://helm.sh [helm/charts stable]: https://github.com/helm/charts/tree/master/stable/elasticsearch/ [how to install plugins guide]: https://github.com/elastic/helm-charts/tree/master/elasticsearch/README.md#how-to-install-plugins @@ -502,8 +472,6 @@ make goss [parent readme]: https://github.com/elastic/helm-charts/tree/master/README.md [priorityClass]: https://kubernetes.io/docs/concepts/configuration/pod-priority-preemption/#priorityclass [probe]: https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-probes/ -[pytest]: https://docs.pytest.org/en/latest/ -[requirements.txt]: https://github.com/elastic/helm-charts/tree/master/requirements.txt [resources]: https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/ [roles]: https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-node.html [secret]: https://kubernetes.io/docs/concepts/configuration/secret/#using-secrets diff --git a/filebeat/README.md b/filebeat/README.md index dfeec9c47..94e93bfdc 100644 --- a/filebeat/README.md +++ b/filebeat/README.md @@ -140,48 +140,18 @@ indices: curl localhost:9200/_cat/indices ``` -## Testing +## Contributing -This chart uses [pytest][] to test the templating logic. The dependencies for -testing can be installed from the [requirements.txt][] in the parent directory: - -``` -pip install -r ../requirements.txt -make pytest -``` - -You can also use `helm template` to look at the YAML being generated: - -``` -make template -``` - -It is possible to run all of the tests and linting inside of a Docker container: - -``` -make test -``` - -## Integration Testing - -Integration tests are run using [goss][] which is a serverspec like tool written -in golang. See [goss.yaml][] for an example of what the tests look like. - -To run the goss tests against the default example: - -``` -cd examples/default -make goss -``` +Please check [CONTRIBUTING.md][] before any contribution or for any questions +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/ +[contributing.md]: https://github.com/elastic/helm-charts/blob/master/CONTRIBUTING.md [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 [examples]: https://github.com/elastic/helm-charts/tree/master/filebeat/examples [filebeat docker image]: https://www.elastic.co/guide/en/beats/filebeat/current/running-on-docker.html -[goss]: https://github.com/aelsabbahy/goss/blob/master/docs/manual.md -[goss.yaml]: https://github.com/elastic/helm-charts/tree/master/filebeat/examples/default/test/goss.yaml [helm]: https://helm.sh [hostNetwork]: https://kubernetes.io/docs/concepts/policy/pod-security-policy/#host-namespaces [hostPath]: https://kubernetes.io/docs/concepts/storage/volumes/#hostpath @@ -193,8 +163,6 @@ make goss [podSecurityContext]: https://kubernetes.io/docs/tasks/configure-pod-container/security-context/ [priorityClass]: https://kubernetes.io/docs/concepts/configuration/pod-priority-preemption/#priorityclass [probe]: https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-probes/ -[pytest]: https://docs.pytest.org/en/latest/ -[requirements.txt]: https://github.com/elastic/helm-charts/tree/master/requirements.txt [resources]: https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/ [serviceAccount]: https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/ [tolerations]: https://kubernetes.io/docs/concepts/configuration/taint-and-toleration/ diff --git a/kibana/README.md b/kibana/README.md index 0bd21115d..5fd1e52e6 100644 --- a/kibana/README.md +++ b/kibana/README.md @@ -180,29 +180,13 @@ random times. 2. Mutating the state of a running Docker image (by installing plugins) goes against best practices of containers and immutable infrastructure. -## Testing +## Contributing -This chart uses [pytest][] to test the templating logic. The dependencies for -testing can be installed from the [requirements.txt][] in the parent directory: - -``` -pip install -r ../requirements.txt -make test -``` - -You can also use `helm template` to look at the YAML being generated: - -``` -make template -``` - -It is possible to run all of the tests and linting inside of a Docker container: - -``` -make test -``` +Please check [CONTRIBUTING.md][] before any contribution or for any questions +about our development and testing process. [annotations]: https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/ +[contributing.md]: https://github.com/elastic/helm-charts/blob/master/CONTRIBUTING.md [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 [kibana docker image]: https://www.elastic.co/guide/en/kibana/current/docker.html @@ -216,8 +200,6 @@ make test [parent readme]: https://github.com/elastic/helm-charts/tree/master/README.md [priorityClass]: https://kubernetes.io/docs/concepts/configuration/pod-priority-preemption/#priorityclass [probe]: https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-probes/ -[pytest]: https://docs.pytest.org/en/latest/ -[requirements.txt]: https://github.com/elastic/helm-charts/tree/master/requirements.txt [resources]: https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/ [security enabled elasticsearch cluster]: https://github.com/elastic/helm-charts/tree/master/elasticsearch/README.md#security [securityContext]: https://kubernetes.io/docs/tasks/configure-pod-container/security-context/#set-the-security-context-for-a-pod diff --git a/logstash/README.md b/logstash/README.md index 78f2e5d90..4d96917ef 100644 --- a/logstash/README.md +++ b/logstash/README.md @@ -173,49 +173,19 @@ random times. 2. Mutating the state of a running Docker image (by installing plugins) goes against best practices of containers and immutable infrastructure. -## Testing +## Contributing -This chart uses [pytest][] to test the templating logic. The dependencies for -testing can be installed from the [requirements.txt][] in the parent directory: - -``` -pip install -r ../requirements.txt -make pytest -``` - -You can also use `helm template` to look at the YAML being generated: - -``` -make template -``` - -It is possible to run all of the tests and linting inside of a Docker container: - -``` -make test -``` - -## Integration Testing - -Integration tests are run using [goss][] which is a serverspec like tool written -in golang. See [goss.yaml][] for an example of what the tests look like. - -To run the goss tests against the default example: - -``` -cd examples/default -make goss -``` +Please check [CONTRIBUTING.md][] before any contribution or for any questions +about our development and testing process. [alternate scheduler]: https://kubernetes.io/docs/tasks/administer-cluster/configure-multiple-schedulers/#specify-schedulers-for-pods [annotations]: https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/ [anti-affinity]: https://kubernetes.io/docs/concepts/configuration/assign-pod-node/#affinity-and-anti-affinity +[contributing.md]: https://github.com/elastic/helm-charts/blob/master/CONTRIBUTING.md [deploys statefulsets serially]: https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/#pod-management-policies [custom docker image]: https://www.elastic.co/guide/en/logstash/current/docker-config.html#_custom_images [environment variables]: https://kubernetes.io/docs/tasks/inject-data-application/define-environment-variable-container/#using-environment-variables-inside-of-your-config [examples]: https://github.com/elastic/helm-charts/tree/master/logstash/examples -[goss]: https://github.com/aelsabbahy/goss/blob/master/docs/manual.md -[goss.yaml]: https://github.com/elastic/helm-charts/tree/master/logstash/examples/default/test/goss.yaml [helm]: https://helm.sh [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 @@ -228,8 +198,6 @@ make goss [parent readme]: https://github.com/elastic/helm-charts/tree/master/README.md [priorityClass]: https://kubernetes.io/docs/concepts/configuration/pod-priority-preemption/#priorityclass [probe]: https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-probes/ -[pytest]: https://docs.pytest.org/en/latest/ -[requirements.txt]: https://github.com/elastic/helm-charts/tree/master/requirements.txt [resources]: https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/ [updateStrategy]: https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/ [securityContext]: https://kubernetes.io/docs/tasks/configure-pod-container/security-context/#set-the-security-context-for-a-pod diff --git a/metricbeat/README.md b/metricbeat/README.md index d1e4c297e..c1ccc3cc2 100644 --- a/metricbeat/README.md +++ b/metricbeat/README.md @@ -169,51 +169,21 @@ indices: curl localhost:9200/_cat/indices ``` -## Testing +## Contributing -This chart uses [pytest][] to test the templating logic. The dependencies for -testing can be installed from the [requirements.txt][] in the parent directory: - -``` -pip install -r ../requirements.txt -make pytest -``` - -You can also use `helm template` to look at the YAML being generated: - -``` -make template -``` - -It is possible to run all of the tests and linting inside of a Docker container: - -``` -make test -``` - -## Integration Testing - -Integration tests are run using [goss][] which is a serverspec like tool written -in golang. See [goss.yaml][] for an example of what the tests look like. - -To run the goss tests against the default example: - -``` -cd examples/default -make goss -``` +Please check [CONTRIBUTING.md][] before any contribution or for any questions +about our development and testing process. [#395]: https://github.com/elastic/helm-charts/issues/395 [7.5.1]: https://github.com/elastic/helm-charts/releases/tag/7.5.1 [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/ +[contributing.md]: https://github.com/elastic/helm-charts/blob/master/CONTRIBUTING.md [default elasticsearch helm chart]: https://github.com/elastic/helm-charts/tree/master/elasticsearch/README.md#default [cluster role rules]: https://kubernetes.io/docs/reference/access-authn-authz/rbac/#role-and-clusterrole [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/metricbeat/examples -[goss]: https://github.com/aelsabbahy/goss/blob/master/docs/manual.md -[goss.yaml]: https://github.com/elastic/helm-charts/tree/master/metricbeat/examples/default/test/goss.yaml [helm]: https://helm.sh [helm/charts#15261]: https://github.com/helm/charts/pull/15261 [hostPath]: https://kubernetes.io/docs/concepts/storage/volumes/#hostpath @@ -226,8 +196,6 @@ make goss [nodeSelector]: https://kubernetes.io/docs/concepts/configuration/assign-pod-node/#nodeselector [parent readme]: https://github.com/elastic/helm-charts/tree/master/README.md [probe]: https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-probes -[pytest]: https://docs.pytest.org/en/latest/ -[requirements.txt]: https://github.com/elastic/helm-charts/tree/master/requirements.txt [resources]: https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/ [securityContext]: https://kubernetes.io/docs/tasks/configure-pod-container/security-context/ [serviceAccount]: https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/