Skip to content

Commit 964852e

Browse files
authored
Add guidelines about the format version to use (#2291)
1 parent 79e380f commit 964852e

File tree

1 file changed

+42
-0
lines changed

1 file changed

+42
-0
lines changed

docs/howto/format_version.md

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
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

Comments
 (0)