Skip to content

Commit

Permalink
Fix docs links (#1674)
Browse files Browse the repository at this point in the history
## Description

Fixes links to / from the init package page.

## Related Issue

Fixes #N/A

## Type of change

- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [X] Other (security config, docs update, etc)

## Checklist before merging

- [X] Test, docs, adr added or updated as needed
- [X] [Contributor Guide
Steps](https://github.com/defenseunicorns/zarf/blob/main/CONTRIBUTING.md#developer-workflow)
followed
  • Loading branch information
Racer159 committed May 4, 2023
1 parent 8df33b6 commit b03dac1
Show file tree
Hide file tree
Showing 8 changed files with 19 additions and 19 deletions.
2 changes: 1 addition & 1 deletion docs/1-getting-started/1-core-concepts.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,4 +6,4 @@ Now, assuming you're familiar with Kubernetes, AirGap, and GitOps from [Understa

- [**Zarf Package**](../3-create-a-zarf-package/1-zarf-packages.md) - A binary file that contains the instructions and dependencies necessary to install an application on a system.
- [**Zarf Component**](../3-create-a-zarf-package/2-zarf-components.md) - A set of defined functionality and resources that build up a package.
- [**Zarf Init Package**](../3-create-a-zarf-package/3-the-zarf-init-package.md) - The initial package that lays the groundwork for other packages.
- [**Zarf Init Package**](../3-create-a-zarf-package/3-zarf-init-package.md) - The initial package that lays the groundwork for other packages.
6 changes: 3 additions & 3 deletions docs/1-getting-started/2-set-up-and-install.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,17 +40,17 @@ Depending on the permissions of your user, if you are installing K3s through the

<!-- TODO: Link to a support matrix of k8 distros -->

Zarf offers the flexibility of deploying to a wide range of clusters beyond the K3s cluster included in the [init package](../3-create-a-zarf-package/3-the-zarf-init-package.md). This means that you can utilize various options, including local dockerized K8s clusters 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/). Such a diverse set of deployment choices frees you from being tethered to a single cluster option, allowing you to select the best-suited cluster environment for your specific needs.
Zarf offers the flexibility of deploying to a wide range of clusters beyond the K3s cluster included in the [init package](../3-create-a-zarf-package/3-zarf-init-package.md). This means that you can utilize various options, including local dockerized K8s clusters 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/). Such a diverse set of deployment choices frees you from being tethered to a single cluster option, allowing you to select the best-suited cluster environment for your specific needs.

## Initializing a Cluster

<!-- TODO: Some duplicated information from the 'Common CLI Uses' page incoming... -->

After installing the CLI and setting up a cluster, the next step is to initialize the cluster to enable the deployment of application packages.

Initializing a cluster is necessary since most K8 clusters do not come pre-installed with a container registry. This presents a challenging situation since pushing container images into a registry requires a registry to exist in the first place. For more information, please see the [init package](./../3-create-a-zarf-package/3-the-zarf-init-package.md) page.
Initializing a cluster is necessary since most K8 clusters do not come pre-installed with a container registry. This presents a challenging situation since pushing container images into a registry requires a registry to exist in the first place. For more information, please see the [init package](./../3-create-a-zarf-package/3-zarf-init-package.md) page.

As part of the initialization process, Zarf creates a dedicated namespace called `zarf` and deploys several essential components within the cluster. These include an in-cluster Docker registry (serves as the container image host for future packages), a `zarf agent` mutating webhook (to redirect outgoing requests to the internally hosted resources), and a set of secrets. Additionally, users can optionally deploy a gitea server that hosts the Git repositories needed for future packages. For more information regarding package components, see the [init package](./../3-create-a-zarf-package/3-the-zarf-init-package.md) page.
As part of the initialization process, Zarf creates a dedicated namespace called `zarf` and deploys several essential components within the cluster. These include an in-cluster Docker registry (serves as the container image host for future packages), a `zarf agent` mutating webhook (to redirect outgoing requests to the internally hosted resources), and a set of secrets. Additionally, users can optionally deploy a gitea server that hosts the Git repositories needed for future packages. For more information regarding package components, see the [init package](./../3-create-a-zarf-package/3-zarf-init-package.md) page.

To access the relevant init package release, visit the [GitHub releases](https://github.com/defenseunicorns/zarf/releases) page. Once downloaded, navigate to the directory containing the init package and execute the command [`zarf init`](../2-the-zarf-cli/100-cli-commands/zarf_init.md) to install it. Zarf will prompt you to confirm whether you wish to deploy the optional component. You can type 'y' or 'n' depending on your specific use case.

Expand Down
2 changes: 1 addition & 1 deletion docs/2-the-zarf-cli/1-cli-common-uses.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ Before deploying a package to a cluster, you must initialize the cluster using t

For Windows and macOS environments, a cluster must already exist before initializing it using Zarf. You can use [Kind](https://kind.sigs.k8s.io/), [K3d](https://k3d.io/), [Docker Desktop](https://docs.docker.com/desktop/kubernetes/), or any other local or remote Kubernetes cluster.

For Linux environments, Zarf can, itself, create and update a local K3s cluster, in addition to using any other local or remote Kubernetes cluster. The init package used by `zarf init` contains all the resources necessary to create a local [K3s](https://k3s.io/) cluster on your machine. 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. Further details on the initialization process can be found on the [init package](../3-create-a-zarf-package/3-the-zarf-init-package.md) page.
For Linux environments, Zarf can, itself, create and update a local K3s cluster, in addition to using any other local or remote Kubernetes cluster. The init package used by `zarf init` contains all the resources necessary to create a local [K3s](https://k3s.io/) cluster on your machine. 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. Further details on the initialization process can be found on the [init package](../3-create-a-zarf-package/3-zarf-init-package.md) page.

:::note
Depending on the permissions of your user, if you are installing K3s with `zarf init`, you may need to run it as a privileged user. This can be done by either:
Expand Down
2 changes: 1 addition & 1 deletion docs/2-the-zarf-cli/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -127,7 +127,7 @@ As previously mentioned, Zarf was specifically designed to facilitate the deploy

<!-- TODO: Find a good place to talk about what the init command is actually doing (there's a lot of special magic sauce going on with that command) -->

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-the-zarf-init-package.md) page.
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

Expand Down
2 changes: 1 addition & 1 deletion docs/3-create-a-zarf-package/1-zarf-packages.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ Throughout the rest of the documentation, we will refer to the `ZarfInitConfig`

### ZarfInitConfig

The init package is used to initialize a cluster, making it ready for deployment of other Zarf Packages. It must be executed once on each cluster that you want to deploy another package onto, even if multiple clusters share the same host. For additional information on the init package, we provide detailed documentation on the Zarf ['init' package page](./3-the-zarf-init-package.md).
The init package is used to initialize a cluster, making it ready for deployment of other Zarf Packages. It must be executed once on each cluster that you want to deploy another package onto, even if multiple clusters share the same host. For additional information on the init package, we provide detailed documentation on the Zarf ['init' package page](./3-zarf-init-package.md).

If there is no running cluster, the init package can be used to create one. It has a deployable K3s cluster component that can be optionally deployed on your machine. Usually, an init package is the first Zarf Package to be deployed on a cluster as other packages often depend on the services installed or configured by the init package. If you want to install a K8s cluster with Zarf, but you don't want to use K3s as your cluster, you will need to create or find another Zarf Package that will stand up your cluster before you run the zarf init command.

Expand Down
16 changes: 8 additions & 8 deletions docs/3-create-a-zarf-package/3-zarf-init-package.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,29 +6,29 @@ sidebar_position: 3

The 'init' package is a special Zarf Package (denoted by `kind: ZarfInitConfig` in its `zarf.yaml`) that initializes a cluster with the requisite air gap services when running `zarf init`. This allows future Zarf Packages to store any required resources (i.e. container images and git repositories) so that they can be retrieved later.

The default 'init' package that Zarf ships is defined in the `zarf.yaml` that lives at the [root of the Zarf repository](https://github.com/defenseunicorns/zarf/blob/main/zarf.yaml), and is constructed from composed components that provide a foundation for customization. If you would like to change the behavior of the 'init' package you can do so by modifying this `zarf.yaml` or any of the composed components that it references and running `zarf package create` at the root of the repository. You can learn more about creating a custom init package in the [Using Zarf Package Create Walkthrough](../../13-walkthroughs/0-using-zarf-package-create.md).
The default 'init' package that Zarf ships is defined in the `zarf.yaml` that lives at the [root of the Zarf repository](https://github.com/defenseunicorns/zarf/blob/main/zarf.yaml), and is constructed from composed components that provide a foundation for customization. If you would like to change the behavior of the 'init' package you can do so by modifying this `zarf.yaml` or any of the composed components that it references and running `zarf package create` at the root of the repository. You can learn more about creating a custom init package in the [Using Zarf Package Create Walkthrough](../6-zarf-tutorials/0-using-zarf-package-create.md).

Upon deployment, the init package creates a `zarf` namespace within your K8s cluster and deploys pods, services, and secrets to that namespace based on the components selected for deployment.

## Required Component

Zarf's mutation capabilities require that the [`zarf-agent`](../../9-faq.md#what-is-the-zarf-agent) component of the init package is deployed and active within the cluster, meaning that it cannot be disabled and is always running. This component intercepts requests to create resources and uses the `zarf-state` secret to mutate them to point to their air gap equivalents. It is automatically deployed whenever a `zarf init` command is executed.
Zarf's mutation capabilities require that the [`zarf-agent`](../8-faq.md#what-is-the-zarf-agent) component of the init package is deployed and active within the cluster, meaning that it cannot be disabled and is always running. This component intercepts requests to create resources and uses the `zarf-state` secret to mutate them to point to their air gap equivalents. It is automatically deployed whenever a `zarf init` command is executed.

| Component | Description |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| zarf-agent | A Kubernetes mutating webhook installed during `zarf init` that converts Pod specs and Flux GitRepository objects to match their air gap equivalents. |

:::note

The `zarf-agent` will mutate any resources it sees that have not already been patched and don't have the `zarf.dev/agent: ignore` label applied. This label is automatically applied to all namespaces that exist prior to `zarf init`, and will prevent the `zarf-agent` from mutating system resources. You can manually apply this label to any additional namespaces or resources after the fact to prevent the `zarf-agent` from acting upon them. See the FAQ entry to learn more about [what happens to resources that were deployed prior to `zarf init`](../../9-faq.md#what-happens-to-resources-that-exist-in-the-cluster-before-zarf-init).
The `zarf-agent` will mutate any resources it sees that have not already been patched and don't have the `zarf.dev/agent: ignore` label applied. This label is automatically applied to all namespaces that exist prior to `zarf init`, and will prevent the `zarf-agent` from mutating system resources. You can manually apply this label to any additional namespaces or resources after the fact to prevent the `zarf-agent` from acting upon them. See the FAQ entry to learn more about [what happens to resources that were deployed prior to `zarf init`](../8-faq.md#what-happens-to-resources-that-exist-in-the-cluster-before-zarf-init).

:::

## Core Components

In addition to the required `zarf-agent` component, Zarf also offers components that provide additional functionality and can be enabled as needed based on your desired end-state.

In most scenarios, Zarf will also deploy an internal registry using the three components described below. However, Zarf can be configured to use an already existing registry with the `--registry-*` flags when running `zarf init` (detailed information on all `zarf init` command flags can be found in the [zarf init CLI](../1-the-zarf-cli/100-cli-commands/zarf_init.md) section). This option skips the injector and seed process, and will not deploy a registry inside of the cluster. Instead, it uploads any images to the externally configured registry.
In most scenarios, Zarf will also deploy an internal registry using the three components described below. However, Zarf can be configured to use an already existing registry with the `--registry-*` flags when running `zarf init` (detailed information on all `zarf init` command flags can be found in the [zarf init CLI](../2-the-zarf-cli/100-cli-commands/zarf_init.md) section). This option skips the injector and seed process, and will not deploy a registry inside of the cluster. Instead, it uploads any images to the externally configured registry.

| Components | Description |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
Expand All @@ -44,7 +44,7 @@ Given the registry is a core part of any Kubernetes deployment you MUST either s

:::tip

You can further customize how the registry behaves by setting variables such as `REGISTRY_PVC_SIZE` with a [config file](../1-the-zarf-cli/index.md#using-a-config-file-to-make-cli-command-flags-declarative) or `--set` on `zarf init`.
You can further customize how the registry behaves by setting variables such as `REGISTRY_PVC_SIZE` with a [config file](../2-the-zarf-cli/index.md#using-a-config-file-to-make-cli-command-flags-declarative) or `--set` on `zarf init`.

To see a full list of `variables` you can view the [zarf.yaml that defines the registry](https://github.com/defenseunicorns/zarf/blob/main/packages/zarf-registry/zarf.yaml).

Expand Down Expand Up @@ -78,15 +78,15 @@ root@machine ~ # zarf init --components k3s --set K3S_ARGS="" --confirm

:::tip

You can further customize how the git-server behaves by setting variables such as `GIT_SERVER_PVC_SIZE` with a [config file](../1-the-zarf-cli/index.md#using-a-config-file-to-make-cli-command-flags-declarative) or `--set` on `zarf init`.
You can further customize how the git-server behaves by setting variables such as `GIT_SERVER_PVC_SIZE` with a [config file](../2-the-zarf-cli/index.md#using-a-config-file-to-make-cli-command-flags-declarative) or `--set` on `zarf init`.

To see a full list of `variables` you can view the [zarf.yaml that defines the git-server](https://github.com/defenseunicorns/zarf/blob/main/packages/gitea/zarf.yaml).

:::

## What Makes the Init Package Special

Deploying into air gapped environments is a [hard problem](../../1-understand-the-basics.md#what-is-the-air-gap), particularly when the K8s environment doesn't have a container registry for you to store images in already. This results in a dilemma where the container registry image must be introduced to the cluster, but there is no container registry to push it to as the image is not yet in the cluster - chicken, meet egg. To ensure that our approach is distro-agnostic, we developed a unique solution to seed the container registry into the cluster.
Deploying into air gapped environments is a [hard problem](../1-getting-started/0-understand-the-basics.md#what-is-the-air-gap), particularly when the K8s environment doesn't have a container registry for you to store images in already. This results in a dilemma where the container registry image must be introduced to the cluster, but there is no container registry to push it to as the image is not yet in the cluster - chicken, meet egg. To ensure that our approach is distro-agnostic, we developed a unique solution to seed the container registry into the cluster.

This is done with the `zarf-injector` [component](https://github.com/defenseunicorns/zarf/blob/main/packages/zarf-injector/zarf.yaml) which injects a single rust binary (statically compiled) and a series of configmap chunks of a `registry:2` image into an ephemeral pod that is based on an existing image in the cluster. This gives us a running registry to bootstrap from and deploy the rest of the 'init' package and any other packages down the line.

Expand All @@ -98,7 +98,7 @@ The `registry:2` image and the Zarf Agent image can be configured with a custom

## The `zarf init` Lifecycle

The `zarf init` lifecycle is _very similar_ to the [`zarf package deploy` lifecycle](../4-package-command-lifecycle.md#zarf-package-deploy) except that it sets up resources specific to Zarf such as the `zarf-state` and performs special actions such as the injection procedure.
The `zarf init` lifecycle is _very similar_ to the [`zarf package deploy` lifecycle](./6-package-create-lifecycle.md#zarf-package-deploy) except that it sets up resources specific to Zarf such as the `zarf-state` and performs special actions such as the injection procedure.

```mermaid
graph TD
Expand Down
Loading

0 comments on commit b03dac1

Please sign in to comment.