Add contributor guide for destination (#812)

* Add contributor guide for destination Signed-off-by: Pete Wall <[email protected]> * Update contributing guide for features Signed-off-by: Pete Wall <[email protected]> * Fix lint issues Signed-off-by: Pete Wall <[email protected]> * Fix Markdown comment style Signed-off-by: Pete Wall <[email protected]> * No need to escape these characters Signed-off-by: Pete Wall <[email protected]> * Fix link Signed-off-by: Pete Wall <[email protected]> --------- Signed-off-by: Pete Wall <[email protected]>
grafana · Oct 23, 2024 · 6036b68 · 6036b68
1 parent ed99cf2
commit 6036b68
Show file tree

Hide file tree

Showing 3 changed files with 72 additions and 2 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -34,6 +34,17 @@ installing them for a better experience:
 
 Each chart has a Makefile with targets to automate much of the process.
 
+## Contributor Guides
+
+Each component has its own guide for contributing:
+
+<!-- [Main Helm chart](./charts/k8s-monitoring/README.md#Contributing) -->
+
+-   [Feature subcharts](./charts/k8s-monitoring/docs/Features.md#Contributing)
+-   [Destinations](./charts/k8s-monitoring/docs/destinations/README.md#Contributing)
+
+<!-- [Integrations](./charts/feature-integrations/README.md#Contributing) -->
+
 ## Building
 
 Lots of files in this repository are generated in order to reduce duplication and ensure consistency. To build these
@@ -58,7 +69,7 @@ Some charts will also generate additional templates and docs based on other file
 If your chart is dependent on external charts, you can update the dependencies by:
 
 1.  Set the dependency's version in Chart.yaml.
-2.  Update the Chart.lock file by running `make -C charts/&lt;the chart you are modifying&gt; build`.
+2.  Update the Chart.lock file by running `make -C charts/<the chart you are modifying> build`.
 
 ### Updating feature dependencies
 
@@ -99,7 +110,7 @@ chart and runs helm test as well.
 To run the integration tests for the `k8s-monitoring` chart, use the following commands:
 
 ```bash
-./scripts/run-integration-test.sh charts/k8s-monitoring/tests/integration/&lt;test dir&gt;
+./scripts/run-integration-test.sh charts/k8s-monitoring/tests/integration/<test dir>
 ```
 
 This will create a new Kubernetes cluster using kind, deploy any required dependencies, deploy the `k8s-monitoring` Helm

diff --git a/charts/k8s-monitoring/docs/Features.md b/charts/k8s-monitoring/docs/Features.md
@@ -65,3 +65,27 @@ Collect profiles using Pyroscope.
 [Documentation](https://github.com/grafana/k8s-monitoring-helm/tree/main/charts/feature-frontend-observability)
 
 Open a Faro receiver to collect telemetry data from instrumented frontend applications.
+
+## Contributing
+
+Features are stored in their own Helm chart. That chart is not a standalone chart, but is included in the main
+k8s-monitoring Helm chart as a dependency. The parent chart interacts with the feature chart via template functions.
+
+To add a new feature, create a new Helm chart in the `charts` directory. The chart should have a `feature-` prefix in
+its name. The following files are required for a feature chart:
+
+-   `templates/_module.alloy.tpl` - This file should contain a template function named
+    `feature.<feature-slug>.module` which should create an [Alloy module](https://grafana.com/docs/alloy/latest/get-started/modules/)
+    that wraps the configuration for your feature. It should expose any of these arguments as appropriate:
+    -   `metrics_destination` - An argument that defines where scrape metrics should be delivered.
+    -   `logs_destination` - An argument that defines where logs should be delivered.
+    -   `traces_destination` - An argument that defines where traces should be delivered.
+    -   `profiles_destination` - An argument that defines where profiles should be delivered.
+
+-   `templates/_notes.alloy.tpl` - This file should contain these template functions:
+    -   `feature.<feature-slug>.notes.deployments` - This function returns a list of workloads that will be
+    deployed to the Kubernetes Cluster by the feature.
+    -   `feature.<feature-slug>.notes.task` - This function returns a 1-line summary of what this feature will do.
+    -   `feature.<feature-slug>.notes.actions` - This function returns any prompts for the user to take additional
+        action after deployment.
+    -   `feature.<feature-slug>.summary` - This function a dictionary of settings, used for self-reporting metrics.
diff --git a/charts/k8s-monitoring/docs/destinations/README.md b/charts/k8s-monitoring/docs/destinations/README.md
@@ -138,3 +138,38 @@ podLogs:
 ```
 
 ![Example 3](./.images/example3.png)
+
+## Contributing
+
+Destinations use a specific set of files to define the destination configuration. These files are used to generate the
+destination configuration and documentation.
+
+Several files are used for defining a destination:
+
+-   `destinations/<destination slug>-values.yaml` - The values file that defines the valid configuration options
+  for the destination. It is a YAML file in the style of a Helm chart values file. This file is used to generate
+  documentation and schema files that will validate the options when deploying.
+-   `templates/destinations/_destination_<destination slug>.tpl` - The template file that generates the
+  destination configuration. This file is required to implement the following template functions:
+    -   `destinations.<destination slug>.alloy` - Returns the Alloy configuration for the destination.
+    -   `destinations.<destination slug>.secrets` - Returns a YAML list of values that should be considered secrets. This will control how the secret for this destination is generated and interfaced in the Alloy config.
+    -   `destinations.<destination slug>.supports_metrics` - Returns true if the destination supports metrics.
+    -   `destinations.<destination slug>.supports_logs` - Returns true if the destination supports logs.
+    -   `destinations.<destination slug>.supports_traces` - Returns true if the destination supports traces.
+    -   `destinations.<destination slug>.supports_profiles` - Returns true if the destination supports profiles.
+    -   `destinations.<destination slug>.ecosystem` - Returns the telemetry data ecosystem.
+    -   `destinations.<destination slug>.<ecosystem>.<data type>.target` - Returns the name of the Alloy target where telemetry data of the matching type and ecosystem should be sent.
+  Multiple target template functions can be made to support converting from one ecosystem to another.
+-   `docs/destinations/.doc_templates/<destination slug>.gotmpl` - The optional documentation template file for the
+  destination. This file can include examples, usage instructions, and other information about the destination.
+
+### Generated files
+
+When using `make build`, the following files will be updated or generated:
+
+-   `docs/destinations/<destination slug>.md` - The documentation file for the destination. This file is generated
+  from the destination values file and the destination template file.
+-   `values/destinations/<destination slug>.schema.json` - The JSON schema file for the destination values file. This
+  file is generated from the destination values file.
+-   `templates/destinations/_destination_types.tpl` - This template file is generated with the list of all possible
+  destination types.