diff --git a/.adr-dir b/.adr-dir index c73b64aed2..0a5ca20aeb 100644 --- a/.adr-dir +++ b/.adr-dir @@ -1 +1 @@ -docs/adr +adr diff --git a/docs/adr/0001-record-architecture-decisions.md b/adr/0001-record-architecture-decisions.md similarity index 100% rename from docs/adr/0001-record-architecture-decisions.md rename to adr/0001-record-architecture-decisions.md diff --git a/docs/adr/0002-moving-e2e-tests-away-from-terratest.md b/adr/0002-moving-e2e-tests-away-from-terratest.md similarity index 100% rename from docs/adr/0002-moving-e2e-tests-away-from-terratest.md rename to adr/0002-moving-e2e-tests-away-from-terratest.md diff --git a/docs/adr/0003-image-injection-into-remote-clusters-without-native-support.md b/adr/0003-image-injection-into-remote-clusters-without-native-support.md similarity index 100% rename from docs/adr/0003-image-injection-into-remote-clusters-without-native-support.md rename to adr/0003-image-injection-into-remote-clusters-without-native-support.md diff --git a/docs/adr/0004-generate-sboms-with-witness.md b/adr/0004-generate-sboms-with-witness.md similarity index 100% rename from docs/adr/0004-generate-sboms-with-witness.md rename to adr/0004-generate-sboms-with-witness.md diff --git a/docs/adr/0005-mutating-webhook.md b/adr/0005-mutating-webhook.md similarity index 100% rename from docs/adr/0005-mutating-webhook.md rename to adr/0005-mutating-webhook.md diff --git a/docs/adr/template.md b/adr/template.md similarity index 100% rename from docs/adr/template.md rename to adr/template.md diff --git a/docs/.images/Zarf Files - 3 Bubbles.svg b/docs/.images/Zarf Files - 3 Bubbles.svg new file mode 100644 index 0000000000..2b2cf8536e --- /dev/null +++ b/docs/.images/Zarf Files - 3 Bubbles.svg @@ -0,0 +1,215 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/.images/Zarf Left Underwater - Behind rock.svg b/docs/.images/Zarf Left Underwater - Behind rock.svg new file mode 100644 index 0000000000..159ca1cd96 --- /dev/null +++ b/docs/.images/Zarf Left Underwater - Behind rock.svg @@ -0,0 +1,732 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/.images/architecture.drawio.svg b/docs/.images/architecture.drawio.svg new file mode 100644 index 0000000000..faac38e53a --- /dev/null +++ b/docs/.images/architecture.drawio.svg @@ -0,0 +1,4 @@ + + + +
ns
ns
zarf-state
zarf-sta...
NodePort
31999
NodePort...
zarf
zarf
pvc
pvc
pv
pv
sc
sc
clusterip
svc
clusteri...
rs
rs
deploy
deploy
Zarf Gitops Service
Zarf Gitops Service
pod
pod
nodeport
svc
nodeport...
Zarf Injector
Zarf Injector
pod
from existing
image
pod...
Dynamic configmaps:
n = tarball size / 512 KB
Dynamic configmaps:...
Dynamic
NodePort
Dynamic...
Images updated to use 127.0.0.1:31999 and the Registry NodePort service
Images updated to use 127.0.0.1:3...
4. (Optional) Deploy the Zarf Gitops Service
4. (Optional) Deploy the Zarf Gitops Service
1. Create the Zarf State in the cluster
1. Create the Zarf State in the cluster
3. Deploy the Zarf Registry
3. Deploy the Zarf Registry
pod
pod
pvc
pvc
pv
pv
sc
sc
nodeport
svc
nodeport...
rs
rs
deploy
deploy
Zarf Registry 
Zarf Registry 
2. Launch the injector system
2. Launch the injector system
Zarf Resource
Zarf Resource
Zarf Temporary Resource
Zarf Temporary Resource
Zarf-Managed Resource
Zarf-Managed Resource
Zarf CLI to Cluster Comms
Zarf CLI to Cluster Comms
Image Pull From Zarf Registry
Image Pull From Zarf Registry
Standard K8s Comms
Standard K8s Comms
Standard K8s Controller Comms
Standard K8s Controller Comms
initial image pulled from zarf-injector nodeport
initial image pulled from zarf-injector nodeport
Post registry boot all images pull from the registry     
Post registry boot all images pull from the registry     
ns
ns
ns
ns
pod
pod
rs
rs
deploy
deploy
Zarf-Managed Deployments
Zarf-Managed Deployments
ns
ns
5. Deploy the Helm/Kustomize/raw YAML
5. Deploy the Helm/Kustomize/raw YAML
https://github.com/defenseunicorns/zarf
https://github.com/defenseunicorns/zarfText is not SVG - cannot display diff --git a/docs/.images/favicon.svg b/docs/.images/favicon.svg new file mode 100644 index 0000000000..2fc8794d16 --- /dev/null +++ b/docs/.images/favicon.svg @@ -0,0 +1,97 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/0-zarf-overview.md b/docs/0-zarf-overview.md new file mode 100644 index 0000000000..255587c245 --- /dev/null +++ b/docs/0-zarf-overview.md @@ -0,0 +1,78 @@ +import TabItem from "@theme/TabItem"; +import Tabs from "@theme/Tabs"; + +# Overview + +![Zarf Underwater](.images/Zarf%20Left%20Underwater%20-%20Behind%20rock.svg) + +## What is Zarf? + +Zarf is an open-source tool that simplifies the setup & deployment of applications and resources onto AirGap or disconnected environments. You can think of a disconnected environment as a system that has the has limited connection to the internet, kind of like airplane mode. + +Zarf equips you with the ability to quickly and securely deploy modern software onto these types of systems without relying on internet connectivity. It also simplifies the installation, updating, and maintenance of DevSecOps capabilities like Kubernetes clusters, logging, and SBOM compliance out of the box. Most importantly Zarf keeps applications and systems running even when they are disconnected. + +## How Zarf works? + +Zarf uses a static Go binary CLI that can be run on any machine, with or without internet connectivity. The Zarf CLI equips users with the ability to pull, package, and install all the resources their applications or clusters need to run without being connected to the internet. It can also deploy any necessary resources needed to stand up infrastructure tools (such as Terraform). + +All that is needed to deploy your infrastructure, application, and resources in a disconnected environment is 3 files; the Zarf CLI binary, the Zarf init package, and a Zarf Package containing your app and resources. + +![Zarf CLI + Zarf Init + Zarf Package](.images/Zarf%20Files%20-%20%203%20Bubbles.svg) + +:::note + +For more information on how zarf works under the hood visit our [Nerd Notes page](./6-developer-guide/3-nerd-notes.md) + +::: + +## Why Use Zarf? + +- 💸 **Free and Open Source.** Zarf will always be free to use and maintained by the open source community. +- 🔓 **No Vender Lock.** There is no proprietary software that locks you into using Zarf. If you want to remove it, you still can use your help charts to deploy your software manually. +- 💻 **OS Agnostic.** Zarf supports numerous operating systems.For a full list, visit the [Supported OSes](./5-operator-manual/90-supported-oses.md) page. +- 📦 **Highly Distributable.** Integrate and deploy software from multiple, secure development environments including edge, embedded systems, secure cloud, data centers, and even local environments. +- 🚀 **Develop Connected Deploy Disconnected.** Teams can build, and configure individual applications or entire DevSecOps environments while connected to the internet and then package and ship them to a disconnected environment to be deployed. +- 💿 **Single File Deployments.** Zarf allows you to package the parts of the internet your app needs into a single compressed file to be installed without connectivity. +- ♻️ **Declarative Deployments.** +- 🦖 **Inherit Legacy Code** + +## Quick Start + +:::info + +This quick start requires you to already have [home brew](https://brew.sh/) package manager installed on your machine. +For more install options please visit our [Getting Started page](3-getting-started.md) + +::: + +To download the Zarf CLI Binary, + +1. Select your systems OS below +2. copy and past the quick start command into your computers terminal. + + + + +```bash +brew tap defenseunicorns/tap +brew install zarf +``` + + + + +```bash +brew tap defenseunicorns/tap +brew install zarf +``` + + + + +```bash +Coming Soon! +``` + + + + diff --git a/docs/1-understand-the-basics.md b/docs/1-understand-the-basics.md new file mode 100644 index 0000000000..b55adf7e19 --- /dev/null +++ b/docs/1-understand-the-basics.md @@ -0,0 +1,27 @@ +# Understand The Basics + +Before you are able to effectively use Zarf, it is would be useful to have an underlying understanding of the technology Zarf is built on/around. The section below provides some helpful links to start build up this foundation. + +:::caution Hard Hat Area +This page is still being developed. More content will be added soon! +::: + + + + +
+
+ +## What is Kubernetes? + - [Kubernetes Overview](https://kubernetes.io/docs/concepts/overview/) +
+
+ +## What is the 'Air Gap'? + + +
+
+ +## What is GitOps? + - [CloudBees GitOps Definition](https://www.cloudbees.com/gitops/what-is-gitops) diff --git a/docs/10-roadmap.md b/docs/10-roadmap.md new file mode 100644 index 0000000000..ced1cd60a3 --- /dev/null +++ b/docs/10-roadmap.md @@ -0,0 +1,21 @@ +# Roadmap + +:::caution Hard Hat Area +This page is still being developed. More content will be added soon! +::: + +## Roadmap +The project roadmap for Zarf is hosted on a [GitHub Project Board](https://github.com/orgs/defenseunicorns/projects/1). There, you can see what we're working on and what work we're prioritizing. + +If you want to add your own bug reports or feature requests to be considered on our roadmap, please feel free [add an issue](https://github.com/defenseunicorns/zarf/issues) on the GitHub repository. + +
+ +## GA Release +Right now, Zarf is still in its 'beta' phase. We are working on a few final things before we release the official 1.0 general availability (GA) release. The current planned date for the GA release is mid June 2022. The work still needed for the GA release can be found on the roadmap with [this filter](https://github.com/orgs/defenseunicorns/projects/1/views/1?filterQuery=repo%3A%22defenseunicorns%2Fzarf%22+milestone%3A%22zarf+ga%22). + + + + + + \ No newline at end of file diff --git a/docs/11-community.md b/docs/11-community.md new file mode 100644 index 0000000000..73d05a667e --- /dev/null +++ b/docs/11-community.md @@ -0,0 +1,12 @@ +# Community + +:::caution Hard Hat Area +This page is still being developed. More content will be added soon! +::: + +- You can find us in the k8s slack in the [#zarf](https://kubernetes.slack.com/archives/C03B6BJAUJ3) channel or the [#zarf-dev](https://kubernetes.slack.com/archives/C03BP9Z3CMA) channel. +- The Zarf repository is hosted on [GitHub](https://github.com/defenseunicorns/zarf) +- [Zarf LinkedIn Project](https://www.linkedin.com/company/zarf-project/) + + + diff --git a/docs/12-support.md b/docs/12-support.md new file mode 100644 index 0000000000..279f6d80af --- /dev/null +++ b/docs/12-support.md @@ -0,0 +1,6 @@ +# Support + +1. Make sure you've read the [Zarf Overview](./zarf-overview), [Understanding the Basics](./understand-the-basics), and the [Getting Started](./getting-started) guides. +2. Look for an answer in [the frequently asked questions](./faq). +3. Ask a question in [the Zarf Slack Channel](https://kubernetes.slack.com/archives/C03B6BJAUJ3) +4. [Read issues, report a bug, or rquest a new feature](https://github.com/defenseunicorns/zarf/issues) \ No newline at end of file diff --git a/docs/13-walkthroughs.md b/docs/13-walkthroughs.md new file mode 100644 index 0000000000..34b3e98388 --- /dev/null +++ b/docs/13-walkthroughs.md @@ -0,0 +1,6 @@ +# Walkthroughs + +:::caution Hard Hat Area +This page is still being developed. More content will be added soon! +::: + diff --git a/docs/2-core-concepts.md b/docs/2-core-concepts.md new file mode 100644 index 0000000000..401d09c588 --- /dev/null +++ b/docs/2-core-concepts.md @@ -0,0 +1,10 @@ +# Core Concepts + +:::caution Hard Hat Area +This page is still being developed. More content will be added soon! +::: + +Now, assuming you're familiar with Kubernetes, the AirGap, and GitOps, we can get started on the core concepts of Zarf. + +- **Package** - A binary files that contains the instructions and dependencies necessary to install an application on a system. +- **Component** - A set of defined functionality and resources that build up a package. diff --git a/docs/3-getting-started.md b/docs/3-getting-started.md new file mode 100644 index 0000000000..6850a31d4d --- /dev/null +++ b/docs/3-getting-started.md @@ -0,0 +1,75 @@ +# Getting Started + +Welcome to the documentation about Zarf, the air-gap tool! Let's get you started down your Zarfing journey! + +## Installing Zarf + +There are multiple ways to get the Zarf CLI onto your machine including installing from the Defense Unicorns Homebrew Tap, downloading a prebuilt binary from our GitHub releases, or even building the CLI from scratch yourself. + +### Installing from the Defense Unicorns Homebrew Tap + +[Homebrew](https://brew.sh/) is an open-source software package manager that simplifies the installation of software on macOS and Linux. With Homebrew, installing Zarf is super simple! + +```bash +brew tap defenseunicorns/tap +brew install zarf +``` + +The above command detects your OS and system architecture and installs the correct Zarf CLI binary for your machine. Thanks to the magic of Homebrew, the CLI should be installed onto your $PATH and ready for immediate use. + +### Downloading a prebuilt binary from our GitHub releases + +All [Zarf releases](https://github.com/defenseunicorns/zarf/releases) on GitHub include prebuilt binaries that you can download and use. We offer a small range of combinations of OS and architecture for you to choose from. Once downloaded, you can install the binary onto your $PATH by moving the binary to the `/usr/local/bin` directory. + +```bash +mv ./path/to/downloaded/{ZARF_FILE} /usr/local/bin/zarf +``` + +### Building the CLI from scratch + +If you want to build the CLI from scratch, you can do that too! Our local builds depend on [Go 1.18.x](https://golang.org/doc/install) and are built using [make](https://www.gnu.org/software/make/). + +```bash +git clone git@github.com:defenseunicorns/zarf.git +cd zarf +make build-cli # This builds all combinations of OS and architecture +mv ./build/{ZARF_FILE} /usr/local/bin/zarf +``` + +:::note +The `make build-cli` command builds a binary for each combinations of OS and architecture. If you want to shorten the build time, you can use an alternative command to only build the binary you need: + +- `make build-cli-mac-intel` +- `make build-cli-mac-apple` +- `make build-cli-linux-amd` +- `make build-cli-linux-arm` + ::: + +
+ +## Verifying Zarf Install + +Now that you have installed Zarf onto your path, let's verify that it is working by checking two things! First, we'll check the version of Zarf that has been installed with the command: + +```bash +zarf version + +# Expected output should look similar to the following +vX.X.X # X.X.X is replaced with the version number of your specific installation +``` + +If you are not seeing that, then it's possible that Zarf was not installed onto your $PATH, [this $PATH guide](https://zwbetz.com/how-to-add-a-binary-to-your-path-on-macos-linux-windows/) should help with that. + +
+ +## Where to next? + +Depending on how familiar you are with Kubernetes, DevOps, and Zarf, let's find what set of information would be most useful to you! + +- If you want to dive straight into Zarf, you can find examples and guides in the [Walkthroughs](./walkthroughs) page. + +- More information about the Zarf CLI is available in the [Zarf CLI](./user-guide/the-zarf-cli) page, or by browsing through the help descriptions of all the commands available through `zarf --help`. + +- More information about the packages that Zarf create and deploy is available in the [Understanding Zarf Packages](./user-guide/zarf-packages/zarf-packages) page. + +- If you want to take a step back and better understand the problem Zarf is trying to solve, you can find more context in the [Understand the Basics](./understand-the-basics) and [Core Concepts](./core-concepts) page. diff --git a/docs/4-user-guide/1-the-zarf-cli/1-building-your-own-cli.md b/docs/4-user-guide/1-the-zarf-cli/1-building-your-own-cli.md new file mode 100644 index 0000000000..d62a5fbcd5 --- /dev/null +++ b/docs/4-user-guide/1-the-zarf-cli/1-building-your-own-cli.md @@ -0,0 +1,42 @@ +# Building Your Own Zarf CLI + +:::note +As mentioned in the [Getting Started page](../../getting-started), a pre-compiled binary is available for arm64 and amd64 machines under the 'Assets' tab of our latest releases on [GitHub](https://github.com/defenseunicorns/zarf/releases). If you don't want to build the CLI yourself you could always download it from there. +::: + +## Dependencies + +:::info + +If you want to built the CLI from scratch, you can easily do that! In order to build the cli you will need to make sure you have the following dependencies correctly configured: + +1. The Zarf repository cloned down: + - `git clone git@github.com:defenseunicorns/zarf.git` +2. Have Go 1.18.x installed on your PATH (instructions can be found [here](https://go.dev/doc/install)) +3. `make` utility installed on your PATH (instructions to install w/ Homebrew can be found [here](https://formulae.brew.sh/formula/make)) + +::: + +## Building The CLI + +Once you have the dependencies configured you can build the Zarf CLI by running the following commands: + +```bash +cd zarf # go into the root level of the zarf repository + +make build-cli # This will build binaries for linux, M1 Mac, and Intel Mac machines + # This puts the built binaries in the ./build directory +``` + +:::note Optimization Note +The `make build-cli` command builds a binary for each combinations of OS and architecture. If you want to shorten the build time, you can use an alternative command to only build the binary you need: + +- `make build-cli-mac-intel` +- `make build-cli-mac-apple` +- `make build-cli-linux-amd` +- `make build-cli-linux-arm` + ::: + +#### Breaking Down Whats Happening + +[Under the hood](https://github.com/defenseunicorns/zarf/blob/473cbd5be203bd38254556cf3d55561e5be247dd/Makefile#L44), the make command is executing a `go build .....` command with specific `CGO_ENABLED`, `GOOS`, and `GOARCH` flags depending on the distro and architecture of the system it is building for. The `CLI_VERSION` is passed in as a `ldflag` and is set to whatever the latest tag is in the repository as defined by `git describe --tags`. diff --git a/docs/4-user-guide/1-the-zarf-cli/100-cli-commands/0-zarf.md b/docs/4-user-guide/1-the-zarf-cli/100-cli-commands/0-zarf.md new file mode 100644 index 0000000000..8f78137449 --- /dev/null +++ b/docs/4-user-guide/1-the-zarf-cli/100-cli-commands/0-zarf.md @@ -0,0 +1,29 @@ +# zarf + +Small tool to bundle dependencies with K3s for air-gapped deployments + +``` +zarf [COMMAND]|[ZARF-PACKAGE]|[ZARF-YAML] [flags] +``` + +### Options + +``` + -a, --architecture string Architecture for OCI images + -h, --help help for zarf + -l, --log-level string Log level when running Zarf. Valid options are: warn, info, debug, trace + -t, --toggle Help message for toggle +``` + +### SEE ALSO + +* [zarf completion](./completion) - Generate the autocompletion script for the specified shell +* [zarf connect](./zarf_connect) - Access services or pods deployed in the cluster. +* [zarf destroy](./zarf_destroy) - Tear it all down, we'll miss you Zarf... +* [zarf init](./zarf_init) - Deploys the gitops service or appliance cluster on a clean linux box +* [zarf package](./package) - Pack and unpack updates for the Zarf gitops service. +* [zarf prepare](./prepare) - Tools to help prepare assets for packaging +* [zarf tools](./tools) - Collection of additional tools to make airgap easier +* [zarf version](./zarf_version) - Displays the version the zarf binary was built from + +###### Auto generated by spf13/cobra on 20-May-2022 diff --git a/docs/4-user-guide/1-the-zarf-cli/100-cli-commands/2-package/index.md b/docs/4-user-guide/1-the-zarf-cli/100-cli-commands/2-package/index.md new file mode 100644 index 0000000000..a09e849d8e --- /dev/null +++ b/docs/4-user-guide/1-the-zarf-cli/100-cli-commands/2-package/index.md @@ -0,0 +1,25 @@ +# zarf package + +Pack and unpack updates for the Zarf gitops service. + +### Options + +``` + -h, --help help for package +``` + +### Options inherited from parent commands + +``` + -a, --architecture string Architecture for OCI images + -l, --log-level string Log level when running Zarf. Valid options are: warn, info, debug, trace +``` + +### SEE ALSO + +* [zarf](../zarf) - Small tool to bundle dependencies with K3s for air-gapped deployments +* [zarf package create](./zarf_package_create) - Create an update package to push to the gitops server (runs online) +* [zarf package deploy](./zarf_package_deploy) - Deploys an update package from a local file or URL (runs offline) +* [zarf package inspect](./zarf_package_inspect) - lists the payload of an update package file (runs offline) + +###### Auto generated by spf13/cobra on 20-May-2022 diff --git a/docs/4-user-guide/1-the-zarf-cli/100-cli-commands/2-package/zarf_package_create.md b/docs/4-user-guide/1-the-zarf-cli/100-cli-commands/2-package/zarf_package_create.md new file mode 100644 index 0000000000..ed68565cc8 --- /dev/null +++ b/docs/4-user-guide/1-the-zarf-cli/100-cli-commands/2-package/zarf_package_create.md @@ -0,0 +1,29 @@ +# zarf package create + +Create an update package to push to the gitops server (runs online) + +``` +zarf package create [flags] +``` + +### Options + +``` + --confirm Confirm package creation without prompting + -h, --help help for create + --skip-sbom Skip generating SBOM for this package + --zarf-cache string Specify the location of the Zarf image cache (default ".zarf-image-cache") +``` + +### Options inherited from parent commands + +``` + -a, --architecture string Architecture for OCI images + -l, --log-level string Log level when running Zarf. Valid options are: warn, info, debug, trace +``` + +### SEE ALSO + +* [zarf package](./) - Pack and unpack updates for the Zarf gitops service. + +###### Auto generated by spf13/cobra on 20-May-2022 diff --git a/docs/4-user-guide/1-the-zarf-cli/100-cli-commands/2-package/zarf_package_deploy.md b/docs/4-user-guide/1-the-zarf-cli/100-cli-commands/2-package/zarf_package_deploy.md new file mode 100644 index 0000000000..d865800627 --- /dev/null +++ b/docs/4-user-guide/1-the-zarf-cli/100-cli-commands/2-package/zarf_package_deploy.md @@ -0,0 +1,30 @@ +# zarf package deploy + +Deploys an update package from a local file or URL (runs offline) + +``` +zarf package deploy [PACKAGE] [flags] +``` + +### Options + +``` + --components string Comma-separated list of components to install. Adding this flag will skip the init prompts for which components to install + --confirm Confirm package deployment without prompting + -h, --help help for deploy + --insecure --shasum Skip shasum validation of remote package. Required if deploying a remote package and --shasum is not provided + --shasum --insecure Shasum of the package to deploy. Required if deploying a remote package and --insecure is not provided +``` + +### Options inherited from parent commands + +``` + -a, --architecture string Architecture for OCI images + -l, --log-level string Log level when running Zarf. Valid options are: warn, info, debug, trace +``` + +### SEE ALSO + +* [zarf package](./) - Pack and unpack updates for the Zarf gitops service. + +###### Auto generated by spf13/cobra on 20-May-2022 diff --git a/docs/4-user-guide/1-the-zarf-cli/100-cli-commands/2-package/zarf_package_inspect.md b/docs/4-user-guide/1-the-zarf-cli/100-cli-commands/2-package/zarf_package_inspect.md new file mode 100644 index 0000000000..fa36fd5499 --- /dev/null +++ b/docs/4-user-guide/1-the-zarf-cli/100-cli-commands/2-package/zarf_package_inspect.md @@ -0,0 +1,26 @@ +# zarf package inspect + +lists the payload of an update package file (runs offline) + +``` +zarf package inspect [PACKAGE] [flags] +``` + +### Options + +``` + -h, --help help for inspect +``` + +### Options inherited from parent commands + +``` + -a, --architecture string Architecture for OCI images + -l, --log-level string Log level when running Zarf. Valid options are: warn, info, debug, trace +``` + +### SEE ALSO + +* [zarf package](./) - Pack and unpack updates for the Zarf gitops service. + +###### Auto generated by spf13/cobra on 20-May-2022 diff --git a/docs/4-user-guide/1-the-zarf-cli/100-cli-commands/3-tools/archiver/index.md b/docs/4-user-guide/1-the-zarf-cli/100-cli-commands/3-tools/archiver/index.md new file mode 100644 index 0000000000..8900cb533c --- /dev/null +++ b/docs/4-user-guide/1-the-zarf-cli/100-cli-commands/3-tools/archiver/index.md @@ -0,0 +1,24 @@ +# zarf tools archiver + +Compress/Decompress tools + +### Options + +``` + -h, --help help for archiver +``` + +### Options inherited from parent commands + +``` + -a, --architecture string Architecture for OCI images + -l, --log-level string Log level when running Zarf. Valid options are: warn, info, debug, trace +``` + +### SEE ALSO + +* [zarf tools](../) - Collection of additional tools to make airgap easier +* [zarf tools archiver compress](zarf_tools_archiver_compress.md) - Compress a collection of sources based off of the destination file extension +* [zarf tools archiver decompress](zarf_tools_archiver_decompress.md) - Decompress an archive to a specified location. + +###### Auto generated by spf13/cobra on 20-May-2022 diff --git a/docs/4-user-guide/1-the-zarf-cli/100-cli-commands/3-tools/archiver/zarf_tools_archiver_compress.md b/docs/4-user-guide/1-the-zarf-cli/100-cli-commands/3-tools/archiver/zarf_tools_archiver_compress.md new file mode 100644 index 0000000000..86fb2cf616 --- /dev/null +++ b/docs/4-user-guide/1-the-zarf-cli/100-cli-commands/3-tools/archiver/zarf_tools_archiver_compress.md @@ -0,0 +1,26 @@ +# zarf tools archiver compress + +Compress a collection of sources based off of the destination file extension + +``` +zarf tools archiver compress [SOURCES] [ARCHIVE] [flags] +``` + +### Options + +``` + -h, --help help for compress +``` + +### Options inherited from parent commands + +``` + -a, --architecture string Architecture for OCI images + -l, --log-level string Log level when running Zarf. Valid options are: warn, info, debug, trace +``` + +### SEE ALSO + +* [zarf tools archiver](./) - Compress/Decompress tools + +###### Auto generated by spf13/cobra on 20-May-2022 diff --git a/docs/4-user-guide/1-the-zarf-cli/100-cli-commands/3-tools/archiver/zarf_tools_archiver_decompress.md b/docs/4-user-guide/1-the-zarf-cli/100-cli-commands/3-tools/archiver/zarf_tools_archiver_decompress.md new file mode 100644 index 0000000000..091dd8e9c2 --- /dev/null +++ b/docs/4-user-guide/1-the-zarf-cli/100-cli-commands/3-tools/archiver/zarf_tools_archiver_decompress.md @@ -0,0 +1,26 @@ +# zarf tools archiver decompress + +Decompress an archive to a specified location. + +``` +zarf tools archiver decompress [ARCHIVE] [DESTINATION] [flags] +``` + +### Options + +``` + -h, --help help for decompress +``` + +### Options inherited from parent commands + +``` + -a, --architecture string Architecture for OCI images + -l, --log-level string Log level when running Zarf. Valid options are: warn, info, debug, trace +``` + +### SEE ALSO + +* [zarf tools archiver](./) - Compress/Decompress tools + +###### Auto generated by spf13/cobra on 20-May-2022 diff --git a/docs/4-user-guide/1-the-zarf-cli/100-cli-commands/3-tools/index.md b/docs/4-user-guide/1-the-zarf-cli/100-cli-commands/3-tools/index.md new file mode 100644 index 0000000000..d808834d44 --- /dev/null +++ b/docs/4-user-guide/1-the-zarf-cli/100-cli-commands/3-tools/index.md @@ -0,0 +1,27 @@ +# zarf tools + +Collection of additional tools to make airgap easier + +### Options + +``` + -h, --help help for tools +``` + +### Options inherited from parent commands + +``` + -a, --architecture string Architecture for OCI images + -l, --log-level string Log level when running Zarf. Valid options are: warn, info, debug, trace +``` + +### SEE ALSO + +* [zarf](../zarf) - Small tool to bundle dependencies with K3s for air-gapped deployments +* [zarf tools archiver](./archiver) - Compress/Decompress tools +* [zarf tools config-schema](./zarf_tools_config-schema) - Generates a JSON schema for the zarf.yaml configuration +* [zarf tools get-admin-password](./zarf_tools_get-admin-password) - Returns the Zarf admin password for gitea read from the zarf-state secret in the zarf namespace +* [zarf tools monitor](./zarf_tools_monitor) - Launch K9s tool for managing K8s clusters +* [zarf tools registry](./registry) - Collection of registry commands provided by Crane + +###### Auto generated by spf13/cobra on 20-May-2022 diff --git a/docs/4-user-guide/1-the-zarf-cli/100-cli-commands/3-tools/registry/index.md b/docs/4-user-guide/1-the-zarf-cli/100-cli-commands/3-tools/registry/index.md new file mode 100644 index 0000000000..4ed8142811 --- /dev/null +++ b/docs/4-user-guide/1-the-zarf-cli/100-cli-commands/3-tools/registry/index.md @@ -0,0 +1,27 @@ +# zarf tools registry + +Collection of registry commands provided by Crane + +### Options + +``` + -h, --help help for registry +``` + +### Options inherited from parent commands + +``` + -a, --architecture string Architecture for OCI images + -l, --log-level string Log level when running Zarf. Valid options are: warn, info, debug, trace +``` + +### SEE ALSO + +* [zarf tools](../) - Collection of additional tools to make airgap easier +* [zarf tools registry catalog](zarf_tools_registry_catalog.md) - List the repos in a registry +* [zarf tools registry copy](zarf_tools_registry_copy.md) - Efficiently copy a remote image from src to dst while retaining the digest value +* [zarf tools registry login](zarf_tools_registry_login.md) - Log in to a registry +* [zarf tools registry pull](zarf_tools_registry_pull.md) - Pull remote images by reference and store their contents locally +* [zarf tools registry push](zarf_tools_registry_push.md) - Push local image contents to a remote registry + +###### Auto generated by spf13/cobra on 20-May-2022 diff --git a/docs/4-user-guide/1-the-zarf-cli/100-cli-commands/3-tools/registry/zarf_tools_registry_catalog.md b/docs/4-user-guide/1-the-zarf-cli/100-cli-commands/3-tools/registry/zarf_tools_registry_catalog.md new file mode 100644 index 0000000000..2e6404691d --- /dev/null +++ b/docs/4-user-guide/1-the-zarf-cli/100-cli-commands/3-tools/registry/zarf_tools_registry_catalog.md @@ -0,0 +1,26 @@ +# zarf tools registry catalog + +List the repos in a registry + +``` +zarf tools registry catalog [flags] +``` + +### Options + +``` + -h, --help help for catalog +``` + +### Options inherited from parent commands + +``` + -a, --architecture string Architecture for OCI images + -l, --log-level string Log level when running Zarf. Valid options are: warn, info, debug, trace +``` + +### SEE ALSO + +* [zarf tools registry](./) - Collection of registry commands provided by Crane + +###### Auto generated by spf13/cobra on 20-May-2022 diff --git a/docs/4-user-guide/1-the-zarf-cli/100-cli-commands/3-tools/registry/zarf_tools_registry_copy.md b/docs/4-user-guide/1-the-zarf-cli/100-cli-commands/3-tools/registry/zarf_tools_registry_copy.md new file mode 100644 index 0000000000..0391c1e761 --- /dev/null +++ b/docs/4-user-guide/1-the-zarf-cli/100-cli-commands/3-tools/registry/zarf_tools_registry_copy.md @@ -0,0 +1,26 @@ +# zarf tools registry copy + +Efficiently copy a remote image from src to dst while retaining the digest value + +``` +zarf tools registry copy SRC DST [flags] +``` + +### Options + +``` + -h, --help help for copy +``` + +### Options inherited from parent commands + +``` + -a, --architecture string Architecture for OCI images + -l, --log-level string Log level when running Zarf. Valid options are: warn, info, debug, trace +``` + +### SEE ALSO + +* [zarf tools registry](./) - Collection of registry commands provided by Crane + +###### Auto generated by spf13/cobra on 20-May-2022 diff --git a/docs/4-user-guide/1-the-zarf-cli/100-cli-commands/3-tools/registry/zarf_tools_registry_login.md b/docs/4-user-guide/1-the-zarf-cli/100-cli-commands/3-tools/registry/zarf_tools_registry_login.md new file mode 100644 index 0000000000..d2d21719c4 --- /dev/null +++ b/docs/4-user-guide/1-the-zarf-cli/100-cli-commands/3-tools/registry/zarf_tools_registry_login.md @@ -0,0 +1,36 @@ +# zarf tools registry login + +Log in to a registry + +``` +zarf tools registry login [OPTIONS] [SERVER] [flags] +``` + +### Examples + +``` + # Log in to reg.example.com + zarf-mac-intel login reg.example.com -u AzureDiamond -p hunter2 +``` + +### Options + +``` + -h, --help help for login + -p, --password string Password + --password-stdin Take the password from stdin + -u, --username string Username +``` + +### Options inherited from parent commands + +``` + -a, --architecture string Architecture for OCI images + -l, --log-level string Log level when running Zarf. Valid options are: warn, info, debug, trace +``` + +### SEE ALSO + +* [zarf tools registry](./) - Collection of registry commands provided by Crane + +###### Auto generated by spf13/cobra on 20-May-2022 diff --git a/docs/4-user-guide/1-the-zarf-cli/100-cli-commands/3-tools/registry/zarf_tools_registry_pull.md b/docs/4-user-guide/1-the-zarf-cli/100-cli-commands/3-tools/registry/zarf_tools_registry_pull.md new file mode 100644 index 0000000000..ed6a80aa35 --- /dev/null +++ b/docs/4-user-guide/1-the-zarf-cli/100-cli-commands/3-tools/registry/zarf_tools_registry_pull.md @@ -0,0 +1,28 @@ +# zarf tools registry pull + +Pull remote images by reference and store their contents locally + +``` +zarf tools registry pull IMAGE TARBALL [flags] +``` + +### Options + +``` + -c, --cache_path string Path to cache image layers + --format string Format in which to save images ("tarball", "legacy", or "oci") (default "tarball") + -h, --help help for pull +``` + +### Options inherited from parent commands + +``` + -a, --architecture string Architecture for OCI images + -l, --log-level string Log level when running Zarf. Valid options are: warn, info, debug, trace +``` + +### SEE ALSO + +* [zarf tools registry](./) - Collection of registry commands provided by Crane + +###### Auto generated by spf13/cobra on 20-May-2022 diff --git a/docs/4-user-guide/1-the-zarf-cli/100-cli-commands/3-tools/registry/zarf_tools_registry_push.md b/docs/4-user-guide/1-the-zarf-cli/100-cli-commands/3-tools/registry/zarf_tools_registry_push.md new file mode 100644 index 0000000000..94faf5630d --- /dev/null +++ b/docs/4-user-guide/1-the-zarf-cli/100-cli-commands/3-tools/registry/zarf_tools_registry_push.md @@ -0,0 +1,32 @@ +# zarf tools registry push + +Push local image contents to a remote registry + +### Synopsis + +If the PATH is a directory, it will be read as an OCI image layout. Otherwise, PATH is assumed to be a docker-style tarball. + +``` +zarf tools registry push PATH IMAGE [flags] +``` + +### Options + +``` + -h, --help help for push + --image-refs string path to file where a list of the published image references will be written + --index push a collection of images as a single index, currently required if PATH contains multiple images +``` + +### Options inherited from parent commands + +``` + -a, --architecture string Architecture for OCI images + -l, --log-level string Log level when running Zarf. Valid options are: warn, info, debug, trace +``` + +### SEE ALSO + +* [zarf tools registry](./) - Collection of registry commands provided by Crane + +###### Auto generated by spf13/cobra on 20-May-2022 diff --git a/docs/4-user-guide/1-the-zarf-cli/100-cli-commands/3-tools/zarf_tools_config-schema.md b/docs/4-user-guide/1-the-zarf-cli/100-cli-commands/3-tools/zarf_tools_config-schema.md new file mode 100644 index 0000000000..635bcb5c4d --- /dev/null +++ b/docs/4-user-guide/1-the-zarf-cli/100-cli-commands/3-tools/zarf_tools_config-schema.md @@ -0,0 +1,26 @@ +# zarf tools config-schema + +Generates a JSON schema for the zarf.yaml configuration + +``` +zarf tools config-schema [flags] +``` + +### Options + +``` + -h, --help help for config-schema +``` + +### Options inherited from parent commands + +``` + -a, --architecture string Architecture for OCI images + -l, --log-level string Log level when running Zarf. Valid options are: warn, info, debug, trace +``` + +### SEE ALSO + +* [zarf tools](./) - Collection of additional tools to make airgap easier + +###### Auto generated by spf13/cobra on 20-May-2022 diff --git a/docs/4-user-guide/1-the-zarf-cli/100-cli-commands/3-tools/zarf_tools_get-admin-password.md b/docs/4-user-guide/1-the-zarf-cli/100-cli-commands/3-tools/zarf_tools_get-admin-password.md new file mode 100644 index 0000000000..e63fe69c4d --- /dev/null +++ b/docs/4-user-guide/1-the-zarf-cli/100-cli-commands/3-tools/zarf_tools_get-admin-password.md @@ -0,0 +1,26 @@ +# zarf tools get-admin-password + +Returns the Zarf admin password for gitea read from the zarf-state secret in the zarf namespace + +``` +zarf tools get-admin-password [flags] +``` + +### Options + +``` + -h, --help help for get-admin-password +``` + +### Options inherited from parent commands + +``` + -a, --architecture string Architecture for OCI images + -l, --log-level string Log level when running Zarf. Valid options are: warn, info, debug, trace +``` + +### SEE ALSO + +* [zarf tools](./) - Collection of additional tools to make airgap easier + +###### Auto generated by spf13/cobra on 20-May-2022 diff --git a/docs/4-user-guide/1-the-zarf-cli/100-cli-commands/3-tools/zarf_tools_monitor.md b/docs/4-user-guide/1-the-zarf-cli/100-cli-commands/3-tools/zarf_tools_monitor.md new file mode 100644 index 0000000000..4d63e37256 --- /dev/null +++ b/docs/4-user-guide/1-the-zarf-cli/100-cli-commands/3-tools/zarf_tools_monitor.md @@ -0,0 +1,26 @@ +# zarf tools monitor + +Launch K9s tool for managing K8s clusters + +``` +zarf tools monitor [flags] +``` + +### Options + +``` + -h, --help help for monitor +``` + +### Options inherited from parent commands + +``` + -a, --architecture string Architecture for OCI images + -l, --log-level string Log level when running Zarf. Valid options are: warn, info, debug, trace +``` + +### SEE ALSO + +* [zarf tools](./) - Collection of additional tools to make airgap easier + +###### Auto generated by spf13/cobra on 20-May-2022 diff --git a/docs/4-user-guide/1-the-zarf-cli/100-cli-commands/4-completion/index.md b/docs/4-user-guide/1-the-zarf-cli/100-cli-commands/4-completion/index.md new file mode 100644 index 0000000000..33e1c1ce48 --- /dev/null +++ b/docs/4-user-guide/1-the-zarf-cli/100-cli-commands/4-completion/index.md @@ -0,0 +1,32 @@ +# zarf completion + +Generate the autocompletion script for the specified shell + +### Synopsis + +Generate the autocompletion script for zarf for the specified shell. +See each sub-command's help for details on how to use the generated script. + + +### Options + +``` + -h, --help help for completion +``` + +### Options inherited from parent commands + +``` + -a, --architecture string Architecture for OCI images + -l, --log-level string Log level when running Zarf. Valid options are: warn, info, debug, trace +``` + +### SEE ALSO + +* [zarf](../zarf) - Small tool to bundle dependencies with K3s for air-gapped deployments +* [zarf completion bash](./zarf_completion_bash) - Generate the autocompletion script for bash +* [zarf completion fish](./zarf_completion_fish) - Generate the autocompletion script for fish +* [zarf completion powershell](./zarf_completion_powershell) - Generate the autocompletion script for powershell +* [zarf completion zsh](./zarf_completion_zsh) - Generate the autocompletion script for zsh + +###### Auto generated by spf13/cobra on 20-May-2022 diff --git a/docs/4-user-guide/1-the-zarf-cli/100-cli-commands/4-completion/zarf_completion_bash.md b/docs/4-user-guide/1-the-zarf-cli/100-cli-commands/4-completion/zarf_completion_bash.md new file mode 100644 index 0000000000..ed6a2966b4 --- /dev/null +++ b/docs/4-user-guide/1-the-zarf-cli/100-cli-commands/4-completion/zarf_completion_bash.md @@ -0,0 +1,51 @@ +# zarf completion bash + +Generate the autocompletion script for bash + +### Synopsis + +Generate the autocompletion script for the bash shell. + +This script depends on the 'bash-completion' package. +If it is not installed already, you can install it via your OS's package manager. + +To load completions in your current shell session: + + source <(zarf completion bash) + +To load completions for every new session, execute once: + +#### Linux: + + zarf completion bash > /etc/bash_completion.d/zarf + +#### macOS: + + zarf completion bash > /usr/local/etc/bash_completion.d/zarf + +You will need to start a new shell for this setup to take effect. + + +``` +zarf completion bash +``` + +### Options + +``` + -h, --help help for bash + --no-descriptions disable completion descriptions +``` + +### Options inherited from parent commands + +``` + -a, --architecture string Architecture for OCI images + -l, --log-level string Log level when running Zarf. Valid options are: warn, info, debug, trace +``` + +### SEE ALSO + +* [zarf completion](./) - Generate the autocompletion script for the specified shell + +###### Auto generated by spf13/cobra on 20-May-2022 diff --git a/docs/4-user-guide/1-the-zarf-cli/100-cli-commands/4-completion/zarf_completion_fish.md b/docs/4-user-guide/1-the-zarf-cli/100-cli-commands/4-completion/zarf_completion_fish.md new file mode 100644 index 0000000000..ab4d65da00 --- /dev/null +++ b/docs/4-user-guide/1-the-zarf-cli/100-cli-commands/4-completion/zarf_completion_fish.md @@ -0,0 +1,42 @@ +# zarf completion fish + +Generate the autocompletion script for fish + +### Synopsis + +Generate the autocompletion script for the fish shell. + +To load completions in your current shell session: + + zarf completion fish | source + +To load completions for every new session, execute once: + + zarf completion fish > ~/.config/fish/completions/zarf.fish + +You will need to start a new shell for this setup to take effect. + + +``` +zarf completion fish [flags] +``` + +### Options + +``` + -h, --help help for fish + --no-descriptions disable completion descriptions +``` + +### Options inherited from parent commands + +``` + -a, --architecture string Architecture for OCI images + -l, --log-level string Log level when running Zarf. Valid options are: warn, info, debug, trace +``` + +### SEE ALSO + +* [zarf completion](./) - Generate the autocompletion script for the specified shell + +###### Auto generated by spf13/cobra on 20-May-2022 diff --git a/docs/4-user-guide/1-the-zarf-cli/100-cli-commands/4-completion/zarf_completion_powershell.md b/docs/4-user-guide/1-the-zarf-cli/100-cli-commands/4-completion/zarf_completion_powershell.md new file mode 100644 index 0000000000..67387d6cec --- /dev/null +++ b/docs/4-user-guide/1-the-zarf-cli/100-cli-commands/4-completion/zarf_completion_powershell.md @@ -0,0 +1,39 @@ +# zarf completion powershell + +Generate the autocompletion script for powershell + +### Synopsis + +Generate the autocompletion script for powershell. + +To load completions in your current shell session: + + zarf completion powershell | Out-String | Invoke-Expression + +To load completions for every new session, add the output of the above command +to your powershell profile. + + +``` +zarf completion powershell [flags] +``` + +### Options + +``` + -h, --help help for powershell + --no-descriptions disable completion descriptions +``` + +### Options inherited from parent commands + +``` + -a, --architecture string Architecture for OCI images + -l, --log-level string Log level when running Zarf. Valid options are: warn, info, debug, trace +``` + +### SEE ALSO + +* [zarf completion](./) - Generate the autocompletion script for the specified shell + +###### Auto generated by spf13/cobra on 20-May-2022 diff --git a/docs/4-user-guide/1-the-zarf-cli/100-cli-commands/4-completion/zarf_completion_zsh.md b/docs/4-user-guide/1-the-zarf-cli/100-cli-commands/4-completion/zarf_completion_zsh.md new file mode 100644 index 0000000000..367826824e --- /dev/null +++ b/docs/4-user-guide/1-the-zarf-cli/100-cli-commands/4-completion/zarf_completion_zsh.md @@ -0,0 +1,49 @@ +# zarf completion zsh + +Generate the autocompletion script for zsh + +### Synopsis + +Generate the autocompletion script for the zsh shell. + +If shell completion is not already enabled in your environment you will need +to enable it. You can execute the following once: + + echo "autoload -U compinit; compinit" >> ~/.zshrc + +To load completions for every new session, execute once: + +#### Linux: + + zarf completion zsh > "${fpath[1]}/_zarf" + +#### macOS: + + zarf completion zsh > /usr/local/share/zsh/site-functions/_zarf + +You will need to start a new shell for this setup to take effect. + + +``` +zarf completion zsh [flags] +``` + +### Options + +``` + -h, --help help for zsh + --no-descriptions disable completion descriptions +``` + +### Options inherited from parent commands + +``` + -a, --architecture string Architecture for OCI images + -l, --log-level string Log level when running Zarf. Valid options are: warn, info, debug, trace +``` + +### SEE ALSO + +* [zarf completion](./) - Generate the autocompletion script for the specified shell + +###### Auto generated by spf13/cobra on 20-May-2022 diff --git a/docs/4-user-guide/1-the-zarf-cli/100-cli-commands/5-prepare/index.md b/docs/4-user-guide/1-the-zarf-cli/100-cli-commands/5-prepare/index.md new file mode 100644 index 0000000000..7abf50bc60 --- /dev/null +++ b/docs/4-user-guide/1-the-zarf-cli/100-cli-commands/5-prepare/index.md @@ -0,0 +1,25 @@ +# zarf prepare + +Tools to help prepare assets for packaging + +### Options + +``` + -h, --help help for prepare +``` + +### Options inherited from parent commands + +``` + -a, --architecture string Architecture for OCI images + -l, --log-level string Log level when running Zarf. Valid options are: warn, info, debug, trace +``` + +### SEE ALSO + +* [zarf](../zarf) - Small tool to bundle dependencies with K3s for air-gapped deployments +* [zarf prepare find-images](./zarf_prepare_find-images) - evaluates components in a zarf file to identify images specified in their helm charts and manifests +* [zarf prepare patch-git](./zarf_prepare_patch-git) - Converts all .git URLs to the specified Zarf HOST and with the Zarf URL pattern in a given FILE +* [zarf prepare sha256sum](./zarf_prepare_sha256sum) - Generate a SHA256SUM for the given file + +###### Auto generated by spf13/cobra on 20-May-2022 diff --git a/docs/4-user-guide/1-the-zarf-cli/100-cli-commands/5-prepare/zarf_prepare_find-images.md b/docs/4-user-guide/1-the-zarf-cli/100-cli-commands/5-prepare/zarf_prepare_find-images.md new file mode 100644 index 0000000000..90ba100902 --- /dev/null +++ b/docs/4-user-guide/1-the-zarf-cli/100-cli-commands/5-prepare/zarf_prepare_find-images.md @@ -0,0 +1,27 @@ +# zarf prepare find-images + +evaluates components in a zarf file to identify images specified in their helm charts and manifests + +``` +zarf prepare find-images [flags] +``` + +### Options + +``` + -h, --help help for find-images + -p, --repo-chart-path string If git repos hold helm charts, often found with gitops tools, specify the chart path, e.g. "/" or "/chart" +``` + +### Options inherited from parent commands + +``` + -a, --architecture string Architecture for OCI images + -l, --log-level string Log level when running Zarf. Valid options are: warn, info, debug, trace +``` + +### SEE ALSO + +* [zarf prepare](./) - Tools to help prepare assets for packaging + +###### Auto generated by spf13/cobra on 20-May-2022 diff --git a/docs/4-user-guide/1-the-zarf-cli/100-cli-commands/5-prepare/zarf_prepare_patch-git.md b/docs/4-user-guide/1-the-zarf-cli/100-cli-commands/5-prepare/zarf_prepare_patch-git.md new file mode 100644 index 0000000000..34f1f53272 --- /dev/null +++ b/docs/4-user-guide/1-the-zarf-cli/100-cli-commands/5-prepare/zarf_prepare_patch-git.md @@ -0,0 +1,26 @@ +# zarf prepare patch-git + +Converts all .git URLs to the specified Zarf HOST and with the Zarf URL pattern in a given FILE + +``` +zarf prepare patch-git [HOST] [FILE] [flags] +``` + +### Options + +``` + -h, --help help for patch-git +``` + +### Options inherited from parent commands + +``` + -a, --architecture string Architecture for OCI images + -l, --log-level string Log level when running Zarf. Valid options are: warn, info, debug, trace +``` + +### SEE ALSO + +* [zarf prepare](./) - Tools to help prepare assets for packaging + +###### Auto generated by spf13/cobra on 20-May-2022 diff --git a/docs/4-user-guide/1-the-zarf-cli/100-cli-commands/5-prepare/zarf_prepare_sha256sum.md b/docs/4-user-guide/1-the-zarf-cli/100-cli-commands/5-prepare/zarf_prepare_sha256sum.md new file mode 100644 index 0000000000..9a8aaf1782 --- /dev/null +++ b/docs/4-user-guide/1-the-zarf-cli/100-cli-commands/5-prepare/zarf_prepare_sha256sum.md @@ -0,0 +1,26 @@ +# zarf prepare sha256sum + +Generate a SHA256SUM for the given file + +``` +zarf prepare sha256sum [FILE|URL] [flags] +``` + +### Options + +``` + -h, --help help for sha256sum +``` + +### Options inherited from parent commands + +``` + -a, --architecture string Architecture for OCI images + -l, --log-level string Log level when running Zarf. Valid options are: warn, info, debug, trace +``` + +### SEE ALSO + +* [zarf prepare](./) - Tools to help prepare assets for packaging + +###### Auto generated by spf13/cobra on 20-May-2022 diff --git a/docs/4-user-guide/1-the-zarf-cli/100-cli-commands/_category_.json b/docs/4-user-guide/1-the-zarf-cli/100-cli-commands/_category_.json new file mode 100644 index 0000000000..8c0ac2aa6c --- /dev/null +++ b/docs/4-user-guide/1-the-zarf-cli/100-cli-commands/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "CLI Commands" + } + \ No newline at end of file diff --git a/docs/4-user-guide/1-the-zarf-cli/100-cli-commands/zarf_connect.md b/docs/4-user-guide/1-the-zarf-cli/100-cli-commands/zarf_connect.md new file mode 100644 index 0000000000..222e1765ec --- /dev/null +++ b/docs/4-user-guide/1-the-zarf-cli/100-cli-commands/zarf_connect.md @@ -0,0 +1,32 @@ +# zarf connect + +Access services or pods deployed in the cluster. + +``` +zarf connect [flags] +``` + +### Options + +``` + --cli-only Disable browser auto-open + -h, --help help for connect + --local-port int (Optional, autogenerated if not provided) Specify the local port to bind to. E.g. local-port=42000 + --name string Specify the resource name. E.g. name=unicorns or name=unicorn-pod-7448499f4d-b5bk6 (default "docker-registry") + --namespace string Specify the namespace. E.g. namespace=default (default "zarf") + --remote-port int Specify the remote port of the resource to bind to. E.g. remote-port=8080 + --type string Specify the resource type. E.g. type=svc or type=pod (default "svc") +``` + +### Options inherited from parent commands + +``` + -a, --architecture string Architecture for OCI images + -l, --log-level string Log level when running Zarf. Valid options are: warn, info, debug, trace +``` + +### SEE ALSO + +* [zarf](./zarf) - Small tool to bundle dependencies with K3s for air-gapped deployments + +###### Auto generated by spf13/cobra on 20-May-2022 diff --git a/docs/4-user-guide/1-the-zarf-cli/100-cli-commands/zarf_destroy.md b/docs/4-user-guide/1-the-zarf-cli/100-cli-commands/zarf_destroy.md new file mode 100644 index 0000000000..bc72df6820 --- /dev/null +++ b/docs/4-user-guide/1-the-zarf-cli/100-cli-commands/zarf_destroy.md @@ -0,0 +1,28 @@ +# zarf destroy + +Tear it all down, we'll miss you Zarf... + +``` +zarf destroy [flags] +``` + +### Options + +``` + --confirm Confirm the destroy action + -h, --help help for destroy + --remove-components Also remove any installed components outside the zarf namespace +``` + +### Options inherited from parent commands + +``` + -a, --architecture string Architecture for OCI images + -l, --log-level string Log level when running Zarf. Valid options are: warn, info, debug, trace +``` + +### SEE ALSO + +* [zarf](./zarf) - Small tool to bundle dependencies with K3s for air-gapped deployments + +###### Auto generated by spf13/cobra on 20-May-2022 diff --git a/docs/4-user-guide/1-the-zarf-cli/100-cli-commands/zarf_init.md b/docs/4-user-guide/1-the-zarf-cli/100-cli-commands/zarf_init.md new file mode 100644 index 0000000000..34681da591 --- /dev/null +++ b/docs/4-user-guide/1-the-zarf-cli/100-cli-commands/zarf_init.md @@ -0,0 +1,35 @@ +# zarf init + +Deploys the gitops service or appliance cluster on a clean linux box + +### Synopsis + +Flags are only required if running via automation, otherwise the init command will prompt you for your configuration choices + +``` +zarf init [flags] +``` + +### Options + +``` + --components string Comma-separated list of components to install. Adding this flag will skip the init prompts for which components to install + --confirm Confirm the install without prompting + -h, --help help for init + --nodeport string Nodeport to access the Zarf container registry. Between [30000-32767] + --secret string Root secret value that is used to 'seed' other secrets + --storage-class string Describe the StorageClass to be used +``` + +### Options inherited from parent commands + +``` + -a, --architecture string Architecture for OCI images + -l, --log-level string Log level when running Zarf. Valid options are: warn, info, debug, trace +``` + +### SEE ALSO + +* [zarf](./zarf) - Small tool to bundle dependencies with K3s for air-gapped deployments + +###### Auto generated by spf13/cobra on 20-May-2022 diff --git a/docs/4-user-guide/1-the-zarf-cli/100-cli-commands/zarf_version.md b/docs/4-user-guide/1-the-zarf-cli/100-cli-commands/zarf_version.md new file mode 100644 index 0000000000..5085b85357 --- /dev/null +++ b/docs/4-user-guide/1-the-zarf-cli/100-cli-commands/zarf_version.md @@ -0,0 +1,26 @@ +# zarf version + +Displays the version the zarf binary was built from + +``` +zarf version [flags] +``` + +### Options + +``` + -h, --help help for version +``` + +### Options inherited from parent commands + +``` + -a, --architecture string Architecture for OCI images + -l, --log-level string Log level when running Zarf. Valid options are: warn, info, debug, trace +``` + +### SEE ALSO + +* [zarf](./zarf) - Small tool to bundle dependencies with K3s for air-gapped deployments + +###### Auto generated by spf13/cobra on 20-May-2022 diff --git a/docs/4-user-guide/1-the-zarf-cli/2-cli-commond-uses.md b/docs/4-user-guide/1-the-zarf-cli/2-cli-commond-uses.md new file mode 100644 index 0000000000..e5e0d085ab --- /dev/null +++ b/docs/4-user-guide/1-the-zarf-cli/2-cli-commond-uses.md @@ -0,0 +1,37 @@ +# Common CLI Uses + +Since the main priority of Zarf is to make deploying applications into disconnected environments easier, almost all of the commands Zarf provides really boil down to making it easier to create and deploy packages. This is especially true with the most commonly used commands; `zarf init`, `zarf package create` and `zarf package deploy`. + + +
+ + +## Building Packages: `zarf package create` +[`zarf package create`](./cli-commands/package/zarf_package_create) is used to create a tar.zst binary file that contains all the necessary dependencies and instructions to deploy a set of functionality onto another machine. We call this tar.zst file a 'package'. The 'package create' command looks for a file called `zarf.yaml` which describes all of the things that make up the package and then does all the work necessary to prepare the output tar.zst package, such as downloading required container images and git repositories. More information on what these Zarf packages are can be found in the [Zarf Packages](../zarf-packages/zarf-packages) page. + +
+ +## Initializing a Cluster: `zarf init` + + +Before you are able to deploy onto a cluster, Zarf needs to initialize the cluster to be ready. This is done through the [`zarf init`](./cli-commands/zarf_init) command, which injects and starts-up an in-cluster container registry, along with other optional tools and services into your cluster within the Zarf namespace that future packages will need. If you don't have a cluster yet, this command can help with that too! This command uses a specialized package called an 'init-package' that also contains all the resources necessary to create a local k3s cluster on your machine. This init-package can either be located in your current working directory, in the directory where the Zarf CLI binary lives, or be downloaded from the GitHub releases as the command is running. More information about what the 'init' command is doing will be provided soon but more information about the init-package can be found on the [init-package](../zarf-packages/the-zarf-init-package) page. + +:::note +Depending on the permissions of your user, if you are installing k3s through the `zarf init` command you may need to run the command as a privileged user. This can be done by either: + +1. Becoming a privileged user via the command `sudo su` and then running all the Zarf commands as you normally would. +2. Manually running all the Zarf commands as a privileged user via the command `sudo {ZARF_COMMAND_HERE}`. +3. Running the init command as a privileged user via `sudo zarf init` and then changing the permissions of the `~/.kube/config` file to be readable by the current user. +::: + +
+ +## Deploying Packages: `zarf package deploy` + + + +As stated many times now, the entire purpose of Zarf is to make it easier to deploy applications onto air gapped environments. This is where that magic happens! [`zarf package deploy`](./cli-commands/package/zarf_package_deploy) is used to deploy an already built tar.zst package onto a machine, usually specifically into a k8s cluster. It is usually assumed that the `zarf init` command has already been run on the machine you are deploying to but there are a few rare cases where this doesn't apply. + +Since the package has all of its dependencies built-in, it can be deployed onto any cluster, even without an external internet connection. The dependency resources are pushed onto the cluster in their respective places, such as an in-cluster Gitea Git server or Docker registry, and then the application is deployed as instructed in the `zarf.yaml` file (i.e. deploying a helm chart, deploying raw k8s manifests, or even just executing a series of shell commands). + +More information about Zarf packages is available on the [Understanding Zarf Packages](../zarf-packages/zarf-packages) page diff --git a/docs/4-user-guide/1-the-zarf-cli/_category_.json b/docs/4-user-guide/1-the-zarf-cli/_category_.json new file mode 100644 index 0000000000..424e2a1b7e --- /dev/null +++ b/docs/4-user-guide/1-the-zarf-cli/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "The Zarf CLI" + } + \ No newline at end of file diff --git a/docs/4-user-guide/1-the-zarf-cli/index.md b/docs/4-user-guide/1-the-zarf-cli/index.md new file mode 100644 index 0000000000..2f12104bdf --- /dev/null +++ b/docs/4-user-guide/1-the-zarf-cli/index.md @@ -0,0 +1,155 @@ +import TabItem from "@theme/TabItem"; +import Tabs from "@theme/Tabs"; + +# The Zarf CLI + + + + + +Zarf is a command line interface (CLI) tool used to enable software delivery, specifically designed around delivery to disconnected environments. The Zarf tool is statically built Go binary, meaning once it is built, it can be used anywhere without needing to bring along any other dependencies. The Zarf CLI project is, and always will be, a free to use open-source project on [GitHub](https://github.com/defenseunicorns/zarf). + +
+ +## Getting the CLI + + + + +There are multiple ways to get the Zarf CLI onto your machine including installing from the Defense Unicorns Homebrew Tap, downloading a prebuilt binary from our GitHub releases, or even building the CLI from scratch yourself. Instructions for all of these methods are provided in the [Installing Zarf](../../getting-started/#installing-zarf) section of the Getting Started guide but if you have Homebrew installed and you want to dive right in, you can install Zarf by copying the commands for your systems OS into a terminal: + + + + + +```bash +brew tap defenseunicorns/tap +brew install zarf +``` + + + + + +```bash +brew tap defenseunicorns/tap +brew install zarf +``` + + + + +
+ +## I have a CLI.. Now What? + + + +First, lets test to make sure the CLI you have works by running the CLI to get a help message output. Depending on how you installed the CLI, the tabs below will help you figure out how to run the CLI for the first time. If Zarf has been installed properly, you should see a list of all the command options as well as a short description for what each command does. + +
Expected Help Output +

+The output of the help command should look something like this: + +```text +Small tool to bundle dependencies with K3s for air-gapped deployments + +Usage: + zarf [COMMAND]|[ZARF-PACKAGE]|[ZARF-YAML] [flags] + zarf [command] + +Available Commands: + completion Generate the autocompletion script for the specified shell + connect Access services or pods deployed in the cluster. + destroy Tear it all down, we'll miss you Zarf... + help Help about any command + init Prepares a k8s cluster for the deployment of Zarf packages + package Pack and unpack updates for the Zarf gitops service. + prepare Tools to help prepare assets for packaging + tools Collection of additional tools to make airgap easier + version Displays the version of the Zarf binary + +Flags: + -a, --architecture string Architecture for OCI images + -h, --help help for zarf + -l, --log-level string Log level when running Zarf. Valid options are: warn, info, debug, trace + -t, --toggle Help message for toggle + +Use "zarf [command] --help" for more information about a command. + + +``` + +

+
+ + + + +```bash +zarf --help +``` + + + + + +- If you're not sure where the file was downloaded to, a good default place to look is `~/Downloads`. +- While we only say `zarf` for this example command, the name of the binary is the name of the file you downloaded, which will likely have a different name. + +```bash +chmod +x ~/Downloads/zarf # Make the binary executable +~/Downloaded/zarf --help +``` + + + + + +- While we only say `zarf` for this example command, depending on your system, you might have to use a different name for the binary like `zarf-mac-intel` or `zarf-mac-apple` + +```bash +cd ./path/to/zarf/repo +cd build +./zarf --help +``` + + + + + +
+
+ +### Adding The CLI To Your Path + +:::note +If you installed Zarf through Homebrew, Zarf will already be on your $PATH. and you can skip this section. +::: + +If you want to make your life a little easier, you can put the Zarf CLI on your $PATH. This way, instead of always needing to path to the exact location of the binary, you can just use `zarf` and your computer will automatically fine the binary for your to execute. The list of the directories in your PATH can be seen by running `echo $PATH`. As long as you move your CLI to one of those directories you will be able to execute it without having to path to it. One common $PATH you can use is `mv ./path/to/cli/file/zarf /usr/local/bin/zarf` + +:::note +Throughout the rest of the does we will often be describing commands as `zarf {command}`, this assumes that the CLI is in your path. +::: + +
+ +## Introduction to Zarf Commands + +Zarf has multiple commands to make building, deploying, and maintaining packages easier. Some commands also have multiple sub-commands under them. All of the commands and sub-commands available have a short description of what they do when the `--help` flag is provided. These descriptions get more detailed the further down you go into the command hierarchy. Feel free to explore around the different commands available to get a feel for what Zarf can do. + +As stated before, Zarf was built to make deploying applications into disconnected environments easier. To reach this objective, the most common commands that get used are `zarf init`, `zarf package create` and `zarf package deploy`. More detail on all of the commands can be found in the [CLI Commands](./cli-commands/zarf) section but a short description of the most commonly used commands are provided below. You might notice that all three of these commands operate in some way with what we call a Zarf package. More information about Zarf packages can be found in the next section [Zarf Packages](../zarf-packages/zarf-packages). + +### zarf init + + + +`zarf init` is used to prepare a k8s cluster for the deployment of future zarf packages. The init command uses a specialized 'init-package' to operate. This package can either be located in your current working directory, in the directory where the Zarf CLI binary lives, or be downloaded from the GitHub releases as the command is running. More information about what the 'init' command is doing will be provided soon but more information about the init-package can be found on the [init-package](../zarf-packages/the-zarf-init-package) page. + +### zarf package deploy + + + + +`zarf package deploy` is used to deploy an already built tar.zst package onto a machine, usually specifically into a k8s cluster. It is usually assumed that the `zarf init` command has already been run on the machine you are deploying to but there are a few rare cases where this doesn't apply. diff --git a/docs/4-user-guide/2-zarf-packages/1-zarf-packages.md b/docs/4-user-guide/2-zarf-packages/1-zarf-packages.md new file mode 100644 index 0000000000..e0ccc5b784 --- /dev/null +++ b/docs/4-user-guide/2-zarf-packages/1-zarf-packages.md @@ -0,0 +1,101 @@ +--- +sidebar_position: 1 +--- + +# Understanding Zarf Packages + +A Zarf package is a single binary Tarball that contains everything you need to deploy a system or capability while fully disconnected. Zarf packages are defined by a `zarf.yaml` file. + +Zarf packages are built while 'online' and connected to whatever is hosting the dependencies your package definition defined. When being built, all these defined dependencies are pulled from the internet and stored within the tarball package. Because all the dependencies are now within the tarball, the package can be deployed on to disconnected systems that don't have connection to the outside world. + +The `zarf.yaml` file, that the package builds from, defines declarative instructions on how capabilities of the package should be deployed. The declarative nature of the package means everything is represented by code and automatically runs as it is configured, instead of having to give manual steps that might not be reproducible on all systems. + +Zarf Packages are made up of functionality blocks called components which are described more in the [Zarf Components page](./zarf-components). These components can be optional, giving more flexibility to how packages can be used. + +
+ + + +## Deploying on to Airgapped Systems + +Zarf packages are built with all the dependencies necessary being included within the package itself, this is important when deploying on to systems. Since there is no need for an outbound connection to the internet, these packages become highly distributable and can be run on edge, embedded systems, secure cloud, data centers, or even in a local environment. When deploying a package onto a cluster, the dependencies of the cluster (which were included in the package itself when it was created) are pushed into a docker registry and git server that Zarf stands up on the airgapped system. This way later steps can use the dependencies as they are needed. + +
+
+ +## Types of Zarf Packages + +There are two types of Zarf packages, a `ZarfInitConfig` and a `ZarfPackageConfig`. The package type is defined by the `kind:` field in the zarf.yaml file. + +For the remainder of the docs, we will often refer to the `ZarfInitConfig` as an `init config` or `init package` package and the `ZarfPackageConfig` as any `package`. + +### ZarfInitConfig + +The init package is the package you use to initialize your cluster to be ready to deploy other Zarf packages on to. Because the init package is a special package, we have more documentation in the [Zarf 'init' Package page](./the-zarf-init-package) if you're still curious after reading this section. + +**The init package needs to be run once on every cluster you want to deploy another package onto, even if the clusters share the same host.** + +If you don't have a cluster running yet, the init-package can help with that too! The init-package has a deployable k3s cluster as a component that can optionally be deployed onto your machine. An init-package will almost always be the first Zarf package you deploy onto a cluster since other packages will often depend on the services the package installs onto your cluster. + +> Note: The only exception where you wouldn't deploy an init package first is when you don't have a k8s cluster yet, you don't want to deploy with the k3s distro built into the init-package and you have a package that deploys your preferred distro. In those situations, you can deploy the distro package first, then the init-package, and then whatever other packages you want.) + +While initializing, Zarf will seed your cluster with an container registry so it can have a place to push images that other packages will need. The init package will also optionally deploy other functionality to your cluster, such as a git-server to push git repositories to, or a simple PLG logging stack so you can monitor the things running on your cluster. + +#### Using the init-package + +You initialize your cluster by running the command `zarf init`, which will search your current working directory for a file that matches the name `zarf-init-{ARCHITECTURE}.tar.zst` where the `ARCHITECTURE` matches the architecture of the host you are running on. If the machine your are deploying onto has a different machine architecture, you will have to specify the name of the architecture you are deploying onto. For example, if you are on a arm64 machine but are deploying on a amd64 machine, you will run `zarf init zarf-init-amd64.tar.zst` + +At the end of the day, init packages are just like other packages, meaning they can also be run with `zarf package deploy zarf-init-{ARCHITECTURE}.tar.zst` + +Init configs are not something you will have to create yourself unless you really want to customize how your cluster is installed / configured (i.e. if you wanted to use the init process to install a specifically configured k3s cluster onto your host machine), and even then it is often easier to create a specific package to do that before your run the init package. + +### ZarfPackageConfig + +`ZarfPackageConfigs` is any package that isn't an init package. These packages define named capabilities that you want to deploy onto your already initialized cluster. + +You can deploy a Zarf package with the command `zarf package deploy` which will bring up a prompt listing all of the files in your current path that match the name `zarf-package-*.tar.zst` so that you can select which package you want to deploy. If you already know which package you want to deploy, you can do that easily with the command `zarf package deploy {PACKAGE_NAME}`. + +When Zarf is deploying the package, it will use the infrastructure that was created when doing the 'init' process (such as the docker registry and git server) to push all of the images and repos that the package needs to operate. + +
+
+ +## What Makes Up A Package + +Zarf packages are split into smaller chunks called 'components'. These components are defined more in the [Zarf Components page](./zarf-components) but a quick way to understand components are as the actual named capabilities that packages provide. The schema of a zarf.yaml package follows the following format: + +```yaml +kind: # Either ZarfPackageConfig or ZarfInitConfig +metadata: + name: # The name of the package + description: # A description of the package +seed: # Docker registry to seed the cluster with. Only used for init packages +components: # Components definitions are complex and broken down more in the 'Understanding Zarf Components' page +``` + +
+
+ +## Building A Zarf Package + + +:::info + +**Dependencies** for Building a Zarf Package + +- A local k8s cluster to work with ([k3s](https://k3s.io/)/[k3d](https://k3d.io/v5.4.1/)/[KinD](https://kind.sigs.k8s.io/docs/user/quick-start#installation)) +- A Zarf CLI ([downloaded](https://github.com/defenseunicorns/zarf/releases) or [manually built](../the-zarf-cli/building-your-own-cli)) +- A Zarf init package ([downloaded](https://github.com/defenseunicorns/zarf/releases) or [manually built](../the-zarf-cli/building-your-own-cli)) + +::: + +The process of defining a package is covered in the [Creating Your Own Package](https://google.com) page. Assuming you have a package already defined, building the package itself is fairly simple. + +`zarf package create` will look for a `zarf.yaml` file in the current directory and build the package from that file. Behind the scenes, this is pulling down all the resources it needs from the internet and placing them in a temporary directory, once all the necessary resources of retrieved, Zarf will create the tarball of the temp directory and clean up the temp directory. + +
+
+ +## Inspecting a Built Package + +`zarf package inspect ./path/to/package.tar.zst` will look at the contents of the package and print out the contents of the zarf.yaml file that defined it. diff --git a/docs/4-user-guide/2-zarf-packages/2-zarf-components.md b/docs/4-user-guide/2-zarf-packages/2-zarf-components.md new file mode 100644 index 0000000000..2bafa03c59 --- /dev/null +++ b/docs/4-user-guide/2-zarf-packages/2-zarf-components.md @@ -0,0 +1,130 @@ +--- +sidebar_position: 2 +--- + +# Understanding Zarf Components + +The actual capabilities that Zarf Packages provided are defined within named components. These components define what dependencies they have and a declaritive definition of how it should be deployed. Each package can have as many components as the package creator wants but a package really isn't anything without at least one component. + +Components can define a wide range of resources that it needs when the package it is a part of gets deployed. The schema for the components is listed below but a high level look at the things components can define include: + * Files to move onto the host + * Helm charts to install into the running k8s cluster + * Raw Kubernetes manifests to deploy (by getting converted into zarf-generated helm charts and installed) + * Container images to push into the registry the init-package created in the k8s cluster + * Git repositories to push into the git server the init-package created in the k8s cluster + * Data to push into a resource (i.e. a pod) in the k8s cluster + * Scripts to run before/after the component is deployed + + +### Deploying a component +When deploying a Zarf package, the **components within a package are deployed in the order they are defined in the `zarf.yaml` that the package was created from.** The `zarf.yaml` configuration for each component also defines whether the component is 'required' or not. 'Required' components are always deployed without any additional user interaction whenever the package is deployed while optional components are printed out in an interactive prompt to the user asking if they wish to the deploy the component. + + If you already know which components you want to deploy, you can do so without getting prompted by passing the components as a comma separated listed to the `--components` flag during deploy command. (ex. `zarf package deploy ./path/to/package.tar.zst --components=optional-component-1,optional-component-2`) + + +  + + +## Composing Package Components +Existing components from other packages can be composed in new packages. This can be achieved by using the import field and providing a path to the zarf.yaml you wish to compose. + +```yaml +components: + - name: flux + import: + path: 'path/to/flux/package/directory/' +``` + +Unless you specify the component name in the import field, Zarf will try to import a component from the specified path that has the same name as the new component that is currently being defined. In the example above, since the new component is named 'flux' Zarf will import the 'flux' component from the specified path. If the new component is going to have a different name, you can specify the name of the package that needs to be imported in the import field. + + +```yaml +components: + - name: flux + import: + path: 'path/to/flux/package/directory/' + name: flux-v1.0.0 +``` + +> Note: When importing a component, Zarf will copy all of the values from the original component expect for the `required` key. In addition, while Zarf will copy the values, you have the ability to override the value for the `description` key. + + Checkout the [composable-packages](https://github.com/defenseunicorns/zarf/blob/master/examples/composable-packages/zarf.yaml) example to see this in action. + +  + +## What Makes Up A Component +Zarf components can contain any of the following key/value pairs. Technically, none of the keys are required and you can use as many or few that makes sense to get to desired functionality: + + + + +```yaml + + +components: + - name: # A unique identifier for this component. + # The name can only contain alphabetical, numerical, or '-' characters. + + description: # Message given to a user when deciding to enable this component or not + + required: # If required, this component will always be deployed with the package + + secretName: # The secret Zarf will use for the registry; default is 'zarf-registry'> + # The secret lives in the 'zarf' namespace. + + cosignKeyPath: # Path to publickey to use for online resources signed by cosign. + # Signed files should be denoted with sget:// i.e. `sget://defenseunicorns/zarf-injector:0.4.3` + + images: # List of container images the component will use + # These images will be deployed to the Zarf provided docker registry + + repos: # List of git repos the component will use. + # These repos will be pushed into the gitea server. + # This also means the git-server component needs to be deployed during `zarf init`. + # Private repos need to have their credentialis listed in ~/.git-credentials + + + files: # Files to move onto the system that will be doing the `zarf package deploy` command + - source: # URL or path to where the file lives on the machine performing the `zarf package create` command + shasum: # Optional value to verify remote sources + target: # PAth to where the file will be placed on the system performing the `zarf package deploy` command + executable: # Indicates whether or not executable permissions should be set on the file + symlinks: # List of symlinks to create on the system performing the `zarf package deploy` command + + charts: # Helm charts to install during a package deploy + - name: # Name of the component + - url: # URL to where the chart is hosted (git or otherwise) + - version: # Version of the chart to install + - namespace: # Namespace to install the chart into + - gitPath: # Path to the chart on the git repo + - valuesFiles: # List of values files to use for the helm chart + + manifests: # Raw manifests that get converted into zarf-generated helm charts during deploy + - name: # Name of the component + namespace: # Namespace to install the manifest into + # This defaults to 'default' + files: # + kustomizations: # + + dataInjectors: # data packages to push into a running k8s cluster + - source: # TODO + target: # TODO + namespace: # TODO + selector: # TODO + path: # TODO + + import: # References a component in another Zarf package to import + # When 'import' is provided, the only other keys that matter are the 'name', + # 'required', 'description', and 'secretName' keys. + path: # Path to the zarf.yaml file of the component to import + name: # Optional name of the component to import + # If not provided, it defaults to the name of the component being defined + + scripts: # custom commands that run before or after component deployment + showOutput: # Indicates if the output of the scripts should be sent through stdout/stderr + timeoutSeconds: # Amount of time (in seconds) to wait for the script to complete before throwing an error + # The default time is 5 minutes + retry: # Indicates if the script should be retried if it fails + before: # List of scripts to run before the component is deployed + after: # List of scripts to run after the component is deployed +``` \ No newline at end of file diff --git a/docs/4-user-guide/2-zarf-packages/3-the-zarf-init-package.md b/docs/4-user-guide/2-zarf-packages/3-the-zarf-init-package.md new file mode 100644 index 0000000000..7f5fa30023 --- /dev/null +++ b/docs/4-user-guide/2-zarf-packages/3-the-zarf-init-package.md @@ -0,0 +1,47 @@ +--- +sidebar_position: 3 +--- + +# The Zarf 'init' Package + +The init package is the zarf.yaml file that lives at the [root of the Zarf repository](https://github.com/defenseunicorns/zarf/blob/master/zarf.yaml). It is defined via composed components that all offer value for future packages to utilize. When the init package is deployed, it will create a `zarf` namespace within your k8s cluster and deploy various pods, services, and secrets to that namespace, depending on which optional components you choose to deploy. + + +## Mandatory Components + +Zarf's work necessitates that some components in the [init package](https://github.com/defenseunicorns/zarf/blob/master/zarf.yaml) are "always on" (a.k.a. required & cannot be disabled). These components are always deployed whenever you perform a `zarf init` command. Those include: + +| | Description | +| ----------------------- | -------------------------------------------------------------------------------------------------------------------- | +| zarf-injector | Adds a Rust and Go binary to the working directory to use during the registry bootstrapping. +| container-registry-seed | Adds a container registry so Zarf can bootstrap itself into the cluster. | +| container-registry | Adds a container registry service—[docker registry](https://docs.docker.com/registry/)—into the cluster. | + + +  +## Additional Components + +In addition to those that are always installed, Zarf's optional components provide additional functionality and can be enabled as & when you need them. + +These optional components for the init package are listed below along with the "magic strings" you pass to `zarf init --components` to pull them in: + +| --components | Description | +| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| k3s | REQUIRES ROOT. Installs a lightweight Kubernetes Cluster on the local host—[k3s](https://k3s.io/)—and configures it to start up on boot. | +| logging | Adds a log monitoring stack—[promtail / loki / graphana (a.k.a. PLG)](https://github.com/grafana/loki)—into the cluster. | +| git-server | Adds a [GitOps](https://www.cloudbees.com/gitops/what-is-gitops)-compatible source control service—[Gitea](https://gitea.io/en-us/)—into the cluster. | + +There are two ways to deploy optional components, you can either pass a comma separated list of components to the `--components` flag such as `zarf init --components k3s,git-server --confirm` or you can exclude the flags and say yes/no as each optional component gets prompted to you. + +> Note: The 'k3s' component requires root access when deploying as it will modify your host machine to install the cluster. + +
+ +# What Makes the Init Package Special + +Deploying onto air-gapped environments is a [hard problem](../../understand-the-basics#what-is-the-air-gap), especially when the k8s environment you're deploying to doesn't have a container registry running for you to put your images into. This leads to a classic 'chicken or the egg' problem since the container registry image needs to make its way into the cluster but there is on container registry running on the cluster to push to yet because the image isn't in the cluster yet. In order to remain distro agnostic, we had to come up with a unique solution to seed the container registry into the cluster. + +The `zarf-injector` [component](https://github.com/defenseunicorns/zarf/blob/master/packages/zarf-injector/zarf.yaml) within the init-package solves this problem by injecting a really small [Go registry binary](https://github.com/defenseunicorns/zarf/blob/master/src/injector/stage2/registry.go) into the cluster by splitting the binary into small enough chunks that would fit inside of a k8s ConfigMap. Once th config map is pushed onto the cluster, it gets stitched back together and runs to bootstrap the registry. + + +More details about how we solved that problem is described in the [Seeding the Zarf Registry page](https://google.com). \ No newline at end of file diff --git a/docs/4-user-guide/2-zarf-packages/4-supported-packages.md b/docs/4-user-guide/2-zarf-packages/4-supported-packages.md new file mode 100644 index 0000000000..085d0e5d84 --- /dev/null +++ b/docs/4-user-guide/2-zarf-packages/4-supported-packages.md @@ -0,0 +1,12 @@ +# Supported Packages + + +:::caution Hard Hat Area +This page is still being developed. More content will be added soon! +::: + + + +There are a lot of zarf.yaml packages listed within the GitHub repository. A lot of the examples are just that, examples. We actually support and maintain the packages in the 'packages' directory. + +Here, we will talk about and briefly describe the packages that we support. \ No newline at end of file diff --git a/docs/4-user-guide/2-zarf-packages/_category_.json b/docs/4-user-guide/2-zarf-packages/_category_.json new file mode 100644 index 0000000000..7b356f3060 --- /dev/null +++ b/docs/4-user-guide/2-zarf-packages/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Zarf Packages" + } + \ No newline at end of file diff --git a/docs/4-user-guide/2-zarf-packages/index.md b/docs/4-user-guide/2-zarf-packages/index.md new file mode 100644 index 0000000000..11f7489f03 --- /dev/null +++ b/docs/4-user-guide/2-zarf-packages/index.md @@ -0,0 +1,28 @@ +# Zarf Packages + +## What is a Zarf Package? + +Zarf allows you to bundle portions of "the internet" into a single package to be installed later following specific instructions. A Zarf package is just a single tarball file that includes everything you need to manage a system or capability while fully disconnected. Think of a disconnected system as a system that always is or sometimes is on airplane mode. + +## How does a Zarf Package work? + +You bring this single file (we call it a package) to the system you want to install or update new software on. The package includes instructions on how to assemble all the pieces of software (components) once on the other side. These instructions are fully "declarative," which means that everything is represented by code and automated instead of manual. The hardest part is assembling the declarative package on the connected side. But once everything is packaged, Zarf makes even very complex systems easy to install, update, and maintain within disconnected systems. + +## Using Zarf Packages + +Such packages also become highly distributable, as they can now run on edge, embedded systems, secure cloud, data centers, or even in a local environment. This is incredibly helpful for organizations that need to integrate and deploy software from multiple, secure development environments from disparate development teams into disconnected IT operational environments. Zarf helps ensure that development teams can integrate with the production environment they are deploying to, even if they will never actually touch that environment. + +## Dependencies for Deploying Zarf Packages + +:::info + +**Dependencies** + +- A Zarf CLI ([downloaded](https://github.com/defenseunicorns/zarf/releases) or [manually built](../the-zarf-cli/building-your-own-cli)) +- A Zarf init package ([downloaded](https://github.com/defenseunicorns/zarf/releases) or [manually built](../the-zarf-cli/building-your-own-cli)) +- A Zarf Package (provided externally or [manually built](./zarf-packages#building-a-package)) +- kube-context into a k8s cluster + + - (NOTE: Not needed if you plan on deploying the cluster with `zarf init` step) + +::: diff --git a/docs/4-user-guide/_category_.json b/docs/4-user-guide/_category_.json new file mode 100644 index 0000000000..e5dcc382eb --- /dev/null +++ b/docs/4-user-guide/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "User Guide" + } + \ No newline at end of file diff --git a/docs/4-user-guide/index.md b/docs/4-user-guide/index.md new file mode 100644 index 0000000000..d612cf4118 --- /dev/null +++ b/docs/4-user-guide/index.md @@ -0,0 +1,20 @@ +# User Guide + +Experience just how easy it is to go from zero to chainsaw-wielding hero (of the Kubernetes cluster) using Zarf! + +This guide is intended for end users who are using Zarf in a disconnected environment, and contains information on how to use and configure Zarf's major features: + +- Deploy Zarf [Packages](2-zarf-packages/1-zarf-packages.md) (Zpkg) +- Maintain Zarf Packages in the cluster +- A reference of all [CLI commands](1-the-zarf-cli/100-cli-commands/0-zarf.md) +- Autogenerate and view a package SBOM +- Add logging to your cluster +- A list of [supported Zarf packages](2-zarf-packages/1-zarf-packages.md) + +## Other Resources + +If you are looking for more advanced information on how to operate and custom configure Zarf to your specfic environment needs, check out these additional resources. + +- For information on how to create custom configuration of the Zarf CLI see the [Operator Manual](./../5-operator-manual/_category_.json) +- For information on how to create your own custom Zarf Packages see the [Developer Guide](./../6-developer-guide/1-contributor-guide.md) +- To see some of the ways our community is using Zarf to deploy code onto AirGap systems see the Zarf [Examples](./../7-examples/_category_.json) diff --git a/docs/5-operator-manual/0-set-up-and-install.md b/docs/5-operator-manual/0-set-up-and-install.md new file mode 100644 index 0000000000..08cfa9d224 --- /dev/null +++ b/docs/5-operator-manual/0-set-up-and-install.md @@ -0,0 +1,57 @@ +# Set Up And Install + +:::caution Hard Hat Area +This page is still being developed. More content will be added soon! +::: + + + + +# Installing Zarf + +Until we get Zarf into common package managers, you can install the Zarf CLI by: +1. Downloading the latest release version for your machine from our [GitHub release page](https://github.com/defenseunicorns/zarf/releases). +2. Move the downloaded file onto your path. This can be done in your terminal with the command `mv ~/Downloads/{DOWNLOADED_RELEASE_FILE} /usr/local/bin/zarf` +3. Test out the CLI within your terminal with the command `zarf -version`. The version you downloaded from GitHub should print to your terminal. + +
+
+ +# Starting Up A Cluster + +### Zarf Deployed K3s Cluster + +Now that you have a Zarf CLI to work with, let's make a cluster that you can deploy to! The [init package](../user-guide/zarf-packages/the-zarf-init-package) comes with a built-in k3s cluster that you can deploy if you don't already have another cluster available. You can find the relevant [init package release](https://github.com/defenseunicorns/zarf/releases) on the GitHub releases page. + +Once downloaded, you can install the init package by navigating to the directory containing the init package and running the command [zarf init](../user-guide/the-zarf-cli/cli-commands/zarf_init). Zarf will prompt you, asking if you want to deploy the k3s component, you can type `y` and hit enter to have Zarf startup a local single node k3s cluster on your current machine. Other useful information about initializing a cluster with Zarf is available in the [Initializing a Cluster](./set-up-and-install#initializing-) section later on in this page. + +:::note +Depending on the permissions of your user, if you are installing k3s through the `zarf init` command you may need to run the command as a privileged user. This can be done by either: + +1. Becoming a privileged user via the command `sudo su` and then running all the Zarf commands as you normally would. +2. Manually running all the Zarf commands as a privileged user via the command `sudo {ZARF_COMMAND_HERE}`. +3. Running the init command as a privileged user via `sudo zarf init` and then changing the permissions of the `~/.kube/config` file to be readable by the current user. +::: + +### Any Other Cluster + +Zarf deploys to almost any cluster, you are not tied down to the K3s cluster that the [init package](../user-guide/zarf-packages/the-zarf-init-package) provides! You could use local dockerized k8s cluster such as [k3d](https://k3d.io/v5.4.1/) or [KinD](https://kind.sigs.k8s.io/), Rancher's next-generation k8s distribution [RKE2](https://docs.rke2.io/), or cloud-provided clusters such as [eks](https://aws.amazon.com/eks/) + + +# Initializing a Cluster + + +Now that you have the CLI installed and a cluster to work with, let's get that cluster initialized so you can deploy application packages onto it! + +Initializing a cluster is necessary since almost all k8 clusters do not come with a container registry by default. This becomes an interesting 'chicken or the egg' problem since you don't have a container registry available to push your container registry image into. This problem is discussed more in the [init package](http://localhost:3000/docs/user-guide/zarf-packages/the-zarf-init-package#what-makes-the-init-package-special) page. + +During the initialization process, Zarf will create a 'zarf' namespace and deploy an in-cluster Docker registry (used to host container images future packages will need), a 'zarf agent' mutating webhook (to redirect outgoing requests into the internally hosted resources), an optional gitea server (to host the git repositories future packages will need), and a handful of secrets. + +You can find the relevant [init package release](https://github.com/defenseunicorns/zarf/releases) on the GitHub releases page. Once downloaded, you can install the init package by navigating to the directory containing the init package and running the command [zarf init](../user-guide/the-zarf-cli/cli-commands/zarf_init). Zarf will prompt you, asking if you want to deploy the optional component, you can type `y` or `n` depending on your use case and needs. + +Once the init command is finished, you can run `kubectl get pods -n zarf` to verify that the pods have come up healthy. You should expect to see two `agent-hook` pods, a `zarf-docker-registry` pod, and optionally a `zarf-gitea` pod. + + +# Setup Complete! + +At this point, you have the Zarf CLI installed and a k8s cluster running and initialized. You are now ready to start deploying packages to your cluster! The Walkthroughs section of the documentation will guide you through the process of deploying packages to your cluster, a good one to start with is the [Doom Walkthrough](https://google.com). \ No newline at end of file diff --git a/docs/supported-oses.md b/docs/5-operator-manual/90-supported-oses.md similarity index 89% rename from docs/supported-oses.md rename to docs/5-operator-manual/90-supported-oses.md index 4861ad5643..118db66ba2 100644 --- a/docs/supported-oses.md +++ b/docs/5-operator-manual/90-supported-oses.md @@ -1,3 +1,6 @@ +--- +sidebar_position: 8 +--- # Supported OSes Zarf is intended to install & run on a multitude of 64-bit Linux distributions. @@ -6,7 +9,7 @@ Check the table below to understand which distros which we test against & if the   - + ## Support Matrix |OS |VM_ID |Notes| @@ -21,7 +24,7 @@ Check the table below to understand which distros which we test against & if the   - + ## Demo Environments We support running an instance of Zarf _inside a local VM_ (of any of the [supported OSes](#support-matrix)) for test & demonstration purposes. @@ -81,4 +84,4 @@ Closing out the demo environment is _also_ a single command: make vm-destroy ``` -This will shutdown & destroy _all_ the demo VM instances it can find. Easy-peasy—nice and clean. +This will shutdown & destroy _all_ the demo VM instances it can find. Easy-peasy—nice and clean. \ No newline at end of file diff --git a/docs/5-operator-manual/_category_.json b/docs/5-operator-manual/_category_.json new file mode 100644 index 0000000000..fcd5e28841 --- /dev/null +++ b/docs/5-operator-manual/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Operator Manual" + } + \ No newline at end of file diff --git a/docs/6-developer-guide/1-contributor-guide.md b/docs/6-developer-guide/1-contributor-guide.md new file mode 100644 index 0000000000..d2809e9a5d --- /dev/null +++ b/docs/6-developer-guide/1-contributor-guide.md @@ -0,0 +1,98 @@ +# Contributor Guide + +:::caution Hard Hat Area +This page is still being developed. More content will be added soon! +::: + +First off, thanks so much for wanting to help out! :tada: + +The following is a set of guidelines for contributing to Zarf. These are mostly guidelines, not rules. Use your best judgement, and feel free to propose changes to this document in a pull request. + +## Developer Experience + +Continuous Delivery is core to our development philosophy. Check out [https://minimumcd.org](https://minimumcd.org/) for a good baseline agreement on what that means. + +Specifically: + +- We do trunk-based development with short-lived feature branches that originate from the trunk, get merged to the trunk, and are deleted after the merge +- We don't merge code into the trunk that isn't releasable +- We perform automated testing on all changes before they get merged to the trunk +- We create immutable release artifacts + +### Developer Workflow + +Here's what a typical "day in the life" of a Zarf developer might look like. Keep in mind that other than things that are required through automation these aren't hard-and-fast rules. When in doubt, the process outlined here works for us. + +:key: == Required by automation + +1. Pick an outstanding issue to work on, set yourself as the assignee, and move it to "Doing Now" in the [Kanban Board](https://github.com/orgs/defenseunicorns/projects/1). The "Ready to Start" and "Planned" columns are mostly prioritized according to feedback from our users and other inputs, but don't feel like you have to pick from the top of the pile if something else is jumping out at you. +1. Write up a rough outline of what you plan to do in the issue so you can get early feedback. Clearly announce any breaking changes you think need to be made. +1. :key: Set up your Git config to GPG sign all commits. [Here's some documentation on how to set it up](https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits). You won't be able to merge your PR if you have any unverified commits. +1. :key: Create a branch off the trunk, or a fork if you are an external contributor. +1. Create a Draft Pull Request as soon as you are able to, even if it is just 5 minutes after you started working on it. Around here we aren't afraid to show unfinished work. It helps us get feedback more quickly. +1. :key: Create a Pull Request (or mark it Ready for Review if you've been working in a Draft PR). +1. :key: Run all automated tests by adding `/test all` as a comment in the PR. If you want to re-run certain tests you can also run them individually. Example: `/test e2e` just runs the end-to-end tests. You can chain different tests together like `/test foo bar baz`. You need `write` permission to the repo to trigger the tests. +1. Clearly announce any breaking changes that have been made. +1. :key: Get at least 1 peer-review approval. +1. :key: Merge the PR into the trunk. We tend to prefer "Squash and Merge" but if your commits are on-point and you want to preserve them in the Git history of the trunk that's fine too. +1. Delete the branch +1. Close the issue if it got fully resolved by your PR. *Hint: You can add "Fixes #XX" to the PR description to automatically close an issue when the PR is merged.* + +## Testing + +This section dives deeper into how we test Zarf + +### Pre-Commit Hooks and Linting + +In this repo we use [pre-commit](https://pre-commit.com/) hooks for automated validation and linting. The CI pipeline will (eventually) validate that all of the hooks pass so we strongly recommend that you install the hooks locally or you'll be spending a lot of time manually fixing issues that could be fixed automatically very quickly. + +#### Pre-Commit Prerequisites + +1. Install [pre-commit](https://pre-commit.com/) +1. Install [go](https://golang.org/) +1. Install [golangci-lint](https://github.com/golangci/golangci-lint) +1. Run `pre-commit install` in the repo to install the pre-commit hooks. This will make the hooks run automatically each time you `git commit`. If you want to skip the hooks for any reason you can run `git commit --no-verify` to skip them. + +> **HINT:** *Consider [automatically enabling the hooks in every Git repository](https://pre-commit.com/#automatically-enabling-pre-commit-on-repositories)* + +### End2End Testing + +Our E2E tests utilize [Terratest](https://terratest.gruntwork.io/). They create real infrastructure in AWS that the tests get run on. By doing this we are able to make the test environments ephemeral and allow them to be run in parallel so that we can do more testing more quickly. + +The Terratest E2E tests can be found in the `/test` folder. + +We're still working on building out the test suite. If you want to help check out these issues: + +- [#97](https://github.com/defenseunicorns/zarf/issues/97): Make our own test harness container +- [#99](https://github.com/defenseunicorns/zarf/issues/99): Writing additional tests +- [#100](https://github.com/defenseunicorns/zarf/issues/100): Each test should be runnable locally +- [#101](https://github.com/defenseunicorns/zarf/issues/101): Run E2E tests on multiple distros +- [#102](https://github.com/defenseunicorns/zarf/issues/102): Make the E2E tests more efficient + +## Documentation + +In this section you'll find documentation on documentation! Pun absolutely intended :smile: + +### Architecture Decision Records (ADR) + +We've chosen to use ADRs to document architecturally significant decisions. We primarily use the guidance found in [this article by Michael Nygard](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions) with a couple of tweaks: + +- The criteria for when an ADR is needed is undefined. The team will decide when the team needs an ADR. +- We will use the tool [adr-tools](https://github.com/npryce/adr-tools) to make it easier on ourselves to create and maintain ADRs. +- We will keep ADRs in the repository under `docs/adr/NNNN-name-of-adr.md`. `adr-tools` is configured with a dotfile to automatically use this directory and format. + +### How to use `adr-tools` + +```bash +# Create a new ADR titled "Use Bisquick for all waffle making" +adr new Use Bisquick for all waffle making + +# Create a new ADR that supercedes a previous one. Let's say for example that the previous ADR about Bisquick was ADR number 9. +adr new -s 9 Use scratch ingredients for all waffle making + +# Create a new ADR that amends a previous one. Let's say the previous one was ADR number 15 +adr new -l "15:Amends:Amended by" Use store-bought butter for all waffle making + +# Get full help docs. There are all sorts of other helpful commands that help manage the decision log. +adr help +``` \ No newline at end of file diff --git a/docs/6-developer-guide/2-testing.md b/docs/6-developer-guide/2-testing.md new file mode 100644 index 0000000000..c9d89363c2 --- /dev/null +++ b/docs/6-developer-guide/2-testing.md @@ -0,0 +1,56 @@ +# Code Testing + +:::caution Hard Hat Area +This page is still being developed. More content will be added soon! +::: + + +Currently, we test Zarf through a series of end-to-end tests which can be found in the [e2e directory](https://github.com/defenseunicorns/zarf/tree/master/src/test/e2e) of the project. This directory holds all of our e2e tests that we use to verify Zarf functionality in an environment that replicates a live setting. The tests in this directory are automatically run against several K8s distros whenever a PR is opened or updated. + +## Running Tests Locally +The tests in this directory are also able to be run locally! + +### Dependencies +Running the tests locally have the same prerequisites as running and building Zarf: + 1. GoLang >= `1.18.x` + 2. Make + 3. (for the `kind` and `k3d` options only) Docker + 4. (for the `k3s` cluster only) Linux with root privileges + +### Existing K8s Cluster +If you have a cluster already running, and use the env var `TESTDISTRO=provided`, the test suite will use the `KUBECONFIG` env var and the cluster that is currently configured as the active context. To make sure you are running in the right cluster, run something like `kubectl get nodes` with no optional flags and if the nodes that appear are the ones you expect, then the tests will use that cluster as well. + +This means that you are able to run the tests against any remote distro you want, like EKS, AKS, GKE, RKE, etc. + +### No Existing K8s Cluster +If you do not have a local cluster running, no worries! The e2e tests use the `sigs.k8s.io/kind` and `github.com/k3d-io/k3d/v5` libraries to stand up local clusters to test against. All you have to do is make sure Docker is running and set the `TESTDISTRO` env var to either `"kind"` or `"k3d"` and the test suite will automatically create the appropriate cluster before the test run, run the tests on it, then automatically destroy it to clean up. + +You can also use K3s by setting `TESTDISTRO=k3s` but note that there are extra requirements of being on Linux with root privileges. + +### Actually Running The Test +Here are a few different ways to run the tests, based on your specific situation: + +```shell +# The default way, from the root directory of the repo. Will run all of the tests against your chosen k8s distro. Will automatically build any binary dependencies that don't already exist. +TESTDISTRO="[provided|kind|k3d|k3s]" make test-e2e + +# If you already have everything build, you can run this inside this folder. This lets you customize the test run. +TESTDISTRO=YourChoiceHere go test ./... -v + +# Let's say you only want to run one test. You would run: +TESTDISTRO=YourChoiceHere go test ./... -v -run TestFooBarBaz +``` +:::note +The zarf binary and built packages need to live in the ./build directory but if you're trying to run the tests locally with 'go test ./...' then the zarf-init package will need to be in this directory. +::: + +## Adding More Tests +There are a few requirements for all of our tests, that will need to be followed when new tests are added. + +1. Tests may not run in parallel, since they use the same kubernetes cluster to run them. +2. Each test must begin with `defer e2e.cleanupAfterTest(t)` so that the cluster can be reset back to empty when finished. + +## Coming Soon +1. More Linux distros tested +2. More K8s distros tested, including cloud distros like EKS +3. Make the tests that run in the CI pipeline more efficient by using more parallelization \ No newline at end of file diff --git a/docs/6-developer-guide/3-nerd-notes.md b/docs/6-developer-guide/3-nerd-notes.md new file mode 100644 index 0000000000..bfe618a435 --- /dev/null +++ b/docs/6-developer-guide/3-nerd-notes.md @@ -0,0 +1,28 @@ +# Zarf Nerd Notes + +:::caution Hard Hat Area +This page is still being developed. More content will be added soon! +::: + + +Zarf is written entirely in [go](https://go.dev/), except for a single 400Kb binary for the injector system written in [rust](https://www.rust-lang.org/), so we can fit it in a [configmap](https://kubernetes.io/docs/concepts/configuration/configmap/). All assets are bundled together into a single [zstd](https://facebook.github.io/zstd/) tarball on each `zarf package create` operation. On the air gap / offline side, `zarf package deploy` extracts the various assets and places them on the filesystem or installs them in the cluster, depending on what the zarf package says to do. Some important ideas behind Zarf: + +- All workloads are installed in the cluster via the [Helm SDK](https://helm.sh/docs/topics/advanced/#go-sdk) +- The OCI Registries used are both from [Docker](https://github.com/distribution/distribution) +- Currently, the Registry and Git servers _are not HA_, see [#375](https://github.com/defenseunicorns/zarf/issues/376) and [#376](https://github.com/defenseunicorns/zarf/issues/376) for discussion on this +- To avoid TLS issues, Zarf binds to `127.0.0.1:31999` on each node as a [NodePort](https://kubernetes.io/docs/concepts/services-networking/service/#type-nodeport) to allow all nodes to access the pod(s) in the cluster +- Until [#306](https://github.com/defenseunicorns/zarf/pull/306) is merged, during helm install/upgrade a [Helm PostRender](https://helm.sh/docs/topics/advanced/#post-rendering) function is called to mutate images and [ImagePullSecrets](https://kubernetes.io/docs/concepts/containers/images/#specifying-imagepullsecrets-on-a-pod) so the deployed resources use the NodePort binding +- Zarf uses a custom injector system to bootstrap a new cluster. See the PR [#329](https://github.com/defenseunicorns/zarf/pull/329) and [ADR](https://github.com/defenseunicorns/zarf/blob/master/docs/adr/0003-image-injection-into-remote-clusters-without-native-support.md) for more details on how we came to this solution. The general steps are listed below: + - Get a list of images in the cluster + - Attempt to create an ephemeral pod using an image from the list + - A small rust binary that is compiled using [musl](https://www.musl-libc.org/) to keep the size the max binary size of ~ 672 KBs is injected into the pod + - The mini zarf registry binary and `docker:2` images are put in a tar archive and split into 512 KB chunks; larger sizes tended to cause latency issues on low-resource control planes + - An init container runs the rust binary to re-assemble and extract the zarf binary and registry image + - The container then starts and runs the zarf binary to host the registry image in an embedded docker registry + - After this, the main docker registry chart is deployed, pulls the image from the ephemeral pod, and finally destroys the created configmaps, pod, and service + +
+ + +### Zarf Architecture +![Architecture Diagram](../.images/architecture.drawio.svg) diff --git a/docs/6-developer-guide/_category_.json b/docs/6-developer-guide/_category_.json new file mode 100644 index 0000000000..b95172da24 --- /dev/null +++ b/docs/6-developer-guide/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Developer Guide" + } + \ No newline at end of file diff --git a/docs/7-examples/_category_.json b/docs/7-examples/_category_.json new file mode 100644 index 0000000000..e422a54ed1 --- /dev/null +++ b/docs/7-examples/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Examples" + } + \ No newline at end of file diff --git a/docs/8-dashboard-ui/1-sbom-dashboard.md b/docs/8-dashboard-ui/1-sbom-dashboard.md new file mode 100644 index 0000000000..0c77b0d7ac --- /dev/null +++ b/docs/8-dashboard-ui/1-sbom-dashboard.md @@ -0,0 +1,5 @@ +# SBOM Dashboard + +:::caution Hard Hat Area +This page is still being developed. More content will be added soon! +::: \ No newline at end of file diff --git a/docs/8-dashboard-ui/2-k9s-dashboard.md b/docs/8-dashboard-ui/2-k9s-dashboard.md new file mode 100644 index 0000000000..8fa52bf963 --- /dev/null +++ b/docs/8-dashboard-ui/2-k9s-dashboard.md @@ -0,0 +1,5 @@ +# K9s + +:::caution Hard Hat Area +This page is still being developed. More content will be added soon! +::: \ No newline at end of file diff --git a/docs/8-dashboard-ui/_category_.json b/docs/8-dashboard-ui/_category_.json new file mode 100644 index 0000000000..3249b6d4ed --- /dev/null +++ b/docs/8-dashboard-ui/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "UI Dashboards" + } + \ No newline at end of file diff --git a/docs/9-faq.md b/docs/9-faq.md new file mode 100644 index 0000000000..662839e6d7 --- /dev/null +++ b/docs/9-faq.md @@ -0,0 +1,5 @@ +# FAQ + +:::caution Hard Hat Area +This page is still being developed. More content will be added soon! +::: \ No newline at end of file diff --git a/docs/asciinema/.gitignore b/docs/asciinema/.gitignore deleted file mode 100644 index 95ddfc5472..0000000000 --- a/docs/asciinema/.gitignore +++ /dev/null @@ -1,3 +0,0 @@ -recordings/ -.config/ -*.log diff --git a/docs/asciinema/README.md b/docs/asciinema/README.md deleted file mode 100644 index 837fc5eda2..0000000000 --- a/docs/asciinema/README.md +++ /dev/null @@ -1,188 +0,0 @@ -# asciinema - -The Zarf docs include a series of recorded / published terminal sessions which we use to brag to (potential) users about the appeal of our clear, easy-to-use CLI. These recordings let them _experience_ Zarf in a way that simply reading can't, they pass on pro usage tips / context, and they help new users find their footing with the tool—we love them. - -They don't come "for free" though—creating them takes time; keeping them current takes even more. - -To facilitate this process we use a product called [asciinema](https://asciinema.org/) which does two things for us: 1) captures _actual terminal sessions_, and 2) serves as a simple, backing web host for storage & (browser-based) playback of recordings. - -Best of all, because it provides for both of those functions through its CLI, we can _script the creation & update of our terminal session recordings_ for ultra-low cost of maintenance & near total elimination of toil. Yay! - -  - - -## The Flow - -1. [Setup Your Environment](#setup-your-environment) - -1. [Run Scenarios](#run-scenarios) - -1. [Review Recordings](#review-recordings) - -1. [Publish to Asciinema.org](#publish-to-asciinemaorg) - -  - - -## Setup Your Environment - -1. Put a Zarf release into the `/build` folder—it doesn't matter if you download it or build it yourself, just make sure _it's the version you want to generate docs against_. - -1. Log Zarf into Iron Bank—instructions [here](../ironbank.md#2-configure-zarf-the-use-em). - -1. Install the things necessary to run our [./Vagrantfile](./Vagrantfile)—instructions [here](../workstation.md#i-want-a-demoexample-sandbox). - -1. Configure your "asciinema.org install id" such that `asciinema` uploads are tied to Zarf's collection of recordings. Follow [these instructions](#setup---zarf-install-id) then come back & continue. - - -  - - -## Run Scenarios - -Make sure the `expect` scripts you need _exist in the `./scenarios` folder_, then run the utility script: - -```sh -./asciinema.sh run [""|"all"] # run & record ALL scenarios -./asciinema.sh run # run & record a SPECIFIC scenario -``` - -Watch the terminal do its magic & dump your new recordings to the `./recordings` folder. - -  - - -## Review Recordings - -By this point, you should have some terminal session recordings in the `./recordings` folder. They (currently) only exist on _your machine_ though, so this is your chance to check them before they "go live". - -You can use your local terminal _sort-of-like_ a video player & "play" back any of your recordings like so: - -```sh -asciinema play -``` - -Be sure to do a review & verify that what you caught during recording was everything you expected to! - -  - - -## Publish to Asciinema.org - -Once all of your recordings look good it's time to push them out to https://asciinema.org! - -During publishing `asciinema` uses a unique identifier—called an "install id"—to connect an uploaded recording to the appropriate asciinema.org account. It stores this id in a file on your disk: `$HOME/.config/asciinema/install-id`. - -When you run `asciinema` commands, if you do not already have an `install-id` file one is generated for you. This makes for a nice new-user experience and if you only need to upload anonymous, temporary recordings to asciinema.org this is enough. - -If you need recordings to stick around and be listed in a specific group, however—and in this case you do—then you'll need access to an install id that has been registered with Zarf's account on asciinema.org. - -> _**Dig in!**_ -> -> Go ahead and have a look at the asciinema [usage page](https://asciinema.org/docs/usage) (under the "auth" heading) if you're interested in more detail / background on this topic. - -  - -### The Flow - -1. [Publish New Recordings](#publish-new-recordings) - -1. [Update Project Links](#update-project-links) - -1. [Remove Outdated Recordings](#remove-outdated-recordings) - -  - - -### Setup - Zarf install id - -#### Access - -For access to an "install id" that has been authorized to upload recordings to [the Zarf account](./asciinema-org) on asciinema.org, you can: - -- Login to [Zarf's asciinema.org account](./asciinema-org) and copy down a "recorder token" (a.k.a. "install id") from the [account settings](https://asciinema.org/user/edit) page, _**or**_— - -- Generate a new install id locally, then login & associate it to [Zarf's asciinema.org account](./asciinema-org) (as described [under the "auth" heading](https://asciinema.org/docs/usage)), _**or**_— - -- Get someone else with access to do any of the above _for_ you & just send back the install id! - - -  - - -#### Associate - -Once you have access to an authorized install id you need to put it in a location on disk where `asciinema` knows to look for it. - -**If you are configuring your own machine to run asciinema** you can drop your install id into an appropriate file with a couple of commands that look like this: - -```sh -mkdir -p $HOME/.config/asciinema -echo -n "" > $HOME/.config/asciinema/install-id -``` - -**If you plan to use the [./Vagrantfile](./Vagrantfile) to run asciinema instead** you should dump your install id into a `./.config/asciinema/install-id` file (in the same directory as the README.md you're reading right now!) as this will allow your install id to be mounted into the VM on startup: - -```sh -mkdir -p ./.config/asciinema -echo -n "" > ./.config/asciinema/install-id -``` - -  - - -### Publish New Recordings - -After you've configured `asciinema` to use the Zarf install id it's time to publish some recordings! - -Again, using the utility script, you'll run a command that looks something like this: - -```sh -./asciinema.sh pub [""|"all"] # upload ALL recordings -./asciinema.sh pub # upload a SPECIFIC recording -``` - -> _**Take note**_ -> -> Publishing _always creates a brand new link_ at asciinema.org! There is, unfortunately (as of Oct 2021), no "official" way to update a recording using the `asciinema` CLI—ugh. - -Once the recordings have been published you'll see some `.url` files appear in your `recordings` folder—these files contain the **new** asciinema.org urls that you'll use to update the rest of your project links. - -  - - -### Update Project Links - -After you publish recordings to asciinema.org you'll have some project docs' links to update. By-hand updates can be slow, annoying, and error-prone though, so... utility script to the rescue! - -```sh -./asciinema.sh see # see where all the links are (manual use!) -./asciinema.sh sub # substitute old urls for new (full auto!) -``` - -These commands will speed you along no matter which manner of update you prefer (manual or auto). - -> _**Recommendation**_ -> -> Post-modification, pre-commit reviews are less bothersome (and easier to rollback) if you clear your working directory (e.g. `git stash`) before running the `sub` command. - -  - - -### Remove Outdated Recordings - -The last step in the asciinema.org publishing flow is to go and _clean out old recordings_. Regrettably, this step is a manual one because there is no "official" way (as of Oct 2021) to delete recordings via the `asciinema` CLI. - -The task here is pretty simple, thankfully: -1. Point your browser at the asciinema.org account listed in [this file](./asciinema-org). - -1. Log in. - -1. Delete all recordings _other than the most recent upload of **any given title**_ by handing-off to this utility script command: - - ```sh - ./asciinema.sh zap # nukes ALL the expired stuff! - ``` - - Some interaction will be required for this command to complete—you'll have to dig some cookies out of your browser's dev tools & hand them over. While this isn't an ideal situation, it _is_ about the best we can do without "real" support for deletes in `asciinema`. It's still _way_ better than trying to cleanup a bunch of recordings by hand. -  diff --git a/docs/asciinema/Vagrantfile b/docs/asciinema/Vagrantfile deleted file mode 100644 index 066e5768a6..0000000000 --- a/docs/asciinema/Vagrantfile +++ /dev/null @@ -1,31 +0,0 @@ -Vagrant.configure("2") do |config| - - config.vm.provider "virtualbox" do |vb| - vb.check_guest_additions = false - vb.cpus = 4 - vb.memory = 4096 - end - - config.vm.box = "boxomatic/ubuntu-20.04" - config.vm.network "forwarded_port", guest: 80, host: 50080 - config.vm.network "forwarded_port", guest: 443, host: 50443 - - config.vm.hostname = "asciinema" - config.vm.synced_folder '.', '/vagrant', disabled: true - config.vm.synced_folder '../..', '/zarf', SharedFoldersEnableSymlinksCreate: false - config.vm.synced_folder'./.config/asciinema', '/root/.config/asciinema', - SharedFoldersEnableSymlinksCreate: false, - owner: 'root', group: 'root' - config.vm.synced_folder'~/.docker', '/root/.docker', - SharedFoldersEnableSymlinksCreate: false, - owner: 'root', group: 'root' - - config.ssh.insert_key = false - config.ssh.extra_args = [ "-t", "cd /zarf/docs/asciinema; sudo su" ] - - config.vm.provision "shell", inline: <<-'SCRIPT' - # https://serverfault.com/questions/500764/dpkg-reconfigure-unable-to-re-open-stdin-no-file-or-directory - export DEBIAN_FRONTEND=noninteractive - apt-get --yes install asciinema expect jq - SCRIPT -end diff --git a/docs/asciinema/asciinema-org b/docs/asciinema/asciinema-org deleted file mode 100644 index 5029fda1b8..0000000000 --- a/docs/asciinema/asciinema-org +++ /dev/null @@ -1 +0,0 @@ -https://asciinema.org/~barrett diff --git a/docs/asciinema/asciinema.sh b/docs/asciinema/asciinema.sh deleted file mode 100755 index fd6f10758f..0000000000 --- a/docs/asciinema/asciinema.sh +++ /dev/null @@ -1,317 +0,0 @@ -#!/bin/bash - -# Assumptions: -# - run as root (for proper zarf permissions) - -# Usage: -# - described in ./README.md - -# env -ME="$( basename "${BASH_SOURCE[0]}" )" -HERE="$( cd "$( dirname -- "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )" -SCENARIOS="$HERE/scenarios" -RECORDINGS="$HERE/recordings" -ROOTDIR="$( realpath "$HERE/../.." )" -ZARFDIR="$( realpath "$ROOTDIR/build" )" - -# func defs -function help() { - echo "" - echo "Usage: $ME [args...]" - echo "" - echo " run - run a scripted scenario & record terminal session" - echo " pub - publish recording to asciinema.org" - echo " see - show outdated project asciinema.org links" - echo " sub - substitute newly-uploaded asciinema.org links in project source" - echo " zap - remove all but the MOST CURRENT recordings from asciinema.org" - echo "" -} - -# executes (and records) a given scenario file's terminal session -function run() { - local fname="${1##*/}" - local fpath="$SCENARIOS/$fname" - - if [ ! -f "$fpath" ] ; then - echo "" - echo "Can't find scenario: $fpath" - echo "" - return 1 - fi - - mkdir -p "$RECORDINGS" - local base="${fname/.exp/}" - local recording="$RECORDINGS/$base.rec" - local log="${recording/.rec/.log}" - rm -f "$RECORDINGS/$base".* - - local cols=$(tput cols) - local rows=$(tput lines) - ( - cd "$ZARFDIR" \ - && stty cols 90 rows 30 \ - && expect -d -f "$fpath" "$recording" "$log" - ) - stty cols "$cols" rows "$rows" -} - -# finds scenarios and "run"s them all -function run_all() { - local scenarios=$(find "$SCENARIOS" -name '*.exp' -type f) - - # need to keep access to calling tty so settings can be - # manipulated during recording - local tty="$(tty)" - echo "$scenarios" | while read scenario ; do - run "$(basename "$scenario")" < "$tty" - done -} - -# uploads a given recording file to asciinema.org -function pub() { - local fname="${1##*/}" - local fpath="$RECORDINGS/$fname" - - if [ ! -f "$fpath" ] ; then - echo "" - echo "Can't find recording: $fpath" - echo "" - return 1 - fi - - local uname="$( basename $fname ".rec" ).url" - local upath="$RECORDINGS/$uname" - if [ -f "$upath" ] ; then - echo "URL file found. Skipping: $fname." && return 0 - fi - - asciinema upload "$fpath" \ - | grep -Po 'https://asciinema.org[^ |\n]*' \ - | tr -d '\n' \ - > "$upath" -} - -# finds new recordings and "pub"s them all -function pub_all() { - local recordings=$(find "$RECORDINGS" -name '*.rec' -type f) - - echo "$recordings" | while read recording ; do - pub "$(basename "$recording")" - done -} - -# finds, parses, and outputs locations of all asciinema.org links in project -# - helps creator of new recordings know what needs update -# - intput to "automatic link update" function (sub) below -function see() { - local found="$( - find "$ROOTDIR" -type f -name '*.md' -print0 \ - | xargs -0 grep -Pon '(http|https)://asciinema.org/a/[^ \]\)'"'"'"]*' - )" - if [ -z "$found" ] ; then return 0 ; fi - - echo "$found" | while IFS= read -r f ; do - local file=$(echo "$f" | awk -F ':' '{print $1}' ) - local line=$(echo "$f" | awk -F ':' '{print $2}' ) - local url=$(echo "$f" | cut -d ':' -f3- ) - local proto=$(echo "$url" | cut -d ':' -f1 ) - local host=$(echo "$url" | cut -d '/' -f3 ) - local path=$(echo "$url" \ - | cut -d '/' -f4- \ - | cut -d '#' -f1 \ - | cut -d '?' -f1 \ - | cut -d '.' -f1 - ) - local ext=$(echo "$url" \ - | cut -d '#' -f1 \ - | cut -d '?' -f1 \ - | awk -F '/' '{print $NF}' \ - | grep '\.' \ - | cut -d '.' -f2 - ) - local query=$(echo "$url" | awk -F '?' '{print $2}' | grep -o '^[^#]*' ) - local fragment=$(echo "$url" | awk -F '#' '{print $2}' ) - local scenario=$(echo "$query" | grep -Po 'x-scenario=\K[^&]*' ) - - local sub="no" - local rsu="$RECORDINGS/$scenario.url" - if [ -f "$rsu" ] ; then - local found_base="$proto://$host/$path" - local rsu_url=$( cat "$rsu" ) - if [ "$found_base" != "$rsu_url" ] ; then - local from="$url" - local to="$rsu_url${ext:+.$ext}${query:+?$query}${fragment:+#$fragment}" - sub="$from > $to" - fi - fi - - echo "Found: $f" - echo " file : $file" - echo " line : $line" - echo " protocol : $proto" - echo " host : $host" - echo " path : $path" - echo " ext : $ext" - echo " query : $query" - echo " fragment : $fragment" - echo " scenario : $scenario" - echo " sub : $sub" - echo "" - done -} - -# substitutes newly-published asciinema.org URLs for old values -function sub() { - local lines="$( printf '%.0s- ' {1..12} )" - local found="$( cat - | paste -d '\t' $lines )" # <-- reads stdin! - local clean="$( echo "$found" | tr -s ' ' | sed -E 's/: \t/: -\t/g' )" - - echo "$clean" | while IFS= read -r c ; do - local sub="$( echo "$c" | grep -Po 'sub : \K[^\t]*' )" - if [ "$sub" = "no" ] ; then continue ; fi - - local file="$( echo "$c" | grep -Po 'file : \K[^\t]*' )" - local line="$( echo "$c" | grep -Po 'line : \K[^\t]*' )" - local from="$( echo "$sub" | awk -F '>' '{print $1}' | tr -d ' ' )" - local to="$( echo "$sub" | awk -F '>' '{print $2}' | tr -d ' ' )" - - local to_sed_safe="${to/&/\\&}" - sed -i'' "${line}s|$from|$to_sed_safe|" "$file" - done -} - -# removes any "outdated" links from asciinema.org -function zap() { - # Web scraping, eeewww! - local account="$( cat "$HERE/asciinema-org" )" - - # scrape paging controls - local page_one="$( curl --silent --location "$account" )" - local page_nav="$( echo "$page_one" \ - | grep '