diff --git a/docs/.images/what-is-zarf/appliance-mode.png b/docs/.images/what-is-zarf/appliance-mode.png deleted file mode 100644 index ec93133ad6..0000000000 Binary files a/docs/.images/what-is-zarf/appliance-mode.png and /dev/null differ diff --git a/docs/.images/what-is-zarf/appliance.drawio.png b/docs/.images/what-is-zarf/appliance.drawio.png new file mode 100644 index 0000000000..13ccfe81cc Binary files /dev/null and b/docs/.images/what-is-zarf/appliance.drawio.png differ diff --git a/docs/.images/what-is-zarf/build-the-package.png b/docs/.images/what-is-zarf/build-the-package.png deleted file mode 100644 index 31edb1aa03..0000000000 Binary files a/docs/.images/what-is-zarf/build-the-package.png and /dev/null differ diff --git a/docs/.images/what-is-zarf/existing-cluster.drawio.png b/docs/.images/what-is-zarf/existing-cluster.drawio.png new file mode 100644 index 0000000000..b6fee8f4d0 Binary files /dev/null and b/docs/.images/what-is-zarf/existing-cluster.drawio.png differ diff --git a/docs/.images/what-is-zarf/how-to-use-it.png b/docs/.images/what-is-zarf/how-to-use-it.png deleted file mode 100644 index 0e81561b56..0000000000 Binary files a/docs/.images/what-is-zarf/how-to-use-it.png and /dev/null differ diff --git a/docs/.images/what-is-zarf/how-to-use-zarf.drawio.png b/docs/.images/what-is-zarf/how-to-use-zarf.drawio.png new file mode 100644 index 0000000000..7b62e58243 Binary files /dev/null and b/docs/.images/what-is-zarf/how-to-use-zarf.drawio.png differ diff --git a/docs/.images/what-is-zarf/ship-the-package.png b/docs/.images/what-is-zarf/ship-the-package.png deleted file mode 100644 index 8627c97f63..0000000000 Binary files a/docs/.images/what-is-zarf/ship-the-package.png and /dev/null differ diff --git a/docs/.images/what-is-zarf/utility-cluster.drawio.png b/docs/.images/what-is-zarf/utility-cluster.drawio.png new file mode 100644 index 0000000000..26f289ea9f Binary files /dev/null and b/docs/.images/what-is-zarf/utility-cluster.drawio.png differ diff --git a/docs/.images/what-is-zarf/utility-mode.png b/docs/.images/what-is-zarf/utility-mode.png deleted file mode 100644 index cb43b08acc..0000000000 Binary files a/docs/.images/what-is-zarf/utility-mode.png and /dev/null differ diff --git a/docs/0-zarf-overview.md b/docs/0-zarf-overview.md index 9c615c2ddc..57f12896b3 100644 --- a/docs/0-zarf-overview.md +++ b/docs/0-zarf-overview.md @@ -11,13 +11,13 @@ import Tabs from "@theme/Tabs"; ## What is Zarf? -Zarf was created to _**support the declarative creation & distribution of software "packages" into remote/constrained/independent environments**_. +Zarf was created to _**support the declarative creation & distribution of software "packages" into remote/constrained/standalone environments**_. > "Zarf is a tool to help deploy modern stacks into air-gapped environments; it's all about moving the bits." — Jeff -Zarf is a free and open-source tool that simplifies the setup and deployment of applications and resources onto air-gapped or disconnected environments. Zarf equips you with the ability to quickly and securely deploy modern software onto complex systems without relying on internet connectivity. +Zarf is a free and open-source tool that simplifies the setup and deployment of applications and supporting resources onto air-gapped or disconnected environments. Zarf equips you with the ability to quickly and securely deploy modern software onto complex 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. +It also simplifies the installation, update, and maintenance of supporting DevSecOps capabilities like Kubernetes clusters and logging stacks, while providing features that ensure supply chain security, including SBOM compliance. Most importantly though, Zarf keeps applications and systems running even when they are disconnected. :::note @@ -27,21 +27,21 @@ Check out our [glossary](1-getting-started/0-understand-the-basics.md) for an ex ## How Zarf Works -Zarf simplifies and standardizes the delivery of complex software deployments. This gives users the ability to reduce tens/hundreds of individual software updates, movements, and manual installations to a few simple terminal commands. This tool 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). +Zarf simplifies and standardizes the delivery of complex software deployments. This gives users the ability to reduce tens/hundreds of individual software updates, data transfers, and manual installations to a few simple terminal commands. This tool equips users with the ability to pull, package, and install all of 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 tooling (such as Open Tofu / Terraform). ![Zarf CLI + Zarf Init + Zarf Package](.images/Zarf%20Files%20-%20%203%20Bubbles.svg) A typical Zarf deployment is made up of three parts: -1. The `zarf` binary: - - A statically compiled Go binary that can be run on any machine, server, or operating system with or without connectivity. - - Creates packages containing numerous software types/updates into a single distributable package (while on an internet-accessible network). - - Declaratively deploys package contents "into place" for use on production systems (while on an internet-isolated network). -2. A Zarf init package: +1. The [`zarf` binary](./2-the-zarf-cli/index.md): + - Is a statically compiled Go binary that can be run on any machine, server, or operating system with or without connectivity. + - Creates packages combining numerous types of software/updates into a single distributable package (while on a network capable of accessing them). + - Declaratively deploys package contents "into place" for use on production systems (while on an isolated network). +2. A [Zarf init package](./3-create-a-zarf-package/3-zarf-init-package.md): - A compressed tarball package that contains the configuration needed to instantiate an environment without connectivity. - - Automatically seeds your cluster with a container registry. - - Provides additional capabilities such as logging, git server, and K8s cluster. -3. A Zarf Package: + - Automatically seeds your cluster with a container registry or wires up a pre-existing one + - Provides additional capabilities such as logging, git server support, and/or a K8s cluster. +3. A [Zarf Package](./3-create-a-zarf-package/1-zarf-packages.md): - A compressed tarball package that contains all of the files, manifests, source repositories, and images needed to deploy your infrastructure, application, and resources in a disconnected environment. :::note @@ -59,60 +59,66 @@ For more technical information on how Zarf works and to view the Zarf architectu ## What can be Packaged? -Given Zarf's being a "K8s cluster to serve _other_ K8s clusters", the following types of software can be rolled into a Zarf Package: +The following types of software can be rolled into a Zarf Package: -- Container images: to serve images for the Zarf and downstream clusters to run containers from. -- Repositories: to serve as the git-based "source of truth" for downstream "GitOps"ed K8s clusters to watch. -- Pre-compiled binaries: to provide the software necessary to start and support the Zarf cluster. +- Container images + artifacts: to serve images and OCI artifacts for clusters and other consumers to pull. +- [Repositories](../examples/git-data/README.md): to serve as the git-based "source of truth" for GitOps application deployments. +- Pre-compiled binaries: to provide the software necessary to start and support a cluster. - [Component actions](3-create-a-zarf-package/7-component-actions.md): to support scripts and commands that run at various stages of the Zarf [package create lifecycle](./3-create-a-zarf-package/5-package-create-lifecycle.md), and [package deploy lifecycle](./4-deploy-a-zarf-package/1-package-deploy-lifecycle.md). -- Helm charts, kustomizations, and other K8s manifests: to apply in a Kubernetes cluster. +- Helm charts, kustomizations, and other K8s manifests: to apply to a Kubernetes cluster. - [Data injections](../examples/kiwix/README.md): to declaratively inject data into running containers in a Kubernetes cluster. ## How To Use Zarf Zarf is intended for use in a software deployment process that looks similar to this: -![How Zarf works](./.images/what-is-zarf/how-to-use-it.png) +![How Zarf works](./.images/what-is-zarf/how-to-use-zarf.drawio.png) ### (0) Connect to the Internet Zarf doesn't build softwareβ€”it helps you distribute software that already exists. -Zarf can pull from various places like Docker Hub, Iron Bank, GitHub, and local filesystems. In order to do this, you must ensure that Zarf has a clear path and appropriate access credentials. Be sure you know what you want to pack and how to access it before you begin using Zarf. +Zarf can pull from various places like Docker Hub, Iron Bank, GitHub, private registries and local filesystems. In order to do this, you must ensure that Zarf has a clear path and appropriate access credentials. Be sure you know what you want to pack and how to access it before you begin using Zarf. ### (1) Create a Package -This part of the process requires access to the internet. The `zarf` binary is presented with a `zarf.yaml`, it then begins downloading, packing, and compressing the software that you requested. It then outputs a single, ready-to-move distributable called "a package". +This part of the process requires access to the internet (or a network that mirrors your resources). When the `zarf` binary is presented with a `zarf.yaml`, it then begins downloading, packing, and compressing the software that you requested. It then outputs a single, ready-to-move distributable called "a package". For additional information, see the [Creating a package](./5-zarf-tutorials/0-creating-a-zarf-package.md) section. ### (2) Ship the Package to the System Location -Zarf enables secure software delivery for various environments, such as remote, constrained, independent, and air-gapped systems. Considering there are various target environments with their own appropriate transferring mechanisms, Zarf does not determine _how_ packages are moved so long as they can arrive in your downstream environment. +Zarf enables secure software delivery for various environments, such as remote, constrained, standalone, and air-gapped systems. Considering there are various target environments with their own appropriate transferring mechanisms, Zarf does not determine _how_ packages are moved so long as they can arrive in your downstream environment. See [Package Sources](./4-deploy-a-zarf-package/2-package-sources.md) for more information on where Zarf packages can be stored / pulled from. ### (3) Deploy the Package Once your package has arrived, you will need to: 1. Install the binary onto the system. -2. Run the zarf init package. -3. Deploy the package to your cluster. +2. Initialize a cluster with a zarf init package (`zarf init`) +3. Deploy the package to your cluster (`zarf package deploy`) ## Cluster Configuration Options -Zarf allows the package to either deploy to an existing K8s cluster or a local K3s cluster. This is a configuration that is available on deployment in the init package. +Zarf allows the package to either deploy to a K3s cluster it creates or an existing K8s cluster. This configuration is available on deployment of the init package. -### Appliance Cluster Mode +### Initialize `k3s` as an Appliance -![Appliance Mode Diagram](.images/what-is-zarf/appliance-mode.png) +![Appliance Cluster Diagram](.images/what-is-zarf/appliance.drawio.png) -In the simplest usage scenario, your package consists of a single application (plus dependencies) and you configure the Zarf cluster to serve your application directly to end users. This mode of operation is called "Appliance Mode" and it is intended for use in environments where you want to run K8s-native tooling but need to keep a small footprint (i.e. single-purpose/constrained/"Edge" environments). +In the simplest usage scenario, you deploy the Zarf init package's builtin cluster and use it to serve your application(s) directly to end users. This configuration runs Zarf and it's init package components as a self-contained appliance and is intended for use in environments where you want to run K8s-native tooling but need to keep a small footprint (i.e. single-purpose/constrained/"Edge" environments). -### Utility Cluster Mode +### Initialize `k3s` as a Utility Cluster -![Appliance Mode Diagram](.images/what-is-zarf/utility-mode.png) +![Utility Cluster Diagram](.images/what-is-zarf/utility-cluster.drawio.png) -In the more complex use case, your package consists of updates for many apps/systems and you configure the Zarf cluster to propagate updates to downstream systems rather than to serve users directly. This mode of operation is called "Utility Mode" and it is intended for use in places where you want to run independent, full-service production environments (ex. your own Big Bang cluster) but you need help tracking, caching and disseminating system/dependency updates. +In a more complex use case, you deploy the Zarf init package's builtin cluster and use it to serve resources to further downstream clusters. This configuration makes your Zarf deployment a utility cluster in service of a larger system and is intended for use in places where you want to run independent, full-service production environments with their own lifecycles but you want help tracking, caching and disseminating system/dependency updates. + +### Skip `k3s` and Initialize to an Existing Cluster + +![Existing Cluster Diagram](.images/what-is-zarf/existing-cluster.drawio.png) + +In this use case, you configure Zarf to initialize a cluster that already exists within your environment, and use that existing cluster to host and serve your applications. This configuration is intended for environments that may already have some supporting infrastructure such as disconnected / highly regulated cloud environments. ## Why Use Zarf? @@ -194,7 +200,18 @@ zarf package deploy oci://defenseunicorns/dos-games:1.0.0-$(uname -m) --key=http :::note -Zarf has no prerequisites on Linux. However, for this example, we will use Docker and Kind. +This example shows how to install Zarf with the official (πŸ“œ) `defenseunicorns` Homebrew tap, however there are many other options to install Zarf on Linux such as: + +- πŸ“œ **[official]** Downloading Zarf directly from [GitHub releases](https://github.com/defenseunicorns/zarf/releases) +- πŸ§‘β€πŸ€β€πŸ§‘ **[community]** `apk add` on [Alpine Linux Edge](https://pkgs.alpinelinux.org/package/edge/testing/x86_64/zarf) +- πŸ§‘β€πŸ€β€πŸ§‘ **[community]** `asdf install` with the [ASDF Version Manager](https://github.com/defenseunicorns/asdf-zarf) +- πŸ§‘β€πŸ€β€πŸ§‘ **[community]** `nix-shell`/`nix-env` with [Nix Packages](https://search.nixos.org/packages?channel=23.05&show=zarf&from=0&size=50&sort=relevance&type=packages&query=zarf) + +::: + +:::tip + +Zarf can deploy it's own `k3s` cluster on Linux if you have `root` access by selecting the `k3s` component on `zarf init`. ::: @@ -235,8 +252,17 @@ zarf package deploy oci://πŸ¦„/dos-games:1.0.0-$(uname -m) --key=https://zarf.de ## Windows Commands + +:::info + +There is currently no Zarf Quick Start for Windows, though you can learn how to install Zarf from our Github Releases by visiting the [Getting Started page](./1-getting-started/index.md#downloading-from-github-releases) + +::: + ```text + Coming soon! + ``` diff --git a/docs/1-getting-started/index.md b/docs/1-getting-started/index.md index 7bba3bfc9b..d0a852da6e 100644 --- a/docs/1-getting-started/index.md +++ b/docs/1-getting-started/index.md @@ -1,3 +1,6 @@ +import TabItem from "@theme/TabItem"; +import Tabs from "@theme/Tabs"; + # Getting Started Welcome to the Zarf documentation! This section will list the various ways to install Zarf onto your machine. It will also demonstrate how to verify the installation. Choose the installation type that best suits your needs in accordance with your operating system. Let's get started! @@ -6,33 +9,101 @@ Welcome to the Zarf documentation! This section will list the various ways to in There are multiple ways to get the Zarf CLI onto your machine: -- Install from [Homebrew](#installing-from-the-defense-unicorns-homebrew-tap). +- [Install from Homebrew](#installing-from-the-defense-unicorns-homebrew-tap). - [Download a prebuilt binary](#downloading-a-prebuilt-binary-from-our-github-releases). - [Build the CLI](#building-the-cli-from-scratch) from scratch. -### Installing from the Defense Unicorns Homebrew Tap +### Installing with Homebrew + +[Homebrew](https://brew.sh/) is an open-source software package manager that simplifies the installation of software on macOS and Linux. + -[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 simple: + + + +With Homebrew on macOS, installing Zarf is as simple as: ```bash -brew tap defenseunicorns/tap -brew install zarf +brew tap defenseunicorns/tap && brew install zarf ``` + + + +With Homebrew on Linux, installing Zarf is as simple as: + +```bash +brew tap defenseunicorns/tap && brew install zarf +``` + + + + +:::note + The above command detects your OS and system architecture and installs the correct Zarf CLI binary for your machine. Once the above command is entered, the CLI should be installed on your `$PATH` and is ready for immediate use. -### Downloading a Prebuilt Binary from our GitHub Releases +::: + +### Downloading from GitHub Releases + +All [Zarf releases](https://github.com/defenseunicorns/zarf/releases) on GitHub include prebuilt binaries that you can download and use. We offer range of combinations of OS and architecture for you to choose from. + + + -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. +To download Zarf on Linux you can run the following (replacing `` with a version of Zarf): -On most Linux distributions, you can install the binary onto your `$PATH` by simply moving the downloaded binary to the `/usr/local/bin` directory: +```bash +ZARF_VERSION= +ZARF_ARCH=$([ $(uname -m) == "x86_64" ] && echo "amd64" || echo "arm64";) + +curl -sL https://github.com/defenseunicorns/zarf/releases/download/${ZARF_VERSION}/zarf_${ZARF_VERSION}_Linux_${ZARF_ARCH} -o zarf +chmod +x zarf +``` + +On most Linux distributions, you can also install the binary onto your `$PATH` by simply moving the downloaded binary to the `/usr/local/bin` directory: ```bash -chmod +x ./path/to/downloaded/{ZARF_FILE} -mv ./path/to/downloaded/{ZARF_FILE} /usr/local/bin/zarf +sudo mv zarf /usr/local/bin/zarf ``` -On Windows or macOS, you can install the binary onto your `$PATH` by moving the downloaded binary to the desired directory and modifying the `$PATH` environment variable to include that directory. + + + +To download Zarf on macOS you can run the following (replacing `` with a version of Zarf): + +```bash +ZARF_VERSION= +ZARF_ARCH=$([ $(uname -m) == "x86_64" ] && echo "amd64" || echo "arm64";) + +curl -sL https://github.com/defenseunicorns/zarf/releases/download/${ZARF_VERSION}/zarf_${ZARF_VERSION}_Darwin_${ZARF_ARCH} -o zarf +chmod +x zarf +``` + +You can also install the binary onto your `$PATH` by simply moving the downloaded binary to the `/usr/local/bin` directory: + +```bash +sudo mv zarf /usr/local/bin/zarf +``` + + + + + +To download Zarf on Windows you can run the following (replacing `` with a version of Zarf and `` with either `amd64` or `arm64` depending on your system): + +```bash +$ZarfVersion="" +$ZarfArch="" + +Start-BitsTransfer -Source "https://github.com/defenseunicorns/zarf/releases/download/$($ZarfVersion)/zarf_$($ZarfVersion)_Windows_$($ZarfArch).exe" -Destination zarf.exe +``` + +You can also install the binary onto your `$PATH` by moving the downloaded binary to the desired directory and modifying the `$PATH` environment variable to include that directory. + + + ### Building the CLI from Scratch @@ -53,8 +124,6 @@ For additional information, see the [Building Your Own Zarf CLI](../2-the-zarf-c ::: ---- - ## Verifying the Zarf Install Now that you have installed Zarf, let's verify that it is working. First, we'll check the version of Zarf that has been installed: @@ -67,15 +136,13 @@ vX.X.X # X.X.X is replaced with the version number of your specific installatio If you are not seeing this then Zarf was not installed onto your `$PATH` correctly. [This $PATH guide](https://zwbetz.com/how-to-add-a-binary-to-your-path-on-macos-linux-windows/) should help with that. ---- - ## Downloading the ['Init' Package](../3-create-a-zarf-package/3-zarf-init-package.md) The ['init' package](../3-create-a-zarf-package/3-zarf-init-package.md) is a special Zarf package that initializes a cluster with services that are used to store resources while in the air gap and is required for most ([but not all](../../examples/yolo/README.md)) Zarf deployments. You can get it for your version of Zarf by visiting the [Zarf releases](https://github.com/defenseunicorns/zarf/releases) page and downloading it into your working directory or into `~/.zarf-cache/zarf-init--vX.X.X.tar.zst`) -If you are online on the machine with cluster access you can also run `zarf init` without the `--confirm` flag to be given the option to download the version of the init package for your Zarf version. +If you are online on the machine with cluster access you can also run `zarf init` without the `--confirm` flag to be given the option to download the version of the init package for your Zarf version or you can use the `zarf tools download-init` command. :::note @@ -83,8 +150,6 @@ You can build your own custom 'init' package too if you'd like. For this you sho ::: ---- - ## 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. diff --git a/docs/2-the-zarf-cli/index.md b/docs/2-the-zarf-cli/index.md index f14c049c87..3992d368e8 100644 --- a/docs/2-the-zarf-cli/index.md +++ b/docs/2-the-zarf-cli/index.md @@ -1,137 +1,39 @@ -import TabItem from "@theme/TabItem"; -import Tabs from "@theme/Tabs"; - # The Zarf CLI - - - - -Zarf is a command line interface (CLI) tool that enables secure software delivery, with a particular focus on delivery to disconnected or complex environments. Zarf is a statically compiled Go binary, which means it can be utilized in any environment without requiring additional dependencies. The Zarf CLI project is an always free, open-source project available on [GitHub](https://github.com/defenseunicorns/zarf). +Zarf is a command line interface (CLI) tool that enables secure software delivery, with a particular focus on delivery to disconnected or highly regulated environments. Zarf is a statically compiled Go binary, which means it can be utilized in any environment without requiring additional dependencies. ## Getting the CLI - - - -You can get the Zarf CLI on your machine in a few different ways. You can use the Defense Unicorns Homebrew Tap, download a prebuilt binary from our GitHub releases, or build the CLI from scratch on your own. We provide instructions for all of these methods in the [Installing Zarf](../1-getting-started/index.md#installing-zarf) section of the Getting Started guide. If you're eager to start using Zarf and you already have Homebrew installed, you can quickly install it by copying and pasting the relevant commands for your operating system into your terminal: - - - - - -```bash -brew tap defenseunicorns/tap -brew install zarf -``` - - - - - -```bash -brew tap defenseunicorns/tap -brew install zarf -``` - - - - -## Verify the CLI - - - -To begin, we'll test whether the CLI you have is functioning correctly. Running the CLI will generate a help message output, which will verify its functionality. Depending on the method you used to install the CLI, the tabs below will provide guidance on how to initiate it for the first time. Upon successful installation, you should see a comprehensive list of all command options, along with concise descriptions of their functions. - -
Expected Help Output -

-The output of the help command should look something like this (CLI flags will also appear at the end of the output): - -```text -Zarf eliminates the complexity of air gap software delivery for Kubernetes clusters and cloud native workloads -using a declarative packaging strategy to support DevSecOps in offline and semi-connected environments. - -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 Zarf package commands for creating, deploying, and inspecting packages - 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 -``` - -

-
+You can get the Zarf CLI on your machine in a few different ways, using the Defense Unicorns Homebrew Tap, downloading a prebuilt binary from our GitHub releases, or building the CLI from scratch on your own. - - +We provide instructions for all of these methods in the [Installing Zarf](../1-getting-started/index.md#installing-zarf) section of the Getting Started guide. -```bash -zarf --help -``` - - - - - -- If you're not sure where the file was downloaded, 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. +## Introduction to Zarf Commands -```bash -chmod +x ~/Downloads/zarf # Make the binary executable -~/Downloaded/zarf --help -``` +Zarf provides a suite of commands that streamline the creation, deployment, and maintenance of packages. Some of these commands contain additional sub-commands to further assist with package management. When executed with the `--help` flag, each command and sub-command provides a concise summary of its functionality. As you navigate deeper into the command hierarchy, the provided descriptions become increasingly detailed. We encourage you to explore the various commands available to gain a comprehensive understanding of Zarf's capabilities. - +As previously mentioned, Zarf was specifically designed to facilitate the deployment of applications in disconnected environments with ease. As a result, the most commonly utilized commands are `zarf init`, `zarf package create`, and `zarf package deploy`. Detailed information on all commands can be found in the [CLI Commands](./100-cli-commands/zarf.md) section. However, brief descriptions of the most frequently used commands are provided below. It's worth noting that these three commands are closely linked to what we refer to as a "Zarf Package". Additional information on Zarf Packages can be found on the [Zarf Packages](../3-create-a-zarf-package/1-zarf-packages.md) page. - +### zarf init -- 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`. +The `zarf init` command is used to configure a K8s cluster in preparation for the deployment of future Zarf Packages. The init command uses a specialized 'init-package' to operate which may be located in your current working directory, the directory where the Zarf CLI binary is located, or downloaded from the GitHub Container Registry during command execution. For further details regarding the init-package, please refer to the [init-package](../3-create-a-zarf-package/3-zarf-init-package.md) page. -```bash -cd ./path/to/zarf/repo -cd build -./zarf --help -``` +### zarf package deploy - +The `zarf package deploy` command is used to deploy an already created Zarf package onto a machine, typically to a K8s cluster. Generally, it is presumed that the `zarf init` command has already been executed on the target machine, however, there are a few exceptional cases where this assumption does not apply. You can learn more about deploying Zarf packages on the [Deploy a Zarf Package](../4-deploy-a-zarf-package/index.md) page. - +:::tip -### Adding The CLI To Your Path +When deploying and managing packages you may find the sub-commands under `zarf tools` useful to troubleshoot or interact with deployments. -:::note -If you installed Zarf through Homebrew, Zarf will already be on your $PATH and you can skip this section. ::: -To simplify the usage of the Zarf CLI, you may add it to your $PATH. This configuration will allow you to use `zarf` without having to specify the binary's precise location and your computer will automatically find the binary for you to execute. The directories listed in your $PATH can be viewed by executing the command `echo $PATH` in your terminal. If you move your CLI to any of these directories, you will be able to execute it without the need to specify its full path. A typical $PATH you can use is: `mv ./path/to/cli/file/zarf /usr/local/bin/zarf` - -:::note -Throughout the rest of the documentation, we will often be describing commands as `zarf {command}`. This assumes that the CLI is on your $PATH. -::: +### zarf package create -## Introduction to Zarf Commands +The `zarf package create` command is used to create a Zarf package from a `zarf.yaml` package definition. This command will pull all of the defined resources into a single package you can take with you to a disconnected environment. You can learn more about creating Zarf packages on the [Create a Zarf Package](../3-create-a-zarf-package/index.md) page. -Zarf provides a suite of commands that streamline the creation, deployment, and maintenance of packages. Some of these commands contain additional sub-commands to further assist with package management. When executed with the "--help" flag, each command and sub-command provides a concise summary of its functionality. As you navigate deeper into the command hierarchy, the provided descriptions become increasingly detailed. We encourage you to explore the various commands available to gain a comprehensive understanding of Zarf's capabilities. +:::tip -As previously mentioned, Zarf was specifically designed to facilitate the deployment of applications in disconnected environments with ease. As a result, the most commonly utilized commands are `zarf init`, `zarf package create`, and `zarf package deploy`. Detailed information on all commands can be found in the [CLI Commands](./100-cli-commands/zarf.md) section. However, brief descriptions of the most frequently used commands are provided below. It's worth noting that these three commands are closely linked to what we refer to as a "Zarf Package". Additional information on Zarf Packages can be found in the following section: [Zarf Packages](../3-create-a-zarf-package/1-zarf-packages.md). +When deploying and managing packages you may find the sub-commands under `zarf prepare` useful to find resources and manipulate package definitions as needed. -### zarf init - - - -The `zarf init` command is utilized to configure a K8s cluster in preparation for the deployment of future Zarf Packages. The init command uses a specialized 'init-package' to operate. This package may be located in your current working directory, the directory where the Zarf CLI binary is located, or downloaded from GitHub releases during command execution. For further details regarding the init-package, please refer to the [init-package](../3-create-a-zarf-package/3-zarf-init-package.md) page. - -### zarf package deploy - - - - -The `zarf package deploy` command is used to deploy an already built tar.zst package onto a machine, typically within a K8s cluster. Generally, it is presumed that the `zarf init` command has already been executed on the target machine. However, there are a few exceptional cases where this assumption does not apply. +::: diff --git a/examples/podinfo-flux/README.md b/examples/podinfo-flux/README.md index d9a00d33c9..70bd096f10 100644 --- a/examples/podinfo-flux/README.md +++ b/examples/podinfo-flux/README.md @@ -6,7 +6,7 @@ This example demonstrates how to use flux with Zarf to deploy the `stefanprodan/ It uses a vanilla configuration of flux with upstream containers. -If you want to learn more about how Zarf handles `git` repositories, see the [git-data](../git-data/) example. +If you want to learn more about how Zarf handles `git` repositories, see the [git-data](../git-data/README.md) example. ## `zarf.yaml` {#zarf.yaml}