diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e7d998c9d..ccdf725c6 100644 --- 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: + + + +- [Feature subcharts](./charts/k8s-monitoring/docs/Features.md#Contributing) +- [Destinations](./charts/k8s-monitoring/docs/destinations/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/<the chart you are modifying> build`. +2. Update the Chart.lock file by running `make -C charts/ 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/<test dir> +./scripts/run-integration-test.sh charts/k8s-monitoring/tests/integration/ ``` 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 index d42049843..2cb01c44d 100644 --- 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..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..notes.deployments` - This function returns a list of workloads that will be + deployed to the Kubernetes Cluster by the feature. + - `feature..notes.task` - This function returns a 1-line summary of what this feature will do. + - `feature..notes.actions` - This function returns any prompts for the user to take additional + action after deployment. + - `feature..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 index 30928c41b..2fe77e95c 100644 --- 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/-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_.tpl` - The template file that generates the + destination configuration. This file is required to implement the following template functions: + - `destinations..alloy` - Returns the Alloy configuration for the destination. + - `destinations..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..supports_metrics` - Returns true if the destination supports metrics. + - `destinations..supports_logs` - Returns true if the destination supports logs. + - `destinations..supports_traces` - Returns true if the destination supports traces. + - `destinations..supports_profiles` - Returns true if the destination supports profiles. + - `destinations..ecosystem` - Returns the telemetry data ecosystem. + - `destinations....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/.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/.md` - The documentation file for the destination. This file is generated + from the destination values file and the destination template file. +- `values/destinations/.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.