Skip to content
Zarf

Zarf v1.0.0

Introduction

Zarf is happy to announce v1.0.0. This milestone marks our commitment to stable releases, backward compatibility, and long-term support.

v1beta1 Package Schema

A package schema defines the fields and structure of the zarf.yaml package definition. Zarf v1.0.0 introduces a new version of that format, v1beta1. It introduces reusable published components and a dedicated templating workflow. The new format removes several deprecated features from the existing schema, v1alpha1. The v1beta1 schema provides a migration path for each removed feature, improving usability, security, or performance. The v1alpha1 to v1beta1 migration guide provides a detailed list of changes and instructions for updating existing package definitions.

v1alpha1 Deprecation

The legacy package schema, v1alpha1, is deprecated in v1.0.0. However, we know there are countless existing v1alpha1 packages supporting many critical systems across the world. To give users time to migrate, we are providing an extended deprecation period. Zarf will support v1alpha1 packages through May 2027, six months after the v1.0.0 release in November 2026.

With the release of v1.0.0, Zarf will log a warning when v1alpha1 packages are used. Starting in February 2027, create-time operations such as package create, publish, and sign will require --features=v1alpha1=true for continued use. Deploy-time operations will require the feature flag starting in March 2027.

  1. v1alpha1 Deprecated
  2. Create-time opt-in
  3. Deploy-time opt-in
  4. Support ends

Package removal will continue to work without a feature flag until v1alpha1 is fully unsupported.

Init Package

The default init package has migrated to v1beta1. Note that deployment must be configured through values instead of variables. You can read the migration guide using zarf package inspect attachments --keys=migration or in MIGRATION.md.

The flag --storage-class has been removed from zarf init. The storage class can be configured through registry.persistence.storageClass and gitServer.persistence.storageClass. New deployments now use the cluster’s default storage class. Previously, Zarf assigned a default storage class based on the Kubernetes distribution. Upgrades continue to use the existing storage class.

Deployed Package State

Starting in v1.0, deployed package secrets contain deploy configuration and more granular deployment status. This information will enable additional features described by the Enhanced State Management ZEP. Failure to write package state will now cause deployment to fail. To prevent oversized secret write failures, secrets are now gzip-compressed.

Zarf versions before v1.0 cannot read the gzipped secrets created by v1.0 and later, which can cause failures when accessing deployed packages.

Removed Features

Notable features removed in v1.0.0:

  • The Zarf artifact server, which used Gitea to store artifacts such as npm packages, was removed due to limited adoption.
  • zarf tools registry export: Removed as registry commands focus on generic OCI operations, and container image exports were outside this scope.
  • The SBOM viewer: Zarf no longer produces HTML files for human-friendly SBOM reading.
  • Older Docker engine compatibility: Pulling images from a local Docker daemon now requires Docker Engine 25.0.0 or later.