From 555e755d9c2bd927000313e6f324c5cf12fe4de0 Mon Sep 17 00:00:00 2001 From: Austin Abro Date: Mon, 20 Oct 2025 08:11:51 -0400 Subject: [PATCH 01/30] v1beta1 start Signed-off-by: Austin Abro --- 0051-v1beta1-schema/README.md | 282 ++++++++++++++++++++++++++++++++++ 0051-v1beta1-schema/zep.yaml | 34 ++++ 2 files changed, 316 insertions(+) create mode 100644 0051-v1beta1-schema/README.md create mode 100644 0051-v1beta1-schema/zep.yaml diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md new file mode 100644 index 0000000..7074e9f --- /dev/null +++ b/0051-v1beta1-schema/README.md @@ -0,0 +1,282 @@ + + +# ZEP-NNNN: Your short, descriptive title + + + + + + +- [Summary](#summary) +- [Motivation](#motivation) + - [Goals](#goals) + - [Non-Goals](#non-goals) +- [Proposal](#proposal) + - [User Stories (Optional)](#user-stories-optional) + - [Story 1](#story-1) + - [Story 2](#story-2) + - [Risks and Mitigations](#risks-and-mitigations) +- [Design Details](#design-details) + - [Test Plan](#test-plan) + - [Prerequisite testing updates](#prerequisite-testing-updates) + - [Unit tests](#unit-tests) + - [e2e tests](#e2e-tests) + - [Graduation Criteria](#graduation-criteria) + - [Upgrade / Downgrade Strategy](#upgrade--downgrade-strategy) + - [Version Skew Strategy](#version-skew-strategy) +- [Implementation History](#implementation-history) +- [Drawbacks](#drawbacks) +- [Alternatives](#alternatives) +- [Infrastructure Needed (Optional)](#infrastructure-needed-optional) + + +## Summary + + + +There are several fields in the ZarfPackageConfig v1alpha1 that can be restructured or removed to provide a better experience to creators of Zarf packages. + +## Motivation + + + +### Goals + + + +- Detail all schema changes in the ZarfPackageConfig from v1alpha1 to v1beta1. + +### Non-Goals + + + +- Discuss upgrade / downgrade strategy for users and packages. This is detailed in 0048-schema-upgrade-process + +## Proposal + + + + + +### User Stories (Optional) + + + +#### Story 1 + +#### Story 2 + +### Risks and Mitigations + + + +## Design Details + + + +### Test Plan + + + +[ ] I/we understand the owners of the involved components may require updates to +existing tests to make this code solid enough prior to committing the changes necessary +to implement this proposal. + +### Graduation Criteria + + + +### Upgrade / Downgrade Strategy + + + +### Version Skew Strategy + + + +## Implementation History + + + +## Drawbacks + + + +## Alternatives + + + +## Infrastructure Needed (Optional) + + diff --git a/0051-v1beta1-schema/zep.yaml b/0051-v1beta1-schema/zep.yaml new file mode 100644 index 0000000..d982c61 --- /dev/null +++ b/0051-v1beta1-schema/zep.yaml @@ -0,0 +1,34 @@ +schema-version: 1.0.0 + +title: ZEP Template +zep-number: NNNN +authors: + - "@jane.doe" +status: provisional|implementable|implemented|deferred|rejected|withdrawn|replaced +creation-date: yyyy-mm-dd +reviewers: + - TBD + - "@alice.doe" +approvers: + - TBD + - "@oscar.doe" + +see-also: + - "/1234-we-heard-you-like-zeps" + - "/5678-everyone-gets-a-zep" +replaces: + - "/3456-replaced-zep" + +# The target maturity stage in the current dev cycle for this ZEP. +stage: alpha|beta|stable + +# The most recent milestone for which work toward delivery of this ZEP has been +# done. This can be the current (upcoming) milestone, if it is being actively +# worked on. +latest-milestone: "v0.39" + +# The milestone at which this feature was, or is targeted to be, at each stage. +milestone: + alpha: "v0.39" + beta: "v0.40" + stable: "v1.0" From 64b60245ae70e336585c8a57bc5aab447c141894 Mon Sep 17 00:00:00 2001 From: Austin Abro Date: Mon, 20 Oct 2025 10:08:18 -0400 Subject: [PATCH 02/30] WIP Signed-off-by: Austin Abro --- 0051-v1beta1-schema/README.md | 82 +++++++++++++++++++++++++++-------- 1 file changed, 63 insertions(+), 19 deletions(-) diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md index 7074e9f..43a9c60 100644 --- a/0051-v1beta1-schema/README.md +++ b/0051-v1beta1-schema/README.md @@ -45,12 +45,7 @@ The latest instructions for this template can be found in [this repo](/NNNN-zep- longer appropriate, updates to the list must be approved by the remaining approvers. --> -# ZEP-NNNN: Your short, descriptive title - - +# ZEP-0051: v1beta1 schema ## Summary @@ -98,7 +92,7 @@ feedback and reduce unnecessary changes. [documentation style guide]: https://docs.zarf.dev/contribute/style-guide/ --> -There are several fields in the ZarfPackageConfig v1alpha1 that can be restructured or removed to provide a better experience to creators of Zarf packages. +Several fields in the ZarfPackageConfig v1alpha1 can be restructured to provide a more intuitive experience. Some field in the v1alpha1 schema have a poor user experience and add overhead to Zarf, these will be removed. A new schema version, v1beta1, provides Zarf the space to make these changes. ## Motivation @@ -120,7 +114,7 @@ List the specific goals of the ZEP. What is it trying to achieve? How will we know that this has succeeded? --> -- Detail all schema changes in the ZarfPackageConfig from v1alpha1 to v1beta1. +- Detail the schema changes in the ZarfPackageConfig from v1alpha1 to v1beta1. ### Non-Goals @@ -129,7 +123,7 @@ What is out of scope for this ZEP? Listing non-goals helps to focus discussion and make progress. --> -- Discuss upgrade / downgrade strategy for users and packages. This is detailed in 0048-schema-upgrade-process +- Discuss how the codebase will change to handle a new schema version. This is detailed in 0048-schema-upgrade-process ## Proposal @@ -141,7 +135,48 @@ desired outcome and how success will be measured. The "Design Details" section below is for the real nitty-gritty. --> +The v1beta1 schema will remove or rename several fields. + +- `.metadata.aggregateChecksum` will move to `.build.aggregateChecksum` +- `.metadata` fields `image`, `source`, `documentation`, `url`, `authors`, `vendors` -> will be removed. `zarf dev convert` will automatically add them as fields under `.metadata.annotations`. +- `.components[x].required` will be renamed to `.components[x].optional`. `optional` will default to false, this is a change in behavior since required defaults to false. +- `.components.[x].group` will be removed. Users are recommend to use `components[x].only.flavor` instead. +- `setVariable` will be removed. It can be automatically migrated to the existing field `setVariables`. +- `scripts` will be removed. It can be automatically migrated to the existing field `actions`. +- `noWait` will be renamed to `wait`. `wait` will default to true. This change will happen on both `.components.[x].manifests` and `components.[x].charts` +- `yolo` will be renamed to `airgap`. `airgap` will default to true +- `.components.[x].actions.[default/onAny].maxRetries` -> `.components.[x].actions.[default/onAny].retries` +- `.components.[x].actions.[default/onAny].maxTotalSeconds` -> `.components.[x].actions.[default/onAny].timeout`, which must be in a [Go recognized duration string format](https://pkg.go.dev/time#ParseDuration) +- `.component.[x].charts` will break off fields into different sub-objects depending on the method of consuming the chart. See [#2245](https://github.com/defenseunicorns/zarf/issues/2245). Exactly one of `helm`, `git`, `oci`, or `local` must exist for each `components.[x].charts`, and their objects look like below. The fields `localPath`, `gitPath`, `version`, `URL`, and `repoName` will all be removed from the top level of `components.[x].charts`. +```yaml +- name: podinfo-repo-new + helm: + url: https://stefanprodan.github.io/podinfo + name: podinfo # replaces repoName since it's only applicable for helm chart repositories + version: 6.4.0 + +- name: podinfo-git-new + git: + url: https://stefanprodan.github.io/podinfo@6.4.0 + path: charts/podinfo + # no version field, Zarf will use the version in the chart.yaml at that git tag + +- name: podinfo-oci-new + oci: + url: oci://ghcr.io/stefanprodan/charts/podinfo + version: 6.4.0 + +- name: podinfo-local-same + local: + path: chart + # no version field, use local chart.yaml version +``` +- `.components.[x].healthChecks` will be removed in favor of changing the behavior of `.components.[x].actions.[onAny].wait.cluster` to use Kstatus when the `.wait.cluster.condition` is empty. `.wait.cluster` currently shells out to `kubectl wait`. Kstatus checks are generally preferred as the user doesn't need to set a condition, instead Kstatus has inherent knowledge of how to check the readiness of a resource. The advantages of `.wait.cluster` are that specific conditions can be set. This can be useful when readiness is not the desired state, or for certain CRDs that do not implement the fields for Kstatus readiness checks. The original behavior of `.wait.cluster` will be used when `.wait.cluster.condition` is set. + - Since Kstatus requires the API version, `apiVersion` will be added as a field to `.wait.cluster`. +- `.components.[x].dataInjections` will be removed from the v1beta1 schema without replacement. See [#3926](https://github.com/zarf-dev/zarf/issues/3926). +- `.components.[x].charts.variables` will be removed. This is an alpha feature that is replaced by Zarf values. +In order for this schema to be applied, users must set `.apiVersion` to `v1beta1`. If the apiVersion is not set then Zarf will assume the v1alpha1 schema. ### User Stories (Optional) @@ -168,6 +203,10 @@ How will security be reviewed, and by whom? How will UX be reviewed, and by whom? --> +The fields `.components.[x].dataInjections` will be removed without a direct replacement in the schema. There must be documentation to present to users so they know what alternatives they can use achieve a similar result. + +The alpha field `.components.[x].charts.variables` has seen significant adoption. There should be documentation on how users can utilize Zarf values as an alternative to chart variables. + ## Design Details -[ ] I/we understand the owners of the involved components may require updates to +[X] I/we understand the owners of the involved components may require updates to existing tests to make this code solid enough prior to committing the changes necessary to implement this proposal. +There will be e2e tests for `zarf dev convert` from a v1alpha1 definition to a v1beta1 definition. + +There will be e2e tests for creating, deploying, and publishing a v1beta1 package. As the schema nears towards GA, the current v1alpha1 + ### Graduation Criteria +- Alpha: fields are subject to change or rename. No backwards compatibility guarantees. +- Beta: Fields will not change in a way that is not fully backwards compatible. +- GA: We've received feedback that all of are changes are an improvement. Examples and tests in Zarf shift to using the v1beta1 schema. + +Deprecation: +- This schema will likely be deprecated one day in the future in favor of a v1 schema. It will not be deprecated until the next schema version is at least generally available. Once deprecated, Zarf will still support the v1beta1 schema for at least a year. + ### Upgrade / Downgrade Strategy + + ### Version Skew Strategy - -## Infrastructure Needed (Optional) - - From 1ae1fc307b2169e9a4c01a4365366dca1f089039 Mon Sep 17 00:00:00 2001 From: Austin Abro Date: Mon, 20 Oct 2025 10:17:16 -0400 Subject: [PATCH 03/30] add user story Signed-off-by: Austin Abro --- 0051-v1beta1-schema/README.md | 95 ++++++++++++++++++++++++++++++++++- 1 file changed, 94 insertions(+), 1 deletion(-) diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md index 43a9c60..9ae6bd9 100644 --- a/0051-v1beta1-schema/README.md +++ b/0051-v1beta1-schema/README.md @@ -176,7 +176,7 @@ The v1beta1 schema will remove or rename several fields. - `.components.[x].dataInjections` will be removed from the v1beta1 schema without replacement. See [#3926](https://github.com/zarf-dev/zarf/issues/3926). - `.components.[x].charts.variables` will be removed. This is an alpha feature that is replaced by Zarf values. -In order for this schema to be applied, users must set `.apiVersion` to `v1beta1`. If the apiVersion is not set then Zarf will assume the v1alpha1 schema. +In order for this schema to be applied, users must set `.apiVersion` to `v1beta1`. If the apiVersion is not set then Zarf will assume the v1alpha1 schema. Users will be able to automatically upgrade their package to the v1beta1 schema by running `zarf dev convert`. ### User Stories (Optional) @@ -189,8 +189,101 @@ bogged down. #### Story 1 +As a user of Helm charts in my package, I have the following existing `zarf.yaml`: + +```yaml +kind: ZarfPackageConfig +metadata: + name: helm-charts +components: + - name: demo-helm-charts + required: true + charts: + - name: podinfo-local + version: 6.4.0 + namespace: podinfo-from-local-chart + localPath: chart + valuesFiles: + - values.yaml + + - name: podinfo-oci + version: 6.4.0 + namespace: podinfo-from-oci + url: oci://ghcr.io/stefanprodan/charts/podinfo + valuesFiles: + - values.yaml + + - name: podinfo-git + version: 6.4.0 + namespace: podinfo-from-git + url: https://github.com/stefanprodan/podinfo.git + gitPath: charts/podinfo + valuesFiles: + - values.yaml + + - name: podinfo-repo + version: 6.4.0 + namespace: podinfo-from-repo + url: https://stefanprodan.github.io/podinfo + repoName: podinfo + releaseName: cool-release-name + valuesFiles: + - values.yaml +``` + +I want to upgrade to the v1beta1 schema so I run `zarf dev convert`, which produces: + +```yaml +apiVersion: v1beta1 +kind: ZarfPackageConfig +metadata: + name: helm-charts + description: Example showcasing multiple ways to deploy helm charts + version: 0.0.1 + +components: + - name: demo-helm-charts + optional: false # Changed from `required: true` + charts: + - name: podinfo-local + namespace: podinfo-from-local-chart + local: + path: chart # Changed from `localPath` + # version field removed - uses version from local chart.yaml + valuesFiles: + - values.yaml + - name: podinfo-oci + namespace: podinfo-from-oci + oci: + url: oci://ghcr.io/stefanprodan/charts/podinfo + version: 6.4.0 + valuesFiles: + - values.yaml + + - name: podinfo-git + namespace: podinfo-from-git + git: + url: https://github.com/stefanprodan/podinfo.git@6.4.0 + path: charts/podinfo # Changed from `gitPath` + # version field removed - uses version from chart.yaml at git tag + valuesFiles: + - values.yaml + + - name: podinfo-repo + namespace: podinfo-from-repo + helm: + url: https://stefanprodan.github.io/podinfo + name: podinfo # Changed from `repoName` + version: 6.4.0 + releaseName: cool-release-name + valuesFiles: + - values.yaml +``` + #### Story 2 + + ### Risks and Mitigations +There are several open issues requesting enhancements to the schema. The general theme of these changes is to make the ZarfPackageConfig schema more intuitive to use. +- [Refactor charts definition in zarf.yaml #2245](https://github.com/zarf-dev/zarf/issues/2245) +- [Breaking Change: make components required by default #2059](https://github.com/zarf-dev/zarf/issues/2059) +- [Use kstatus as the engine behind zarf tools wait-for and .wait.cluster #4077](https://github.com/zarf-dev/zarf/issues/4077) + +Additionally, users often struggle to use data injections. Usually, they would be be better served by using a Kubernetes native solution [#3926](https://github.com/zarf-dev/zarf/issues/3926). + ### Goals -- Discuss how the codebase will change to handle a new schema version. This is detailed in 0048-schema-upgrade-process +- Discuss how the Zarf codebase will shift to handle multiple API versions. This is detailed in [0048-schema-upgrade-process](https://github.com/zarf-dev/proposals/pull/49) ## Proposal From 38fd5ded3d99005380d805bb0c131cfa256e4bd7 Mon Sep 17 00:00:00 2001 From: Austin Abro Date: Mon, 20 Oct 2025 11:28:45 -0400 Subject: [PATCH 06/30] fixes Signed-off-by: Austin Abro --- 0051-v1beta1-schema/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md index 861ebcd..73629e2 100644 --- a/0051-v1beta1-schema/README.md +++ b/0051-v1beta1-schema/README.md @@ -149,9 +149,9 @@ The v1beta1 schema will remove or rename several fields. - `.components[x].required` will be renamed to `.components[x].optional`. `optional` will default to false, this is a change in behavior since required defaults to false. - `.components.[x].group` will be removed. Users are recommend to use `components[x].only.flavor` instead. - `setVariable` will be removed. It can be automatically migrated to the existing field `setVariables`. -- `scripts` will be removed. It can be automatically migrated to the existing field `actions`. +- `.components.[x].scripts` will be removed. It can be automatically migrated to the existing field `.components.[x].actions`. - `noWait` will be renamed to `wait`. `wait` will default to true. This change will happen on both `.components.[x].manifests` and `components.[x].charts` -- `yolo` will be renamed to `airgap`. `airgap` will default to true +- `.metadata.yolo` will be renamed to `.metadata.airgap`. `airgap` will default to true - `.components.[x].actions.[default/onAny].maxRetries` -> `.components.[x].actions.[default/onAny].retries` - `.components.[x].actions.[default/onAny].maxTotalSeconds` -> `.components.[x].actions.[default/onAny].timeout`, which must be in a [Go recognized duration string format](https://pkg.go.dev/time#ParseDuration) - `.component.[x].charts` will break off fields into different sub-objects depending on the method of consuming the chart. See [#2245](https://github.com/defenseunicorns/zarf/issues/2245). Exactly one of `helm`, `git`, `oci`, or `local` must exist for each `components.[x].charts`, and their objects look like below. The fields `localPath`, `gitPath`, `version`, `URL`, and `repoName` will all be removed from the top level of `components.[x].charts`. From 52f55f9b4328490fac9b0e53191fba475bb099c4 Mon Sep 17 00:00:00 2001 From: Austin Abro Date: Mon, 20 Oct 2025 11:57:47 -0400 Subject: [PATCH 07/30] restructure Signed-off-by: Austin Abro --- 0051-v1beta1-schema/README.md | 26 +++++++++++++++++--------- 1 file changed, 17 insertions(+), 9 deletions(-) diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md index 73629e2..491aba6 100644 --- a/0051-v1beta1-schema/README.md +++ b/0051-v1beta1-schema/README.md @@ -142,19 +142,17 @@ desired outcome and how success will be measured. The "Design Details" section below is for the real nitty-gritty. --> -The v1beta1 schema will remove or rename several fields. +The v1beta1 schema will rename, restructure, and remove several fields. + +### Renamed fields - `.metadata.aggregateChecksum` will move to `.build.aggregateChecksum` -- `.metadata` fields `image`, `source`, `documentation`, `url`, `authors`, `vendors` -> will be removed. `zarf dev convert` will automatically add them as fields under `.metadata.annotations`. +- `.metadata.yolo` will be renamed to `.metadata.airgap`. `airgap` will default to true - `.components[x].required` will be renamed to `.components[x].optional`. `optional` will default to false, this is a change in behavior since required defaults to false. -- `.components.[x].group` will be removed. Users are recommend to use `components[x].only.flavor` instead. -- `setVariable` will be removed. It can be automatically migrated to the existing field `setVariables`. -- `.components.[x].scripts` will be removed. It can be automatically migrated to the existing field `.components.[x].actions`. - `noWait` will be renamed to `wait`. `wait` will default to true. This change will happen on both `.components.[x].manifests` and `components.[x].charts` -- `.metadata.yolo` will be renamed to `.metadata.airgap`. `airgap` will default to true - `.components.[x].actions.[default/onAny].maxRetries` -> `.components.[x].actions.[default/onAny].retries` - `.components.[x].actions.[default/onAny].maxTotalSeconds` -> `.components.[x].actions.[default/onAny].timeout`, which must be in a [Go recognized duration string format](https://pkg.go.dev/time#ParseDuration) -- `.component.[x].charts` will break off fields into different sub-objects depending on the method of consuming the chart. See [#2245](https://github.com/defenseunicorns/zarf/issues/2245). Exactly one of `helm`, `git`, `oci`, or `local` must exist for each `components.[x].charts`, and their objects look like below. The fields `localPath`, `gitPath`, `version`, `URL`, and `repoName` will all be removed from the top level of `components.[x].charts`. +- `.component.[x].charts` will be restructured to move fields into different sub-objects depending on the method of consuming the chart. See [#2245](https://github.com/defenseunicorns/zarf/issues/2245). Exactly one of `helm`, `git`, `oci`, or `local` must exist for each `components.[x].charts`, and their objects look like below. The fields `localPath`, `gitPath`, `version`, `URL`, and `repoName` will all be removed from the top level of `components.[x].charts`. ```yaml - name: podinfo-repo-new helm: @@ -178,12 +176,22 @@ The v1beta1 schema will remove or rename several fields. path: chart # no version field, use local chart.yaml version ``` -- `.components.[x].healthChecks` will be removed in favor of changing the behavior of `.components.[x].actions.[onAny].wait.cluster` to use Kstatus when the `.wait.cluster.condition` is empty. `.wait.cluster` currently shells out to `kubectl wait`. Kstatus checks are generally preferred as the user doesn't need to set a condition, instead Kstatus has inherent knowledge of how to check the readiness of a resource. The advantages of `.wait.cluster` are that specific conditions can be set. This can be useful when readiness is not the desired state, or for certain CRDs that do not implement the fields for Kstatus readiness checks. The original behavior of `.wait.cluster` will be used when `.wait.cluster.condition` is set. + +### Removed fields with automated replacement + +- `.components.[x].actions.[onAny].onSuccess` will be removed. Any onSuccess actions, will be migrated to the end of the `actions.[onAny].after` list. +- `setVariable` will be removed. This field is already deprecated and will be automatically migrated to the existing `.components[x].actions.[x].setVariables`. +- `.components.[x].scripts` will be removed. This field is already deprecated and will be automatically migrated to the existing `.components.[x].actions`. +- `.metadata` fields `image`, `source`, `documentation`, `url`, `authors`, `vendors` will be removed. `zarf dev convert` will automatically move these fields to `.metadata.annotations`, which is a generic map of strings. +- `.components.[x].healthChecks` will be removed in favor of changing the behavior of `.components.[x].actions.[onAny].wait.cluster` to use Kstatus when the `.wait.cluster.condition` is empty. `.wait.cluster` currently shells out to `kubectl wait`. Kstatus checks are generally preferred as the user doesn't need to set a condition, instead Kstatus has inherent knowledge of how to check the readiness of a resource. The advantage of the current `.wait.cluster` behavior is that specific conditions can be set. This can be useful when readiness is not the desired state, or for certain CRDs that do not implement the fields for Kstatus readiness checks. The original behavior of `.wait.cluster` will be used when `.wait.cluster.condition` is set. - Since Kstatus requires the API version, `apiVersion` will be added as a field to `.wait.cluster`. - `.healthChecks` always occur after deploy so `zarf dev convert` will migrate them to `.components[x].actions.onDeploy.After.wait.cluster`. + +### Removed fields without replacement. + +- `.components.[x].group` will be removed. Users are recommend to use `components[x].only.flavor` instead. - `.components.[x].dataInjections` will be removed from the v1beta1 schema without replacement. See [#3926](https://github.com/zarf-dev/zarf/issues/3926). - `.components.[x].charts.[x].variables` will be removed. It's successor is [Zarf values](../0021-zarf-values/), but there will be no automated migration with `zarf dev convert`. -- `.components.[x].actions.[onAny].onSuccess` will be removed. Any onSuccess actions, will be migrated to the end of `actions.[onAny].after`. In order for this schema to be applied, users must set `apiVersion` to `v1beta1`. If `apiVersion` is not set then Zarf will assume it is a v1alpha1 package. Users will be able to automatically upgrade their package to the v1beta1 schema by running `zarf dev convert`. From 8a7d3696451a75bcee48df3cfbb76aec331be1a5 Mon Sep 17 00:00:00 2001 From: Austin Abro Date: Mon, 20 Oct 2025 11:58:09 -0400 Subject: [PATCH 08/30] restructure Signed-off-by: Austin Abro --- 0051-v1beta1-schema/README.md | 36 +++++++++++++++++------------------ 1 file changed, 18 insertions(+), 18 deletions(-) diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md index 491aba6..7d2d872 100644 --- a/0051-v1beta1-schema/README.md +++ b/0051-v1beta1-schema/README.md @@ -144,6 +144,24 @@ below is for the real nitty-gritty. The v1beta1 schema will rename, restructure, and remove several fields. +### Removed fields without replacement. + +- `.components.[x].group` will be removed. Users are recommend to use `components[x].only.flavor` instead. +- `.components.[x].dataInjections` will be removed from the v1beta1 schema without replacement. See [#3926](https://github.com/zarf-dev/zarf/issues/3926). +- `.components.[x].charts.[x].variables` will be removed. It's successor is [Zarf values](../0021-zarf-values/), but there will be no automated migration with `zarf dev convert`. + +In order for this schema to be applied, users must set `apiVersion` to `v1beta1`. If `apiVersion` is not set then Zarf will assume it is a v1alpha1 package. Users will be able to automatically upgrade their package to the v1beta1 schema by running `zarf dev convert`. + +### Removed fields with automated replacement + +- `.components.[x].actions.[onAny].onSuccess` will be removed. Any onSuccess actions, will be migrated to the end of the `actions.[onAny].after` list. +- `setVariable` will be removed. This field is already deprecated and will be automatically migrated to the existing `.components[x].actions.[x].setVariables`. +- `.components.[x].scripts` will be removed. This field is already deprecated and will be automatically migrated to the existing `.components.[x].actions`. +- `.metadata` fields `image`, `source`, `documentation`, `url`, `authors`, `vendors` will be removed. `zarf dev convert` will automatically move these fields to `.metadata.annotations`, which is a generic map of strings. +- `.components.[x].healthChecks` will be removed in favor of changing the behavior of `.components.[x].actions.[onAny].wait.cluster` to use Kstatus when the `.wait.cluster.condition` is empty. `.wait.cluster` currently shells out to `kubectl wait`. Kstatus checks are generally preferred as the user doesn't need to set a condition, instead Kstatus has inherent knowledge of how to check the readiness of a resource. The advantage of the current `.wait.cluster` behavior is that specific conditions can be set. This can be useful when readiness is not the desired state, or for certain CRDs that do not implement the fields for Kstatus readiness checks. The original behavior of `.wait.cluster` will be used when `.wait.cluster.condition` is set. + - Since Kstatus requires the API version, `apiVersion` will be added as a field to `.wait.cluster`. + - `.healthChecks` always occur after deploy so `zarf dev convert` will migrate them to `.components[x].actions.onDeploy.After.wait.cluster`. + ### Renamed fields - `.metadata.aggregateChecksum` will move to `.build.aggregateChecksum` @@ -177,24 +195,6 @@ The v1beta1 schema will rename, restructure, and remove several fields. # no version field, use local chart.yaml version ``` -### Removed fields with automated replacement - -- `.components.[x].actions.[onAny].onSuccess` will be removed. Any onSuccess actions, will be migrated to the end of the `actions.[onAny].after` list. -- `setVariable` will be removed. This field is already deprecated and will be automatically migrated to the existing `.components[x].actions.[x].setVariables`. -- `.components.[x].scripts` will be removed. This field is already deprecated and will be automatically migrated to the existing `.components.[x].actions`. -- `.metadata` fields `image`, `source`, `documentation`, `url`, `authors`, `vendors` will be removed. `zarf dev convert` will automatically move these fields to `.metadata.annotations`, which is a generic map of strings. -- `.components.[x].healthChecks` will be removed in favor of changing the behavior of `.components.[x].actions.[onAny].wait.cluster` to use Kstatus when the `.wait.cluster.condition` is empty. `.wait.cluster` currently shells out to `kubectl wait`. Kstatus checks are generally preferred as the user doesn't need to set a condition, instead Kstatus has inherent knowledge of how to check the readiness of a resource. The advantage of the current `.wait.cluster` behavior is that specific conditions can be set. This can be useful when readiness is not the desired state, or for certain CRDs that do not implement the fields for Kstatus readiness checks. The original behavior of `.wait.cluster` will be used when `.wait.cluster.condition` is set. - - Since Kstatus requires the API version, `apiVersion` will be added as a field to `.wait.cluster`. - - `.healthChecks` always occur after deploy so `zarf dev convert` will migrate them to `.components[x].actions.onDeploy.After.wait.cluster`. - -### Removed fields without replacement. - -- `.components.[x].group` will be removed. Users are recommend to use `components[x].only.flavor` instead. -- `.components.[x].dataInjections` will be removed from the v1beta1 schema without replacement. See [#3926](https://github.com/zarf-dev/zarf/issues/3926). -- `.components.[x].charts.[x].variables` will be removed. It's successor is [Zarf values](../0021-zarf-values/), but there will be no automated migration with `zarf dev convert`. - -In order for this schema to be applied, users must set `apiVersion` to `v1beta1`. If `apiVersion` is not set then Zarf will assume it is a v1alpha1 package. Users will be able to automatically upgrade their package to the v1beta1 schema by running `zarf dev convert`. - ### User Stories (Optional) +In order for this schema to be applied, users must set `apiVersion` to `v1beta1`. If `apiVersion` is not set then Zarf will assume it is a v1alpha1 package. Users will be able to automatically upgrade their package to the v1beta1 schema by running `zarf dev convert`. + The v1beta1 schema will rename, restructure, and remove several fields. ### Removed fields without replacement. -- `.components.[x].group` will be removed. Users are recommend to use `components[x].only.flavor` instead. +- `.components.[x].group` will be removed. Users will be recommended to use `components[x].only.flavor` instead. - `.components.[x].dataInjections` will be removed from the v1beta1 schema without replacement. See [#3926](https://github.com/zarf-dev/zarf/issues/3926). - `.components.[x].charts.[x].variables` will be removed. It's successor is [Zarf values](../0021-zarf-values/), but there will be no automated migration with `zarf dev convert`. -In order for this schema to be applied, users must set `apiVersion` to `v1beta1`. If `apiVersion` is not set then Zarf will assume it is a v1alpha1 package. Users will be able to automatically upgrade their package to the v1beta1 schema by running `zarf dev convert`. - ### Removed fields with automated replacement - `.components.[x].actions.[onAny].onSuccess` will be removed. Any onSuccess actions, will be migrated to the end of the `actions.[onAny].after` list. -- `setVariable` will be removed. This field is already deprecated and will be automatically migrated to the existing `.components[x].actions.[x].setVariables`. +- `.components[x].actions.[onAny].setVariable` will be removed. This field is already deprecated and will be automatically migrated to the existing field `.components[x].actions.[onAny].setVariables`. - `.components.[x].scripts` will be removed. This field is already deprecated and will be automatically migrated to the existing `.components.[x].actions`. - `.metadata` fields `image`, `source`, `documentation`, `url`, `authors`, `vendors` will be removed. `zarf dev convert` will automatically move these fields to `.metadata.annotations`, which is a generic map of strings. - `.components.[x].healthChecks` will be removed in favor of changing the behavior of `.components.[x].actions.[onAny].wait.cluster` to use Kstatus when the `.wait.cluster.condition` is empty. `.wait.cluster` currently shells out to `kubectl wait`. Kstatus checks are generally preferred as the user doesn't need to set a condition, instead Kstatus has inherent knowledge of how to check the readiness of a resource. The advantage of the current `.wait.cluster` behavior is that specific conditions can be set. This can be useful when readiness is not the desired state, or for certain CRDs that do not implement the fields for Kstatus readiness checks. The original behavior of `.wait.cluster` will be used when `.wait.cluster.condition` is set. From ffb02a2451508675fa64c00ffca813c12a20f0fd Mon Sep 17 00:00:00 2001 From: Austin Abro Date: Mon, 20 Oct 2025 12:05:26 -0400 Subject: [PATCH 10/30] easier to read condition Signed-off-by: Austin Abro --- 0051-v1beta1-schema/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md index a900d51..4e6fb2a 100644 --- a/0051-v1beta1-schema/README.md +++ b/0051-v1beta1-schema/README.md @@ -142,7 +142,7 @@ desired outcome and how success will be measured. The "Design Details" section below is for the real nitty-gritty. --> -In order for this schema to be applied, users must set `apiVersion` to `v1beta1`. If `apiVersion` is not set then Zarf will assume it is a v1alpha1 package. Users will be able to automatically upgrade their package to the v1beta1 schema by running `zarf dev convert`. +Zarf will determine the schema of the package definition using the `apiVersion` flag. If `apiVersion` is not set then Zarf will assume it is a v1alpha1 package. Users will be able to automatically upgrade their package to the v1beta1 schema by running `zarf dev convert`. The v1beta1 schema will rename, restructure, and remove several fields. From 776d4d047b37f638cb39eb9526f34ef8a84bffee Mon Sep 17 00:00:00 2001 From: Austin Abro Date: Mon, 20 Oct 2025 12:07:13 -0400 Subject: [PATCH 11/30] spelling Signed-off-by: Austin Abro --- 0051-v1beta1-schema/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md index 4e6fb2a..6dec514 100644 --- a/0051-v1beta1-schema/README.md +++ b/0051-v1beta1-schema/README.md @@ -150,7 +150,7 @@ The v1beta1 schema will rename, restructure, and remove several fields. - `.components.[x].group` will be removed. Users will be recommended to use `components[x].only.flavor` instead. - `.components.[x].dataInjections` will be removed from the v1beta1 schema without replacement. See [#3926](https://github.com/zarf-dev/zarf/issues/3926). -- `.components.[x].charts.[x].variables` will be removed. It's successor is [Zarf values](../0021-zarf-values/), but there will be no automated migration with `zarf dev convert`. +- `.components.[x].charts.[x].variables` will be removed. Its successor is [Zarf values](../0021-zarf-values/), but there will be no automated migration with `zarf dev convert`. ### Removed fields with automated replacement From b4f1ebf191657e5007dcaad2f92cdea24d38e769 Mon Sep 17 00:00:00 2001 From: Austin Abro Date: Mon, 20 Oct 2025 14:44:20 -0400 Subject: [PATCH 12/30] zarf chart changes Signed-off-by: Austin Abro --- 0051-v1beta1-schema/README.md | 95 +++++++++++++++++++++++++++++------ 1 file changed, 81 insertions(+), 14 deletions(-) diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md index 6dec514..de243b4 100644 --- a/0051-v1beta1-schema/README.md +++ b/0051-v1beta1-schema/README.md @@ -146,7 +146,7 @@ Zarf will determine the schema of the package definition using the `apiVersion` The v1beta1 schema will rename, restructure, and remove several fields. -### Removed fields without replacement. +### Removed fields without replacement - `.components.[x].group` will be removed. Users will be recommended to use `components[x].only.flavor` instead. - `.components.[x].dataInjections` will be removed from the v1beta1 schema without replacement. See [#3926](https://github.com/zarf-dev/zarf/issues/3926). @@ -161,16 +161,7 @@ The v1beta1 schema will rename, restructure, and remove several fields. - `.components.[x].healthChecks` will be removed in favor of changing the behavior of `.components.[x].actions.[onAny].wait.cluster` to use Kstatus when the `.wait.cluster.condition` is empty. `.wait.cluster` currently shells out to `kubectl wait`. Kstatus checks are generally preferred as the user doesn't need to set a condition, instead Kstatus has inherent knowledge of how to check the readiness of a resource. The advantage of the current `.wait.cluster` behavior is that specific conditions can be set. This can be useful when readiness is not the desired state, or for certain CRDs that do not implement the fields for Kstatus readiness checks. The original behavior of `.wait.cluster` will be used when `.wait.cluster.condition` is set. - Since Kstatus requires the API version, `apiVersion` will be added as a field to `.wait.cluster`. - `.healthChecks` always occur after deploy so `zarf dev convert` will migrate them to `.components[x].actions.onDeploy.After.wait.cluster`. - -### Renamed fields - -- `.metadata.aggregateChecksum` will move to `.build.aggregateChecksum` -- `.metadata.yolo` will be renamed to `.metadata.airgap`. `airgap` will default to true -- `.components[x].required` will be renamed to `.components[x].optional`. `optional` will default to false, this is a change in behavior since required defaults to false. -- `noWait` will be renamed to `wait`. `wait` will default to true. This change will happen on both `.components.[x].manifests` and `components.[x].charts` -- `.components.[x].actions.[default/onAny].maxRetries` -> `.components.[x].actions.[default/onAny].retries` -- `.components.[x].actions.[default/onAny].maxTotalSeconds` -> `.components.[x].actions.[default/onAny].timeout`, which must be in a [Go recognized duration string format](https://pkg.go.dev/time#ParseDuration) -- `.component.[x].charts` will be restructured to move fields into different sub-objects depending on the method of consuming the chart. See [#2245](https://github.com/defenseunicorns/zarf/issues/2245). Exactly one of `helm`, `git`, `oci`, or `local` must exist for each `components.[x].charts`, and their objects look like below. The fields `localPath`, `gitPath`, `version`, `URL`, and `repoName` will all be removed from the top level of `components.[x].charts`. +- `.component.[x].charts` will be restructured to move fields into different sub-objects depending on the method of consuming the chart. ```yaml - name: podinfo-repo-new helm: @@ -193,7 +184,16 @@ The v1beta1 schema will rename, restructure, and remove several fields. local: path: chart # no version field, use local chart.yaml version -``` +``` + +### Renamed fields + +- `.metadata.aggregateChecksum` will move to `.build.aggregateChecksum` +- `.metadata.yolo` will be renamed to `.metadata.airgap`. `airgap` will default to true +- `.components[x].required` will be renamed to `.components[x].optional`. `optional` will default to false, this is a change in behavior since required defaults to false. +- `noWait` will be renamed to `wait`. `wait` will default to true. This change will happen on both `.components.[x].manifests` and `components.[x].charts` +- `.components.[x].actions.[default/onAny].maxRetries` -> `.components.[x].actions.[default/onAny].retries` +- `.components.[x].actions.[default/onAny].maxTotalSeconds` -> `.components.[x].actions.[default/onAny].timeout`, which must be in a [Go recognized duration string format](https://pkg.go.dev/time#ParseDuration) ### User Stories (Optional) @@ -353,7 +353,7 @@ components: # condition is empty, so Kstatus will be used for readiness check ``` -The `healthChecks` field has been removed and replaced with an `actions.onDeploy.after` wait action that uses Kstatus for health checking when no explicit condition is set. +a v1beta1 package that replaces the `healthChecks` entry with an `onDeploy.after.wait.cluster` entry. ### Risks and Mitigations @@ -367,7 +367,7 @@ How will security be reviewed, and by whom? How will UX be reviewed, and by whom? --> -The fields `.components.[x].dataInjections` will be removed without a direct replacement in the schema. There must be documentation to present to users so they know what alternatives they can use achieve a similar result. +The field `.components.[x].dataInjections` will be removed without a direct replacement in the schema. There must be documentation to present to users so they know what alternatives they can use achieve a similar result. The alpha field `.components.[x].charts.[x].variables` has seen significant adoption and we will not be able to automatically convert users to Zarf values with `zarf dev convert`. There should be documentation on how users can utilize Zarf values as an alternative to chart variables. @@ -380,6 +380,73 @@ required) or even code snippets. If there's any ambiguity about HOW your proposal will be implemented, this is the place to discuss that. --> +### Zarf Chart Changes + +The ZarfChart object will be restructured. The new object is defined below. Exactly one of `helm`, `git`, `oci`, or `local` must exist for each `components.[x].charts`, and their objects look like below. The fields `localPath`, `gitPath`, `URL`, and `repoName` are all removed from the top level of `components.[x].charts`. See [#2245](https://github.com/defenseunicorns/zarf/issues/2245). + +During conversion, Zarf will detect the method of consuming the chart and create the proper sub-objects. If a git repo is used `@{{Version}}` will be appended to the URL. This is consistent with the current Zarf behavior. + +Zarf uses the top level `version` field to determine where in the package layout file structure it will place charts. This makes the field necessary for create and deploy, and therefore it must be carried over using the strategy defined in the removed fields section of [0048](https://github.com/zarf-dev/proposals/pull/49/files). Newer versions of Zarf will ensure that Zarf works whether or not `version` is set. Packages created with the v1beta1 schema will leave `version` empty, and therefore not work with previous versions of Zarf. When support is dropped for v1alpha1 packages the `version` field will be dropped entirely. + +```go +// ZarfChart defines a helm chart to be deployed. +type ZarfChart struct { + // The name of the chart within Zarf; note that this must be unique and does not need to be the same as the name in the chart repo. + Name string `json:"name"` + // The version of the chart. This field is removed for the schema, but kept as a backwards compatibility shim so v1alpha1 packages can be converted to v1beta1 + version string + // The Helm repo where the chart is stored + Helm HelmRepoSource `json:"helm,omitempty"` + // The Git repo where the chart is stored + Git GitRepoSource `json:"git,omitempty"` + // The local path where the chart is stored + Local LocalRepoSource `json:"local,omitempty"` + // The OCI registry where the chart is stored + OCI OCISource `json:"oci,omitempty"` + // The namespace to deploy the chart to. + Namespace string `json:"namespace,omitempty"` + // The name of the Helm release to create (defaults to the Zarf name of the chart). + ReleaseName string `json:"releaseName,omitempty"` + // Whether to not wait for chart resources to be ready before continuing. + Wait *bool `json:"wait,omitempty"` + // List of local values file paths or remote URLs to include in the package; these will be merged together when deployed. + ValuesFiles []string `json:"valuesFiles,omitempty"` + // [alpha] List of values sources to their Helm override target + Values []ZarfChartValue `json:"values,omitempty"` +} + +// HelmRepoSource represents a Helm chart stored in a Helm repository. +type HelmRepoSource struct { + // The name of a chart within a Helm repository + RepoName string `json:"repoName,omitempty"` + // The URL of the chart repository where the helm chart is stored. + URL string `json:"url"` + // The version of the chart to deploy; for git-based charts this is also the tag of the git repo by default (when not using the '@' syntax for 'repos'). + Version string `json:"version"` +} + +// GitRepoSource represents a Helm chart stored in a Git repository. +type GitRepoSource struct { + // The URL of the git repository where the helm chart is stored. + URL string `json:"url"` + // The sub directory to the chart within a git repo. + Path string `json:"path,omitempty"` +} + +// LocalRepoSource represents a Helm chart stored locally. +type LocalRepoSource struct { + // The path to a local chart's folder or .tgz archive. + Path string `json:"path"` +} + +// OCISource represents a Helm chart stored in an OCI registry. +type OCISource struct { + // The URL of the OCI registry where the helm chart is stored. + URL string `json:"url"` + Version string `json:"version"` +} +``` + ### Test Plan -### Zarf Chart Changes +### Zarf Helm Chart Changes The ZarfChart object will be restructured. The new object is defined below. Exactly one of `helm`, `git`, `oci`, or `local` must exist for each `components.[x].charts`, and their objects look like below. The fields `localPath`, `gitPath`, `URL`, and `repoName` are all removed from the top level of `components.[x].charts`. See [#2245](https://github.com/defenseunicorns/zarf/issues/2245). -During conversion, Zarf will detect the method of consuming the chart and create the proper sub-objects. If a git repo is used `@{{Version}}` will be appended to the URL. This is consistent with the current Zarf behavior. +During conversion, Zarf will detect the method of consuming the chart and create the proper sub-objects. If a git repo is used `@{{Version}}` will be appended to `.gitRepoSource.URL`. This is consistent with the current Zarf behavior. -Zarf uses the top level `version` field to determine where in the package layout file structure it will place charts. This makes the field necessary for create and deploy, and therefore it must be carried over using the strategy defined in the removed fields section of [0048](https://github.com/zarf-dev/proposals/pull/49/files). Newer versions of Zarf will ensure that Zarf works whether or not `version` is set. Packages created with the v1beta1 schema will leave `version` empty, and therefore not work with previous versions of Zarf. When support is dropped for v1alpha1 packages the `version` field will be dropped entirely. +Zarf uses the top level `version` field to determine where in the package layout file structure it will place charts. This makes the field necessary for create and deploy, and therefore it must be carried over using the strategy defined in the removed fields section of [0048](https://github.com/zarf-dev/proposals/pull/49/files). Newer versions of Zarf will ensure that Zarf works whether or not `version` is set. Packages created with the v1beta1 schema will leave `version` empty, and therefore not work with previous versions of Zarf. When support is dropped for v1alpha1 packages the `version` field will be dropped entirely. Note, this applies to internal conversions of v1alpha1 packages so function signatures can be updated to use v1beta1 objects. `zarf dev convert` will simply move the top level `version` field to the right sub object, or drop it when not applicable. ```go // ZarfChart defines a helm chart to be deployed. @@ -494,7 +471,7 @@ If this feature will eventually be deprecated, plan for it: - Alpha: fields are subject to change or rename. No backwards compatibility guarantees. - Beta: Fields will not change in a way that is not fully backwards compatible. -- GA: We've received feedback that all of are changes are an improvement. Examples and tests in Zarf shift to using the v1beta1 schema. +- GA: We've received feedback from users and are confident improve the user experience. Examples and tests in Zarf shift to using the v1beta1 schema. Deprecation: - This schema will likely be deprecated one day in the future in favor of a v1 schema. It will not be deprecated until the next schema version is at least generally available. Once deprecated, Zarf will still support the v1beta1 schema for at least a year. @@ -515,7 +492,7 @@ proposal: make use of the proposal? --> - +Once the v1beta1 package schema is released, all functions in Zarf will be changed to use v1beta1 objects. ### Version Skew Strategy @@ -529,6 +506,8 @@ proposal: - (i.e. the Zarf Agent and CLI? The init package and the CLI?) --> + + ## Implementation History -Once the v1beta1 package schema is released, all functions in Zarf will be changed to use v1beta1 objects. +This is discussed more in detail in ZEP-0048 ### Version Skew Strategy From e571b1e65097ac7528416fd562a0c5a02880b0b1 Mon Sep 17 00:00:00 2001 From: Austin Abro Date: Mon, 20 Oct 2025 15:37:54 -0400 Subject: [PATCH 15/30] grammar Signed-off-by: Austin Abro --- 0051-v1beta1-schema/README.md | 12 ++++++------ 0051-v1beta1-schema/zep.yaml | 6 +++--- 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md index b62635a..c3b0687 100644 --- a/0051-v1beta1-schema/README.md +++ b/0051-v1beta1-schema/README.md @@ -92,7 +92,7 @@ feedback and reduce unnecessary changes. [documentation style guide]: https://docs.zarf.dev/contribute/style-guide/ --> -Several fields in the ZarfPackageConfig v1alpha1 can be restructured to provide a more intuitive experience. Some field in the v1alpha1 schema have a poor user experience and add overhead to Zarf, these will be removed. A new schema version, v1beta1, provides Zarf the space to make these changes. +Several fields in the ZarfPackageConfig v1alpha1 can be restructured to provide a more intuitive experience. Some fields in the v1alpha1 schema have a poor user experience and add overhead to Zarf, these will be removed. A new schema version, v1beta1, provides Zarf the space to make these changes. ## Motivation @@ -112,7 +112,7 @@ There are several open issues requesting enhancements to the schema. The general - [Breaking Change: make components required by default #2059](https://github.com/zarf-dev/zarf/issues/2059) - [Use kstatus as the engine behind zarf tools wait-for and .wait.cluster #4077](https://github.com/zarf-dev/zarf/issues/4077) -Additionally, users often struggle to use data injections. Usually, they would be be better served by using a Kubernetes native solution [#3926](https://github.com/zarf-dev/zarf/issues/3926). +Additionally, users often struggle to use data injections. Usually, they would be better served by using a Kubernetes native solution [#3926](https://github.com/zarf-dev/zarf/issues/3926). ### Goals @@ -158,7 +158,7 @@ These fields will error when `zarf dev convert` is run and recommend an alternat `zarf dev convert` will work with these fields. -- `.components.[x].actions.[onAny].onSuccess` will be removed. Any `onSuccess` actions, will be migrated to the end of the `actions.[onAny].after` list. +- `.components.[x].actions.[onAny].onSuccess` will be removed. Any `onSuccess` actions will be migrated to the end of the `actions.[onAny].after` list. - `.components[x].actions.[onAny].setVariable` will be removed. This field is already deprecated and will be automatically migrated to the existing field `.components[x].actions.[onAny].setVariables`. - `.components.[x].scripts` will be removed. This field is already deprecated and will be automatically migrated to the existing `.components.[x].actions`. - `.metadata` fields `image`, `source`, `documentation`, `url`, `authors`, `vendors` will be removed. `zarf dev convert` will automatically move these fields to `.metadata.annotations`, which is a generic map of strings. @@ -173,7 +173,7 @@ These fields will error when `zarf dev convert` is run and recommend an alternat - `.metadata.aggregateChecksum` will move to `.build.aggregateChecksum` - `.metadata.yolo` will be renamed to `.metadata.airgap`. `airgap` will default to true -- `.components[x].required` will be renamed to `.components[x].optional`. `optional` will default to false, this is a change in behavior since required defaults to false. +- `.components[x].required` will be renamed to `.components[x].optional`. `optional` will default to false, this is a change in behavior since `required` defaults to false - `noWait` will be renamed to `wait`. `wait` will default to true. This change will happen on both `.components.[x].manifests` and `components.[x].charts` - `.components.[x].actions.[default/onAny].maxRetries` -> `.components.[x].actions.[default/onAny].retries` - `.components.[x].actions.[default/onAny].maxTotalSeconds` -> `.components.[x].actions.[default/onAny].timeout`, which must be in a [Go recognized duration string format](https://pkg.go.dev/time#ParseDuration) @@ -350,7 +350,7 @@ How will security be reviewed, and by whom? How will UX be reviewed, and by whom? --> -The field `.components.[x].dataInjections` will be removed without a direct replacement in the schema. There must be documentation to present to users so they know what alternatives they can use achieve a similar result. +The field `.components.[x].dataInjections` will be removed without a direct replacement in the schema. There must be documentation to present to users so they know what alternatives they can use to achieve a similar result. The alpha field `.components.[x].charts.[x].variables` has seen significant adoption and we will not be able to automatically convert users to Zarf values with `zarf dev convert`. There should be documentation on how users can utilize Zarf values as an alternative to chart variables. @@ -477,7 +477,7 @@ If this feature will eventually be deprecated, plan for it: - Alpha: fields are subject to change or rename. No backwards compatibility guarantees. - Beta: Fields will not change in a way that is not fully backwards compatible. -- GA: We've received feedback from users and are confident improve the user experience. Examples and tests in Zarf shift to using the v1beta1 schema. +- GA: Users have provided feedback that the new schema improves the UX. Examples and tests in Zarf shift to using the v1beta1 schema. Deprecation: - This schema will likely be deprecated one day in the future in favor of a v1 schema. It will not be deprecated until the next schema version is at least generally available. Once deprecated, Zarf will still support the v1beta1 schema for at least one year. diff --git a/0051-v1beta1-schema/zep.yaml b/0051-v1beta1-schema/zep.yaml index d982c61..817ab91 100644 --- a/0051-v1beta1-schema/zep.yaml +++ b/0051-v1beta1-schema/zep.yaml @@ -1,9 +1,9 @@ schema-version: 1.0.0 -title: ZEP Template -zep-number: NNNN +title: v1beta1 schema +zep-number: 0051 authors: - - "@jane.doe" + - "@austinabro321" status: provisional|implementable|implemented|deferred|rejected|withdrawn|replaced creation-date: yyyy-mm-dd reviewers: From 38a1249908d2883a42485e6be7add9e893924069 Mon Sep 17 00:00:00 2001 From: Austin Abro Date: Mon, 20 Oct 2025 15:42:47 -0400 Subject: [PATCH 16/30] grammar Signed-off-by: Austin Abro --- 0051-v1beta1-schema/README.md | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md index c3b0687..a1fcf9c 100644 --- a/0051-v1beta1-schema/README.md +++ b/0051-v1beta1-schema/README.md @@ -92,7 +92,7 @@ feedback and reduce unnecessary changes. [documentation style guide]: https://docs.zarf.dev/contribute/style-guide/ --> -Several fields in the ZarfPackageConfig v1alpha1 can be restructured to provide a more intuitive experience. Some fields in the v1alpha1 schema have a poor user experience and add overhead to Zarf, these will be removed. A new schema version, v1beta1, provides Zarf the space to make these changes. +Several fields in the ZarfPackageConfig v1alpha1 can be restructured to provide a more intuitive experience. Some fields in the v1alpha1 schema have a poor user experience and add overhead to Zarf; these will be removed. A new schema version, v1beta1, provides Zarf the space to make these changes. ## Motivation @@ -173,8 +173,8 @@ These fields will error when `zarf dev convert` is run and recommend an alternat - `.metadata.aggregateChecksum` will move to `.build.aggregateChecksum` - `.metadata.yolo` will be renamed to `.metadata.airgap`. `airgap` will default to true -- `.components[x].required` will be renamed to `.components[x].optional`. `optional` will default to false, this is a change in behavior since `required` defaults to false -- `noWait` will be renamed to `wait`. `wait` will default to true. This change will happen on both `.components.[x].manifests` and `components.[x].charts` +- `.components[x].required` will be renamed to `.components[x].optional`. `optional` will default to false. This is a change in behavior since `required` defaults to false. +- `noWait` will be renamed to `wait`. `wait` will default to true. This change will happen on both `.components.[x].manifests` and `.components.[x].charts`. - `.components.[x].actions.[default/onAny].maxRetries` -> `.components.[x].actions.[default/onAny].retries` - `.components.[x].actions.[default/onAny].maxTotalSeconds` -> `.components.[x].actions.[default/onAny].timeout`, which must be in a [Go recognized duration string format](https://pkg.go.dev/time#ParseDuration) @@ -336,8 +336,6 @@ components: # condition is empty, so Kstatus will be used for readiness check ``` -a v1beta1 package that replaces the `healthChecks` entry with an `onDeploy.after.wait.cluster` entry. - ### Risks and Mitigations -This is discussed more in detail in ZEP-0048 +This is discussed in more detail in ZEP-0048. ### Version Skew Strategy From f7ba8377fbd91813dc15b16afe16c94c9caa79fe Mon Sep 17 00:00:00 2001 From: Austin Abro Date: Tue, 21 Oct 2025 08:08:13 -0400 Subject: [PATCH 17/30] upgrade / downgrade Signed-off-by: Austin Abro --- 0051-v1beta1-schema/README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md index a1fcf9c..66fa2d9 100644 --- a/0051-v1beta1-schema/README.md +++ b/0051-v1beta1-schema/README.md @@ -447,7 +447,7 @@ to implement this proposal. There will be e2e tests for `zarf dev convert` from a v1alpha1 definition to a v1beta1 definition. -There will be e2e tests for creating, deploying, and publishing a v1beta1 package. As the schema nears towards GA existing tests will shift to use the v1beta1 schema. +There will be e2e tests for creating, deploying, and publishing a v1beta1 package. As the schema nears towards GA, existing tests will shift to use the v1beta1 schema. ### Graduation Criteria @@ -496,7 +496,7 @@ proposal: make use of the proposal? --> -This is discussed in more detail in ZEP-0048. +See upgrade / downgrade strategy in ZEP-0048 ### Version Skew Strategy @@ -510,7 +510,7 @@ proposal: - (i.e. the Zarf Agent and CLI? The init package and the CLI?) --> - +See version skew strategy in ZEP-0048 ## Implementation History From 345e9c8b4add5a1585933efee0b9a84f1c68412f Mon Sep 17 00:00:00 2001 From: Austin Abro Date: Tue, 21 Oct 2025 08:45:40 -0400 Subject: [PATCH 18/30] ZEP 0048 Signed-off-by: Austin Abro --- 0051-v1beta1-schema/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md index 66fa2d9..90ae094 100644 --- a/0051-v1beta1-schema/README.md +++ b/0051-v1beta1-schema/README.md @@ -496,7 +496,7 @@ proposal: make use of the proposal? --> -See upgrade / downgrade strategy in ZEP-0048 +See ZEP-0048 ### Version Skew Strategy From 9764cefe89397b236b59d297273f51722c120f30 Mon Sep 17 00:00:00 2001 From: Austin Abro Date: Tue, 21 Oct 2025 09:48:40 -0400 Subject: [PATCH 19/30] proposal Signed-off-by: Austin Abro --- 0051-v1beta1-schema/README.md | 10 ++++++---- 0051-v1beta1-schema/zep.yaml | 25 ++++++++++--------------- 2 files changed, 16 insertions(+), 19 deletions(-) diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md index 90ae094..e2913c8 100644 --- a/0051-v1beta1-schema/README.md +++ b/0051-v1beta1-schema/README.md @@ -92,7 +92,7 @@ feedback and reduce unnecessary changes. [documentation style guide]: https://docs.zarf.dev/contribute/style-guide/ --> -Several fields in the ZarfPackageConfig v1alpha1 can be restructured to provide a more intuitive experience. Some fields in the v1alpha1 schema have a poor user experience and add overhead to Zarf; these will be removed. A new schema version, v1beta1, provides Zarf the space to make these changes. +Several fields in the ZarfPackageConfig v1alpha1 can be restructured to provide a more intuitive experience. Other fields have a poor user experience and add unnecessary overhead to Zarf; these fields will be removed. A new schema version, v1beta1, provides the space to make these changes. ## Motivation @@ -163,7 +163,7 @@ These fields will error when `zarf dev convert` is run and recommend an alternat - `.components.[x].scripts` will be removed. This field is already deprecated and will be automatically migrated to the existing `.components.[x].actions`. - `.metadata` fields `image`, `source`, `documentation`, `url`, `authors`, `vendors` will be removed. `zarf dev convert` will automatically move these fields to `.metadata.annotations`, which is a generic map of strings. - `.components.[x].healthChecks` will be removed in favor of changing the behavior of `.components.[x].actions.[onAny].wait.cluster` to use Kstatus when the `.wait.cluster.condition` is empty. `.wait.cluster` currently shells out to `kubectl wait`. Kstatus checks are generally preferred as the user doesn't need to set a condition, instead Kstatus has inherent knowledge of how to check the readiness of a resource. The advantage of the current `.wait.cluster` behavior is that specific conditions can be set. This can be useful when readiness is not the desired state, or for certain CRDs that do not implement the fields for Kstatus readiness checks. The original behavior of `.wait.cluster` will be used when `.wait.cluster.condition` is set. - - Since Kstatus requires the API version, `apiVersion` will be added as a field to `.wait.cluster`. + - Since Kstatus requires API version, `apiVersion` will be added as a field to `.wait.cluster`. - `.healthChecks` always occur after deploy so `zarf dev convert` will migrate them to `.components[x].actions.onDeploy.After.wait.cluster`. - `.component.[x].charts` will be restructured to move fields into different sub-objects depending on the method of consuming the chart. See [Helm Chart Changes](#zarf-helm-chart-changes) @@ -350,7 +350,7 @@ How will UX be reviewed, and by whom? The field `.components.[x].dataInjections` will be removed without a direct replacement in the schema. There must be documentation to present to users so they know what alternatives they can use to achieve a similar result. -The alpha field `.components.[x].charts.[x].variables` has seen significant adoption and we will not be able to automatically convert users to Zarf values with `zarf dev convert`. There should be documentation on how users can utilize Zarf values as an alternative to chart variables. +The alpha field `.components.[x].charts.[x].variables` has seen significant adoption and there will be no automatic conversion to it's replacement Zarf values. There must be documentation on how users can utilize Zarf values as an alternative to chart variables. ## Design Details @@ -496,7 +496,7 @@ proposal: make use of the proposal? --> -See ZEP-0048 +See proposal in ZEP-0048 ### Version Skew Strategy @@ -525,6 +525,8 @@ Major milestones might include: - when the ZEP was retired or superseded --> +- 2025-10-21: Proposal submitted + ## Drawbacks -There are several open issues requesting enhancements to the schema. The general theme of these changes is to make the ZarfPackageConfig schema more intuitive to use. +There are several open issues requesting enhancements to the schema. The general theme of these changes is to make it easier to create Zarf packages. - [Refactor charts definition in zarf.yaml #2245](https://github.com/zarf-dev/zarf/issues/2245) - [Breaking Change: make components required by default #2059](https://github.com/zarf-dev/zarf/issues/2059) - [Use kstatus as the engine behind zarf tools wait-for and .wait.cluster #4077](https://github.com/zarf-dev/zarf/issues/4077) Additionally, users often struggle to use data injections. Usually, they would be better served by using a Kubernetes native solution [#3926](https://github.com/zarf-dev/zarf/issues/3926). -### Goals1 +### Goals -Zarf will determine the schema of the package definition using the `apiVersion` flag. If `apiVersion` is not set then Zarf will assume it is a v1alpha1 package. Users will be able to automatically upgrade their package to the v1beta1 schema by running `zarf dev convert`. +Zarf will determine the schema of the package definition using the top level `apiVersion` field. `apiVersion` already exists as a top level field in the Zarf package config schema. If `apiVersion` is not set then Zarf will assume it is a v1alpha1 package. Users will be able to automatically upgrade their package to the v1beta1 schema by running `zarf dev convert`. -The v1beta1 schema will rename, restructure, and remove several fields. +The v1beta1 schema will remove, restructure, and rename several fields. ### Removed fields without replacement @@ -158,12 +158,12 @@ These fields will error when `zarf dev convert` is run and recommend an alternat `zarf dev convert` will automatically migrate these fields. -- `.components.[x].actions.[onAny].onSuccess` will be removed. Any `onSuccess` actions will be migrated to the end of the `actions.[onAny].after` list. +- `.components.[x].actions.[onAny].onSuccess` will be removed. Any `onSuccess` actions will be appended to the `actions.[onAny].after` list. - `.components[x].actions.[onAny].setVariable` will be removed. This field is already deprecated and will be migrated to the existing field `.components[x].actions.[onAny].setVariables`. - `.components.[x].scripts` will be removed. This field is already deprecated and will be migrated to the existing `.components.[x].actions`. - `.metadata` fields `image`, `source`, `documentation`, `url`, `authors`, `vendors` will be removed. `zarf dev convert` will move these fields under `.metadata.annotations`, which is a generic map of strings. - `.components[x].actions.[onAny].wait.cluster` will receive a new required sub field, `.apiVersion`. During conversion `.apiVersion` will be added to the object but kept empty. Users will be warned that they must fill this field out, otherwise create will error. -- `.components.[x].healthChecks` will be removed and appended to `.components.[x].actions.[onAny].wait.cluster` during conversions. This will be accompanied by a behavior change in `zarf tools wait-for` to perform kstatus style readiness checks when `.wait.cluster.condition` is empty. See [Zarf Tools wait-for Changes](#zarf-tools-wait-for-changes). +- `.components.[x].healthChecks` will be removed and appended to `.components.[x].actions.[onAny].wait.cluster`. This will be accompanied by a behavior change in `zarf tools wait-for` to perform kstatus style readiness checks when `.wait.cluster.condition` is empty. See [Zarf Tools wait-for Changes](#zarf-tools-wait-for-changes). - `.component.[x].charts` will be restructured to move fields into different sub-objects depending on the method of consuming the chart. See [Helm Chart Changes](#zarf-helm-chart-changes) ### Renamed fields @@ -362,11 +362,11 @@ proposal will be implemented, this is the place to discuss that. ### Zarf Helm Chart Changes -The ZarfChart object will be restructured. The new object is defined below. Exactly one of `helm`, `git`, `oci`, or `local` must exist for each `components.[x].charts`, and their objects look like below. The fields `localPath`, `gitPath`, `URL`, and `repoName` are all removed from the top level of `components.[x].charts`. See [#2245](https://github.com/defenseunicorns/zarf/issues/2245). +The ZarfChart object will be restructured to match the code block below. Exactly one of sub-objects `helm`, `git`, `oci`, or `local` must exist for each `components.[x].charts`. The fields `localPath`, `gitPath`, `URL`, and `repoName` will be removed from the top level of `components.[x].charts`. See [#2245](https://github.com/defenseunicorns/zarf/issues/2245). During conversion, Zarf will detect the method of consuming the chart and create the proper sub-objects. If a git repo is used then `@` + the `.version` value will be appended to `.gitRepoSource.URL`. This is consistent with the current Zarf behavior. -Zarf uses the top level `version` field to determine where in the package layout file structure it will place charts. This makes the field necessary for create and deploy, and therefore it must be carried over using the strategy defined in the removed fields section of [0048](https://github.com/zarf-dev/proposals/pull/49/files). Newer versions of Zarf will ensure that Zarf works whether or not `version` is set. Packages created with the v1beta1 schema will leave `version` empty, and therefore not work with previous versions of Zarf. When support is dropped for v1alpha1 packages the `version` field will be dropped entirely. Note, this process is applied to internal conversion so that there is no change in behavior when v1alpha1 packages use function signatures that container v1beta1 objects. `zarf dev convert` will simply move the top level `version` field to the right sub object, or drop it when not applicable. +Zarf uses the top level `version` field to determine where in the package layout file structure it will place charts. This makes the field necessary for deploy, and therefore it must be carried over using the strategy defined in the removed fields section of [0048](https://github.com/zarf-dev/proposals/pull/49/files). Newer versions of Zarf will ensure that Zarf works whether or not `version` is set. Packages created with the v1beta1 schema will leave `version` empty, and therefore not work with earlier versions of Zarf. When support is dropped for v1alpha1 packages the `version` field will be dropped entirely. Note, this process is applied to internal conversion so that there is no change in behavior when v1alpha1 packages use function signatures that contain v1beta1 objects. `zarf dev convert` will simply move the top level `version` field to the right sub object, or drop it when not applicable. ```go // ZarfChart defines a helm chart to be deployed. @@ -429,9 +429,9 @@ type OCISource struct { #### Zarf Tools wait-for Changes -`zarf tools wait-for` is the underlying engine to `.wait.cluster`. Currently, `zarf tools wait-for` shell out to `zarf tools kubectl wait`. In the future, `wait-for` will optionally accept an API version alongside the resource kind. If API version is set, and condition is empty then kstatus will be used as `wait-for`'s engine. +`zarf tools wait-for` is the underlying engine to `.wait.cluster`. Currently, `zarf tools wait-for` shells out to `zarf tools kubectl wait`. In the future, `wait-for` will optionally accept an API version alongside the resource kind. If API version is set, and condition is empty then kstatus will be used as `wait-for`'s engine. -v1alpha1 packages do not have `.apiVersion` as a sub field under `.wait.cluster`, so they will always use the existing engine, avoiding breaking changes. v1beta1 packages will require that `apiVersion` is set, and will be able to optionally set `condition` as kstatus only checks for readiness. +v1alpha1 packages do not have `.apiVersion` as a sub field under `.wait.cluster`, so they will always use the existing engine, avoiding breaking changes. v1beta1 packages will require that `apiVersion` is set. ### Test Plan From 0251e7ace085106b316fd4692ad898d853539344 Mon Sep 17 00:00:00 2001 From: Austin Abro Date: Fri, 24 Oct 2025 08:56:12 -0400 Subject: [PATCH 25/30] fix Signed-off-by: Austin Abro --- 0051-v1beta1-schema/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md index a799475..c55d534 100644 --- a/0051-v1beta1-schema/README.md +++ b/0051-v1beta1-schema/README.md @@ -92,7 +92,7 @@ feedback and reduce unnecessary changes. [documentation style guide]: https://docs.zarf.dev/contribute/style-guide/ --> -Several fields in the ZarfPackageConfig v1alpha1 can be restructured to provide a more intuitive experience. Other fields have a poor user experience and add unnecessary overhead to Zarf; these fields will be removed. A new schema version, v1beta1, provides the space to make these changes. +Several fields in the v1alpha1 ZarfPackageConfig can be restructured to provide a more intuitive experience. Other fields have a poor user experience and add unnecessary overhead to Zarf; these fields will be removed. A new schema version, v1beta1, provides the space to make these changes. ## Motivation From 27e195fdf2930787bc5e7691779fa3f1df40659c Mon Sep 17 00:00:00 2001 From: Austin Abro Date: Fri, 24 Oct 2025 09:04:21 -0400 Subject: [PATCH 26/30] clenaup flow Signed-off-by: Austin Abro --- 0051-v1beta1-schema/README.md | 20 +++++++++----------- 1 file changed, 9 insertions(+), 11 deletions(-) diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md index c55d534..6a2c1a0 100644 --- a/0051-v1beta1-schema/README.md +++ b/0051-v1beta1-schema/README.md @@ -92,7 +92,7 @@ feedback and reduce unnecessary changes. [documentation style guide]: https://docs.zarf.dev/contribute/style-guide/ --> -Several fields in the v1alpha1 ZarfPackageConfig can be restructured to provide a more intuitive experience. Other fields have a poor user experience and add unnecessary overhead to Zarf; these fields will be removed. A new schema version, v1beta1, provides the space to make these changes. +Several fields in the v1alpha1 ZarfPackageConfig can be restructured to provide a more intuitive experience. Other fields that have a poor user experience and add unnecessary overhead to Zarf should be removed. A new schema version, v1beta1, provides the space to make these changes. ## Motivation @@ -142,11 +142,11 @@ desired outcome and how success will be measured. The "Design Details" section below is for the real nitty-gritty. --> -Zarf will determine the schema of the package definition using the top level `apiVersion` field. `apiVersion` already exists as a top level field in the Zarf package config schema. If `apiVersion` is not set then Zarf will assume it is a v1alpha1 package. Users will be able to automatically upgrade their package to the v1beta1 schema by running `zarf dev convert`. +Zarf will determine the schema of the package definition using the existing optional field `apiVersion`. If `apiVersion` is not set then Zarf will assume it is a v1alpha1 package. Users will be able to automatically upgrade their package to the v1beta1 schema by running `zarf dev convert`. -The v1beta1 schema will remove, restructure, and rename several fields. +The v1beta1 schema will remove, replace, and rename several fields. -### Removed fields without replacement +### Removed Fields These fields will error when `zarf dev convert` is run and recommend an alternative method to achieve the desired behavior. @@ -154,7 +154,7 @@ These fields will error when `zarf dev convert` is run and recommend an alternat - `.components.[x].dataInjections` will be removed. There will be a guide in Zarf's documentation for alternatives. See [#3926](https://github.com/zarf-dev/zarf/issues/3926). - `.components.[x].charts.[x].variables` will be removed. Its successor is [Zarf values](../0021-zarf-values/), but there will be no automated migration with `zarf dev convert`. -### Removed fields with automated replacement +### Replaced / Restructured Fields `zarf dev convert` will automatically migrate these fields. @@ -163,10 +163,10 @@ These fields will error when `zarf dev convert` is run and recommend an alternat - `.components.[x].scripts` will be removed. This field is already deprecated and will be migrated to the existing `.components.[x].actions`. - `.metadata` fields `image`, `source`, `documentation`, `url`, `authors`, `vendors` will be removed. `zarf dev convert` will move these fields under `.metadata.annotations`, which is a generic map of strings. - `.components[x].actions.[onAny].wait.cluster` will receive a new required sub field, `.apiVersion`. During conversion `.apiVersion` will be added to the object but kept empty. Users will be warned that they must fill this field out, otherwise create will error. -- `.components.[x].healthChecks` will be removed and appended to `.components.[x].actions.[onAny].wait.cluster`. This will be accompanied by a behavior change in `zarf tools wait-for` to perform kstatus style readiness checks when `.wait.cluster.condition` is empty. See [Zarf Tools wait-for Changes](#zarf-tools-wait-for-changes). +- `.components.[x].healthChecks` will be removed and appended to `.components.[x].actions.onDeploy.After.wait.cluster`. This will be accompanied by a behavior change in `zarf tools wait-for` to perform kstatus style readiness checks when `.wait.cluster.condition` is empty. See [Zarf Tools wait-for Changes](#zarf-tools-wait-for-changes). - `.component.[x].charts` will be restructured to move fields into different sub-objects depending on the method of consuming the chart. See [Helm Chart Changes](#zarf-helm-chart-changes) -### Renamed fields +### Renamed Fields `zarf dev convert` will automatically migrate these fields. @@ -362,11 +362,11 @@ proposal will be implemented, this is the place to discuss that. ### Zarf Helm Chart Changes -The ZarfChart object will be restructured to match the code block below. Exactly one of sub-objects `helm`, `git`, `oci`, or `local` must exist for each `components.[x].charts`. The fields `localPath`, `gitPath`, `URL`, and `repoName` will be removed from the top level of `components.[x].charts`. See [#2245](https://github.com/defenseunicorns/zarf/issues/2245). +The ZarfChart object will be restructured to match the code block below. Exactly one of sub-objects `helm`, `git`, `oci`, or `local` is required for each entry in `components.[x].charts`. The fields `localPath`, `gitPath`, `URL`, and `repoName` will be removed from the top level of `components.[x].charts`. See [#2245](https://github.com/defenseunicorns/zarf/issues/2245). During conversion, Zarf will detect the method of consuming the chart and create the proper sub-objects. If a git repo is used then `@` + the `.version` value will be appended to `.gitRepoSource.URL`. This is consistent with the current Zarf behavior. -Zarf uses the top level `version` field to determine where in the package layout file structure it will place charts. This makes the field necessary for deploy, and therefore it must be carried over using the strategy defined in the removed fields section of [0048](https://github.com/zarf-dev/proposals/pull/49/files). Newer versions of Zarf will ensure that Zarf works whether or not `version` is set. Packages created with the v1beta1 schema will leave `version` empty, and therefore not work with earlier versions of Zarf. When support is dropped for v1alpha1 packages the `version` field will be dropped entirely. Note, this process is applied to internal conversion so that there is no change in behavior when v1alpha1 packages use function signatures that contain v1beta1 objects. `zarf dev convert` will simply move the top level `version` field to the right sub object, or drop it when not applicable. +Zarf uses the top level `version` field to determine where in the package layout file structure it will place charts. This makes the field necessary for deploy, and therefore it must be carried over using the strategy defined in the removed fields section of [0048](https://github.com/zarf-dev/proposals/pull/49/files). Newer versions of Zarf will ensure that Zarf works whether or not `version` is set. Packages created with the v1beta1 schema will leave `version` empty, and therefore not work with earlier versions of Zarf. When support is dropped for v1alpha1 packages the `version` field will be dropped entirely. Note, this process is applied to internal conversion so that there is no change in behavior when v1alpha1 packages use function signatures that contain v1beta1 objects. `zarf dev convert` will simply move the top level `version` field to the right sub object, or drop it when not applicable. ```go // ZarfChart defines a helm chart to be deployed. @@ -450,8 +450,6 @@ when drafting this test plan. existing tests to make this code solid enough prior to committing the changes necessary to implement this proposal. -There will be e2e tests for `zarf dev convert` from a v1alpha1 definition to a v1beta1 definition. - There will be e2e tests for creating, deploying, and publishing a v1beta1 package. As the schema nears towards GA, existing tests will shift to use the v1beta1 schema. ### Graduation Criteria From dffa7bd19d8b9a6bf3aface287aad6806d77f015 Mon Sep 17 00:00:00 2001 From: Austin Abro Date: Fri, 24 Oct 2025 09:10:05 -0400 Subject: [PATCH 27/30] improve grammar and flow Signed-off-by: Austin Abro --- 0051-v1beta1-schema/README.md | 40 +++++++++++++++++------------------ 1 file changed, 20 insertions(+), 20 deletions(-) diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md index 6a2c1a0..8c4bdc0 100644 --- a/0051-v1beta1-schema/README.md +++ b/0051-v1beta1-schema/README.md @@ -92,7 +92,7 @@ feedback and reduce unnecessary changes. [documentation style guide]: https://docs.zarf.dev/contribute/style-guide/ --> -Several fields in the v1alpha1 ZarfPackageConfig can be restructured to provide a more intuitive experience. Other fields that have a poor user experience and add unnecessary overhead to Zarf should be removed. A new schema version, v1beta1, provides the space to make these changes. +Several fields in the v1alpha1 ZarfPackageConfig can be restructured to provide a more intuitive experience. Other fields that have a poor user experience and add unnecessary overhead to Zarf should be removed. A new schema version, v1beta1, provides the opportunity to make these changes. ## Motivation @@ -142,13 +142,13 @@ desired outcome and how success will be measured. The "Design Details" section below is for the real nitty-gritty. --> -Zarf will determine the schema of the package definition using the existing optional field `apiVersion`. If `apiVersion` is not set then Zarf will assume it is a v1alpha1 package. Users will be able to automatically upgrade their package to the v1beta1 schema by running `zarf dev convert`. +Zarf will determine the schema of the package definition using the existing optional field `apiVersion`. If `apiVersion` is not set, then Zarf will assume it is a v1alpha1 package. Users will be able to automatically upgrade their package to the v1beta1 schema by running `zarf dev convert`. The v1beta1 schema will remove, replace, and rename several fields. ### Removed Fields -These fields will error when `zarf dev convert` is run and recommend an alternative method to achieve the desired behavior. +If a package has these fields defined then `zarf dev convert` will error with and print a recommendation for an alternative. - `.components.[x].group` will be removed. Users will be recommended to use `components[x].only.flavor` instead. - `.components.[x].dataInjections` will be removed. There will be a guide in Zarf's documentation for alternatives. See [#3926](https://github.com/zarf-dev/zarf/issues/3926). @@ -160,9 +160,9 @@ These fields will error when `zarf dev convert` is run and recommend an alternat - `.components.[x].actions.[onAny].onSuccess` will be removed. Any `onSuccess` actions will be appended to the `actions.[onAny].after` list. - `.components[x].actions.[onAny].setVariable` will be removed. This field is already deprecated and will be migrated to the existing field `.components[x].actions.[onAny].setVariables`. -- `.components.[x].scripts` will be removed. This field is already deprecated and will be migrated to the existing `.components.[x].actions`. +- `.components.[x].scripts` will be removed. This field is already deprecated and will be migrated to the existing field `.components.[x].actions`. - `.metadata` fields `image`, `source`, `documentation`, `url`, `authors`, `vendors` will be removed. `zarf dev convert` will move these fields under `.metadata.annotations`, which is a generic map of strings. -- `.components[x].actions.[onAny].wait.cluster` will receive a new required sub field, `.apiVersion`. During conversion `.apiVersion` will be added to the object but kept empty. Users will be warned that they must fill this field out, otherwise create will error. +- `.components[x].actions.[onAny].wait.cluster` will receive a new required sub field, `.apiVersion`. During conversion, `.apiVersion` will be added to the object but kept empty. Users will be warned that they must fill this field out, otherwise create will error. - `.components.[x].healthChecks` will be removed and appended to `.components.[x].actions.onDeploy.After.wait.cluster`. This will be accompanied by a behavior change in `zarf tools wait-for` to perform kstatus style readiness checks when `.wait.cluster.condition` is empty. See [Zarf Tools wait-for Changes](#zarf-tools-wait-for-changes). - `.component.[x].charts` will be restructured to move fields into different sub-objects depending on the method of consuming the chart. See [Helm Chart Changes](#zarf-helm-chart-changes) @@ -170,12 +170,12 @@ These fields will error when `zarf dev convert` is run and recommend an alternat `zarf dev convert` will automatically migrate these fields. -- `.metadata.aggregateChecksum` will move to `.build.aggregateChecksum` -- `.metadata.yolo` will be renamed to `.metadata.airgap`. `airgap` will default to true -- `.components[x].required` will be renamed to `.components[x].optional`. `optional` will default to false. Since `required` currently defaults to false, components now default to being required by default. +- `.metadata.aggregateChecksum` will move to `.build.aggregateChecksum`. +- `.metadata.yolo` will be renamed to `.metadata.airgap`. `airgap` will default to true. +- `.components[x].required` will be renamed to `.components[x].optional`. `optional` will default to false. Since `required` currently defaults to false, components will now default to being required. - `noWait` will be renamed to `wait`. `wait` will default to true. This change will happen on both `.components.[x].manifests` and `.components.[x].charts`. -- `.components.[x].actions.[default/onAny].maxRetries` will be renamed to `.components.[x].actions.[default/onAny].retries` -- `.components.[x].actions.[default/onAny].maxTotalSeconds` will be renamed to `.components.[x].actions.[default/onAny].timeout`, which must be in a [Go recognized duration string format](https://pkg.go.dev/time#ParseDuration) +- `.components.[x].actions.[default/onAny].maxRetries` will be renamed to `.components.[x].actions.[default/onAny].retries`. +- `.components.[x].actions.[default/onAny].maxTotalSeconds` will be renamed to `.components.[x].actions.[default/onAny].timeout`, which must be in a [Go recognized duration string format](https://pkg.go.dev/time#ParseDuration). ### User Stories (Optional) @@ -230,7 +230,7 @@ components: - values.yaml ``` -I want to upgrade to the v1beta1 schema so I run `zarf dev convert`, which produces: +I want to upgrade to the v1beta1 schema, so I run `zarf dev convert`, which produces: ```yaml apiVersion: v1beta1 @@ -305,7 +305,7 @@ components: kind: Pod ``` -I want to move to the latest schema so I run `zarf dev convert`, which produces: +I want to move to the latest schema, so I run `zarf dev convert`, which produces: ```yaml apiVersion: v1beta1 @@ -349,7 +349,7 @@ How will UX be reviewed, and by whom? The field `.components.[x].dataInjections` will be removed without a direct replacement in the schema. There must be documentation to present to users so they know what alternatives they can use to achieve a similar result. -The alpha field `.components.[x].charts.[x].variables` has seen significant adoption and there will be no automatic conversion to it's replacement Zarf values. There must be documentation on how users can utilize Zarf values as an alternative to chart variables. +The alpha field `.components.[x].charts.[x].variables` has seen significant adoption and there will be no automatic conversion to its replacement Zarf values. There must be documentation on how users can utilize Zarf values as an alternative to chart variables. ## Design Details @@ -364,9 +364,9 @@ proposal will be implemented, this is the place to discuss that. The ZarfChart object will be restructured to match the code block below. Exactly one of sub-objects `helm`, `git`, `oci`, or `local` is required for each entry in `components.[x].charts`. The fields `localPath`, `gitPath`, `URL`, and `repoName` will be removed from the top level of `components.[x].charts`. See [#2245](https://github.com/defenseunicorns/zarf/issues/2245). -During conversion, Zarf will detect the method of consuming the chart and create the proper sub-objects. If a git repo is used then `@` + the `.version` value will be appended to `.gitRepoSource.URL`. This is consistent with the current Zarf behavior. +During conversion, Zarf will detect the method of consuming the chart and create the proper sub-objects. If a git repo is used, then `@` + the `.version` value will be appended to `.gitRepoSource.URL`. This is consistent with the current Zarf behavior. -Zarf uses the top level `version` field to determine where in the package layout file structure it will place charts. This makes the field necessary for deploy, and therefore it must be carried over using the strategy defined in the removed fields section of [0048](https://github.com/zarf-dev/proposals/pull/49/files). Newer versions of Zarf will ensure that Zarf works whether or not `version` is set. Packages created with the v1beta1 schema will leave `version` empty, and therefore not work with earlier versions of Zarf. When support is dropped for v1alpha1 packages the `version` field will be dropped entirely. Note, this process is applied to internal conversion so that there is no change in behavior when v1alpha1 packages use function signatures that contain v1beta1 objects. `zarf dev convert` will simply move the top level `version` field to the right sub object, or drop it when not applicable. +Zarf uses the top level `version` field to determine where in the package layout file structure it will place charts. This makes the field necessary for deploy, and therefore it must be carried over using the strategy defined in the removed fields section of [0048](https://github.com/zarf-dev/proposals/pull/49/files). Newer versions of Zarf will ensure that Zarf works whether or not `version` is set. Packages created with the v1beta1 schema will leave `version` empty, and therefore will not work with earlier versions of Zarf. When support is dropped for v1alpha1 packages, the `version` field will be dropped entirely. Note, this process is applied to internal conversion so that there is no change in behavior when v1alpha1 packages use function signatures that contain v1beta1 objects. `zarf dev convert` will simply move the top level `version` field to the right sub object, or drop it when not applicable. ```go // ZarfChart defines a helm chart to be deployed. @@ -429,7 +429,7 @@ type OCISource struct { #### Zarf Tools wait-for Changes -`zarf tools wait-for` is the underlying engine to `.wait.cluster`. Currently, `zarf tools wait-for` shells out to `zarf tools kubectl wait`. In the future, `wait-for` will optionally accept an API version alongside the resource kind. If API version is set, and condition is empty then kstatus will be used as `wait-for`'s engine. +`zarf tools wait-for` is the underlying engine to `.wait.cluster`. Currently, `zarf tools wait-for` shells out to `zarf tools kubectl wait`. In the future, `wait-for` will optionally accept an API version alongside the resource kind. If API version is set and condition is empty, then kstatus will be used as `wait-for`'s engine. v1alpha1 packages do not have `.apiVersion` as a sub field under `.wait.cluster`, so they will always use the existing engine, avoiding breaking changes. v1beta1 packages will require that `apiVersion` is set. @@ -476,12 +476,12 @@ If this feature will eventually be deprecated, plan for it: - Wait at least two versions before fully removing it. --> -- Alpha: fields are subject to change or rename. No backwards compatibility guarantees. +- Alpha: Fields are subject to change or rename. No backwards compatibility guarantees. - Beta: Fields will not change in a way that is not fully backwards compatible. - GA: Users have provided feedback that the new schema improves the UX. Examples and tests in Zarf shift to using the v1beta1 schema. Deprecation: -- This schema will likely be deprecated one day in favor of a v1 schema. It will not be deprecated until after the next schema version generally available. Once deprecated, Zarf will still support the v1beta1 schema for at least one year. +- This schema will likely be deprecated one day in favor of a v1 schema. It will not be deprecated until after the next schema version is generally available. Once deprecated, Zarf will still support the v1beta1 schema for at least one year. ### Upgrade / Downgrade Strategy @@ -499,7 +499,7 @@ proposal: make use of the proposal? --> -See proposal in ZEP-0048 +See proposal in ZEP-0048. ### Version Skew Strategy @@ -513,7 +513,7 @@ proposal: - (i.e. the Zarf Agent and CLI? The init package and the CLI?) --> -See version skew strategy in ZEP-0048 +See version skew strategy in ZEP-0048. ## Implementation History From 9e27b3b1ec60be5105f1444256ef886ac589bb92 Mon Sep 17 00:00:00 2001 From: Austin Abro Date: Fri, 24 Oct 2025 11:47:00 -0400 Subject: [PATCH 28/30] add that default is removed Signed-off-by: Austin Abro --- 0051-v1beta1-schema/README.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md index 8c4bdc0..cdc1928 100644 --- a/0051-v1beta1-schema/README.md +++ b/0051-v1beta1-schema/README.md @@ -150,9 +150,10 @@ The v1beta1 schema will remove, replace, and rename several fields. If a package has these fields defined then `zarf dev convert` will error with and print a recommendation for an alternative. -- `.components.[x].group` will be removed. Users will be recommended to use `components[x].only.flavor` instead. +- `.components.[x].group` will be removed. Users will be recommended to use `components[x].only.flavor` instead. - `.components.[x].dataInjections` will be removed. There will be a guide in Zarf's documentation for alternatives. See [#3926](https://github.com/zarf-dev/zarf/issues/3926). - `.components.[x].charts.[x].variables` will be removed. Its successor is [Zarf values](../0021-zarf-values/), but there will be no automated migration with `zarf dev convert`. +- `.component.[x].default` will be removed. It set the default option for groups and (y/n) interactive prompts for optional components. Groups are removed, and we've generally seen the user base shift away from optional components. ### Replaced / Restructured Fields @@ -270,7 +271,7 @@ components: - name: podinfo-repo namespace: podinfo-from-repo - helm: + helmRepo: url: https://stefanprodan.github.io/podinfo name: podinfo # Changed from `repoName` version: 6.4.0 @@ -362,7 +363,7 @@ proposal will be implemented, this is the place to discuss that. ### Zarf Helm Chart Changes -The ZarfChart object will be restructured to match the code block below. Exactly one of sub-objects `helm`, `git`, `oci`, or `local` is required for each entry in `components.[x].charts`. The fields `localPath`, `gitPath`, `URL`, and `repoName` will be removed from the top level of `components.[x].charts`. See [#2245](https://github.com/defenseunicorns/zarf/issues/2245). +The ZarfChart object will be restructured to match the code block below. Exactly one of sub-objects `helmRepo`, `git`, `oci`, or `local` is required for each entry in `components.[x].charts`. The fields `localPath`, `gitPath`, `URL`, and `repoName` will be removed from the top level of `components.[x].charts`. See [#2245](https://github.com/defenseunicorns/zarf/issues/2245). During conversion, Zarf will detect the method of consuming the chart and create the proper sub-objects. If a git repo is used, then `@` + the `.version` value will be appended to `.gitRepoSource.URL`. This is consistent with the current Zarf behavior. @@ -376,7 +377,7 @@ type ZarfChart struct { // The version of the chart. This field is removed for the schema, but kept as a backwards compatibility shim so v1alpha1 packages can be converted to v1beta1 version string // The Helm repo where the chart is stored - Helm HelmRepoSource `json:"helm,omitempty"` + HelmRepo HelmRepoSource `json:"helmRepo,omitempty"` // The Git repo where the chart is stored Git GitRepoSource `json:"git,omitempty"` // The local path where the chart is stored From 8772404265f456a3334956acec8798767923b48e Mon Sep 17 00:00:00 2001 From: Austin Abro Date: Fri, 24 Oct 2025 11:50:06 -0400 Subject: [PATCH 29/30] package definition Signed-off-by: Austin Abro --- 0051-v1beta1-schema/README.md | 2 +- 0051-v1beta1-schema/zarf.yaml | 443 ++++++++++++++++++++++++++++++++++ 2 files changed, 444 insertions(+), 1 deletion(-) create mode 100644 0051-v1beta1-schema/zarf.yaml diff --git a/0051-v1beta1-schema/README.md b/0051-v1beta1-schema/README.md index cdc1928..02ba76a 100644 --- a/0051-v1beta1-schema/README.md +++ b/0051-v1beta1-schema/README.md @@ -144,7 +144,7 @@ below is for the real nitty-gritty. Zarf will determine the schema of the package definition using the existing optional field `apiVersion`. If `apiVersion` is not set, then Zarf will assume it is a v1alpha1 package. Users will be able to automatically upgrade their package to the v1beta1 schema by running `zarf dev convert`. -The v1beta1 schema will remove, replace, and rename several fields. +The v1beta1 schema will remove, replace, and rename several fields. View this [zarf.yaml](zarf.yaml) to see a package definition with reasonable values for each key. ### Removed Fields diff --git a/0051-v1beta1-schema/zarf.yaml b/0051-v1beta1-schema/zarf.yaml new file mode 100644 index 0000000..474658e --- /dev/null +++ b/0051-v1beta1-schema/zarf.yaml @@ -0,0 +1,443 @@ +kind: ZarfPackageConfig +apiVersion: v1beta1 +metadata: + name: everything-zarf-package + description: A zarf package with a non empty value for every key - this demonstrates the changes proposed by ZEP-0051 + version: v1.0.0 + uncompressed: false + architecture: amd64 + airgap: true # changed from yolo + annotations: # All of these are v0 fields that will be deprecated in favor of a choose your own adventure label map + authors: cool-kidz + documentation: https://my-package-documentation.com + source: https://my-git-server/my-package + url: https://my-package-website.com + vendor: my-vendor + image: https://my-image-url-to-use-in-deprecated-zarf-ui + anyway-you-want-it: thats-the-way-you-need-it + allowNamespaceOverride: true +build: # Everything here is created by Zarf not be users + terminal: my-computer + user: my-user + architecture: amd64 + timestamp: 2021-09-01T00:00:00Z + version: v1.0.0 + migrations: + - scripts-to-actions + versionRequirements: + - version: 0.65.0 + reason: "the package structure of Helm charts changed" + registryOverrides: + gcr.io: my-gcr.com + differential: true + differentialPackageVersion: "v0.99.9" + differentialMissing: + - missing-component + flavor: cool-flavor + lastNonBreakingVersion: "v0.99.9" + aggregateChecksum: shasum # this is moved from .metadata +values: + files: + - values.yaml + schema: values-schema.json +components: +- name: a-component + description: Zarf description + optional: false # Component is required (default behavior) + only: + localOS: darwin + cluster: + architecture: amd64 + distros: + - ubuntu + flavor: a-flavor # this will only be used when there are multiple components + import: + name: other-component-name + path: ABCD # Only path or URL will be used, not both + url: oci:// + manifests: + - name: manifest + namespace: manifest-ns + files: + - a-file.yaml + kustomizeAllowAnyDirectory: false + kustomizations: + - a-kustomization.yaml + wait: false + template: true # Enable go-template processing + charts: + - name: chart + namespace: chart-ns + releaseName: chart-release + wait: true + valuesFiles: + - values.yaml + values: + - sourcePath: ".app.name" + targetPath: ".appName" + schemaValidation: true + helmRepo: # Only one of helm, git, oci, url, or local is allowed + url: https://stefanprodan.github.io/podinfo + name: podinfo # replaces repoName since it's only applicable in this situation + version: 6.4.0 + git: + url: https://stefanprodan.github.io/podinfo + path: charts/podinfo + oci: + url: oci://ghcr.io/stefanprodan/charts/podinfo + version: 6.4.0 + local: + path: chart + files: + - source: source-file.txt + target: target-file.txt + shasum: shasum + executable: false + symlinks: + - /path/to/symlink + extractPath: /path/to/extract + template: false # Disable go-template processing for this file + images: + - podinfo@v1 + repos: + - https://github.com/defenseunicorns/zarf + actions: + onCreate: + defaults: + mute: true + timeout: 1m + retries: 0 + dir: dir + env: + - ENV_VAR=FOO + shell: + darwin: sh + linux: sh + windows: powershell + before: + - mute: false + timeout: 1m + retries: 0 + dir: dir + env: + - ENV_VAR=FOO + cmd: echo hello + shell: + darwin: sh + linux: sh + windows: powershell + setVariables: + - name: VAR + sensitive: false + autoIndent: true + pattern: ".+" + type: raw + setValues: + - key: .json + description: action-description + wait: + cluster: # Only one of cluster / network can be used + apiVersion: v1 + kind: pod + name: my-pod + namespace: pod-ns + condition: ready + network: + protocol: http + address: github.com + code: 200 + after: + - mute: false + timeout: 1m + retries: 0 + dir: dir + env: + - ENV_VAR=FOO + cmd: echo hello + shell: + darwin: sh + linux: sh + windows: powershell + setVariables: + - name: VAR + sensitive: false + autoIndent: true + pattern: ".+" + type: raw + setValues: + - key: .json + description: action-description + wait: + cluster: # Only one of cluster / network can be used + apiVersion: v1 + kind: pod + name: my-pod + namespace: pod-ns + condition: ready + network: + protocol: http + address: github.com + code: 200 + onFailure: + - mute: false + timeout: 1m + retries: 0 + dir: dir + env: + - ENV_VAR=FOO + cmd: echo hello + shell: + darwin: sh + linux: sh + windows: powershell + setVariables: + - name: VAR + sensitive: false + autoIndent: true + pattern: ".+" + type: raw + setValues: + - key: .json + description: action-description + wait: + cluster: # Only one of cluster / network can be used + apiVersion: v1 + kind: pod + name: my-pod + namespace: pod-ns + condition: ready + network: + protocol: http + address: github.com + code: 200 + onDeploy: + defaults: + mute: true + timeout: 1m + retries: 0 + dir: dir + env: + - ENV_VAR=FOO + shell: + darwin: sh + linux: sh + windows: powershell + before: + - mute: false + timeout: 1m + retries: 0 + dir: dir + env: + - ENV_VAR=FOO + cmd: echo hello + shell: + darwin: sh + linux: sh + windows: powershell + setVariables: + - name: VAR + sensitive: false + autoIndent: true + pattern: ".+" + type: raw + setValues: + - key: .json + description: action-description + wait: + cluster: # Only one of cluster / network can be used + apiVersion: v1 + kind: pod + name: my-pod + namespace: pod-ns + condition: ready + network: + protocol: http + address: github.com + code: 200 + after: + - mute: false + timeout: 1m + retries: 0 + dir: dir + env: + - ENV_VAR=FOO + cmd: echo hello + shell: + darwin: sh + linux: sh + windows: powershell + setVariables: + - name: VAR + sensitive: false + autoIndent: true + pattern: ".+" + type: raw + setValues: + - key: .json + description: action-description + wait: + cluster: # Only one of cluster / network can be used + apiVersion: v1 + kind: pod + name: my-pod + namespace: pod-ns + condition: ready + network: + protocol: http + address: github.com + code: 200 + onFailure: + - mute: false + timeout: 1m + retries: 0 + dir: dir + env: + - ENV_VAR=FOO + cmd: echo hello + shell: + darwin: sh + linux: sh + windows: powershell + setVariables: + - name: VAR + sensitive: false + autoIndent: true + pattern: ".+" + type: raw + setValues: + - key: .json + description: action-description + wait: + cluster: # Only one of cluster / network can be used + apiVersion: v1 + kind: pod + name: my-pod + namespace: pod-ns + condition: ready + network: + protocol: http + address: github.com + code: 200 + onRemove: + defaults: + mute: true + timeout: 1m + retries: 0 + dir: dir + env: + - ENV_VAR=FOO + shell: + darwin: sh + linux: sh + windows: powershell + before: + - mute: false + timeout: 1m + retries: 0 + dir: dir + env: + - ENV_VAR=FOO + cmd: echo hello + shell: + darwin: sh + linux: sh + windows: powershell + setVariables: + - name: VAR + sensitive: false + autoIndent: true + pattern: ".+" + type: raw + setValues: + - key: .json + description: action-description + wait: + cluster: # Only one of cluster / network can be used + apiVersion: v1 + kind: pod + name: my-pod + namespace: pod-ns + condition: ready + network: + protocol: http + address: github.com + code: 200 + after: + - mute: false + timeout: 1m + retries: 0 + dir: dir + env: + - ENV_VAR=FOO + cmd: echo hello + shell: + darwin: sh + linux: sh + windows: powershell + setVariables: + - name: VAR + sensitive: false + autoIndent: true + pattern: ".+" + type: raw + setValues: + - key: .json + description: action-description + wait: + cluster: # Only one of cluster / network can be used + apiVersion: v1 + kind: pod + name: my-pod + namespace: pod-ns + condition: ready + network: + protocol: http + address: github.com + code: 200 + onFailure: + - mute: false + timeout: 1m + retries: 0 + dir: dir + env: + - ENV_VAR=FOO + cmd: echo hello + shell: + darwin: sh + linux: sh + windows: powershell + setVariables: + - name: VAR + sensitive: false + autoIndent: true + pattern: ".+" + type: raw + setValues: + - key: .json + description: action-description + wait: + cluster: # Only one of cluster / network can be used + apiVersion: v1 + kind: pod + name: my-pod + namespace: pod-ns + condition: ready + network: + protocol: http + address: github.com + code: 200 +constants: +- name: CONSTANT + value: constant-value + description: constant-value + autoIndent: false + pattern: ".+" +variables: +- name: VAR + sensitive: false + autoIndent: true + pattern: ".+" + type: raw + description: var + default: whatever + prompt: false From 265b8bace51b0cf3b967cb584ab806c358fdcb66 Mon Sep 17 00:00:00 2001 From: Austin Abro Date: Tue, 28 Oct 2025 09:16:46 -0400 Subject: [PATCH 30/30] update build Signed-off-by: Austin Abro --- 0051-v1beta1-schema/zarf.yaml | 3 --- 1 file changed, 3 deletions(-) diff --git a/0051-v1beta1-schema/zarf.yaml b/0051-v1beta1-schema/zarf.yaml index 474658e..6323b57 100644 --- a/0051-v1beta1-schema/zarf.yaml +++ b/0051-v1beta1-schema/zarf.yaml @@ -31,10 +31,7 @@ build: # Everything here is created by Zarf not be users gcr.io: my-gcr.com differential: true differentialPackageVersion: "v0.99.9" - differentialMissing: - - missing-component flavor: cool-flavor - lastNonBreakingVersion: "v0.99.9" aggregateChecksum: shasum # this is moved from .metadata values: files: