add initial faq for tutorial

zarf-faq.md

@@ -0,0 +1,198 @@
+# Zarf FAQ
+
+## Basics & Concepts
+
+**What exactly is a Zarf package and how is it different from a Helm chart?**
+
+A Zarf package is a self-contained, compressed archive (`.tar.zst`) that bundles everything your application needs to run — container images, Kubernetes manifests, Helm charts, scripts, and binaries. A Helm chart is a templating mechanism for Kubernetes manifests that still requires a live internet connection to pull images and dependencies at deploy time. Zarf wraps around Helm if needed, making the whole thing portable and deployable without any internet connection.
+
+Here are the different component types you can define in a Zarf package:
+
+### Manifests
+
+Raw Kubernetes YAML files included directly in a component.
+
+```yaml
+components:
+  - name: my-app
+    manifests:
+      - name: app-manifests
+        files:
+          - manifests/deployment.yaml
+          - manifests/service.yaml
+```
+
+### Helm Charts
+
+You can include Helm charts inside a Zarf component — either from a local path or from a remote Helm repository. Zarf pulls and bundles the chart at build time, so no Helm repo access is needed at deploy time.
+
+```yaml
+components:
+  - name: my-helm-app
+    charts:
+      - name: my-chart
+        url: https://charts.example.com
+        version: 1.2.3
+        namespace: my-namespace
+```
+
+> Zarf wraps around Helm — your existing charts work as-is, now bundled and portable.
+
+### Images
+
+Container images that your application needs. Zarf pulls these at build time and embeds them in the package. At deploy time they are pushed into Zarf's internal registry inside the cluster.
+
+```yaml
+components:
+  - name: my-app-images
+    images:
+      - nginx:1.25
+      - my-registry.io/my-app:v2.1.0
+```
+
+> This is the mechanism behind airgapped deployments — no internet needed at deploy time because the images are already inside the package.
+
+### Repos
+
+Git repositories can be bundled inside a Zarf package. Zarf will mirror the repo and push it into an internal Gitea instance inside the cluster. This is useful for GitOps workflows where your cluster needs access to source code or manifests.
+
+```yaml
+components:
+  - name: my-gitops-repo
+    repos:
+      - https://github.com/my-org/my-repo.git
+```
+
+> Ideal for teams using Flux or ArgoCD in airgapped environments — your GitOps source of truth travels with the package.
+
+### Files
+
+Any arbitrary file you want to include — scripts, configuration files, binaries, certificates. Zarf can place these files on the system at deploy time, with specific permissions if needed.
+
+```yaml
+components:
+  - name: config-files
+    files:
+      - source: configs/app-config.yaml
+        target: /etc/myapp/config.yaml
+        executable: false
+```
+
+### Actions
+
+Actions let you run scripts or commands before or after deployment steps. Useful for pre-flight checks, post-deploy configuration, or cleanup tasks.
+
+```yaml
+components:
+  - name: my-app
+    actions:
+      onDeploy:
+        before:
+          - cmd: echo "Starting deployment..."
+        after:
+          - cmd: kubectl rollout status deployment/my-app
+```
+
+---
+
+**Why would I use Zarf instead of just using `kubectl apply`?**
+
+`kubectl apply` just applies manifests — it assumes all your images are already reachable and everything is in place. Zarf handles the entire delivery pipeline: bundling, signing, transporting, and deploying. In airgapped or high-security environments, `kubectl apply` alone is simply not sufficient.
+
+---
+
+**Does Zarf replace Docker Compose or Helm, or does it work alongside them?**
+
+It works alongside them. Zarf is not a replacement for Helm or Compose — it's the outer layer that packages and delivers your existing tooling. You can include a Helm chart inside a Zarf package. Zarf operates at the delivery and distribution layer, not the application definition layer.
+
+---
+
+## Airgapped & Disconnected Environments
+
+**How does Zarf handle image pulls in a completely airgapped environment?**
+
+Zarf includes a built-in internal container registry that it spins up inside the cluster. When you create a Zarf package, all required container images are pulled and embedded directly into the package archive. At deploy time, Zarf pushes those images from the archive into its internal registry, so Kubernetes can pull them locally — no internet needed.
+
+---
+
+**What happens if the target environment has no internet access at all during deployment?**
+
+That's exactly the scenario Zarf is designed for. As long as the package was built correctly on a connected machine beforehand, the deployment on the airgapped side is fully self-sufficient. Nothing reaches out to the internet during deployment.
+
+---
+
+**How do you get the Zarf package onto the airgapped machine in the first place?**
+
+This is the "sneakernet" step — you move it physically or through whatever secure transfer mechanism your environment allows. In practice this means a USB drive, an SFTP transfer through a one-way data diode, or a secure file transfer to a bastion host. In many regulated or secure environments, this is already a well-defined process governed by security policy.
+
+---
+
+## Security & Signing
+
+**How does signing and verification work in Zarf?**
+
+Zarf uses Cosign under the hood. When you build a package, you can sign it with a private key. When someone deploys that package, Zarf verifies the signature against the corresponding public key before anything is deployed. If the signature doesn't match, deployment is blocked.
+
+---
+
+**What happens if a package fails signature verification — does deployment stop?**
+
+Yes. Zarf will refuse to deploy a package that fails verification. This is a hard stop, not a warning — a critical feature in regulated environments where you need to guarantee that what you're deploying is exactly what was approved and signed off.
+
+---
+
+**How does Zarf relate to SBOMs and software provenance?**
+
+Zarf automatically generates an SBOM (Software Bill of Materials) when you build a package. This gives you a full inventory of everything inside — every image, every layer, every component. This is invaluable for compliance, vulnerability scanning, and audit trails in any environment where you need to prove exactly what software is running on which system.
+
+---
+
+## Practical & Operational
+
+**How big can a Zarf package get, and is there a size limit?**
+
+There's no hard limit imposed by Zarf itself — packages can technically be gigabytes in size since they include all container images. In practice, size is constrained by your storage and transfer method. For large packages you can use Zarf's `--max-package-size` flag to split packages into chunks for easier transport.
+
+---
+
+**Can I update a deployed Zarf package, or do I have to redeploy from scratch?**
+
+You can redeploy a newer version of the package and Zarf will handle the update. It's not a full teardown — Zarf is smart enough to update existing components. That said, for stateful applications you still need to think carefully about data migrations and rollback strategies, just as you would with any Kubernetes deployment.
+
+---
+
+**How do I handle secrets and sensitive configuration inside a package?**
+
+Zarf has a concept called Zarf variables — these allow you to inject values at deploy time rather than baking secrets into the package itself. Your package can be fully portable and shareable, while sensitive values like passwords or tokens are only provided at the moment of deployment, by the operator on the target system.
+
+---
+
+**Can Zarf packages be used in a CI/CD pipeline?**
+
+Absolutely. Zarf has a CLI that is fully scriptable, making it easy to integrate into pipelines like GitHub Actions, GitLab CI, or Jenkins. A typical pipeline would build and sign the package on a connected build agent, store it in an artifact registry, and then a separate job — or a human — transports and deploys it to the target environment.
+
+---
+
+## Infrastructure & Compatibility
+
+**Does Zarf work with any Kubernetes distribution, like OpenShift or K3s?**
+
+Yes, Zarf is distribution-agnostic. It works with K3s, RKE2, OpenShift, EKS, GKE, AKS, and others. Zarf even comes with a built-in K3s option (`zarf init` can spin up a lightweight cluster for you), which is useful for edge or resource-constrained environments.
+
+---
+
+**Can I deploy to multiple clusters with the same package?**
+
+Yes, and that's one of Zarf's key strengths. The same `.tar.zst` package can be deployed to development, staging, and production — or across multiple sites — with full confidence that the content is identical. Variables and configuration can differ per environment, but the package itself is the same verified artifact.
+
+---
+
+**How does Zarf handle version conflicts between environments?**
+
+Zarf packages are versioned and self-contained, so the risk of version conflicts is significantly reduced compared to traditional deployment methods. Since all dependencies are bundled, you're not relying on whatever version happens to be available in a remote registry at deploy time. What you built is what gets deployed — deterministically.
+
+---
+
+**What are components in Zarf and why do they matter?**
+
+A Zarf package is built from one or more components. Think of components as the building blocks of your package — each component groups a specific type of resource together. When you deploy a package, you can choose which components to include, making packages flexible and reusable across different scenarios.