Introduce a command to enable end-users to inspect package contents. This will be implemented as the zarf package inspect command, with five subcommands: definition, sbom, images, manifests, and values-files. All the commands will work with an existing package, whether local or remote.
Additionally, introduce a command for developers to preview a package during implementation. This will be achieved through the zarf dev inspect command, with three subcommands: definition, sbom and values-files. These commands will accept a directory containing a zarf.yaml file.
Users need an easier way to view their package definition after it's rendered by Zarf, but before zarf package create. A rendered package definition has had templating, imports, and flavors applied. The only path to view the rendered package definition is running zarf package create and viewing the printed yaml before the (y/n) prompt. Having a separate command, zarf dev inspect definition, improves the UX by providing users with an easier way to view the rendered package definition. It also opens the possibility of allowing zarf package create to proceed without requiring user confirmation.
Viewing manifests and values files after Zarf variable templating would be useful for both creators and deployers. Catching a mistake in templating early can save time. A Helm template is almost instant, whereas create + deploy could take several minutes to hours.
A user can achieve a similar effect to zarf package inspect manifests by decompressing their package and running helm template on their chart. Not only is this a poor UX, but the helm template may fail depending on where Zarf variable templating is used within the chart.
Features relating to these problems have been highly requested in recent months:
- Request in Kubernetes Slack - https://kubernetes.slack.com/archives/C03B6BJAUJ3/p1730229638367829
- An issue has been created for this - zarf-dev/zarf#2631
- Defense Unicorns, an organization that relies heavily on Zarf for their deployments, has received requests to view manifests in a feedback session with their partners.
- View manifests or values files after Zarf variable templating and Helm templating have been applied.
- View rendered package definition before creation
- Accept a cluster source of the package for new functionality. Cluster source will continue to work for
zarf package inspect definitionandzarf package inspect images, but not forzarf package inspect sbom,zarf package inspect manifests, orzarf package inspect values-files - Print out multiple types of inspects in the same command. A user will not be able to print out the package definition and manifests in the same command.
- Support directly opening the SBOM in browser
The newly added commands will not have a confirmation flag and will not prompt for optional components, package templates, or package variables. Users will be able to specify these values using flags, when applicable. None of these commands will run any Zarf actions.
zarf package inspect will be deprecated and replaced by the five commands below.
Displays the zarf.yaml definition of the given package. Will accept a package in the cluster in addition to local or OCI packages. This will mirror behavior of the current zarf package inspect <package> command.
Lists the images of the specified package. Will accept a package in the cluster in addition to local or OCI packages. This will mirror behavior of the current zarf package inspect <package> --list-images command
Extracts the package SBOM into the specified directory. If no directory is specified it will default to the current directory. This will mirror behavior of the current zarf package inspect <package> --sbom-out command. Note that the zarf package inspect <package> --sbom flag which opens the sbom in browser will be removed without replacement.
Templates Helm charts and displays all Kubernetes manifests. Accepts package variables and components as flags.
Prints the values files of Helm charts. Accepts package variables and components as flags.
A new command zarf dev inspect will be introduced with the three subcommands specified below.
Displays the 'zarf.yaml' definition after flavors, templating, and component imports are applied.
Templates Helm charts and displays all Kubernetes manifests. Accepts package templates, package variables, flavors, and components as flags.
Prints the values files of Helm charts. Accepts package templates, package variables, flavors, and components as flags.
As a creator of Zarf packages, I want to make sure that the variables in my package are properly rendered with the expected values. I want to check this for both manifests and values files.
As a deployer of Zarf packages, I want to make sure that the variables in my package are properly rendered for both manifests and values files before I deploy.
As a creator of Zarf packages I want to see what my package definition will look like after templates, imports, and flavors are applied.
The inspect manifest and inspect values-files commands could print Zarf variables with the sensitive key set to true. Zarf variables are set using values that a user already has access to: user input or configuration files. Given that these commands are expected to be run by a user developing a package or preparing for a deployment and not in an automated system, we deem these risks acceptable.
For the inspect manifests commands, before printing the manifests of each chart, the name and version of the chart will be printed. Before printing Manifests from the .components[x].manifests key the name of the manifests block, .components[x].manifests[x].name, will be printed.
All of these commands, besides zarf package inspect sbom, will provide a user with text output. The output will go to stdout, while all other logs will go to stderr.
For commands printing deployment variables Internal variables will be set using the default logic except for sensitive values which do not have defaults. Sensitive values will be set to "PLACEHOLDER" instead. For example, the ZARF_REGISTRY variable becomes 127.0.0.1:31999, while ZARF_GIT_AUTH_PUSH will be set to "PLACEHOLDER". This is done to ensure that these commands can run without requiring a connection to a cluster.
The following commands will accept a --components flag: zarf package inspect manifests, zarf package inspect values-files, zarf dev inspect manifests, and zarf dev inspect values-files. If --components is not used these commands will print out the requested resource from all components.
Any commands running a Helm template will accept a --kube-version flag. This is to avoid situations where the chart KubeVersion field doesn't match the kube version field in Zarf which prevents templating.
[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.
Given the simplicity of this feature, unit tests will be adequate.
These new commands will be implemented directly in a stable state. The commands are simple to test, do not interact with a Kubernetes cluster, and do not have state to track between runs.
The current zarf package inspect command will become deprecated, after a year it will be removed. In cobra, when a command is added as a child command it will take priority over the parent command. For example, if a user calls zarf package inspect images <my-package.tar.zst> it will call the child images command, however if a user calls zarf package inspect <my-package.tar.zst> Cobra will call the parent command. Zarf will use the behavior to introduce the new commands, and leave a deprecation note on the zarf package inspect command.
The only functionality of zarf package inspect that will be removed instead of deprecated is the --sbom flag, which opens an HTML viewer of the SBOM in the browser. Users can instead run zarf package inspect sbom and then point their browser to the HTML file in their filesystem. Removing this option keeps the zarf package inspect sbom command simple.
N/A
- 2024-12-04: Document created
- 2025-01-15: Rework proposal, squashing with ZEP-0006 introduce zarf package preview
Since zarf package inspect and zarf dev inspect have different roots they may not be immediately discoverable. It's easy to imagine a user who doesn't know about zarf dev inspect so they build their package each time before running zarf package inspect. Still, zarf dev find-images has had significant usage from community members so it's reasonable to expect users to find commands under the dev root. In the future, we could provide tutorials going over different situations where these commands may be useful.
zarf package inspect <package.tar.zst> inspect will remain usable, but deprecated for a year until it's removed, see Upgrade / Downgrade Strategy. Given that the zarf package inspect command is not a part of the core flow, and likely not often used in automated systems, we considered removing it right away. However, given the low anticipated maintenance cost of keeping the command around, we decided to institute a deprecation process
There are several different ways this command could be structured differently.
zarf package inspectwith flags for the different commands such aszarf package inspect --manifestsorzarf package inspect --images. The issue here is that many flags would apply to some commands and not others. For example,--kube-versionand--setare relevant tozarf package inspect manifestsand values-files but irrelevant tozarf package inspect images. By separating the commands it becomes clear which flags apply to which resources.zarf package show manifests [PACKAGE|DIRECTORY]andzarf package show values-files [PACKAGE|DIRECTORY]. This limits the amount of new commands and reads well. However, we wanted to avoid commands accepting either a package, directory, or OCI source. We felt the multiple possible sources would not be intuitive. Additionally, the resulting commands would have flags that would apply to packages, but not apply to directories and vice versa.zarf dev show manifests [DIRECTORY],zarf dev show values-files [DIRECTORY],zarf package show manifests [PACKAGE], andzarf package show values-files [PACKAGE]. This would make the commands less overloaded as they wouldn't take either a package or a directory. It also would ensure every flag is relevant. For example, the--create-setand--flavorwould only exist for thedevcommands. However, This increases the surface area of the CLI with four new commands. Additionally, sincezarf dev show manifestsandzarf package show manifestshave different parent commands they would be less discoverable than if under the same parent.