I think a lot of other commentors here are more taking issue with the concept of ZTNs in general and may not have used them at scale, or at all. The intro is buzzword heavy, however I don't think that's an issue with your documentation, just the terminology of the space Octelium operates in which came from big business and was conceived as buzzwords to start with so there's not a lot of flexibility to use alternate terms that make sense.
Your documentation is extremely detailed and generally excellent. It does seem to be targeted at people who have already deployed Octelium or are very familiar with ZTN-style deployments. It's quite fractally dense (you stumble over one new term, need to go to another docs page, which is as long, that has more terms you need to read about, etc.) so as you've mentioned the issue really isn't your product but likely conveying what it does in a clear manner.
If you want to get general devs and homelabbers on board with the concept or testing this out, which I imagine is a very different target to your initial versions, maybe you could prefix your GitHub readme with something like:
"Octelium is a free and open source zero trust network platform. It integrates and manages your Kubernetes (and other container orchestration) applications to provide single point of authentication for all services. Your users log in once to one authentication provider such as a managed provider like Okta or any other OAuth OpenID compatible service and then your users are automatically granted their correct access levels to all your web services, databases, SSH, VPNs and more. Log in once, access everything, self-hosted."
When reading your documentation I immediately had a number of questions that were not clearly answered. That doesn't mean to say the answer isn't in your documentation, it's just that after 15-20 minutes of reading I still didn't have a clear answer. I'm reading this from the perspective of someone very familiar with operating Kubernetes clusters at scale and dabbled quite a bit with some of the commercial ZTN offerings. Apologies if the questions below are answered in your docs, I didn't find them in the time I had.
1) Your initial setup guides go from how to install Octelium to immediately scheduling services via YAML as a direct replacement for, I assume, something like deployments on k8s. Does Octelium actually run workloads? Is it 1:1 compatible with k8s API spec? Does it just talk to k8s over the API and effectively rewrite deployment YAML and spam it to k8s? Immediately this has concerns, why do I want this? Do I trust Octelium to manage deployments for me? Replacing a vast part of the k8s stack with Octelium tooling is a big ask for even small companies to trial. There's also just straight upstream connections, why would I want to let Octelium manage workloads over just using an internal k8s service hostname so I don't have to effectively rebuild the entire application around Octelium? Does letting Octelium manage workloads impact anything else (monitoring, logging, any other deployment tools that interact with k8s - if some CI/CD pipeline updates a container image does Octelium "know" or is it out of date?). What about RBAC stuff? Namespaces? Are these 1:1 k8s compatible?
2) If I work for BigCorp I'm going to have things like compliance issues coming out of my ears, your Services store credentials in plain text which is going to be flagged immediately. No-one is going to offload SSH authentication if root SSH keys are stored in plain text in secrets somewhere. I did note there's the option to effectively write your own gRPC interfaces to handle secure secrets storage but this seems like a pretty big hurdle. You then basically say "if you're enterprise we can help here" at the bottom, but I wouldn't even test this myself on a homelab without some sort of more sane basic secret management.
3) How, specifically, does Octelium handle HTTP upstream service issues? For example, if I'm proxying my companies connections to saas.com via saas.myintranet.example.com I assume I lose the ability to apply 2fa to user accounts? It's unclear from the documentation, can I specify unique credentials per user? How would I manage those? Is the only option OAuth and scopes? What if the upstream doesn't support OAuth? It's fine if upstream services need to support OAuth to support the most seamless and secure ZTN-style experience, it's just not that clear how these things work in practice.
4) You re-use a lot of terms from k8s (cluster, service etc.) which are subtly different k8s, this could cause confusion with a lot of k8s trained admins. For example, I believe an Octelium cluster is a k8s cluster running multiple Octelium instances and a custom data plane, this different enough to what a k8s cluster is to potentially be confusing as it's a different logic level. I appreciate there are limited generic descriptive terms in the dictionary to describe these things.
5) How, technically, does some of this stuff work? I know I can browse the repo or read the extensive documentation, but it would be helpful to have some clear "k8s admin"-targeted terms like, we install X proxy that does Y, using Z certificates, services managed by Octelium get a sidecar that intercepts connections to proxy them back into the ZTN, or whatever magic it does in clear, k8s, terms. If I'm looking after something like this I would need to know it inside-out, what if some certificate stops working? If I don't know exactly where everything is how can I debug it? If I deployed this it would be absolutely mission-critical, if it breaks the entire company immediately breaks. If that happens for a couple of days, realistically it can be business-terminating.
What would be really helpful to see would be some documentation with step by step guides on going from a starting point to what an Octelium-powered endgame would look like. For example, if I'm the CTO of a business that has some remote managed k8s clusters running our public SaaS along with some tooling/control panels/etc, and then a big server in my office running some non-critical but important apps via Podman, and 15 remote users that currently connect over a Tailscale VPN into the office, and 20+ upstream external web services that provide support ticketing, email, etc. then what does this look like after I "switch" to Octelium? Before and after comprehensive diagrams, and maybe even a little before-video of someone logging in via a VPN then logging into 15 control panels vs an after-video with someone logging into an intranet and just everything magically appearing would be nice. You need to sell something of this scale to CTOs, not engineers.
Generally, however, my personal biggest flag with this would be that it requires effectively a total rebuild of all infrastructure, learning entirely new tooling, management and oversight. It's a lot to ask and it doesn't seem like it can be that gradually rolled out. I suppose you could set up a second k8s cluster, deploy Octelium on it and then slowly migrate services over, but that's going to be expensive.
Some suggestions:
1) You have built a very impressive toolkit, why not operate this as a SaaS using your toolkit (with on-prem open source extensions)? You don't seem to have an actual product, you have a swiss army knife of ZTN tools which is way more work so hats off to you there. It seems you're partitioning this with "the toolkit is public, write your own glue for free, to get a working platform, come pay us" which is perfectly fine, the issue there is your "enterprise" offerings seem to be even more toolkit options rather than an actual offering. Bundle in some actual enterprise tools (fancy log tool with a web UI that also does user management and connection monitoring as a single dashboard?) and it would be a lot more appealing.
2) You require replacing industry standard technologies like directly managing k8s with kubectl with your own platform and tools - replacing "the way that everyone does X" with "new tool from relatively unknown ZTN provider" is going to be tough to sell. Can you make your octeliumctl tool a kubectl plugin? Could Octelium be less control-everything and just sit on top k8s rather than seemingly replace a lot of it?
Edit: 3) Have a homelabber edition, if that's a market you want to target, that's way easier to install and works in a single docker container or something (sacrificing some of the redundancy) but offers a basic complete suite of services (dashboard, HTTP upstream proxying, VPN) with a single "docker run...".
Good luck with Octelium, it's certainly interesting and I'll keep an eye on it as it evolves.
333
144