docs: what is zarf? #172
docs: what is zarf? #172
Conversation
|
haven't got to go through all this yet, but it's really good so far |
|
All right, @YrrepNoj. Can you give it another look when you get a chance, plz? In particular, these sections:
Do you think they make it any clearer to a new Zarfer that, 1) the project operates in 2 parts, and 2) that one of them is long-running (the Zarf cluster) while the other isn't (the binary)..? |
|
I'd like to nail down these definitions a little better and then be consistent across the entire project (there are plenty of places in the codebase that aren't consistent right now). |
I'm game. For now I've resolved all the open comments with the substitutions recommended in them. I think it's made this file self-consistent, at least. Do we want to wait on normalizing terminology in all the docs before accepting this PR? Or is this good enough to get into master so that external peeps can start finding it? |
|
|
||
| #### (2) - Package | ||
|
|
||
| Actually making a Zarf package out of a `zarf.yaml` file is a matter of calling a single, simple command: `zarf package`. You'll see a `zarf-package-*.tar.zst` file pop into existence afterward—that's your package. |
There was a problem hiding this comment.
technically this is zarf package create to see the menu or you can just do zarf zarf.yaml to skip the menu
There was a problem hiding this comment.
Wait, but this para here is about making the package rather than deploying it, right? So I guess the command should be zarf package create.
So you can run it both ways, right? Either directly with zarf package create or with zarf zarf.yaml will both build the package?
I kinda prefer the one with package in it cuz that makes the CLI API a bit more explicit, which seems fitting for a "first touch"-ish file like this.
You think it'd read more clearly with just zarf zarf.yaml though?
There was a problem hiding this comment.
yeah updated me comment. I agree zarf package create is better introduction, power users will like move to zarf zarf.yaml
|
|
||
| Recommended Zarf components: `management`. | ||
|
|
||
| Deploy your package into the Zarf cluster with the command: `zarf deploy`. |
There was a problem hiding this comment.
same here it's actually zarf *zarffilename* or zarf package deploy to get the menu
There was a problem hiding this comment.
Definitely forgot the "package" part in there; good catch. Should read zarf package deploy for sure.
|
|
||
| - Make it easy to support GitOps-based k8s cluster updates in isolated environments. | ||
|
|
||
| - Make it possible to support GitOps-based k8s cluster updates in internet-connected-but-independent environments (think: dependency caching per availability zone, etc). |
There was a problem hiding this comment.
I'd add comments about saving bandwidth / increase fault tolerance / etc here.
|
|
||
| - container images — to serve images for the Zarf & downstream clusters to run containers from. | ||
|
|
||
| - git repositories — to serve as the git-based "source of truth" for downstream "GitOps"ed k8s clusters to watch. |
There was a problem hiding this comment.
now also any generic git repos needed from the online to offline side since the last big git PR merge. Think "I'd love to have the docs for this cool tool in my airgap, can zarf bring those from github to here for me?"
| - git 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 & support the Zarf cluster. | ||
|
|
There was a problem hiding this comment.
Not just pre-compiled binaries, that's a particular file type zarf is aware of, but could also be infra code, ie. terraform modules, scripts, config files, etc. Also big one that was left off is the data injection one
There was a problem hiding this comment.
Mmm... lemme make sure I'm clear on this one:
You're suggesting we add another "type of software" line in here to cover stuff that, 1) gets installed on the Zarf cluster machine, but 2) is not a binary? Stuff for Zarf to use to bootstrap other stuff?
There was a problem hiding this comment.
Also, where would the "data injection" part fit? I sort of imagined that was covered by the container images line item but you're thinking it should be it's own thing?
There was a problem hiding this comment.
Oh, unless you're thinking that we should call out that you can use Zarf to package stuff that has nothing to do with the Zarf cluster at all. So, like, to add an additional block that talks about if you just want to use the packaging facilities to seed your own non-Zarf-cluster stuff (i.e. TF modules for your own infra, etc.).
There was a problem hiding this comment.
Overall this is an absolutely fantastic document. I would like to try and settle a definition for the "zarf cluster" "utility cluster" "gitops service" "appliance mode" "standard mode" as they are all partially overlapping ideas/terms I think we can really get settled now. I'll open a new issue for that.
|
Okay created the other issue with comments: #174 |
|
/test all |
|
/test all |
Signed-off-by: Jeff McCoy <code@jeffm.us>
Signed-off-by: Jeff McCoy <code@jeffm.us>
Added a new file: docs/what-is-zarf.md.
Makes an attempt to:
distill all the "What does Zarf really do?" conversations I've been having (with new devs & outside users) into something we can have others read,
visualize Zarf in a software delivery context to show just how it helps move "software across the air gap",
give us an artifact to talk to & update as we have discussions about what is/isn't, should/shouldn't be in-scope for the project.
Some of this will need expansion / fix-up but I thought it was in a good enough shape to fill some documentation holes we've had for a while.
Happy to have further conversations about what should / shouldn't be here, if we want to chunk some of this out into separate pages, etc.