Create a Package

The following diagram shows the order of operations for the zarf package create command and the hook locations for actions.

Lifecycle Diagram

graph TD A1(set working directory)-->A2 A2(parse zarf.yaml)-->A3 A3(filter components by architecture)-->A4 A4(detect init package)-->A5 A5(handle deprecations)-->A6 A6(parse component imports)-->A8 A8(write build data and zarf.yaml)-->A9 A9(run validations)-->A10 A10(confirm package create):::prompt-->A11 A11{Init package?} A11 -->|Yes| A12(add seed image)-->A13 A11 -->|No| A13 subgraph "" A13(add each component)-->A13 A13 --> A14(run each '.actions.onCreate.before'):::action-->A14 A14 --> A15(load '.charts')-->A16 A16(load '.files')-->A17 A17(load '.dataInjections')-->A18 A18(load '.manifests')-->A19 A19(load '.repos')-->A20 A20(run each '.actions.onCreate.after'):::action-->A20 A20-->A21{Success?} A21-->|Yes|A22(run each '.actions.onCreate.success'):::action-->A22 A21-->|No|A23(run each '.actions.onCreate.failure'):::action-->A23-->A999 end A22-->A24(load all '.images') A24-->A25{Skip SBOM?} A25-->|Yes|A27 A25-->|No|A26 A26(generate SBOM)-->A27 A27(reset working directory)-->A28 A28(create package archive)-->A29 A29{Is multipart?} A29-->|Yes|A30(split package archive)-->A31 A29-->|No|A31 A31(handle sbom-out flag) A999[Abort]:::fail classDef prompt fill:#4adede,color:#000000 classDef action fill:#bd93f9,color:#000000 classDef fail fill:#aa0000

Package Templates

Use zarf dev template to render a package or component definition before creating a package. Templates use Go template syntax with [[ and ]] delimiters. The rendered definition is included in the package, so its template values cannot be changed after creation.

For example, save this definition as zarf.tpl.yaml:

apiVersion: zarf.dev/v1beta1
kind: ZarfPackageConfig
metadata:
  name: app
  version: "[[ .VERSION ]]"
components:
  - name: app
    images:
      - name: "[[ .IMAGE ]]"

Render the template and create the package from the generated definition:

zarf dev template --set VERSION=1.0.0 --set IMAGE=ghcr.io/example/app:1.0.0
zarf package create zarf.gen.yaml

You can also provide a YAML mapping with --set-file template-values.yaml. Values passed with --set take precedence over the file. Template keys are case-sensitive, and missing values cause an error. Rendering validates the generated definition and writes it alongside the template with a .gen.yaml suffix.

Render local component templates separately and use their generated paths in import.local[].path. Render remote components before publishing them.

Do not put sensitive data in package templates: rendered values are stored in the package. For configuration supplied at deploy time, see Package Values.

Differential Packages

The --differential flag accepts another Zarf package (local or OCI) as a reference. Images and Git repositories that exist in both packages are excluded from the new package, reducing its size. This is especially useful in environments where large data transfers are costly or time-consuming. View the Differential Package Tutorial for an example.