From a8aa16723f099e5bc7dbc3d9fb7674624fcc223c Mon Sep 17 00:00:00 2001 From: Austin Abro <37223396+AustinAbro321@users.noreply.github.com> Date: Wed, 24 Apr 2024 16:26:39 -0400 Subject: [PATCH] docs: init package clarity and cleanup (#2447) ## Description There was duplication in the docs, I also reorganized / reworded some messaging around the init package ## Checklist before merging - [x] Test, docs, adr added or updated as needed - [x] [Contributor Guide Steps](https://github.com/defenseunicorns/zarf/blob/main/.github/CONTRIBUTING.md#developer-workflow) followed --------- Co-authored-by: Lucas Rodriguez Co-authored-by: schristoff <167717759+schristoff-du@users.noreply.github.com> --- site/src/content/docs/ref/create.mdx | 44 +++------------------- site/src/content/docs/ref/deploy.mdx | 2 +- site/src/content/docs/ref/init-package.mdx | 2 +- site/src/content/docs/ref/packages.mdx | 12 +++--- 4 files changed, 14 insertions(+), 46 deletions(-) diff --git a/site/src/content/docs/ref/create.mdx b/site/src/content/docs/ref/create.mdx index 422a887035..8ce19e4e95 100644 --- a/site/src/content/docs/ref/create.mdx +++ b/site/src/content/docs/ref/create.mdx @@ -27,7 +27,7 @@ graph TD A11 -->|Yes| A12(add seed image)-->A13 A11 -->|No| A13 - subgraph + subgraph "" A13(add each component)-->A13 A13 --> A14(run each '.actions.onCreate.before'):::action-->A14 A14 --> A15(load '.charts')-->A16 @@ -61,44 +61,10 @@ graph TD `}/> -## Types of Zarf Packages -There are two types of Zarf Packages, the `ZarfInitConfig` and the `ZarfPackageConfig`, which are distinguished by the `kind:` field and specified in the `zarf.yaml` file. +## Package Templates -Throughout the rest of the documentation, we will refer to the `ZarfInitConfig` as an `init config` package or `init` package, and to the `ZarfPackageConfig` as simply a "package". - -### 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](/ref/init-package/). - -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. - -:::note - -To clarify, in most cases, the first Zarf Package you deploy onto a cluster should be the init package since other packages often depend on the services it installs onto your cluster. However, if you don't want to use the K3s distribution included in the init package or if you already have a preferred K8s distribution, you can deploy the distribution package first, followed by the init package, and then any other packages you want. This only applies if you don't have a K8s cluster yet. - -::: - -During the initialization process, Zarf will seed your cluster with a container registry to store images that other packages may require. Additionally, the init package has the option to deploy other features to your cluster, such as a Git server to manage your repositories or a PLG logging stack that allows you to monitor the applications running on your cluster. - -#### Using the init-package - -To initialize your cluster, you need to run the command `zarf init`. This command will search for a file with the specific naming convention: `zarf-init-{ARCHITECTURE}-{VERSION}.tar.zst`. The architecture must match that of the cluster you are deploying to. If you are deploying to a cluster with a different architecture, you will need to specify the name of the architecture you are deploying on with the `-a` flag. For example, if you are on an arm64 machine but are deploying on an amd64 machine, you will run `zarf init -a amd64`. - -Init packages can also be run with `zarf package deploy zarf-init-{ARCHITECTURE}-{VERSION}.tar.zst`. - -You do not need to create init configs by yourself unless you want to customize how your cluster is installed/configured. For example, if you want to use the init process to install a specifically configured K3s cluster onto your host machine, you can create a specific package to do that before running the init package. - -### ZarfPackageConfig - -`ZarfPackageConfig` refers to any package that is not an init package and is used to define specific capabilities that you want to deploy onto your initialized cluster. - -To deploy a Zarf Package, you can use the command `zarf package deploy`. This will prompt you to select from all of the files in your current directory that match the name `zarf-package-*.tar.zst`. Alternatively, if you already know which package you want to deploy, you can simply use the command `zarf package deploy {PACKAGE_NAME}`. - -During the deployment process, Zarf will leverage the infrastructure created during the 'init' process (such as the Docker registry and Git server) to push all the necessary images and repositories required for the package to operate. - - -### Package Templates +Package configuration templates can be used during `zarf package create` to configure the `zarf.yaml` file. Templates are baked into the Zarf package so they cannot be changed post create. :::caution @@ -106,8 +72,9 @@ During the deployment process, Zarf will leverage the infrastructure created dur ::: -You can also specify `zarf.yaml` package configuration templates at package create time by including `###_ZARF_PKG_TMPL_*###` as the value for any string-type data in your package definition. These values are discovered during `zarf package create` and will always be prompted for if not using `--confirm` or `--set`. An example of this is below: +You can specify `zarf.yaml` templates at package create time by including `###_ZARF_PKG_TMPL_*###` as the value for any string-type data in your package definition. Template values can be defined using [config files](/ref/config-files/) or the `--set` flag. If a template is undefined during `zarf package create` if will always be prompted for unless `--confirm` is used. +An example of templates is below: ```yaml kind: ZarfPackageConfig metadata: @@ -138,4 +105,3 @@ You can only template string values in this way as non-string values will not ma Additionally, you cannot template the component import path using package configuration templates ::: - diff --git a/site/src/content/docs/ref/deploy.mdx b/site/src/content/docs/ref/deploy.mdx index 2a19268c4c..f6b144c9bd 100644 --- a/site/src/content/docs/ref/deploy.mdx +++ b/site/src/content/docs/ref/deploy.mdx @@ -50,7 +50,7 @@ graph TD B12(prompt to confirm components)-->B13 B13(prompt to choose components in '.group')-->B14 - subgraph + subgraph "" B14(deploy each component)-->B14 B14 --> B15(run each '.actions.onDeploy.before'):::action-->B15 B15 --> B16(copy '.files')-->B17 diff --git a/site/src/content/docs/ref/init-package.mdx b/site/src/content/docs/ref/init-package.mdx index 11e07ca97c..660e04e290 100644 --- a/site/src/content/docs/ref/init-package.mdx +++ b/site/src/content/docs/ref/init-package.mdx @@ -153,7 +153,7 @@ graph TD B12(prompt to confirm components)-->B13 B13(prompt to choose components in '.group')-->B14 - subgraph + subgraph "" B52 --> |Yes|B14(deploy each component)-->B14 B14 --> B15{Component is \n zarf-seed-registry} B15 --> |Yes|B51(initialize zarf-state secret):::action diff --git a/site/src/content/docs/ref/packages.mdx b/site/src/content/docs/ref/packages.mdx index 913e125f3a..4cb1e4434c 100644 --- a/site/src/content/docs/ref/packages.mdx +++ b/site/src/content/docs/ref/packages.mdx @@ -20,17 +20,19 @@ 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](/ref/init-package/). +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. -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. +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. To install a K8s distribution other than K3s, finding or creating a custom Zarf Package is necessary. -:::note +Typically, an init package is the first Zarf Package to be deployed on a cluster as other packages often rely on the services it installs or configures, however Zarf may be used to package and install the cluster distribution itself. In this scenario, the distribution package would be deployed first, followed by the init package, and then any other packages planned for deployment. + +:::tip -To clarify, in most cases, the first Zarf Package you deploy onto a cluster should be the init package since other packages often depend on the services it installs onto your cluster. However, if you don't want to use the K3s distribution included in the init package or if you already have a preferred K8s distribution, you can deploy the distribution package first, followed by the init package, and then any other packages you want. This only applies if you don't have a K8s cluster yet. +Check out our [K3s cluster package](https://github.com/defenseunicorns/zarf/blob/main/packages/distros/k3s/zarf.yaml) to see an example of a Zarf Package that installs a Kubernetes distribution ::: -During the initialization process, Zarf will seed your cluster with a container registry to store images that other packages may require. Additionally, the init package has the option to deploy other features to your cluster, such as a Git server to manage your repositories or a PLG logging stack that allows you to monitor the applications running on your cluster. +During the initialization process, Zarf will seed the cluster with a container registry to store images that other packages may require. The init package has the option to deploy other features to your cluster, such as a Git server to manage your repositories or a PLG logging stack that allows you to monitor the applications running on your cluster. For additional information on the init package, we provide detailed documentation on the Zarf ['init' package page](/ref/init-package/). #### Using the init-package