diff --git a/docs/4-user-guide/index.md b/docs/4-user-guide/index.md index ab601d4928..89d002d4c5 100644 --- a/docs/4-user-guide/index.md +++ b/docs/4-user-guide/index.md @@ -1,47 +1,59 @@ # User Guide -Experience just how easy it is to go from zero to chainsaw-wielding hero (of the Kubernetes cluster) using Zarf! +Using Zarf optimizes the delivery of applications and capabilities in air-gapped and complex environments. This tool eliminates the complexity of air gap software delivery for Kubernetes clusters and cloud-native workloads using a declarative packaging strategy to support DevSecOps. This guide is intended for end users using Zarf to securely and efficiently deploy modern stacks onto remote/constrained/independent environments. -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: +The below list 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/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) +- 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/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). ## Overview of Zarf Workflow -### Create a package +### Create a Package diagram showing the process to build a package -#### (0) - Identify software to-be-moved +#### (0) Identify Software to be Packaged -Zarf doesn't build software; it helps you distribute software that already exists. +Zarf doesn't build software—it helps you distribute software that already exists. -Zarf can pull from sources like [Docker Hub](https://hub.docker.com/), [Iron Bank](https://p1.dso.mil/products/iron-bank), [GitHub](https://github.com/), local filesystems, etc. but you have to make sure that Zarf has a clear path & appropriate access credentials. Be sure you know what you want to pack & how to access it before you Zarf. +Zarf can pull from sources like [Docker Hub](https://hub.docker.com/), [Iron Bank](https://p1.dso.mil/products/iron-bank), [GitHub](https://github.com/), 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. -Find out more about the types of software Zarf can move in the "[What can be packaged?](../0-zarf-overview.md#what-can-be-packaged)" section. +:::note -#### (1) - Preparation +Find out more about the types of software Zarf can move in the [What can be Packaged](../0-zarf-overview.md#what-can-be-packaged) section. -To build a Zarf package, you need to prepare: +::: -- a "packaging" workstation which must have the `zarf` [CLI tool installed](../3-getting-started.md#installing-zarf), and +#### (1) Preparation -- a `zarf.yaml` file which tells Zarf what you need to package. +To build a Zarf package, you will need to prepare: -Find some detailed uses of the `zarf.yaml` file in [our examples](../../examples/). +- A "packaging" workstation which must have the `zarf` [CLI tool installed](../3-getting-started.md#installing-zarf). -#### (2) - Package +- A `zarf.yaml` file which tells Zarf what you need to package. -Making a Zarf package out of a `zarf.yaml` file is a matter of calling a single, simple command: `zarf package create`. You'll see a `zarf-package-*.tar.zst` file pop into existence afterward. That's your package. +:::note -Find out more about that by calling the CLI for help, or check out an example package build in [our game example](../../examples/dos-games#package-the-game). +For additional information and detailed uses of the `zarf.yaml` file, see [our examples](../../examples/) page. + +::: + +#### (2) Package + +Making a Zarf Package out of a `zarf.yaml` file is a matter of calling a single command: `zarf package create`. You will see a `zarf-package-*.tar.zst` file populate aftwerards—that's your package. + +:::note + +For more information you can call the CLI for help, or check out an example package build in [our game example](../../examples/dos-games#package-the-game). + +::: ### Ship Package @@ -49,22 +61,28 @@ Find out more about that by calling the CLI for help, or check out an example pa diagram showing the process to ship a package -What this activity looks like is _very_ contextual to the target environment, so Zarf tries not to have an opinion. Transfer Zarf packages between production & operating locations using whatever mechanisms are appropriate. - -Have to burn your package to disk & "sneakernet" it? That works. +Shipping a Zarf Package is _very_ contextual to the target environment. 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. Transfer Zarf Packages between production and operating locations using whatever mechanisms are appropriate for your mission. -Got an intermittent, super-secret satellite uplink you can use? Awesome. +There are numerous methods to transport your Zarf Package, for example: -Can you make a direct network connection? Even better. +- Burning your package onto a disk. +- Using a satellite uplink. +- Creating a direct internet connection. -Consider the art of the possible and use what you can. Zarf will work, regardless. +No matter the system complexity or internet connectivity, Zarf will work regardless. ### Deploy Package -## Other Resources +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. + +## Additional Resources -If you are looking for more advanced information on how to operate and customize Zarf to your specific environment needs, check out these additional resources. +If you are looking for more advanced information on how to operate and customize Zarf to your specific environment needs, check out these additional resources: -- For information on how to create a custom configuration of the Zarf CLI see the [Operator Manual](../5-operator-manual/_category_.json) -- For information on how to create your own 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](../../examples/README.md) +- For information on how to create a custom configuration of the Zarf CLI see the [Operator Manual](../5-operator-manual/_category_.json). +- For information on how to create your own 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 air-gapped systems see the [Zarf Examples](../../examples/README.md).