Skip to content

Commit b7a2a54

Browse files
brandtkellerbrandtkeller
committed
feat(inspect): add inspect module
Signed-off-by: Brandt Keller <brandt.keller@defenseunicorns.com>
1 parent b209a71 commit b7a2a54

3 files changed

Lines changed: 172 additions & 9 deletions

File tree

‎02-deploy-zarf-package/README.md‎

Lines changed: 1 addition & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -61,13 +61,6 @@ zarf tools kubectl port-forward -n argocd service/argocd-server 42000:80
6161
Then open your browser to [http://localhost:42000](http://localhost:42000).
6262

6363

64-
## Conclusion
65-
66-
You've built and deployed a complete Zarf package end-to-end. From here, Zarf has a lot more to offer for air-gapped software delivery:
67-
68-
- Browse the [Zarf examples](https://github.com/zarf-dev/zarf/tree/main/examples) for more complex package configurations
69-
- Read the [Zarf documentation](https://docs.zarf.dev) for the full feature set
70-
7164
---
7265

73-
**Back:** [Part 1: Create a Zarf Package](../01-create-zarf-package/README.md)
66+
**Back:** [Part 1: Create a Zarf Package](../01-create-zarf-package/README.md) | **Next:** [Part 3: Inspect a Zarf Package](../03-inspect-zarf-package/README.md)

‎03-inspect-zarf-package/README.md‎

Lines changed: 160 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,160 @@
1+
# Part 3: Inspect a Zarf Package
2+
3+
A Zarf Package is meant to be a transparent "envelope" of what is packaged for secure software delivery. This is intentional such that they can transition organizational boundaries with provenance and trust.
4+
5+
You can inspect a Zarf Package in multiple locations:
6+
- A tarball on your filesystem
7+
- Published to an OCI Registry
8+
- Deployed to your Kubernetes Cluster
9+
10+
Make sure you're in the same `zarf-package` directory you used in Parts 1 and 2.
11+
12+
## Declarative Packaging and the Filesystem (optional)
13+
14+
You might be asking yourself — "What actually happened earlier when I packaged ArgoCD?"
15+
16+
Decompress the package tarball to take a look:
17+
18+
```bash
19+
zarf tools archiver decompress zarf-package-argocd-amd64-9.4.4.tar.zst unarchived/ --unarchive-all
20+
```
21+
22+
> [!NOTE]
23+
> Replace the filename with the actual tarball name if your architecture differs (e.g., `arm64` instead of `amd64`).
24+
25+
You should see a structure like the following:
26+
27+
```
28+
unarchived
29+
├── checksums.txt
30+
├── components
31+
│ └── argocd
32+
│ ├── charts
33+
│ │ └── argo-cd-9.4.4.tgz
34+
│ └── values
35+
│ └── argo-cd-9.4.4-0
36+
├── images
37+
│ ├── blobs
38+
│ │ └── sha256
39+
│ │ └── ...
40+
│ ├── index.json
41+
│ ├── ingest
42+
│ └── oci-layout
43+
├── sboms
44+
│ ├── compare.html
45+
│ ├── docker.io_library_redis_8.2.3-alpine.json
46+
│ ├── quay.io_argoproj_argocd_v3.3.2.json
47+
│ ├── sbom-viewer-docker.io_library_redis_8.2.3-alpine.html
48+
│ └── sbom-viewer-quay.io_argoproj_argocd_v3.3.2.html
49+
└── zarf.yaml
50+
```
51+
52+
This expands as you add more components to the manifest in such a way that Zarf can deterministically deploy 1→N applications from a given manifest.
53+
54+
If you were to sign this Zarf Package, you would additionally see the signature included in the archive — creating more portable provenance for cryptographic integrity.
55+
56+
## Inspect Commands (filesystem)
57+
58+
The `zarf package inspect` command provides further transparency into the package:
59+
60+
```bash
61+
zarf package inspect --help
62+
```
63+
64+
This will output the following sub-commands:
65+
66+
```
67+
definition Displays the 'zarf.yaml' definition for the specified package
68+
documentation Extract documentation files from the package
69+
images List all container images contained in the package
70+
manifests Template and output all manifests and charts in a package
71+
sbom Output the package SBOM (Software Bill Of Materials) to the specified directory
72+
values-files Creates, templates, and outputs the values-files to be sent to each chart
73+
```
74+
75+
Try a few of them:
76+
77+
View the `zarf.yaml` definition for the package:
78+
79+
```bash
80+
zarf package inspect definition zarf-package-argocd-amd64-9.4.4.tar.zst
81+
```
82+
83+
See all of the rendered manifests for the packaged Helm charts:
84+
85+
```bash
86+
zarf package inspect manifests zarf-package-argocd-amd64-9.4.4.tar.zst
87+
```
88+
89+
View the values files that will be sent to each chart:
90+
91+
```bash
92+
zarf package inspect values-files zarf-package-argocd-amd64-9.4.4.tar.zst
93+
```
94+
95+
Output the package SBOMs to a local directory:
96+
97+
```bash
98+
zarf package inspect sbom zarf-package-argocd-amd64-9.4.4.tar.zst
99+
```
100+
101+
List the images included in the package:
102+
103+
```bash
104+
zarf package inspect images zarf-package-argocd-amd64-9.4.4.tar.zst
105+
```
106+
107+
## Inspect a Deployed Package
108+
109+
Zarf doesn't just package applications into deterministic archives — it also tracks state when deploying. This enables users to identify which versions of applications they have deployed, as well as inspect or remove them.
110+
111+
List deployed packages:
112+
113+
```bash
114+
zarf package list
115+
```
116+
117+
Inspect the definition of a deployed package:
118+
119+
```bash
120+
zarf package inspect definition argocd
121+
```
122+
123+
View the images from a deployed package:
124+
125+
```bash
126+
zarf package inspect images argocd
127+
```
128+
129+
> [!NOTE]
130+
> Currently Zarf does not store SBOMs or values-files for deployed packages.
131+
132+
## Remove a Package from the Cluster
133+
134+
Given that Zarf stores the deployed package state, you have the option to upgrade packages in-place or remove a package and all of its resources.
135+
136+
Confirm the `argocd` package is still deployed:
137+
138+
```bash
139+
zarf package list
140+
```
141+
142+
Remove the `argocd` package from the cluster:
143+
144+
```bash
145+
zarf package remove argocd
146+
```
147+
148+
This will prompt you to confirm removal. You can also use the `--confirm` flag to auto-confirm.
149+
150+
Verify the package has been removed:
151+
152+
```bash
153+
zarf tools kubectl get all -n argocd
154+
```
155+
156+
You should see that the argocd namespace and its resources are gone.
157+
158+
---
159+
160+
**Back:** [Part 2: Deploy a Zarf Package](../02-deploy-zarf-package/README.md)

‎README.md‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@ In this tutorial, you'll build a Zarf package for [ArgoCD](https://argo-cd.readt
1010
- How to use `zarf dev find-images` to discover required container images
1111
- How to build a Zarf package tarball
1212
- How to deploy a Zarf package to a Kubernetes cluster
13+
- How to inspect and remove a deployed package
1314

1415
## Prerequisites
1516

@@ -46,5 +47,14 @@ Select `y` to confirm deploying the package and `y` for the `git-server` compone
4647
|------|-------------|
4748
| [Part 1: Create a Zarf Package](./01-create-zarf-package/README.md) | Author a `zarf.yaml`, discover images, and build the package tarball |
4849
| [Part 2: Deploy a Zarf Package](./02-deploy-zarf-package/README.md) | Deploy the package to your cluster and access ArgoCD |
50+
| [Part 3: Inspect a Zarf Package](./03-inspect-zarf-package/README.md) | Inspect package contents, deployed state, and remove a package |
4951

50-
Work through the parts in order — Part 2 depends on the package tarball produced in Part 1.
52+
Work through the parts in order — each part builds on the state from the previous one.
53+
54+
## Next Steps
55+
56+
After completing the tutorial, there's a lot more to explore with Zarf:
57+
58+
- Browse the [Zarf examples](https://github.com/zarf-dev/zarf/tree/main/examples) for more complex package configurations (multi-component packages, OCI publishing, custom variables, etc.)
59+
- Read the [Zarf documentation](https://docs.zarf.dev) for the full feature set
60+
- Try packaging your own application — start with a skeleton `zarf.yaml` and iterate from there

0 commit comments

Comments
 (0)