From 3f71d402b07edc2fa0d066cac6a2178aab062332 Mon Sep 17 00:00:00 2001 From: Wayne Starr Date: Wed, 10 May 2023 10:19:36 -0500 Subject: [PATCH 1/5] Add SBOM pages and more SBOM info --- README.md | 16 ++--- adr/0004-generate-sboms-with-witness.md | 2 +- adr/0011-scripts-actions.md | 4 +- docs/0-zarf-overview.md | 8 +-- .../6-package-sboms.md | 37 +++++++++++ ...nent-actions.md => 7-component-actions.md} | 0 .../{7-vscode.md => 8-vscode.md} | 0 ...{8-github-action.md => 9-github-action.md} | 0 .../3-deployment-ui.md} | 2 +- docs/4-deploy-a-zarf-package/4-view-sboms.md | 61 +++++++++++++++++++ .../5-k9s-dashboard.md} | 0 docs/5-dashboard-ui/1-sbom-dashboard.md | 42 ------------- docs/5-dashboard-ui/_category_.json | 4 -- docs/5-dashboard-ui/index.md | 7 --- .../0-creating-a-zarf-package.md | 6 +- .../2-deploying-zarf-packages.md | 2 +- docs/8-faq.md | 2 +- examples/component-actions/README.md | 2 +- 18 files changed, 120 insertions(+), 75 deletions(-) create mode 100644 docs/3-create-a-zarf-package/6-package-sboms.md rename docs/3-create-a-zarf-package/{6-component-actions.md => 7-component-actions.md} (100%) rename docs/3-create-a-zarf-package/{7-vscode.md => 8-vscode.md} (100%) rename docs/3-create-a-zarf-package/{8-github-action.md => 9-github-action.md} (100%) rename docs/{5-dashboard-ui/3-zarf-deployment-ui.md => 4-deploy-a-zarf-package/3-deployment-ui.md} (99%) create mode 100644 docs/4-deploy-a-zarf-package/4-view-sboms.md rename docs/{5-dashboard-ui/2-k9s-dashboard.md => 4-deploy-a-zarf-package/5-k9s-dashboard.md} (100%) delete mode 100644 docs/5-dashboard-ui/1-sbom-dashboard.md delete mode 100644 docs/5-dashboard-ui/_category_.json delete mode 100644 docs/5-dashboard-ui/index.md diff --git a/README.md b/README.md index a370219bb6..6bf71d002b 100644 --- a/README.md +++ b/README.md @@ -17,24 +17,24 @@ Zarf eliminates the [complexity of air gap software delivery](https://www.itopst ## 📦 Out of the Box Features - Automate Kubernetes deployments in disconnected environments -- Automate [Software Bill of Materials (SBOM)](https://www.linuxfoundation.org/tools/the-state-of-software-bill-of-materials-sbom-and-cybersecurity-readiness/) generation -- Provide a [web dashboard](https://docs.zarf.dev/docs/dashboard-ui/sbom-dashboard) for viewing SBOM output +- Automate [Software Bill of Materials (SBOM)](https://docs.zarf.dev/docs/deploy-a-zarf-package/package-sboms) generation +- Provide a [web dashboard](https://docs.zarf.dev/docs/deploy-a-zarf-package/view-sboms) for viewing SBOM output - Create and verify package signatures with [cosign](https://github.com/sigstore/cosign) -- [Publish](https://docs.zarf.dev/docs/user-guide/the-zarf-cli/cli-commands/zarf_package_publish), [pull](https://docs.zarf.dev/docs/user-guide/the-zarf-cli/cli-commands/zarf_package_pull), and [deploy](https://docs.zarf.dev/docs/user-guide/the-zarf-cli/cli-commands/zarf_package_deploy) packages from an [OCI registry](https://opencontainers.org/) -- Powerful component lifecycle [actions](https://docs.zarf.dev/docs/user-guide/component-actions) +- [Publish](https://docs.zarf.dev/docs/the-zarf-cli/cli-commands/zarf_package_publish), [pull](https://docs.zarf.dev/docs/the-zarf-cli/cli-commands/zarf_package_pull), and [deploy](https://docs.zarf.dev/docs/the-zarf-cli/cli-commands/zarf_package_deploy) packages from an [OCI registry](https://opencontainers.org/) +- Powerful component lifecycle [actions](https://docs.zarf.dev/docs/create-a-zarf-package/component-actions) - Deploy a new cluster while fully disconnected with [K3s](https://k3s.io/) or into any existing cluster using a [kube config](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/) - Builtin logging stack with [Loki](https://grafana.com/oss/loki/) - Builtin Git server with [Gitea](https://gitea.com/) - Builtin Docker registry - Builtin [K9s Dashboard](https://k9scli.io/) for managing a cluster from the terminal - [Mutating Webhook](adr/0005-mutating-webhook.md) to automatically update Kubernetes pod's image path and pull secrets as well as [Flux Git Repository](https://fluxcd.io/docs/components/source/gitrepositories/) URLs and secret references -- Builtin [command to find images](https://docs.zarf.dev/docs/user-guide/the-zarf-cli/cli-commands/zarf_prepare_find-images) and resources from a Helm chart -- Tunneling capability to [connect to Kubernetes resources](https://docs.zarf.dev/docs/user-guide/the-zarf-cli/cli-commands/zarf_connect) without network routing, DNS, TLS or Ingress configuration required +- Builtin [command to find images](https://docs.zarf.dev/docs/the-zarf-cli/cli-commands/zarf_prepare_find-images) and resources from a Helm chart +- Tunneling capability to [connect to Kubernetes resources](https://docs.zarf.dev/docs/the-zarf-cli/cli-commands/zarf_connect) without network routing, DNS, TLS or Ingress configuration required ## 🛠️ Configurable Features - Customizable [variables and package templates](examples/variables/README.md) with defaults and user prompting -- [Composable packages](https://docs.zarf.dev/docs/user-guide/zarf-packages/zarf-components#composing-package-components) to include multiple sub-packages/components +- [Composable packages](https://docs.zarf.dev/docs/create-a-zarf-package/zarf-components#composing-package-components) to include multiple sub-packages/components - Component-level OS/architecture filtering ## Demo @@ -47,7 +47,7 @@ __ To try Zarf out for yourself, visit the ["Try It Now"](https://zarf.dev/install) section on our website, and if you want to learn more about Zarf and its use cases visit [docs.zarf.dev](https://docs.zarf.dev/docs/zarf-overview). -From the docs you can learn more about [installation](https://docs.zarf.dev/docs/getting-started/#installing-zarf), [using the CLI](https://docs.zarf.dev/docs/user-guide/the-zarf-cli/), [making packages](https://docs.zarf.dev/docs/user-guide/zarf-packages/), and the [Zarf package schema](https://docs.zarf.dev/docs/user-guide/zarf-schema). +From the docs you can learn more about [installation](https://docs.zarf.dev/docs/getting-started/#installing-zarf), [using the CLI](https://docs.zarf.dev/docs/the-zarf-cli/), [making packages](https://docs.zarf.dev/docs/create-a-zarf-package/zarf-packages/), and the [Zarf package schema](https://docs.zarf.dev/docs/create-a-zarf-package/zarf-schema). Using Zarf in Github workflows? Check out the [setup-zarf](https://github.com/defenseunicorns/setup-zarf) action. Install any version of Zarf and its `init` package with zero added dependencies. diff --git a/adr/0004-generate-sboms-with-witness.md b/adr/0004-generate-sboms-with-witness.md index e43e76a55e..ebb855480d 100644 --- a/adr/0004-generate-sboms-with-witness.md +++ b/adr/0004-generate-sboms-with-witness.md @@ -12,7 +12,7 @@ SBOM are required for software running on government hardware per EO14028. ## Decision -Using Witness' Syft attestor functionality allows Zarf to continue to get more refined SBOM capabilities as Witness' capabilities expand over time. Syft is capable of finding installed packages and some binaries for statically compiled dependencies over each image within a Zarf package. This allows for SBOMs for each image to be generated and packaged along with the Zarf package. Abilities to export the SBOM to SDPX and CycloneDX formatted documents as well as a browsable web page are in works. +Using Witness' Syft attestor functionality allows Zarf to continue to get more refined SBOM capabilities as Witness' capabilities expand over time. Syft is capable of finding installed packages and some binaries for statically compiled dependencies over each image within a Zarf package. This allows for SBOMs for each image to be generated and packaged along with the Zarf package. Abilities to export the SBOM to SDPX and CycloneDX formatted documents as well as a browse-able web page are in works. ## Consequences diff --git a/adr/0011-scripts-actions.md b/adr/0011-scripts-actions.md index 0d59d860dc..8f5c748fa7 100644 --- a/adr/0011-scripts-actions.md +++ b/adr/0011-scripts-actions.md @@ -18,9 +18,9 @@ The `scripts` section of the `zarf.yaml` will be replaced with a new `actions` s - `onDeploy` - Runs during `zarf package deploy` - `onRemove` - Runs during `zarf package remove` -In addition to adding more lifecycle events, the `actions` section will also allow for more complex actions to be defined. New configurations include, setting the cmd directory, defining custom env variables, setting the number of retries, setting the max total seconds, muting the output, and [setting a variable](../docs/3-create-a-zarf-package/6-component-actions.md#creating-dynamic-variables-from-actions) to be used in other actions or components. +In addition to adding more lifecycle events, the `actions` section will also allow for more complex actions to be defined. New configurations include, setting the cmd directory, defining custom env variables, setting the number of retries, setting the max total seconds, muting the output, and [setting a variable](../docs/3-create-a-zarf-package/7-component-actions.md#creating-dynamic-variables-from-actions) to be used in other actions or components. -Further details can be found in the `component-actions` [component actions documentation](../docs/3-create-a-zarf-package/6-component-actions.md), [package create lifecycle documentation](../docs/3-create-a-zarf-package/5-package-create-lifecycle.md), [package deploy lifecycle documentation](../docs/4-deploy-a-zarf-package/1-package-deploy-lifecycle.md), and the [example package](../examples/component-actions/README.md). +Further details can be found in the `component-actions` [component actions documentation](../docs/3-create-a-zarf-package/7-component-actions.md), [package create lifecycle documentation](../docs/3-create-a-zarf-package/5-package-create-lifecycle.md), [package deploy lifecycle documentation](../docs/4-deploy-a-zarf-package/1-package-deploy-lifecycle.md), and the [example package](../examples/component-actions/README.md). ## Consequences diff --git a/docs/0-zarf-overview.md b/docs/0-zarf-overview.md index 7ae4cac89e..889fd1c2b9 100644 --- a/docs/0-zarf-overview.md +++ b/docs/0-zarf-overview.md @@ -65,7 +65,7 @@ Given Zarf's being a "K8s cluster to serve _other_ K8s clusters", the following - Container images: to serve images for the Zarf and downstream clusters to run containers from. - Repositories: to serve as the git-based "source of truth" for downstream "GitOps"ed K8s clusters to watch. - Pre-compiled binaries: to provide the software necessary to start and support the Zarf cluster. -- [Component actions](3-create-a-zarf-package/6-component-actions.md): to support scripts and commands that run at various stages of the Zarf [package create lifecycle](./3-create-a-zarf-package/5-package-create-lifecycle.md), and [package deploy lifecycle](./4-deploy-a-zarf-package/1-package-deploy-lifecycle.md). +- [Component actions](3-create-a-zarf-package/7-component-actions.md): to support scripts and commands that run at various stages of the Zarf [package create lifecycle](./3-create-a-zarf-package/5-package-create-lifecycle.md), and [package deploy lifecycle](./4-deploy-a-zarf-package/1-package-deploy-lifecycle.md). - Helm charts, kustomizations, and other K8s manifests: to apply in a Kubernetes cluster. - [Data injections](../examples/data-injection/README.md): to declaratively inject data into running containers in a Kubernetes cluster. @@ -133,11 +133,11 @@ In the more complex use case, your package consists of updates for many apps/sys ### 📦 Out of the Box Features - Automate Kubernetes deployments in disconnected environments -- Automate [Software Bill of Materials (SBOM)](https://www.linuxfoundation.org/tools/the-state-of-software-bill-of-materials-sbom-and-cybersecurity-readiness/) generation -- Provide a [web dashboard](./5-dashboard-ui/1-sbom-dashboard.md) for viewing SBOM output +- Automate [Software Bill of Materials (SBOM)](./3-create-a-zarf-package/6-package-sboms.md) generation +- Provide a [web dashboard](./4-deploy-a-zarf-package/4-view-sboms.md) for viewing SBOM output - Create and verify package signatures with [cosign](https://github.com/sigstore/cosign) - [Publish](./2-the-zarf-cli/100-cli-commands/zarf_package_publish.md), [pull](./2-the-zarf-cli/100-cli-commands/zarf_package_pull.md), and [deploy](./2-the-zarf-cli/100-cli-commands/zarf_package_deploy.md) packages from an [OCI registry](https://opencontainers.org/) -- Powerful component lifecycle [actions](./3-create-a-zarf-package/6-component-actions.md) +- Powerful component lifecycle [actions](./3-create-a-zarf-package/7-component-actions.md) - Deploy a new cluster while fully disconnected with [K3s](https://k3s.io/) or into any existing cluster using a [kube config](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/) - Builtin logging stack with [Loki](https://grafana.com/oss/loki/) - Builtin Git server with [Gitea](https://gitea.com/) diff --git a/docs/3-create-a-zarf-package/6-package-sboms.md b/docs/3-create-a-zarf-package/6-package-sboms.md new file mode 100644 index 0000000000..d63069f69f --- /dev/null +++ b/docs/3-create-a-zarf-package/6-package-sboms.md @@ -0,0 +1,37 @@ +# Package SBOMs + + + +Zarf builds [Software Bill of Materials (SBOM)](https://www.linuxfoundation.org/tools/the-state-of-software-bill-of-materials-sbom-and-cybersecurity-readiness/) into packages to help with the management of software being brought into the air gap. This page goes into detail of how these SBOMs are created and what within a package will get an associated SBOM. If you would like to see how to interact with SBOMs after they are built into a package, see the [View SBOMs page](../4-deploy-a-zarf-package/4-view-sboms.md) under Deploy a Zarf Package. + +## How SBOMs are Generated + +Zarf uses [Syft](https://github.com/anchore/syft) under the hood to provide SBOMs for container `images`, as well as `files` and `dataInjections` included in components. This is run during the final step of package creation with the SBOM information for a package being placed within an `sboms` directory at the root of the Zarf Package tarball. Additionally, the SBOMs are created in the Syft `.json` format which is a superset of all of the information that Syft can discover and is used so that we can provide the most information possible even when performing [lossy conversions to formats like `spdx-json` or `cyclonedx-json`](../4-deploy-a-zarf-package/4-view-sboms.md#sboms-built-into-packages). + +If you were using the Syft CLI to create these SBOM files manually this would be equivalent to the following commands: + +```bash +# For `images` contained within the package +$ syft packages oci-dir:path/to/yourimage +``` + +```bash +# For `files` or `dataInjections` contained within the package +$ syft packages file:path/to/yourproject/file +``` + +:::note + +Zarf uses the file Syft SBOM scheme even if given a directory as the `files` or `dataInjection` source since this generally provides more information (at the cost of execution speed). + +::: + +:::tip + +Given the Syft CLI is vendored into Zarf you can run these commands with the Zarf binary as well: + +```bash +$ zarf tools sbom packages file:path/to/yourproject/file +``` + +::: diff --git a/docs/3-create-a-zarf-package/6-component-actions.md b/docs/3-create-a-zarf-package/7-component-actions.md similarity index 100% rename from docs/3-create-a-zarf-package/6-component-actions.md rename to docs/3-create-a-zarf-package/7-component-actions.md diff --git a/docs/3-create-a-zarf-package/7-vscode.md b/docs/3-create-a-zarf-package/8-vscode.md similarity index 100% rename from docs/3-create-a-zarf-package/7-vscode.md rename to docs/3-create-a-zarf-package/8-vscode.md diff --git a/docs/3-create-a-zarf-package/8-github-action.md b/docs/3-create-a-zarf-package/9-github-action.md similarity index 100% rename from docs/3-create-a-zarf-package/8-github-action.md rename to docs/3-create-a-zarf-package/9-github-action.md diff --git a/docs/5-dashboard-ui/3-zarf-deployment-ui.md b/docs/4-deploy-a-zarf-package/3-deployment-ui.md similarity index 99% rename from docs/5-dashboard-ui/3-zarf-deployment-ui.md rename to docs/4-deploy-a-zarf-package/3-deployment-ui.md index 56a630ac90..0bef8509e8 100644 --- a/docs/5-dashboard-ui/3-zarf-deployment-ui.md +++ b/docs/4-deploy-a-zarf-package/3-deployment-ui.md @@ -1,4 +1,4 @@ -# Zarf Deployment Web UI +# Deployment Web UI Zarf has a Deployment Web UI built in that supports a number of Zarf features used during the package deployment process. For users who prefer not to use the command line tool, the Web UI creates a simple experience to deploy and manage Zarf clusters and packages. The Web UI can be used to connect to existing clusters (via a Kubeconfig), initialize a cluster, deploy packages into a cluster, update packages in the cluster, and remove packages from the cluster. diff --git a/docs/4-deploy-a-zarf-package/4-view-sboms.md b/docs/4-deploy-a-zarf-package/4-view-sboms.md new file mode 100644 index 0000000000..b8489f1d5b --- /dev/null +++ b/docs/4-deploy-a-zarf-package/4-view-sboms.md @@ -0,0 +1,61 @@ +# View SBOMs + +A [Software Bill of Materials (SBOM)](https://www.linuxfoundation.org/tools/the-state-of-software-bill-of-materials-sbom-and-cybersecurity-readiness/) is a document that contains a detailed list of all the things a software application is using. SBOMs are important from a security standpoint because they allow you to better track what dependencies you have, and with that information, you can quickly check if any of your dependencies are out of date or have a known vulnerability that should be patched. Zarf makes SBOMs easier, if not painless, to deal with! + +## SBOMs Built Into Packages + +Zarf treats security as a first-class concern and builds SBOM documents into packages by default! Unless explicitly skipped with the `--skip-sbom` flag, whenever a package is created, Zarf generates an SBOM for it and adds it to the package itself. This means that wherever you end up moving your package, you will always be able to take a peek inside to see what it contains. You can learn more about how Zarf does this on the [Package SBOMs page](../3-create-a-zarf-package/6-package-sboms.md). + +You can quickly view these files in your browser by running `zarf package inspect` with the `-s` or `--sbom` flag. If there are any SBOMs included in the package, Zarf will open the SBOM viewer to the first SBOM in the list. + +``` bash +$ zarf package inspect zarf-package-example-amd64.tar.zst -s +``` + +:::tip + +If you would like to get to the raw SBOM files inside of a package you can use the `--sbom-out` flag as shown below: + +``` bash +$ zarf package inspect zarf-package-example-amd64.tar.zst --sbom-out ./temp-sbom-dir +$ cd ./temp-sbom-dir/example +$ ls +``` + +This will output the raw SBOM viewer `.html` files as well as the Syft `.json` files contained in the package. Both of these files contain the same information, but the `.html` files are a lightweight representation of the `.json` SBOM files to be more human-readable. The `.json` files exist to be injected into other tools, such as [Grype](https://github.com/anchore/grype) for vulnerability checking. + +The Syft `.json` files can also be converted to other formats with the Syft CLI (which is vendored into Zarf) including `spdx-json` and `cyclonedx-json`. + +``` +zarf tools sbom convert nginx_1.23.0.json -o cyclonedx-json > nginx_1.23.0.cyclonedx.json +``` + +To learn more about the formats Syft supports see `zarf tools sbom convert -h` + +::: + +## Viewing SBOMs When Deploying + + + +When deploying a package, Zarf will output the yaml definition of the package, i.e. the `zarf.yaml` that defined the package that was created. If there are any artifacts included in the package, Zarf will also output a note saying how many artifacts are going to be deployed with a link to a lightweight [SBOM viewer](#the-sbom-viewer) that you can copy into your browser to get a visual overview of the artifacts and what they contain. + +![SBOM Prompt](../.images/dashboard/SBOM_prompt_example.png) + +:::note + +Zarf does not prompt you to view the SBOM if you are deploying a package with the `--confirm` flag + +::: + +## The SBOM Viewer + +**Example SBOM Dashboard** +![SBOM Dashboard](../.images/dashboard/SBOM_dashboard.png) + +In each package that contains SBOM information, Zarf includes a simple dashboard that allows you to see the contents of each container image or set of component files within your package. You can toggle through the different images or components in the dropdown at the top right of the dashboard as well as export the table contents to a CSV. + +**Example SBOM Comparer** +![SBOM Comparer](../.images/dashboard/SBOM_compare.png) + +The SBOM viewer also has an SBOM comparison tool built in that you can access by clicking the "Compare Tool" button next to the image selector. This view allows you to take the SBOM `.json` data (extracted alongside the `.html` files with `--sbom-out`) and compare that across images or packages (if you extract multiple Zarf packages at a time). This is useful for seeing what has changed between different image or component versions. diff --git a/docs/5-dashboard-ui/2-k9s-dashboard.md b/docs/4-deploy-a-zarf-package/5-k9s-dashboard.md similarity index 100% rename from docs/5-dashboard-ui/2-k9s-dashboard.md rename to docs/4-deploy-a-zarf-package/5-k9s-dashboard.md diff --git a/docs/5-dashboard-ui/1-sbom-dashboard.md b/docs/5-dashboard-ui/1-sbom-dashboard.md deleted file mode 100644 index 5ef25a9b7c..0000000000 --- a/docs/5-dashboard-ui/1-sbom-dashboard.md +++ /dev/null @@ -1,42 +0,0 @@ -# SBOM Dashboard - -A Software Bill of Materials (SBOM) is a document that contains a detailed list of all the things a software application is using. SBOMs are important from a security standpoint because they allow you to better track what dependencies you have, and with that information, you can quickly check if any of your dependencies are out of date or have a known vulnerability that should be patched. Zarf makes SBOMs easier, if not painless, to deal with! - -## SBOMs Built Into Packages - -Zarf treats security as a first-class concern and builds SBOM capabilities into packages by default! Unless explicitly skipped with the `--skip-sbom` flag, whenever a package is created, Zarf generates an SBOM for it and adds it to the package itself. This means that wherever you end up moving your package, you will always be able to take a peek inside to see what it contains. All of the package's SBOM information exists within a `sboms` directory at the root of the zarf package tarball. - -You can view these files by decompressing the package tarball and navigating to the `sboms` directory or by running `zarf package inspect --sbom-out `. If there are any images or files included in the package definition, the `sboms` directory will contain a `.html` and `.json` file for each image or set of files. Both of these files contain the same information, but the `.html` files are a lightweight representation of the `.json` SBOM files to be more human-readable. The `.json` files exist to be injected into other tools, such as [Grype](https://github.com/anchore/grype) for vulnerability checking as an example. - -``` bash -zarf package inspect zarf-package-example-amd64.tar.zst --sbom-out ./temp-sbom-dir -cd ./temp-sbom-dir/example -ls -``` - -If you would like to get to any of this information without messing with the raw files you can also run package inspect with the `-s` or `--sbom` flag to quickly open a browser to the viewer: - -``` bash -zarf package inspect zarf-package-example-amd64.tar.zst --sbom -``` - -## Viewing SBOMs When Deploying - -:::note -Zarf does not prompt you to view the SBOM if you are deploying a package with the `--confirm` flag -::: - -When deploying a package, Zarf will output the yaml definition of the package, i.e. the `zarf.yaml` file that defined the package that was created. If there are any artifacts included in the package, Zarf will also output a note saying how many artifacts are going to be deployed with a link to a lightweight html viewer that you can use to get a visual overview of the artifacts and what they contain. - -**Example SBOM Prompt** -![SBOM Prompt](../.images/dashboard/SBOM_prompt_example.png) - -You can navigate to the SBOM viewer dashboard by copying the `.html` file into your browser. Through the simple dashboard you can see all of the contents for each container image or component within your package. You can toggle through the different images or components in the dropdown at the top right of the dashboard as well as export the table contents to a CSV. - -**Example SBOM Dashboard** -![SBOM Dashboard](../.images/dashboard/SBOM_dashboard.png) - -The SBOM viewer also has an SBOM comparison tool built in that you can access by clicking the "Compare Tool" button next to the image selector. This view allows you to take the SBOM JSON data (extracted alongside the HTML files) and compare that across images or packages (if you extract multiple at a time). This is useful for seeing what has changed between different image or component versions. - -**Example SBOM Comparer** -![SBOM Comparer](../.images/dashboard/SBOM_compare.png) diff --git a/docs/5-dashboard-ui/_category_.json b/docs/5-dashboard-ui/_category_.json deleted file mode 100644 index b0ba0f5a48..0000000000 --- a/docs/5-dashboard-ui/_category_.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "position": 5, - "label": "UI Dashboards" -} diff --git a/docs/5-dashboard-ui/index.md b/docs/5-dashboard-ui/index.md deleted file mode 100644 index 5d56df07a2..0000000000 --- a/docs/5-dashboard-ui/index.md +++ /dev/null @@ -1,7 +0,0 @@ -# UI Dashboards - -In order to help users interact with clusters and packages in the air gap, Zarf comes bundled with User Interfaces beyond the standard [Zarf CLI](../2-the-zarf-cli/index.md). These provide a more interactive experience to interact with clusters and Zarf packages. Currently these include: - -1. A viewer and comparison tool for [interacting with package SBOMs](./1-sbom-dashboard.md) -2. The [`k9s` Kubernetes cluster management tool](./2-k9s-dashboard.md) -3. A [custom Web UI](./3-zarf-deployment-ui.md) for deploying and managing Zarf Packages diff --git a/docs/6-zarf-tutorials/0-creating-a-zarf-package.md b/docs/6-zarf-tutorials/0-creating-a-zarf-package.md index 9268180917..d040d80d90 100644 --- a/docs/6-zarf-tutorials/0-creating-a-zarf-package.md +++ b/docs/6-zarf-tutorials/0-creating-a-zarf-package.md @@ -15,7 +15,7 @@ When creating a Zarf package, you must have a network connection so that Zarf ca Before beginning this tutorial you will need the following: - Zarf binary installed on your $PATH: ([Installing Zarf](../1-getting-started/index.md#installing-zarf)) -- A text editor or development environment such as [VS Code](../3-create-a-zarf-package/7-vscode.md) +- A text editor or development environment such as [VS Code](../3-create-a-zarf-package/8-vscode.md) ## Putting Together a Zarf Package @@ -36,7 +36,7 @@ metadata: :::tip -If you are using an Integrated Development Environment (such as [VS Code](../3-create-a-zarf-package/7-vscode.md)) to create and edit the `zarf.yaml` file, you can install or reference the [`zarf.schema.json`](https://github.com/defenseunicorns/zarf/blob/main/zarf.schema.json) file to get error checking and autocomplete. +If you are using an Integrated Development Environment (such as [VS Code](../3-create-a-zarf-package/8-vscode.md)) to create and edit the `zarf.yaml` file, you can install or reference the [`zarf.schema.json`](https://github.com/defenseunicorns/zarf/blob/main/zarf.schema.json) file to get error checking and autocomplete. ::: @@ -258,7 +258,7 @@ You can learn more about what is going on behind the scenes of this process on t ::: -Congratulations! You've built the Wordpress package. Now, you can learn how to [inspect the SBOMs](../5-dashboard-ui/1-sbom-dashboard.md) or head straight to [deploying it](./2-deploying-zarf-packages.md)! +Congratulations! You've built the Wordpress package. Now, you can learn how to [inspect the SBOMs](../4-deploy-a-zarf-package/4-view-sboms.md) or head straight to [deploying it](./2-deploying-zarf-packages.md)! ## Troubleshooting diff --git a/docs/6-zarf-tutorials/2-deploying-zarf-packages.md b/docs/6-zarf-tutorials/2-deploying-zarf-packages.md index a1003c287c..1266e36200 100644 --- a/docs/6-zarf-tutorials/2-deploying-zarf-packages.md +++ b/docs/6-zarf-tutorials/2-deploying-zarf-packages.md @@ -48,7 +48,7 @@ To accept a default value for a given variable, simply press the `enter` key. Y ![Zarf Connect Wordpress](../.images/tutorials/wordpress_connected.png) -4. We can also explore the resources deployed by our package by running the `zarf tools monitor` command to start [`K9s`](../5-dashboard-ui/2-k9s-dashboard.md). Once you are done, hit `ctrl/control c` to exit. +4. We can also explore the resources deployed by our package by running the `zarf tools monitor` command to start [`K9s`](../4-deploy-a-zarf-package/5-k9s-dashboard.md). Once you are done, hit `ctrl/control c` to exit. ![Zarf Tools Monitor](../.images/tutorials/zarf_tools_monitor.png) diff --git a/docs/8-faq.md b/docs/8-faq.md index b6031785b1..6378bf01f0 100644 --- a/docs/8-faq.md +++ b/docs/8-faq.md @@ -48,7 +48,7 @@ Additionally, when adopting resources, you should ensure that the namespaces you Due to some limitations with how Docker provides access to local image layers, `zarf package create` has to rely on `docker save` under the hood which is [very slow overall](https://github.com/defenseunicorns/zarf/issues/1214) and also takes a long time to report progress. We experimented with many ways to improve this, but for now recommend leveraging a local docker registry to speed up the process. -This can be done by running a local registry and pushing the images to it before running `zarf package create`. This will allow `zarf package create` to pull the images from the local registry instead of Docker. This can also be combined with [component actions](3-create-a-zarf-package/6-component-actions.md) and [`--registry-override`](./2-the-zarf-cli/100-cli-commands/zarf_package_create.md) to make the process automatic. Given an example image of `registry.enterprise.corp/my-giant-image:v2` you could do something like this: +This can be done by running a local registry and pushing the images to it before running `zarf package create`. This will allow `zarf package create` to pull the images from the local registry instead of Docker. This can also be combined with [component actions](3-create-a-zarf-package/7-component-actions.md) and [`--registry-override`](./2-the-zarf-cli/100-cli-commands/zarf_package_create.md) to make the process automatic. Given an example image of `registry.enterprise.corp/my-giant-image:v2` you could do something like this: ```sh # Create a local registry diff --git a/examples/component-actions/README.md b/examples/component-actions/README.md index 13201c8b90..cc52cbf97e 100644 --- a/examples/component-actions/README.md +++ b/examples/component-actions/README.md @@ -14,7 +14,7 @@ To view the example source code, select the `Edit this page` link below the arti This example demonstrates how to define actions within your package that can run either on `zarf package create`, `zarf package deploy` or `zarf package remove`. These actions will be executed with the context that the Zarf binary is executed with. -For more details on component actions, see the [component actions](../../docs/3-create-a-zarf-package/6-component-actions.md) documentation. +For more details on component actions, see the [component actions](../../docs/3-create-a-zarf-package/7-component-actions.md) documentation. ```yaml components: From fa1c6c7ac224bdb0772511a6072c54bb3885e4be Mon Sep 17 00:00:00 2001 From: Wayne Starr Date: Wed, 10 May 2023 10:22:46 -0500 Subject: [PATCH 2/5] Add the -o json to the Syft commands --- docs/3-create-a-zarf-package/6-package-sboms.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/3-create-a-zarf-package/6-package-sboms.md b/docs/3-create-a-zarf-package/6-package-sboms.md index d63069f69f..7eb3f5e650 100644 --- a/docs/3-create-a-zarf-package/6-package-sboms.md +++ b/docs/3-create-a-zarf-package/6-package-sboms.md @@ -12,12 +12,12 @@ If you were using the Syft CLI to create these SBOM files manually this would be ```bash # For `images` contained within the package -$ syft packages oci-dir:path/to/yourimage +$ syft packages oci-dir:path/to/yourimage -o json > my-sbom.json ``` ```bash # For `files` or `dataInjections` contained within the package -$ syft packages file:path/to/yourproject/file +$ syft packages file:path/to/yourproject/file -o json > my-sbom.json ``` :::note @@ -31,7 +31,7 @@ Zarf uses the file Syft SBOM scheme even if given a directory as the `files` or Given the Syft CLI is vendored into Zarf you can run these commands with the Zarf binary as well: ```bash -$ zarf tools sbom packages file:path/to/yourproject/file +$ zarf tools sbom packages file:path/to/yourproject/file -o json > my-sbom.json ``` ::: From 6ac54d472001713d8828b110e70c0d659bdeb914 Mon Sep 17 00:00:00 2001 From: Wayne Starr Date: Wed, 10 May 2023 10:26:25 -0500 Subject: [PATCH 3/5] Make file: stand out --- docs/3-create-a-zarf-package/6-package-sboms.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/3-create-a-zarf-package/6-package-sboms.md b/docs/3-create-a-zarf-package/6-package-sboms.md index 7eb3f5e650..7dfc335bf3 100644 --- a/docs/3-create-a-zarf-package/6-package-sboms.md +++ b/docs/3-create-a-zarf-package/6-package-sboms.md @@ -22,7 +22,7 @@ $ syft packages file:path/to/yourproject/file -o json > my-sbom.json :::note -Zarf uses the file Syft SBOM scheme even if given a directory as the `files` or `dataInjection` source since this generally provides more information (at the cost of execution speed). +Zarf uses the `file:` Syft SBOM scheme even if given a directory as the `files` or `dataInjection` source since this generally provides more information (at the cost of execution speed). ::: From 0d4771385303f894368f44d2257486eae3ef14c5 Mon Sep 17 00:00:00 2001 From: Wayne Starr Date: Wed, 10 May 2023 19:18:13 -0500 Subject: [PATCH 4/5] Fix #1653 --- docs/3-create-a-zarf-package/7-component-actions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/3-create-a-zarf-package/7-component-actions.md b/docs/3-create-a-zarf-package/7-component-actions.md index 5df302be56..a286f6925b 100644 --- a/docs/3-create-a-zarf-package/7-component-actions.md +++ b/docs/3-create-a-zarf-package/7-component-actions.md @@ -135,7 +135,7 @@ Within each of the `action` lists (`before`, `after`, `onSuccess`, and `onFailur - `wait` - (required if not a cmd action) the wait parameters. - `cluster` - perform a wait operation on a Kubernetes resource (kubectl wait). - `kind` - the kind of resource to wait for (required). - - `identifier` - the identifier of the resource to wait for (required), can be a name or label selector. + - `name` - the name of the resource to wait for (required), can be a name or label selector. - `namespace` - the namespace of the resource to wait for. - `condition` - the condition to wait for (default: `exists`). - `network` - perform a wait operation on a network resource (curl). From bf22bcf044c0b6fae514bcae02188956b35977d0 Mon Sep 17 00:00:00 2001 From: Wayne Starr Date: Thu, 11 May 2023 11:01:50 -0500 Subject: [PATCH 5/5] Remove TODO in 6-package-sboms.md --- docs/3-create-a-zarf-package/6-package-sboms.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/3-create-a-zarf-package/6-package-sboms.md b/docs/3-create-a-zarf-package/6-package-sboms.md index 7dfc335bf3..cc84e4244a 100644 --- a/docs/3-create-a-zarf-package/6-package-sboms.md +++ b/docs/3-create-a-zarf-package/6-package-sboms.md @@ -1,7 +1,5 @@ # Package SBOMs - - Zarf builds [Software Bill of Materials (SBOM)](https://www.linuxfoundation.org/tools/the-state-of-software-bill-of-materials-sbom-and-cybersecurity-readiness/) into packages to help with the management of software being brought into the air gap. This page goes into detail of how these SBOMs are created and what within a package will get an associated SBOM. If you would like to see how to interact with SBOMs after they are built into a package, see the [View SBOMs page](../4-deploy-a-zarf-package/4-view-sboms.md) under Deploy a Zarf Package. ## How SBOMs are Generated