|
| 1 | +# Guidelines for the format version to use in a package |
| 2 | + |
| 3 | +Packages need to indicate the version of the [Package Spec](https://github.com/elastic/package-spec) they are using. |
| 4 | +This is done by setting the `format_version` field in the main manifest. |
| 5 | + |
| 6 | +The version of the spec used influences the features available for the package, |
| 7 | +the validations that are performed and some formatting rules. In general newer |
| 8 | +versions include more validations intended to improve the reliability of |
| 9 | +packages. They also include definitions that enable the use of some features. |
| 10 | + |
| 11 | +Some stack versions restrict the discovery and installation of packages of |
| 12 | +specific spec versions. This helps to avoid using packages that require features |
| 13 | +that are not available in older versions of the stack. |
| 14 | + |
| 15 | +## What format versions are supported by each version of the stack? |
| 16 | + |
| 17 | +This is controlled in two places now: |
| 18 | +- In the [Kibana default configuration](https://github.com/elastic/kibana/blob/84fcda021be1d71018fa77005837da7e932c6d7f/x-pack/plugins/fleet/server/config.ts#L224). |
| 19 | +- In the user-provided configuration of Kibana, by setting |
| 20 | + `xpack.fleet.internal.registry.spec.min` and/or |
| 21 | + `xpack.fleet.internal.registry.spec.max`. |
| 22 | + |
| 23 | +At the moment of writing this document, the following rules can be assumed: |
| 24 | +- Stacks older than 8.16 support all versions of the spec till 3.0.x. |
| 25 | +- Stacks from 8.16 support all versions of the spec till 3.3.x. |
| 26 | +- Serverless projects support versions of the stack from 3.0.0 to 3.3.x. |
| 27 | + |
| 28 | +In case of doubt, you can check the Fleet default configuration, and the |
| 29 | +configuration overrides in the Kibana repository. |
| 30 | + |
| 31 | +## What format version to choose for a package? |
| 32 | + |
| 33 | +The general rule of thumb is to use the latest version that enables everything |
| 34 | +that is required for a package. |
| 35 | + |
| 36 | +The safest option, to support a broader range of stack versions, and a greater |
| 37 | +number of features, would be to use 3.0.4. If you need some newer feature, you |
| 38 | +would need to increase this version, but this can limit the availability of the |
| 39 | +package in older versions of the stack. |
| 40 | + |
| 41 | +Regarding compatibility with versions of the stack, check also the [guidelines |
| 42 | +for stack version constraints](./stack_version_support.md). |
0 commit comments