Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 28 additions & 11 deletions COMPATIBILITY.md
Original file line number Diff line number Diff line change
@@ -1,15 +1,32 @@
# Compatibility Contract

The migration preserves established `io.cattle.*` Java packages, Maven coordinates, database schemas and migration IDs, setting keys, API resource and field names, event names, Docker labels, generated client types, and internal service identifiers. These values are persisted or consumed across repositories and are not product branding.

# Compatibility Contract
The migration preserves established `io.cattle.*` Java packages, Maven coordinates, database schemas and migration IDs, setting keys, API resource and field names, event names, Docker labels, generated client types, and internal service identifiers. These values are persisted or consumed across repositories and are not product branding.
New operator-facing names use PastureStack and `PASTURESTACK_*`. Compatibility identifiers must be changed only with an explicit data migration, a dual-read or dual-write transition, a rollback plan, and cross-repository verification.

The `rancher.compose.*` setting keys and inherited executable aliases remain compatibility contracts for existing launchers. Public artifact URLs and container images are hosted under the PastureStack GitHub organization; remove an alias only after its launcher and rollback fixtures accept the replacement name.

## Host API token rollout

The Engine is the issuer for Host API access tokens. Docker socket access carries the exact `scope=dockersocket` claim. Host statistics carry a single formatted `resourceId`; container statistics carry only the Docker identifiers and formatted resource IDs that the caller is allowed to observe. Empty or broader compatibility tokens are not valid.
## Docker host policy

Deploy the issuing Engine first, allow tokens issued by the previous Engine to expire, and only then deploy a Host API version that enforces these claims. Rollback follows the reverse compatibility boundary: retain the strict issuer while rolling Host API back, and do not reintroduce empty claims.
The unreleased candidate adds Docker Engine `29.8.0` as an exact supported
version alongside the preserved legacy ranges, `24.0.9`, and the existing
`29.4.1` through `29.7.2` interval. It does not widen the interval to admit
untested patch versions. `newest.docker.version` is `v29.8.0` so the host UI
classifies versions above it as untested rather than misreporting them as
supported.

Before release, validate clean installation, upgrade from a preserved database, rollback, API and UI behavior, subscriptions, agent events, scheduler, networking, storage, secrets, authentication, catalog, backup and restore, and both supported database engines in isolated VMs.
Host Docker version classification and host firewall backend selection are
different contracts. Ubuntu version does not determine whether an operator
uses `iptables-legacy`, `iptables-nft`, or Docker's native nftables backend.
Network components must detect the host's actual active backend before
installing only their owned rules, without switching the host default or
modifying another backend. Each of those modes needs runtime acceptance on
the relevant host before this candidate is published as fully supported.

The `rancher.compose.*` setting keys and inherited executable aliases remain compatibility contracts for existing launchers. Public artifact URLs and container images are hosted under the PastureStack GitHub organization; remove an alias only after its launcher and rollback fixtures accept the replacement name.

## Host API token rollout

The Engine is the issuer for Host API access tokens. Docker socket access carries the exact `scope=dockersocket` claim. Host statistics carry a single formatted `resourceId`; container statistics carry only the Docker identifiers and formatted resource IDs that the caller is allowed to observe. Empty or broader compatibility tokens are not valid.

Deploy the issuing Engine first, allow tokens issued by the previous Engine to expire, and only then deploy a Host API version that enforces these claims. Rollback follows the reverse compatibility boundary: retain the strict issuer while rolling Host API back, and do not reintroduce empty claims.

Before release, validate clean installation, upgrade from a preserved database, rollback, API and UI behavior, subscriptions, agent events, scheduler, networking, storage, secrets, authentication, catalog, backup and restore, and both supported database engines in isolated VMs.
11 changes: 6 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,9 +8,10 @@ PastureStack is an independent community effort to preserve, audit, and moderniz

## Project status

This source tree and its current public GitHub Release
The current public GitHub Release
[`v0.183.298`](https://github.com/PastureStack/orchestration-engine/releases/tag/v0.183.298)
produce engine version `0.183.298`. It retains the existing Java 25, Ubuntu
produces engine version `0.183.298`. This branch prepares an unreleased
`0.183.299` Docker host policy candidate. It retains the existing Java 25, Ubuntu
26.04, Maven, Liquibase, MariaDB/MySQL, WebSocket, dependency, concurrency, and
runtime-hardening work from the maintained compatibility line. Release builds
consume the exact `5.7.4` runtime JAR published by
Expand Down Expand Up @@ -44,9 +45,9 @@ dependency line. The existing platform JSON surface remains on
`com.fasterxml.jackson` 2.22. Packaging gates admit only the reviewed,
version-pinned pair and verify that their class namespaces are disjoint.

Host compatibility is evidence-based. The default policy recognizes the preserved legacy ranges, Docker Engine `24.0.9`, and every stable Docker 29 release from `29.4.1` through `29.7.2` inclusive. The bounded Docker 29 interval includes `29.6.2`; Docker 25 through 28 and versions outside that interval remain unsupported.
Host compatibility is evidence-based. The candidate default policy preserves the legacy ranges and Docker Engine `24.0.9`, retains the bounded `29.4.1` through `29.7.2` interval, and adds exactly `29.8.0`. It does not admit unverified `29.7.3` or `29.8.1`, or Docker 25 through 28. The frontend marks versions above the configured newest version as *untested*, not *supported*. The `29.8.0` policy still requires the separate Ubuntu 26.04 host and firewall-backend runtime acceptance gate before release.

The build and Dapper images compile the Docker `29.7.2` CLI from the pinned official tag commit with Go `1.27.0`; they do not import Docker's precompiled Go `1.26.5` binary. The source archive SHA-256 and Go builder image digest are enforced by the source gate and the resulting images are scanned before release.
The build and Dapper images still compile the Docker `29.7.2` CLI from the pinned official tag commit with Go `1.27.0`; the CLI tool version is separate from the Docker daemon host support setting. They do not import Docker's precompiled Go `1.26.5` binary. The source archive SHA-256 and Go builder image digest are enforced by the source gate and the resulting images are scanned before release.

Container and service port changes expose a read-only `portpreflight` project action. The action evaluates persisted workload ownership, eligible-host capacity, requested scheduling constraints, rolling-upgrade overlap, and live Node Agent socket observations before a change is saved. Primary and sidekick bindings retain their own network modes while sharing one physical-host collision check. Managed-network published ports are unique across the environment even when a workload targets one host; bridge and host-network checks remain scoped to an explicitly requested host, and host networking checks the effective container port rather than a misleading published-port remap. Running owners block the applicable scope, stopped owners remain visible as warnings, and incomplete live inspection is reported as unknown rather than available. During a start-first upgrade, unchanged bindings reserve their current hosts without being reported as self-conflicts; changed bindings are checked as new requests, and runtime probes ignore only the exact containers already represented by those persisted reservations. The allocator and final create/upgrade validation repeat the authoritative check so the browser result is never the only enforcement boundary. Project authorization explicitly exposes the action's nested input and read-only result schemas; regression tests load the shipped authorization overlays and verify the network-scope, upgrade-capacity, self-ownership, and runtime-probe contracts.

Expand Down Expand Up @@ -92,7 +93,7 @@ The gate performs dependency-hygiene checks, builds every Maven module with JDK
To create the complete release archive after the gate passes:

```sh
ENGINE_VERSION=0.183.298 bash scripts/build --release
ENGINE_VERSION=0.183.299 bash scripts/build --release
bash scripts/check-release-artifact dist/artifacts/cattle.jar
```

Expand Down
2 changes: 1 addition & 1 deletion code/framework/api-pub-sub-jetty/pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
<parent>
<groupId>io.cattle</groupId>
<artifactId>cattle-parent</artifactId>
<version>0.183.298</version>
<version>0.183.299</version>
<relativePath>../../parent/pom.xml</relativePath>
</parent>
<dependencies>
Expand Down
2 changes: 1 addition & 1 deletion code/framework/api-pub-sub/pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
<parent>
<groupId>io.cattle</groupId>
<artifactId>cattle-parent</artifactId>
<version>0.183.298</version>
<version>0.183.299</version>
<relativePath>../../parent/pom.xml</relativePath>
</parent>
<dependencies>
Expand Down
2 changes: 1 addition & 1 deletion code/framework/api/pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
<parent>
<artifactId>cattle-parent</artifactId>
<groupId>io.cattle</groupId>
<version>0.183.298</version>
<version>0.183.299</version>
<relativePath>../../parent/pom.xml</relativePath>
</parent>
<dependencies>
Expand Down
2 changes: 1 addition & 1 deletion code/framework/archaius/pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
<parent>
<groupId>io.cattle</groupId>
<artifactId>cattle-meta-parent</artifactId>
<version>0.183.298</version>
<version>0.183.299</version>
<relativePath>../../meta-parent/pom.xml</relativePath>
</parent>
</project>
2 changes: 1 addition & 1 deletion code/framework/async/pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
<parent>
<groupId>io.cattle</groupId>
<artifactId>cattle-parent</artifactId>
<version>0.183.298</version>
<version>0.183.299</version>
<relativePath>../../parent/pom.xml</relativePath>
</parent>
<dependencies>
Expand Down
2 changes: 1 addition & 1 deletion code/framework/auditing/pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
<parent>
<artifactId>cattle-parent</artifactId>
<groupId>io.cattle</groupId>
<version>0.183.298</version>
<version>0.183.299</version>
<relativePath>../../parent/pom.xml</relativePath>
</parent>

Expand Down
2 changes: 1 addition & 1 deletion code/framework/db-loader/pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
<parent>
<groupId>io.cattle</groupId>
<artifactId>cattle-parent</artifactId>
<version>0.183.298</version>
<version>0.183.299</version>
<relativePath>../../parent/pom.xml</relativePath>
</parent>
<dependencies>
Expand Down
2 changes: 1 addition & 1 deletion code/framework/deferred/pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
<parent>
<groupId>io.cattle</groupId>
<artifactId>cattle-parent</artifactId>
<version>0.183.298</version>
<version>0.183.299</version>
<relativePath>../../parent/pom.xml</relativePath>
</parent>
<dependencies>
Expand Down
2 changes: 1 addition & 1 deletion code/framework/encryption/pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
<parent>
<groupId>io.cattle</groupId>
<artifactId>cattle-parent</artifactId>
<version>0.183.298</version>
<version>0.183.299</version>
<relativePath>../../parent/pom.xml</relativePath>
</parent>
<dependencies>
Expand Down
2 changes: 1 addition & 1 deletion code/framework/engine/pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
<parent>
<groupId>io.cattle</groupId>
<artifactId>cattle-parent</artifactId>
<version>0.183.298</version>
<version>0.183.299</version>
<relativePath>../../parent/pom.xml</relativePath>
</parent>
<dependencies>
Expand Down
2 changes: 1 addition & 1 deletion code/framework/eventing/pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
<parent>
<groupId>io.cattle</groupId>
<artifactId>cattle-parent</artifactId>
<version>0.183.298</version>
<version>0.183.299</version>
<relativePath>../../parent/pom.xml</relativePath>
</parent>
<dependencies>
Expand Down
2 changes: 1 addition & 1 deletion code/framework/events/pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
<parent>
<groupId>io.cattle</groupId>
<artifactId>cattle-parent</artifactId>
<version>0.183.298</version>
<version>0.183.299</version>
<relativePath>../../parent/pom.xml</relativePath>
</parent>
<dependencies>
Expand Down
2 changes: 1 addition & 1 deletion code/framework/extension-spring/pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
<parent>
<artifactId>cattle-parent</artifactId>
<groupId>io.cattle</groupId>
<version>0.183.298</version>
<version>0.183.299</version>
<relativePath>../../parent/pom.xml</relativePath>
</parent>
<dependencies>
Expand Down
2 changes: 1 addition & 1 deletion code/framework/extension/pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
<parent>
<artifactId>cattle-parent</artifactId>
<groupId>io.cattle</groupId>
<version>0.183.298</version>
<version>0.183.299</version>
<relativePath>../../parent/pom.xml</relativePath>
</parent>
<dependencies>
Expand Down
2 changes: 1 addition & 1 deletion code/framework/java-server/pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
<parent>
<groupId>io.cattle</groupId>
<artifactId>cattle-parent</artifactId>
<version>0.183.298</version>
<version>0.183.299</version>
<relativePath>../../parent/pom.xml</relativePath>
</parent>
<dependencies>
Expand Down
2 changes: 1 addition & 1 deletion code/framework/jmx/pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
<parent>
<groupId>io.cattle</groupId>
<artifactId>cattle-parent</artifactId>
<version>0.183.298</version>
<version>0.183.299</version>
<relativePath>../../parent/pom.xml</relativePath>
</parent>
<dependencies>
Expand Down
2 changes: 1 addition & 1 deletion code/framework/jooq/pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
<parent>
<groupId>io.cattle</groupId>
<artifactId>cattle-parent</artifactId>
<version>0.183.298</version>
<version>0.183.299</version>
<relativePath>../../parent/pom.xml</relativePath>
</parent>
<dependencies>
Expand Down
2 changes: 1 addition & 1 deletion code/framework/json/pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
<parent>
<groupId>io.cattle</groupId>
<artifactId>cattle-parent</artifactId>
<version>0.183.298</version>
<version>0.183.299</version>
<relativePath>../../parent/pom.xml</relativePath>
</parent>
<dependencies>
Expand Down
2 changes: 1 addition & 1 deletion code/framework/launcher/pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
<parent>
<groupId>io.cattle</groupId>
<artifactId>cattle-parent</artifactId>
<version>0.183.298</version>
<version>0.183.299</version>
<relativePath>../../parent/pom.xml</relativePath>
</parent>
<dependencies>
Expand Down
2 changes: 1 addition & 1 deletion code/framework/lock/pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
<parent>
<groupId>io.cattle</groupId>
<artifactId>cattle-parent</artifactId>
<version>0.183.298</version>
<version>0.183.299</version>
<relativePath>../../parent/pom.xml</relativePath>
</parent>
<dependencies>
Expand Down
2 changes: 1 addition & 1 deletion code/framework/logback/pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
<parent>
<groupId>io.cattle</groupId>
<artifactId>cattle-meta-parent</artifactId>
<version>0.183.298</version>
<version>0.183.299</version>
<relativePath>../../meta-parent/pom.xml</relativePath>
</parent>
<dependencies>
Expand Down
2 changes: 1 addition & 1 deletion code/framework/managed-context/pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
<parent>
<groupId>io.cattle</groupId>
<artifactId>cattle-parent</artifactId>
<version>0.183.298</version>
<version>0.183.299</version>
<relativePath>../../parent/pom.xml</relativePath>
</parent>
<dependencies>
Expand Down
2 changes: 1 addition & 1 deletion code/framework/metrics/pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
<parent>
<groupId>io.cattle</groupId>
<artifactId>cattle-parent</artifactId>
<version>0.183.298</version>
<version>0.183.299</version>
<relativePath>../../parent/pom.xml</relativePath>
</parent>
<dependencies>
Expand Down
2 changes: 1 addition & 1 deletion code/framework/module/pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
<parent>
<groupId>io.cattle</groupId>
<artifactId>cattle-parent</artifactId>
<version>0.183.298</version>
<version>0.183.299</version>
<relativePath>../../parent/pom.xml</relativePath>
</parent>
<dependencies>
Expand Down
2 changes: 1 addition & 1 deletion code/framework/object/pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
<parent>
<groupId>io.cattle</groupId>
<artifactId>cattle-parent</artifactId>
<version>0.183.298</version>
<version>0.183.299</version>
<relativePath>../../parent/pom.xml</relativePath>
</parent>
<dependencies>
Expand Down
2 changes: 1 addition & 1 deletion code/framework/pool/pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
<parent>
<groupId>io.cattle</groupId>
<artifactId>cattle-parent</artifactId>
<version>0.183.298</version>
<version>0.183.299</version>
<relativePath>../../parent/pom.xml</relativePath>
</parent>
<dependencies>
Expand Down
2 changes: 1 addition & 1 deletion code/framework/resource-monitor/pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
<parent>
<artifactId>cattle-parent</artifactId>
<groupId>io.cattle</groupId>
<version>0.183.298</version>
<version>0.183.299</version>
<relativePath>../../parent/pom.xml</relativePath>
</parent>
<dependencies>
Expand Down
2 changes: 1 addition & 1 deletion code/framework/schema/pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
<parent>
<artifactId>cattle-parent</artifactId>
<groupId>io.cattle</groupId>
<version>0.183.298</version>
<version>0.183.299</version>
<relativePath>../../parent/pom.xml</relativePath>
</parent>
<dependencies>
Expand Down
2 changes: 1 addition & 1 deletion code/framework/server/pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
<parent>
<artifactId>cattle-meta-parent</artifactId>
<groupId>io.cattle</groupId>
<version>0.183.298</version>
<version>0.183.299</version>
<relativePath>../../meta-parent/pom.xml</relativePath>
</parent>
<dependencies>
Expand Down
2 changes: 1 addition & 1 deletion code/framework/spring/pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
<parent>
<groupId>io.cattle</groupId>
<artifactId>cattle-parent</artifactId>
<version>0.183.298</version>
<version>0.183.299</version>
<relativePath>../../parent/pom.xml</relativePath>
</parent>
<dependencies>
Expand Down
2 changes: 1 addition & 1 deletion code/framework/system-task/pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
<parent>
<groupId>io.cattle</groupId>
<artifactId>cattle-parent</artifactId>
<version>0.183.298</version>
<version>0.183.299</version>
<relativePath>../../parent/pom.xml</relativePath>
</parent>
<dependencies>
Expand Down
2 changes: 1 addition & 1 deletion code/framework/token/pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
<parent>
<groupId>io.cattle</groupId>
<artifactId>cattle-parent</artifactId>
<version>0.183.298</version>
<version>0.183.299</version>
<relativePath>../../parent/pom.xml</relativePath>
</parent>
<dependencies>
Expand Down
2 changes: 1 addition & 1 deletion code/framework/utils/pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
<parent>
<groupId>io.cattle</groupId>
<artifactId>cattle-parent</artifactId>
<version>0.183.298</version>
<version>0.183.299</version>
<relativePath>../../parent/pom.xml</relativePath>
</parent>
<dependencies>
Expand Down
2 changes: 1 addition & 1 deletion code/iaas/agent-instance/pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
<parent>
<artifactId>cattle-parent</artifactId>
<groupId>io.cattle</groupId>
<version>0.183.298</version>
<version>0.183.299</version>
<relativePath>../../parent/pom.xml</relativePath>
</parent>
<dependencies>
Expand Down
2 changes: 1 addition & 1 deletion code/iaas/agent-server/pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
<parent>
<groupId>io.cattle</groupId>
<artifactId>cattle-parent</artifactId>
<version>0.183.298</version>
<version>0.183.299</version>
<relativePath>../../parent/pom.xml</relativePath>
</parent>
<dependencies>
Expand Down
Loading
Loading