Documentation: How to install Stackable without an Internet connection

[dervoeti]

@fhennig I inivited you to my private Github repo with the documentation for this (https://github.com/dervoeti/stackable-airgap). The documentation itself is just the README.md. For this issue, only the first half (until Sigstore / Image signature verification) is relevant. I wrote the documentation in a "tutorial style", I did not check wording / grammar yet, not sure if we want to publish parts of this and if so, how we want to publish it (docs, blog post, both?). At least the second part on how to verify image signatures most likely needs to be public documentation at some point (not part of this issue though, there's another issue for that: https://github.com/stackabletech/issues/issues/437). I'd say, as a first step, try to follow along using the documentation and see if it makes sense. We can then refine the documentation together and check where to publish it.

[dervoeti]

This is how my test setups looked like in the IONOS DCD

[fhennig]

Ok great! I had a look at your repo, looks good! You mention a few times that it is more a "proof of concept", but this is really good to have.

I see two ways forward here:

1. keep working on this and turn it into a tutorial (wouldn't be completly air-gapped but with a bastion host still)
2. leave it for now. We have this document to come back to it later

I'm leaning towards 2., because it's not urgent to document this now I think, and I think there's too much work left to do to clean up the tutorial

[dervoeti]

Alright, we need some more discussion here on how and what exactly to publish. None of this is secret, but we want to make sure it's actually helpful to customers before we publish anything. The current state of the documentation is moved into this repository for now: https://github.com/stackabletech/documentation-airgapped-setup

But I think we can't give much more than a proof of concept here since how exactly to deploy this pretty much depends on the setup of the customer (which OS is running on the nodes, how can we get data into the cluster, is an image registry already in place, ...).

[lfrancke]

Thank you! I'll read the docs and will make suggestions.

In my past "life" I was referring to the "offline docs" quite frequently. They mostly consisted of lists of packages to mirror which was already useful.

[fhennig]

Alright, could you maybe elaborate more? I'd be happy to refine this ticket a little bit more. If we could have an MVP docs page which is mostly links to repos etc for more "expert" users to mirror, maybe that could already be helpful. We can then expand on this in the future. @dervoeti what do you think, could we make such a simple list of stuff to mirror and then thats already good enough for people that know what they're doing?

[dervoeti]

I think the basic steps are simple: Since the list of images to mirror depends on what exactly customers install on their cluster, we can't really provide one. So if in doubt I would probably advise to replicate all our images and charts (or to setup a proxy to our registry, as done in the tutorial, if that's possible). How they do this depends on their environment. Maybe we can provide examples for a few common scenarios. Or maybe that's not really needed, not sure. The documentation I wrote is basically about what I did to setup an air-gapped environment. So, in its current form, I think of it more as internal documentation for us to reproduce those kind of environments. The question is what we can extract from it that could be useful for customers, I'm not sure about this, since I don't really know how the usual requirements / questions from customers about this look like. The other thing we can extract from it is how customers can verify signatures in an air-gapped environment, I'm currently working on adding this to our docs (https://github.com/stackabletech/issues/issues/437). And maybe we can generate some marketing material (blog posts, demos, talks) from this, since this is not something most people usually work with and I could not find too much good documentation about air-gapped Kubernetes setups in general.

[fhennig]

Ok so I suspect if we document these things:

• this is the image repo, this is the Chart repo, mirror it all (or what you need)
• configure your images to be pulled from your local repo: https://docs.stackable.tech/home/nightly/concepts/product-image-selection#_custom_docker_registry
• use your local repo with Helm

Then maybe that's already enough? That would skip over the details of how to mirror things exactly etc, but maybe people might know that already if they're running an airgapped cluster

[dervoeti]

Sounds good to me :slightly_smiling_face: At least as a first step. We could add more details / hints if customers ask about other specific things. But I would also assume that most customers already know most of the details if they run an air-gapped cluster.

[dervoeti]

@lfrancke @fhennig First version is ready for review now: https://deploy-preview-530--stackable-docs.netlify.app/home/nightly/tutorials/running_stackable_in_an_airgapped_environment

I tried to explain some ways how the setup could be done. oci.stackable.tech (Harbor) is used in the examples, I could change it to docker.stackable.tech since our migation to Harbor will most likely take some more time.