Initial commit

charts/loki/scenarios/README.md

@@ -0,0 +1,82 @@
+# Loki Helm Scenarios
+
+These scenarios are used by Github Workflow: [Publish Rendered Helm Chart Diff](../../../../.github/workflows/helm-diff-ci.yml).
+
+Each scenario is used in a different job execution that will be used to deploy loki inside a K3D cluster in our github action workflow.
+
+We deploy the scenario with the latest release and then we execute a helm diff with the current version in the workspace, the diff between the release deployed will be posted in the pull request inside a comment like [this](https://github.com/grafana/loki/pull/15734#issuecomment-2592439539) making clear to review.
+
+>*NOTE*: the helm diff output file will be available for each scenario inside github action to download for 2 days, after this you may need to re-run the job if you would like to download the output files.
+
+## Add new scenario to the CI
+
+To add a new scenario in the CI, you would just add a new entry to the matrix configuration:
+
+```
+strategy:
+  matrix:
+    scenario:
+      - name: New Scenario
+        values_file: new-scenario-values.yaml
+        use_k3d: true  # or false depending on requirements
+```
+
+## Run scenarios locally
+
+All this process that we run in the CI can be done locally, the following steps would explain how.
+
+## Requirements
+
+To run locally you will need the following tools in your local environment
+
+* k3d or any kubernetes cluster
+* helm
+* [helm-diff plugin](https://github.com/databus23/helm-diff)
+
+## Run
+
+Make sure that you are pointing to the kubernetes cluster that you want to apply the chart and validate.
+
+Create a `${scenario}-values.yaml` file with the configuration that you would like to validate.
+
+Deploy in your kubernetes cluster the latest released version of the helm chart with your config file:
+
+```shell
+  helm install --create-namespace loki-release grafana/loki -f ${scenario}-values.yaml
+```
+
+ Then run the helm diff plugin to compare the local helm chart to see the upgrade changes that will happen:
+
+```shell
+    HELM_DIFF_USE_UPGRADE_DRY_RUN: true helm diff upgrade loki-release -f ${scenario}-values.yaml production/helm/loki
+```
+
+The helm diff plugin will compare all manifests that are created in your local development kubernetes cluster and the generated by helm upgrade operation, the output will be printed in your terminal.
+
+### Configs for CSP specific
+
+To compare the changes specifically for a cloud provider the process is similar, the main difference that you will need to have access to the kubernetes cluster with the right permissions inside the cloud provider.
+
+In case that is not possible, the quick validation can be done in a different way, instead of deploy to the kubernetes cluster, we generate the manifests with helm like this:
+
+```shell
+  helm template loki-release grafana/loki -f ${scenario}-values.yaml > release-manifest.yaml
+```
+
+Then we make the same process with local chart version
+
+```shell
+  helm template loki-release production/helm/loki -f ${scenario}-values.yaml > current-manifest.yaml
+```
+
+As the last step you need to run a diff between both files:
+
+```shell
+  diff current-manifest.yaml release-manifest.yaml
+```
+
+### Known Issues
+
+* The Github Action won't be able to post the diff comment if the PR is coming from a fork, because of permissions the workflow run from a fork is not able to write in the PR content.
+
+  In this case, to review the output we recommend to download the artifacts in the workflow run and check the outputs.