elastic / elastic/elastic-package

Alerting v2 templates have gaps in generated docs, build validation, and asset tests

Open
#3,946 0 comments 0 reactions 0 assignees View on GitHub
enhancement
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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.