docs: Improve upgrade guide and breaking change documentation (#331)

Signed-off-by: Christian Kreuzberger <[email protected]>

CHANGELOG.md

@@ -68,15 +68,16 @@ All notable changes to this project will be documented in this file. See [standa
 
 ## [0.2.0](https://github.com/keptn-contrib/job-executor-service/compare/0.1.8...0.2.0) (2022-05-04)
 
+:tada: This release focuses on :closed_lock_with_key: security hardening, quality assurance and refactoring.
 
 ### ⚠ BREAKING CHANGES
 
-* The `enableKubernetesApiAccess` flag is removed in favor of the serviceAccount configuration for jobs
-* - The job-executor-service is moved into it's own namespace (e.g.: keptn-jes) to isolate the jobs from other Keptn services
-- A valid Keptn API token is needed for the job-executor-service to function properly
-- A more restrictive service account is used for jobs
+- :joystick:  The `enableKubernetesApiAccess` flag is removed in favor of the `serviceAccount` configuration for jobs
+- :lock: The job-executor-service is moved into it's own namespace (e.g.: keptn-jes) to isolate the jobs from other Keptn services
+- :key: A valid Keptn API token and Keptn API endpoint need to be configured when installing job-executor-service (it is no longer possible to connect directly to Keptn's nats-cluster)
+- :robot:  A more restrictive service account is used for jobs by default
+- :egg: The default value for `remotecontrolPlane.api.protocol` has been set to `http` (was `https` before). Please take special care when upgrading and specify the desired protocol.
 
-Signed-off-by: Raphael Ludwig <[email protected]>
 
 ### Features
 
@@ -87,7 +88,7 @@ Signed-off-by: Raphael Ludwig <[email protected]>
 * Job security context ([#221](https://github.com/keptn-contrib/job-executor-service/issues/221)) ([9185e8e](https://github.com/keptn-contrib/job-executor-service/commit/9185e8e3ec1ec1dbdf6070ded245c102208d362f))
 * Move job-executor-service to it's own namespace ([#207](https://github.com/keptn-contrib/job-executor-service/issues/207)) ([8139bd5](https://github.com/keptn-contrib/job-executor-service/commit/8139bd5d228bca1686fbaff752da62290584e141))
 * Restrict service account of jobs ([#204](https://github.com/keptn-contrib/job-executor-service/issues/204)) ([07dd337](https://github.com/keptn-contrib/job-executor-service/commit/07dd33713383d264b9f2627aad96df0737e3b975))
-* send error log when error occurs before starting any job ([5768b46](https://github.com/keptn-contrib/job-executor-service/commit/5768b46cf4ea5a90024db59bddd2fbbfaa30364e))
+* Send error log when error occurs before starting any job ([5768b46](https://github.com/keptn-contrib/job-executor-service/commit/5768b46cf4ea5a90024db59bddd2fbbfaa30364e))
 * Upgrade to Keptn 0.13 ([#228](https://github.com/keptn-contrib/job-executor-service/issues/228)) ([c287632](https://github.com/keptn-contrib/job-executor-service/commit/c287632ccc865e33b8798cfb365d6f83a21fb49a))
 
 

docs/INSTALL.md

@@ -8,7 +8,7 @@ During the installation process various parameters of the *job-executor-service*
 of these helm values have a look at the [documentation](../chart/README.md).
 In order to install the *job-executor-service* on the remote execution plane, some values of the helm chart need to be configured:
 * `remoteControlPlane.topicSubscription` - list of Keptn CloudEvent types that this instance should listen to, e.g., `sh.keptn.event.remote-task.triggered`
-* `remoteControlPlane.api.protocol` - protocol (`http` or `https`) used to connect to the remote control plane
+* `remoteControlPlane.api.protocol` - protocol (`http` or `https`) used to connect to the remote control plane (default: `http` - this has changed with the [0.2.0 release](https://github.com/keptn-contrib/job-executor-service/releases/tag/0.2.0))
 * `remoteControlPlane.api.hostname` - Keptn API Hostname (e.g., `1.2.3.4.nip.io`). If Keptn is installed on the same cluster the API is usually reachable under `api-gateway-nginx.keptn`.
 * `remoteControlPlane.api.token` - Keptn API Token (can be obtained from Bridge)
 * `remoteControlPlane.api.authMode` - Authentication mode which should be used when communicating with Keptn. Must be either `token` or `oauth`. Defaults to `token` if omitted
@@ -122,19 +122,37 @@ helm upgrade -n <NAMESPACE> \
 
 ## Upgrade
 
-To upgrade to a newer version of *job-executor-service*, first save the existing installation values to a helm override
-file
-```shell
+### Preparation
+
+To upgrade to a newer version of *job-executor-service*, first figure out what version you are currently on:
+```bash
+helm -n <NAMESPACE> list job-executor-service
+```
+or via looking at your Keptn Bridge Integration page.
+
+Then figure out which version you want to upgrade to, e.g., from the [GitHub Releases Page](https://github.com/keptn-contrib/job-executor-service/releases).
+
+**Note**: Please get informed about breaking changes via the release notes provided for each release or via looking at
+our [Changelog](../CHANGELOD.md).
+
+### Perform the upgrade
+
+First save the existing installation values to a helm override file:
+```bash
 helm -n <NAMESPACE> get values job-executor-service > values.yaml
 ```
-then upgrade using the previous installation value file as an override
+Perform any changes on values.yaml, especially with breaking changes in mind. Please avoid using 
+`helm upgrade ... --reuse-values` as there are some [limitations](https://github.com/helm/helm/issues/8085), especially
+regarding default values.
+
+Then upgrade using the previous installation value file as an override
 ```bash
 helm upgrade -n <NAMESPACE> \
   job-executor-service https://github.com/keptn-contrib/job-executor-service/releases/download/<VERSION>/job-executor-service-<VERSION>.tgz \
   -f values.yaml
 ```
 
-To upgrade to a newer version of *job-executor-service* and automatically use the auto-detection to configure the Keptn 
+In order to upgrade to a newer version of *job-executor-service* and automatically use the auto-detection to configure the Keptn 
 API token, the `helm upgrade` command should be:
 ```bash
 helm upgrade -n <NAMESPACE> \
@@ -143,14 +161,10 @@ helm upgrade -n <NAMESPACE> \
   --set remoteControlPlane.api.token="",remoteControlPlane.api.hostname="",remoteControlPlane.api.protocol=""
 ```
 
-**Note:** during upgrade we dump the existing installation values to a file and use it as an override file to work around
-some of the `helm upgrade --reuse-values` [limitations](https://github.com/helm/helm/issues/8085) and make sure that new
-default values are applied as expected when upgrading job-executor-service to a newer version.
-
 ## Uninstall
 
 To uninstall *job-executor-service*, run
 
 ```bash
 helm uninstall -n <NAMESPACE> job-executor-service
-```
+```