ZEP-0048: schema upgrade process#49
Conversation
AustinAbro321
commented
Oct 10, 2025
- One-line PR description: This PR introduces the schema upgrades ZEP
- Issue link: Schema upgrade process #48
Signed-off-by: Austin Abro <austinabro321@gmail.com>
Signed-off-by: Austin Abro <austinabro321@gmail.com>
Signed-off-by: Austin Abro <austinabro321@gmail.com>
Signed-off-by: Austin Abro <austinabro321@gmail.com>
Signed-off-by: Austin Abro <austinabro321@gmail.com>
Signed-off-by: Austin Abro <austinabro321@gmail.com>
Signed-off-by: Austin Abro <austinabro321@gmail.com>
Signed-off-by: Austin Abro <austinabro321@gmail.com>
Signed-off-by: Austin Abro <austinabro321@gmail.com>
Signed-off-by: Austin Abro <austinabro321@gmail.com>
Signed-off-by: Austin Abro <austinabro321@gmail.com>
Signed-off-by: Austin Abro <austinabro321@gmail.com>
Signed-off-by: Austin Abro <austinabro321@gmail.com>
Signed-off-by: Austin Abro <austinabro321@gmail.com>
Signed-off-by: Austin Abro <austinabro321@gmail.com>
Signed-off-by: Austin Abro <austinabro321@gmail.com>
Signed-off-by: Austin Abro <austinabro321@gmail.com>
Signed-off-by: Austin Abro <austinabro321@gmail.com>
Signed-off-by: Austin Abro <austinabro321@gmail.com>
Signed-off-by: Austin Abro <austinabro321@gmail.com>
Signed-off-by: Austin Abro <austinabro321@gmail.com>
Signed-off-by: Austin Abro <austinabro321@gmail.com>
| Once the latest schema is introduced, the built zarf.yaml file will contain the package definition for itself, as well as all older API versions that are still supported. For example, the built zarf.yaml in a v1beta1 package will include the v1beta1 package config and v1alpha1 package config. The built zarf.yaml for a v1alpha1 package will only include the v1alpha1 package. This is done because older API versions will always be able to convert to newer API versions without data loss, but newer API versions may include fields that are not represented in older API versions. | ||
|
|
||
| A new API version may coincide with packages being incompatible with earlier versions of Zarf, but the logic for determining compatibility will be decoupled from the API version. Zarf will introduce a new field `build.VersionRequirements` which will be automatically populated on create, and will error on deploy or remove if the user's version is older than the required version. See [#4256](https://github.com/zarf-dev/zarf/issues/4256) |
There was a problem hiding this comment.
Had to re-read these paragraphs a few times to process, but if I'm following this right is this statement a bit misleading/not the full picture?
as well as all older API versions that are still supported. For example, the built zarf.yaml in a v1beta1 package will include the v1beta1 package config and v1alpha1 package config
This would only be true for compatible API versions right? Not just all supported versions?
There was a problem hiding this comment.
I think other places in the ZEP gave me the right holistic picture, just took a bit to follow. Maybe my confusion was what supported meant and if that was "zarf CLI supports this" or if that was "the specific package supports this" (VersionRequirements).
Signed-off-by: Austin Abro <austinabro321@gmail.com>
brandtkeller
left a comment
There was a problem hiding this comment.
Passing comments but otherwise ready to get this back on target,
Signed-off-by: Austin Abro <austinabro321@gmail.com>
soltysh
left a comment
There was a problem hiding this comment.
The biggest one I believe is the location of apiVersions, but other than that this looks good.
| below is for the real nitty-gritty. | ||
| --> | ||
|
|
||
| During Zarf's lifetime, it will introduce, deprecate, and drop support for ZarfPackageConfig API versions. Once a version is deprecated, users will still be able to perform all package operations such as create, publish, and deploy, but will receive warnings that they should upgrade. Zarf will drop support for an API version one year after it is deprecated. Once an API version is no longer supported, Zarf will error if a user tries to perform common package operations with that API version such as `zarf package create`, `zarf package publish`, or `zarf package deploy`. Even after Zarf drops official support for an API version, Zarf will still work with the commands `zarf package inspect`, `zarf package remove`, and `zarf package pull` for an additional year. These commands will help users understand their unsupported existing packages, which may have already been deployed to cluster, so that they can migrate them. The SDK will follow the same timeline, I.E. one year for `packager.Create`, two years for `packager.Pull`. |
There was a problem hiding this comment.
Once this lands, it should be added to our docs, so that users can easily find the deprecation policy we provide for various APIs.
|
|
||
| Package definitions will be separated by the standard YAML `---`. Currently, Zarf only checks the first yaml object in the zarf.yaml file. To maintain backwards compatibility, API versions will always be placed in ascending order beginning with the v1alpha1 definition. Future versions of Zarf will check the API version of each package definition and select the latest version that it understands. This process will be implemented before any new API versions are released. If Zarf sees a version that it does not understand, Zarf will log to the user that there is a new API version available that the user should consider updating to. | ||
|
|
||
| A new field on all future schemas called `.build.apiVersion` will be introduced to track which apiVersion was used at build time. This field will be used to determine which version of the package definition will be printed to the user during `zarf package inspect definition` and the interactive prompts of `zarf package deploy|remove`. |
There was a problem hiding this comment.
See my other comment about doing top-level apiVersion. The other field you've mentioned being .build.supportedVersions is fine. apiVersion should be top-level.
There was a problem hiding this comment.
There is currently an APIVersion top level field, and in all future schema versions it will be required. I think .build.supportedVersions wouldn't be exactly what I had in mind since I'm looking to track which version the package was created using. Maybe .build.createAPIVersion?
There was a problem hiding this comment.
Updated to .build.originalAPIVersion
There was a problem hiding this comment.
Austin and I talked about it and we've decided for now that we're not going to include this at all. We couldn't find any use-cases to keep this. We can always re-evaluate that need at a later point in time.
Co-authored-by: Maciej Szulik <maciej@defenseunicorns.com> Signed-off-by: Austin Abro <37223396+AustinAbro321@users.noreply.github.com>
Signed-off-by: Austin Abro <austinabro321@gmail.com>
…nto 0048-schema-updates
Signed-off-by: Austin Abro <austinabro321@gmail.com>
Signed-off-by: Austin Abro <austinabro321@gmail.com>
Signed-off-by: Austin Abro <austinabro321@gmail.com>
Signed-off-by: Austin Abro <austinabro321@gmail.com>
Signed-off-by: Austin Abro <austinabro321@gmail.com>
Signed-off-by: Austin Abro <austinabro321@gmail.com>
Signed-off-by: Austin Abro <austinabro321@gmail.com>
Signed-off-by: Austin Abro <austinabro321@gmail.com>