Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

add dashboard docs for sbom and k9s #598

Merged
merged 2 commits into from
Jul 7, 2022
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Binary file added docs/.images/dashboard/SBOM_dashboard.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/.images/dashboard/SBOM_prompt_example.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/.images/dashboard/k9s_dashboard_example.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
35 changes: 32 additions & 3 deletions docs/8-dashboard-ui/1-sbom-dashboard.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,34 @@
# SBOM Dashboard

:::caution Hard Hat Area
This page is still being developed. More content will be added soon!
:::
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, 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 into the package itself. This means that wherever you end up moving your package to, you will always be able to take a peek inside to see what it contains. All of the packages sbom information exists within a `sboms` directory at the root of the tarball.

You can view these files by decompressing the package tarball and navigating to the `sboms` directory. If there are any containers included in the package definition, the `sboms` directory will contain a `.html` and .`.json` file for each container. Both of these files contain the same information but the `.html` files are a lightweight representation of the SBOM and the `.json` files in a more human readable format.
``` bash
zarf tools archiver decompress my-zarf-package.tar.zst ./temp-decompressed-dir
cd ./temp-decompressed-dir/sboms
ls
```

<br />

## 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, the zarf.yaml file that defined the package that got created. If there are any containers included in the package, Zarf will also output a note saying how many images are going to be getting deployed and links to a lightweight html viewer that you can use to get a visual overview of the images 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 within your package. You can toggle through the different images in the dropdown at the top right of the dashboard.

<!-- TODO: I would like to annotate this png with colored boxes/text to describe different parts of the dashboard -->
**Example SBOM Dashboard**
![SBOM Dashboard](../.images/dashboard/SBOM_dashboard.png)
24 changes: 21 additions & 3 deletions docs/8-dashboard-ui/2-k9s-dashboard.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,23 @@
# K9s

:::caution Hard Hat Area
This page is still being developed. More content will be added soon!
:::
Zarf vendors in [K9s](https://k9scli.io/), a terminal based UI to interact with your Kubernetes cluster. K9s is not necessary to deploy, manage, or operate Zarf or its deployed packages, but it is a great tool to use when you want to interact with your cluster. Since Zarf vendors in this tool, you don't have to worry about additional dependencies or trying to install it yourself!


## Using the k9s Dashboard

All you need to use the k9s dashboard is to:
1. Have access to a running cluster kubecontext
1. Have a zarf binary installed

<br />
Using the k9s Dashboard is as simple as using a single command!

```bash
zarf tools k9s
```
<br />

**Example k9s Dashboard**
![k9s dashboard](../.images/dashboard/k9s_dashboard_example.png)

More instructions on how to use k9s can be found on their [documentation site](https://k9scli.io/topics/commands/).