From e5a812082ae033afb1eed82c0f2df3d0f6bdc93f Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Wed, 17 Apr 2024 08:53:20 +0200 Subject: Adding upstream version 2.1.6. Signed-off-by: Daniel Baumann --- xml/README.md | 136 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 136 insertions(+) create mode 100644 xml/README.md (limited to 'xml/README.md') diff --git a/xml/README.md b/xml/README.md new file mode 100644 index 0000000..e32edc2 --- /dev/null +++ b/xml/README.md @@ -0,0 +1,136 @@ +# Schema Reference + +Pacemaker's XML schema has a version of its own, independent of the version of +Pacemaker itself. + +## Versioned Schema Evolution + +A versioned schema offers transparent backward and forward compatibility. + +- It reflects the timeline of schema-backed features (introduction, + changes to the syntax, possibly deprecation) through the versioned + stable schema increments, while keeping schema versions used by default + by older Pacemaker versions untouched. + +- Pacemaker internally uses the latest stable schema version, and relies on + supplemental transformations to promote cluster configurations based on + older, incompatible schema versions into the desired form. + +## Mapping Pacemaker Versions to Schema Versions + +| Pacemaker | Latest Schema | Changed +| --------- | ------------- | ---------------------------------------------- +| `2.1.5` | `3.9` | `alerts`, `constraints`, `nodes`, `nvset`, +| | | `options`, `resources`, `rule` +| `2.1.3` | `3.8` | `acls` +| `2.1.0` | `3.7` | `constraints`, `resources` +| `2.0.5` | `3.5` | `api`, `resources`, `rule` +| `2.0.4` | `3.3` | `tags` +| `2.0.1` | `3.2` | `resources` +| `2.0.0` | `3.1` | `constraints`, `resources` +| `1.1.18` | `2.10` | `resources`, `alerts` +| `1.1.17` | `2.9` | `resources`, `rule` +| `1.1.16` | `2.6` | `constraints` +| `1.1.15` | `2.5` | `alerts` +| `1.1.14` | `2.4` | `fencing` +| `1.1.13` | `2.3` | `constraints` +| `1.1.12` | `2.0` | `nodes`, `nvset`, `resources`, `tags`, `acls` +| `1.1.8` | `1.2` | + +## Schema generation + +Each logical portion of the schema goes into its own RNG file, named like +`${base}-${X}.${Y}.rng`. `${base}` identifies the portion of the schema +(e.g. constraints, resources); ${X}.${Y} is the latest schema version that +contained changes in this portion of the schema. + +The complete, overall schema, `pacemaker-${X}.${Y}.rng`, is automatically +generated from the other files via the Makefile. + +# Updating schema files # + +## New features ## + +The current schema version is determined at runtime when +crm\_schema\_init() scans the CRM\_SCHEMA\_DIRECTORY. + +It will have the form `pacemaker-${X}.${Y}` and the highest +`${X}.${Y}` wins. + +### Simple Additions + +When the new syntax is a simple addition to the previous one, create a +new entry, incrementing `${Y}`. + +### Feature Removal or otherwise Incompatible Changes + +When the new syntax is not a simple addition to the previous one, +create a new entry, incrementing `${X}` and setting `${Y} = 0`. + +An XSLT file is also required that converts an old syntax to the new +one and must be named `upgrade-${Xold}.${Yold}.xsl`. + +See `xml/upgrade-1.3.xsl` for an example. + +Since `xml/upgrade-2.10.xsl`, rather self-descriptive approach is taken, +separating metadata of the replacements and other modifications to +perform from the actual executive parts, which is leveraged, e.g., with +the on-the-fly overview as obtained with `./regression.sh -X test2to3`. +Also this was the first time particular key names of `nvpair`s, +i.e. below the granularity of the schemas so far, received attention, +and consequently, no longer expected names became systemically banned +in the after-upgrade schemas, using `` construct in the +data type specification pertaining the affected XML path. + +The implied complexity also resulted in establishing a new compound, +stepwise transformation, alleviating the procedural burden from the +core upgrade recipe. In particular, `id-ref` based syntactic +simplification granted in the CIB format introduces nonnegligible +internal "noise" because of the extra indirection encumbered with +generally non-bijective character of such a scheme (context-dependent +interpretation). To reduce this strain, a symmetric arrangement is +introduced as a pair of _enter_/_leave_ (pre-upgrade/post-upgrade) +transformations where the latter is meant to eventually reversibly +restore what the former intentionally simplified (normalized) for +upgrade transformation's peruse. It's optional (even the post-upgrade +counterpart is optional alone) and depends on whether the suitable +files are found along the upgrade transformation itself: e.g., for +`upgrade-2.10.xsl`, such files are `upgrade-2.10-enter.xsl` and +`upgrade-2.10-leave.xsl`. Note that unfolding + refolding `id-ref` +shortcuts is just a practically imposed individual case of how to +reversibly make the configuration space tractable in the upgrade +itself, allowing for more sophistication down the road. + +### General Procedure + +1. Copy the most recent version of `${base}-*.rng` to `${base}-${X}.${Y}.rng`, + such that the new file name increments the highest number of any schema file, + not just the file being edited. +2. Commit the copy, e.g. `"Low: xml: clone ${base} schema in preparation for + changes"`. This way, the actual change will be obvious in the commit history. +3. Modify `${base}-${X}.${Y}.rng` as required. +4. If required, add an XSLT file, and update `xslt\_SCRIPTS` in `xml/Makefile.am`. +5. Commit. +6. Run `make -C xml clean; make -C xml` to rebuild the schemas in the local +6. Run `make -C xml clean; make -C xml` to rebuild the schemas in the local + source directory. +7. The CIB validity and upgrade regression tests will break after the schema is + updated. Run `cts/cts-cli -s` to make the expected outputs reflect the + changes made so far, and run `git diff` to ensure that these changes look + sane. Finally, commit the changes. +8. Similarly, with the new major version `${X}`, it's advisable to refresh + scheduler tests at some point. See the instructions in `cts/README.md`. + +## Using a New Schema + +New features will not be available until the cluster administrator: + +1. Updates all the nodes +2. Runs the equivalent of `cibadmin --upgrade --force` + +## Random Notes + +From the source directory, run `make -C xml diff` to see the changes +in the current schema (compared to the previous ones). +Alternatively, if the intention is to grok the overall historical schema +evolution, use `make -C xml fulldiff`. -- cgit v1.2.3