Readme.md
1# Schema Reference
2
3Pacemaker's XML schema has a version of its own, independent of the version of
4Pacemaker itself.
5
6## Versioned Schema Evolution
7
8A versioned schema offers transparent backward and forward compatibility.
9
10- It reflects the timeline of schema-backed features (introduction,
11 changes to the syntax, possibly deprecation) through the versioned
12 stable schema increments, while keeping schema versions used by default
13 by older Pacemaker versions untouched.
14
15- Pacemaker internally uses the latest stable schema version, and relies on
16 supplemental transformations to promote cluster configurations based on
17 older, incompatible schema versions into the desired form.
18
19- It allows experimental features with a possibly unstable configuration
20 interface to be developed using the special `next` version of the schema.
21
22## Mapping Pacemaker Versions to Schema Versions
23
24| Pacemaker | Latest Schema | Changed
25| --------- | ------------- | ----------------------------------------------
26| `1.1.18`+ | `2.10` | `resources`, `alerts`
27| `1.1.17` | `2.9` | `resources`, `rule`
28| `1.1.16` | `2.6` | `constraints`
29| `1.1.15` | `2.5` | `alerts`
30| `1.1.14` | `2.4` | `fencing`
31| `1.1.13` | `2.3` | `constraints`
32| `1.1.12` | `2.0` | `nodes`, `nvset`, `resources`, `tags` + `acls`
33| `1.1.8`+ | `1.2` |
34
35## Schema generation
36
37Each logical portion of the schema goes into its own RNG file, named like
38`${base}-${X}.${Y}.rng`. `${base}` identifies the portion of the schema
39(e.g. constraints, resources); ${X}.${Y} is the latest schema version that
40contained changes in this portion of the schema.
41
42The complete, overall schema, `pacemaker-${X}.${Y}.rng`, is automatically
43generated from the other files via the Makefile.
44
45# Updating schema files #
46
47## Experimental features ##
48
49Experimental features go into `${base}-next.rng` where `${base}` is the
50affected portion of the schema. If such a file does not already exist,
51create it by copying the most recent `${base}-${X}.${Y}.rng`.
52
53Pacemaker will not use the experimental schema by default; the cluster
54administrator must explicitly set the `validate-with` property appropriately to
55use it.
56
57## Stable features ##
58
59The current stable version is determined at runtime when
60crm_schema_init() scans the CRM_DTD_DIRECTORY.
61
62It will have the form `pacemaker-${X}.${Y}` and the highest
63`${X}.${Y}` wins.
64
65### Simple Additions
66
67When the new syntax is a simple addition to the previous one, create a
68new entry, incrementing `${Y}`.
69
70### Feature Removal or otherwise Incompatible Changes
71
72When the new syntax is not a simple addition to the previous one,
73create a new entry, incrementing `${X}` and setting `${Y} = 0`.
74
75An XSLT file is also required that converts an old syntax to the new
76one and must be named `upgrade-${Xold}.${Yold}.xsl`.
77
78See `xml/upgrade-1.3.xsl` for an example.
79
80### General Procedure
81
821. Copy the most recent version of `${base}-*.rng` to `${base}-${X}.${Y}.rng`
831. Commit the copy, e.g. `"Low: xml: clone ${base} schema in preparation for
84 changes"`. This way, the actual change will be obvious in the commit history.
851. Modify `${base}-${X}.${Y}.rng` as required.
861. If required, add an XSLT file, and update `xslt_SCRIPTS` in `xml/Makefile.am`.
871. Commit
881. `make -C xml clean; make -C xml all` to rebuild the schemas in the local
89 source directory.
901. The CIB validity regression tests will break after the schema is updated.
91 Run `tools/regression.sh` to get the new output,
92 `diff tools/regression.validity.{out,exp}` to ensure the changes look correct,
93 `cp tools/regression.validity.{out,exp}` to update the expected output,
94 then commit the change.
95
96## Using a New Schema
97
98New features will not be available until the cluster administrator:
99
1001. Updates all the nodes
1011. Runs the equivalent of `cibadmin --upgrade --force`
102
103## Random Notes
104
105From the source directory, run `make -C xml diff` to see the changes
106in the current schema (compared to the previous ones) and also the
107pending changes in `pacemaker-next`.
108Alternatively, if the intention is to grok the overall historical schema
109evolution, use `make -C xml fulldiff`.
110