elastic / elastic/elastic-package
Alerting v2 templates have gaps in generated docs, build validation, and asset tests
- Dominant language
- Go
- Stars
- 72
- Forks
- 141
- Avg merge
- 19h 42m
- Merged PRs (30d)
- 55
Description
## Summary
Packages can contain Alerting v2 `alerting_rule_template` assets, but successful package builds and asset-loading tests do not currently provide complete coverage for those templates. There are also gaps in their generated documentation.
This matters when publishing classic and v2 templates side by side: a package can build successfully while its v2 templates are undocumented or absent from the asset-test assertions.
## Steps to reproduce
Use a disposable package with `kibana/alerting_rule_template/` assets and a README template containing `{{alertRuleTemplates}}`.
### 1. Generated documentation
Include a v2 template whose display metadata is under `attributes.rule.metadata`, alongside a classic template whose metadata is directly under `attributes`. Run:
```sh
elastic-package build
```
Inspect the generated alert-rule-template section. The current upstream renderer reads only the classic metadata locations and always reports a minimum Stack version of 9.2.0. V2 names/descriptions are therefore not represented correctly, and the version statement does not account for the v2 engine's 9.6 requirement.
### 2. Asset-loading coverage
With a compatible local stack running, run:
```sh
elastic-package test asset
```
Inspect the individual test cases. `alerting_rule_template` is absent from the expected Kibana asset types, so neither classic nor v2 template IDs receive an installation assertion. Package installation can still fail for other reasons, but a successful asset test does not establish that these templates were loaded.
### 3. Invalid v2 content accepted during build
Add this intentionally invalid asset to an otherwise buildable package:
```json
{
"id": "invalid-v2-example",
"type": "alerting_rule_template",
"attributes": {
"engine": "v2",
"rule": {
"metadata": {
"name": "Invalid v2 example",
"description": "Build validation reproduction"
},
"kind": "not-a-valid-rule-kind",
"query": {
"format": "composed",
"base": "THIS IS NOT ESQL"
}
}
}
}
```
Run `elastic-package build` without `--skip-validation`. In the tested checkout, the command succeeds and includes this file in the ZIP, despite the invalid rule kind, missing schedule, and invalid query text.
## Expected behavior
- Generated documentation accurately represents v2 templates and their Stack compatibility; readers can distinguish the engines when both are published.
- Asset-loading results account for each alert-rule-template ID, including missing templates.
- Invalid v2 rule structures are not reported as successfully validated package content. The distinction between package validation and stack-side query validation is clear.
## Actual behavior and impact
- V2 metadata is not read correctly by the upstream documentation renderer.
- Template IDs are omitted from asset-loading assertions.
- The invalid v2 example above is packaged successfully.
These gaps make it difficult to tell whether a package containing v2 templates is ready to publish. Preserving the JSON in a build artifact is not equivalent to validating the rule or confirming its installation and behavior.
## Environment and evidence
- Local `elastic-package` build based on `63cd101ba394`.
- Package-spec dependency: `github.com/elastic/package-spec/v3 v3.5.5`.
- Local stack: Kibana `9.6.0-SNAPSHOT`.
- A disposable copy of `system` containing six classic and six v2 templates built successfully; all twelve template files were preserved byte-for-byte in the ZIP.
- The invalid-content build reproduction was tested locally. The documentation and expected-asset-list gaps were also checked against upstream `main` at `444d7948a9398b8dbbeb3d140bb644c404c8f287`:
- [Alert-rule-template documentation renderer](https://github.com/elastic/elastic-package/blob/444d7948a9398b8dbbeb3d140bb644c404c8f287/internal/docs/alert_rule_template.go)
- [Expected package assets](https://github.com/elastic/elastic-package/blob/444d7948a9398b8dbbeb3d140bb644c404c8f287/internal/packages/assets.go)
The asset-coverage gap also affects classic templates; it is not exclusive to v2.
## Related references
- [Kibana #281861: rule-template saved-object support for v1 and v2 shapes](https://github.com/elastic/kibana/pull/281861).
- [Kibana #285421: separate Classic and Alerting v2 template tabs in Fleet](https://github.com/elastic/kibana/pull/285421).
- [Kibana #285278: list and install v2 templates from the rule library](https://github.com/elastic/kibana/pull/285278).
- [V2 template schema](https://github.com/elastic/kibana/blob/main/x-pack/platform/packages/shared/response-ops/alerting-v2-schemas/src/rule_template_schema.ts): expected template attributes and create-rule payload relationship.
- [Official Alerting v2 API documentation](https://www.elastic.co/docs/api/doc/kibana/group/endpoint-alerting-v2): API context and experimental status.
Contributor guide
No contributing guide indexed for this repository
Research direction
Start with internal/docs/alert_rule_template.go and internal/packages/assets.go, then reproduce the documented cases with elastic-package build and elastic-package test asset. Trace the build-validation path for the v2 example and confirm that generated docs, asset assertions, and invalid-content handling cover both classic and v2 templates without weakening the package-versus-stack validation distinction.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- go
- Domain
- build-system, documentation, testing, tooling
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100