Skip to content

Commit 8ba3518

Browse files
YrrepNojYrrepNoj
authored
migrate website docs main zarf repo (zarf-dev#590)
* migrate website docs into this repo * reorganize migrated docs structure
1 parent e96c5c8 commit 8ba3518

File tree

92 files changed

+3081
-1585
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

92 files changed

+3081
-1585
lines changed

‎.adr-dir

+1-1
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
docs/adr
1+
adr

‎docs/adr/0001-record-architecture-decisions.md ‎adr/0001-record-architecture-decisions.md

File renamed without changes.

‎docs/adr/0002-moving-e2e-tests-away-from-terratest.md ‎adr/0002-moving-e2e-tests-away-from-terratest.md

File renamed without changes.

‎docs/adr/0003-image-injection-into-remote-clusters-without-native-support.md ‎adr/0003-image-injection-into-remote-clusters-without-native-support.md

File renamed without changes.

‎docs/adr/0004-generate-sboms-with-witness.md ‎adr/0004-generate-sboms-with-witness.md

File renamed without changes.

‎docs/adr/0005-mutating-webhook.md ‎adr/0005-mutating-webhook.md

File renamed without changes.

‎docs/adr/template.md ‎adr/template.md

File renamed without changes.

‎docs/.images/Zarf Files - 3 Bubbles.svg

+215
Loading

‎docs/.images/Zarf Left Underwater - Behind rock.svg

+732
Loading

‎docs/.images/architecture.drawio.svg

+4
Loading

‎docs/.images/favicon.svg

+97
Loading

‎docs/0-zarf-overview.md

+78
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
import TabItem from "@theme/TabItem";
2+
import Tabs from "@theme/Tabs";
3+
4+
# Overview
5+
6+
![Zarf Underwater](.images/Zarf%20Left%20Underwater%20-%20Behind%20rock.svg)
7+
8+
## What is Zarf?
9+
10+
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.
11+
12+
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.
13+
14+
## How Zarf works?
15+
16+
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).
17+
18+
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.
19+
20+
![Zarf CLI + Zarf Init + Zarf Package](.images/Zarf%20Files%20-%20%203%20Bubbles.svg)
21+
22+
:::note
23+
24+
For more information on how zarf works under the hood visit our [Nerd Notes page](./6-developer-guide/3-nerd-notes.md)
25+
26+
:::
27+
28+
## Why Use Zarf?
29+
30+
- 💸 **Free and Open Source.** Zarf will always be free to use and maintained by the open source community.
31+
- 🔓 **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.
32+
- 💻 **OS Agnostic.** Zarf supports numerous operating systems.For a full list, visit the [Supported OSes](./5-operator-manual/90-supported-oses.md) page.
33+
- 📦 **Highly Distributable.** Integrate and deploy software from multiple, secure development environments including edge, embedded systems, secure cloud, data centers, and even local environments.
34+
- 🚀 **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.
35+
- 💿 **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.
36+
- ♻️ **Declarative Deployments.**
37+
- 🦖 **Inherit Legacy Code**
38+
39+
## Quick Start
40+
41+
:::info
42+
43+
This quick start requires you to already have [home brew](https://brew.sh/) package manager installed on your machine.
44+
For more install options please visit our [Getting Started page](3-getting-started.md)
45+
46+
:::
47+
48+
To download the Zarf CLI Binary,
49+
50+
1. Select your systems OS below
51+
2. copy and past the quick start command into your computers terminal.
52+
53+
<Tabs>
54+
<TabItem value="macOS" label="macOS" default>
55+
56+
```bash
57+
brew tap defenseunicorns/tap
58+
brew install zarf
59+
```
60+
61+
</TabItem>
62+
<TabItem value="Linux" label="Linux">
63+
64+
```bash
65+
brew tap defenseunicorns/tap
66+
brew install zarf
67+
```
68+
69+
</TabItem>
70+
<TabItem value="Windows" label="Windows">
71+
72+
```bash
73+
Coming Soon!
74+
```
75+
76+
</TabItem>
77+
</Tabs>
78+

‎docs/1-understand-the-basics.md

+27
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# Understand The Basics
2+
3+
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.
4+
5+
:::caution Hard Hat Area
6+
This page is still being developed. More content will be added soon!
7+
:::
8+
9+
<!-- TODO: This might be a good place to shamelessly plug the 'Air Gap' course -->
10+
<!-- TODO: The links and information on this page need to be expanded a lot more to really be useful -->
11+
12+
<br />
13+
<br />
14+
15+
## What is Kubernetes?
16+
- [Kubernetes Overview](https://kubernetes.io/docs/concepts/overview/)
17+
<br />
18+
<br />
19+
20+
## What is the 'Air Gap'?
21+
22+
23+
<br />
24+
<br />
25+
26+
## What is GitOps?
27+
- [CloudBees GitOps Definition](https://www.cloudbees.com/gitops/what-is-gitops)

‎docs/10-roadmap.md

+21
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# Roadmap
2+
3+
:::caution Hard Hat Area
4+
This page is still being developed. More content will be added soon!
5+
:::
6+
7+
## Roadmap
8+
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.
9+
10+
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.
11+
12+
<br />
13+
14+
## GA Release
15+
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).
16+
17+
18+
19+
<!-- TODO: Expected release cycle? -->
20+
<!-- TODO: Plan to be GA soon? (but we're currently not..) -->
21+
<!-- TODO: Link to GitHub project backlog -->

‎docs/11-community.md

+12
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
# Community
2+
3+
:::caution Hard Hat Area
4+
This page is still being developed. More content will be added soon!
5+
:::
6+
7+
- 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.
8+
- The Zarf repository is hosted on [GitHub](https://github.com/defenseunicorns/zarf)
9+
- [Zarf LinkedIn Project](https://www.linkedin.com/company/zarf-project/)
10+
11+
12+
<!-- TODO: link to dev twitter (we don't have a zarf specific twitter yet but maybe we can link to the devs if they want?) -->

‎docs/12-support.md

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
# Support
2+
3+
1. Make sure you've read the [Zarf Overview](./zarf-overview), [Understanding the Basics](./understand-the-basics), and the [Getting Started](./getting-started) guides.
4+
2. Look for an answer in [the frequently asked questions](./faq).
5+
3. Ask a question in [the Zarf Slack Channel](https://kubernetes.slack.com/archives/C03B6BJAUJ3)
6+
4. [Read issues, report a bug, or rquest a new feature](https://github.com/defenseunicorns/zarf/issues)

‎docs/13-walkthroughs.md

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
# Walkthroughs
2+
3+
:::caution Hard Hat Area
4+
This page is still being developed. More content will be added soon!
5+
:::
6+

‎docs/2-core-concepts.md

+10
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
# Core Concepts
2+
3+
:::caution Hard Hat Area
4+
This page is still being developed. More content will be added soon!
5+
:::
6+
7+
Now, assuming you're familiar with Kubernetes, the AirGap, and GitOps, we can get started on the core concepts of Zarf.
8+
9+
- **Package** - A binary files that contains the instructions and dependencies necessary to install an application on a system.
10+
- **Component** - A set of defined functionality and resources that build up a package.

‎docs/3-getting-started.md

+75
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
# Getting Started
2+
3+
Welcome to the documentation about Zarf, the air-gap tool! Let's get you started down your Zarfing journey!
4+
5+
## Installing Zarf
6+
7+
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.
8+
9+
### Installing from the Defense Unicorns Homebrew Tap
10+
11+
[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!
12+
13+
```bash
14+
brew tap defenseunicorns/tap
15+
brew install zarf
16+
```
17+
18+
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.
19+
20+
### Downloading a prebuilt binary from our GitHub releases
21+
22+
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.
23+
24+
```bash
25+
mv ./path/to/downloaded/{ZARF_FILE} /usr/local/bin/zarf
26+
```
27+
28+
### Building the CLI from scratch
29+
30+
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/).
31+
32+
```bash
33+
git clone git@github.com:defenseunicorns/zarf.git
34+
cd zarf
35+
make build-cli # This builds all combinations of OS and architecture
36+
mv ./build/{ZARF_FILE} /usr/local/bin/zarf
37+
```
38+
39+
:::note
40+
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:
41+
42+
- `make build-cli-mac-intel`
43+
- `make build-cli-mac-apple`
44+
- `make build-cli-linux-amd`
45+
- `make build-cli-linux-arm`
46+
:::
47+
48+
<br />
49+
50+
## Verifying Zarf Install
51+
52+
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:
53+
54+
```bash
55+
zarf version
56+
57+
# Expected output should look similar to the following
58+
vX.X.X # X.X.X is replaced with the version number of your specific installation
59+
```
60+
61+
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.
62+
63+
<br />
64+
65+
## Where to next?
66+
67+
Depending on how familiar you are with Kubernetes, DevOps, and Zarf, let's find what set of information would be most useful to you!
68+
69+
- If you want to dive straight into Zarf, you can find examples and guides in the [Walkthroughs](./walkthroughs) page.
70+
71+
- 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`.
72+
73+
- More information about the packages that Zarf create and deploy is available in the [Understanding Zarf Packages](./user-guide/zarf-packages/zarf-packages) page.
74+
75+
- 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.

‎docs/4-user-guide/1-the-zarf-cli/1-building-your-own-cli.md

+42
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
# Building Your Own Zarf CLI
2+
3+
:::note
4+
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.
5+
:::
6+
7+
## Dependencies
8+
9+
:::info
10+
11+
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:
12+
13+
1. The Zarf repository cloned down:
14+
- `git clone git@github.com:defenseunicorns/zarf.git`
15+
2. Have Go 1.18.x installed on your PATH (instructions can be found [here](https://go.dev/doc/install))
16+
3. `make` utility installed on your PATH (instructions to install w/ Homebrew can be found [here](https://formulae.brew.sh/formula/make))
17+
18+
:::
19+
20+
## Building The CLI
21+
22+
Once you have the dependencies configured you can build the Zarf CLI by running the following commands:
23+
24+
```bash
25+
cd zarf # go into the root level of the zarf repository
26+
27+
make build-cli # This will build binaries for linux, M1 Mac, and Intel Mac machines
28+
# This puts the built binaries in the ./build directory
29+
```
30+
31+
:::note Optimization Note
32+
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:
33+
34+
- `make build-cli-mac-intel`
35+
- `make build-cli-mac-apple`
36+
- `make build-cli-linux-amd`
37+
- `make build-cli-linux-arm`
38+
:::
39+
40+
#### Breaking Down Whats Happening
41+
42+
[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`.

‎docs/4-user-guide/1-the-zarf-cli/100-cli-commands/0-zarf.md

+29
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
# zarf
2+
3+
Small tool to bundle dependencies with K3s for air-gapped deployments
4+
5+
```
6+
zarf [COMMAND]|[ZARF-PACKAGE]|[ZARF-YAML] [flags]
7+
```
8+
9+
### Options
10+
11+
```
12+
-a, --architecture string Architecture for OCI images
13+
-h, --help help for zarf
14+
-l, --log-level string Log level when running Zarf. Valid options are: warn, info, debug, trace
15+
-t, --toggle Help message for toggle
16+
```
17+
18+
### SEE ALSO
19+
20+
* [zarf completion](./completion) - Generate the autocompletion script for the specified shell
21+
* [zarf connect](./zarf_connect) - Access services or pods deployed in the cluster.
22+
* [zarf destroy](./zarf_destroy) - Tear it all down, we'll miss you Zarf...
23+
* [zarf init](./zarf_init) - Deploys the gitops service or appliance cluster on a clean linux box
24+
* [zarf package](./package) - Pack and unpack updates for the Zarf gitops service.
25+
* [zarf prepare](./prepare) - Tools to help prepare assets for packaging
26+
* [zarf tools](./tools) - Collection of additional tools to make airgap easier
27+
* [zarf version](./zarf_version) - Displays the version the zarf binary was built from
28+
29+
###### Auto generated by spf13/cobra on 20-May-2022

‎docs/4-user-guide/1-the-zarf-cli/100-cli-commands/2-package/index.md

+25
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
# zarf package
2+
3+
Pack and unpack updates for the Zarf gitops service.
4+
5+
### Options
6+
7+
```
8+
-h, --help help for package
9+
```
10+
11+
### Options inherited from parent commands
12+
13+
```
14+
-a, --architecture string Architecture for OCI images
15+
-l, --log-level string Log level when running Zarf. Valid options are: warn, info, debug, trace
16+
```
17+
18+
### SEE ALSO
19+
20+
* [zarf](../zarf) - Small tool to bundle dependencies with K3s for air-gapped deployments
21+
* [zarf package create](./zarf_package_create) - Create an update package to push to the gitops server (runs online)
22+
* [zarf package deploy](./zarf_package_deploy) - Deploys an update package from a local file or URL (runs offline)
23+
* [zarf package inspect](./zarf_package_inspect) - lists the payload of an update package file (runs offline)
24+
25+
###### Auto generated by spf13/cobra on 20-May-2022

‎docs/4-user-guide/1-the-zarf-cli/100-cli-commands/2-package/zarf_package_create.md

+29
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
# zarf package create
2+
3+
Create an update package to push to the gitops server (runs online)
4+
5+
```
6+
zarf package create [flags]
7+
```
8+
9+
### Options
10+
11+
```
12+
--confirm Confirm package creation without prompting
13+
-h, --help help for create
14+
--skip-sbom Skip generating SBOM for this package
15+
--zarf-cache string Specify the location of the Zarf image cache (default ".zarf-image-cache")
16+
```
17+
18+
### Options inherited from parent commands
19+
20+
```
21+
-a, --architecture string Architecture for OCI images
22+
-l, --log-level string Log level when running Zarf. Valid options are: warn, info, debug, trace
23+
```
24+
25+
### SEE ALSO
26+
27+
* [zarf package](./) - Pack and unpack updates for the Zarf gitops service.
28+
29+
###### Auto generated by spf13/cobra on 20-May-2022

0 commit comments

Comments
 (0)